ESP-IDF RMT 外设驱动完整指南:符号编码、载波调制与多通道同步传输
ESP-IDF RMT 外设驱动完整指南:符号编码、载波调制与多通道同步传输
导读
RMT(Remote Control Transceiver)是 ESP-IDF 中一个极具灵活性的通用收发外设,最初为红外收发而设计,凭借其灵活的数据格式被广泛扩展为通用时序信号发生器/采集器——从 NEC 红外遥控、WS2812 LED 灯带,到 DShot 电调协议、步进电机 S 曲线驱动均可胜任。本文以 ESP-IDF 官方文档 RMT API 参考 为主体,结合仓库内驱动源码(components/esp_driver_rmt)与示例工程,系统讲解 RMT 通道分配、符号(Symbol)编码、载波调制解调、事件回调、TX/RX 事务流程、多通道同步、编码器体系、电源管理与缓存安全等完整技术细节。读完本文,你将掌握 RMT 驱动的全部关键 API、配置项语义及其底层实现原理,可直接用于开发 IR 协议栈、时序信号生成等实际项目。
RMT 简介:从红外收发器到通用信号收发机
RMT 外设的硬件设计初衷是充当红外收发器,但由于其数据格式极其灵活,可以扩展为通用的收发机,用于发送或接收多种类型的信号。从网络分层角度看,RMT 硬件同时包含物理层和数据链路层:物理层定义了通信介质与比特信号的表示方式;数据链路层定义了 RMT 帧的格式。
RMT 帧中的最小数据单元称为 RMT Symbol(符号),在驱动中以 rmt_symbol_word_t 表示。不同 ESP 芯片系列拥有的 RMT 通道数量不同,每个通道可独立配置为发送器(TX)或接收器(RX)。
RMT 外设的典型应用场景包括:
- 以任意红外协议(如 NEC)发送或接收红外信号;
- 作为通用时序序列发生器;
- 在硬件控制的循环中发送信号,支持有限次或无限次循环;
- 多通道同时发送;
- 对输出信号进行载波调制,或从输入信号中解调载波。
RMT 符号(Symbol)的位布局
RMT 硬件以自己独有的模式定义数据。每个符号由两对值组成:每对值的第一个是 15 位数值,表示以 RMT tick 为单位的信号持续时间;第二个是 1 位数值,表示信号逻辑电平(高或低)。这与驱动头文件 components/esp_hal_rmt/include/hal/rmt_types.h#L30-L38 中 rmt_symbol_word_t 联合体的定义完全对应:
typedef union {
struct {
uint16_t duration0 : 15; /*!< Duration of level0 */
uint16_t level0 : 1; /*!< Level of the first part */
uint16_t duration1 : 15; /*!< Duration of level1 */
uint16_t level1 : 1; /*!< Level of the second part */
};
uint32_t val; /*!< Equivalent unsigned value for the RMT symbol */
} rmt_symbol_word_t;
也就是说,一个 32 位的 rmt_symbol_word_t 恰好描述了一段"先高/低电平持续 N 个 tick,再高/低电平持续 M 个 tick"的完整脉冲对,其图表定义源文件位于 docs/_static/diagrams/rmt/rmt_symbols.diag。
TX 与 RX 通道数据通路概览
RMT 发送通道的数据通路与控制通路(图表定义源见 docs/_static/diagrams/rmt/rmt_tx.diag):驱动将用户数据编码为 RMT 数据格式,随后 RMT 发送器根据编码产物生成波形;在信号路由到 GPIO 引脚之前,还可以选择将高频载波信号调制到消息信号上。
接收通道(图表定义源见 docs/_static/diagrams/rmt/rmt_rx.diag):RMT 接收器可将输入信号采样为 RMT 数据格式并存入内存;可以预先告知接收器输入信号的基本特征,从而识别停止条件、滤除毛刺与噪声;RMT 外设还支持从基带信号中解调高频载波。
资源分配:安装与卸载 RMT 通道
TX 与 RX 通道在驱动中统一由 rmt_channel_handle_t 句柄表示,驱动内部管理哪些通道可用,并在请求时分配空闲通道(句柄类型定义见 components/esp_driver_rmt/include/driver/rmt_types.h#L22)。
安装 RMT TX 通道
安装 TX 通道前需要提供配置结构体 rmt_tx_channel_config_t(完整定义见 components/esp_driver_rmt/include/driver/rmt_tx.h#L32-L49),各成员含义如下:
gpio_num:发送器使用的 GPIO 编号。clk_src:选择 RMT 通道的源时钟,可选时钟见rmt_clock_source_t。注意所选时钟也会被其他通道共用,因此在分配其他通道时(无论 TX 还是 RX)应保证该配置一致。不同时钟源对功耗的影响见下文"电源管理"小节。resolution_hz:内部 tick 计数器的分辨率。RMT 信号的时序参数均基于该 tick 计算。例如设为1 MHz时,1 个 tick = 1 µs。mem_block_symbols:根据是否启用 DMA 后端,含义略有不同:- 若通过
with_dma启用 DMA,该字段控制内部 DMA 缓冲区大小。为获得更高吞吐量和更小 CPU 开销,可设较大值(如1024)。 - 若不使用 DMA,该字段控制通道拥有的专用内存块大小,至少应为
SOC_RMT_MEM_WORDS_PER_CHANNEL。
- 若通过
trans_queue_depth:内部事务队列深度,队列越深,可积压的待处理事务越多。invert_out:决定在将 RMT 信号送到 GPIO 引脚前是否反转。with_dma:为通道启用 DMA 后端。使用 DMA 可将通道的大量工作负载从 CPU 卸载;但并非所有 ESP 芯片都支持 DMA 后端,开启前请查阅芯片 TRM 手册,否则可能遇到ESP_ERR_NOT_SUPPORTED错误。intr_priority:设置中断优先级。设为0时驱动使用低或中优先级中断(优先级可能为 1、2、3 之一);否则使用指定的优先级。请使用数字形式(1、2、3),不要使用位掩码形式((1<<1)、(1<<2)、(1<<3))。中断优先级一旦设定,在调用rmt_del_channel之前不可更改。allow_pd:配置驱动是否允许系统在 light sleep 模式下关断外设电源。进入睡眠前系统会备份 RMT 寄存器上下文,退出睡眠后恢复。关断外设可节省更多功耗,但代价是消耗更多内存保存寄存器上下文——这是功耗与内存的权衡。该配置依赖特定硬件特性,在不支持的芯片上启用会看到类似not able to power down in light sleep的错误信息。
配置结构体填充完毕后,调用 rmt_new_tx_channel 分配并初始化 TX 通道(实现见 components/esp_driver_rmt/src/rmt_tx.c#L251)。当 RMT 资源池中没有空闲通道时返回 ESP_ERR_NOT_FOUND;若某些特性(如 DMA 后端)硬件不支持,返回 ESP_ERR_NOT_SUPPORTED。示例:
rmt_channel_handle_t tx_chan = NULL;
rmt_tx_channel_config_t tx_chan_config = {
.clk_src = RMT_CLK_SRC_DEFAULT, // select source clock
.gpio_num = 0, // GPIO number
.mem_block_symbols = 64, // memory block size, 64 * 4 = 256 Bytes
.resolution_hz = 1 * 1000 * 1000, // 1 MHz tick resolution, i.e., 1 tick = 1 µs
.trans_queue_depth = 4, // set the number of transactions that can pend in the background
.flags.invert_out = false, // do not invert output signal
.flags.with_dma = false, // do not need DMA backend
};
ESP_ERROR_CHECK(rmt_new_tx_channel(&tx_chan_config, &tx_chan));
安装 RMT RX 通道
RX 通道使用 rmt_rx_channel_config_t(完整定义见 components/esp_driver_rmt/include/driver/rmt_rx.h#L32-L47):
gpio_num:接收器使用的 GPIO 编号。clk_src/resolution_hz:与 TX 通道语义相同(见上文)。mem_block_symbols:含义同样取决于是否启用 DMA——启用 DMA 时控制 DMA 缓冲区的最大尺寸;不启用时控制通道专用内存块大小,至少应为SOC_RMT_MEM_WORDS_PER_CHANNEL。invert_in:在信号送入 RMT 接收器之前反转输入信号。此反转由 GPIO 矩阵完成,而非 RMT 外设本身。with_dma/intr_priority/allow_pd:与 TX 通道对应字段语义一致。
调用 rmt_new_rx_channel 分配并初始化 RX 通道,错误码含义与 TX 相同。示例:
rmt_channel_handle_t rx_chan = NULL;
rmt_rx_channel_config_t rx_chan_config = {
.clk_src = RMT_CLK_SRC_DEFAULT, // select source clock
.resolution_hz = 1 * 1000 * 1000, // 1 MHz tick resolution, i.e., 1 tick = 1 µs
.mem_block_symbols = 64, // memory block size, 64 * 4 = 256 Bytes
.gpio_num = 2, // GPIO number
.flags.invert_in = false, // do not invert input signal
.flags.with_dma = false, // do not need DMA backend
};
ESP_ERROR_CHECK(rmt_new_rx_channel(&rx_chan_config, &rx_chan));
多通道分配注意事项:同时分配多个 RMT 通道时,组的分频系数(prescale)由第一个通道的分辨率决定,驱动随后从低到高选择合适的分频值。为避免分频冲突,分配多个通道时应按目标分辨率排序(从高到低或从低到高)依次分配。
卸载 RMT 通道
当已安装的 RMT 通道不再需要时,调用 rmt_del_channel 回收资源,使底层软硬件资源得以复用(API 声明见 components/esp_driver_rmt/include/driver/rmt_common.h#L27)。若通道仍在工作中,该函数会返回 ESP_ERR_INVALID_STATE。
载波调制与解调
RMT 发送器可以生成载波并将其调制到消息信号上。与消息信号相比,载波频率显著更高,且用户只能设置载波的频率与占空比。RMT 接收器则可以从输入信号中解调出载波。注意并非所有 ESP 芯片都支持载波调制与解调,配置前请查阅芯片 TRM,否则可能遇到 ESP_ERR_NOT_SUPPORTED 错误。
载波相关配置集中在 rmt_carrier_config_t(定义见 components/esp_driver_rmt/include/driver/rmt_types.h#L79-L87):
frequency_hz:载波频率,单位 Hz;设为 0 表示关闭载波。duty_cycle:载波占空比。flags.polarity_active_low:设置载波极性,即载波调制到哪个电平上。flags.always_on:是否在数据传输结束后仍持续输出载波。该配置仅对 TX 通道有效。
RX 载波频率的容差建议:对于 RX 通道,不应将载波频率恰好设为理论值,建议为载波频率留出容差。例如下例中 RX 侧设为 25 KHz,而非 TX 侧配置的 38 KHz。原因在于信号在空中传播时会发生反射和折射,导致接收端信号失真。
rmt_carrier_config_t tx_carrier_cfg = {
.duty_cycle = 0.33, // duty cycle 33%
.frequency_hz = 38000, // 38 KHz
.flags.polarity_active_low = false, // carrier should be modulated to high level
};
// modulate carrier to TX channel
ESP_ERROR_CHECK(rmt_apply_carrier(tx_chan, &tx_carrier_cfg));
rmt_carrier_config_t rx_carrier_cfg = {
.duty_cycle = 0.33, // duty cycle 33%
.frequency_hz = 25000, // 25 KHz carrier, should be smaller than the transmitter's carrier frequency
.flags.polarity_active_low = false, // the carrier is modulated to high level
};
// demodulate carrier from RX channel
ESP_ERROR_CHECK(rmt_apply_carrier(rx_chan, &rx_carrier_cfg));
rmt_apply_carrier 对 TX 通道执行调制、对 RX 通道执行解调;传入 NULL 配置则可关闭载波调制/解调功能(见 components/esp_driver_rmt/include/driver/rmt_common.h#L39)。仓库中载波波形示意(调制前/调制后对比)位于 docs/_static/rmt-waveform.png 与 docs/_static/rmt-waveform-modulated.png。
注册事件回调
当 RMT 通道上发生事件(如发送或接收完成)时,CPU 通过中断获知。如需在特定事件发生时执行某个函数,可通过 rmt_tx_register_event_callbacks 和 rmt_rx_register_event_callbacks 将回调注册到 RMT 驱动的 ISR 中。由于注册的回调在中断上下文中被调用,回调函数不得阻塞(例如只能调用带 FromISR 后缀的 FreeRTOS API)。回调返回布尔值,用于指示该回调是否唤醒了一个更高优先级的任务。
TX 通道支持的事件回调在 rmt_tx_event_callbacks_t 中定义(见 components/esp_driver_rmt/include/driver/rmt_tx.h#L25-L27):
on_trans_done:为"trans-done"(发送完成)事件设置回调函数,函数原型见rmt_tx_done_callback_t。
RX 通道支持的事件回调在 rmt_rx_event_callbacks_t 中定义(见 components/esp_driver_rmt/include/driver/rmt_rx.h#L24-L27):
on_recv_done:为"receive-done"(接收完成)事件设置回调,函数原型见rmt_rx_done_callback_t。
"receive-done" ≠ "receive-finished":该回调也可能在"部分接收完成"时被多次调用(在一次接收事务期间),详见下文"发起 RX 事务"中的部分接收(partial receive)特性。
用户还可通过 rmt_tx_register_event_callbacks / rmt_rx_register_event_callbacks 的 user_data 参数保存自己的上下文,该用户数据会被直接传递给每个回调函数。回调中可通过 edata 获取驱动填充的事件特定数据,但 edata 指针仅在回调期间有效,不要保存该指针并在回调之外使用。
TX-done 事件数据定义于 rmt_tx_done_event_data_t(components/esp_driver_rmt/include/driver/rmt_types.h#L37-L40):
num_symbols:已发送的 RMT 符号数量,同时反映编码产物的尺寸。注意该值包含驱动为标记一次事务结束而追加的 EOF 符号。循环发送时该值只统计一轮。
RX-complete 事件数据定义于 rmt_rx_done_event_data_t(components/esp_driver_rmt/include/driver/rmt_types.h#L56-L63):
received_symbols:指向接收到的 RMT 符号。这些符号保存在rmt_receive函数的buffer参数中,回调返回前不要释放该接收缓冲区。若启用了部分接收特性,用户缓冲区会被当作"二级缓冲区",后续到达的数据可能覆盖其内容——如需保留或稍后处理,应将数据复制到其他位置。num_symbols:接收到的 RMT 符号数量,不会大于rmt_receive的buffer_size参数。若buffer_size不足以容纳全部符号,驱动只保留缓冲区能容纳的最大数量,多余符号被丢弃或忽略。flags.is_last:指示当前接收缓冲区是否是本次事务的最后一部分,在启用en_partial_rx部分接收时尤其有用。
使能与失能通道
rmt_enable 必须在发送或接收 RMT 符号之前调用(声明见 components/esp_driver_rmt/include/driver/rmt_common.h#L53):
- 对 TX 通道,使能会开启特定中断并让硬件准备好派发事务;
- 对 RX 通道,使能只开启中断,此时接收器并不会启动——因为输入信号的特征尚未指定,接收器在
rmt_receive中才会真正启动。
rmt_disable 则相反:失能中断并清除挂起的中断,同时失能发送器与接收器。rmt_disable 还会释放分配通道时可能安装的电源管理锁(见下文"电源管理"),并隐式调用编码器的 reset。
ESP_ERROR_CHECK(rmt_enable(tx_chan));
ESP_ERROR_CHECK(rmt_enable(rx_chan));
发起 TX 事务
RMT 是一种特殊的通信外设:它无法像 SPI、I2C 那样发送原始字节流,只能以自身格式 rmt_symbol_word_t 发送数据。但硬件并不会帮助把用户数据转换为 RMT 符号,这一步只能由软件中的 RMT 编码器(Encoder) 完成——编码器负责将用户数据编码为 RMT 符号并写入 RMT 内存块或 DMA 缓冲区。编码器的创建方式见下文"RMT 编码器"一节。
创建编码器后,调用 rmt_transmit 发起一次 TX 事务(实现见 components/esp_driver_rmt/src/rmt_tx.c#L520)。该函数接收通道句柄、编码器句柄、负载缓冲区等位置参数,此外还需提供事务级配置 rmt_transmit_config_t(定义见 components/esp_driver_rmt/include/driver/rmt_tx.h#L54-L60):
loop_count:发送循环次数。发送器完成一轮发送后,若该值不为零则自动重新开始相同发送。由于循环由硬件控制,RMT 通道可在极少的 CPU 干预下生成大量周期序列。- 设为
-1表示无限循环发送。此时通道不会停止,直到调用rmt_disable;同时不会产生 "trans-done" 事件。 - 设为正数表示有限次循环(非 esp32 平台)。此时 "trans-done" 事件在指定的循环次数完成后触发。
- 设为
flags.eot_level:发送器完成工作或通过rmt_disable停止工作时,输出引脚保持的电平("End Of Transmission" 电平)。flags.queue_nonblocking:当事务队列已满时是否等待空闲槽位。设为true时函数在队列满时直接返回错误码ESP_ERR_INVALID_STATE;否则函数会阻塞直到队列出现空闲槽位。
循环发送的尺寸限制:当
loop_count非零(启用循环)时存在发送尺寸限制——编码器返回的符号总数不得超过SOC_RMT_MEM_WORDS_PER_CHANNEL的容量,否则可能看到类似encoding artifacts can't exceed hw memory block for loop transmission的错误。如需通过循环启动大事务,可尝试以下两种方法:
- 增大
rmt_tx_channel_config_t::mem_block_symbols(注意:启用 DMA 后端时此方法不适用);- 自定义编码器,在编码函数中构造无限循环(见下文"RMT 编码器")。
事务的异步语义:在内部,rmt_transmit 构造一个事务描述符并送入工作队列,由 ISR 派发。因此 rmt_transmit 返回时事务可能尚未启动——在事务结束前不能回收或修改负载缓冲区。可通过 rmt_tx_register_event_callbacks 注册回调获取事务完成事件;若想确保所有挂起事务完成,可调用 rmt_tx_wait_all_done(声明见 components/esp_driver_rmt/include/driver/rmt_tx.h#L124),其 timeout_ms 参数设为 -1 表示无限等待。
多通道同步发送
在某些实时控制应用中(例如让两个机械臂同时运动),不希望不同通道之间存在时间漂移。RMT 驱动通过创建 同步管理器(Sync Manager) 来管理这一点,管理器句柄类型为 rmt_sync_manager_handle_t。RMT 同步发送的流程如下图所示:
安装 RMT 同步管理器
创建同步管理器时,需要告知管理器要管理哪些通道,配置位于 rmt_sync_manager_config_t(定义见 components/esp_driver_rmt/include/driver/rmt_tx.h#L65-L68):
tx_channel_array:指向被管理的 TX 通道数组。array_size:被管理的通道数量。
rmt_new_sync_manager 成功时返回管理器句柄;可能因参数无效等各种错误而失败。特别地,当同步管理器已安装且没有硬件资源创建新的管理器时,报告 ESP_ERR_NOT_FOUND;若硬件不支持同步管理器,报告 ESP_ERR_NOT_SUPPORTED(使用前请查阅芯片 TRM)。注意:放入同步管理器的所有通道都应先通过 rmt_enable() 使能。
同时启动发送
对于任意被管理的 TX 通道,在 tx_channel_array 中所有通道都调用了 rmt_transmit 之前,该通道不会启动发送,只是处于等待状态。由于各通道事务内容不同,TX 通道通常会在不同时间完成各自的事务,导致失去同步。因此重启一次同步发送前,需要调用 rmt_sync_reset 重新同步所有通道(声明见 components/esp_driver_rmt/include/driver/rmt_tx.h#L181)。
调用 rmt_del_sync_manager 可回收同步管理器,此后各通道可独立发起事务。
rmt_channel_handle_t tx_channels[2] = {NULL}; // declare two channels
int tx_gpio_number[2] = {0, 2};
// install channels one by one
for (int i = 0; i < 2; i++) {
rmt_tx_channel_config_t tx_chan_config = {
.clk_src = RMT_CLK_SRC_DEFAULT, // select source clock
.gpio_num = tx_gpio_number[i], // GPIO number
.mem_block_symbols = 64, // memory block size, 64 * 4 = 256 Bytes
.resolution_hz = 1 * 1000 * 1000, // 1 MHz resolution
.trans_queue_depth = 1, // set the number of transactions that can pend in the background
};
ESP_ERROR_CHECK(rmt_new_tx_channel(&tx_chan_config, &tx_channels[i]));
}
// enable the channels
for (int i = 0; i < 2; i++) {
ESP_ERROR_CHECK(rmt_enable(tx_channels[i]));
}
// install sync manager
rmt_sync_manager_handle_t synchro = NULL;
rmt_sync_manager_config_t synchro_config = {
.tx_channel_array = tx_channels,
.array_size = sizeof(tx_channels) / sizeof(tx_channels[0]),
};
ESP_ERROR_CHECK(rmt_new_sync_manager(&synchro_config, &synchro));
ESP_ERROR_CHECK(rmt_transmit(tx_channels[0], led_strip_encoders[0], led_data, led_num * 3, &transmit_config));
// tx_channels[0] does not start transmission until call of `rmt_transmit()` for tx_channels[1] returns
ESP_ERROR_CHECK(rmt_transmit(tx_channels[1], led_strip_encoders[1], led_data, led_num * 3, &transmit_config));
发起 RX 事务
如"使能与失能通道"所述,rmt_enable 并不会让 RX 通道开始接收。用户需要在 rmt_receive_config_t 中指定输入信号的基本特征(定义见 components/esp_driver_rmt/include/driver/rmt_rx.h#L52-L61):
signal_range_min_ns:指定有效脉冲(高或低电平)的最小持续时间。脉宽小于该值的脉冲被视为毛刺(glitch),被硬件忽略。signal_range_max_ns:指定有效脉冲(高或低电平)的最大持续时间。脉宽大于该值的脉冲被视为停止信号(Stop Signal),接收器立即产生 receive-complete 事件。flags.en_partial_rx:当输入数据包很长、无法一次性存入用户缓冲区时,可置true启用部分接收特性。此时驱动会在一次事务中、当用户缓冲区几乎写满时多次调用on_recv_done回调;通过检查rmt_rx_done_event_data_t::flags.is_last判断事务是否即将结束。该特性依赖硬件能力(如 "ping-pong receive" 或 "DMA receive"),并非所有 ESP 系列芯片都支持。
调用 rmt_receive 后 RMT 接收器才真正启动(实现见 components/esp_driver_rmt/src/rmt_rx.c#L350)。注意该配置是事务级的——要开始新一轮接收,需要重新设置 rmt_receive_config_t。接收器将输入信号以 rmt_symbol_word_t 格式存入内部内存块或 DMA 缓冲区。
接收起点说明:调用
rmt_receive后,实际接收从接收信号的第一次电平变化开始。如需获取接收的起始时间,可在 RMT RX 通道的 GPIO 上注册 GPIO 中断,详见 GPIO API 文档。
关于内存块容量与接收帧长度的关系(取决于芯片是否支持 SOC_RMT_SUPPORT_RX_PINGPONG):
- 支持 ping-pong 接收的芯片:由于内存块大小有限,RMT 接收器会以 ping-pong 方式通知驱动把累积的符号搬走。
- 不支持 ping-pong 的芯片:由于内存块大小有限,RMT 接收器只能保存长度不超过内存块容量的短帧。长帧会被硬件截断,驱动报告错误信息
hw buffer too small, received symbols truncated。
接收数据的拷贝目标由 rmt_receive 的 buffer 参数提供。若缓冲区大小不足导致溢出,接收器仍可继续工作,但溢出的符号被丢弃并报告 user buffer too small, received symbols truncated。请务必管理好 buffer 的生命周期,确保在接收器完成或停止之前不回收该缓冲区。
当接收到持续时间大于 signal_range_max_ns 的信号时,接收器由驱动自动停止。如有需要,须再次调用 rmt_receive 重启接收器。以下为典型的 NEC 接收流程(完整回调与收发实现见 examples/peripherals/rmt/ir_nec_transceiver/main/ir_nec_transceiver_main.c):
static bool example_rmt_rx_done_callback(rmt_channel_handle_t channel, const rmt_rx_done_event_data_t *edata, void *user_data)
{
BaseType_t high_task_wakeup = pdFALSE;
QueueHandle_t receive_queue = (QueueHandle_t)user_data;
// send the received RMT symbols to the parser task
xQueueSendFromISR(receive_queue, edata, &high_task_wakeup);
// return whether any task is woken up
return high_task_wakeup == pdTRUE;
}
QueueHandle_t receive_queue = xQueueCreate(1, sizeof(rmt_rx_done_event_data_t));
rmt_rx_event_callbacks_t cbs = {
.on_recv_done = example_rmt_rx_done_callback,
};
ESP_ERROR_CHECK(rmt_rx_register_event_callbacks(rx_channel, &cbs, receive_queue));
// the following timing requirement is based on NEC protocol
rmt_receive_config_t receive_config = {
.signal_range_min_ns = 1250, // the shortest duration for NEC signal is 560 µs, 1250 ns < 560 µs, valid signal is not treated as noise
.signal_range_max_ns = 12000000, // the longest duration for NEC signal is 9000 µs, 12000000 ns > 9000 µs, the receive does not stop early
};
rmt_symbol_word_t raw_symbols[64]; // 64 symbols should be sufficient for a standard NEC frame
// ready to receive
ESP_ERROR_CHECK(rmt_receive(rx_channel, raw_symbols, sizeof(raw_symbols), &receive_config));
// wait for the RX-done signal
rmt_rx_done_event_data_t rx_data;
xQueueReceive(receive_queue, &rx_data, portMAX_DELAY);
// parse the received symbols
example_parse_nec_frame(rx_data.received_symbols, rx_data.num_symbols);
RMT 编码器体系
RMT 编码器是 TX 事务的一部分,其职责是在特定时刻生成正确的 RMT 符号并写入硬件内存或 DMA 缓冲区。编码函数存在两条特殊约束:
- 多次调用:单次事务中编码函数可能被多次调用。这是因为目标 RMT 内存块无法一次容纳所有编码产物。为克服该限制,驱动采用 ping-pong 方式,将编码会话分为多个部分——这意味着编码器需要跟踪自身状态,以便从上一部分结束的位置继续编码。
- ISR 上下文:编码函数在 ISR 上下文中运行。为加速编码会话,强烈建议将编码函数放入 IRAM,这也可避免编码期间的缓存未命中。
为帮助开发者更快上手,驱动开箱即用地提供了一些常用编码器,它们既可以单独使用,也可以链接成新编码器(其原理参见组合模式 Composite Pattern)。驱动在 rmt_encoder_t 中定义了编码器接口(见 components/esp_driver_rmt/include/driver/rmt_encoder.h#L37-L72),包含三个函数指针:
encode:编码器的核心函数,编码会话在此发生。- 单次事务中可能被多次调用,应返回当前编码会话的状态。
- 支持的状态见
rmt_encode_state_t枚举:若结果包含RMT_ENCODING_COMPLETE,表示当前编码器已完成工作;若结果包含RMT_ENCODING_MEM_FULL,表示没有更多空间保存编码产物,程序需从当前会话让出(yield)。
reset:将编码器状态复位到初始状态(RMT 编码器是有状态的)。- 若 RMT 发送器被手动停止而未复位对应编码器,后续编码会话可能出错;
- 该函数也会在
rmt_disable中被隐式调用。
del:释放编码器分配的资源。
复制编码器(Copy Encoder)
通过 rmt_new_copy_encoder 创建。复制编码器的主要功能是把用户空间的 RMT 符号原样复制到驱动层,通常用于编码 const 数据,即初始化后运行期不变的数据(如 IR 协议中的引导码)。创建前需提供 rmt_copy_encoder_config_t 配置结构体,目前该结构体仅为将来扩展保留,暂无具体使用项(见 components/esp_driver_rmt/include/driver/rmt_encoder.h#L135-L136)。注意:使用复制编码器发送时,输入数据必须已按 rmt_symbol_word_t 格式组织。
字节编码器(Bytes Encoder)
通过 rmt_new_bytes_encoder 创建。字节编码器将用户空间的字节流动态转换为 RMT 符号,通常用于编码动态数据(如 IR 协议中的地址和命令字段)。创建前需提供 rmt_bytes_encoder_config_t(见 components/esp_driver_rmt/include/driver/rmt_encoder.h#L124-L130):
bit0与bit1:以rmt_symbol_word_t格式指定编码器如何表示比特 0 与比特 1。flags.msb_first:设置每个字节的位端序。为true时编码器先发送最高有效位(MSB),否则先发送最低有效位(LSB)。
此外,rmt_bytes_encoder_update_config 支持在运行期更新字节编码器的配置(见 components/esp_driver_rmt/include/driver/rmt_encoder.h#L183)。
除驱动提供的原始编码器外,用户可通过链接现有编码器实现自己的编码器。常见的编码器链(encoder chain)结构(图表定义源见 docs/_static/diagrams/rmt/rmt_encoder_chain.diag)通常为:copy encoder(引导码/结束码)→ bytes encoder(地址/命令数据)→ copy encoder(结束码)。
简单回调编码器(Simple Callback Encoder)
通过 rmt_new_simple_encoder 创建。简单回调编码器允许用户提供一个回调,从用户空间读取数据并直接向输出流写入符号,而无需链接其他编码器。回调会获得:传给 rmt_transmit 的数据指针、本次发送中该回调已写入的符号计数、以及可写入 RMT 符号的位置及其空闲空间大小。若空间不足,回调可返回 0,RMT 会等待先前符号发送完毕后再以更多空间调用该回调;若成功写入符号,则返回写入的符号数。
创建前需提供 rmt_simple_encoder_config_t(见 components/esp_driver_rmt/include/driver/rmt_encoder.h#L148-L155):
callback与arg:回调函数及其不透明参数。min_chunk_size:以符号数指定编码器保证总能写入一些数据所需的最小空闲空间。换言之,当传入的空闲空间达到该值时,回调绝不应返回 0(编码器完成编码除外)。若设为 0 或未给出,默认值为 64。
虽然简单回调编码器的功能通常也可以通过链接其他编码器实现,但简单回调更易于理解和维护。
BitScrambler 编码器(特定芯片)
当 RMT 发送通道启用了 DMA 时,可以通过编写 BitScrambler 汇编代码控制 DMA 通路上的数据,实现简单的编码操作。相比基于 CPU 的编码,BitScrambler 性能更高且不消耗 CPU 资源。但由于 BitScrambler 指令内存空间有限,无法实现复杂编码操作,且其程序输出的数据格式必须符合 rmt_symbol_word_t 结构。
通过 rmt_new_bitscrambler_encoder 创建 BitScrambler 编码器,配置参数类型为 rmt_bs_encoder_config_t(见 components/esp_driver_rmt/include/driver/rmt_encoder.h#L141-L143):
program_bin:指向 BitScrambler 程序的二进制文件,须符合 BitScrambler 汇编语言规范,运行时会加载到 BitScrambler 的指令内存中。编写与编译方法见 BitScrambler 编程指南。
重要限制:BitScrambler 编码器必须与启用 DMA 的 RMT 通道配合使用。该特性的驱动实现位于 components/esp_driver_rmt/src/rmt_encoder_bs.c。
实战:为 NEC 协议自定义 RMT 编码器
NEC 红外协议对消息位采用脉冲距离编码。每个脉冲串持续 562.5 µs,逻辑比特的发送方式如下(注意每个字节的最低有效位先发送):
- 逻辑
0:562.5 µs脉冲串 +562.5 µs空闲,总发送时间1.125 ms; - 逻辑
1:562.5 µs脉冲串 +1.6875 ms空闲,总发送时间2.25 ms。
按下遥控器按键时,发送的消息按以下顺序包含各元素:
9 ms引导脉冲串(又称 "AGC pulse");4.5 ms空闲;- 8 位接收设备地址;
- 8 位地址的逻辑反码;
- 8 位命令;
- 8 位命令的逻辑反码;
- 结尾的
562.5 µs脉冲串,表示消息发送结束。
随后可以按相同顺序构造 NEC 编码器的 encode 函数。完整示例见 examples/peripherals/rmt/ir_nec_transceiver/main/ir_nec_encoder.c(该文件在 encode 与 reset 函数上使用了 RMT_ENCODER_FUNC_ATTR 宏,以便在启用缓存安全配置时把编码函数放入 IRAM):
// IR NEC scan code representation
typedef struct {
uint16_t address;
uint16_t command;
} ir_nec_scan_code_t;
// construct an encoder by combining primitive encoders
typedef struct {
rmt_encoder_t base; // the base "class" declares the standard encoder interface
rmt_encoder_t *copy_encoder; // use the copy_encoder to encode the leading and ending pulse
rmt_encoder_t *bytes_encoder; // use the bytes_encoder to encode the address and command data
rmt_symbol_word_t nec_leading_symbol; // NEC leading code with RMT representation
rmt_symbol_word_t nec_ending_symbol; // NEC ending code with RMT representation
int state; // record the current encoding state, i.e., we are in which encoding phase
} rmt_ir_nec_encoder_t;
static size_t rmt_encode_ir_nec(rmt_encoder_t *encoder, rmt_channel_handle_t channel, const void *primary_data, size_t data_size, rmt_encode_state_t *ret_state)
{
rmt_ir_nec_encoder_t *nec_encoder = __containerof(encoder, rmt_ir_nec_encoder_t, base);
rmt_encode_state_t session_state = RMT_ENCODING_RESET;
rmt_encode_state_t state = RMT_ENCODING_RESET;
size_t encoded_symbols = 0;
ir_nec_scan_code_t *scan_code = (ir_nec_scan_code_t *)primary_data;
rmt_encoder_handle_t copy_encoder = nec_encoder->copy_encoder;
rmt_encoder_handle_t bytes_encoder = nec_encoder->bytes_encoder;
switch (nec_encoder->state) {
case 0: // send leading code
encoded_symbols += copy_encoder->encode(copy_encoder, channel, &nec_encoder->nec_leading_symbol,
sizeof(rmt_symbol_word_t), &session_state);
if (session_state & RMT_ENCODING_COMPLETE) {
nec_encoder->state = 1; // we can only switch to the next state when the current encoder finished
}
if (session_state & RMT_ENCODING_MEM_FULL) {
state |= RMT_ENCODING_MEM_FULL;
goto out; // yield if there is no free space to put other encoding artifacts
}
// fall-through
case 1: // send address
encoded_symbols += bytes_encoder->encode(bytes_encoder, channel, &scan_code->address, sizeof(uint16_t), &session_state);
if (session_state & RMT_ENCODING_COMPLETE) {
nec_encoder->state = 2; // we can only switch to the next state when the current encoder finished
}
if (session_state & RMT_ENCODING_MEM_FULL) {
state |= RMT_ENCODING_MEM_FULL;
goto out; // yield if there is no free space to put other encoding artifacts
}
// fall-through
case 2: // send command
encoded_symbols += bytes_encoder->encode(bytes_encoder, channel, &scan_code->command, sizeof(uint16_t), &session_state);
if (session_state & RMT_ENCODING_COMPLETE) {
nec_encoder->state = 3; // we can only switch to the next state when the current encoder finished
}
if (session_state & RMT_ENCODING_MEM_FULL) {
state |= RMT_ENCODING_MEM_FULL;
goto out; // yield if there is no free space to put other encoding artifacts
}
// fall-through
case 3: // send ending code
encoded_symbols += copy_encoder->encode(copy_encoder, channel, &nec_encoder->nec_ending_symbol,
sizeof(rmt_symbol_word_t), &session_state);
if (session_state & RMT_ENCODING_COMPLETE) {
nec_encoder->state = RMT_ENCODING_RESET; // back to the initial encoding session
state |= RMT_ENCODING_COMPLETE; // telling the caller the NEC encoding has finished
}
if (session_state & RMT_ENCODING_MEM_FULL) {
state |= RMT_ENCODING_MEM_FULL;
goto out; // yield if there is no free space to put other encoding artifacts
}
}
out:
*ret_state = state;
return encoded_symbols;
}
上述片段使用 switch-case 与若干 goto 语句实现了有限状态机(FSM):每次 encode 调用只推进一个编码阶段,遇到 RMT_ENCODING_MEM_FULL 就 yield,等待下一次调用从上次状态继续;只有当前阶段编码完成(RMT_ENCODING_COMPLETE)才切换到下一阶段。借助这种模式,用户可以构造更复杂的 IR 协议。编码器创建函数 rmt_new_ir_nec_encoder 中通过 rmt_alloc_encoder_mem 分配编码器内存、组合 copy/bytes 原始编码器,并根据 config->resolution 计算 NEC 引导码/结束码符号的 tick 时长(如 9000ULL * config->resolution / 1000000)。
电源管理
当启用电源管理(即开启 CONFIG_PM_ENABLE)时,系统可能在睡眠前调整或关闭时钟源,导致 RMT 内部时间基准无法正常工作。
驱动通过创建电源管理锁来避免该问题,锁的类型根据不同的时钟源设定。驱动在 rmt_enable 中获取该锁、在 rmt_disable 中释放——这意味着这两个函数之间的任何 RMT 事务都能保证正确、稳定地工作(相关注释见 components/esp_driver_rmt/include/driver/rmt_common.h#L44 与 components/esp_driver_rmt/include/driver/rmt_common.h#L58)。
此外,在支持睡眠保持(sleep retention,SOC_RMT_SUPPORT_SLEEP_RETENTION)的芯片上,启用电源管理后系统还可在睡眠前关断 RMT 硬件。将 rmt_tx_channel_config_t::allow_pd 与 rmt_rx_channel_config_t::allow_pd 置为 true 即可启用该关断特性:RMT 寄存器在睡眠前备份、唤醒后恢复。注意启用该选项会增加内存消耗(各芯片的寄存器上下文保持实现见 components/esp_driver_rmt 下各芯片目录中的 rmt_retention.c)。
缓存安全(Cache Safe)
默认情况下,当缓存因写入或擦除主 Flash 等原因被禁用时,RMT 中断会被推迟,导致事务完成中断无法及时处理——这在实时应用中不可接受。更糟的是,当 RMT 事务依赖 ping-pong 中断来连续编码或搬运 RMT 符号时,延迟的中断可能导致不可预测的结果。
Kconfig 选项 CONFIG_RMT_TX_ISR_CACHE_SAFE 与 CONFIG_RMT_RX_ISR_CACHE_SAFE 提供以下特性:
- 即使缓存被禁用,中断也能被正常处理;
- 将 ISR 使用的所有函数放入 IRAM;
- 将驱动对象放入 DRAM,避免被意外映射到 PSRAM。
该选项允许中断处理程序在缓存禁用时运行,但代价是增加 IRAM 消耗(各 Kconfig 选项的精确定义见 components/esp_driver_rmt/Kconfig)。
请注意,启用 CONFIG_RMT_TX_ISR_CACHE_SAFE 时,还必须将编码器函数(主要是 rmt_encoder_t::encode 和 rmt_encoder_t::reset)放入 IRAM,可使用 RMT_ENCODER_FUNC_ATTR 宏修饰编码器函数(该宏在启用 CONFIG_RMT_ENCODER_FUNC_IN_IRAM 时展开为 IRAM_ATTR,见 components/esp_driver_rmt/include/driver/rmt_encoder.h#L74-L78)。另外,用户注册的回调函数(如 on_trans_done)及其内部调用的函数也应自行放入 IRAM。
另一个 Kconfig 选项 CONFIG_RMT_RECV_FUNC_IN_IRAM 可将 rmt_receive 函数也放入 IRAM,从而在 Flash 缓存被禁用时仍可使用接收函数(该选项默认关闭,见 components/esp_driver_rmt/Kconfig#L24-L29)。注意:以上 *_CACHE_SAFE 选项在启用 SPI_FLASH_AUTO_SUSPEND 时不可配置。仓库中对缓存安全路径的测试用例见 components/esp_driver_rmt/test_apps/rmt/main/test_rmt_cache_safe.c。
线程安全
驱动保证以下工厂函数是线程安全的,用户可以从不同 RTOS 任务中调用它们而无需额外加锁:
rmt_new_tx_channelrmt_new_rx_channelrmt_new_sync_manager
其他以 rmt_channel_handle_t 和 rmt_sync_manager_handle_t 作为第一个位置参数的函数不是线程安全的,应避免从多个任务调用。
以下函数还允许在 ISR 上下文中使用:
rmt_receive
Kconfig 选项汇总
RMT 驱动支持的 Kconfig 选项定义于 components/esp_driver_rmt/Kconfig,主要包括:
CONFIG_RMT_TX_ISR_CACHE_SAFE与CONFIG_RMT_RX_ISR_CACHE_SAFE:控制默认 ISR 处理程序是否能在缓存禁用时工作,详见上文"缓存安全"一节。CONFIG_RMT_ENABLE_DEBUG_LOG:启用调试日志,代价是固件二进制体积增大(会忽略全局日志设置、编译全部日志消息并将运行日志级别设为 VERBOSE)。CONFIG_RMT_RECV_FUNC_IN_IRAM:控制 RMT 接收函数的放置位置(IRAM 或 Flash),详见"缓存安全"一节。- 相关辅助选项(由上述选项自动选择):
CONFIG_RMT_ENCODER_FUNC_IN_IRAM(将编码器函数放入 IRAM,默认开启)、CONFIG_RMT_TX_ISR_HANDLER_IN_IRAM/CONFIG_RMT_RX_ISR_HANDLER_IN_IRAM(将 ISR 处理程序放入 IRAM 降低延迟,默认开启)、CONFIG_RMT_OBJ_CACHE_SAFE(确保 RMT 对象不分配自缓存可被禁用的内存区域)。 CONFIG_RMT_ISR_IRAM_SAFE:已废弃的选项,等价于同时开启 TX/RX 的ISR_CACHE_SAFE。
应用示例
仓库 examples/peripherals/rmt 目录下提供了覆盖 RMT 主要能力的示例工程:
led_strip:使用 RMT 外设驱动 WS2812 LED 灯带,支持更改 LED 数量与追逐特效。led_strip_simple_encoder:通过实现一个将 RGB 像素转换为硬件可识别格式的回调,使用简单回调编码器驱动 WS2812 灯带。ir_nec_transceiver:使用 RMT 外设实现红外 NEC 协议的编码与解码。dshot_esc:使用 RMT TX 通道实现无限循环发送,为 DShot 数字协议构造 RMT 编码器。该协议主要用于飞控与电子调速器之间的通信,相比传统模拟协议具有更强的抗电气噪声能力。onewire:使用onewire_bus库模拟 1-wire 硬件协议,读取总线上多个 DS18B20 温度传感器;该库构建于 RMT 的一对发送/接收通道之上。musical_buzzer(支持SOC_RMT_SUPPORT_TX_LOOP_COUNT的芯片):使用 RMT TX 通道驱动无源蜂鸣器播放简单音乐,每个音符由固定时长、恒定频率的 PWM 信号表示。stepper_motor(支持SOC_RMT_SUPPORT_TX_LOOP_AUTO_STOP的芯片):使用 RMT 驱动 STEP/DIR 接口的步进电机控制器(如 DRV8825)。编写 RMT 编码器后,可针对期望的加速、匀速、减速阶段实现 S 曲线(S-curve)轮廓,从而平滑驱动步进电机。
常见问题(FAQ)
为什么 RMT 发送的数据比预期多?
RMT 发送的编码在 ISR 上下文中进行。如果 RMT 编码过程被拉长(例如在过程中记录日志或跟踪)或由于中断延迟、抢占中断而延迟,硬件发送器可能会在编码器写入内存之前就读取内存,导致发送器发出过时数据。虽然无法让发送器暂停等待,但可通过组合以下策略缓解:
- 增大
rmt_tx_channel_config_t::mem_block_symbols(以SOC_RMT_MEM_WORDS_PER_CHANNEL为步进); - 使用
IRAM_ATTR属性将编码函数放入 IRAM; - 若 DMA 可用,启用
rmt_tx_channel_config_t::with_dma; - 将 RMT 驱动安装到独立的 CPU 核心上,避免与其他中断密集型外设(如 WiFi、蓝牙)竞争同一 CPU 资源。
小结
RMT 外设驱动以"符号(Symbol)"为核心抽象,通过通道分配、事务队列、编码器链与同步管理器等机制,将硬件的高灵活性与软件的易用性结合。本文系统梳理了 RMT API 参考文档 的全部要点,并结合 components/esp_driver_rmt 的驱动头文件与实现、examples/peripherals/rmt 的示例工程给出了源码级印证。实际开发时,建议参照 ir_nec_transceiver 示例理解编码器状态机与收发回调的配合,参照 led_strip 理解字节编码器的位序配置,并依据芯片 TRM 手册确认 DMA、载波、同步管理器、部分接收等特性在目标芯片上的支持情况。

