High level interface for interacting with the pulse width modulator (PWM) hardware resource.
The PWM driver can be used to generate periodic digital waveforms with configurable frequency and duty cycle. The driver allows assigning the PWM output and an optional inverted output to supplied pins. The driver supports interrupt generation on PWM terminal count and compare events.
See Snippet 1: Simple PWM initialization and output to pin for a code snippet that generates a signal with the specified frequency and duty cycle on the specified pin.
The following snippet initializes a PWM resource and assigns the output to the supplied pin using cyhal_pwm_init.
The clock parameter clk is optional and need not be provided (NULL), to generate and use an available clock resource with a default frequency.
The clock frequency and the duty cycle is set using cyhal_pwm_set_duty_cycle.
cyhal_pwm_start starts the PWM output on the pin.
cyhal_pwm_start and cyhal_pwm_stop functions can be used after PWM initialization to start and stop the PWM output.
cyhal_pwm_init_adv can be used to specify advanced PWM options like an additional inverted PWM output, pulse alignment (left, right, center) and run mode (one-shot or continuous). The following snippet initializes a left-aligned, continuous running PWM assigned to the supplied pin. The inverted output is assigned to a second pin (compl_pin).
PWM events like hitting the terminal count or a compare event can be used to trigger a callback function.
cyhal_pwm_enable_event() can be used to enable one or more events to trigger the callback function.
API Reference | |
PWM HAL Results | |
PWM specific return codes. | |
Macros | |
#define | cyhal_pwm_init(obj, pin, clk) (cyhal_pwm_init_adv(obj, pin, NC, CYHAL_PWM_LEFT_ALIGN, true, 0u, false, clk)) |
Initialize the PWM out peripheral and configure the pin This is similar to the cyhal_pwm_init_adv() but uses defaults for some of the more advanced setup options. More... | |
Typedefs | |
typedef void(* | cyhal_pwm_event_callback_t) (void *callback_arg, cyhal_pwm_event_t event) |
Handler for PWM interrupts. | |
Enumerations | |
enum | cyhal_pwm_event_t { CYHAL_PWM_IRQ_NONE = 0 , CYHAL_PWM_IRQ_TERMINAL_COUNT = 1 << 0 , CYHAL_PWM_IRQ_COMPARE = 1 << 1 , CYHAL_PWM_IRQ_ALL = (1 << 2) - 1 } |
PWM interrupt triggers. More... | |
enum | cyhal_pwm_alignment_t { CYHAL_PWM_LEFT_ALIGN = 0 , CYHAL_PWM_RIGHT_ALIGN = 1 , CYHAL_PWM_CENTER_ALIGN = 2 } |
PWM alignment. More... | |
enum | cyhal_pwm_input_t { CYHAL_PWM_INPUT_START , CYHAL_PWM_INPUT_STOP , CYHAL_PWM_INPUT_RELOAD , CYHAL_PWM_INPUT_COUNT , CYHAL_PWM_INPUT_CAPTURE } |
PWM input signal. More... | |
enum | cyhal_pwm_output_t { CYHAL_PWM_OUTPUT_OVERFLOW , CYHAL_PWM_OUTPUT_UNDERFLOW , CYHAL_PWM_OUTPUT_COMPARE_MATCH , CYHAL_PWM_OUTPUT_LINE_OUT } |
PWM output signal. More... | |
Functions | |
cy_rslt_t | cyhal_pwm_init_adv (cyhal_pwm_t *obj, cyhal_gpio_t pin, cyhal_gpio_t compl_pin, cyhal_pwm_alignment_t pwm_alignment, bool continuous, uint32_t dead_time_us, bool invert, const cyhal_clock_t *clk) |
Initialize the PWM out peripheral and configure the pin. More... | |
cy_rslt_t | cyhal_pwm_init_cfg (cyhal_pwm_t *obj, const cyhal_pwm_configurator_t *cfg) |
Initialize the PWM out peripheral using a configurator generated configuration struct. More... | |
void | cyhal_pwm_free (cyhal_pwm_t *obj) |
Deinitialize the PWM object. More... | |
cy_rslt_t | cyhal_pwm_set_period (cyhal_pwm_t *obj, uint32_t period_us, uint32_t pulse_width_us) |
Set the number of microseconds for the PWM period & pulse width. More... | |
cy_rslt_t | cyhal_pwm_set_duty_cycle (cyhal_pwm_t *obj, float duty_cycle, uint32_t frequencyhal_hz) |
Set the PWM duty cycle and frequency. More... | |
cy_rslt_t | cyhal_pwm_start (cyhal_pwm_t *obj) |
Starts the PWM generation and outputs on pin and compl_pin. More... | |
cy_rslt_t | cyhal_pwm_stop (cyhal_pwm_t *obj) |
Stops the PWM generation and outputs on pin and compl_pin. More... | |
void | cyhal_pwm_register_callback (cyhal_pwm_t *obj, cyhal_pwm_event_callback_t callback, void *callback_arg) |
Register a PWM interrupt handler. More... | |
void | cyhal_pwm_enable_event (cyhal_pwm_t *obj, cyhal_pwm_event_t event, uint8_t intr_priority, bool enable) |
Configure PWM event enablement. More... | |
cy_rslt_t | cyhal_pwm_connect_digital (cyhal_pwm_t *obj, cyhal_source_t source, cyhal_pwm_input_t signal) |
Connects a source signal and configures and enables a PWM event to be triggered from that signal. More... | |
cy_rslt_t | cyhal_pwm_connect_digital2 (cyhal_pwm_t *obj, cyhal_source_t source, cyhal_pwm_input_t signal, cyhal_edge_type_t edge_type) |
Connects a source signal and configures and enables a PWM event to be triggered from that signal with a configurable edge type. More... | |
cy_rslt_t | cyhal_pwm_enable_output (cyhal_pwm_t *obj, cyhal_pwm_output_t signal, cyhal_source_t *source) |
Enables the specified output signal from a PWM that will be triggered when the corresponding event occurs. More... | |
cy_rslt_t | cyhal_pwm_disconnect_digital (cyhal_pwm_t *obj, cyhal_source_t source, cyhal_pwm_input_t signal) |
Disconnects a source signal and disables the PWM event. More... | |
cy_rslt_t | cyhal_pwm_disable_output (cyhal_pwm_t *obj, cyhal_pwm_output_t signal) |
Disables the specified output signal from a PWM. More... | |
#define cyhal_pwm_init | ( | obj, | |
pin, | |||
clk | |||
) | (cyhal_pwm_init_adv(obj, pin, NC, CYHAL_PWM_LEFT_ALIGN, true, 0u, false, clk)) |
Initialize the PWM out peripheral and configure the pin This is similar to the cyhal_pwm_init_adv() but uses defaults for some of the more advanced setup options.
See Snippet 1: Simple PWM initialization and output to pin.
[out] | obj | Pointer to a PWM object. The caller must allocate the memory for this object but the init function will initialize its contents. |
[in] | pin | The PWM pin to initialize. This pin is required, it cannot be NC (No Connect). |
[in] | clk | An optional, pre-allocated clock to use, if NULL a new clock will be allocated |
enum cyhal_pwm_event_t |
PWM alignment.
enum cyhal_pwm_input_t |
enum cyhal_pwm_output_t |
cy_rslt_t cyhal_pwm_init_adv | ( | cyhal_pwm_t * | obj, |
cyhal_gpio_t | pin, | ||
cyhal_gpio_t | compl_pin, | ||
cyhal_pwm_alignment_t | pwm_alignment, | ||
bool | continuous, | ||
uint32_t | dead_time_us, | ||
bool | invert, | ||
const cyhal_clock_t * | clk | ||
) |
Initialize the PWM out peripheral and configure the pin.
This is similar to the cyhal_pwm_init() but provides additional setup options.
See Snippet 3: Advanced PWM output to pin.
[out] | obj | Pointer to a PWM object. The caller must allocate the memory for this object but the init function will initialize its contents. |
[in] | pin | The PWM pin to initialize. This pin is required, it cannot be NC (No Connect). |
[in] | compl_pin | An optional, additional inverted output pin. If supplied, this must be connected to the same or related PWM instance as pin, see Complementary PWM output for details. If this output is not needed, use NC (No Connect). |
[in] | pwm_alignment | PWM alignment: left, right, or center. |
[in] | continuous | PWM run type: continuous (true) or one shot (false). |
[in] | dead_time_us | The number of micro-seconds for dead time. This is only meaningful if both pin and compl_pin are provided. |
[in] | invert | An option for the user to invert the PWM output |
[in] | clk | An optional, pre-allocated clock to use, if NULL a new clock will be allocated. |
cy_rslt_t cyhal_pwm_init_cfg | ( | cyhal_pwm_t * | obj, |
const cyhal_pwm_configurator_t * | cfg | ||
) |
Initialize the PWM out peripheral using a configurator generated configuration struct.
[out] | obj | Pointer to a PWM object. The caller must allocate the memory for this object but the init function will initialize its contents. |
[in] | cfg | Configuration structure generated by a configurator. |
void cyhal_pwm_free | ( | cyhal_pwm_t * | obj | ) |
Deinitialize the PWM object.
[in,out] | obj | The PWM object |
cy_rslt_t cyhal_pwm_set_period | ( | cyhal_pwm_t * | obj, |
uint32_t | period_us, | ||
uint32_t | pulse_width_us | ||
) |
Set the number of microseconds for the PWM period & pulse width.
[in] | obj | The PWM object |
[in] | period_us | The period in microseconds |
[in] | pulse_width_us | The pulse width in microseconds |
cy_rslt_t cyhal_pwm_set_duty_cycle | ( | cyhal_pwm_t * | obj, |
float | duty_cycle, | ||
uint32_t | frequencyhal_hz | ||
) |
Set the PWM duty cycle and frequency.
[in] | obj | The PWM object |
[in] | duty_cycle | The percentage of time the output is high (0 - 100%) |
[in] | frequencyhal_hz | The frequency of the PWM in Hz |
cy_rslt_t cyhal_pwm_start | ( | cyhal_pwm_t * | obj | ) |
Starts the PWM generation and outputs on pin and compl_pin.
[in] | obj | The PWM object |
cy_rslt_t cyhal_pwm_stop | ( | cyhal_pwm_t * | obj | ) |
Stops the PWM generation and outputs on pin and compl_pin.
[in] | obj | The PWM object |
void cyhal_pwm_register_callback | ( | cyhal_pwm_t * | obj, |
cyhal_pwm_event_callback_t | callback, | ||
void * | callback_arg | ||
) |
Register a PWM interrupt handler.
This function will be called when one of the events enabled by cyhal_pwm_enable_event occurs.
[in] | obj | The PWM object |
[in] | callback | The callback handler which will be invoked when the event occurs |
[in] | callback_arg | Generic argument that will be provided to the callback when called |
void cyhal_pwm_enable_event | ( | cyhal_pwm_t * | obj, |
cyhal_pwm_event_t | event, | ||
uint8_t | intr_priority, | ||
bool | enable | ||
) |
Configure PWM event enablement.
When an enabled event occurs, the function specified by cyhal_pwm_register_callback will be called.
[in] | obj | The PWM object |
[in] | event | The PWM event type |
[in] | intr_priority | The priority for NVIC interrupt events |
[in] | enable | True to turn on events, False to turn off |
cy_rslt_t cyhal_pwm_connect_digital | ( | cyhal_pwm_t * | obj, |
cyhal_source_t | source, | ||
cyhal_pwm_input_t | signal | ||
) |
Connects a source signal and configures and enables a PWM event to be triggered from that signal.
These PWM events can be configured independently and connect to the same or different source signals.
[in] | obj | PWM obj |
[in] | source | Source signal obtained from another driver's cyhal_<PERIPH>_enable_output |
[in] | signal | The PWM input signal |
cy_rslt_t cyhal_pwm_connect_digital2 | ( | cyhal_pwm_t * | obj, |
cyhal_source_t | source, | ||
cyhal_pwm_input_t | signal, | ||
cyhal_edge_type_t | edge_type | ||
) |
Connects a source signal and configures and enables a PWM event to be triggered from that signal with a configurable edge type.
These PWM events can be configured independently and connect to the same or different source signals.
[in] | obj | PWM obj |
[in] | source | Source signal obtained from another driver's cyhal_<PERIPH>_enable_output |
[in] | signal | The PWM input signal |
[in] | edge_type | The edge type that should trigger the event. This must be consistent with the edge type of source . If source produces a "level" signal, the only valid value is CYHAL_EDGE_TYPE_LEVEL. If source produces an "edge" signal, then CYHAL_EDGE_TYPE_LEVEL is not a valid value. |
cy_rslt_t cyhal_pwm_enable_output | ( | cyhal_pwm_t * | obj, |
cyhal_pwm_output_t | signal, | ||
cyhal_source_t * | source | ||
) |
Enables the specified output signal from a PWM that will be triggered when the corresponding event occurs.
Multiple output signals can be configured simultaneously.
[in] | obj | PWM obj |
[in] | signal | The PWM output signal |
[out] | source | Pointer to user-allocated source signal object which will be initialized by enable_output. source should be passed to (dis)connect_digital functions to (dis)connect the associated endpoints. |
cy_rslt_t cyhal_pwm_disconnect_digital | ( | cyhal_pwm_t * | obj, |
cyhal_source_t | source, | ||
cyhal_pwm_input_t | signal | ||
) |
Disconnects a source signal and disables the PWM event.
[in] | obj | PWM obj |
[in] | source | Source signal from cyhal_<PERIPH>_enable_output to disable |
[in] | signal | The PWM input signal |
cy_rslt_t cyhal_pwm_disable_output | ( | cyhal_pwm_t * | obj, |
cyhal_pwm_output_t | signal | ||
) |
Disables the specified output signal from a PWM.
[in] | obj | PWM obj |
[in] | signal | The PWM output signal |