SAMA5D29-Curiosity – Getting Started with MPLAB® Harmony v3 Development: CSP Application: pio_led_on_off_interrupt

Last modified by Microchip on 2024/06/20 12:44

Contents

Introduction
- MPLAB Harmony v3 Application
Prerequisites
Hardware
- SAMA5D29-Curiosity Development Board
Configure and Build a Project for Debugging
Continuing Development with MPLAB Harmony v3 Software Framework
Summary
Learn More

Introduction

In this training topic, you will download, configure, and build an MPLAB® Harmony v3 Software Framework application example using MPLAB X Integrated Development Environment (IDE) to run on the SAMA5D29-Curiosity Development Board in debug mode. This scenario is typical of project development steps of coding, building, and debugging.

While in Debug mode, the second-stage bootloader, at91bootstrap, is used by MPLAB X IDE to initialize Dynamic Random-Access Memory (DRAM) so that it can continue loading the MPLAB Harmony v3 project binary (harmony.bin). Once the project has been loaded onto the SAMA5D29-Curiosity, MPLAB X IDE can be used to run and debug the application.

Once a project has been fully developed, the application is cleaned and built for production. The application binary (harmony.bin) is loaded by at91bootstrap from Non-Volatile Memory (NVM), such as an SD memory card, e.MMC, NAND, NOR, and SQI™ Flash memories. Training topics on how to write binary files to NVM are given in the "Learn More" section.

MPLAB Harmony v3 Application

This Chip Support Package (CSP) Application example demonstrates the control of peripherals using Peripheral Libraries (PLIB) with minimal external dependencies.

This application uses the PIO Peripheral library to generate callback on switch press and release and drives the GPIO pin connected to the RGB LED to indicate the switch status. The RGB LED is turned ON when the switch is pressed and turned OFF when the switch is released.

Prerequisites

MPLAB X IDE installed
MPLAB XC32 Compiler installed

This training topic was developed with MPLAB X IDE v6.20 and MPLAB XC32 Compiler v4.35

Hardware

For this training, you will use the SAMA5D29-Curiosity Development Board (P/N: EV07R15A) .

SAMA5D29-Curiosity Development Board

For more information, see the “SAMA5D29-Curiosity – Features” page.

Setup the SAMA5D29-Curiosity as listed below to the host computer running MPLAB X IDE.

Jumpers

Set the jumpers to their default positions as shown in the “Jumper Summary” section of the “SAMA5D29-Curiosity - Features” page.

SD Memory Cards

Ensure no SD memory cards are plugged into SD Card slots (J6 or J7).

Power

Apply power as shown in the “Power Options” section of the “SAMA5D29-Curiosity - Features” page.

Debug Communications

Connect a debug probe, such as the Microchip J-32 Debug Probe to the JTAG Connector (J12) and the host computer running MPLAB X IDE.

Console Serial Communications

To view the target console, connect the host computer running a terminal emulation program in accordance with “SAMA5D29-Curiosity – Console Serial Communications.”

Configure and Build a Project for Debugging

In this section, you will download, configure, and build a CSP Application example using the MPLAB X IDE to run on the SAMA5D29-Curiosity in Debug mode. This scenario is typical of the initial project development steps of coding, building, and debugging.

As of MPLAB X IDE v6.05, the plugins, MPLAB Harmony 3 Content Manager (MHCM) and MPLAB Harmony Configurator (MHC), have been migrated to MPLAB Code Configurator (MCC).

Normally, the MPLAB Harmony v3 Software Framework libraries are downloaded when a new MCC project is created in MPLAB X IDE. However, when working with an example application, such as this one, the MPLAB Harmony v3 Software Framework libraries are assumed to be preinstalled on the host computer. Therefore, if you do not have the MPLAB Harmony v3 Software Framework libraries preloaded, you must download or clone the CSP Application Library from the Microchip MPLAB Harmony v3 GitHub repository before opening the example application project. We will show you how in the following steps.

Download CSP Application Library

Create a Harmony3 Directory.

Create a directory named Harmony3. For a Windows operating system, it is typically located at C:\Users\<user>\Harmony3\

Download or clone csp_apps_sam_a5d2.

Download or clone csp_apps_sam_a5d2 library from the Microchip MPLAB Harmony 3 GitHub repository to the Harmony3 directory.

Open Project: pio_led_on_off_interrupt_sam_a5d2_curiosity.

From MPLAB X IDE, select File > Open project.

An Open Project window will open.

Locate the following project in the Harmony3 directory:

C:\Users\<user>\Harmony3\csp_apps_sam_a5d2\apps\pio\pio_led_on_off_interrupt\firmware\sam_a5d2_curiosity.X

Click on the Open Project button.

The pio_led_on_off_interrupt_sam_a5d2_curiosity project loads into MPLAB X IDE.

Open Project

You may receive a Configuration Loading Error. This is due to an older version of the Device Family Pack (DFP) at the time of creating the project. You will update the DFP to the latest version in the next steps.

Configure Project Properties for debugging in MPLAB X IDE.

Open Project Properties.

Open the pio_led_on_off_interrupt_sam_a5d2_curiosity Project Properties using one of the following methods:

In the Projects pane, highlight pio_led_on_off_interrupt_sam_a5d2_curiosity and click on the wrench icon in the pio_led_on_off_interrupt_sam_a5d2_curiosity - Dashboard.
In the Projects pane, right-click on pio_led_on_off_interrupt_sam_a5d2_curiosity and select Properties from the menu.

The Projects Properties – pio_led_on_off_interrupt_sam_a5d2_curiosity dialog box opens.

Screen capture of the Open Project window

In the Categories pane, select Config: [sam_a5d2_curiosity].

Select the version of DFP and MPLAB XC32 Compiler you require for the application.

You may see a [Resolve] link next to a version of the DFP. This is due to an older version of the DFP at the time of creating the project. Highlight the latest DFP and click on the Apply button. This will update the configuration to the latest DFP.

In the Connected Hardware Tool drop-down menu, select the connected debug probe.

The debug probe must be connected to the host computer to see it available in the drop-down menu.

In this example, we are using the Microchip J-32 Debug Probe.

Click on the Apply button. Observe under the Categories: Conf: [sam_a5d2_curiosity) that J-32 and Bootstrap are now listed.

Screen capture of Project Properties: Tools

Screen capture of Project Properties: Tools apply

In the Categories pane, select J-32.

In the Option categories drop-down box, select Communications.

Observe JTAG Method is set to SWD.

Observe JTAG Speed (MHz) is set to 4.

Screen capture of Project Properties: Tools SWD

In the Categories pane, select Bootstrap.

Observe that Use bootstrap is selected and the pre-compiled version of the at91bootstrap.elf is selected.

If you have compiled a custom version of the at91bootstrap, press on the Load button, locate and highlight, then press the Open button. For more information, see the training topics listed in the "Learn More" section.

While in Debug mode, the second-stage bootloader, at91bootstrap, is used by MPLAB X IDE to initialize DRAM so that it can continue loading the MPLAB Harmony v3 project binary (harmony.bin). Once the project has been loaded onto the SAMA5D29-Curiosity, MPLAB X IDE can be used to run and debug the application.

AT91bootstrap is a second-stage bootloader for Arm®-based Microchip Technology microprocessors (MPU). For more information see the "at91bootstrap: A Second Stage Bootloader for Microchip MPUs" page.

Screen capture of Project Properties: Bootstrap

Click the Apply and OK buttons.

Configure the Harmony Content Path.

In this step, you will let MPLAB X IDE know the location (directory) of the MPLAB Harmony v3 Software Framework on your host computer.

From the MPLAB X IDE menu, select Tools > Options.

From the Options window, Select Plugins from the ribbon.

Click on the MPLAB Code Configurator 5.x tab.

Under Harmony Content Path, click on the finder and select the location of the Harmony3 directory.

Click on Apply and OK buttons.

MPLAB X IDE Options

Set Debug Reset and Debug startup options.

In MPLAB X IDE, click on Tools > Options. An Options window opens.

Click on the Embedded icon at the top and the Generic Settings tab.

Configure the settings for:

Debug Reset @ as Main
Debug startup as Halt at Main

MPLAB IDE Options: Debug

Click on the OK button.

Power the SAMA5D29-Curiosity.

Power the SAMA5D29-Curiosity by connecting either:

a USB-C cable to USB-A Port (J1) and host computer, or
+5 VDC external power applied to connector J2.

For more information see the “Power Options” section of the “SAMA5D29-Curiosity - Features” page.

Press the RESET push button (SW2).

This step places the first-stage bootloader into the SAM-BA Monitor mode. You can observe the RomBOOT message on the console.

For more information see the "SAMA5D2 Series Boot Process" page.

At this point, you have configured the MPLAB Harmony 3 project within MPLAB X IDE. In the next section, you will build the project for debugging.

Build the project.

Click on the Debug Project icon on the toolbar.

The project will build with debugging parameters, load the application binary to the SAMA5D29-Curiosity, and Halt at Main. Once the build is complete and the application binary is loaded into the target, the toolbar expands to show additional debugging icons.

MPLAB X IDE uses at91bootstrap to initialize the SAMA5D29 and then exits without loading any additional binary files to SD. MPLAB X IDE then loads the application program to SDRAM. For more information see the "SAMA5D2 Series Boot Process" page.

Screen capture of IDE halted in debug mode

You can view the second-stage bootloader (at91bootstrap) activity on the console.

For more information on establishing serial communications with the target console see the "SAMA5D29-Curiosity - Console Serial Communications" page.

Screen capture of console with harmony application running

Click on the Continue button. The application binary runs within the target.

Press the USER (SW1) push button and observe the RGB LED (D7) lights green. Release the USER push button and the RGB LED will turn off.

The application uses the PIO Peripheral library to generate callback on switch press and release and drives the GPIO pin connected to the RGB LED to indicate the switch status.

If you Stop a debug session, you must press the Reset button on the SAMA5D29-Curiosity to initiate the boot process before launching another debug session.

Congratulations! You successfully downloaded, configured, and built an MPLAB Harmony v3 CSP Application example to run on the SAMA5D29-Curiosity in debug mode.

Continuing Development with MPLAB Harmony v3 Software Framework

With the project in Debug mode, you can now pause, insert additional breakpoints, and continue running the project. If you change the source code, you will need to reset the SAMA5D29-Curiosity prior to (re)building and loading the project to the target. Resetting places the MPU back into the bootloader mode.

For this example application, you only downloaded or cloned one MPLAB Harmony v3 library, CSP Applications for the SAMA5D29. There are several libraries required to perform full development. In this section, you will use MPLAB Code Configurator to download and manage these libraries.

MPLAB Code Configurator (MCC)

Start MCC by clicking on the MCC shield on the toolbar.

The MCC Content Manager Wizard will open. In the top half window is the Required Content.

Screen capture of MCC Content Manager

Expand the rows in the Component column to view the required libraries.

Click on the Finish button at the bottom-right. The required content will be downloaded. Be patient, this will take a while.

A Package Versions Used vs Available dialog may appear if the MPLAB Harmony package versions that the project was developed with do not match the versions available locally. In the next steps, you will update the project to the latest package versions.

Click on the Continue button.

MCC is now available. The Project Graph, Project Resources, and Device Resources windows are active.

If you received a Package Versions Used vs. Available dialog, perform the following steps:

In the Device Resources pane, click on the Content Manager button.

MCC Project Graph

Observe the packages and versions that were called out in the dialog in Step 3.1 above. You can either:

Individually select the latest version available for each package (in this example, the csp and dev_packs) and click the Apply button, or
Click the Select Latest Version(s) button and click the Apply button. This will update all selected libraries to the latest version.

Changes will be applied and MCC will restart. You will see the Package Versions Used vs Available dialog again, this time showing the latest versions under the Local Packages column. Click the Continue button.

Click the Generate button.

MCC will generate new source code.

Download Packages for MPU Development

There are additional libraries required for MPU development. They are the Board Support Package (bsp) and Core (core).

The BSP contains the defines (names and attributes) of the features (clock configuration, pins, switches, and LEDs) of a selected evaluation kit.
The Core Package (core) contains device driver, system service, OSAL, and third-party software libraries.

Click the Component drop-down box and un-check Device Supported Content Only to display all available MPLAB Harmony v3 libraries.

Expand Harmony 3 - Core.

Select the latest version of the bsp and core libraries.

Click on the Apply button.

The package versions will be downloaded and installed. MCC will restart.

The bsp and core libraries give you more resources for MPU development. However, there are a number of additional libraries available. Select and download them as needed using the same steps outlined above.

Click on the Generate button.

MCC will generate new source code.

Close MCC.

If displayed, merge all code.

At this point, the required libraries for the pio_led_on_off_interrupt_sam_a5d2_curiosity project are loaded.

Configure and Build a Project for Production

Once a project has been fully developed, the application is cleaned and built for production. The application binary (harmony.bin) is loaded from NVM, such as SD memory card, eMMC, NAND, and NOR Flash memories, by the second-stage bootloader, at91bootstrap.

Clean and Build the Project

Click on the Clean and Build icon on the toolbar.

Observe the location of the production binary. Take note of this location as it contains the harmony.bin binary that you will write into NVM.

C:\Users\<user>\Harmony3\csp_apps_sam_a5d2\apps\pio\pio_led_on_off_interrupt\firmware\sam_a5d2_curiosity.X\dist\sam_a5d2_curiosity\production\harmony.bin

Screen capture of the MPLAB IDE output window

Observe the DDRAM Address that harmony.bin is to be loaded to by at91bootstrap. This is found in the Linker Files, ddram.ld. Take note of this value as it is required for configuring at91bootstrap to load harmony.bin from NVM.

Screen capture of MPLAB IDE showing DDRAM linker

Summary

In this training topic, you downloaded, configured, and built an MPLAB Harmony v3 application example using the MPLAB X IDE to run on the SAMA5D29-Curiosity Development Board in debug mode. You cleaned and built the application for production and now it’s ready for writing into NVM.

Learn More

Once an MPLAB Harmony v3 application (harmony.bin) has been developed and built for production, the next step is to configure and build the second-stage bootloader, at91bootstrap, for reading the harmony.bin binary from NVM and writing to SDRAM. The following training topics show how this is done for SQI™ Flash memory and SD memory card.