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.

Return

The status of the init request.

Parameters
  • [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

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.

Return

The status of the init request

Parameters
  • [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 PWM instance as

    pin, see Complementary PWM output.

    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.

void cyhal_pwm_free(cyhal_pwm_t *obj)

Deinitialize the PWM object.

Parameters
  • [inout] 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.

Return

The status of the period request

Parameters
  • [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.

Return

The status of the duty cycle request

Parameters
  • [in] obj: The PWM object

  • [in] duty_cycle: The percentage of time the output is high

  • [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.

Return

The status of the start request

Parameters
  • [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.

Return

The status of the stop request

Parameters
  • [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.

Parameters
  • [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.

Parameters
  • [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, 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.

Return

The status of the connection

Parameters
  • [in] obj: PWM obj

  • [in] source: Source signal obtained from another driver’s cyhal_<PERIPH>_enable_output

  • [in] signal: The PWM input signal

  • [in] type: The PWM input signal edge type

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.

Return

The status of the output enable

Parameters
  • [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.

Return

The status of the disconnection

Parameters
  • [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.

Return

The status of the output disable

Parameters
  • [in] obj: PWM obj

  • [in] signal: The PWM output signal