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

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.