SAM9X60-EK MPLAB® Harmony 3 Development CSP Application: PWM

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:

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

dev_model_csp.png
Figure 1

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.

dev_model_plib.png
Figure 2

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:


Prerequisites


Hardware

SAM9X60-EK Evaluation Kit

sam9x60-ek.png
Figure 3

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.

sam9x60_ek_jlink_ob_cdc.png
Figure 4

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.

install_harmony_framework_02.png
Figure 5

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.

2

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

The MPLAB Harmony 3 Content Manager window will open:

install_harmony_framework_02.png
Figure 6

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.

5

Click on the Select Category dropdown arrow and select csp_apps_sam_9x60.

This will filter the display to show only the CSP application programs for the SAM9X60.

mhcm_app_browser_csp_apps_sam_9x60.png
Figure 7

6

Scroll down to the bottom of the list and check the box next to csp_apps_sam_9x60\apps\pwm\pwm_channels\firmware\sam_9x60_ek.X.

mhcm_app_browser_csp_apps_sam_9x60_copy.png
Figure 8

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_csp_apps_sam_9x60_copy_destination.png
Figure 9

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.

2

Create a new project by clicking on the New Project icon or select File > New Project…

A New Project window will open.

h3_new_project_1c.png
Figure 10
h3_new_project_1.png
Figure 11

3

From the New Project window, Step 1. Choose Project:

a

Select Categories: Microchip Embedded.

b

Select Projects: 32-bit MPLAB Harmony 3 Project.

c

Click on the Next button.

h3_new_project_2.png
Figure 12

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.

h3_new_project_3a.png
Figure 13

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.

h3_new_project_3.1a.png
Figure 14

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.

h3_new_project_3.2a.png
Figure 15

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.

h3_new_project_3.3a.png
Figure 16

As you may have noticed, we are using blink_RGB_LED for three things:

  1. The location of the project files,
  2. the name of the MPLAB X IDE project folder, and
  3. the project name.

b

Click on the Next button.

6

From the New Project window, Step 4. Configuration Settings:

a

Enter the name of the configuration: blink_RGB_LED.

h3_new_project_5a.png
Figure 17

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.

a

Click on the Launch button to continue loading the Harmony 3 Configurator.

h3_new_project_6.png
Figure 18

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.

1

After a few seconds, the Harmony 3 Configurator window will open. Observe the Project Graph pane in the top center of the window. The Device Family Pack (DFP) and System libraries have been automatically added to the blink_RGB_LED project.

configure_H3_01.png
Figure 19

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.

c

Drag the PWM peripheral to the Project Graph pane in the top center of the window.

configure_H3_02b.png
Figure 20

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:

configure_H3_03a.png
Figure 21

From the SAM9X60-EK user guide, we can see that PB11 controls the red LED.

configure_H3_04.png
Figure 22
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.

configure_H3_06.png
Figure 23

The Pin Configuration window provides three different views:

  1. Pin Settings (which can be ordered by Pins or Ports)
  2. Pin Table
  3. 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.

d

Click on the Available drop-down box and select PWM_PWM0.

configure_H3_07.png
Figure 24

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.

a

In the Project Graph pane, select the PWM Peripheral Library icon. Observe the icon outline turns green and the Configuration Options pane on the right displays the PWM configuration menu.

configure_H3_08.png
Figure 25

b

Expand Clock A Configurations:

  1. Click on the Enable Clock box.
  2. Select Master Clock divided by 512 from the Prescaler drop-down menu.
  3. 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:

  1. Click on the Enable box.
  2. Select Clock A from the Prescaler drop-down menu.
  3. Select Center aligned from the Alignment drop down menu.
  4. Select Waveform starts at high level from the Polarity drop-down menu.
  5. Enter 500 in the Period Count box.
  6. Enter 250 in the Duty Cycle Count box.
configure_H3_05.png
Figure 26

5

Save your configuration by clicking on the Save icon or selecting File > Save Configuration from the menu bar. Observe the asterisk after the project name goes away indicating the project configuration has been saved.

configure_H3_08c.png
Figure 27

6

Generate source code by selecting the Generate Code icon or selecting Generate > Generate Code from the menu bar. A Generate Project window will open.

configure_H3_08d.png
Figure 28

7

Click on the Generate button. A Generating Project window will open and display a progress bar. When completed the window will close.

configure_H3_09.png
Figure 29

8

Close (exit) the MPLAB Harmony 3 Configurator.

9

Observe the Projects tab in MPLAB X IDE. Expand the menu items to view the source code files generated by the MPLAB Harmony 3 Configurator.

configure_H3_10.png
Figure 30

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.

11

Observe the blink_RGB_LEDDashboard and Output panes in MPLAB X IDE.

You may observe some configuration and warning messages in the Output and Dashboard panes. Not to worry, you will configure MPLAB X IDE for the blink_LED_RGB project in the next section.

configure_H3_11a.png
Figure 31
configure_H3_11b.png
Figure 32

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.

1

Open the blink_RGB_LED project properties by clicking on the Project Properties icon in the Dashboard pane or by right-clicking on the blink_RGB_LED in the Projects tab. Select Properties. A Project Properties – blink_RGB_LED window will open.

configure_IDE_01a.png
Figure 33

2

In the Project Properties – blink_RGB_LED window:

configure_IDE_02.png
Figure 34

a

In the Packs box, select the latest version of the SAM9X60 Device Family Pack (DFP).

b

In the Compiler Toolchain box, expand the XC32 menu and select the latest version of the MPLAB XC32 compiler.

configure_IDE_03.png
Figure 35

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.

e

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

configure_IDE_04.png
Figure 36

f

In the Option categories drop-down menu, select Communication.

configure_IDE_05.png
Figure 37

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.

j

Observe that the ${ProjectDir}\..\at91bootstrap_sam_9x60_ek.X\binaries\at91bootstrap.elf is displayed in the Bootstrap file box .

configure_IDE_06b.png
Figure 38

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.

configure_IDE_07c.png
Figure 39

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:

  1. 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)
  2. 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)
  3. Online as a GitHub Pages file: https://microchip-mplab-harmony.github.io/csp/

1

Open the Chip Support Package documentation. Expand the menu and select SAM9X60 Peripheral Libraries. A listing of each of the PLIBs available for the SAM9X60 is displayed.

write_app_00a.png
Figure 40

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:

  1. Initialize the PWM peripheral,
  2. Enable channel 0, and
  3. 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);

c

Write the application in main.c to start the PWM Channel 0.

Finally, to start PWM Channel 0, we write the function PWM_ChannelsStart() right below the code you wrote to enable PWM Channel 0:

/* Start PWM Channel 0 */
PWM_ChannelsStart(PWM_CHANNEL_0_MASK);
write_app_01.png
Figure 41

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:

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

c

Observe the settings for:

  • Debug Reset @ – Main
  • Debug startup – Halt at Main

In the next step, when you debug the project, MPLAB X IDE will compile the project and download it to the target. With the debug settings listed above, the IDE will reset and halt at the beginning of main.c.

debug_00a.png
Figure 42

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.

debug_01.png
Figure 43

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.

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