SAM9X60-EK – Getting Started with MPLAB® Harmony 3 Development: CSP Application: rtt_periodic_timeout

Introduction

In this training topic, you will download, configure, and build an MPLAB® Harmony 3 Software Framework application to run on the SAM9X60-EK Evaluation Kit using the MPLAB X Integrated Development Environment (IDE) in Debug mode. This scenario is typical of project development: coding, building, and debugging.

Once the application has been fully developed, the application is cleaned and built for production. The resulting binary image (harmony.bin) is written to Non-Volatile Memory (NVM), such as SD memory card, eMMC, NAND, or NOR Flash memories. The harmony.bin binary image is read from NVM by the second-stage bootloader, at91bootstrap, which is also written to NVM. However, at91boostrap must be configured and built for a given NVM. Instructions on how to do this are given in the "What’s Next?" section below.

MPLAB Harmony 3 Application

The CSP Application demonstrates the control of peripherals using Peripheral Libraries (PLIBs) with minimal external dependencies. The rtt_periodic_timeout application blinks the RGB LED once per second when an RTT timer interrupt occurs.

This same application can be run on the SAM9X60-Curiosity Development Board by migrating the code. For more information see: "Migrating a MPLAB® Harmony 3 Application from the SAM9X60-EK to SAM9X60-Curiosity: rtt_periodic_timeout"


Prerequisites

This training topic was developed with MPLAB X IDE v6.05 and XC32 v4.21.


Hardware

For this training, you will use the SAM9X60-EK Evaluation Kit.

SAM9X60-EK Evaluation Kit

Set up the SAM9X60-EK as listed below to the host computer running MPLAB X IDE.

Jumpers

SD Memory Cards

  • Ensure no SD memory cards are plugged into the SD card (J4) connector.

Power

Debug Communications

  • The SAM9X60-EK contains a J-Link On-Board Debug Probe. Connect a micro-B USB cable to J22 and the host computer running MPLAB X IDE.

Console Serial Communications


Configure and Build a Project for Debugging

In this section, you will download, configure, and build a CSP application using the MPLAB X IDE to run on the SAM9X60-EK in Debug mode. This scenario is typical of project development: coding, building, and debugging.

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

Normally, the MPLAB Harmony 3 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 3 Software Framework libraries are assumed preinstalled on the host computer. Therefore, if you do not have the MPLAB Harmony 3 Software Framework libraries preloaded, you will have to download or clone the CSP Application Library from the Microchip MPLAB Harmony 3 GitHub repository before opening the example application project. We will show you how in the steps below.

1

Download CSP Application Library

a

Create a Harmony3 directory

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

b

Download or clone csp_apps_sam_9x60

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

2

Open Project: rtt_periodic_timeout_sam_9x60_ek

a

From MPLAB X IDE, select File > Open project.

An Open Project window will open.

b

Locate the following project in the Harmony3 directory:

C:\Users\<user>\Harmony3\csp_apps_sam_9x60\apps\rtt\rtt_periodic_timeout\firmware\sam_9x60_ek.X
ide-rtt-open-proj.png

c

Click on the Open Project button. The rtt_periodic_timeout_sam_9x60_ek project loads into MPLAB X IDE.

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 at91bootstrap project. You can update the DFP to the latest version in the next steps.

3

Configure Project Properties for Debugging in MPLAB X IDE

a

Open Project Properties

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

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

The Projects Properties – rtt_periodic_timeout_sam_9x60_ek dialog box opens.

If you received a Configuration Loading Error in the previous step, you will see a [Resolve] link next to the version of the DFP that the project was originally developed with (see figure below). To update to the latest version, highlight the latest DFP and click on the Apply button. This will update the configuration to the latest DFP.

ide_rtt_proj_config_01.png

b

In the Categories pane, select Conf: [sam_9x60_ek]

c

Select the latest version of DFP, CMSIS, and XC32 Compiler.

The DFP contains device-specific support software. The 32-bit MCU and MPU DFPs are maintained by Microchip Technology and are available on GitHub.

The Cortex Microcontroller Software Interface Standard (CMSIS) is a vendor-independent hardware abstraction layer. It provides interfaces to processors and peripherals, real-time operating systems, and middleware components. CMSIS is publicly maintained on GitHub and provided free of charge by Arm® under the Apache 2.0 license.

d

In the Connected Hardware Tool drop-down menu, select the J-Link On-Board (OB) debug probe.

You must have the host computer running MPLAB X IDE connected to the J22 of the SAM9X60-EK to see the J-Link OB available in the drop-down menu.

ide_rtt_proj_config_tool_jlink.png

e

In the Categories pane, select Bootstrap.

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

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 3 project binary (harmony.bin). Once the project has been loaded onto the SAM9X60-EK, MPLAB X IDE can be used to run and debug the application.

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

ide_rtt_proj_bootstrap_elf.png

f

Click the Apply and OK buttons.

4

Configure the Harmony Content Path

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

a

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

b

From the Options window, Select Plugins from the ribbon.

c

Click on the MPLAB Code Configurator 5.x tab.

d

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

e

Click on the Apply and OK buttons.

ide_rtt_options_plugins_605.png

5

Set Debug Reset and Startup Options

a

In MPLAB X IDE, click on Tools > Options.

An Options window opens.

b

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

c

Configure the settings for:

  • Debug Reset @ – Main
  • Debug startup – Halt at Main
ide-rtt-options-embedded.png

d

Click on the OK button. 

6

Build the Project

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

a

Click on the Debug Project icon on the toolbar.

The project will build with debugging parameters, load the application binary to the SAM9X60-EK, 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 SAM9X60 and then exits without loading any additional binary files to SDRAM. MPLAB X IDE then loads the application program to SDRAM. For more information see: SAM9X60 Boot Process

For more information on establishing serial communications with the target console see: "SAM9X60 Curiosity Development Board - Console Serial Communications"

rtt-console.png
ide-rtt-debug-halt.png

b

Click on the Continue button. The application binary runs within the target. Observe the RGB LED LD1 flashes blue at a 1 Hz rate.

Congratulations! You successfully downloaded, configured, and built an MPLAB Harmony 3 CSP application example to run on the SAM9X60-EK in debug mode.

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


Continuing Development with MPLAB Harmony 3 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, don’t forget to (re)build the project. Also, you must reset the SAM9X60-EK.

For this example application, you only downloaded or cloned one MPLAB Harmony 3 library: CSP application for the SAM9X60. There are several libraries required to perform full development. In this section, you will use MCC to download and manage these libraries.

Open MPLAB Code Configurator (MCC)

1

Open MCC by clicking on the MCC shield on the tool bar.

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

ide_mcc_content_manager_wizard.png

2

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

3

Click on the Finish button at the top. The required content will download. Be patient, this will take a while.

a

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.

ide-rtt-mcc-project-manifest.png

b

Click on the Continue button

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

4

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

a

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

ide-rtt-mcc-project-graph.png

b

Observe the packages and versions that were called out in the dialog in Step 3a above. Select the latest version available for each package and click on the Apply button. In this example, the csp and dev_packs.

ide-rtt-mcc-content-manager.png

c

Click on the Generate button.

MCC will generate new source code.

5

Close MCC

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


Download Packages for MPU Development

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

  • The Board Support Package (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 the device driver, system service, OSAL, and third-party software libraries.

1

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

2

Expand Harmony 3 Core

3

Select the latest version of the bsp and core libraries.

4

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.


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

1

Click on the Clean and Build icon on the toolbar.

2

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_9x60/apps/rtt/rtt_periodic_timeout/firmware/sam_9x60_ek.X/dist/sam_9x60_ek/production/
ide_rtt_build_successful_production.png

3

Observe the DDRAM Address that harmony.bin is to be loaded 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.

ide_rtt_ddram_linker_production.png

Summary

In this training topic, you downloaded, configured, and built an MPLAB Harmony 3 application example using the MPLAB X IDE to run on the SAM9X60-EK Evaluation Kit in Debug mode. Finally, you cleaned and built the application for production.


What’s Next?

Once an MPLAB Harmony 3 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 image from NVM and writing to SDRAM. The following training topics show how this is done for NAND Flash, NOR Flash (QSPI), and SD memory card.

Second-Stage Bootloader at91bootstrap

Writing to Non-Volatile Memory (NVM) using SAM-BA In-System Programmer (ISP)

Migrating to SAM9X60-Curiosity Development Board

If you would like to learn how to migrate an MPLAB Harmony 3 Software Framework application example initially developed for the SAM9X60-EK Evaluation Kit to the SAM9X60-Curiosity Development Board, see: "Migrating a MPLAB® Harmony 3 Application from the SAM9X60-EK to SAM9X60-Curiosity: rtt_periodic_timeout"

© 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.