| 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
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
PWM driver
PWM HAL and driver

nRF52 only: Pulse Width Modulation (PWM) module driver. More...

## Modules
| PWM peripheral driver configuration

## Data Structures
struct | nrf_drv_pwm_t
| PWM driver instance data structure. More...
struct | nrf_drv_pwm_config_t
| PWM driver configuration structure. More...

## Macros
#define | PWM0_INSTANCE_INDEX 0
#define | PWM1_INSTANCE_INDEX PWM0_INSTANCE_INDEX+PWM0_ENABLED
#define | PWM2_INSTANCE_INDEX PWM1_INSTANCE_INDEX+PWM1_ENABLED
#define | NRF_DRV_PWM_INSTANCE(id)
| Macro for creating a PWM driver instance. More...
#define | NRF_DRV_PWM_PIN_NOT_USED 0xFF
| 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.
#define | NRF_DRV_PWM_PIN_INVERTED 0x80
| This value can be added to a pin number to inverse its polarity (set idle state = 1).
#define | NRF_DRV_PWM_DEFAULT_CONFIG
| PWM driver default configuration. More...

## Typedefs
typedef void(* | nrf_drv_pwm_handler_t )(nrf_drv_pwm_evt_type_t event_type)
| PWM driver event handler type.

## Enumerations
enum | nrf_drv_pwm_flag_t { NRF_DRV_PWM_FLAG_STOP = 0x01, NRF_DRV_PWM_FLAG_LOOP = 0x02, NRF_DRV_PWM_FLAG_SIGNAL_END_SEQ0 = 0x04, NRF_DRV_PWM_FLAG_SIGNAL_END_SEQ1 = 0x08, NRF_DRV_PWM_FLAG_NO_EVT_FINISHED = 0x10 }
| PWM flags providing additional playback options. More...
enum | nrf_drv_pwm_evt_type_t { NRF_DRV_PWM_EVT_FINISHED, NRF_DRV_PWM_EVT_END_SEQ0, NRF_DRV_PWM_EVT_END_SEQ1, NRF_DRV_PWM_EVT_STOPPED }
| PWM driver event type. More...

## Functions
ret_code_t | nrf_drv_pwm_init (nrf_drv_pwm_t const *const p_instance, nrf_drv_pwm_config_t const *p_config, nrf_drv_pwm_handler_t handler)
| Function for initializing the PWM driver. More...
void | nrf_drv_pwm_uninit (nrf_drv_pwm_t const *const p_instance)
| Function for uninitializing the PWM driver. More...
void | nrf_drv_pwm_simple_playback (nrf_drv_pwm_t const *const p_instance, nrf_pwm_sequence_t const *p_sequence, uint16_t playback_count, uint32_t flags)
| Function for starting a single sequence playback. More...
void | nrf_drv_pwm_complex_playback (nrf_drv_pwm_t const *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. More...
__STATIC_INLINE void | nrf_drv_pwm_step (nrf_drv_pwm_t const *const p_instance)
| Function for advancing the active sequence. More...
bool | nrf_drv_pwm_stop (nrf_drv_pwm_t const *const p_instance, bool wait_until_stopped)
| Function for stopping the sequence playback. More...
bool | nrf_drv_pwm_is_stopped (nrf_drv_pwm_t const *const p_instance)
| Function for checking the status of the PWM peripheral. More...
__STATIC_INLINE void | nrf_drv_pwm_sequence_update (nrf_drv_pwm_t const *const p_instance, uint8_t seq_id, nrf_pwm_sequence_t const *p_sequence)
| Function for updating the sequence data during playback. More...
__STATIC_INLINE void | nrf_drv_pwm_sequence_values_update (nrf_drv_pwm_t const *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. More...
__STATIC_INLINE void | nrf_drv_pwm_sequence_length_update (nrf_drv_pwm_t const *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. More...
__STATIC_INLINE void | nrf_drv_pwm_sequence_repeats_update (nrf_drv_pwm_t const *const p_instance, uint8_t seq_id, uint32_t repeats)
| Function for updating the number of repeats for duty cycle values in specified sequence during playback. More...
__STATIC_INLINE void | nrf_drv_pwm_sequence_end_delay_update (nrf_drv_pwm_t const *const p_instance, uint8_t seq_id, uint32_t end_delay)
| Function for updating the additional delay after the specified sequence during playback. More...
__STATIC_INLINE uint32_t | nrf_drv_pwm_task_address_get (nrf_drv_pwm_t const *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. More...
__STATIC_INLINE uint32_t | nrf_drv_pwm_event_address_get (nrf_drv_pwm_t const *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. More...

## Detailed Description

nRF52 only: Pulse Width Modulation (PWM) module driver.

## Macro Definition Documentation

#define NRF_DRV_PWM_DEFAULT_CONFIG

Value:
{ \
.output_pins = {PWM_DEFAULT_CONFIG_OUT0_PIN, \
PWM_DEFAULT_CONFIG_OUT1_PIN, \
PWM_DEFAULT_CONFIG_OUT2_PIN, \
PWM_DEFAULT_CONFIG_OUT3_PIN }, \
.irq_priority = PWM_DEFAULT_CONFIG_IRQ_PRIORITY, \
.base_clock = (nrf_pwm_clk_t)PWM_DEFAULT_CONFIG_BASE_CLOCK, \
.count_mode = (nrf_pwm_mode_t)PWM_DEFAULT_CONFIG_COUNT_MODE, \
.top_value = PWM_DEFAULT_CONFIG_TOP_VALUE, \
.load_mode = (nrf_pwm_dec_load_t)PWM_DEFAULT_CONFIG_LOAD_MODE, \
.step_mode = (nrf_pwm_dec_step_t)PWM_DEFAULT_CONFIG_STEP_MODE, \
}

PWM driver default configuration.

#define NRF_DRV_PWM_INSTANCE | ( |  | id | ) |

Value:
{ \
.p_registers = CONCAT_2(NRF_PWM, id), \
.drv_inst_idx = CONCAT_3(PWM, id, _INSTANCE_INDEX), \
}

Macro for creating a PWM driver instance.

## Enumeration Type Documentation

enum nrf_drv_pwm_evt_type_t

PWM driver event type.

Enumerator
NRF_DRV_PWM_EVT_FINISHED | Sequence playback finished.
NRF_DRV_PWM_EVT_END_SEQ0 | End of sequence 0 reached. Its data can be safely modified now.
NRF_DRV_PWM_EVT_END_SEQ1 | End of sequence 1 reached. Its data can be safely modified now.
NRF_DRV_PWM_EVT_STOPPED | The PWM peripheral has been stopped.

enum nrf_drv_pwm_flag_t

PWM flags providing additional playback options.

Enumerator
NRF_DRV_PWM_FLAG_STOP | When the requested playback is finished, the peripheral should 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.
NRF_DRV_PWM_FLAG_LOOP | When the requested playback is finished, it should be started from the beginning. This flag is ignored if used together with NRF_DRV_PWM_FLAG_STOP.
NRF_DRV_PWM_FLAG_SIGNAL_END_SEQ0 | The event handler should be called when the last value from sequence 0 is loaded.
NRF_DRV_PWM_FLAG_SIGNAL_END_SEQ1 | The event handler should be called when the last value from sequence 1 is loaded.
NRF_DRV_PWM_FLAG_NO_EVT_FINISHED | The playback finished event (enabled by default) should be suppressed.

## Function Documentation

void nrf_drv_pwm_complex_playback | ( | nrf_drv_pwm_t const *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.

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

Parameters

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

__STATIC_INLINE uint32_t nrf_drv_pwm_event_address_get | ( | nrf_drv_pwm_t const *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

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

Returns
  Event address.

ret_code_t nrf_drv_pwm_init | ( | nrf_drv_pwm_t const *const | p_instance,
|  | nrf_drv_pwm_config_t const * | p_config,
|  | nrf_drv_pwm_handler_t | handler
| ) |  |

Function for initializing the PWM driver.

Parameters

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

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_INVALID_STATE | If the driver was already initialized.

bool nrf_drv_pwm_is_stopped | ( | nrf_drv_pwm_t const *const | p_instance | ) |

Function for checking the status of the PWM peripheral.

Parameters

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

Return values

  true | If the PWM peripheral is stopped.
  false | If the PWM peripheral is not stopped.

__STATIC_INLINE void nrf_drv_pwm_sequence_end_delay_update | ( | nrf_drv_pwm_t const *const | p_instance,
|  | uint8_t | seq_id,
|  | uint32_t | end_delay
| ) |  |

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

Parameters

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

__STATIC_INLINE void nrf_drv_pwm_sequence_length_update | ( | nrf_drv_pwm_t const *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

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

__STATIC_INLINE void nrf_drv_pwm_sequence_repeats_update | ( | nrf_drv_pwm_t const *const | p_instance,
|  | uint8_t | seq_id,
|  | uint32_t | repeats
| ) |  |

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

Parameters

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

__STATIC_INLINE void nrf_drv_pwm_sequence_update | ( | nrf_drv_pwm_t const *const | p_instance,
|  | uint8_t | seq_id,
|  | nrf_pwm_sequence_t const * | p_sequence
| ) |  |

Function for updating the sequence data during playback.

Parameters

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

__STATIC_INLINE void nrf_drv_pwm_sequence_values_update | ( | nrf_drv_pwm_t const *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

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

void nrf_drv_pwm_simple_playback | ( | nrf_drv_pwm_t const *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 end of sequence notifications are required, events for both sequences should be used (that means that both the NRF_DRV_PWM_FLAG_SIGNAL_END_SEQ0 flag and the NRF_DRV_PWM_FLAG_SIGNAL_END_SEQ1 flag should be specified and the NRF_DRV_PWM_EVT_END_SEQ0 event and the NRF_DRV_PWM_EVT_END_SEQ1 event should be handled in the same way).

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

Parameters

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

__STATIC_INLINE void nrf_drv_pwm_step | ( | nrf_drv_pwm_t const *const | p_instance | ) |

Function for advancing the active sequence.

This function only applies to NRF_PWM_STEP_TRIGGERED mode.

Parameters

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

bool nrf_drv_pwm_stop | ( | nrf_drv_pwm_t const *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). Note that, depending on the length of the PMW period, this might take a significant amount of time. Alternatively, the nrf_drv_pwm_is_stopped function can be used to poll the status, or the NRF_DRV_PWM_EVT_STOPPED event can be used to get the notification when the playback is stopped, provided the event handler is defined.

Parameters

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

Return values

  true | If the PWM peripheral is stopped.
  false | If the PWM peripheral is not stopped.

__STATIC_INLINE uint32_t nrf_drv_pwm_task_address_get | ( | nrf_drv_pwm_t const *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

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

Returns
  Task address.

void nrf_drv_pwm_uninit | ( | nrf_drv_pwm_t const *const | p_instance | ) |

Function for uninitializing the PWM driver.

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

Parameters

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