Introduction
This training is for the embedded systems developer who wishes to use MPLAB® Harmony 3 Software Framework for Microchip Technology’s SAM9X60 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, you will learn how to open, configure, build, and debug the Time System Service Core Application example project using MPLAB X Integrated Development Environment (IDE). This example project uses the TC0 timer to blink the RGB LED (LD1) 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_9x60) 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 SAM9X60 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
SAM9X60-EK Evaluation Kit
For this training, you will be using the SAM9X60-EK Evaluation Kit.
Setup
You will need two USB Micro-B cables. One cable will connect the Host PC to USB port (J22) to communicate with the J-Link On-Board + CDC (see Setup below). The second cable will connect the Host PC to USB port (J7) to power the SAM9X60-EK.
Ensure the jumpers are in the positions shown in the figure above.
Debug Communications
You will be using the J-Link On-Board Debug Probe that is located on the SAM9X60-EK Evaluation Kit. Debug communications between the Host PC and the SAM9X60-EK take place through USB port J22 (J-Link-OB). Note that this is the same USB port used for Console Serial communications. MPLAB X IDE will control the SAM9X60-EK (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 "MPU Debug Probes" page.
Console Serial Communications
Console Serial communications between the Host PC and the SAM9X60-EK take place through USB port J22 (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 SAM9X60 DBGU 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 the "SAM9X60-EK - Console Serial Communications" page.
Power
You can power the SAM9X60-EK Evaluation kit by connecting a USB Micro-B cable between the Host PC and USB port (J7). Alternately, you can power the SAM9X60-EK by connecting an external 5 VDC regulated power supply to J1.
Create Project Directory
It is a good practice to create a project 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 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 the figure below). 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 project directory.
Create a Project Directory
Creating a project 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 project 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 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 Project Directory.
For the purposes of this tutorial, we’ll name our project directory C:\Users\<user>\Harmony3_Core_Apps.
This completes creating a project 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_9x60 package.
1
Start MPLAB X IDE.
2
Click on File > Open Project…
The Open Project window will open.
4
Select sam_9x60_ek.X and click on the Open Project button.
This completes opening (Open Project…) of the Time System Service Application project. You can observe sys_time_multiclient_sam_9x60_ek 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 SAM9X60-EK 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_9x60_ek).
4
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 SAM9X60-EK.
The J-Link Debug Probe will not be visible in the drop-down box unless the SAM9X60-EK Evaluation Kit is connected in accordance with the Hardware Setup (above) and powered on.
6
In the Categories pane (on left), select Conf: (sam_9x60_ek) > 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_9x60_ek.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.
8
In the Option categories drop down box, select Communication.
9
Select JTAG Method as 4-wire JTAG, click on the Apply button, then the OK button to close the Project Properties window.
You have established debug communications via the SAM9X60-EK 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 SAM9X60-EK Evaluation Kit is connected to the Host PC in accordance with the instructions in the hardware Setup section above.
LEDs on the SAM9X60-EK will indicate:
- D9 green – J-Link-OB+CDC is operational
- D7 green – Boot Enabled (Jumper J13 is open)
- RGB LD1 red – no program is running on the SAM9X60
3
In the Projects pane (upper left), select and highlight the sys_time_multiclient_sam_9x60_ek project.
The icons in the toolbar will act on the selected project.
4
Clean and Build the sys_time_multiclient_sam_9x60_ek project by either:
- Click on the Clean and Build Project icon in the Toolbar, or
- Right click on sys_time_multiclient_sam_9x60_ek 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_9x60_ek, 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_9x60_ek 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-9x60_ek, 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.
You may observe on the Console terminal the message that the at91boostrap failed to load the image.
The reason for the message is that the at91bootstrap.elf file for this example project was originally compiled expecting to load harmony.bin from SD memory card. When at91bootstrap failed to find harmony.bin on a SD memory card, MPLAB X IDE took over and loaded harmony.bin to the SAM9X60.
The at91bootstrap initialized the main oscillator, external volatile memory (DRAM), and configured peripherals. MPLAB X IDE loaded the application binary (harmony.bin) to DRAM via the JTAG port.
For more information see:
d
Observe RGB LED LD1 is green, indicating a program has been loaded on the SAM9X60.
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 SAM9X60-EK 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 (LD1) 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_9x60) contains several 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 SAM9X60 is available on GitHub.
CSP Application Examples
The CSP Applications Package (csp_apps_sam_9x60) 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 SAM9X60 is available on GitHub.