MCPWM 操作器：组装输出级

操作器位于定时器与生成器之间，管理比较器、生成器动作、制动、死区路由和载波调制。一个定时器可驱动同组的多个操作器，而一个操作器只连接一个定时器。

如果把定时器看成时钟源，操作器就是一套输出级的资源容器。它让多个输出共享同一时间基准，同时把保护、死区和载波这类功率级特性收拢到一个地方管理。

连接基本模块 

操作器必须与定时器在同一组。先通过 mcpwm_operator_connect_timer() 创建并连接操作器；连接前，生成器不能使用定时器事件。

mcpwm_oper_handle_t oper = NULL;
mcpwm_operator_config_t oper_config = {
    .group_id = 0,
    .flags.update_gen_action_on_tez = true,
    .flags.update_dead_time_on_tez = true,
};
ESP_ERROR_CHECK(mcpwm_new_operator(&oper_config, &oper));
ESP_ERROR_CHECK(mcpwm_operator_connect_timer(oper, timer));

操作器配置很小，但有两个字段没有出现在示例中：

group_id — 操作器从哪个 MCPWM 组分配。它必须与定时器所在组一致，因为操作器只能连接同组内的定时器。
intr_priority — 制动事件回调使用的中断优先级。不设置（0）时由驱动选择较低优先级；当制动通知需要抢占其他中断时可适当提高。

flags 用于选择新的生成器动作和死区配置在何时生效。默认全部关闭，改动会立即生效——可能在 PWM 周期中间：

update_gen_action_on_tez、update_gen_action_on_tep 和 update_gen_action_on_sync — 将生成器动作的改动缓冲到计数归零、峰值或同步事件时。
update_dead_time_on_tez、update_dead_time_on_tep 和 update_dead_time_on_sync — 死区改动同样缓冲，更新点规则见死区。

对于运行中的功率级，应使用归零（tez）、峰值（tep）或同步点更新，以避免部分周期。

一个定时器，多个操作器 

同一定时器可驱动多个操作器，每个操作器产生不同的波形。这适用于多相逆变器或多个同频但独立占空比的电机。

反过来，一个操作器只能连接一个定时器，因此该操作器下的所有比较器和生成器天然共享同一时间基准。这正是同相、互补或成对输出容易实现的原因。

mcpwm_oper_handle_t oper_b = NULL;
mcpwm_operator_config_t oper_config_b = {
    .group_id = 0,
    .flags.update_gen_action_on_tez = true,
};
ESP_ERROR_CHECK(mcpwm_new_operator(&oper_config_b, &oper_b));
ESP_ERROR_CHECK(mcpwm_operator_connect_timer(oper_b, timer));
// 在 oper_b 下创建独立的比较器和生成器。

制动与安全输出 

操作器将故障转换为制动动作。应在启动 PWM 前配置生成器的制动状态，使故障路径完全由硬件驱动，避免软件延迟。

恢复策略 

CBC（逐周期）： 故障有效期间制动，并在配置的定时器归零或峰值处恢复，适合瞬态限流。
OST（单次）： 故障消失后仍保持制动，必须由软件显式恢复，适合互锁或严重过流。

对于 CBC，设置 cbc_recover_on_tez 或 cbc_recover_on_tep，选择已清除故障后释放输出的边界。在边界恢复可避免在 PWM 周期中间重新导通开关。

警告

不要同时启用 cbc_recover_on_tez 和 cbc_recover_on_tep；应选择与波形和栅极驱动时序相匹配的边界。

故障连接 

将故障连接到操作器，然后为每个生成器指定制动模式下的状态。此例在两个计数方向将原始生成器置低，使用 OST 制动：

ESP_ERROR_CHECK(mcpwm_operator_set_brake_on_fault(oper,
    &(mcpwm_brake_config_t) {
        .fault = fault,
        .brake_mode = MCPWM_OPER_BRAKE_MODE_OST,
    }));

ESP_ERROR_CHECK(mcpwm_generator_set_action_on_brake_event(
    generator, MCPWM_GEN_BRAKE_EVENT_ACTION(
        MCPWM_TIMER_DIRECTION_UP, MCPWM_OPER_BRAKE_MODE_OST,
        MCPWM_GEN_ACTION_LOW)));
ESP_ERROR_CHECK(mcpwm_generator_set_action_on_brake_event(
    generator, MCPWM_GEN_BRAKE_EVENT_ACTION(
        MCPWM_TIMER_DIRECTION_DOWN, MCPWM_OPER_BRAKE_MODE_OST,
        MCPWM_GEN_ACTION_LOW)));

半桥必须为两个生成器都配置相同的制动动作。逻辑低电平可能被死区、GPIO 矩阵或外部电路反相，因此应在栅极驱动器处确认实际安全状态。

生成器级故障动作与操作器制动的区别在于：前者适合单个输出的即时边沿响应，后者负责整个输出级的安全状态、锁存行为和恢复策略。主保护路径通常应优先使用操作器制动。

OST 故障恢复 

CBC 在故障消失后在配置的边界自动恢复。OST 恢复前，先移除并确认故障根因已经消失，然后调用：

ESP_ERROR_CHECK(mcpwm_operator_recover_from_fault(oper, fault));

故障仍有效时该调用会失败。

PWM 运行期间故障被触发。CBC 在故障有效期间将输出保持在制动电平，并在下一个周期边界恢复；OST 则保持锁存直至软件恢复。 — CBC 仅在故障有效期间制动，并在下一个周期边界恢复；OST 保持锁存直至软件恢复。

制动事件回调 

操作器可通过 on_brake_cbc 和 on_brake_ost 回调报告制动事件。二者均在 ISR 上下文运行，只应用于通知，不应用于阻塞式恢复。

mcpwm_operator_event_callbacks_t cbs = {
    .on_brake_cbc = my_brake_cbc_cb,
    .on_brake_ost = my_brake_ost_cb,
};
ESP_ERROR_CHECK(mcpwm_operator_register_event_callbacks(oper, &cbs, NULL));

载波调制 

载波调制在操作器的 PWM 输出上叠加高频载波，常用于变压器隔离式栅极驱动：即使基础 PWM 保持 100% 占空比，调制后仍有可穿过隔离栅的跳变。应先完成基础 PWM 的配置；载波设置影响此操作器的所有生成器。

载波配置 

mcpwm_carrier_config_t carrier = {
    .clk_src = MCPWM_CARRIER_CLK_SRC_DEFAULT,
    .frequency_hz = 100000,
    .duty_cycle = 0.5f,
    .first_pulse_duration_us = 20,
};
ESP_ERROR_CHECK(mcpwm_operator_apply_carrier(oper, &carrier));

50% 占空比基础 PWM 的载波调制 — 100 kHz 载波与 50% 占空比基础 PWM 做与操作。首个脉冲被拉伸到 20 us（两个载波周期）；基础 PWM 为低电平时不做斩波。

载波参数 

clk_src 选择载波时钟源。默认指向一个内部 PLL 时钟（如 PLL_F160M），部分芯片还提供 RC_FAST 或 XTAL 作为备选。不同时钟源的分辨率与功耗不同；默认时钟源即可满足大多数应用，仅在需要避开某个时钟引入的噪声、PLL 精度不够，或对功耗有要求时，才需要手动指定。
frequency_hz 是载波频率；应选择同时满足隔离变压器、栅极驱动器、开关损耗预算和目标芯片时钟分辨率的值。
duty_cycle 只能取硬件支持的 0.125、0.25、0.375、0.5、0.625、0.75 或 0.875，而非任意比例。
first_pulse_duration_us 控制调制开始后的首个脉冲。它必须非零，且至少为一个载波周期。较长的首脉冲可帮助在感性隔离路径中建立电流，但必须保持在栅极驱动系统允许范围内。
invert_before_modulate 改变原始 PWM 极性，invert_after_modulate 改变调制后极性。

不需要载波调制时，向 mcpwm_operator_apply_carrier() 传入 NULL 配置即可禁用。

API 参考 

MCPWM 操作器驱动函数 

Header File

components/esp_driver_mcpwm/include/driver/mcpwm_oper.h
This header file can be included with:
#include "driver/mcpwm_oper.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_operator(const mcpwm_operator_config_t *config, mcpwm_oper_handle_t *ret_oper)

Create MCPWM operator.

参数:

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

返回:

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.

参数:

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

返回:

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.

参数:

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

返回:

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 oper, const mcpwm_brake_config_t *config)

Set brake method for MCPWM operator.

参数:

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

返回:

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 oper, mcpwm_fault_handle_t fault)

Try to make the operator recover from fault.

备注

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

参数:

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

返回:

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.

备注

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

参数:

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

返回:

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.

参数:

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

返回:

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

int intr_priority: MCPWM operator interrupt priority, if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3)

struct mcpwm_operator_config_t::extra_mcpwm_operator_flags flags: Extra configuration flags for operator

struct extra_mcpwm_operator_flags

Extra configuration flags for operator.

Public Members

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_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 flags: Extra flags for brake configuration

struct mcpwm_operator_event_callbacks_t

Group of supported MCPWM operator event callbacks.

备注

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

mcpwm_carrier_clock_source_t clk_src: MCPWM carrier clock source

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 flags: Extra flags for carrier configuration

此文档对您有帮助吗？

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

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