MCPWM Fault: Bring a Protection Signal into MCPWM

A fault object represents an abnormal condition. A GPIO fault is for a hardware signal such as an over-current comparator; a software fault lets application logic trigger the same protection route. Use the object with the operator brake to define the output response.

The purpose of the fault path is to make protection depend as little as possible on software polling or task scheduling. In motor drives and power converters, over-current, interlock, or emergency-stop conditions usually need hardware to force a safe output state first, then let software decide how to log and recover.

Create an active-low GPIO fault

Create the fault in the same group as the operator that will consume it. The pin's electrical pull configuration is separate GPIO setup, so make the inactive level unambiguous before starting the power stage. The MCPWM driver does not enable internal pull resistors for a GPIO fault pin; if the fault signal does not drive the pin in the inactive state, configure the pull direction yourself with gpio_set_pull_mode().

mcpwm_fault_handle_t fault = NULL;
mcpwm_gpio_fault_config_t fault_config = {
    .group_id = 0,
    .gpio_num = 4,
    .flags.active_level = 0,
};
ESP_ERROR_CHECK(mcpwm_new_gpio_fault(&fault_config, &fault));

The GPIO fault configuration has a few fields to consider:

  • group_id — the MCPWM group the fault belongs to. It must match the group of the operator consuming the fault.

  • gpio_num — the GPIO carrying the fault signal.

  • active_level — the level treated as active. The example uses 0, so the fault is active low; the pin's pull direction must keep it inactive (high) when nothing asserts the fault. The driver leaves the pad's pull configuration untouched, so call gpio_set_pull_mode() to select the pull-up/pull-down as appropriate.

  • intr_priority — the interrupt priority used by the fault event callbacks. Not setting it (0) lets the driver choose a low priority.

Create a software fault

For an application-detected condition, create mcpwm_new_soft_fault() and invoke mcpwm_soft_fault_activate() when the condition occurs, instead of wiring a GPIO fault pin. The activation is a one-time fault event; its output policy is still configured by the operator brake mechanism.

Note

Bind the soft fault to an operator with mcpwm_operator_set_brake_on_fault() before activating it. The driver does not attach the soft fault to an operator at mcpwm_new_soft_fault() time; the operator association and its brake mode are set by the bind call, and a soft fault can be bound to only one operator. Calling mcpwm_soft_fault_activate() before binding is undefined behavior.

Fault as a trigger for generator actions

A GPIO fault can also directly trigger a generator action via mcpwm_generator_set_action_on_fault_event(). This is a local edge-level response — it changes the output at the fault edge but does not latch a safe state. For persistent braking with recovery, use the operator brake mechanism.

Mechanism

Behavior

Best fit

Generator fault action

Immediately changes one output at the fault edge

Local fast reaction on a single output

Operator brake

Defines safe state, latching, and recovery policy

Primary protection path for a power stage

Fault event callbacks

The on_fault_enter and on_fault_exit callbacks report GPIO fault transitions and are only available for GPIO faults — the driver rejects registering them on a soft fault. Soft faults trigger the brake immediately in hardware, with no callback. The callbacks run in ISR context. Timestamp the event or notify a task with an ISR-safe primitive, then make logging and recovery decisions in the task.

mcpwm_fault_event_callbacks_t cbs = {
    .on_fault_enter = my_fault_enter_cb,
    .on_fault_exit = my_fault_exit_cb,
};
ESP_ERROR_CHECK(mcpwm_fault_register_event_callbacks(fault, &cbs, NULL));

API Reference

MCPWM Fault Driver Functions

Header File

  • components/esp_driver_mcpwm/include/driver/mcpwm_fault.h

  • This header file can be included with:

    #include "driver/mcpwm_fault.h"

  • This header file is a part of the API provided by the esp_driver_mcpwm component. To declare that your component depends on esp_driver_mcpwm, add the following to your CMakeLists.txt:

    REQUIRES esp_driver_mcpwm

    or

    PRIV_REQUIRES esp_driver_mcpwm

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.

Note

User can deregister a previously registered callback by calling this function and setting the callback member in the cbs structure to NULL.

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 intr_priority

MCPWM GPIO fault interrupt priority, if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3)

int gpio_num

GPIO used by the fault signal

struct mcpwm_gpio_fault_config_t::extra_mcpwm_gpio_fault_flags flags

Extra configuration flags for GPIO fault

struct extra_mcpwm_gpio_fault_flags

Extra configuration flags for GPIO fault.

Public Members

uint32_t active_level

On which level the fault signal is treated as active

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

Was this page helpful?