ATSAMA5D27-SOM1-EK1 MPLAB® Harmony 3 Development Core Application: Time System Service

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:

  1. Debugging – In this training, we show you how to debug the project using MPLAB X IDE.
  2. 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.

dev_model_core.png
Figure 1

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 X IDE

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

atsama5d27-som1-ek1.png
Figure 2

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.

atsama5d27-som1-ek1_jlink_ob_cdc_pwr.png
Figure 3

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

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.

install_harmony_framework_02.png
Figure 4

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.

2

Click on Tools > Embedded > MPLAB Harmony 3 Content Manager.

The Framework Path window will open:

install_harmony_framework_02.png
Figure 5

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.

5

Click on the Select Category dropdown arrow and select core_apps_sam_a5d2.

This will filter the display to show only the Core Application programs for the SAMA5D2 Series.

mhcm_app_browser_a5d2_core.png
Figure 6

6

Scroll down to the bottom of the list and check the box next to
core_apps_sam_a5d2\apps\system\time\sys_time_multiclient\firmware\at91bootstrap_sam_a5d27_som1_ek_freertos.X
core_apps_sam_a5d2\apps\system\time\sys_time_multiclient\firmware\sam_a5d27_som1_ek_freertos.X

mhcm_app_browser_a5d2_core_copy.png
Figure 7

7

Click on the Copy selected link at the top left.

A Select Destination Path dialog box will open. This is where you can enter the location of your working directory:

mhcm_app_browser_a5d2_core_copy_destination.png
Figure 8

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.

3

Navigate to the directory:
C:\Users\<user>\Harmony3_Core_Apps\core_apps_sam_a5d2\apps\system\time\sys_time_multiclient\firmware\

mplab_x_open_project_a5d2.png
Figure 9

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.

mplab_x_sys_time_dashboard_a5d27.png
Figure 10

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.

1

In the Projects pane (upper left), select sys_time_multiclient_sam_a5d27_som1_ek_freertos.

Observe the Dashboard in the lower left pane, which displays the sys_time_multiclient_sam_a5d27_som1_ek_freertos project properties.

mplab_x_sys_time_dashboard_a5d27.png
Figure 11

2

Open the Project Properties window by either:

  • In the Projects pane (upper left), right-click on sys_time_multiclient_sam_a5d27_som1_ek_freertos and select Properties, or
  • In the Dashboard pane (lower left), click on the wrench.
sam_a5d27_som1_ek_project_properties_01.png
Figure 12

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.

sam_a5d27_som1_ek_project_properties_02.png
Figure 13

d

Click on the Apply button.

Observe that Bootstrap now shows in the Categories pane:

sam_a5d27_som1_ek_project_properties_02a.png
Figure 14

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

sam_a5d27_som1_ek_project_properties_bootstrap.png
Figure 15

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.

5

In the Categories pane (on left), select Conf: (sam_a5d27_som1_ek_freertos) > J-Link.

sam_a5d27_som1_ek_project_properties_03.png
Figure 16

a

In the Option categories drop down box, select Communication.

b

Select JTAG Method as SWD

c

Click on the Apply button.

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:

sam_a5d27_som1_ek_project_properties_dashboard.png
Figure 17

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

2

On the ATSAMA5D27-SOM1-EK1, momentarily press the nRST (Reset) button (PB1).

Observe RomBOOT is displayed on the Console terminal.

tera_term_romboot.png
Figure 18

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:

  1. Debugging – In this training, we show you how to debug the project using MPLAB X IDE.
  2. 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.

b

Observe the Console terminal messages displayed:

tera_term_time_sys_running_a5d27.png
Figure 19

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.

© 2024 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.