Motor Control Pulse Width Modulator (MCPWM)

The MCPWM peripheral is a versatile PWM generator, which contains various submodules to make it a key element in power electronic applications like motor control, digital power and so on. Typically, the MCPWM peripheral can be used in the following scenarios:

Digital motor control, e.g. brushed/brushless DC motor, RC servo motor
Switch mode based digital power conversion
Power DAC, where the duty cycle is equivalent to a DAC analog value
Calculate external pulse width, and convert it into other analog value like speed, distance
Generate Space Vector PWM (SVPWM) signals for Field Oriented Control (FOC)

The main submodules are listed in the following diagram:

MCPWM Overview

MCPWM Timer: The time base of the final PWM signal, it also determines the event timing of other submodules.
MCPWM Operator: The key module that is responsible for generating the PWM waveforms. It consists of other submodules, like comparator, PWM generator, dead-time and carrier modulator.
MCPWM Comparator: The compare module takes the time-base count value as input, and continuously compare to the threshold value that configured by user. When the time-base counter is equal to any of the threshold value, an compare event will be generated and the MCPWM generator can update its level accordingly.
MCPWM Generator: One MCPWM generator can generate a pair of PWM waves, complementarily or independently, based on various events triggered from other submodules like MCPWM Timer, MCPWM Comparator.
MCPWM Fault: The fault module is used to detect the fault condition from outside, mainly via GPIO matrix. Once the fault signal is active, MCPWM Operator will force all the generators into a predefined state, to protect the system from damage.
MCPWM Sync: The sync module is used to synchronize the MCPWM timers, so that the final PWM signals generated by different MCPWM generators can have a fixed phase difference. The sync signal can be routed from GPIO matrix or from MCPWM Timer event.
Dead Time: This submodule is used to insert extra delay to the existing PWM edges that generated in the previous steps.
Carrier Modulation: The carrier submodule allows a high-frequency carrier signal to modulate the PWM waveforms generated by the generator and dead time submodules. This capability is mandatory if you need pulse transformer-based gate drivers to control the power switching elements.
Brake: MCPWM operator can set how to brake the generators when particular fault is detected. We can shut down the PWM output immediately or regulate the PWM output cycle by cycle, depends on how critical the fault is.
MCPWM Capture: This is a standalone submodule which can work even without the above MCPWM operators. The capture consists one dedicated timer and several independent channels. Each channel is connected to the GPIO, a pulse on the GPIO will trigger the capture timer to store the time-base count value and then notify the user by interrupt. Using this feature, we can measure a pulse width precisely. What’s more, the capture timer can also be synchronized by the MCPWM Sync submodule.

Functional Overview

Description of the MCPWM functionality is divided into the following sections:

Resource Allocation and Initialization - covers how to allocate various MCPWM objects, like timers, operators, comparators, generators and so on. These objects are the basis of the following IO setting and control functions.
Timer Operations and Events - describes control functions and event callbacks that supported by the MCPWM timer.
Comparator Operations and Events - describes control functions and event callbacks that supported by the MCPWM comparator.
Generator Actions on Events - describes how to set actions for MCPWM generators on particular events that generated by the MCPWM timer and comparators.
Classical PWM Waveforms and Generator Configurations - demonstrates some classical PWM waveforms that can be achieved by configuring generator actions.
Dead Time - describes how to set dead time for MCPWM generators.
Classical PWM Waveforms and Dead Time Configurations - demonstrates some classical PWM waveforms that can be achieved by configuring dead time.
Carrier Modulation - describes how to set modulate a high frequency onto the final PWM waveforms.
Faults and Brake Actions - describes how to set brake actions for MCPWM operators on particular fault event.
Generator Force Actions - describes how to control the generator output level asynchronously in a forceful way.
Synchronization - describes how to synchronize the MCPWM timers and get a fixed phase difference between the generated PWM signals.
Capture - describes how to use the MCPWM capture module to measure the pulse width of a signal.
Power Management - describes how different source clock will affect power consumption.
IRAM Safe - describes tips on how to make the RMT interrupt work better along with a disabled cache.
Thread Safety - lists which APIs are guaranteed to be thread safe by the driver.
Kconfig Options - lists the supported Kconfig options that can bring different effects to the driver.

Resource Allocation and Initialization

As displayed in the diagram above, the MCPWM peripheral consists of several submodules. Each submodule has its own resource allocation, which is described in the following sections.

MCPWM Timers

You can allocate a MCPWM timer object by calling mcpwm_new_timer() function, with a configuration structure mcpwm_timer_config_t as the parameter. The configuration structure is defined as:

mcpwm_timer_config_t::group_id specifies the MCPWM group ID. The ID should belong to [0, SOC_MCPWM_GROUPS - 1] range. Please note, timers located in different groups are totally independent.
mcpwm_timer_config_t::clk_src sets the clock source of the timer.
mcpwm_timer_config_t::resolution_hz set the expected resolution of the timer, the driver internally will set a proper divider based on the clock source and the resolution.
mcpwm_timer_config_t::count_mode sets the count mode of the timer.
mcpwm_timer_config_t::period_ticks sets the period of the timer, in ticks (the tick resolution is set in the mcpwm_timer_config_t::resolution_hz).
mcpwm_timer_config_t::update_period_on_empty sets whether to update the period value when the timer counts to zero.
mcpwm_timer_config_t::update_period_on_sync sets whether to update the period value when the timer takes a sync signal.

The mcpwm_new_timer() will return a pointer to the allocated timer object if the allocation succeeds. Otherwise, it will return error code. Specifically, when there are no more free timers in the MCPWM group, this function will return ESP_ERR_NOT_FOUND error. 1

On the contrary, calling mcpwm_del_timer() function will free the allocated timer object.

MCPWM Operators

You can allocate a MCPWM operator object by calling mcpwm_new_operator()() function, with a configuration structure mcpwm_operator_config_t as the parameter. The configuration structure is defined as:

mcpwm_operator_config_t::group_id specifies the MCPWM group ID. The ID should belong to [0, SOC_MCPWM_GROUPS - 1] range. Please note, operators located in different groups are totally independent.
mcpwm_operator_config_t::update_gen_action_on_tez sets whether to update the generator action when the timer counts to zero. Here and below, the timer refers to the one that is connected to the operator by mcpwm_operator_connect_timer().
mcpwm_operator_config_t::update_gen_action_on_tep sets whether to update the generator action when the timer counts to peak.
mcpwm_operator_config_t::update_gen_action_on_sync sets whether to update the generator action when the timer takes a sync signal.
mcpwm_operator_config_t::update_dead_time_on_tez sets whether to update the dead time when the timer counts to zero.
mcpwm_operator_config_t::update_dead_time_on_tep sets whether to update the dead time when the timer counts to peak.
mcpwm_operator_config_t::update_dead_time_on_sync sets whether to update the dead time when the timer takes a sync signal.

The mcpwm_new_operator()() will return a pointer to the allocated operator object if the allocation succeeds. Otherwise, it will return error code. Specifically, when there are no more free operators in the MCPWM group, this function will return ESP_ERR_NOT_FOUND error. 1

On the contrary, calling mcpwm_del_operator()() function will free the allocated operator object.

MCPWM Comparators

You can allocate a MCPWM comparator object by calling mcpwm_new_comparator() function, with a MCPWM operator handle and configuration structure mcpwm_comparator_config_t as the parameter. The operator handle is created by mcpwm_new_operator()(). The configuration structure is defined as:

mcpwm_comparator_config_t::update_cmp_on_tez sets whether to update the compare threshold when the timer counts to zero.
mcpwm_comparator_config_t::update_cmp_on_tep sets whether to update the compare threshold when the timer counts to peak.
mcpwm_comparator_config_t::update_cmp_on_sync sets whether to update the compare threshold when the timer takes a sync signal.

The mcpwm_new_comparator() will return a pointer to the allocated comparator object if the allocation succeeds. Otherwise, it will return error code. Specifically, when there are no more free comparators in the MCPWM operator, this function will return ESP_ERR_NOT_FOUND error. 1

On the contrary, calling mcpwm_del_comparator() function will free the allocated comparator object.

MCPWM Generators

You can allocate a MCPWM generator object by calling mcpwm_new_generator() function, with a MCPWM operator handle and configuration structure mcpwm_generator_config_t as the parameter. The operator handle is created by mcpwm_new_operator()(). The configuration structure is defined as:

mcpwm_generator_config_t::gen_gpio_num sets the GPIO number used by the generator.
mcpwm_generator_config_t::invert_pwm sets whether to invert the PWM signal.
mcpwm_generator_config_t::io_loop_back sets whether to enable the loop back mode. It is for debugging purposes only. It enables both the GPIO’s input and output ability through the GPIO matrix peripheral.

The mcpwm_new_generator() will return a pointer to the allocated generator object if the allocation succeeds. Otherwise, it will return error code. Specifically, when there are no more free generators in the MCPWM operator, this function will return ESP_ERR_NOT_FOUND error. 1

On the contrary, calling mcpwm_del_generator() function will free the allocated generator object.

MCPWM Faults

There are two types of faults: A fault signal reflected from the GPIO and a fault generated by software. To allocate a GPIO fault object, you can call mcpwm_new_gpio_fault() function, with configuration structure mcpwm_gpio_fault_config_t as the parameter. The configuration structure is defined as:

mcpwm_gpio_fault_config_t::group_id sets the MCPWM group ID. The ID should belong to [0, SOC_MCPWM_GROUPS - 1] range. Please note, GPIO fault located in different groups are totally independent, i.e. GPIO fault in group 0 can not be detected by the operator in group 1.
mcpwm_gpio_fault_config_t::gpio_num sets the GPIO number used by the fault.
mcpwm_gpio_fault_config_t::active_level sets the active level of the fault signal.
mcpwm_gpio_fault_config_t::pull_up and mcpwm_gpio_fault_config_t::pull_down set whether to pull up and/or pull down the GPIO internally.
mcpwm_gpio_fault_config_t::io_loop_back sets whether to enable the loop back mode. It is for debugging purposes only. It enables both the GPIO’s input and output ability through the GPIO matrix peripheral.

The mcpwm_new_gpio_fault() will return a pointer to the allocated fault object if the allocation succeeds. Otherwise, it will return error code. Specifically, when there are no more free GPIO faults in the MCPWM group, this function will return ESP_ERR_NOT_FOUND error. 1

Software fault object can be used to trigger a fault by calling a function mcpwm_soft_fault_activate() instead of waiting for a real fault signal on the GPIO. A software fault object can be allocated by calling mcpwm_new_soft_fault() function, with configuration structure mcpwm_soft_fault_config_t as the parameter. Currently this configuration structure is left for future purpose. mcpwm_new_soft_fault() function will return a pointer to the allocated fault object if the allocation succeeds. Otherwise, it will return error code. Specifically, when there are no memory left for the fault object, this function will return ESP_ERR_NO_MEM error. Although the software fault and GPIO fault are of different types, but the returned fault handle is of the same type.

On the contrary, calling mcpwm_del_fault() function will free the allocated fault object, this function works for both software and GPIO fault.

MCPWM Sync Sources

The sync source is what can be used to synchronize the MCPWM timer and MCPWM capture timer. There’re three types of sync sources: A sync source reflected from the GPIO, a sync source generated by software and a sync source generated by MCPWM timer event.

To allocate a GPIO sync source, you can call mcpwm_new_gpio_sync_src() function, with configuration structure mcpwm_gpio_sync_src_config_t as the parameter. The configuration structure is defined as:

mcpwm_gpio_sync_src_config_t::group_id sets the MCPWM group ID. The ID should belong to [0, SOC_MCPWM_GROUPS - 1] range. Please note, GPIO sync source located in different groups are totally independent, i.e. GPIO sync source in group 0 can not be detected by the timers in group 1.
mcpwm_gpio_sync_src_config_t::gpio_num sets the GPIO number used by the sync source.
mcpwm_gpio_sync_src_config_t::active_neg sets whether the sync signal is active on falling edge.
mcpwm_gpio_sync_src_config_t::pull_up and mcpwm_gpio_sync_src_config_t::pull_down set whether to pull up and/or pull down the GPIO internally.
mcpwm_gpio_sync_src_config_t::io_loop_back sets whether to enable the loop back mode. It is for debugging purposes only. It enables both the GPIO’s input and output ability through the GPIO matrix peripheral.

The mcpwm_new_gpio_sync_src() will return a pointer to the allocated sync source object if the allocation succeeds. Otherwise, it will return error code. Specifically, when there are no more free GPIO sync sources in the MCPWM group, this function will return ESP_ERR_NOT_FOUND error. 1

To allocate a Timer event sync source, you can call mcpwm_new_timer_sync_src() function, with configuration structure mcpwm_timer_sync_src_config_t as the parameter. The configuration structure is defined as:

mcpwm_timer_sync_src_config_t::timer_event specifies on what timer event to generate the sync signal.
mcpwm_timer_sync_src_config_t::propagate_input_sync sets whether to propagate the input sync signal (i.e. the input sync signal will be routed to its sync output).

The mcpwm_new_timer_sync_src() will return a pointer to the allocated sync source object if the allocation succeeds. Otherwise, it will return error code. Specifically, if a sync source has been allocated from the same timer before, this function will return ESP_ERR_INVALID_STATE error.

Last but not least, to allocate a software sync source, you can call mcpwm_new_soft_sync_src() function, with configuration structure mcpwm_soft_sync_config_t as the parameter. Currently this configuration structure is left for future purpose. mcpwm_new_soft_sync_src() will return a pointer to the allocated sync source object if the allocation succeeds. Otherwise, it will return error code. Specifically, when there are no memory left for the sync source object, this function will return ESP_ERR_NO_MEM error. Please note, to make a software sync source take effect, don’t forget to call mcpwm_soft_sync_activate().

On the contrary, calling mcpwm_del_sync_src() function will free the allocated sync source object, this function works for all types of sync sources.

MCPWM Capture Timer and Channels

The MCPWM group has a dedicated timer which is used to capture the timestamp when specific event occurred. The capture timer is connected with several independent channels, each channel is assigned with a GPIO.

To allocate a capture timer, you can call mcpwm_new_capture_timer() function, with configuration structure mcpwm_capture_timer_config_t as the parameter. The configuration structure is defined as:

mcpwm_capture_timer_config_t::group_id sets the MCPWM group ID. The ID should belong to [0, SOC_MCPWM_GROUPS - 1] range.
mcpwm_capture_timer_config_t::clk_src sets the clock source of the capture timer.

The mcpwm_new_capture_timer() will return a pointer to the allocated capture timer object if the allocation succeeds. Otherwise, it will return error code. Specifically, when there are no free capture timer left in the MCPWM group, this function will return ESP_ERR_NOT_FOUND error. 1

Next, to allocate a capture channel, you can call mcpwm_new_capture_channel() function, with a capture timer handle and configuration structure mcpwm_capture_channel_config_t as the parameter. The configuration structure is defined as:

mcpwm_capture_channel_config_t::gpio_num sets the GPIO number used by the capture channel.
mcpwm_capture_channel_config_t::prescale sets the prescaler of the input signal.
mcpwm_capture_channel_config_t::pos_edge and mcpwm_capture_channel_config_t::neg_edge set whether to capture on the positive and/or negative edge of the input signal.
mcpwm_capture_channel_config_t::pull_up and mcpwm_capture_channel_config_t::pull_down set whether to pull up and/or pull down the GPIO internally.
mcpwm_capture_channel_config_t::invert_cap_signal sets whether to invert the capture signal.
mcpwm_capture_channel_config_t::io_loop_back sets whether to enable the loop back mode. It is for debugging purposes only. It enables both the GPIO’s input and output ability through the GPIO matrix peripheral.

The mcpwm_new_capture_channel() will return a pointer to the allocated capture channel object if the allocation succeeds. Otherwise, it will return error code. Specifically, when there are no free capture channel left in the capture timer, this function will return ESP_ERR_NOT_FOUND error.

On the contrary, calling mcpwm_del_capture_channel() and mcpwm_del_capture_timer() function will free the allocated capture channel and timer object accordingly.

Timer Operations and Events

Register Event Callbacks

The MCPWM timer can generate different events at runtime. If you have some function that should be called when particular event happens, you should hook your function to the interrupt service routine by calling mcpwm_timer_register_event_callbacks(). The callback function prototype is declared in mcpwm_timer_event_cb_t. All supported event callbacks are listed in the mcpwm_timer_event_callbacks_t:

mcpwm_timer_event_callbacks_t::on_full sets callback function for timer when it counts to peak value.
mcpwm_timer_event_callbacks_t::on_empty sets callback function for timer when it counts to zero.
mcpwm_timer_event_callbacks_t::on_stop sets callback function for timer when it is stopped.

The callback functions above are called within the ISR context, so they should not attempt to block (e.g., make sure that only FreeRTOS APIs with ISR suffix is called within the function).

The parameter user_data of mcpwm_timer_register_event_callbacks() function is used to save user’s own context, it will be passed to each callback function directly.

This function will lazy install interrupt service for the MCPWM timer without enabling it. It is only allowed to be called before before mcpwm_timer_enable(), otherwise the ESP_ERR_INVALID_STATE error will be returned. See also Enable and Disable timer for more information.

Enable and Disable Timer

Before doing IO control to the timer, user needs to enable the timer first, by calling mcpwm_timer_enable(). Internally, this function will:

switch the timer state from init to enable.
enable the interrupt service if it has been lazy installed by mcpwm_timer_register_event_callbacks().
acquire a proper power management lock if a specific clock source (e.g. PLL_160M clock) is selected. See also Power management for more information.

On the contrary, calling mcpwm_timer_disable() will put the timer driver back to init state, disable the interrupts service and release the power management lock.

Start and Stop Timer

The basic IO operation of a timer is to start and stop. Calling mcpwm_timer_start_stop() with different mcpwm_timer_start_stop_cmd_t commands can start the timer immediately or stop the timer at a specific event. What’re more, you can even start the timer for only one round, that means, the timer will count to peak value or zero, and then stop itself.

Connect Timer with Operator

The allocated MCPWM Timer should be connected with a MCPWM operator by calling mcpwm_operator_connect_timer(), so that the operator can take that timer as its time base, and generate the required PWM waves. Make sure the MCPWM timer and operator are in the same group, otherwise, this function will return ESP_ERR_INVALID_ARG error.

Comparator Operations and Events

Register Event Callbacks

The MCPWM comparator can inform the user when the timer counter equals to the compare value. If you have some function that should be called when this event happens, you should hook your function to the interrupt service routine by calling mcpwm_comparator_register_event_callbacks(). The callback function prototype is declared in mcpwm_compare_event_cb_t. All supported event callbacks are listed in the mcpwm_comparator_event_callbacks_t:

mcpwm_comparator_event_callbacks_t::on_reach sets callback function for comparator when the timer counter equals to the compare value.

The callback function will provide event specific data of type mcpwm_compare_event_data_t to the user. The callback function is called within the ISR context, so is should not attempt to block (e.g., make sure that only FreeRTOS APIs with ISR suffix is called within the function).

The parameter user_data of mcpwm_comparator_register_event_callbacks() function is used to save user’s own context, it will be passed to the callback function directly.

This function will lazy install interrupt service for the MCPWM comparator, whereas the service can only be removed in mcpwm_del_comparator.

Set Compare Value

You can set the compare value for the MCPWM comparator at runtime by calling mcpwm_comparator_set_compare_value(). There’re a few points to note:

New compare value might won’t take effect immediately. The update time for the compare value is set by mcpwm_comparator_config_t::update_cmp_on_tez or mcpwm_comparator_config_t::update_cmp_on_tep or mcpwm_comparator_config_t::update_cmp_on_sync.
Make sure the operator has connected to one MCPWM timer already by mcpwm_operator_connect_timer(). Otherwise, it will return error code ESP_ERR_INVALID_STATE.
The compare value shouldn’t exceed timer’s count peak, otherwise, the compare event will never got triggered.

Generator Actions on Events

Set Generator Action on Timer Event

One generator can set multiple actions on different timer events, by calling mcpwm_generator_set_actions_on_timer_event() with variable number of action configurations. The action configuration is defined in mcpwm_gen_timer_event_action_t:

mcpwm_gen_timer_event_action_t::direction specific the timer direction. The supported directions are listed in mcpwm_timer_direction_t.
mcpwm_gen_timer_event_action_t::event specifies the timer event. The supported timer events are listed in mcpwm_timer_event_t.
mcpwm_gen_timer_event_action_t::action specifies the generator action to be taken. The supported actions are listed in mcpwm_generator_action_t.

There’s a helper macro MCPWM_GEN_TIMER_EVENT_ACTION to simplify the construction of a timer event action entry.

Please note, the argument list of mcpwm_generator_set_actions_on_timer_event() must be terminated by MCPWM_GEN_TIMER_EVENT_ACTION_END.

Set Generator Action on Compare Event

One generator can set multiple actions on different compare events, by calling mcpwm_generator_set_actions_on_compare_event() with variable number of action configurations. The action configuration is defined in mcpwm_gen_compare_event_action_t:

mcpwm_gen_compare_event_action_t::direction specific the timer direction. The supported directions are listed in mcpwm_timer_direction_t.
mcpwm_gen_compare_event_action_t::comparator specifies the comparator handle. See MCPWM Comparators for how to allocate a comparator.
mcpwm_gen_compare_event_action_t::action specifies the generator action to be taken. The supported actions are listed in mcpwm_generator_action_t.

There’s a helper macro MCPWM_GEN_COMPARE_EVENT_ACTION to simplify the construction of a compare event action entry.

Please note, the argument list of mcpwm_generator_set_actions_on_compare_event() must be terminated by MCPWM_GEN_COMPARE_EVENT_ACTION_END.

Classical PWM Waveforms and Generator Configurations

This section will demonstrate the classical PWM waveforms that can be generated by the pair of the generators. The code snippet that is used to generate the waveforms is also provided below the diagram. Some general summary:

The Symmetric or Asymmetric of the waveforms are determined by the count mode of the MCPWM timer.
The active level of the waveform pair is determined by the level of the PWM with a smaller duty cycle.
The period of the PWM waveform is determined by the timer’s period and count mode.
The duty cycle of the PWM waveform is determined by the generator’s various action combinations.

Asymmetric Single Edge Active High

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(gena,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(genb,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(genb,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
}

Asymmetric Single Edge Active Low

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(gena,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(genb,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(genb,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
}

Asymmetric Pulse Placement

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(genb,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_TOGGLE),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
}

Asymmetric Dual Edge Active Low

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(genb,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
}

Symmetric Dual Edge Active Low

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(genb,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
}

Symmetric Dual Edge Complementary

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(genb,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
}

Dead Time

In power electronics, the rectifier and inverter are commonly used. This requires the use of rectifier bridge and inverter bridge. Each bridge arm has two power electronic devices, such as MOSFET, IGBT, etc. The two MOSFETs on the same arm can’t conduct at the same time, otherwise there will be a short circuit. The fact is that, although the PWM wave shows it is turning off the switch, but the MOSFET still needs a small time window to make that happen. This requires an extra delay to be added to the existing PWM wave that generated by setting Generator Actions on Events.

The dead-time driver works like a decorator, which is also reflected in the function parameters of mcpwm_generator_set_dead_time(), where it takes the primary generator handle (in_generator), and returns a generator (out_generator) after applying the dead-time. Please note, if the out_generator and in_generator are the same, it means we’re adding the time delay to the PWM waveform in a “in-place” fashion. In turn, if the out_generator and in_generator are different, it means we’re deriving a new PWM waveform from the existing in_generator.

Dead-time specific configuration is listed in the mcpwm_dead_time_config_t structure:

mcpwm_dead_time_config_t::posedge_delay_ticks and mcpwm_dead_time_config_t::negedge_delay_ticks set the number of ticks to delay the PWM waveform on the rising and falling edge. Specifically, setting both of them to zero means to bypass the dead-time module. The resolution of the dead-time tick is the same to the timer that is connected with the operator by mcpwm_operator_connect_timer().
mcpwm_dead_time_config_t::invert_output: Whether to invert the signal after applying the dead-time, which can be used to control the delay edge polarity.

Note

It is also possible to generate the required dead time by setting Generator Actions on Events, especially by controlling edge placement using different comparators. However, if the more classical edge delay-based dead time with polarity control is required, then the dead-time submodule should be used.

Classical PWM Waveforms and Dead Time Configurations

This section will demonstrate the classical PWM waveforms that can be generated by the dead-time submodule. The code snippet that is used to generate the waveforms is also provided below the diagram.

Active High Complementary

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(gena,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
}

static void dead_time_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb)
{
    mcpwm_dead_time_config_t dead_time_config = {
        .posedge_delay_ticks = 50,
        .negedge_delay_ticks = 0
    };
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(gena, gena, &dead_time_config));
    dead_time_config.posedge_delay_ticks = 0;
    dead_time_config.negedge_delay_ticks = 100;
    dead_time_config.flags.invert_output = true;
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(gena, genb, &dead_time_config));
}

Active Low Complementary

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(gena,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
}

static void dead_time_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb)
{
    mcpwm_dead_time_config_t dead_time_config = {
        .posedge_delay_ticks = 50,
        .negedge_delay_ticks = 0,
        .flags.invert_output = true
    };
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(gena, gena, &dead_time_config));
    dead_time_config.posedge_delay_ticks = 0;
    dead_time_config.negedge_delay_ticks = 100;
    dead_time_config.flags.invert_output = false;
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(gena, genb, &dead_time_config));
}

Active High

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(gena,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
}

static void dead_time_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb)
{
    mcpwm_dead_time_config_t dead_time_config = {
        .posedge_delay_ticks = 50,
        .negedge_delay_ticks = 0,
    };
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(gena, gena, &dead_time_config));
    dead_time_config.posedge_delay_ticks = 0;
    dead_time_config.negedge_delay_ticks = 100;
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(gena, genb, &dead_time_config));
}

Active Low

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(gena,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
}

static void dead_time_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb)
{
    mcpwm_dead_time_config_t dead_time_config = {
        .posedge_delay_ticks = 50,
        .negedge_delay_ticks = 0,
        .flags.invert_output = true
    };
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(gena, gena, &dead_time_config));
    dead_time_config.posedge_delay_ticks = 0;
    dead_time_config.negedge_delay_ticks = 100;
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(gena, genb, &dead_time_config));
}

Rising Delay on PWMA, Bypass deadtime for PWMB

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(gena,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(genb,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(genb,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
}

static void dead_time_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb)
{
    mcpwm_dead_time_config_t dead_time_config = {
        .posedge_delay_ticks = 50,
        .negedge_delay_ticks = 0,
    };
    // apply deadtime to generator_a
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(gena, gena, &dead_time_config));
    // bypass deadtime module for generator_b
    dead_time_config.posedge_delay_ticks = 0;
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(genb, genb, &dead_time_config));
}

Falling Delay on PWMB, Bypass deadtime for PWMA

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(gena,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(genb,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(genb,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
}

static void dead_time_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb)
{
    mcpwm_dead_time_config_t dead_time_config = {
        .posedge_delay_ticks = 0,
        .negedge_delay_ticks = 0,
    };
    // generator_a bypass the deadtime module (no delay)
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(gena, gena, &dead_time_config));
    // apply dead time to generator_b
    dead_time_config.negedge_delay_ticks = 50;
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(genb, genb, &dead_time_config));

}

Rising and Falling Delay on PWMB, Bypass deadtime for PWMA

static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb)
{
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(gena,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(genb,
                    MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_HIGH),
                    MCPWM_GEN_TIMER_EVENT_ACTION_END()));
    ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(genb,
                    MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW),
                    MCPWM_GEN_COMPARE_EVENT_ACTION_END()));
}

static void dead_time_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb)
{
    mcpwm_dead_time_config_t dead_time_config = {
        .posedge_delay_ticks = 0,
        .negedge_delay_ticks = 0,
    };
    // generator_a bypass the deadtime module (no delay)
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(gena, gena, &dead_time_config));
    // apply dead time on both edge for generator_b
    dead_time_config.negedge_delay_ticks = 50;
    dead_time_config.posedge_delay_ticks = 50;
    ESP_ERROR_CHECK(mcpwm_generator_set_dead_time(genb, genb, &dead_time_config));
}

Carrier Modulation

The MCPWM operator has a carrier submodule that can be used if galvanic isolation from the motor driver is required (e.g. isolated digital power application) by passing the PWM output signals through transformers. Any of PWM output signals may be at 100% duty and not changing whenever motor is required to run steady at the full load. Coupling of non alternating signals with a transformer is problematic, so the signals are modulated by the carrier submodule to create an AC waveform, to make the coupling possible.

To configure the carrier submodule, you can call mcpwm_operator_apply_carrier(), and provide configuration structure mcpwm_carrier_config_t:

mcpwm_carrier_config_t::frequency_hz: The carrier frequency in Hz.
mcpwm_carrier_config_t::duty_cycle: The duty cycle of the carrier. Note that, the supported choices of duty cycle are discrete, the driver will search the nearest one based the user configuration.
mcpwm_carrier_config_t::first_pulse_duration_us: The duration of the first pulse in microseconds. The resolution of the first pulse duration is determined by the carrier frequency you set in the mcpwm_carrier_config_t::frequency_hz. The first pulse duration can’t be zero, and it has to be at least one period of the carrier. A longer pulse width can help conduct the inductance quicker.
mcpwm_carrier_config_t::invert_before_modulate and mcpwm_carrier_config_t::invert_after_modulate: Set whether to invert the carrier output before and after modulation.

Specifically, the carrier submodule can be disabled by calling mcpwm_operator_apply_carrier() with a NULL configuration.

Faults and Brake Actions

The MCPWM operator is able to sense external signals with information about failure of the motor, the power driver or any other device connected. These failure signals are encapsulated into MCPWM fault objects.

The user should determine possible failure modes of the motor and what action should be performed on detection of particular fault, e.g. drive all outputs low for a brushed motor, or lock current state for a stepper motor, etc. As result of this action the motor should be put into a safe state to reduce likelihood of a damage caused by the fault.

Set Operator Brake Mode on Fault

The way that MCPWM operator reacts to the fault is called Brake. The MCPWM operator can be configured to perform different brake modes for each fault object by calling mcpwm_operator_set_brake_on_fault(). Brake specific configuration is passed as a structure mcpwm_brake_config_t:

mcpwm_brake_config_t::fault set which fault that the operator should react to.
mcpwm_brake_config_t::brake_mode set the brake mode that should be used for the fault. The supported brake modes are listed in the mcpwm_operator_brake_mode_t. For MCPWM_OPER_BRAKE_MODE_CBC mode, the operator will recover itself automatically as long as the fault disappears. You can specify the recovery time in mcpwm_brake_config_t::cbc_recover_on_tez and mcpwm_brake_config_t::cbc_recover_on_tep. For MCPWM_OPER_BRAKE_MODE_OST mode, the operator can’t recover even though the fault disappears. User has to call mcpwm_operator_recover_from_fault() to manually recover it.

Set Generator Action on Brake Event

One generator can set multiple actions on different brake events, by calling mcpwm_generator_set_actions_on_brake_event() with variable number of action configurations. The action configuration is defined in mcpwm_gen_brake_event_action_t:

mcpwm_gen_brake_event_action_t::direction specific the timer direction. The supported directions are listed in mcpwm_timer_direction_t.
mcpwm_gen_brake_event_action_t::brake_mode specifies the brake mode. The supported brake modes are listed in the mcpwm_operator_brake_mode_t.
mcpwm_gen_brake_event_action_t::action specifies the generator action to be taken. The supported actions are listed in mcpwm_generator_action_t.

There’s a helper macro MCPWM_GEN_BRAKE_EVENT_ACTION to simplify the construction of a brake event action entry.

Please note, the argument list of mcpwm_generator_set_actions_on_brake_event() must be terminated by MCPWM_GEN_BRAKE_EVENT_ACTION_END.

Register Fault Event Callbacks

The MCPWM fault detector can inform the user when it detects a valid fault or a fault signal disappears. If you have some function that should be called when such event happens, you should hook your function to the interrupt service routine by calling mcpwm_fault_register_event_callbacks(). The callback function prototype is declared in mcpwm_fault_event_cb_t. All supported event callbacks are listed in the mcpwm_fault_event_callbacks_t:

mcpwm_fault_event_callbacks_t::on_fault_enter sets callback function that will be called when a fault is detected.
mcpwm_fault_event_callbacks_t::on_fault_exit sets callback function that will be called when a fault is cleared.

The callback function is called within the ISR context, so is should not attempt to block (e.g., make sure that only FreeRTOS APIs with ISR suffix is called within the function).

The parameter user_data of mcpwm_fault_register_event_callbacks() function is used to save user’s own context, it will be passed to the callback function directly.

This function will lazy install interrupt service for the MCPWM fault, whereas the service can only be removed in mcpwm_del_fault.

Register Brake Event Callbacks

The MCPWM operator can inform the user when it going to take a brake action. If you have some function that should be called when this event happens, you should hook your function to the interrupt service routine by calling mcpwm_operator_register_event_callbacks(). The callback function prototype is declared in mcpwm_brake_event_cb_t. All supported event callbacks are listed in the mcpwm_operator_event_callbacks_t:

mcpwm_operator_event_callbacks_t::on_brake_cbc sets callback function that will be called when the operator is going to take a CBC action.
mcpwm_operator_event_callbacks_t::on_brake_ost sets callback function that will be called when the operator is going to take an OST action.

The callback function is called within the ISR context, so is should not attempt to block (e.g., make sure that only FreeRTOS APIs with ISR suffix is called within the function).

The parameter user_data of mcpwm_operator_register_event_callbacks() function is used to save user’s own context, it will be passed to the callback function directly.

This function will lazy install interrupt service for the MCPWM operator, whereas the service can only be removed in mcpwm_del_operator.

Generator Force Actions

Software can override generator output level at runtime, by calling mcpwm_generator_set_force_level(). The software force level always has a higher priority than other event actions set in e.g. mcpwm_generator_set_actions_on_timer_event().

Set the level to -1 means to disable the force action, and the generator’s output level will be controlled by the event actions again.
Set the hold_on to true, the force output level will keep alive, until it’s removed by assigning level to -1.
Set the hole_on to false, the force output level will only be active for a short time, any upcoming event can override it.

Synchronization

When a sync signal is taken by the MCPWM timer, the timer will be forced into a predefined phase, where the phase is determined by count value and count direction. You can set the sync phase by calling mcpwm_timer_set_phase_on_sync(). The sync phase configuration is defined in mcpwm_timer_sync_phase_config_t structure:

mcpwm_timer_sync_phase_config_t::sync_src sets the sync signal source. See MCPWM Sync Sources for how to create a sync source object. Specifically, if this is set to NULL, the driver will disable the sync feature for the MCPWM timer.
mcpwm_timer_sync_phase_config_t::count_value sets the count value to load when the sync signal is taken.
mcpwm_timer_sync_phase_config_t::direction sets the count direction when the sync signal is taken.

Likewise, the MCPWM capture timer MCPWM Capture Timer can be synced as well. You can set the sync phase for the capture timer by calling mcpwm_capture_timer_set_phase_on_sync(). The sync phase configuration is defined in mcpwm_capture_timer_sync_phase_config_t structure:

mcpwm_capture_timer_sync_phase_config_t::sync_src sets the sync signal source. See MCPWM Sync Sources for how to create a sync source object. Specifically, if this is set to NULL, the driver will disable the sync feature for the MCPWM capture timer.
mcpwm_capture_timer_sync_phase_config_t::count_value sets the count value to load when the sync signal is taken.
mcpwm_capture_timer_sync_phase_config_t::direction sets the count direction when the sync signal is taken. Note that, different from MCPWM Timer, the capture timer can only support one count direction: MCPWM_TIMER_DIRECTION_UP.

Sync Timers by GPIO

GPIO Sync All MCPWM Timers

static void example_setup_sync_strategy(mcpwm_timer_handle_t timers[])
{
    mcpwm_sync_handle_t gpio_sync_source = NULL;
    mcpwm_gpio_sync_src_config_t gpio_sync_config = {
        .group_id = 0,              // GPIO fault should be in the same group of the above timers
        .gpio_num = EXAMPLE_SYNC_GPIO,
        .flags.pull_down = true,
        .flags.active_neg = false,  // by default, a posedge pulse can trigger a sync event
    };
    ESP_ERROR_CHECK(mcpwm_new_gpio_sync_src(&gpio_sync_config, &gpio_sync_source));

    mcpwm_timer_sync_phase_config_t sync_phase_config = {
        .count_value = 0,                      // sync phase: target count value
        .direction = MCPWM_TIMER_DIRECTION_UP, // sync phase: count direction
        .sync_src = gpio_sync_source,          // sync source
    };
    for (int i = 0; i < 3; i++) {
        ESP_ERROR_CHECK(mcpwm_timer_set_phase_on_sync(timers[i], &sync_phase_config));
    }
}

Capture

The basic functionality of MCPWM capture is to record the time when any pulse edge of the capture signal turns active. Then you can get the pulse width and convert it into other physical quantity like distance or speed in the capture callback function. For example, in the BLDC (Brushless DC, see figure below) scenario, we can use the capture submodule to sense the rotor position from Hall sensor.

Example of Brushless DC Motor Control with MCPWM

MCPWM BLDC with Hall Sensor

The capture timer is usually connected with several capture channels, please refer to howtoallocatecapturetimerandchannels#mcpwm-capture-timer-and-channels for resource allocation.

Register Event Callbacks

The MCPWM capture channel can inform the user when there’s a valid edge detected on the signal. You have to register a callback function to get the timer count value of the capture moment, by calling mcpwm_capture_channel_register_event_callbacks(). The callback function prototype is declared in mcpwm_capture_event_cb_t. All supported capture callbacks are listed in the mcpwm_capture_event_callbacks_t:

mcpwm_capture_event_callbacks_t::on_cap sets callback function for the capture channel when a valid edge is detected.

The callback function will provide event specific data of type mcpwm_capture_event_data_t, so that you can get the the edge of the capture signal in mcpwm_capture_event_data_t::cap_edge and the count value of that moment in mcpwm_capture_event_data_t::cap_value.

The callback function is called within the ISR context, so is should not attempt to block (e.g., make sure that only FreeRTOS APIs with ISR suffix is called within the function).

The parameter user_data of mcpwm_capture_channel_register_event_callbacks() function is used to save user’s own context, it will be passed to the callback function directly.

This function will lazy install interrupt service for the MCPWM capture channel, whereas the service can only be removed in mcpwm_del_capture_channel.

Enable and Disable Capture Timer

Before doing IO control to the capture timer, user needs to enable the timer first, by calling mcpwm_capture_timer_enable(). Internally, this function will:

switch the capture timer state from init to enable.
acquire a proper power management lock if a specific clock source (e.g. APB clock) is selected. See also Power management for more information.

On the contrary, calling mcpwm_capture_timer_disable() will put the timer driver back to init state, and release the power management lock.

Start and Stop Capture Timer

The basic IO operation of a capture timer is to start and stop. Calling mcpwm_capture_timer_start() can start the timer and calling mcpwm_capture_timer_stop() can stop the timer immediately.

Trigger a Software Capture Event

Sometime, the software also wants to trigger a “fake” capture event. The mcpwm_capture_channel_trigger_soft_catch() is provided for that purpose. Please note that, even though it’s a “fake” capture event, it can still cause an interrupt, thus your capture event callback function will get invoked as well.

Power Management

When power management is enabled (i.e. CONFIG_PM_ENABLE is on), the system will adjust the PLL, APB frequency before going into light sleep, thus potentially changing the period of a MCPWM timers’ counting step and leading to inaccurate time keeping.

However, the driver can prevent the system from changing APB frequency by acquiring a power management lock of type ESP_PM_APB_FREQ_MAX. Whenever the driver creates a MCPWM timer instance that has selected MCPWM_TIMER_CLK_SRC_PLL160M as its clock source, the driver will guarantee that the power management lock is acquired when enable the timer by mcpwm_timer_enable(). Likewise, the driver releases the lock when mcpwm_timer_disable() is called for that timer.

Likewise, Whenever the driver creates a MCPWM capture timer instance that has selected MCPWM_CAPTURE_CLK_SRC_APB as its clock source, the driver will guarantee that the power management lock is acquired when enable the timer by mcpwm_capture_timer_enable(). And will release the lock in mcpwm_capture_timer_disable().

IRAM Safe

By default, the MCPWM interrupt will be deferred when the Cache is disabled for reasons like writing/erasing Flash. Thus the event callback functions will not get executed in time, which is not expected in a real-time application.

There’s a Kconfig option CONFIG_MCPWM_ISR_IRAM_SAFE that will:

Enable the interrupt being serviced even when cache is disabled
Place all functions that used by the ISR into IRAM 2
Place driver object into DRAM (in case it’s mapped to PSRAM by accident)

This will allow the interrupt to run while the cache is disabled but will come at the cost of increased IRAM consumption.

Thread Safety

The factory functions like mcpwm_new_timer() are guaranteed to be thread safe by the driver, which means, you can call it from different RTOS tasks without protection by extra locks.

No functions are allowed to run within ISR environment.

Functions that are not related to Resource Allocation, are not thread safe. Thus, you should avoid calling them in different tasks without mutex protection.

Kconfig Options

CONFIG_MCPWM_ISR_IRAM_SAFE controls whether the default ISR handler can work when cache is disabled, see IRAM Safe for more information.
CONFIG_MCPWM_ENABLE_DEBUG_LOG is used to enabled the debug log output. Enable this option will increase the firmware binary size.

Application Examples

Brushed DC motor speed control by PID algorithm: peripherals/mcpwm/mcpwm_bdc_speed_control
BLDC motor control with hall sensor feedback: peripherals/mcpwm/mcpwm_bldc_hall_control
Ultrasonic sensor (HC-SR04) distance measurement: peripherals/mcpwm/mcpwm_capture_hc_sr04
Servo motor angle control: peripherals/mcpwm/mcpwm_servo_control
MCPWM synchronization between timers: peripherals/mcpwm/mcpwm_sync

API Reference

Header File

components/driver/include/driver/mcpwm_timer.h

Functions

esp_err_t mcpwm_new_timer(const mcpwm_timer_config_t *config, mcpwm_timer_handle_t *ret_timer)

Create MCPWM timer.

Parameters

config – [in] MCPWM timer configuration
ret_timer – [out] Returned MCPWM timer handle

Returns

ESP_OK: Create MCPWM timer successfully
ESP_ERR_INVALID_ARG: Create MCPWM timer failed because of invalid argument
ESP_ERR_NO_MEM: Create MCPWM timer failed because out of memory
ESP_ERR_NOT_FOUND: Create MCPWM timer failed because all hardware timers are used up and no more free one
ESP_FAIL: Create MCPWM timer failed because of other error

esp_err_t mcpwm_del_timer(mcpwm_timer_handle_t timer)

Delete MCPWM timer.

Parameters

timer – [in] MCPWM timer handle, allocated by mcpwm_new_timer()

Returns

ESP_OK: Delete MCPWM timer successfully
ESP_ERR_INVALID_ARG: Delete MCPWM timer failed because of invalid argument
ESP_ERR_INVALID_STATE: Delete MCPWM timer failed because timer is not in init state
ESP_FAIL: Delete MCPWM timer failed because of other error

esp_err_t mcpwm_timer_enable(mcpwm_timer_handle_t timer)

Enable MCPWM timer.

Parameters

timer – [in] MCPWM timer handle, allocated by mcpwm_new_timer()

Returns

ESP_OK: Enable MCPWM timer successfully
ESP_ERR_INVALID_ARG: Enable MCPWM timer failed because of invalid argument
ESP_ERR_INVALID_STATE: Enable MCPWM timer failed because timer is enabled already
ESP_FAIL: Enable MCPWM timer failed because of other error

esp_err_t mcpwm_timer_disable(mcpwm_timer_handle_t timer)

Disable MCPWM timer.

Parameters

timer – [in] MCPWM timer handle, allocated by mcpwm_new_timer()

Returns

ESP_OK: Disable MCPWM timer successfully
ESP_ERR_INVALID_ARG: Disable MCPWM timer failed because of invalid argument
ESP_ERR_INVALID_STATE: Disable MCPWM timer failed because timer is disabled already
ESP_FAIL: Disable MCPWM timer failed because of other error

esp_err_t mcpwm_timer_start_stop(mcpwm_timer_handle_t timer, mcpwm_timer_start_stop_cmd_t command)

Send specific start/stop commands to MCPWM timer.

Parameters

timer – [in] MCPWM timer handle, allocated by mcpwm_new_timer()
command – [in] Supported command list for MCPWM timer

Returns

ESP_OK: Start or stop MCPWM timer successfully
ESP_ERR_INVALID_ARG: Start or stop MCPWM timer failed because of invalid argument
ESP_ERR_INVALID_STATE: Start or stop MCPWM timer failed because timer is not enabled
ESP_FAIL: Start or stop MCPWM timer failed because of other error

esp_err_t mcpwm_timer_register_event_callbacks(mcpwm_timer_handle_t timer, const mcpwm_timer_event_callbacks_t *cbs, void *user_data)

Set event callbacks for MCPWM timer.

Parameters

timer – [in] MCPWM timer handle, allocated by mcpwm_new_timer()
cbs – [in] Group of callback functions
user_data – [in] User data, which will be passed to callback functions directly

Returns

ESP_OK: Set event callbacks successfully
ESP_ERR_INVALID_ARG: Set event callbacks failed because of invalid argument
ESP_ERR_INVALID_STATE: Set event callbacks failed because timer is not in init state
ESP_FAIL: Set event callbacks failed because of other error

esp_err_t mcpwm_timer_set_phase_on_sync(mcpwm_timer_handle_t timer, const mcpwm_timer_sync_phase_config_t *config)

Set sync phase for MCPWM timer.

Parameters

timer – [in] MCPWM timer handle, allocated by mcpwm_new_timer()
config – [in] MCPWM timer sync phase configuration

Returns

ESP_OK: Set sync phase for MCPWM timer successfully
ESP_ERR_INVALID_ARG: Set sync phase for MCPWM timer failed because of invalid argument
ESP_FAIL: Set sync phase for MCPWM timer failed because of other error

Structures

struct mcpwm_timer_event_callbacks_t

Group of supported MCPWM timer event callbacks.

Note

The callbacks are all running under ISR environment

Public Members

mcpwm_timer_event_cb_t on_full: callback function when MCPWM timer counts to peak value

mcpwm_timer_event_cb_t on_empty: callback function when MCPWM timer counts to zero

mcpwm_timer_event_cb_t on_stop: callback function when MCPWM timer stops

struct mcpwm_timer_config_t

MCPWM timer configuration.

Public Members

int group_id: Specify from which group to allocate the MCPWM timer

mcpwm_timer_clock_source_t clk_src: MCPWM timer clock source

uint32_t resolution_hz: Counter resolution in Hz, ranges from around 300KHz to 80MHz. The step size of each count tick equals to (1 / resolution_hz) seconds

mcpwm_timer_count_mode_t count_mode: Count mode

uint32_t period_ticks: Number of count ticks within a period

uint32_t update_period_on_empty: Whether to update period when timer counts to zero

uint32_t update_period_on_sync: Whether to update period on sync event

struct mcpwm_timer_config_t::[anonymous] flags: Extra configuration flags for timer

struct mcpwm_timer_sync_phase_config_t

MCPWM Timer sync phase configuration.

Public Members

mcpwm_sync_handle_t sync_src: The sync event source. Set to NULL will disable the timer being synced by others

uint32_t count_value: The count value that should lock to upon sync event

mcpwm_timer_direction_t direction: The count direction that should lock to upon sync event

Header File

components/driver/include/driver/mcpwm_oper.h

Functions

esp_err_t mcpwm_new_operator(const mcpwm_operator_config_t *config, mcpwm_oper_handle_t *ret_oper)

Create MCPWM operator.

Parameters

config – [in] MCPWM operator configuration
ret_oper – [out] Returned MCPWM operator handle

Returns

ESP_OK: Create MCPWM operator successfully
ESP_ERR_INVALID_ARG: Create MCPWM operator failed because of invalid argument
ESP_ERR_NO_MEM: Create MCPWM operator failed because out of memory
ESP_ERR_NOT_FOUND: Create MCPWM operator failed because can’t find free resource
ESP_FAIL: Create MCPWM operator failed because of other error

esp_err_t mcpwm_del_operator(mcpwm_oper_handle_t oper)

Delete MCPWM operator.

Parameters

oper – [in] MCPWM operator, allocated by mcpwm_new_operator()

Returns

ESP_OK: Delete MCPWM operator successfully
ESP_ERR_INVALID_ARG: Delete MCPWM operator failed because of invalid argument
ESP_FAIL: Delete MCPWM operator failed because of other error

esp_err_t mcpwm_operator_connect_timer(mcpwm_oper_handle_t oper, mcpwm_timer_handle_t timer)

Connect MCPWM operator and timer, so that the operator can be driven by the timer.

Parameters

oper – [in] MCPWM operator handle, allocated by mcpwm_new_operator()
timer – [in] MCPWM timer handle, allocated by mcpwm_new_timer()

Returns

ESP_OK: Connect MCPWM operator and timer successfully
ESP_ERR_INVALID_ARG: Connect MCPWM operator and timer failed because of invalid argument
ESP_FAIL: Connect MCPWM operator and timer failed because of other error

esp_err_t mcpwm_operator_set_brake_on_fault(mcpwm_oper_handle_t operator, const mcpwm_brake_config_t *config)

Set brake method for MCPWM operator.

Parameters

operator – [in] MCPWM operator, allocated by mcpwm_new_operator()
config – [in] MCPWM brake configuration

Returns

ESP_OK: Set trip for operator successfully
ESP_ERR_INVALID_ARG: Set trip for operator failed because of invalid argument
ESP_FAIL: Set trip for operator failed because of other error

esp_err_t mcpwm_operator_recover_from_fault(mcpwm_oper_handle_t operator, mcpwm_fault_handle_t fault)

Try to make the operator recover from fault.

Note

To recover from fault or escape from trip, you make sure the fault signal has dissappeared already. Otherwise the recovery can’t succeed.

Parameters

operator – [in] MCPWM operator, allocated by mcpwm_new_operator()
fault – [in] MCPWM fault handle

Returns

ESP_OK: Recover from fault successfully
ESP_ERR_INVALID_ARG: Recover from fault failed because of invalid argument
ESP_ERR_INVALID_STATE: Recover from fault failed because the fault source is still active
ESP_FAIL: Recover from fault failed because of other error

esp_err_t mcpwm_operator_register_event_callbacks(mcpwm_oper_handle_t oper, const mcpwm_operator_event_callbacks_t *cbs, void *user_data)

Set event callbacks for MCPWM operator.

Parameters

oper – [in] MCPWM operator handle, allocated by mcpwm_new_operator()
cbs – [in] Group of callback functions
user_data – [in] User data, which will be passed to callback functions directly

Returns

ESP_OK: Set event callbacks successfully
ESP_ERR_INVALID_ARG: Set event callbacks failed because of invalid argument
ESP_FAIL: Set event callbacks failed because of other error

esp_err_t mcpwm_operator_apply_carrier(mcpwm_oper_handle_t oper, const mcpwm_carrier_config_t *config)

Apply carrier feature for MCPWM operator.

Parameters

oper – [in] MCPWM operator, allocated by mcpwm_new_operator()
config – [in] MCPWM carrier specific configuration

Returns

ESP_OK: Set carrier for operator successfully
ESP_ERR_INVALID_ARG: Set carrier for operator failed because of invalid argument
ESP_FAIL: Set carrier for operator failed because of other error

Structures

struct mcpwm_operator_config_t

MCPWM operator configuration.

Public Members

int group_id: Specify from which group to allocate the MCPWM operator

uint32_t update_gen_action_on_tez: Whether to update generator action when timer counts to zero

uint32_t update_gen_action_on_tep: Whether to update generator action when timer counts to peak

uint32_t update_gen_action_on_sync: Whether to update generator action on sync event

uint32_t update_dead_time_on_tez: Whether to update dead time when timer counts to zero

uint32_t update_dead_time_on_tep: Whether to update dead time when timer counts to peak

uint32_t update_dead_time_on_sync: Whether to update dead time on sync event

struct mcpwm_operator_config_t::[anonymous] flags: Extra configuration flags for operator

struct mcpwm_brake_config_t

MCPWM brake configuration structure.

Public Members

mcpwm_fault_handle_t fault: Which fault causes the operator to brake

mcpwm_operator_brake_mode_t brake_mode: Brake mode

uint32_t cbc_recover_on_tez: Recovery CBC brake state on tez event

uint32_t cbc_recover_on_tep: Recovery CBC brake state on tep event

struct mcpwm_brake_config_t::[anonymous] flags: Extra flags for brake configuration

struct mcpwm_operator_event_callbacks_t

Group of supported MCPWM operator event callbacks.

Note

The callbacks are all running under ISR environment

Public Members

mcpwm_brake_event_cb_t on_brake_cbc: callback function when mcpwm operator brakes in CBC

mcpwm_brake_event_cb_t on_brake_ost: callback function when mcpwm operator brakes in OST

struct mcpwm_carrier_config_t

MCPWM carrier configuration structure.

Public Members

uint32_t frequency_hz: Carrier frequency in Hz

uint32_t first_pulse_duration_us: The duration of the first PWM pulse, in us

float duty_cycle: Carrier duty cycle

uint32_t invert_before_modulate: Invert the raw signal

uint32_t invert_after_modulate: Invert the modulated signal

struct mcpwm_carrier_config_t::[anonymous] flags: Extra flags for carrier configuration

Header File

components/driver/include/driver/mcpwm_cmpr.h

Functions

esp_err_t mcpwm_new_comparator(mcpwm_oper_handle_t oper, const mcpwm_comparator_config_t *config, mcpwm_cmpr_handle_t *ret_cmpr)

Create MCPWM comparator.

Parameters

oper – [in] MCPWM operator, allocated by mcpwm_new_operator(), the new comparator will be allocated from this operator
config – [in] MCPWM comparator configuration
ret_cmpr – [out] Returned MCPWM comparator

Returns

ESP_OK: Create MCPWM comparator successfully
ESP_ERR_INVALID_ARG: Create MCPWM comparator failed because of invalid argument
ESP_ERR_NO_MEM: Create MCPWM comparator failed because out of memory
ESP_ERR_NOT_FOUND: Create MCPWM comparator failed because can’t find free resource
ESP_FAIL: Create MCPWM comparator failed because of other error

esp_err_t mcpwm_del_comparator(mcpwm_cmpr_handle_t cmpr)

Delete MCPWM comparator.

Parameters

cmpr – [in] MCPWM comparator handle, allocated by mcpwm_new_comparator()

Returns

ESP_OK: Delete MCPWM comparator successfully
ESP_ERR_INVALID_ARG: Delete MCPWM comparator failed because of invalid argument
ESP_FAIL: Delete MCPWM comparator failed because of other error

esp_err_t mcpwm_comparator_register_event_callbacks(mcpwm_cmpr_handle_t cmpr, const mcpwm_comparator_event_callbacks_t *cbs, void *user_data)

Set event callbacks for MCPWM comparator.

Parameters

cmpr – [in] MCPWM comparator handle, allocated by mcpwm_new_comparator()
cbs – [in] Group of callback functions
user_data – [in] User data, which will be passed to callback functions directly

Returns

ESP_OK: Set event callbacks successfully
ESP_ERR_INVALID_ARG: Set event callbacks failed because of invalid argument
ESP_FAIL: Set event callbacks failed because of other error

esp_err_t mcpwm_comparator_set_compare_value(mcpwm_cmpr_handle_t cmpr, uint32_t cmp_ticks)

Set MCPWM comparator’s compare value.

Parameters

cmpr – [in] MCPWM comparator handle, allocated by mcpwm_new_comparator()
cmp_ticks – [in] The new compare value

Returns

ESP_OK: Set MCPWM compare value successfully
ESP_ERR_INVALID_ARG: Set MCPWM compare value failed because of invalid argument (e.g. the cmp_ticks is out of range)
ESP_ERR_INVALID_STATE: Set MCPWM compare value failed because the operator doesn’t have a timer connected
ESP_FAIL: Set MCPWM compare value failed because of other error

Structures

struct mcpwm_comparator_config_t

MCPWM comparator configuration.

Public Members

uint32_t update_cmp_on_tez: Whether to update compare value when timer count equals to zero (tez)

uint32_t update_cmp_on_tep: Whether to update compare value when timer count equals to peak (tep)

uint32_t update_cmp_on_sync: Whether to update compare value on sync event

struct mcpwm_comparator_config_t::[anonymous] flags: Extra configuration flags for comparator

struct mcpwm_comparator_event_callbacks_t

Group of supported MCPWM compare event callbacks.

Note

The callbacks are all running under ISR environment

Public Members

mcpwm_compare_event_cb_t on_reach: ISR callback function which would be invoked when counter reaches compare value

Header File

components/driver/include/driver/mcpwm_gen.h

Functions

esp_err_t mcpwm_new_generator(mcpwm_oper_handle_t oper, const mcpwm_generator_config_t *config, mcpwm_gen_handle_t *ret_gen)

Allocate MCPWM generator from given operator.

Parameters

oper – [in] MCPWM operator, allocated by mcpwm_new_operator()
config – [in] MCPWM generator configuration
ret_gen – [out] Returned MCPWM generator

Returns

ESP_OK: Create MCPWM generator successfully
ESP_ERR_INVALID_ARG: Create MCPWM generator failed because of invalid argument
ESP_ERR_NO_MEM: Create MCPWM generator failed because out of memory
ESP_ERR_NOT_FOUND: Create MCPWM generator failed because can’t find free resource
ESP_FAIL: Create MCPWM generator failed because of other error

esp_err_t mcpwm_del_generator(mcpwm_gen_handle_t gen)

Delete MCPWM generator.

Parameters

gen – [in] MCPWM generator handle, allocated by mcpwm_new_generator()

Returns

ESP_OK: Delete MCPWM generator successfully
ESP_ERR_INVALID_ARG: Delete MCPWM generator failed because of invalid argument
ESP_FAIL: Delete MCPWM generator failed because of other error

esp_err_t mcpwm_generator_set_force_level(mcpwm_gen_handle_t gen, int level, bool hold_on)

Set force level for MCPWM generator.

Note

The force level will be applied to the generator immediately, regardless any other events that would change the generator’s behaviour.

Note

If the hold_on is true, the force level will retain forever, until user removes the force level by setting the force level to -1.

Note

If the hold_on is false, the force level can be overridden by the next event action.

Parameters

gen – [in] MCPWM generator handle, allocated by mcpwm_new_generator()
level – [in] GPIO level to be applied to MCPWM generator, specially, -1 means to remove the force level
hold_on – [in] Whether the forced PWM level should retain (i.e. will remain unchanged until manually remove the force level)

Returns

ESP_OK: Set force level for MCPWM generator successfully
ESP_ERR_INVALID_ARG: Set force level for MCPWM generator failed because of invalid argument
ESP_FAIL: Set force level for MCPWM generator failed because of other error

esp_err_t mcpwm_generator_set_actions_on_timer_event(mcpwm_gen_handle_t gen, mcpwm_gen_timer_event_action_t ev_act, ...)

Set generator actions on different MCPWM timer events.

Parameters

gen – [in] MCPWM generator handle, allocated by mcpwm_new_generator()
ev_act – [in] MCPWM timer event action list, must be terminated by MCPWM_GEN_TIMER_EVENT_ACTION_END()

Returns

ESP_OK: Set generator actions successfully
ESP_ERR_INVALID_ARG: Set generator actions failed because of invalid argument
ESP_ERR_INVALID_STATE: Set generator actions failed because of timer is not connected to operator
ESP_FAIL: Set generator actions failed because of other error

esp_err_t mcpwm_generator_set_actions_on_compare_event(mcpwm_gen_handle_t generator, mcpwm_gen_compare_event_action_t ev_act, ...)

Set generator actions on different MCPWM compare events.

Parameters

generator – [in] MCPWM generator handle, allocated by mcpwm_new_generator()
ev_act – [in] MCPWM compare event action list, must be terminated by MCPWM_GEN_COMPARE_EVENT_ACTION_END()

Returns

ESP_OK: Set generator actions successfully
ESP_ERR_INVALID_ARG: Set generator actions failed because of invalid argument
ESP_FAIL: Set generator actions failed because of other error

esp_err_t mcpwm_generator_set_actions_on_brake_event(mcpwm_gen_handle_t generator, mcpwm_gen_brake_event_action_t ev_act, ...)

Set generator actions on different MCPWM brake events.

Parameters

generator – [in] MCPWM generator handle, allocated by mcpwm_new_generator()
ev_act – [in] MCPWM brake event action list, must be terminated by MCPWM_GEN_BRAKE_EVENT_ACTION_END()

Returns

ESP_OK: Set generator actions successfully
ESP_ERR_INVALID_ARG: Set generator actions failed because of invalid argument
ESP_FAIL: Set generator actions failed because of other error

esp_err_t mcpwm_generator_set_dead_time(mcpwm_gen_handle_t in_generator, mcpwm_gen_handle_t out_generator, const mcpwm_dead_time_config_t *config)

Set dead time for MCPWM generator.

Parameters

in_generator – [in] MCPWM generator, before adding the dead time
out_generator – [in] MCPWM generator, after adding the dead time
config – [in] MCPWM dead time configuration

Returns

ESP_OK: Set dead time for MCPWM generator successfully
ESP_ERR_INVALID_ARG: Set dead time for MCPWM generator failed because of invalid argument
ESP_FAIL: Set dead time for MCPWM generator failed because of other error

Structures

struct mcpwm_generator_config_t

MCPWM generator configuration.

Public Members

int gen_gpio_num: The GPIO number used to output the PWM signal

uint32_t invert_pwm: Whether to invert the PWM signal (done by GPIO matrix)

uint32_t io_loop_back: For debug/test, the signal output from the GPIO will be fed to the input path as well

struct mcpwm_generator_config_t::[anonymous] flags: Extra configuration flags for generator

struct mcpwm_gen_timer_event_action_t

Generator action on specific timer event.

Public Members

mcpwm_timer_direction_t direction: Timer direction

mcpwm_timer_event_t event: Timer event

mcpwm_generator_action_t action: Generator action should perform

struct mcpwm_gen_compare_event_action_t

Generator action on specific comparator event.

Public Members

mcpwm_timer_direction_t direction: Timer direction

mcpwm_cmpr_handle_t comparator: Comparator handle

mcpwm_generator_action_t action: Generator action should perform

struct mcpwm_gen_brake_event_action_t

Generator action on specific brake event.

Public Members

mcpwm_timer_direction_t direction: Timer direction

mcpwm_operator_brake_mode_t brake_mode: Brake mode

mcpwm_generator_action_t action: Generator action should perform

struct mcpwm_dead_time_config_t

MCPWM dead time configuration structure.

Public Members

uint32_t posedge_delay_ticks: delay time applied to rising edge, 0 means no rising delay time

uint32_t negedge_delay_ticks: delay time applied to falling edge, 0 means no falling delay time

uint32_t invert_output: Invert the signal after applied the dead time

struct mcpwm_dead_time_config_t::[anonymous] flags: Extra flags for dead time configuration

Macros

MCPWM_GEN_TIMER_EVENT_ACTION(dir, ev, act): Help macros to construct a mcpwm_gen_timer_event_action_t entry.

MCPWM_GEN_TIMER_EVENT_ACTION_END()

MCPWM_GEN_COMPARE_EVENT_ACTION(dir, cmp, act): Help macros to construct a mcpwm_gen_compare_event_action_t entry.

MCPWM_GEN_COMPARE_EVENT_ACTION_END()

MCPWM_GEN_BRAKE_EVENT_ACTION(dir, mode, act): Help macros to construct a mcpwm_gen_brake_event_action_t entry.

MCPWM_GEN_BRAKE_EVENT_ACTION_END()

Header File

components/driver/include/driver/mcpwm_fault.h

Functions

esp_err_t mcpwm_new_gpio_fault(const mcpwm_gpio_fault_config_t *config, mcpwm_fault_handle_t *ret_fault)

Create MCPWM GPIO fault.

Parameters

config – [in] MCPWM GPIO fault configuration
ret_fault – [out] Returned GPIO fault handle

Returns

ESP_OK: Create MCPWM GPIO fault successfully
ESP_ERR_INVALID_ARG: Create MCPWM GPIO fault failed because of invalid argument
ESP_ERR_NO_MEM: Create MCPWM GPIO fault failed because out of memory
ESP_ERR_NOT_FOUND: Create MCPWM GPIO fault failed because can’t find free resource
ESP_FAIL: Create MCPWM GPIO fault failed because of other error

esp_err_t mcpwm_new_soft_fault(const mcpwm_soft_fault_config_t *config, mcpwm_fault_handle_t *ret_fault)

Create MCPWM software fault.

Parameters

config – [in] MCPWM software fault configuration
ret_fault – [out] Returned software fault handle

Returns

ESP_OK: Create MCPWM software fault successfully
ESP_ERR_INVALID_ARG: Create MCPWM software fault failed because of invalid argument
ESP_ERR_NO_MEM: Create MCPWM software fault failed because out of memory
ESP_FAIL: Create MCPWM software fault failed because of other error

esp_err_t mcpwm_del_fault(mcpwm_fault_handle_t fault)

Delete MCPWM fault.

Parameters

fault – [in] MCPWM fault handle allocated by mcpwm_new_gpio_fault() or mcpwm_new_soft_fault()

Returns

ESP_OK: Delete MCPWM fault successfully
ESP_ERR_INVALID_ARG: Delete MCPWM fault failed because of invalid argument
ESP_FAIL: Delete MCPWM fault failed because of other error

esp_err_t mcpwm_soft_fault_activate(mcpwm_fault_handle_t fault)

Activate the software fault, trigger the fault event for once.

Parameters

fault – [in] MCPWM soft fault, allocated by mcpwm_new_soft_fault()

Returns

ESP_OK: Trigger MCPWM software fault event successfully
ESP_ERR_INVALID_ARG: Trigger MCPWM software fault event failed because of invalid argument
ESP_FAIL: Trigger MCPWM software fault event failed because of other error

esp_err_t mcpwm_fault_register_event_callbacks(mcpwm_fault_handle_t fault, const mcpwm_fault_event_callbacks_t *cbs, void *user_data)

Set event callbacks for MCPWM fault.

Parameters

fault – [in] MCPWM GPIO fault handle, allocated by mcpwm_new_gpio_fault()
cbs – [in] Group of callback functions
user_data – [in] User data, which will be passed to callback functions directly

Returns

ESP_OK: Set event callbacks successfully
ESP_ERR_INVALID_ARG: Set event callbacks failed because of invalid argument
ESP_FAIL: Set event callbacks failed because of other error

Structures

struct mcpwm_gpio_fault_config_t

MCPWM GPIO fault configuration structure.

Public Members

int group_id: In which MCPWM group that the GPIO fault belongs to

int gpio_num: GPIO used by the fault signal

uint32_t active_level: On which level the fault signal is treated as active

uint32_t io_loop_back: For debug/test, the signal output from the GPIO will be fed to the input path as well

uint32_t pull_up: Whether to pull up internally

uint32_t pull_down: Whether to pull down internally

struct mcpwm_gpio_fault_config_t::[anonymous] flags: Extra configuration flags for GPIO fault

struct mcpwm_soft_fault_config_t: MCPWM software fault configuration structure.

struct mcpwm_fault_event_callbacks_t

Group of supported MCPWM fault event callbacks.

Note

The callbacks are all running under ISR environment

Public Members

mcpwm_fault_event_cb_t on_fault_enter: ISR callback function that would be invoked when fault signal becomes active

mcpwm_fault_event_cb_t on_fault_exit: ISR callback function that would be invoked when fault signal becomes inactive

Header File

components/driver/include/driver/mcpwm_sync.h

Functions

esp_err_t mcpwm_new_timer_sync_src(mcpwm_timer_handle_t timer, const mcpwm_timer_sync_src_config_t *config, mcpwm_sync_handle_t *ret_sync)

Create MCPWM timer sync source.

Parameters

timer – [in] MCPWM timer handle, allocated by mcpwm_new_timer()
config – [in] MCPWM timer sync source configuration
ret_sync – [out] Returned MCPWM sync handle

Returns

ESP_OK: Create MCPWM timer sync source successfully
ESP_ERR_INVALID_ARG: Create MCPWM timer sync source failed because of invalid argument
ESP_ERR_NO_MEM: Create MCPWM timer sync source failed because out of memory
ESP_ERR_INVALID_STATE: Create MCPWM timer sync source failed because the timer has created a sync source before
ESP_FAIL: Create MCPWM timer sync source failed because of other error

esp_err_t mcpwm_new_gpio_sync_src(const mcpwm_gpio_sync_src_config_t *config, mcpwm_sync_handle_t *ret_sync)

Create MCPWM GPIO sync source.

Parameters

config – [in] MCPWM GPIO sync source configuration
ret_sync – [out] Returned MCPWM GPIO sync handle

Returns

ESP_OK: Create MCPWM GPIO sync source successfully
ESP_ERR_INVALID_ARG: Create MCPWM GPIO sync source failed because of invalid argument
ESP_ERR_NO_MEM: Create MCPWM GPIO sync source failed because out of memory
ESP_ERR_NOT_FOUND: Create MCPWM GPIO sync source failed because can’t find free resource
ESP_FAIL: Create MCPWM GPIO sync source failed because of other error

esp_err_t mcpwm_new_soft_sync_src(const mcpwm_soft_sync_config_t *config, mcpwm_sync_handle_t *ret_sync)

Create MCPWM software sync source.

Parameters

config – [in] MCPWM software sync source configuration
ret_sync – [out] Returned software sync handle

Returns

ESP_OK: Create MCPWM software sync successfully
ESP_ERR_INVALID_ARG: Create MCPWM software sync failed because of invalid argument
ESP_ERR_NO_MEM: Create MCPWM software sync failed because out of memory
ESP_FAIL: Create MCPWM software sync failed because of other error

esp_err_t mcpwm_del_sync_src(mcpwm_sync_handle_t sync)

Delete MCPWM sync source.

Parameters

sync – [in] MCPWM sync handle, allocated by mcpwm_new_timer_sync_src() or mcpwm_new_gpio_sync_src() or mcpwm_new_soft_sync_src()

Returns

ESP_OK: Delete MCPWM sync source successfully
ESP_ERR_INVALID_ARG: Delete MCPWM sync source failed because of invalid argument
ESP_FAIL: Delete MCPWM sync source failed because of other error

esp_err_t mcpwm_soft_sync_activate(mcpwm_sync_handle_t sync)

Activate the software sync, trigger the sync event for once.

Parameters

sync – [in] MCPWM soft sync handle, allocated by mcpwm_new_soft_sync_src()

Returns

ESP_OK: Trigger MCPWM software sync event successfully
ESP_ERR_INVALID_ARG: Trigger MCPWM software sync event failed because of invalid argument
ESP_FAIL: Trigger MCPWM software sync event failed because of other error

Structures

struct mcpwm_timer_sync_src_config_t

MCPWM timer sync source configuration.

Public Members

mcpwm_timer_event_t timer_event: Timer event, upon which MCPWM timer will generate the sync signal

uint32_t propagate_input_sync: The input sync signal would be routed to its sync output

struct mcpwm_timer_sync_src_config_t::[anonymous] flags: Extra configuration flags for timer sync source

struct mcpwm_gpio_sync_src_config_t

MCPWM GPIO sync source configuration.

Public Members

int group_id: MCPWM group ID

int gpio_num: GPIO used by sync source

uint32_t active_neg: Whether the sync signal is active on negedge, by default, the sync signal’s posedge is treated as active

uint32_t io_loop_back: For debug/test, the signal output from the GPIO will be fed to the input path as well

uint32_t pull_up: Whether to pull up internally

uint32_t pull_down: Whether to pull down internally

struct mcpwm_gpio_sync_src_config_t::[anonymous] flags: Extra configuration flags for GPIO sync source

struct mcpwm_soft_sync_config_t: MCPWM software sync configuration structure.

Header File

components/driver/include/driver/mcpwm_cap.h

Functions

esp_err_t mcpwm_new_capture_timer(const mcpwm_capture_timer_config_t *config, mcpwm_cap_timer_handle_t *ret_cap_timer)

Create MCPWM capture timer.

Parameters

config – [in] MCPWM capture timer configuration
ret_cap_timer – [out] Returned MCPWM capture timer handle

Returns

ESP_OK: Create MCPWM capture timer successfully
ESP_ERR_INVALID_ARG: Create MCPWM capture timer failed because of invalid argument
ESP_ERR_NO_MEM: Create MCPWM capture timer failed because out of memory
ESP_ERR_NOT_FOUND: Create MCPWM capture timer failed because can’t find free resource
ESP_FAIL: Create MCPWM capture timer failed because of other error

esp_err_t mcpwm_del_capture_timer(mcpwm_cap_timer_handle_t cap_timer)

Delete MCPWM capture timer.

Parameters

cap_timer – [in] MCPWM capture timer, allocated by mcpwm_new_capture_timer()

Returns

ESP_OK: Delete MCPWM capture timer successfully
ESP_ERR_INVALID_ARG: Delete MCPWM capture timer failed because of invalid argument
ESP_FAIL: Delete MCPWM capture timer failed because of other error

esp_err_t mcpwm_capture_timer_enable(mcpwm_cap_timer_handle_t cap_timer)

Enable MCPWM capture timer.

Parameters

cap_timer – [in] MCPWM capture timer handle, allocated by mcpwm_new_capture_timer()

Returns

ESP_OK: Enable MCPWM capture timer successfully
ESP_ERR_INVALID_ARG: Enable MCPWM capture timer failed because of invalid argument
ESP_ERR_INVALID_STATE: Enable MCPWM capture timer failed because timer is enabled already
ESP_FAIL: Enable MCPWM capture timer failed because of other error

esp_err_t mcpwm_capture_timer_disable(mcpwm_cap_timer_handle_t cap_timer)

Disable MCPWM capture timer.

Parameters

cap_timer – [in] MCPWM capture timer handle, allocated by mcpwm_new_capture_timer()

Returns

ESP_OK: Disable MCPWM capture timer successfully
ESP_ERR_INVALID_ARG: Disable MCPWM capture timer failed because of invalid argument
ESP_ERR_INVALID_STATE: Disable MCPWM capture timer failed because timer is disabled already
ESP_FAIL: Disable MCPWM capture timer failed because of other error

esp_err_t mcpwm_capture_timer_start(mcpwm_cap_timer_handle_t cap_timer)

Start MCPWM capture timer.

Parameters

cap_timer – [in] MCPWM capture timer, allocated by mcpwm_new_capture_timer()

Returns

ESP_OK: Start MCPWM capture timer successfully
ESP_ERR_INVALID_ARG: Start MCPWM capture timer failed because of invalid argument
ESP_FAIL: Start MCPWM capture timer failed because of other error

esp_err_t mcpwm_capture_timer_stop(mcpwm_cap_timer_handle_t cap_timer)

Start MCPWM capture timer.

Parameters

cap_timer – [in] MCPWM capture timer, allocated by mcpwm_new_capture_timer()

Returns

ESP_OK: Stop MCPWM capture timer successfully
ESP_ERR_INVALID_ARG: Stop MCPWM capture timer failed because of invalid argument
ESP_FAIL: Stop MCPWM capture timer failed because of other error

esp_err_t mcpwm_capture_timer_set_phase_on_sync(mcpwm_cap_timer_handle_t cap_timer, const mcpwm_capture_timer_sync_phase_config_t *config)

Set sync phase for MCPWM capture timer.

Parameters

cap_timer – [in] MCPWM capture timer, allocated by mcpwm_new_capture_timer()
config – [in] MCPWM capture timer sync phase configuration

Returns

ESP_OK: Set sync phase for MCPWM capture timer successfully
ESP_ERR_INVALID_ARG: Set sync phase for MCPWM capture timer failed because of invalid argument
ESP_FAIL: Set sync phase for MCPWM capture timer failed because of other error

esp_err_t mcpwm_new_capture_channel(mcpwm_cap_timer_handle_t cap_timer, const mcpwm_capture_channel_config_t *config, mcpwm_cap_channel_handle_t *ret_cap_channel)

Create MCPWM capture channel.

Parameters

cap_timer – [in] MCPWM capture timer, allocated by mcpwm_new_capture_timer(), will be connected to the new capture channel
config – [in] MCPWM capture channel configuration
ret_cap_channel – [out] Returned MCPWM capture channel

Returns

ESP_OK: Create MCPWM capture channel successfully
ESP_ERR_INVALID_ARG: Create MCPWM capture channel failed because of invalid argument
ESP_ERR_NO_MEM: Create MCPWM capture channel failed because out of memory
ESP_ERR_NOT_FOUND: Create MCPWM capture channel failed because can’t find free resource
ESP_FAIL: Create MCPWM capture channel failed because of other error

esp_err_t mcpwm_del_capture_channel(mcpwm_cap_channel_handle_t cap_channel)

Delete MCPWM capture channel.

Parameters

cap_channel – [in] MCPWM capture channel handle, allocated by mcpwm_new_capture_channel()

Returns

ESP_OK: Delete MCPWM capture channel successfully
ESP_ERR_INVALID_ARG: Delete MCPWM capture channel failed because of invalid argument
ESP_FAIL: Delete MCPWM capture channel failed because of other error

esp_err_t mcpwm_capture_channel_register_event_callbacks(mcpwm_cap_channel_handle_t cap_channel, const mcpwm_capture_event_callbacks_t *cbs, void *user_data)

Set event callbacks for MCPWM capture channel.

Parameters

cap_channel – [in] MCPWM capture channel handle, allocated by mcpwm_new_capture_channel()
cbs – [in] Group of callback functions
user_data – [in] User data, which will be passed to callback functions directly

Returns

ESP_OK: Set event callbacks successfully
ESP_ERR_INVALID_ARG: Set event callbacks failed because of invalid argument
ESP_FAIL: Set event callbacks failed because of other error

esp_err_t mcpwm_capture_channel_trigger_soft_catch(mcpwm_cap_channel_handle_t cap_channel)

Trigger a catch by software.

Parameters

cap_channel – [in] MCPWM capture channel handle, allocated by mcpwm_new_capture_channel()

Returns

ESP_OK: Trigger software catch successfully
ESP_ERR_INVALID_ARG: Trigger software catch failed because of invalid argument
ESP_FAIL: Trigger software catch failed because of other error

Structures

struct mcpwm_capture_timer_config_t

MCPWM capture timer configuration structure.

Public Members

int group_id: Specify from which group to allocate the capture timer

mcpwm_capture_clock_source_t clk_src: MCPWM capture timer clock source

struct mcpwm_capture_timer_sync_phase_config_t

MCPWM Capture timer sync phase configuration.

Public Members

mcpwm_sync_handle_t sync_src: The sync event source

uint32_t count_value: The count value that should lock to upon sync event

mcpwm_timer_direction_t direction: The count direction that should lock to upon sync event

struct mcpwm_capture_channel_config_t

MCPWM capture channel configuration structure.

Public Members

int gpio_num: GPIO used capturing input signal

uint32_t prescale: Prescale of input signal, effective frequency = cap_input_clk/prescale

uint32_t pos_edge: Whether to capture on positive edge

uint32_t neg_edge: Whether to capture on negative edge

uint32_t pull_up: Whether to pull up internally

uint32_t pull_down: Whether to pull down internally

uint32_t invert_cap_signal: Invert the input capture signal

uint32_t io_loop_back: For debug/test, the signal output from the GPIO will be fed to the input path as well

struct mcpwm_capture_channel_config_t::[anonymous] flags: Extra configuration flags for capture channel

struct mcpwm_capture_event_callbacks_t

Group of supported MCPWM capture event callbacks.

Note

The callbacks are all running under ISR environment

Public Members

mcpwm_capture_event_cb_t on_cap: Callback function that would be invoked when capture event occurred

Header File

components/driver/include/driver/mcpwm_types.h

Structures

struct mcpwm_timer_event_data_t

MCPWM timer event data.

Public Members

uint32_t count_value: MCPWM timer count value

mcpwm_timer_direction_t direction: MCPWM timer count direction

struct mcpwm_brake_event_data_t: MCPWM brake event data.

struct mcpwm_fault_event_data_t: MCPWM fault event data.

struct mcpwm_compare_event_data_t

MCPWM compare event data.

Public Members

uint32_t compare_ticks: Compare value

mcpwm_timer_direction_t direction: Count direction

struct mcpwm_capture_event_data_t

MCPWM capture event data.

Public Members

uint32_t cap_value: Captured value

mcpwm_capture_edge_t cap_edge: Capture edge

Type Definitions

typedef struct mcpwm_timer_t *mcpwm_timer_handle_t: Type of MCPWM timer handle.

typedef struct mcpwm_oper_t *mcpwm_oper_handle_t: Type of MCPWM operator handle.

typedef struct mcpwm_cmpr_t *mcpwm_cmpr_handle_t: Type of MCPWM comparator handle.

typedef struct mcpwm_gen_t *mcpwm_gen_handle_t: Type of MCPWM generator handle.

typedef struct mcpwm_fault_t *mcpwm_fault_handle_t: Type of MCPWM fault handle.

typedef struct mcpwm_sync_t *mcpwm_sync_handle_t: Type of MCPWM sync handle.

typedef struct mcpwm_cap_timer_t *mcpwm_cap_timer_handle_t: Type of MCPWM capture timer handle.

typedef struct mcpwm_cap_channel_t *mcpwm_cap_channel_handle_t: Type of MCPWM capture channel handle.

typedef bool (*mcpwm_timer_event_cb_t)(mcpwm_timer_handle_t timer, const mcpwm_timer_event_data_t *edata, void *user_ctx)

MCPWM timer event callback function.

Param timer: [in] MCPWM timer handle
Param edata: [in] MCPWM timer event data, fed by driver
Param user_ctx: [in] User data, set in mcpwm_timer_register_event_callbacks()
Return: Whether a high priority task has been waken up by this function

typedef bool (*mcpwm_brake_event_cb_t)(mcpwm_oper_handle_t operator, const mcpwm_brake_event_data_t *edata, void *user_ctx)

MCPWM operator brake event callback function.

Param operator: [in] MCPWM operator handle
Param edata: [in] MCPWM brake event data, fed by driver
Param user_ctx: [in] User data, set in mcpwm_operator_register_event_callbacks()
Return: Whether a high priority task has been waken up by this function

typedef bool (*mcpwm_fault_event_cb_t)(mcpwm_fault_handle_t fault, const mcpwm_fault_event_data_t *ev_data, void *user_ctx)

MCPWM fault event callback function.

Param fault: MCPWM fault handle
Param ev_data: MCPWM fault event data, fed by driver
Param user_ctx: User data, set in mcpwm_fault_register_event_callbacks()
Return: whether a task switch is needed after the callback returns

typedef bool (*mcpwm_compare_event_cb_t)(mcpwm_cmpr_handle_t comparator, const mcpwm_compare_event_data_t *edata, void *user_ctx)

MCPWM comparator event callback function.

Param comparator: MCPWM comparator handle
Param edata: MCPWM comparator event data, fed by driver
Param user_ctx: User data, set in mcpwm_comparator_register_event_callbacks()
Return: Whether a high priority task has been waken up by this function

typedef bool (*mcpwm_capture_event_cb_t)(mcpwm_cap_channel_handle_t cap_channel, const mcpwm_capture_event_data_t *edata, void *user_ctx)

MCPWM capture event callback function.

Param cap_channel: MCPWM capture channel handle
Param ev_data: MCPWM capture event data, fed by driver
Param user_ctx: User data, set in mcpwm_capture_channel_register_event_callbacks()
Return: Whether a high priority task has been waken up by this function

Header File

components/hal/include/hal/mcpwm_types.h

Type Definitions

typedef soc_periph_mcpwm_timer_clk_src_t mcpwm_timer_clock_source_t: MCPWM timer clock source.

typedef soc_periph_mcpwm_capture_clk_src_t mcpwm_capture_clock_source_t: MCPWM capture clock source.

Enumerations

enum mcpwm_timer_direction_t

MCPWM timer count direction.

Values:

enumerator MCPWM_TIMER_DIRECTION_UP: Counting direction: Increase

enumerator MCPWM_TIMER_DIRECTION_DOWN: Counting direction: Decrease

enum mcpwm_timer_event_t

MCPWM timer events.

Values:

enumerator MCPWM_TIMER_EVENT_EMPTY: MCPWM timer counts to zero (i.e. counter is empty)

enumerator MCPWM_TIMER_EVENT_FULL: MCPWM timer counts to peak (i.e. counter is full)

enumerator MCPWM_TIMER_EVENT_INVALID: MCPWM timer invalid event

enum mcpwm_timer_count_mode_t

MCPWM timer count modes.

Values:

enumerator MCPWM_TIMER_COUNT_MODE_PAUSE: MCPWM timer paused

enumerator MCPWM_TIMER_COUNT_MODE_UP: MCPWM timer counting up

enumerator MCPWM_TIMER_COUNT_MODE_DOWN: MCPWM timer counting down

enumerator MCPWM_TIMER_COUNT_MODE_UP_DOWN: MCPWM timer counting up and down

enum mcpwm_timer_start_stop_cmd_t

MCPWM timer commands, specify the way to start or stop the timer.

Values:

enumerator MCPWM_TIMER_STOP_EMPTY: MCPWM timer stops when next count reaches zero

enumerator MCPWM_TIMER_STOP_FULL: MCPWM timer stops when next count reaches peak

enumerator MCPWM_TIMER_START_NO_STOP: MCPWM timer starts couting, and don’t stop until received stop command

enumerator MCPWM_TIMER_START_STOP_EMPTY: MCPWM timer starts counting and stops when next count reaches zero

enumerator MCPWM_TIMER_START_STOP_FULL: MCPWM timer starts counting and stops when next count reaches peak

enum mcpwm_generator_action_t

MCPWM generator actions.

Values:

enumerator MCPWM_GEN_ACTION_KEEP: Generator action: Keep the same level

enumerator MCPWM_GEN_ACTION_LOW: Generator action: Force to low level

enumerator MCPWM_GEN_ACTION_HIGH: Generator action: Force to high level

enumerator MCPWM_GEN_ACTION_TOGGLE: Generator action: Toggle level

enum mcpwm_operator_brake_mode_t

MCPWM operator brake mode.

Values:

enumerator MCPWM_OPER_BRAKE_MODE_CBC: Brake mode: CBC (cycle by cycle)

enumerator MCPWM_OPER_BRAKE_MODE_OST: Brake mode, OST (one shot)

enumerator MCPWM_OPER_BRAKE_MODE_INVALID: MCPWM operator invalid brake mode

enum mcpwm_capture_edge_t

MCPWM capture edge.

Values:

enumerator MCPWM_CAP_EDGE_POS: Capture on the positive edge

enumerator MCPWM_CAP_EDGE_NEG: Capture on the negative edge

1(1,2,3,4,5,6,7): Different ESP chip series might have different number of MCPWM resources (e.g. groups, timers, comparators, operators, generators and so on). Please refer to the [TRM] for details. The driver won’t forbid you from applying for more MCPWM resources, but it will return error when there’s no hardware resources available. Please always check the return value when doing Resource Allocation.
2: Callback function and the sub-functions invoked by itself should also be placed in IRAM, users need to take care of this by themselves.

Provide feedback about this document