Introduction
This training is for the embedded systems developer who wishes to use MPLAB® Harmony 3 Software Framework for Microchip Technology’s SAM9X60 Microprocessor (MPU).
For more information about the MPLAB Harmony 3 Software Framework, see the "Introduction to MPLAB® Harmony 3 Software Framework for Microchip Technology 32-bit Microprocessor Units (MPUs)" page.
Pulse Width Modulation
In this training, you will learn how to open, configure, build, and debug a Pulse Width Modulation (PWM) Chip Scale Package (CSP) Application example project using MPLAB X Integrated Development Environment (IDE). This project will use the PWM peripheral to blink the RGB LED (LD1) red at a 1.5 Hz rate.
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 external NVM. Instructions on GitHub Pages show you how to open, configure, build, load to SD Memory Card, and run the example project.
Chip Support Package Repository
The Chip Support Package (csp) repository contains software libraries that perform basic MPU device initialization and startup, and Peripheral Libraries (PLIBs) that perform initialization, setup, operation, and status of peripherals.
Peripheral Library
Peripheral Libraries allow the software developer to initialize and control the peripherals of a device. This layer is useful for the developer who requires simple and direct control of peripherals to allow them to write simple applications.
The Peripheral Libraries are part of the Chip Support Package (csp) and are dependent on the Device Family Package (dev_packs) for device information.
CSP Applications Package
The CSP Applications Package (csp_apps_<device>) repository contains example applications that demonstrate the control of peripherals using Peripheral Libraries with minimal external dependencies. A listing of CSP Application example projects is available on GitHub Pages.
Subjects covered in this topic:
- Hardware
- Create Working Directory
- Create New Project
- Configure Harmony Project and Generate Code
- Configure MPLAB X IDE Project
- Write Application Code
- Debug Project
Prerequisites
Hardware
SAM9X60-EK Evaluation Kit
For this training, you will use 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 Figure 4). 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 use 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 the "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 Working Directory
It is a good practice to create a working directory to place the source code 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 the 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 5). On a Windows computer, the default location is C:\Users\<user>\Harmony 3.
You may use this location for running CSP application programs for demonstration purposes. However, if you plan to make any changes you may want to create a project directory.
Creating 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 CSP application of your choice to a working directory of your choice. The Harmony Content Manager will also allow you to keep the CSP 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 working directory location later.
4
Click the Application Browser button.
8
Create a Working Directory.
For the purposes of this tutorial, we’ll name our working directory C:\Users\<user>\Harmony3_CSP_Apps.
This completes creating a working directory for the CSP Application example project.
Create a New Project
In this section, you will start MPLAB X IDE and create a new MPLAB Harmony 3 project for the SAM9X60-EK.
This training topic uses v3.10.0 of the csp package.
1
Start MPLAB X IDE.
4
From the New Project window, Step 2. Framework Selection:
a
Confirm the Framework Path (directory) of the Harmony 3 Framework that you download when creating a working directory.
b
Click on the Next button.
5
From the New Project window, Step 3. Project Settings:
a
Enter the Path (directory) that you wish to store your project.
Location: This is the location (directory) where all project files will be stored. If you installed the Harmony 3 Framework using the default settings, MPLAB X IDE will create the default location C:\Users\<user>\HarmonyProjects\MyProject_n\.
For this project, you’ll backspace over MyProject_n and enter sam9x60-ek\blink_RGB_LED. You can observe how the directory is being constructed in the Path box.
Folder: This is the name of the folder that contains the MPLAB X IDE project files. It is appended to the directory that you entered in the Location box. The folder name will be appended with “.X”.
For this project, enter blink_RGB_LED. You can observe how the directory is being constructed in the Path box.
You will notice that as you enter blink_RGB_LED into the Folder field, it also appears in the Name field.
Name: This is the name of the project as you will see it in the MPLAB X IDE Projects tab after you have created the project.
As you may have noticed, we are using blink_RGB_LED for three things:
- The location of the project files,
- the name of the MPLAB X IDE project folder, and
- the project name.
b
Click on the Next button.
6
From the New Project window, Step 4. Configuration Settings:
b
In the Device Family drop-down box, select SAM. Observe the Target Device is SAM9X60.
c
Click on the Finish button. The Harmony 3 Configurator will begin to load.
You can manually open the Harmony 3 Configurator on the menu bar: Tools > Embedded > MPLAB Harmony 3 Configurator.
7
As the Harmony 3 Configurator opens, a Configuration Database Setup window will appear.
The Configuration Database Setup window displays the location (directory) of the Device Family Pack (DFP) and the Cortex Microcontroller Software Interface Standard (CMSIS) libraries. Both are contained in the dev_pack module when installing the Harmony 3 Framework.
The Harmony 3 Configurator will display the latest versions of the DFP and CMSIS that you installed. You may verify the versions by comparing the Setup window with MPLAB Harmony Content Manager (MHCM).
DFP: The Device Family Pack (DFP) contains device-specific support software. The 32-bit MCU and MPU DFPs are maintained by Microchip Technology and are available on GitHub.
CMSIS: 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.
This completes creating a new project for the CSP Application example project.
Configure the Harmony Project and Generate Code
In this section, you will configure the blink_RGB_LED project using the MPLAB Harmony 3 Configurator to add the PWM PLIB to your project and connect it to the red segment of the RGB LED (LD1). Once the configuration is complete, you will generate the Harmony source code files.
For more information, see MPLAB Harmony 3 Configurator documentation on GitHub Pages.
2
Add the PWM Peripheral Library to the blink_RGB_LED project:
a
In the Active Components pane on the left, expand the Peripherals menu.
b
Expand the PWM menu to show the available PWM peripherals for the SAM9X60. Note that there is only one choice.
3
Configure the Port/Pin to the PWM0 signal.
From the SAM9X60 datasheet we can see that the pin PB11 can be used for PWM functionality in PMUX Function A:
From the SAM9X60-EK user guide, we can see that PB11 controls the red LED.
Pin | Port | Signal | RGB LED LD1 |
---|---|---|---|
D6 | PB11 | PWM0 | Red |
C2 | PB12 | PWM1 | Green |
A4 | PB13 | PWM2 | Blue |
a
Select Tools > Pin Configuration. The Pin Configuration window will open.
The Pin Configuration window provides three different views:
- Pin Settings (which can be ordered by Pins or Ports)
- Pin Table
- Pin Diagram
You can select the view by clicking on the tabs in the lower-left portion of the window. Each view is synchronized. A change in one of the views will be reflected in the other views automatically.
To resize the Pin Configuration window, hover over the edge or corners of the window until the cursor turns into a double arrow. Click, grab and drag.
To reposition the Pin Configuration window, hover over the top-center edge of the window until the cursor turns into a four-way arrow. Click, grab and drag.
b
In the Pin Settings view, select Ports from the Order drop-down menu. The view will be ordered by Port name (labeled as Pin ID).
c
Scroll down until you see Port (Pin ID) PB11.
e
Close the Pin Configuration window by closing all three views in turn.
4
Configure the PWM peripheral for a 1.5 Hz square-wave signal on channel 0.
b
Expand Clock A Configurations:
- Click on the Enable Clock box.
- Select Master Clock divided by 512 from the Prescaler drop-down menu.
- Enter 255 in the Divider box.
When entering values, you must either hit Tabor Enter and observe the label turns green to ensure the value has been entered.
c
Expand the Clock 0 Configurations:
- Click on the Enable box.
- Select Clock A from the Prescaler drop-down menu.
- Select Center aligned from the Alignment drop down menu.
- Select Waveform starts at high level from the Polarity drop-down menu.
- Enter 500 in the Period Count box.
- Enter 250 in the Duty Cycle Count box.
8
Close (exit) the MPLAB Harmony 3 Configurator.
10
Ensure that blink_RGB_LED project is set as the main project.
If no other projects are visible in the Projects tab, then the blink_RGB_LED project will automatically be set as the main project.
However, if there are other projects visible in the Projects tab, then you will need to set the blink_RGB_LED project as the main project.
a
Right-click on the blink_RGB_LED project in the Projects tab. Select Set as Main Project in the pop-up menu.
This completes configuring the Harmony Project and Generate Code for the CSP Application example project.
Configure MPLAB X IDE Project
In this section you will configure the blink_RGB_LED project in the MPLAB X IDE.
Ensure that the SAM9X60-EK is connected to the Host Computer following the instructions in the Hardware section above.
2
In the Project Properties – blink_RGB_LED window:
a
In the Packs box, select the latest version of the SAM9X60 Device Family Pack (DFP).
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 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.
d
Click on the Apply button.
Observe that Bootstrap now shows in the Categories pane.
g
In the JTAG Method drop-down menu, select 4-wire JTAG.
h
In the Categories pane (on left), select Conf: (blink_RGB_LED) > Bootstrap.
i
Observe that the Use bootstrap box is checked.
k
Click on the Apply button.
l
Click on the OK button.
You have established debug communications via the SAM9X60-EK JTAG port and MPLAB X IDE.
This completes the configuration of MPLAB X IDE for building, debugging, and running the blink_RGB_LED project. You can review the Project Properties settings in the Dashboard pane.
In the next section, you will write the application program in main.c.
Write Application Code
Up to this point in the project creation process, you used MPLAB Harmony 3 Configurator to configure and generate code to initialize the device (SAM9X60) and initialize and control the Pulse Width Modulation peripheral. All that is left is for you to write the application code.
Documentation for each of the Peripheral Libraries is contained in the Chip Support Package. You can access them in one of three ways:
- As a Microsoft Compiled Help file (*.chm) that is part of Harmony 3 Framework that you download when installing the Harmony 3 Framework. (C:\Users\<user>\Harmony3\csp\doc\help_harmony_csp.chm)
- As a HTML file (*.html) that is part of Harmony 3 Framework that you download when installing the Harmony 3 Framework. (C:\Users\<user>\Harmony3\csp\docs\index.html)
- Online as a GitHub Pages file: https://microchip-mplab-harmony.github.io/csp/
2
Click on the PWM Peripheral Library Help.
3
Click on Library Interface.
This section describes each available function for the PWM peripheral on the SAM9X60.
4
Write an application in main.c to flash the red LED of LD1 at a rate of 1.5 Hz.
For our blink_RGB_LED application, we need to:
- Initialize the PWM peripheral,
- Enable channel 0, and
- Start channel 0.
a
Write the application in main.c to initialize the PWM peripheral.
Recall that you configured the PWM peripheral clock and channel 0 in the Configure the Harmony Project step. When you clicked on Generate Code, Harmony 3 Configurator created the initialization code for you.
You can see the function PWM_Initialize() in the initialization.c file under the SYS_Initialze() function called from main.c.
Thus, the initialization code was created for you by Harmony 3 Configurator with the parameters you entered in the configuration options.
b
Write the application in main.c to enable PWM Channel 0.
The next step is to enable PWM Channel 0. This is performed with the PWM_ChannelCounterEventEnable() function. We write this function in the main.c file, below the SYS_Initialize() function:
/* Enable PWM Channel 0 */
PWM_ChannelCounterEventEnable(PWM_CHANNEL_0_MASK);
5
Click on the Clean and Build Project icon from the tools bar or select Production > Clean and Build Project from the menu bar. Observe that the build was completed successfully from the Output pane.
This completes writing the application code for the CSP Application example project.
Debugging the Project
In this section, you will set up the 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 external NVM. Instructions on GitHub Pages show you how to open, configure, build, load to SD Memory Card, and run the example project.
1
Observe 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.
2
Click on the Debug Project icon on the toolbar.
The project will build with debugging parameters and load the application binary to the SAM9X60-EK (otherwise known as the target).
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 the SAM9X60 Boot Process training.
Once the build is complete and the application binary is loaded into the target, the toolbar expands to show additional debugging icons.
3
Click on the Continue button. The application binary runs within the target. Observe that LED LD1 flashes red at a 1.5 Hz rate.
Congratulations! You have opened, configured, built, and debugged a CSP 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.
Extra Credit
Here are some things to try:
- Change the blinking rate of the red LED
- Blink the green or blue LED
Hint: you will need to use MPLAB Harmony 3 Configurator to change and/or configure the PWM peripheral. To blink the green or blue LED, remember you must make the pin assignments.
Summary
In this training, you learned how to open, configure, build, and debug a Pulse Width Modulation Peripheral Library CSP Application example project using MPLAB X IDE. This project used the PWM peripheral to blink the RGB LED (LD1) red at a 1.5 Hz rate.
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 Pages.
CSP Application Examples
The CSP Applications Package (csp_apps_sam_9x60) contains example applications that demonstrate the control of peripherals using Peripheral Libraries with minimal external dependencies. A listing of CSP Application example projects for the SAM9X60 is available on GitHub Pages.