PWM HAL

group nrf_pwm_hal

Hardware access layer for managing the Pulse Width Modulation (PWM) peripheral.

Defines

NRF_PWM_HAS_DMA_REG

Symbol indicating whether dedicated DMA register is present.

NRF_PWM_HAS_SHORT_LOOPSDONE_SEQSTART

Symbol indicating whether shorting SEQSTART task with LOOPSDONE event is available.

NRF_PWM_HAS_DMA_TASKS_EVENTS

Symbol indicating whether PWM DMA tasks and events are present.

NRF_PWM_HAS_SEQ_CNT

Symbol indicating whether setting the number of duty cycle values for a sequence is available.

NRF_PWM_INST_GET(idx)

Macro getting pointer to the structure of registers of the PWM peripheral.

Parameters:

  • idx – [in] PWM instance index.

Returns:

Pointer to the structure of registers of the PWM peripheral.

NRF_PWM_PIN_NOT_CONNECTED

This value can be provided as a parameter for the nrf_pwm_pins_set function call to specify that a given output channel shall not be connected to a physical pin.

NRF_PWM_CHANNEL_COUNT

Number of channels in each PWM instance.

NRF_PWM_VALUES_LENGTH(array)

Helper macro for calculating the number of 16-bit values in the specified array of duty cycle values.

Typedefs

typedef uint16_t nrf_pwm_values_common_t

Type used for defining duty cycle values for a sequence loaded in NRF_PWM_LOAD_COMMON mode.

Enums

enum nrf_pwm_task_t

PWM tasks.

Values:

enumerator NRF_PWM_TASK_STOP

Stops PWM pulse generation on all channels at the end of the current PWM period, and stops the sequence playback.

enumerator NRF_PWM_TASK_SEQSTART0

Starts playback of sequence 0.

enumerator NRF_PWM_TASK_SEQSTART1

Starts playback of sequence 1.

enumerator NRF_PWM_TASK_NEXTSTEP

Steps by one value in the current sequence if the decoder is set to NRF_PWM_STEP_TRIGGERED mode.

enum nrf_pwm_event_t

PWM events.

Values:

enumerator NRF_PWM_EVENT_STOPPED

Response to STOP task, emitted when PWM pulses are no longer generated.

enumerator NRF_PWM_EVENT_SEQSTARTED0

First PWM period started on sequence 0.

enumerator NRF_PWM_EVENT_SEQSTARTED1

First PWM period started on sequence 1.

enumerator NRF_PWM_EVENT_SEQEND0

Emitted at the end of every sequence 0 when its last value has been read from RAM.

enumerator NRF_PWM_EVENT_SEQEND1

Emitted at the end of every sequence 1 when its last value has been read from RAM.

enumerator NRF_PWM_EVENT_PWMPERIODEND

Emitted at the end of each PWM period.

enumerator NRF_PWM_EVENT_LOOPSDONE

Concatenated sequences have been played the specified number of times.

enum nrf_pwm_int_mask_t

PWM interrupts.

Values:

enumerator NRF_PWM_INT_STOPPED_MASK

Interrupt on STOPPED event.

enumerator NRF_PWM_INT_SEQSTARTED0_MASK

Interrupt on SEQSTARTED[0] event.

enumerator NRF_PWM_INT_SEQSTARTED1_MASK

Interrupt on SEQSTARTED[1] event.

enumerator NRF_PWM_INT_SEQEND0_MASK

Interrupt on SEQEND[0] event.

enumerator NRF_PWM_INT_SEQEND1_MASK

Interrupt on SEQEND[1] event.

enumerator NRF_PWM_INT_PWMPERIODEND_MASK

Interrupt on PWMPERIODEND event.

enumerator NRF_PWM_INT_LOOPSDONE_MASK

Interrupt on LOOPSDONE event.

enum nrf_pwm_short_mask_t

PWM shortcuts.

Values:

enumerator NRF_PWM_SHORT_SEQEND0_STOP_MASK

Shortcut between SEQEND[0] event and STOP task.

enumerator NRF_PWM_SHORT_SEQEND1_STOP_MASK

Shortcut between SEQEND[1] event and STOP task.

enumerator NRF_PWM_SHORT_LOOPSDONE_SEQSTART0_MASK

Shortcut between LOOPSDONE event and SEQSTART[0] task.

enumerator NRF_PWM_SHORT_LOOPSDONE_SEQSTART1_MASK

Shortcut between LOOPSDONE event and SEQSTART[1] task.

enumerator NRF_PWM_SHORT_LOOPSDONE_STOP_MASK

Shortcut between LOOPSDONE event and STOP task.

enum nrf_pwm_mode_t

PWM modes of operation.

Values:

enumerator NRF_PWM_MODE_UP

Up counter (edge-aligned PWM duty cycle).

enumerator NRF_PWM_MODE_UP_AND_DOWN

Up and down counter (center-aligned PWM duty cycle).

enum nrf_pwm_clk_t

PWM base clock frequencies.

Values:

enumerator NRF_PWM_CLK_16MHz

16 MHz / 1 = 16 MHz.

enumerator NRF_PWM_CLK_8MHz

16 MHz / 2 = 8 MHz.

enumerator NRF_PWM_CLK_4MHz

16 MHz / 4 = 4 MHz.

enumerator NRF_PWM_CLK_2MHz

16 MHz / 8 = 2 MHz.

enumerator NRF_PWM_CLK_1MHz

16 MHz / 16 = 1 MHz.

enumerator NRF_PWM_CLK_500kHz

16 MHz / 32 = 500 kHz.

enumerator NRF_PWM_CLK_250kHz

16 MHz / 64 = 250 kHz.

enumerator NRF_PWM_CLK_125kHz

16 MHz / 128 = 125 kHz.

enum nrf_pwm_dec_load_t

PWM decoder load modes.

The selected mode determines how the sequence data is read from RAM and spread to the compare registers.

Values:

enumerator NRF_PWM_LOAD_COMMON

1st half word (16-bit) used in all PWM channels (0-3).

enumerator NRF_PWM_LOAD_GROUPED

1st half word (16-bit) used in channels 0 and 1; 2nd word in channels 2 and 3.

enumerator NRF_PWM_LOAD_INDIVIDUAL

1st half word (16-bit) used in channel 0; 2nd in channel 1; 3rd in channel 2; 4th in channel 3.

enumerator NRF_PWM_LOAD_WAVE_FORM

1st half word (16-bit) used in channel 0; 2nd in channel 1; … ; 4th as the top value for the pulse generator counter.

enum nrf_pwm_dec_step_t

PWM decoder next step modes.

The selected mode determines when the next value from the active sequence is loaded.

Values:

enumerator NRF_PWM_STEP_AUTO

Automatically after the current value is played and repeated the requested number of times.

enumerator NRF_PWM_STEP_TRIGGERED

When the NRF_PWM_TASK_NEXTSTEP task is triggered.

Functions

NRF_STATIC_INLINE void nrf_pwm_task_trigger(NRF_PWM_Type *p_reg, nrf_pwm_task_t task)

Function for activating the specified PWM task.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • task – [in] Task to be activated.

NRF_STATIC_INLINE uint32_t nrf_pwm_task_address_get(NRF_PWM_Type const *p_reg, nrf_pwm_task_t task)

Function for getting the address of the specified PWM task register.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • task – [in] PWM task.

Returns:

Address of the specified task register.

NRF_STATIC_INLINE void nrf_pwm_event_clear(NRF_PWM_Type *p_reg, nrf_pwm_event_t event)

Function for clearing the specified PWM event.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • event – [in] Event to clear.

NRF_STATIC_INLINE bool nrf_pwm_event_check(NRF_PWM_Type const *p_reg, nrf_pwm_event_t event)

Function for retrieving the state of the PWM event.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • event – [in] Event to be checked.

Return values:

  • true – The event has been generated.

  • false – The event has not been generated.

NRF_STATIC_INLINE uint32_t nrf_pwm_event_address_get(NRF_PWM_Type const *p_reg, nrf_pwm_event_t event)

Function for getting the address of the specified PWM event register.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • event – [in] PWM event.

Returns:

Address of the specified event register.

NRF_STATIC_INLINE void nrf_pwm_shorts_enable(NRF_PWM_Type *p_reg, uint32_t mask)

Function for enabling the specified shortcuts.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • mask – [in] Mask of shortcuts to be enabled.

NRF_STATIC_INLINE void nrf_pwm_shorts_disable(NRF_PWM_Type *p_reg, uint32_t mask)

Function for disabling the specified shortcuts.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • mask – [in] Mask of shortcuts to be disabled.

NRF_STATIC_INLINE void nrf_pwm_shorts_set(NRF_PWM_Type *p_reg, uint32_t mask)

Function for setting the configuration of PWM shortcuts.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • mask – [in] Shortcuts configuration to be set.

NRF_STATIC_INLINE void nrf_pwm_int_enable(NRF_PWM_Type *p_reg, uint32_t mask)

Function for enabling specified interrupts.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • mask – [in] Mask of interrupts to be enabled.

NRF_STATIC_INLINE void nrf_pwm_int_disable(NRF_PWM_Type *p_reg, uint32_t mask)

Function for disabling specified interrupts.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • mask – [in] Mask of interrupts to be disabled.

NRF_STATIC_INLINE void nrf_pwm_int_set(NRF_PWM_Type *p_reg, uint32_t mask)

Function for setting the configuration of PWM interrupts.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • mask – [in] Mask of interrupts to be set.

NRF_STATIC_INLINE uint32_t nrf_pwm_int_enable_check(NRF_PWM_Type const *p_reg, uint32_t mask)

Function for checking if the specified interrupts are enabled.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • mask – [in] Mask of interrupts to be checked.

Returns:

Mask of enabled interrupts.

NRF_STATIC_INLINE void nrf_pwm_subscribe_set(NRF_PWM_Type *p_reg, nrf_pwm_task_t task, uint8_t channel)

Function for setting the subscribe configuration for a given PWM task.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • task – [in] Task for which to set the configuration.

  • channel – [in] Channel through which to subscribe events.

NRF_STATIC_INLINE void nrf_pwm_subscribe_clear(NRF_PWM_Type *p_reg, nrf_pwm_task_t task)

Function for clearing the subscribe configuration for a given PWM task.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • task – [in] Task for which to clear the configuration.

NRF_STATIC_INLINE void nrf_pwm_publish_set(NRF_PWM_Type *p_reg, nrf_pwm_event_t event, uint8_t channel)

Function for setting the publish configuration for a given PWM event.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • event – [in] Event for which to set the configuration.

  • channel – [in] Channel through which to publish the event.

NRF_STATIC_INLINE void nrf_pwm_publish_clear(NRF_PWM_Type *p_reg, nrf_pwm_event_t event)

Function for clearing the publish configuration for a given PWM event.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • event – [in] Event for which to clear the configuration.

NRF_STATIC_INLINE void nrf_pwm_enable(NRF_PWM_Type *p_reg)

Function for enabling the PWM peripheral.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

NRF_STATIC_INLINE void nrf_pwm_disable(NRF_PWM_Type *p_reg)

Function for disabling the PWM peripheral.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

NRF_STATIC_INLINE void nrf_pwm_pins_set(NRF_PWM_Type *p_reg, uint32_t const out_pins[4])

Function for assigning pins to PWM output channels.

Usage of all PWM output channels is optional. If a given channel is not needed, pass the NRF_PWM_PIN_NOT_CONNECTED value instead of its pin number.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • out_pins – [in] Array with pin numbers for individual PWM output channels.

NRF_STATIC_INLINE uint32_t nrf_pwm_pin_get(NRF_PWM_Type const *p_reg, uint8_t channel)

Function for getting pin selection associated with specified PWM output channel.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • channel – [in] PWM output channel.

Returns:

Pin selection associated with specified PWM output channel.

NRF_STATIC_INLINE void nrf_pwm_configure(NRF_PWM_Type *p_reg, nrf_pwm_clk_t base_clock, nrf_pwm_mode_t mode, uint16_t top_value)

Function for configuring the PWM peripheral.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • base_clock – [in] Base clock frequency.

  • mode – [in] Operating mode of the pulse generator counter.

  • top_value – [in] Value up to which the pulse generator counter counts.

NRF_STATIC_INLINE void nrf_pwm_sequence_set(NRF_PWM_Type *p_reg, uint8_t seq_id, nrf_pwm_sequence_t const *p_seq)

Function for defining a sequence of PWM duty cycles.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • seq_id – [in] Identifier of the sequence (0 or 1).

  • p_seq – [in] Pointer to the sequence definition.

NRF_STATIC_INLINE void nrf_pwm_seq_ptr_set(NRF_PWM_Type *p_reg, uint8_t seq_id, uint16_t const *p_values)

Function for modifying the pointer to the duty cycle values in the specified sequence.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • seq_id – [in] Identifier of the sequence (0 or 1).

  • p_values – [in] Pointer to an array with duty cycle values.

NRF_STATIC_INLINE void nrf_pwm_seq_cnt_set(NRF_PWM_Type *p_reg, uint8_t seq_id, uint16_t length)

Function for modifying the total number of duty cycle values in the specified sequence.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • seq_id – [in] Identifier of the sequence (0 or 1).

  • length – [in] Number of duty cycle values.

NRF_STATIC_INLINE void nrf_pwm_seq_refresh_set(NRF_PWM_Type *p_reg, uint8_t seq_id, uint32_t refresh)

Function for modifying the additional number of PWM periods spent on each duty cycle value in the specified sequence.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • seq_id – [in] Identifier of the sequence (0 or 1).

  • refresh – [in] Number of additional PWM periods for each duty cycle value.

NRF_STATIC_INLINE void nrf_pwm_seq_end_delay_set(NRF_PWM_Type *p_reg, uint8_t seq_id, uint32_t end_delay)

Function for modifying the additional time added after the sequence is played.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • seq_id – [in] Identifier of the sequence (0 or 1).

  • end_delay – [in] Number of PWM periods added at the end of the sequence.

NRF_STATIC_INLINE void nrf_pwm_decoder_set(NRF_PWM_Type *p_reg, nrf_pwm_dec_load_t dec_load, nrf_pwm_dec_step_t dec_step)

Function for setting the mode of loading sequence data from RAM and advancing the sequence.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • dec_load – [in] Mode of loading sequence data from RAM.

  • dec_step – [in] Mode of advancing the active sequence.

NRF_STATIC_INLINE void nrf_pwm_loop_set(NRF_PWM_Type *p_reg, uint16_t loop_count)

Function for setting the number of times the sequence playback should be performed.

This function applies to two-sequence playback (concatenated sequence 0 and 1). A single sequence can be played back only once.

Parameters:

  • p_reg – [in] Pointer to the structure of registers of the peripheral.

  • loop_count – [in] Number of times to perform the sequence playback.

NRF_STATIC_INLINE nrf_pwm_task_t nrf_pwm_seqstart_task_get(uint8_t seq_id)

Function for getting the specified PWM SEQSTART task.

Parameters:

  • seq_id – [in] Sequence index.

Returns:

The specified PWM SEQSTART task.

NRF_STATIC_INLINE nrf_pwm_event_t nrf_pwm_seqend_event_get(uint8_t seq_id)

Function for getting the specified PWM SEQEND event.

Parameters:

  • seq_id – [in] Sequence index.

Returns:

The specified PWM SEQEND event.

struct nrf_pwm_values_grouped_t
#include <nrf_pwm.h>

Structure for defining duty cycle values for a sequence loaded in NRF_PWM_LOAD_GROUPED mode.

Public Members

uint16_t group_0

Duty cycle value for group 0 (channels 0 and 1).

uint16_t group_1

Duty cycle value for group 1 (channels 2 and 3).

struct nrf_pwm_values_individual_t
#include <nrf_pwm.h>

Structure for defining duty cycle values for a sequence loaded in NRF_PWM_LOAD_INDIVIDUAL mode.

Public Members

uint16_t channel_0

Duty cycle value for channel 0.

uint16_t channel_1

Duty cycle value for channel 1.

uint16_t channel_2

Duty cycle value for channel 2.

uint16_t channel_3

Duty cycle value for channel 3.

struct nrf_pwm_values_wave_form_t
#include <nrf_pwm.h>

Structure for defining duty cycle values for a sequence loaded in NRF_PWM_LOAD_WAVE_FORM mode.

Public Members

uint16_t channel_0

Duty cycle value for channel 0.

uint16_t channel_1

Duty cycle value for channel 1.

uint16_t channel_2

Duty cycle value for channel 2.

uint16_t counter_top

Top value for the pulse generator counter.

union nrf_pwm_values_t
#include <nrf_pwm.h>

Union grouping pointers to arrays of duty cycle values applicable to various loading modes.

Public Members

nrf_pwm_values_common_t const *p_common

Pointer to be used in NRF_PWM_LOAD_COMMON mode.

nrf_pwm_values_grouped_t const *p_grouped

Pointer to be used in NRF_PWM_LOAD_GROUPED mode.

nrf_pwm_values_individual_t const *p_individual

Pointer to be used in NRF_PWM_LOAD_INDIVIDUAL mode.

nrf_pwm_values_wave_form_t const *p_wave_form

Pointer to be used in NRF_PWM_LOAD_WAVE_FORM mode.

uint16_t const *p_raw

Pointer providing raw access to the values.

struct nrf_pwm_sequence_t
#include <nrf_pwm.h>

Structure for defining a sequence of PWM duty cycles.

When the sequence is set (by a call to nrf_pwm_sequence_set), the provided duty cycle values are not copied. The values pointer is stored in the internal register of the peripheral, and the values are loaded from RAM during the sequence playback. Therefore, you must ensure that the values do not change before and during the sequence playback (for example, the values cannot be placed in a local variable that is allocated on stack). If the sequence is played in a loop and the values are to be updated before the next iteration, it is safe to modify them when the corresponding event signaling the end of sequence occurs (NRF_PWM_EVENT_SEQEND0 or NRF_PWM_EVENT_SEQEND1, respectively).

Note

The repeats and end_delay values (which are written to the SEQ[n].REFRESH and SEQ[n].ENDDELAY registers in the peripheral, respectively) are ignored at the end of a complex sequence playback, indicated by the LOOPSDONE event. See the Product Specification for more information.

Public Members

nrf_pwm_values_t values

Pointer to an array with duty cycle values. This array must be in Data RAM.

This field is defined as an union of pointers to provide a convenient way to define duty cycle values in various loading modes (see nrf_pwm_dec_load_t). In each value, the most significant bit (15) determines the polarity of the output and the others (14-0) compose the 15-bit value to be compared with the pulse generator counter.

uint16_t length

Number of 16-bit values in the array pointed by values.

uint32_t repeats

Number of times that each duty cycle is to be repeated (after being played once). Ignored in NRF_PWM_STEP_TRIGGERED mode.

uint32_t end_delay

Additional time (in PWM periods) that the last duty cycle is to be kept after the sequence is played. Ignored in NRF_PWM_STEP_TRIGGERED mode.