PWM HAL Results¶

group group_hal_pwm

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.

Features

Configurable pin assignment for the PWM output
Optional complementary (inverted) PWM output to a second pin
Configurable dead time between normal and inverted PWM outputs
Configurable alignment: left, right or center
Continuous or One-shot operation
Option to instantiate and use a new clock or use pre-allocated clock for clock input
Configurable interrupt and callback assignment on PWM events: terminal count, compare match or combination of both

Quick Start

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.

Code snippets

Snippet 1: Simple PWM initialization and output to 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.

    cy_rslt_t   rslt;
    cyhal_pwm_t pwm_obj;

    // Initialize PWM on the supplied pin and assign a new clock
    rslt = cyhal_pwm_init(&pwm_obj, P0_0, NULL);

    // Set a duty cycle of 50% and frequency of 1Hz
    rslt = cyhal_pwm_set_duty_cycle(&pwm_obj, 50, 1);

    // Start the PWM output
    rslt = cyhal_pwm_start(&pwm_obj);

Snippet 2: Starting and stopping the PWM output

cyhal_pwm_start and cyhal_pwm_stop functions can be used after PWM initialization to start and stop the PWM output.

    cy_rslt_t   rslt;
    cyhal_pwm_t pwm_obj;

    // Initialize PWM on the supplied pin and assign a new clock
    rslt = cyhal_pwm_init(&pwm_obj, P0_0, NULL);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);

    // Set a duty cycle of 50% and frequency of 1Hz
    rslt = cyhal_pwm_set_duty_cycle(&pwm_obj, 50, 1);

    for (;;)
    {
        // Stop the PWM output
        rslt = cyhal_pwm_stop(&pwm_obj);

        // Delay for observing the output
        cyhal_system_delay_ms(5000);

        // (Re-)start the PWM output
        rslt = cyhal_pwm_start(&pwm_obj);

        // Delay for observing the output
        cyhal_system_delay_ms(5000);
    }

Snippet 3: Advanced PWM output to pin

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).

    cy_rslt_t   rslt;
    cyhal_pwm_t pwm_obj;

    // Initialize a left-aligned, continuous running PWM signal and assign normal and inverted
    // outputs to pins
    rslt = cyhal_pwm_init_adv(&pwm_obj, P0_0, P0_1, CYHAL_PWM_LEFT_ALIGN, true, 0, false, NULL);

    // Set a duty cycle of 80% on the normal PWM output with a frequency of 1kHz
    rslt = cyhal_pwm_set_duty_cycle(&pwm_obj, 80, 1000);

    // Start the PWM output
    rslt = cyhal_pwm_start(&pwm_obj);

Snippet 4: Interrupts on PWM events

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.

void pwm_event_handler(void* callback_arg, cyhal_pwm_event_t event);

void snippet_cyhal_pwm_events(void)
{
    cy_rslt_t   rslt;
    cyhal_pwm_t pwm_obj;

    // Initialize PWM on the supplied pin and assign a new clock
    rslt = cyhal_pwm_init(&pwm_obj, P0_0, NULL);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);

    // Set a duty cycle of 50% and frequency of 1Hz
    rslt = cyhal_pwm_set_duty_cycle(&pwm_obj, 50, 1);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);

    // Register a callback function (pwm_event_handler) to execute on event trigger
    cyhal_pwm_register_callback(&pwm_obj, pwm_event_handler, NULL);

    // Enable all events to trigger the callback
    cyhal_pwm_enable_event(&pwm_obj, CYHAL_PWM_IRQ_ALL, 3, true);

    // Start the PWM output
    rslt = cyhal_pwm_start(&pwm_obj);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);
}


void pwm_event_handler(void* callback_arg, cyhal_pwm_event_t event)
{
    (void)callback_arg;

    if ((event & CYHAL_PWM_IRQ_COMPARE) == CYHAL_PWM_IRQ_COMPARE)
    {
        // Compare event triggered
        // Insert application code to handle event
    }
    else if ((event & CYHAL_PWM_IRQ_TERMINAL_COUNT) == CYHAL_PWM_IRQ_TERMINAL_COUNT)
    {
        // Terminal count event triggered
        // Insert application code to handle event
    }
}

Defines

cyhal_pwm_init(obj, pin, 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.

Parameters

obj – [out] Pointer to a PWM object. The caller must allocate the memory for this object but the init function will initialize its contents.
pin – [in] The PWM pin to initialize. This pin is required, it cannot be NC (No Connect).
clk – [in] An optional, pre-allocated clock to use, if NULL a new clock will be allocated

Returns

The status of the init request.

Typedefs

typedef void (*cyhal_pwm_event_callback_t)(void *callback_arg, cyhal_pwm_event_t event): Handler for PWM interrupts.

Enums

enum cyhal_pwm_event_t

cyhal_pwm_event_t: PWM interrupt triggers.

Values:

enumerator CYHAL_PWM_IRQ_NONE: No interrupts.

enumerator CYHAL_PWM_IRQ_TERMINAL_COUNT: Interrupt on terminal count match event.

enumerator CYHAL_PWM_IRQ_COMPARE: Interrupt on compare match event.

enumerator CYHAL_PWM_IRQ_ALL: Interrupt on any events.

enum cyhal_pwm_alignment_t

cyhal_pwm_alignment_t: PWM alignment.

Values:

enumerator CYHAL_PWM_LEFT_ALIGN: PWM is left aligned (signal starts high and goes low after compare match)

enumerator CYHAL_PWM_RIGHT_ALIGN: PWM is right aligned (signal starts low and goes high after compare match)

enumerator CYHAL_PWM_CENTER_ALIGN: PWM is centered aligned (signal starts and ends low with a center aligned pulse)

enum cyhal_pwm_input_t

cyhal_pwm_input_t: PWM input signal.

Values:

enumerator CYHAL_PWM_INPUT_START: Start signal.

enumerator CYHAL_PWM_INPUT_STOP: Stop signal.

enumerator CYHAL_PWM_INPUT_RELOAD: Reload signal.

enumerator CYHAL_PWM_INPUT_COUNT: Count signal.

enumerator CYHAL_PWM_INPUT_CAPTURE: Capture/swap signal.

enum cyhal_pwm_output_t

cyhal_pwm_output_t: PWM output signal.

Values:

enumerator CYHAL_PWM_OUTPUT_OVERFLOW: Overflow signal.

enumerator CYHAL_PWM_OUTPUT_UNDERFLOW: Underflow signal.

enumerator CYHAL_PWM_OUTPUT_COMPARE_MATCH: Compare Match signal.

enumerator CYHAL_PWM_OUTPUT_LINE_OUT: PWM line out signal.

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.

This is similar to the cyhal_pwm_init()

but provides additional setup options.

See

Snippet 3: Advanced PWM output to pin.

note

In some cases, it is possible to use a pin designated for non-inverting output as an inverting output and vice versa. Whether this is possible is dependent on the HAL implementation and operating mode. See the implementation specific documentation for details.

Parameters

obj – [out] Pointer to a PWM object. The caller must allocate the memory for this object but the init function will initialize its contents.
pin – [in] The PWM pin to initialize. This pin is required, it cannot be NC (No Connect).
compl_pin – [in]
An optional, additional inverted output pin.

If supplied, this must be connected to the same PWM instance as
pin, see Complementary PWM output
.

If this output is not needed, use
NC (No Connect).
pwm_alignment – [in] PWM alignment: left, right, or center.
continuous – [in] PWM run type: continuous (true) or one shot (false).
dead_time_us – [in] The number of micro-seconds for dead time. This is only meaningful if both pin and compl_pin are provided.
invert – [in] An option for the user to invert the PWM output
clk – [in] An optional, pre-allocated clock to use, if NULL a new clock will be allocated.

Returns

The status of the init request

void cyhal_pwm_free(cyhal_pwm_t *obj)

Deinitialize the PWM object.

Parameters: obj – [inout] 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.

Parameters

obj – [in] The PWM object
period_us – [in] The period in microseconds
pulse_width_us – [in] The pulse width in microseconds

Returns

The status of the period request

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.

Parameters

obj – [in] The PWM object
duty_cycle – [in] The percentage of time the output is high
frequencyhal_hz – [in] The frequency of the PWM in Hz

Returns

The status of the duty cycle request

cy_rslt_t cyhal_pwm_start(cyhal_pwm_t *obj)

Starts the PWM generation and outputs on pin and compl_pin.

Parameters: obj – [in] The PWM object
Returns: The status of the start request

cy_rslt_t cyhal_pwm_stop(cyhal_pwm_t *obj)

Stops the PWM generation and outputs on pin and compl_pin.

Parameters: obj – [in] The PWM object
Returns: The status of the stop request

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.

Parameters

obj – [in] The PWM object
callback – [in] The callback handler which will be invoked when the event occurs
callback_arg – [in] 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.

Parameters

obj – [in] The PWM object
event – [in] The PWM event type
intr_priority – [in] The priority for NVIC interrupt events
enable – [in] 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, cyhal_edge_type_t type)

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.

Parameters

obj – [in] PWM obj
source – [in] Source signal obtained from another driver’s cyhal_<PERIPH>_enable_output
signal – [in] The PWM input signal
type – [in] The PWM input signal edge type

Returns

The status of the connection

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.

Parameters

obj – [in] PWM obj
signal – [in] The PWM output signal
source – [out] 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.

Returns

The status of the output enable

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.

Parameters

obj – [in] PWM obj
source – [in] Source signal from cyhal_<PERIPH>_enable_output to disable
signal – [in] The PWM input signal

Returns

The status of the disconnection

cy_rslt_t cyhal_pwm_disable_output(cyhal_pwm_t *obj, cyhal_pwm_output_t signal)

Disables the specified output signal from a PWM.

Parameters

obj – [in] PWM obj
signal – [in] The PWM output signal

Returns

The status of the output disable