Use PWMs in high-level applications

  • Article

This topic describes how to access device pulse-width modulators (PWMs) for use in Azure Sphere high-level applications.

Pulse-width modulation is achieved by varying the duty cycle (ratio of on time to off time) of a pulsed digital signal. Pulse-width modulators are used in a wide range of applications such as digital motor control, communication, and digital-to-analog conversion.

To use PWMs in your Azure Sphere applications you must include the required header files and Pwm capability, and specify the controller for the PWM channels that your application will access.

The PWM_HighLevelApp sample demonstrates how to use PWM in a simple digital-to-analog conversion application on an MT3620 device.

PWM requirements

Applications that use PWMs must include the appropriate header file and add PWM settings to the application manifest.

All applications must set their target hardware and include the corresponding hardware definition header file.

Header Files

 #include <applibs/pwm.h>
 #include "path-to-your-target-hardware.h"

Replace "path-to-your-target-hardware.h" with the path to the header file for your hardware.

Application manifest settings

The PWM setting in the application manifest lists the PWM controllers that are accessed by the application. To configure these settings, add the Pwm capability to the application manifest, and then add each PWM controller to the capability. Azure Sphere application manifest has more details.

In your code, use the constants that are defined for your hardware to identify the PWM controllers. The compiler will translate these values to raw values when you build the app.

For example, here's an excerpt from an application manifest for an application that targets an MT3620 reference development board (RDB).

 "Pwm": [ "$MT3620_RDB_LED_PWM_CONTROLLER2" ]

The following excerpt shows how to specify the same PWM controller in an application that targets the Avnet MT3620 Starter Kit:

  "Pwm": [ "$AVNET_MT3620_SK_PWM_CONTROLLER2" ]

PWM access

Azure Sphere high-level applications can access a PWM by calling Applibs PWM APIs.

Open a PWM controller

To open a PWM controller for access, call PWM_Open and pass as a parameter the ID of the controller to open. A file descriptor will be returned if the call is successful. Otherwise, -1 will be returned.

Set the state of a PWM channel

To set or update the state of a PWM channel, call PWM_Apply. You pass the following parameters to PWM_Apply:

  • The file descriptor returned by PWM_Open

  • The PWM channel to update; this value is platform dependent

  • The period, duty cycle, and polarity to apply to the channel

  • Whether to enable or disable the channel

Note

Minimum and maximum limits for period and duty cycle are device dependent. For example, on the MT3620 high-level core, PWMs run at a fixed base frequency of 2 MHz with 16 bit on/off compare registers. This imposes a duty cycle resolution of 500 ns, and an effective maximum period of approximately 32.77 ms. Consult your specific device’s data sheet for details.

MT3620 support

The supported PWM features for the MT3620 are listed in MT3620 Support Status. The MT3620 development board user guide describes the pin layout and pin functions.

The MT3620 has 12 PWM channels, PWM0 - PWM11. They are organized into 3 groups of 4 channels. Each group is associated with a PWM controller (PWM-CONTROLLER-0, PWM-CONTROLLER-1, PWM-CONTROLLER-2). The PWM channels and GPIO pins GPIO0 through GPIO11 map to the same pins on the MT3260. If your application uses a PWM controller then all of the pins associated with that controller are allocated for use as PWM outputs. They can't be used for any other peripheral type.