Driver for the MCPWM hardware modules on the Espressif ESP32 SoC for generating a Phase-Shift-PWM waveform between two pairs of hardware pins. More...

#include <stdbool.h>
#include "driver/mcpwm.h"

Include dependency graph for ps_pwm.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	pspwm_setpoint_t

struct	pspwm_clk_conf_t

struct	pspwm_setpoint_limits_t

Macros
#define	PS_PWM_LOG_LEVEL ESP_LOG_INFO

#define	MCPWM_INPUT_CLK 160000000

#define	BASE_CLK_PRESCALE_DEFAULT 1

#define	TIMER_CLK_PRESCALE_DEFAULT 1

Functions
esp_err_t	pspwm_init (mcpwm_unit_t mcpwm_num, int gpio_lead_a, int gpio_lead_b, int gpio_lag_a, int gpio_lag_b, float frequency, float ps_duty, float lead_red, float lead_fed, float lag_red, float lag_fed, bool output_enabled, mcpwm_action_on_pwmxa_t disable_action_lead_leg, mcpwm_action_on_pwmxa_t disable_action_lag_leg)
	Set up the PS-PWM generator module for up-counting mode, allowing individual dead-time values for rising and falling edges for both lead and lag output pairs. More...

esp_err_t	pspwm_init_symmetrical (mcpwm_unit_t mcpwm_num, int gpio_lead_a, int gpio_lead_b, int gpio_lag_a, int gpio_lag_b, float frequency, float ps_duty, float lead_dt, float lag_dt, bool output_enabled, mcpwm_action_on_pwmxa_t disable_action_lead_leg, mcpwm_action_on_pwmxa_t disable_action_lag_leg)
	Shortcut version of pspwm_init() with identical rising and falling edge dead times applied for each of lead and lag leg. More...

esp_err_t	pspwm_set_frequency (mcpwm_unit_t mcpwm_num, float frequency)
	Set frequency when running PS-PWM generator in up-counting mode. More...

esp_err_t	pspwm_set_deadtimes (mcpwm_unit_t mcpwm_num, float lead_red, float lead_fed, float lag_red, float lag_fed)
	Set deadtime values individually for leading leg rising and falling edge as well as for lagging leg rising and falling edge for all four PWM outputs. More...

esp_err_t	pspwm_set_deadtimes_symmetrical (mcpwm_unit_t mcpwm_num, float lead_dt, float lag_dt)
	Shortcut version of pspwm_set_deadtimes() with identical rising and falling edge dead times applied for each of lead and lag leg. More...

esp_err_t	pspwm_set_ps_duty (mcpwm_unit_t mcpwm_num, float ps_duty)
	Set PS-PWM phase shift between lead and lag leg output pairs. More...

bool	pspwm_get_hw_fault_shutdown_present (mcpwm_unit_t mcpwm_num)
	Returns true while the hardware fault shutdown pin is active i.e. for as long as the failure is still present.

bool	pspwm_get_hw_fault_shutdown_occurred (mcpwm_unit_t mcpwm_num)
	Returns true when the hardware fault shutdown pin has been activated. More...

void	pspwm_clear_hw_fault_shutdown_occurred (mcpwm_unit_t mcpwm_num)
	Resets the fault shutdown active flag without re-enabling the output. More...

esp_err_t	pspwm_disable_output (mcpwm_unit_t mcpwm_num)
	Disable PWM output immediately by software-triggering the one-shot fault input of the "trip-zone" fault handler module. More...

esp_err_t	pspwm_resync_enable_output (mcpwm_unit_t mcpwm_num)
	(Re-)enable PWM output by clearing fault handler one-shot trigger after software-triggering a re-sync to the initial phase setpoint. More...

esp_err_t	pspwm_enable_hw_fault_shutdown (mcpwm_unit_t mcpwm_num, int gpio_fault_shutdown, mcpwm_fault_input_level_t fault_pin_active_level)
	Enable hardware fault shutdown ("tripzone") input on given GPIO pin. More...

esp_err_t	pspwm_disable_hw_fault_shutdown (mcpwm_unit_t mcpwm_num, int gpio_fault_shutdown)
	Disable hardware fault shutdown pin, resetting the GPIO to default state. More...

esp_err_t	pspwm_get_setpoint_ptr (mcpwm_unit_t mcpwm_num, pspwm_setpoint_t **setpoint)
	Return a pointer to PSPWM stage runtime setpoints. More...

esp_err_t	pspwm_get_setpoint_limits_ptr (mcpwm_unit_t mcpwm_num, pspwm_setpoint_limits_t **setpoint_limits)
	Return a pointer to PSPWM stage setpoint limits as calculated from clock configuration. More...

esp_err_t	pspwm_get_clk_conf_ptr (mcpwm_unit_t mcpwm_num, pspwm_clk_conf_t **clk_conf)
	Return a pointer to PSPWM stage clock configuration. More...

Detailed Description

Driver for the MCPWM hardware modules on the Espressif ESP32 SoC for generating a Phase-Shift-PWM waveform between two pairs of hardware pins.

Application in power electronics, e.g. Zero-Voltage-Switching (ZVS) Full-Bridge-, Dual-Active-Bridge- and LLC converters.

Note: This depends on the ESP-IDF SDK source files.

2021-01-21 Ulrich Lukas

Function Documentation

◆ pspwm_clear_hw_fault_shutdown_occurred()

void pspwm_clear_hw_fault_shutdown_occurred ( mcpwm_unit_t mcpwm_num )

Resets the fault shutdown active flag without re-enabling the output.

If a hardware shutdown occurred, this flag must be reset first in order to re-enable the output. This acts as a safety feature.

◆ pspwm_disable_hw_fault_shutdown()

esp_err_t pspwm_disable_hw_fault_shutdown	(	mcpwm_unit_t	mcpwm_num,
		int	gpio_fault_shutdown
	)

Disable hardware fault shutdown pin, resetting the GPIO to default state.

Parameters

mcpwm_num	PWM unit number (enum, MCPWM_UNIT_0 = 0, MCPWM_UNIT_1 = 1),
gpio_fault_shutdown	GPIO pin number for shutdown input

◆ pspwm_disable_output()

esp_err_t pspwm_disable_output ( mcpwm_unit_t mcpwm_num )

Disable PWM output immediately by software-triggering the one-shot fault input of the "trip-zone" fault handler module.

This sets the PWM output pins to predefined levels TRIPZONE_ACTION_PWMxA and TRIPZONE_ACTION_PWMxB, which can be configured in the header file.

Parameters

mcpwm_num PWM unit number (enum, MCPWM_UNIT_0 = 0, MCPWM_UNIT_1 = 1),

◆ pspwm_enable_hw_fault_shutdown()

esp_err_t pspwm_enable_hw_fault_shutdown	(	mcpwm_unit_t	mcpwm_num,
		int	gpio_fault_shutdown,
		mcpwm_fault_input_level_t	fault_pin_active_level
	)

Enable hardware fault shutdown ("tripzone") input on given GPIO pin.

This registers the fault handler FH0 signal with the specified PWM unit.

Parameters

mcpwm_num	PWM unit number (enum, MCPWM_UNIT_0 = 0, MCPWM_UNIT_1 = 1),
gpio_fault_shutdown	GPIO pin number for shutdown input
fault_pin_active_level	Logic level setting the fault condition [MCPWM_LOW_LEVEL_TGR \| MCPWM_HIGH_LEVEL_TGR]

◆ pspwm_get_clk_conf_ptr()

esp_err_t pspwm_get_clk_conf_ptr	(	mcpwm_unit_t	mcpwm_num,
		pspwm_clk_conf_t **	clk_conf
	)

Return a pointer to PSPWM stage clock configuration.

Parameters

mcpwm_num	PWM unit number (enum, MCPWM_UNIT_0 = 0, MCPWM_UNIT_1 = 1),
clk_conf	Pointer to a struct instance of pspwm_setpoint_t

◆ pspwm_get_hw_fault_shutdown_occurred()

bool pspwm_get_hw_fault_shutdown_occurred ( mcpwm_unit_t mcpwm_num )

Returns true when the hardware fault shutdown pin has been activated.

The state remains true (shutdown activated) as long as hw status has not been cleared by a call to pspwm_clear_hw_fault_shutdown_occurred().

◆ pspwm_get_setpoint_limits_ptr()

esp_err_t pspwm_get_setpoint_limits_ptr	(	mcpwm_unit_t	mcpwm_num,
		pspwm_setpoint_limits_t **	setpoint_limits
	)

Return a pointer to PSPWM stage setpoint limits as calculated from clock configuration.

Parameters

mcpwm_num	PWM unit number (enum, MCPWM_UNIT_0 = 0, MCPWM_UNIT_1 = 1),
setpoint_limits	Pointer to a struct instance of pspwm_setpoint_limits_t

◆ pspwm_get_setpoint_ptr()

esp_err_t pspwm_get_setpoint_ptr	(	mcpwm_unit_t	mcpwm_num,
		pspwm_setpoint_t **	setpoint
	)

Return a pointer to PSPWM stage runtime setpoints.

Parameters

mcpwm_num	PWM unit number (enum, MCPWM_UNIT_0 = 0, MCPWM_UNIT_1 = 1),
setpoint	Pointer to a struct instance of pspwm_setpoint_t

◆ pspwm_init()

esp_err_t pspwm_init	(	mcpwm_unit_t	mcpwm_num,
		int	gpio_lead_a,
		int	gpio_lead_b,
		int	gpio_lag_a,
		int	gpio_lag_b,
		float	frequency,
		float	ps_duty,
		float	lead_red,
		float	lead_fed,
		float	lag_red,
		float	lag_fed,
		bool	output_enabled,
		mcpwm_action_on_pwmxa_t	disable_action_lead_leg,
		mcpwm_action_on_pwmxa_t	disable_action_lag_leg
	)

Set up the PS-PWM generator module for up-counting mode, allowing individual dead-time values for rising and falling edges for both lead and lag output pairs.

FULL-SPEED-MODE, 4x INDIVIDUAL DEAD-TIME, HW-DEAD-TIME-MODULE

To achieve this, this uses the hardware dead-band generator while also calculating and setting complementary timing values for the PWM operator compare registers.

Combined output waveform of the phase-shifted full-bridge is DC-free symmetric nevertheless.

Parameters

mcpwm_num	PWM unit number (enum, MCPWM_UNIT_0 = 0, MCPWM_UNIT_1 = 1),
gpio_lead_a	GPIO number leading leg low_side
gpio_lead_b	GPIO number leading leg high_side
gpio_lag_a	GPIO number lagging leg low_side
gpio_lag_b	GPIO number lagging leg high_side
frequency	Frequency of the non-rectified waveform in Hz,
ps_duty	Duty cycle of the rectified waveform (0..1)
lead_red	dead time value for rising edge, leading leg
lead_fed	dead time value for falling edge, leading leg
lag_red	dead time value for rising edge, lagging leg
lag_fed	dead time value for falling edge, lagging leg
output_enabled	initial output state (true <==> ON)
disable_action_lead_leg	Choice of actions when lead bridge leg is disabled (See typedef for mcpwm_action_on_pwmxa_t)
disable_action_lag_leg	Same for lag leg

◆ pspwm_init_symmetrical()

esp_err_t pspwm_init_symmetrical	(	mcpwm_unit_t	mcpwm_num,
		int	gpio_lead_a,
		int	gpio_lead_b,
		int	gpio_lag_a,
		int	gpio_lag_b,
		float	frequency,
		float	ps_duty,
		float	lead_dt,
		float	lag_dt,
		bool	output_enabled,
		mcpwm_action_on_pwmxa_t	disable_action_lead_leg,
		mcpwm_action_on_pwmxa_t	disable_action_lag_leg
	)

Shortcut version of pspwm_init() with identical rising and falling edge dead times applied for each of lead and lag leg.

This is also call compatible with the up_down_ctr_mode API (different file).

Here is the call graph for this function:

◆ pspwm_resync_enable_output()

esp_err_t pspwm_resync_enable_output ( mcpwm_unit_t mcpwm_num )

(Re-)enable PWM output by clearing fault handler one-shot trigger after software-triggering a re-sync to the initial phase setpoint.

If a hardware shutdown occurred, the shutdown flag must be reset first by calling pspwm_clear_hw_fault_shutdown_occurred() in order to be able to re-enable the output. This acts as a safety feature.

Parameters

mcpwm_num PWM unit number (enum, MCPWM_UNIT_0 = 0, MCPWM_UNIT_1 = 1),

◆ pspwm_set_deadtimes()

esp_err_t pspwm_set_deadtimes	(	mcpwm_unit_t	mcpwm_num,
		float	lead_red,
		float	lead_fed,
		float	lag_red,
		float	lag_fed
	)

Set deadtime values individually for leading leg rising and falling edge as well as for lagging leg rising and falling edge for all four PWM outputs.

Parameters

mcpwm_num	PWM unit number (enum, MCPWM_UNIT_0 = 0, MCPWM_UNIT_1 = 1),
lead_red	dead time value for rising edge, leading leg
lead_fed	dead time value for falling edge, leading leg
lag_red	dead time value for rising edge, lagging leg
lag_fed	dead time value for falling edge, lagging leg

◆ pspwm_set_deadtimes_symmetrical()

esp_err_t pspwm_set_deadtimes_symmetrical	(	mcpwm_unit_t	mcpwm_num,
		float	lead_dt,
		float	lag_dt
	)

Shortcut version of pspwm_set_deadtimes() with identical rising and falling edge dead times applied for each of lead and lag leg.

This is also call compatible with the up_down_ctr_mode API (different file).

Here is the call graph for this function:

◆ pspwm_set_frequency()

esp_err_t pspwm_set_frequency	(	mcpwm_unit_t	mcpwm_num,
		float	frequency
	)

Set frequency when running PS-PWM generator in up-counting mode.

Note: This does not alter prescaler settings.

Parameters

mcpwm_num	PWM unit number (enum, MCPWM_UNIT_0 = 0, MCPWM_UNIT_1 = 1),
frequency	Frequency of the non-rectified waveform in Hz,

◆ pspwm_set_ps_duty()

esp_err_t pspwm_set_ps_duty	(	mcpwm_unit_t	mcpwm_num,
		float	ps_duty
	)

Set PS-PWM phase shift between lead and lag leg output pairs.

This is expressed in units of one where 1.0 means 180° phase-shift for the output pairs, giving maximum duty cycle after rectification.

Note: The value is calculated based on current value of the PWM timer "period" register.

Parameters

mcpwm_num	PWM unit number (enum, MCPWM_UNIT_0 = 0, MCPWM_UNIT_1 = 1),
ps_duty	Duty cycle of the rectified waveform (0..1)

Classes

Macros

Functions

Detailed Description

Function Documentation

◆ pspwm_clear_hw_fault_shutdown_occurred()

◆ pspwm_disable_hw_fault_shutdown()

◆ pspwm_disable_output()

◆ pspwm_enable_hw_fault_shutdown()

◆ pspwm_get_clk_conf_ptr()

◆ pspwm_get_hw_fault_shutdown_occurred()

◆ pspwm_get_setpoint_limits_ptr()

◆ pspwm_get_setpoint_ptr()

◆ pspwm_init()

◆ pspwm_init_symmetrical()

◆ pspwm_resync_enable_output()

◆ pspwm_set_deadtimes()

◆ pspwm_set_deadtimes_symmetrical()

◆ pspwm_set_frequency()

◆ pspwm_set_ps_duty()