| 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
Pulse-width modulation (PWM)
SDK common libraries

Module for generating a pulse-width modulated output signal. More...

## Modules
| PWM functionality configuration

## Data Structures
struct | app_pwm_config_t
| PWM configuration structure used for initialization. More...
struct | app_pwm_t
| PWM instance structure. More...

## Macros
#define | APP_PWM_NOPIN 0xFFFFFFFF
#define | APP_PWM_CHANNELS_PER_INSTANCE 2
| Number of channels for one timer instance (fixed to 2 due to timer properties).
#define | APP_PWM_INSTANCE(name, num)
| Macro for creating a PWM instance. More...
#define | APP_PWM_DEFAULT_CONFIG_1CH(period_in_us, pin)
| PWM instance default configuration (1 channel). More...
#define | APP_PWM_DEFAULT_CONFIG_2CH(period_in_us, pin0, pin1)
| PWM instance default configuration (2 channels). More...

## Typedefs
typedef uint16_t | app_pwm_duty_t
typedef void(* | app_pwm_callback_t )(uint32_t)
| PWM callback that is executed when a PWM duty change has been completed. More...

## Enumerations
enum | app_pwm_polarity_t { APP_PWM_POLARITY_ACTIVE_LOW = 0, APP_PWM_POLARITY_ACTIVE_HIGH = 1 }
| Channel polarity.

## Functions
bool | app_pwm_busy_check (app_pwm_t const *const p_instance)
| Function for checking if the PWM instance is busy updating the duty cycle. More...
ret_code_t | app_pwm_init (app_pwm_t const *const p_instance, app_pwm_config_t const *const p_config, app_pwm_callback_t p_ready_callback)
| Function for initializing a PWM instance. More...
ret_code_t | app_pwm_uninit (app_pwm_t const *const p_instance)
| Function for uninitializing a PWM instance and releasing the allocated resources. More...
void | app_pwm_enable (app_pwm_t const *const p_instance)
| Function for enabling a PWM instance after initialization. More...
void | app_pwm_disable (app_pwm_t const *const p_instance)
| Function for disabling a PWM instance after initialization. More...
ret_code_t | app_pwm_channel_duty_set (app_pwm_t const *const p_instance, uint8_t channel, app_pwm_duty_t duty)
| Function for setting the PWM channel duty cycle in percents. More...
app_pwm_duty_t | app_pwm_channel_duty_get (app_pwm_t const *const p_instance, uint8_t channel)
| Function for retrieving the PWM channel duty cycle in percents. More...

## Functions accessing values in ticks
Auxiliary functions that allow to get values in actual timer ticks.
ret_code_t | app_pwm_channel_duty_ticks_set (app_pwm_t const *const p_instance, uint8_t channel, uint16_t ticks)
| Function for setting PWM channel duty cycle in clock ticks. More...
uint16_t | app_pwm_channel_duty_ticks_get (app_pwm_t const *const p_instance, uint8_t channel)
| Function for retrieving the PWM channel duty cycle in ticks. More...
uint16_t | app_pwm_cycle_ticks_get (app_pwm_t const *const p_instance)
| Function for returning the number of ticks in a whole cycle. More...

## Detailed Description

Module for generating a pulse-width modulated output signal.

This module provides a PWM implementation using timers, GPIOTE, and PPI.

Resource usage:

- 2 PPI channels per instance + 2 PPI channels per PWM channel.
- 1 PPI group per instance.
- 1 GPIOTE channel per PWM channel.

For example, a PWM instance with two channels will consume 2 + 4 PPI channels, 1 PPI group, and 2 GPIOTE channels.

The maximum number of PWM channels per instance is 2.

## Macro Definition Documentation

#define APP_PWM_DEFAULT_CONFIG_1CH | ( |  | period_in_us,
|  |  | pin
| ) |  |

Value:
{ \
.pins = {pin, APP_PWM_NOPIN}, \
.pin_polarity = {APP_PWM_POLARITY_ACTIVE_LOW, APP_PWM_POLARITY_ACTIVE_LOW}, \
.num_of_channels = 1, \
.period_us = period_in_us \
}

PWM instance default configuration (1 channel).

#define APP_PWM_DEFAULT_CONFIG_2CH | ( |  | period_in_us,
|  |  | pin0,
|  |  | pin1
| ) |  |

Value:
{ \
.pins = {pin0, pin1}, \
.pin_polarity = {APP_PWM_POLARITY_ACTIVE_LOW, APP_PWM_POLARITY_ACTIVE_LOW}, \
.num_of_channels = 2, \
.period_us = period_in_us \
}

PWM instance default configuration (2 channels).

#define APP_PWM_INSTANCE | ( |  | name,
|  |  | num
| ) |  |

Value:
const nrf_drv_timer_t m_pwm_##name##_timer = NRF_DRV_TIMER_INSTANCE(num); \
app_pwm_cb_t m_pwm_##name##_cb; \
/*lint -e{545}*/ \
const app_pwm_t name = { \
.p_cb = &m_pwm_##name##_cb, \
.p_timer = &m_pwm_##name##_timer, \
}

Macro for creating a PWM instance.

## Typedef Documentation

typedef void(* app_pwm_callback_t)(uint32_t)

PWM callback that is executed when a PWM duty change has been completed.

Parameters

  [in] | pwm_id | PWM instance ID.

## Function Documentation

bool app_pwm_busy_check | ( | app_pwm_t const *const | p_instance | ) |

Function for checking if the PWM instance is busy updating the duty cycle.

Parameters

  [in] | p_instance | PWM instance.

Return values

  True | If the PWM instance is ready for duty cycle changes.
  False | If a change operation is in progress.

app_pwm_duty_t app_pwm_channel_duty_get | ( | app_pwm_t const *const | p_instance,
|  | uint8_t | channel
| ) |  |

Function for retrieving the PWM channel duty cycle in percents.

Parameters

  [in] | p_instance | PWM instance.
  [in] | channel | Channel number.

Returns
  Duty cycle value.

ret_code_t app_pwm_channel_duty_set | ( | app_pwm_t const *const | p_instance,
|  | uint8_t | channel,
|  | app_pwm_duty_t | duty
| ) |  |

Function for setting the PWM channel duty cycle in percents.

A duty cycle change requires one full PWM clock period to finish. If another change is attempted for any channel of given instance before the current change is complete, the new attempt will result in the error NRF_ERROR_BUSY.

Parameters

  [in] | p_instance | PWM instance.
  [in] | channel | Channel number.
  [in] | duty | Duty cycle (0 - 100).

Return values

  NRF_SUCCESS | If the operation was successful.
  NRF_ERROR_BUSY | If the PWM is not ready yet.
  NRF_ERROR_INVALID_STATE | If the given instance was not initialized.

uint16_t app_pwm_channel_duty_ticks_get | ( | app_pwm_t const *const | p_instance,
|  | uint8_t | channel
| ) |  |

Function for retrieving the PWM channel duty cycle in ticks.

This function retrieves the real, currently set duty cycle in ticks. For one full PWM cycle the value might be different than the value set by the last app_pwm_channel_duty_ticks_set function call.

Parameters

  [in] | p_instance | PWM instance.
  [in] | channel | Channel number.

Returns
  Number of ticks set for selected channel.

ret_code_t app_pwm_channel_duty_ticks_set | ( | app_pwm_t const *const | p_instance,
|  | uint8_t | channel,
|  | uint16_t | ticks
| ) |  |

Function for setting PWM channel duty cycle in clock ticks.

Note
  Duty cycle changes require one full PWM clock period to finish. Until that, the next change attempt (for any channel of given instance) will result in an NRF_ERROR_BUSY error.

Parameters

  [in] | p_instance | PWM instance.
  [in] | channel | Channel number.
  [in] | ticks | Number of PWM clock ticks.

Return values

  NRF_SUCCESS | If the operation was successful.
  NRF_ERROR_BUSY | If PWM is not ready yet.
  NRF_ERROR_INVALID_STATE | If the given instance was not initialized.

uint16_t app_pwm_cycle_ticks_get | ( | app_pwm_t const *const | p_instance | ) |

Function for returning the number of ticks in a whole cycle.

Parameters

  [in] | p_instance | PWM instance.

Returns
  Number of ticks that corresponds to 100% of the duty cycle.

void app_pwm_disable | ( | app_pwm_t const *const | p_instance | ) |

Function for disabling a PWM instance after initialization.

Parameters

  [in] | p_instance | PWM instance.

void app_pwm_enable | ( | app_pwm_t const *const | p_instance | ) |

Function for enabling a PWM instance after initialization.

Parameters

  [in] | p_instance | PWM instance.

ret_code_t app_pwm_init | ( | app_pwm_t const *const | p_instance,
|  | app_pwm_config_t const *const | p_config,
|  | app_pwm_callback_t | p_ready_callback
| ) |  |

Function for initializing a PWM instance.

Parameters

  [in] | p_instance | PWM instance.
  [in] | p_config | Initial configuration.
  [in] | p_ready_callback | Pointer to ready callback function (or NULL to disable).

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_NO_MEM | If there were not enough free resources.
  NRF_ERROR_INVALID_PARAM | If an invalid configuration structure was passed.
  NRF_ERROR_INVALID_STATE | If the timer/PWM is already in use or if initialization failed.

ret_code_t app_pwm_uninit | ( | app_pwm_t const *const | p_instance | ) |

Function for uninitializing a PWM instance and releasing the allocated resources.

Parameters

  [in] | p_instance | PWM instance.

Return values

  NRF_SUCCESS | If uninitialization was successful.
  NRF_ERROR_INVALID_STATE | If the given instance was not initialized.