PWM (Pulse Width Modulator)

General Description

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.

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

    while (loop)
    {
        // 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);

cy_rslt_t 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);

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

    if (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);
    }

    return 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
    }
}

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

Macro Definition Documentation

cyhal_pwm_init

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

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

Returns

The status of the init request.

Enumeration Type Documentation

cyhal_pwm_event_t

enum cyhal_pwm_event_t

PWM interrupt triggers.

Enumerator
CYHAL_PWM_IRQ_NONE	No interrupts.
CYHAL_PWM_IRQ_TERMINAL_COUNT	Interrupt on terminal count match event.
CYHAL_PWM_IRQ_COMPARE	Interrupt on compare match event.
CYHAL_PWM_IRQ_ALL	Interrupt on any events.

cyhal_pwm_alignment_t

enum cyhal_pwm_alignment_t

PWM alignment.

Enumerator
CYHAL_PWM_LEFT_ALIGN	PWM is left aligned (signal starts high and goes low after compare match)
CYHAL_PWM_RIGHT_ALIGN	PWM is right aligned (signal starts low and goes high after compare match)
CYHAL_PWM_CENTER_ALIGN	PWM is centered aligned (signal starts and ends low with a center aligned pulse)

cyhal_pwm_input_t

enum cyhal_pwm_input_t

PWM input signal.

Enumerator
CYHAL_PWM_INPUT_START	Start signal.
CYHAL_PWM_INPUT_STOP	Stop signal.
CYHAL_PWM_INPUT_RELOAD	Reload signal.
CYHAL_PWM_INPUT_COUNT	Count signal.
CYHAL_PWM_INPUT_CAPTURE	Capture/swap signal.

cyhal_pwm_output_t

enum cyhal_pwm_output_t

PWM output signal.

Enumerator
CYHAL_PWM_OUTPUT_OVERFLOW	Overflow signal.
CYHAL_PWM_OUTPUT_UNDERFLOW	Underflow signal.
CYHAL_PWM_OUTPUT_COMPARE_MATCH	Compare Match signal.
CYHAL_PWM_OUTPUT_LINE_OUT	PWM line out signal.

Function Documentation

cyhal_pwm_init_adv()

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.

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

Returns

The status of the init request

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.

cyhal_pwm_init_cfg()

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.

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]	cfg	Configuration structure generated by a configurator.

Returns

The status of the init request

cyhal_pwm_free()

void cyhal_pwm_free

(

cyhal_pwm_t *

obj

)

Deinitialize the PWM object.

Parameters

[in,out]

obj

The PWM object

cyhal_pwm_set_period()

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

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

Returns

The status of the period request

cyhal_pwm_set_duty_cycle()

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

[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

Returns

The status of the duty cycle request

cyhal_pwm_start()

cy_rslt_t cyhal_pwm_start

(

cyhal_pwm_t *

obj

)

Starts the PWM generation and outputs on pin and compl_pin.

Parameters

[in]

obj

The PWM object

Returns

The status of the start request

cyhal_pwm_stop()

cy_rslt_t cyhal_pwm_stop

(

cyhal_pwm_t *

obj

)

Stops the PWM generation and outputs on pin and compl_pin.

Parameters

[in]

obj

The PWM object

Returns

The status of the stop request

cyhal_pwm_register_callback()

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

cyhal_pwm_enable_event()

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

cyhal_pwm_connect_digital()

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.

Parameters

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

Returns

The status of the connection

cyhal_pwm_enable_output()

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

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

Returns

The status of the output enable

cyhal_pwm_disconnect_digital()

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

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

Returns

The status of the disconnection

cyhal_pwm_disable_output()

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

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

Returns

The status of the output disable