| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Low-power PWM library

The low-power pulse-width modulation (PWM) library provides functions to generate a pulse-width modulated output signal while using minimal power. The signal can be used, for example, to change the intensity or the color of LEDs.

Key features include:

- Any number of independent PWM instances.
- One output channel per instance that can control multiple pins.
- Minimal power usage.
- Configurable per-instance polarity and period.

This library uses an application timer and is therefore not very accurate. It can be used to control, for example, LEDs, but for peripherals that need a high accuracy, you should use the PWM library instead.

# Generating a low-power PWM signal

Complete the following steps to generate a low-power PWM signal:

1. For each instance, create a low_power_pwm_t structure.
2. For each instance, create a low_power_pwm_config_t structure that holds the configuration parameters. If you want to use the default configuration, call the LOW_POWER_PWM_DEFAULT_CONFIG macro with the pin mask to fill the init structure.
   The following parameters must be specified:
   - active_high: Polarity.
   - period: Period of app_timer in ticks.
   - bit_mask: Mask of used pins.
3. If required, provide a callback function (see app_timer_timeout_handler_t) that will be executed in the time-out handler.
4. Initialize each instance using the low_power_pwm_init function, with pointers to the instance, the configuration structure, and optionally the callback function as parameters. The function will return NRF_SUCCESS on success or an error code on failure. Initialization will fail if the instance was already initialized or if an invalid configuration was provided.
5. Call low_power_pwm_duty_set to set the duty cycle of a given instance. You can change the duty cycle later by calling low_power_pwm_duty_set again, for example from the PWM callback function.
6. Call low_power_pwm_start to start the timers of a given instance.

The following code example shows how to initialize and start a low-power PWM instance with the default configuration and a given pin mask:

low_power_pwm_t low_power_pwm;
low_power_pwm_config_t low_power_pwm_config = LOW_POWER_PWM_DEFAULT_CONFIG(LEDS_MASK); // use default configuration with given LEDs mask
low_power_pwm_init((&low_power_pwm), &low_power_pwm_config, pwm_handler);
low_power_pwm_duty_set(&low_power_pwm, 50); // set duty cycle to 50
low_power_pwm_start(&low_power_pwm, LEDS_MASK);

As a result, a PWM signal is generated on the selected output pins.

# Limitations

In the default configuration, the RTC frequency is 32768 Hz. The prescaler must not be greater than 6, therefore the timer cannot be started with less than 5 ticks. This means that the break between time-outs is at least 150 microseconds.

# Example

See the Low-Power PWM Example for a full example that uses the low-power PWM library.

# Usage with a SoftDevice

Low-power PWM uses RTC. Therefore, it is less accurate when used with a SoftDevice.