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

此文档对您有帮助吗？