PWM driver¶

group nrfx_pwm

Pulse Width Modulation (PWM) peripheral driver.

Defines

NRFX_PWM_INSTANCE(id)¶: Macro for creating a PWM driver instance.

NRFX_PWM_PIN_NOT_USED¶: This value can be provided instead of a pin number for any channel to specify that its output is not used and therefore does not need to be connected to a pin.

NRFX_PWM_PIN_INVERTED¶: This value can be added to a pin number to invert its polarity (set idle state = 1).

NRFX_PWM_DEFAULT_CONFIG(_out_0, _out_1, _out_2, _out_3)¶

PWM driver default configuration.

This configuration sets up PWM with the following options:

clock frequency: 1 MHz
count up
top value: 1000 clock ticks
load mode: common
step mode: auto

Parameters

_out_0 – [in] PWM output 0 pin.
_out_1 – [in] PWM output 1 pin.
_out_2 – [in] PWM output 2 pin.
_out_3 – [in] PWM output 3 pin.

Typedefs

typedef void (*nrfx_pwm_handler_t)(nrfx_pwm_evt_type_t event_type, void *p_context)¶: PWM driver event handler type.

Enums

enum nrfx_pwm_flag_t¶

PWM flags providing additional playback options.

Values:

enumerator NRFX_PWM_FLAG_STOP¶: When the requested playback is finished, the peripheral will be stopped.

Note

The STOP task is triggered when the last value of the final sequence is loaded from RAM, and the peripheral stops at the end of the current PWM period. For sequences with configured repeating of duty cycle values, this might result in less than the requested number of repeats of the last value.

enumerator NRFX_PWM_FLAG_LOOP¶: When the requested playback is finished, it will be started from the beginning. This flag is ignored if used together with NRFX_PWM_FLAG_STOP.

Note

The playback restart is done via a shortcut configured in the PWM peripheral. This shortcut triggers the proper starting task when the final value of previous playback is read from RAM and applied to the pulse generator counter. When this mechanism is used together with the NRF_PWM_STEP_TRIGGERED mode, the playback restart will occur right after switching to the final value (this final value will be played only once).

enumerator NRFX_PWM_FLAG_SIGNAL_END_SEQ0¶: The event handler is to be called when the last value from sequence 0 is loaded.

enumerator NRFX_PWM_FLAG_SIGNAL_END_SEQ1¶: The event handler is to be called when the last value from sequence 1 is loaded.

enumerator NRFX_PWM_FLAG_NO_EVT_FINISHED¶: The playback finished event (enabled by default) is to be suppressed.

enumerator NRFX_PWM_FLAG_START_VIA_TASK¶: The playback must not be started directly by the called function. Instead, the function must only prepare it and return the address of the task to be triggered to start the playback.

enum nrfx_pwm_evt_type_t¶

PWM driver event type.

Values:

enumerator NRFX_PWM_EVT_FINISHED¶: Sequence playback finished.

enumerator NRFX_PWM_EVT_END_SEQ0¶: End of sequence 0 reached. Its data can be safely modified now.

enumerator NRFX_PWM_EVT_END_SEQ1¶: End of sequence 1 reached. Its data can be safely modified now.

enumerator NRFX_PWM_EVT_STOPPED¶: The PWM peripheral has been stopped.

Functions

nrfx_err_t nrfx_pwm_init(nrfx_pwm_t const *p_instance, nrfx_pwm_config_t const *p_config, nrfx_pwm_handler_t handler, void *p_context)¶

Function for initializing the PWM driver.

Parameters

p_instance – [in] Pointer to the driver instance structure.
p_config – [in] Pointer to the structure with the initial configuration.
handler – [in] Event handler provided by the user. If NULL is passed instead, event notifications are not done and PWM interrupts are disabled.
p_context – [in] Context passed to the event handler.

Returns NRFX_SUCCESS

Initialization was successful.

Returns NRFX_ERROR_INVALID_STATE

The driver was already initialized.

void nrfx_pwm_uninit(nrfx_pwm_t const *p_instance)¶

Function for uninitializing the PWM driver.

If any sequence playback is in progress, it is stopped immediately.

Parameters

p_instance – [in] Pointer to the driver instance structure.

uint32_t nrfx_pwm_simple_playback(nrfx_pwm_t const *p_instance, nrf_pwm_sequence_t const *p_sequence, uint16_t playback_count, uint32_t flags)¶

Function for starting a single sequence playback.

To take advantage of the looping mechanism in the PWM peripheral, both sequences must be used (single sequence can be played back only once by the peripheral). Therefore, the provided sequence is internally set and played back as both sequence 0 and sequence 1. Consequently, if the end of sequence notifications are required, events for both sequences must be used (that is, both the NRFX_PWM_FLAG_SIGNAL_END_SEQ0 flag and the NRFX_PWM_FLAG_SIGNAL_END_SEQ1 flag must be specified, and the NRFX_PWM_EVT_END_SEQ0 event and the NRFX_PWM_EVT_END_SEQ1 event must be handled in the same way).

Use the NRFX_PWM_FLAG_START_VIA_TASK flag if you want the playback to be only prepared by this function, and you want to start it later by triggering a task (for example, by using PPI). The function will then return the address of the task to be triggered.

Note

The array containing the duty cycle values for the specified sequence must be in RAM and cannot be allocated on the stack. For detailed information, see nrf_pwm_sequence_t.

Parameters

p_instance – [in] Pointer to the driver instance structure.
p_sequence – [in] Sequence to be played back.
playback_count – [in] Number of playbacks to be performed (must not be 0).
flags – [in] Additional options. Pass any combination of playback flags, or 0 for default settings.

Returns

Address of the task to be triggered to start the playback if the NRFX_PWM_FLAG_START_VIA_TASK flag was used, 0 otherwise.

uint32_t nrfx_pwm_complex_playback(nrfx_pwm_t const *p_instance, nrf_pwm_sequence_t const *p_sequence_0, nrf_pwm_sequence_t const *p_sequence_1, uint16_t playback_count, uint32_t flags)¶

Function for starting a two-sequence playback.

Use the NRFX_PWM_FLAG_START_VIA_TASK flag if you want the playback to be only prepared by this function, and you want to start it later by triggering a task (using PPI for instance). The function will then return the address of the task to be triggered.

Note

The array containing the duty cycle values for the specified sequence must be in RAM and cannot be allocated on the stack. For detailed information, see nrf_pwm_sequence_t.

Parameters

p_instance – [in] Pointer to the driver instance structure.
p_sequence_0 – [in] First sequence to be played back.
p_sequence_1 – [in] Second sequence to be played back.
playback_count – [in] Number of playbacks to be performed (must not be 0).
flags – [in] Additional options. Pass any combination of playback flags, or 0 for default settings.

Returns

Address of the task to be triggered to start the playback if the NRFX_PWM_FLAG_START_VIA_TASK flag was used, 0 otherwise.

NRFX_STATIC_INLINE void nrfx_pwm_step(nrfx_pwm_t const *p_instance)¶

Function for advancing the active sequence.

This function only applies to NRF_PWM_STEP_TRIGGERED mode.

Parameters

p_instance – [in] Pointer to the driver instance structure.

bool nrfx_pwm_stop(nrfx_pwm_t const *p_instance, bool wait_until_stopped)¶

Function for stopping the sequence playback.

The playback is stopped at the end of the current PWM period. This means that if the active sequence is configured to repeat each duty cycle value for a certain number of PWM periods, the last played value might appear on the output less times than requested.

Note

This function can be instructed to wait until the playback is stopped (by setting wait_until_stopped to true). Depending on the length of the PMW period, this might take a significant amount of time. Alternatively, the nrfx_pwm_is_stopped function can be used to poll the status, or the NRFX_PWM_EVT_STOPPED event can be used to get the notification when the playback is stopped, provided the event handler is defined.

Parameters

p_instance – [in] Pointer to the driver instance structure.
wait_until_stopped – [in] If true, the function will not return until the playback is stopped.

Returns true

The PWM peripheral is stopped.

Returns false

The PWM peripheral is not stopped.

bool nrfx_pwm_is_stopped(nrfx_pwm_t const *p_instance)¶

Function for checking the status of the PWM peripheral.

Parameters

p_instance – [in] Pointer to the driver instance structure.

Returns true

The PWM peripheral is stopped.

Returns false

The PWM peripheral is not stopped.

NRFX_STATIC_INLINE void nrfx_pwm_sequence_update(nrfx_pwm_t const *p_instance, uint8_t seq_id, nrf_pwm_sequence_t const *p_sequence)¶

Function for updating the sequence data during playback.

Parameters

p_instance – [in] Pointer to the driver instance structure.
seq_id – [in] Identifier of the sequence (0 or 1).
p_sequence – [in] Pointer to the new sequence definition.

NRFX_STATIC_INLINE void nrfx_pwm_sequence_values_update(nrfx_pwm_t const *p_instance, uint8_t seq_id, nrf_pwm_values_t values)¶

Function for updating the pointer to the duty cycle values in the specified sequence during playback.

Parameters

p_instance – [in] Pointer to the driver instance structure.
seq_id – [in] Identifier of the sequence (0 or 1).
values – [in] New pointer to the duty cycle values.

NRFX_STATIC_INLINE void nrfx_pwm_sequence_length_update(nrfx_pwm_t const *p_instance, uint8_t seq_id, uint16_t length)¶

Function for updating the number of duty cycle values in the specified sequence during playback.

Parameters

p_instance – [in] Pointer to the driver instance structure.
seq_id – [in] Identifier of the sequence (0 or 1).
length – [in] New number of the duty cycle values.

NRFX_STATIC_INLINE void nrfx_pwm_sequence_repeats_update(nrfx_pwm_t const *p_instance, uint8_t seq_id, uint32_t repeats)¶

Function for updating the number of repeats for duty cycle values in the specified sequence during playback.

Parameters

p_instance – [in] Pointer to the driver instance structure.
seq_id – [in] Identifier of the sequence (0 or 1).
repeats – [in] New number of repeats.

NRFX_STATIC_INLINE void nrfx_pwm_sequence_end_delay_update(nrfx_pwm_t const *p_instance, uint8_t seq_id, uint32_t end_delay)¶

Function for updating the additional delay after the specified sequence during playback.

Parameters

p_instance – [in] Pointer to the driver instance structure.
seq_id – [in] Identifier of the sequence (0 or 1).
end_delay – [in] New end delay value (in PWM periods).

NRFX_STATIC_INLINE uint32_t nrfx_pwm_task_address_get(nrfx_pwm_t const *p_instance, nrf_pwm_task_t task)¶

Function for returning the address of a specified PWM task that can be used in PPI module.

Parameters

p_instance – [in] Pointer to the driver instance structure.
task – [in] Requested task.

Returns

Task address.

NRFX_STATIC_INLINE uint32_t nrfx_pwm_event_address_get(nrfx_pwm_t const *p_instance, nrf_pwm_event_t event)¶

Function for returning the address of a specified PWM event that can be used in PPI module.

Parameters

p_instance – [in] Pointer to the driver instance structure.
event – [in] Requested event.

Returns

Event address.

struct nrfx_pwm_t¶

#include <nrfx_pwm.h>

PWM driver instance data structure.

Public Members

NRF_PWM_Type *p_registers¶: Pointer to the structure with PWM peripheral instance registers.

uint8_t drv_inst_idx¶: Index of the driver instance. For internal use only.

struct nrfx_pwm_config_t¶

#include <nrfx_pwm.h>

PWM driver configuration structure.

Public Members

uint8_t output_pins[NRF_PWM_CHANNEL_COUNT]¶

Pin numbers for individual output channels (optional).

Use NRFX_PWM_PIN_NOT_USED if a given output channel is not needed.

uint8_t irq_priority¶: Interrupt priority.

nrf_pwm_clk_t base_clock¶: Base clock frequency.

nrf_pwm_mode_t count_mode¶: Operating mode of the pulse generator counter.

uint16_t top_value¶: Value up to which the pulse generator counter counts.

nrf_pwm_dec_load_t load_mode¶: Mode of loading sequence data from RAM.

nrf_pwm_dec_step_t step_mode¶: Mode of advancing the active sequence.

bool skip_gpio_cfg¶

Skip the GPIO configuration.

When this flag is set, the user is responsible for providing the proper configuration of the output pins, as the driver does not touch it at all.