# MCPWM 故障：将保护信号接入 MCPWM

故障对象表示异常条件。GPIO 故障适合过流比较器等硬件信号；软件故障可让应用逻辑触发同一保护路径。随后使用操作器 制动 定义输出响应。

故障模块存在的目的，是让保护路径尽可能不依赖软件轮询或任务调度。对于电机驱动和功率变换器，过流、互锁或急停通常要求在硬件路径里先把输出拉到安全状态，再由软件决定如何记录和恢复。

## 创建低电平有效 GPIO 故障源

故障源必须和将使用它的操作器位于同一组。引脚上拉/下拉属于独立 GPIO 配置；MCPWM 驱动不会为故障 GPIO 引脚自动使能内部上拉/下拉。如果故障信号在其他状态下并不驱动引脚电平，请自行用 `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));

GPIO 故障配置中有几个字段值得了解：

- `group_id` — 故障所属的 MCPWM 组。必须与使用该故障的操作器所在组一致。

- `gpio_num` — 承载故障信号的 GPIO。

- `active_level` — 何种电平视为有效。示例使用 `0`，即故障为低有效；无故障时引脚上拉方向应使其保持非有效（高电平）。驱动不会改动引脚的上下拉配置，请按需调用 `gpio_set_pull_mode()` 选择上拉或下拉。

- `intr_priority` — 故障事件回调使用的中断优先级。不设置（`0`）时由驱动选择较低优先级。

## 创建软件故障

对于应用检测到的条件，可创建 `mcpwm_new_soft_fault()`，并在条件发生时调用 `mcpwm_soft_fault_activate()`，而无需接入 GPIO 故障引脚。激活是一次性的故障事件，输出策略仍由操作器 制动机制 决定。

备注

激活前必须先用 `mcpwm_operator_set_brake_on_fault()` 将软件故障绑定到某个操作器。驱动在 `mcpwm_new_soft_fault()` 时并不会关联操作器；操作器关联及其制动模式都由该绑定调用设置，且一个软件故障只能绑定一个操作器。在绑定前调用 `mcpwm_soft_fault_activate()` 属于未定义行为。

## 故障作为生成器动作的触发源

GPIO 故障也可通过 `mcpwm_generator_set_action_on_fault_event()` 直接触发生成器动作。这是局部的边沿级响应——在故障边沿改变输出，但不会锁存安全状态。如需带恢复的持续制动，应使用操作器 制动机制。

机制 | 行为 | 适合场景
--- | --- | ---
生成器故障动作 | 单个输出在故障边沿立即改变 | 某一路输出的局部快速响应
操作器制动 | 为整个输出级定义安全状态、是否锁存和恢复策略 | 主保护路径、半桥/全桥安全关断

## 故障事件回调

`on_fault_enter` 和 `on_fault_exit` 回调报告 GPIO 故障跳变，且仅 GPIO 故障可用——驱动会拒绝在软件故障上注册这些回调。软件故障会在硬件中立即触发制动，不会产生回调。这些回调在 ISR 上下文执行。应只进行时间戳记录或使用 ISR 安全的方式通知任务，在任务中做日志和恢复决策。

    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 参考

### MCPWM 故障驱动函数

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

  参数:

    - config -- [in] MCPWM GPIO fault configuration

    - ret_fault -- [out] Returned GPIO fault handle

  返回:

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

  参数:

    - config -- [in] MCPWM software fault configuration

    - ret_fault -- [out] Returned software fault handle

  返回:

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

  参数:

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

  返回:

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

  参数:

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

  返回:

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

  备注

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

  参数:

    - 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

  返回:

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

  备注

  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

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。