Introduction
This training is for the embedded systems developer who wishes to use the MPLAB® Harmony 3 Software Framework for the Microchip Technology’s ATSAMA5D2 Series Microprocessor Unit (MPU).
For more information about MPLAB Harmony 3 Software Framework, see the "Introduction to MPLAB Harmony 3 Software Framework for Microchip Technology 32-bit Microprocessor Units (MPUs)" page.
Time System Service
In this training topic, you will learn how to open, configure, build, and debug the Time System Service Core Application example project using the MPLAB X Integrated Development Environment (IDE). This example project uses the TC0 timer to blink the RGB LED (D5) blue and print debug messages on the Console Serial port.
In this training, we show you how to debug the project. There are two methods for running the application examples:
- Debugging – In this training, we show you how to debug the project using MPLAB X IDE.
- Production – In production, the application is booted from an external Non-Volatile Memory (NVM). Instructions on GitHub pages show you how to open, configure, build, load to SD memory card, and run the example project.
Core Package
The Core Package (core) contains Device Driver, System Services, Operating System Abstraction Libraries (OSAL), and third-party libraries. Device drivers and System Services provide advanced capabilities such as buffer queuing and peripheral resource sharing.
Core Applications Package
The Core Applications Package (core_apps_sam_a5d2) contains example applications demonstrating the control of peripherals using device drivers and system services managing shared resources. A listing of Core Application example projects for the SAMA5D2 Series is available on GitHub pages.
Subjects covered in this topic:
Prerequisites
Installing MPLAB XC32 Compiler
Introduction to MPLAB Harmony 3 Software Framework
Install the MPLAB Harmony 3 Launcher Plugin
Install the MPLAB Harmony 3 Software Framework
Hardware
ATSAMA5D27-SOM1-EK1 Evaluation Kit
For this training topic, you will be using the ATSAMA5D27-SOM1-EK1 Evaluation Kit.
Setup
You will need one USB Micro-B cable. It will connect the Host PC to USB port (J10) to communicate with the J-Link On-Board + CDC (see Figure 3) and power the ATSAMA5D27-SOM1-EK1.
Debug Communications
You will be using the J-Link On-Board Debug Probe that is located on the ATSAMA5D27-SOM1-EK1 Evaluation Kit. Debug communications between the Host PC and the ATSAMA5D27-SOM1-EK1 are through USB port J10 (J-Link-OB). Note that this is the same USB port used for Console Serial communications. The MPLAB X IDE will control the ATSAMA5D27-SOM1-EK1 (upload binaries, debug) through the JTAG port. The MPLAB Harmony 3 project must be configured to enable debug communications (see Configure MPLAB X IDE Project below).
For more information, see the "MPU Debug Probes" page.
Console Serial Communications
Console Serial communications between the Host PC and the ATSAMA5D27-SOM1-EK1 are through USB port J10 (J-Link-CDC). Note that this is the same USB port used for Debug Communications. A Terminal Emulation program running on the Host PC communicates with the SAMA5D27 UART port.
Ensure the Terminal Emulation program is configured to the COM port and settings are:
- Speed: 115200
- Data: 8
- Parity: None
- Stop Bits: 1
For more information, see: ATSAMA5D27-SOM1-EK1 - Console Serial Communications
Power
You can power the ATSAMA5D27-SOM1-EK1 Evaluation kit by connecting a USB Micro-B cable between the Host PC and USB port (J10). Alternately, you can power the ATSAMA5D27-SOM1-EK1 by connecting a USB Micro-B cable to USB-A Device port (J17).
A priority mechanism manages automatic power source switching between J10 and J17.
Create Working Directory
It is a good practice to create a working directory to place the source code in for a given project. In this way, you can make changes, experiment, and develop your project while maintaining an original copy of the MPLAB Harmony 3 Software Framework on your computer. Another benefit is you can archive the contents of your projects so that you may give them to other developers and/or for archival purposes.
Default Framework Path
When you downloaded MPLAB Harmony 3 Software Framework, you specified the directory on your host computer where you would like to place the packages (libraries). This is the Framework Path (as shown in Figure 4). On a Windows computer, the default location is C:\Users\<user>\Harmony 3.
You may use this location for running Core Application programs for demonstration purposes. However, if you plan to make any changes you may want to create a working directory.
Create a Working Directory
Creating a working directory can be done from the Harmony 3 Content Manager. The benefit of this method is you can download (clone) the Core Application of your choice to a working directory of your choice. The Harmony 3 Content Manager will also allow you to keep the Core Application up to date with any changes from the Harmony 3 Software Framework GitHub repository.
1
Start MPLAB X IDE.
3
Click on the Next button.
You do not need to change the Framework Path here. You will enter a project directory location later.
4
Click the Application Browser tab.
8
Create a Working Directory.
For this tutorial, we’ll name our project directory C:\Users\<user>\Harmony3_Core_Apps.
This completes creating a working directory for the Time System Service Application project.
Open Project
In this section, you will open the Time System Service Application project in MPLAB X IDE.
This training uses v3.2.0 of the core_apps_sam_a5d2 package.
1
Start MPLAB X IDE.
2
Click on File > Open Project…
The Open Project window will open.
4
Select sam_a5d27_som1_ek_freertos.X and click on the Open Project button.
This completes the opening (Open Project…) of the Time System Service Application project. You can observe sys_time_multiclient_sam_som1_ek_freertos is shown in the Projects pane (upper left) in MPLAB X IDE.
You will be using a pre-compiled version of at91bootstrap. The at91bootstrap project is available if you wish to make any modifications. However, building the at91bootstrap in MPLAB X IDE requires setting up the appropriate tools. Instructions are in the GitHub repository.
Configure MPLAB X IDE Project
In this section, you will configure the Time System Service Application project in MPLAB X IDE.
Ensure that the ATSAMA5D27-SOM1-EK1 is connected to the Host Computer following the instructions in the "Hardware" section above.
3
In the Categories pane (on the left), select Conf: (sam_a5d27_som1_ek_freertos).
a
In the Packs window, select the latest version of the SAMA5D2_DFP and CMSIS.
b
In the Compiler Toolchain window, select the latest version of the XC32 compiler.
c
Click on the Connected Hardware Tool drop-down box and select J-Link-SN: nnnnnnnnn
Where nnnnnnnnn is the serial number of the J-Link-OB Debug Probe on the ATSAMA5D27-SOM1-EK1.
The J-Link Debug Probe will not be visible in the drop-down box unless the SAM9X60-EK Evaluation Kit is connected per the Hardware Setup (above) and powered on.
4
In the Categories pane (on left), select Conf: (sam_a5d27_som1_ek_freertos) > Bootstrap.
a
Observe that the Use bootstrap box is checked.
b
Observe that the following path is displayed in the Bootstrap file box:
${ProjectDir}\..\at91bootstrap_sam_a5d27_som1_ek_freertos.X\binaries\at91bootstrap.elf
We are choosing the at91bootstrap.elf because it contains the load and start addresses. If you were to use the at91bootstrap.bin, you would have to specify its load and start address.
You will be using a pre-compiled version of at91bootstrap. The at91bootstrap project is available if you wish to make any modifications. However, to build the at91bootstrap in MPLAB X IDE requires setting up the appropriate tools. Instructions are in the GitHub repository.
6
Finally, click on the OK button to close the Project Properties window.
You have established debug communications via the ATSAMA5D27-SOM1-EK1 JTAG port and MPLAB X IDE.
This completes the configuration of the Time System Service Application project. You can review the Project Properties settings in the Dashboard pane:
Build the Project
In this section, you will build the Time System Service Application project in MPLAB X IDE.
1
Ensure the ATSAMA5D27-SOM1-EK1 Evaluation Kit is connected to the Host PC per the instructions in the hardware Setup section above.
LEDs on the ATSAMA5D27-SOM1-EK1 will indicate:
- D4 Green – J-Link-OB+CDC is operational
- RGB D5 Red – no program is running
3
In the Projects pane (upper left), select and highlight the sys_time_multiclient_sam_a5d27_som1_ek_freertos project.
The icons in the toolbar will act on the selected project.
4
Clean and Build the sys_time_multiclient_sam_a5d27_som1_ek_freertos project by either:
- Click on the Clean and Build Project icon in the Toolbar, or
- Right click on sys_time_multiclient_sam_a5d27_som1_ek_freertos in the Projects pane and select Clean and Build.
Observe CLEAN SUCCESSFUL and BUILD SUCCESSFUL in the Output pane (bottom).
This completes the building of the Time System Service Application project.
Debug the Project
In this section, you will set up the Time System Service Application project for debugging on MPLAB X IDE.
In this training, we show you how to debug the project. There are two methods for running the application examples:
- Debugging – In this training, we show you how to debug the project using MPLAB X IDE.
- Production – In production, the application is booted from an external NVM. Instructions on GitHub pages show you how to open, configure, build, load to SD Memory Card, and run the example project.
1
Open main.c by, in the Projects pane, under sys_time_multiclient_sam_a5d27_som1_ek_freertos, clicking on the plus sign (+) next to Source Files to expand the list of source files and double-clicking on main.c
Observe that main.c opens in the main display pane.
2
Scroll down to int main ( void ) (line 60).
3
Set a breakpoint on the line with SYS_Initialize ( NULL ): (line 63) by right-clicking and selecting Toggle Line Breakpoint.
Observe the line is highlighted red and the breakpoint symbol (red square) is displayed in place of the line number.
4
Debug the project by either:
- Click on the Debug Project icon on the Toolbar, or
- Right-click on sys_time_multiclient_sam_a5d27_som1_ek_freertos in the Projects pane and select Debug.
a
Observe in the Output pane, project tab, that BUILD SUCCESSFUL is displayed.
b
Observe in the Output pane, J-Link-sam_a5d27_som1_ek_freertos, displays programming and verification complete, running, and target halted.
c
Observe in main.c that the program halted on SYS_Initialize ( NULL ): (line 63) – highlighted in green.
At this point, the application has been initialized and halted.
The at91bootstrap initialized the main oscillator, external volatile memory (DRAM), and configured peripherals. MPLAB X IDE loaded the application binary to DRAM via the JTAG port.
For more information see:
d
Observe RGB LED D5 is green, indicating a program has been loaded on the SAMA5D27.
5
To continue, click on the Continue icon on the Toolbar.
The application program runs.
The application program runs without breaking as the SYS_Initialize ( NULL ): (line 63) function is only called once.
a
Observe the RGB LED D5 blinks blue.
Congratulations! You have opened, configured, built, and debugged a Core Applications example program for MPLAB Harmony 3 Software Framework in MPLAB X IDE.
You can now pause, insert other breakpoints, and continue running the project.
If you change the source code, don’t forget to (re)build the project.
If you Stop a debug session you must press the nRST (Reset) button SW3 on the ATSAMA5D27-SOM1-EK1 Evaluation Kit to initiate the boot process before launching another debug session.
Summary
In this training, you learned how to open, configure, build, and debug the Time System Service Core Application example project using MPLAB X IDE. This example project used the TC0 timer to blink the RGB LED (D5) blue and print debug messages on the Console Serial port.
What’s Next?
There are many more application examples that you can explore.
Core Application Examples
The Core Applications Package (core_apps_sam_a5d2) contains several example applications that demonstrate the control of peripherals using device drivers and system services managing shared resources. A listing of Core Application example projects for the SAMA5D2 Series is available on GitHub pages.
CSP Application Examples
The CSP Applications Package (csp_apps_sam_a5d2) contains example applications that demonstrate the control of peripherals using Peripheral Libraries (PLIBs) with minimal external dependencies. A listing of CSP Application example projects for the SAMA5D2 Series is available on GitHub pages.