mirror of
https://github.com/espressif/esp-idf.git
synced 2025-07-31 19:24:33 +02:00
docs(rmt): improve the documentation
Closes https://github.com/espressif/esp-idf/issues/15933 Closes https://github.com/espressif/esp-idf/issues/15929
This commit is contained in:
Chen Jichang
@@ -56,7 +56,8 @@ typedef bool (*rmt_tx_done_callback_t)(rmt_channel_handle_t tx_chan, const rmt_t
|
||||
typedef struct {
|
||||
rmt_symbol_word_t *received_symbols; /*!< Point to the received RMT symbols */
|
||||
size_t num_symbols; /*!< The number of received RMT symbols */
|
||||
struct {
|
||||
/// Extra flags
|
||||
struct extra_rmt_rx_done_event_flags {
|
||||
uint32_t is_last: 1; /*!< Indicating if the current received data are the last part of the transaction */
|
||||
} flags; /*!< Extra flags */
|
||||
} rmt_rx_done_event_data_t;
|
||||
@@ -78,7 +79,8 @@ typedef bool (*rmt_rx_done_callback_t)(rmt_channel_handle_t rx_chan, const rmt_r
|
||||
typedef struct {
|
||||
uint32_t frequency_hz; /*!< Carrier wave frequency, in Hz, 0 means disabling the carrier */
|
||||
float duty_cycle; /*!< Carrier wave duty cycle (0~100%) */
|
||||
struct {
|
||||
/// Extra carrier config flags
|
||||
struct extra_rmt_carrier_config_flags {
|
||||
uint32_t polarity_active_low: 1; /*!< Specify the polarity of carrier, by default it's modulated to base signal's high level */
|
||||
uint32_t always_on: 1; /*!< If set, the carrier can always exist even there's not transfer undergoing */
|
||||
} flags; /*!< Carrier config flags */
|
||||
|
||||
@@ -162,8 +162,8 @@ Carrier-related configurations lie in :cpp:type:`rmt_carrier_config_t`:
|
||||
|
||||
- :cpp:member:`rmt_carrier_config_t::frequency_hz` sets the carrier frequency, in Hz.
|
||||
- :cpp:member:`rmt_carrier_config_t::duty_cycle` sets the carrier duty cycle.
|
||||
- :cpp:member:`rmt_carrier_config_t::polarity_active_low` sets the carrier polarity, i.e., on which level the carrier is applied.
|
||||
- :cpp:member:`rmt_carrier_config_t::always_on` sets whether to output the carrier even when the data transmission has finished. This configuration is only valid for the TX channel.
|
||||
- :cpp:member:`rmt_carrier_config_t::extra_rmt_carrier_config_flags::polarity_active_low` sets the carrier polarity, i.e., on which level the carrier is applied.
|
||||
- :cpp:member:`rmt_carrier_config_t::extra_rmt_carrier_config_flags::always_on` sets whether to output the carrier even when the data transmission has finished. This configuration is only valid for the TX channel.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -218,7 +218,7 @@ The RX-complete event data is defined in :cpp:type:`rmt_rx_done_event_data_t`:
|
||||
|
||||
- :cpp:member:`rmt_rx_done_event_data_t::received_symbols` points to the received RMT symbols. These symbols are saved in the ``buffer`` parameter of the :cpp:func:`rmt_receive` function. Users should not free this receive buffer before the callback returns. If you also enabled the partial receive feature, then the user buffer will be used as a "second level buffer", where its content can be overwritten by data comes in afterwards. In this case, you should copy the received data to another place if you want to keep it or process it later.
|
||||
- :cpp:member:`rmt_rx_done_event_data_t::num_symbols` indicates the number of received RMT symbols. This value is not larger than the ``buffer_size`` parameter of :cpp:func:`rmt_receive` function. If the ``buffer_size`` is not sufficient to accommodate all the received RMT symbols, the driver only keeps the maximum number of symbols that the buffer can hold, and excess symbols are discarded or ignored.
|
||||
- :cpp:member:`rmt_rx_done_event_data_t::is_last` indicates whether the current received buffer is the last one in the transaction. This is useful when you enable the partial reception feature by :cpp:member:`rmt_receive_config_t::extra_rmt_receive_flags::en_partial_rx`.
|
||||
- :cpp:member:`rmt_rx_done_event_data_t::extra_rmt_rx_done_event_flags::is_last` indicates whether the current received buffer is the last one in the transaction. This is useful when you enable the partial reception feature by :cpp:member:`rmt_receive_config_t::extra_rmt_receive_flags::en_partial_rx`.
|
||||
|
||||
.. _rmt-enable-and-disable-channel:
|
||||
|
||||
@@ -334,10 +334,14 @@ As also discussed in the :ref:`rmt-enable-and-disable-channel`, calling :cpp:fun
|
||||
|
||||
- :cpp:member:`rmt_receive_config_t::signal_range_min_ns` specifies the minimal valid pulse duration in either high or low logic levels. A pulse width that is smaller than this value is treated as a glitch, and ignored by the hardware.
|
||||
- :cpp:member:`rmt_receive_config_t::signal_range_max_ns` specifies the maximum valid pulse duration in either high or low logic levels. A pulse width that is bigger than this value is treated as **Stop Signal**, and the receiver generates receive-complete event immediately.
|
||||
- If the incoming packet is long, that they cannot be stored in the user buffer at once, you can enable the partial reception feature by setting :cpp:member:`rmt_receive_config_t::extra_rmt_receive_flags::en_partial_rx` to ``true``. In this case, the driver invokes :cpp:member:`rmt_rx_event_callbacks_t::on_recv_done` callback multiple times during one transaction, when the user buffer is **almost full**. You can check the value of :cpp:member::`rmt_rx_done_event_data_t::is_last` to know if the transaction is about to finish. Please note this features is not supported on all ESP series chips because it relies on hardware abilities like "ping-pong receive" or "DMA receive".
|
||||
- If the incoming packet is long, that they cannot be stored in the user buffer at once, you can enable the partial reception feature by setting :cpp:member:`rmt_receive_config_t::extra_rmt_receive_flags::en_partial_rx` to ``true``. In this case, the driver invokes :cpp:member:`rmt_rx_event_callbacks_t::on_recv_done` callback multiple times during one transaction, when the user buffer is **almost full**. You can check the value of :cpp:member:`rmt_rx_done_event_data_t::extra_rmt_rx_done_event_flags::is_last` to know if the transaction is about to finish. Please note this features is not supported on all ESP series chips because it relies on hardware abilities like "ping-pong receive" or "DMA receive".
|
||||
|
||||
The RMT receiver starts the RX machine after the user calls :cpp:func:`rmt_receive` with the provided configuration above. Note that, this configuration is transaction specific, which means, to start a new round of reception, the user needs to set the :cpp:type:`rmt_receive_config_t` again. The receiver saves the incoming signals into its internal memory block or DMA buffer, in the format of :cpp:type:`rmt_symbol_word_t`.
|
||||
|
||||
.. note::
|
||||
|
||||
After calling :cpp:func:`rmt_receive` function, the actual reception starts at the first level change of the received signal. If you need to get the start time of the reception, you can register a GPIO interrupt on the GPIO of the RMT RX channel, please refer to :doc:`GPIO doc </api-reference/peripherals/gpio>` for details.
|
||||
|
||||
.. only:: SOC_RMT_SUPPORT_RX_PINGPONG
|
||||
|
||||
Due to the limited size of the memory block, the RMT receiver notifies the driver to copy away the accumulated symbols in a ping-pong way.
|
||||
|
||||
@@ -162,8 +162,8 @@ RMT 发射器可以生成载波信号，并将其调制到消息信号上。载
|
||||
|
||||
- :cpp:member:`rmt_carrier_config_t::frequency_hz` 设置载波频率，单位为 Hz。
|
||||
- :cpp:member:`rmt_carrier_config_t::duty_cycle` 设置载波占空比。
|
||||
- :cpp:member:`rmt_carrier_config_t::polarity_active_low` 设置载波极性，即应用载波的电平。
|
||||
- :cpp:member:`rmt_carrier_config_t::always_on` 设置是否在数据发送完成后仍输出载波，该配置仅适用于 TX 通道。
|
||||
- :cpp:member:`rmt_carrier_config_t::extra_rmt_carrier_config_flags::polarity_active_low` 设置载波极性，即应用载波的电平。
|
||||
- :cpp:member:`rmt_carrier_config_t::extra_rmt_carrier_config_flags::always_on` 设置是否在数据发送完成后仍输出载波，该配置仅适用于 TX 通道。
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -218,7 +218,7 @@ RMT 发射器可以生成载波信号，并将其调制到消息信号上。载
|
||||
|
||||
- :cpp:member:`rmt_rx_done_event_data_t::received_symbols` 指向接收到的 RMT 符号，这些符号存储在 :cpp:func:`rmt_receive` 函数的 ``buffer`` 参数中，在回调函数返回前不应释放此接收缓冲区。如果你还启用了部分接收的功能，则这个用户缓冲区会被用作“二级缓冲区”，其中的内容可以被随后传入的数据覆盖。在这种情况下，如果你想要保存或者稍后处理一些数据，则需要将接收到的数据复制到其他位置。
|
||||
- :cpp:member:`rmt_rx_done_event_data_t::num_symbols` 表示接收到的 RMT 符号数量，该值不会超过 :cpp:func:`rmt_receive` 函数的 ``buffer_size`` 参数。如果 ``buffer_size`` 不足以容纳所有接收到的 RMT 符号，驱动程序将只保存缓冲区能够容纳的最大数量的符号，并丢弃或忽略多余的符号。
|
||||
- :cpp:member:`rmt_rx_done_event_data_t::is_last` 指示收到的数据包是否是当前的接收任务中的最后一个。这个标志在你使能 :cpp:member:`rmt_receive_config_t::extra_rmt_receive_flags::en_partial_rx` 部分接收功能时非常有用。
|
||||
- :cpp:member:`rmt_rx_done_event_data_t::extra_rmt_rx_done_event_flags::is_last` 指示收到的数据包是否是当前的接收任务中的最后一个。这个标志在你使能 :cpp:member:`rmt_receive_config_t::extra_rmt_receive_flags::en_partial_rx` 部分接收功能时非常有用。
|
||||
|
||||
.. _rmt-enable-and-disable-channel:
|
||||
|
||||
@@ -334,7 +334,7 @@ RMT 是一种特殊的通信外设，无法像 SPI 和 I2C 那样发送原始字
|
||||
|
||||
- :cpp:member:`rmt_receive_config_t::signal_range_min_ns` 指定高电平或低电平有效脉冲的最小持续时间。如果脉冲宽度小于指定值，硬件会将其视作干扰信号并忽略。
|
||||
- :cpp:member:`rmt_receive_config_t::signal_range_max_ns` 指定高电平或低电平有效脉冲的最大持续时间。如果脉冲宽度大于指定值，接收器会将其视作 **停止信号**，并立即生成接收完成事件。
|
||||
- 如果传入的数据包很长，无法一次性保存在用户缓冲区中，可以通过将 :cpp:member:`rmt_receive_config_t::extra_rmt_receive_flags::en_partial_rx` 设置为 ``true`` 来开启部分接收功能。在这种情况下，当用户缓冲区快满的时候，驱动会多次调用 :cpp:member:`rmt_rx_event_callbacks_t::on_recv_done` 回调函数来通知用户去处理已经收到的数据。你可以检查 :cpp:member::`rmt_rx_done_event_data_t::is_last` 的值来了解当前事务是否已经结束。请注意，并不是所有 ESP 系列芯片都支持这个功能，它依赖硬件提供的 “ping-pong 接收” 或者 “DMA 接收” 的能力。
|
||||
- 如果传入的数据包很长，无法一次性保存在用户缓冲区中，可以通过将 :cpp:member:`rmt_receive_config_t::extra_rmt_receive_flags::en_partial_rx` 设置为 ``true`` 来开启部分接收功能。在这种情况下，当用户缓冲区快满的时候，驱动会多次调用 :cpp:member:`rmt_rx_event_callbacks_t::on_recv_done` 回调函数来通知用户去处理已经收到的数据。你可以检查 :cpp:member:`rmt_rx_done_event_data_t::extra_rmt_rx_done_event_flags::is_last` 的值来了解当前事务是否已经结束。请注意，并不是所有 ESP 系列芯片都支持这个功能，它依赖硬件提供的 “ping-pong 接收” 或者 “DMA 接收” 的能力。
|
||||
|
||||
根据以上配置调用 :cpp:func:`rmt_receive` 后，RMT 接收器会启动 RX 机制。注意，以上配置均针对特定事务存在，也就是说，要开启新一轮的接收时，需要再次设置 :cpp:type:`rmt_receive_config_t` 选项。接收器会将传入信号以 :cpp:type:`rmt_symbol_word_t` 的格式保存在内部内存块或 DMA 缓冲区中。
|
||||
|
||||
@@ -350,6 +350,10 @@ RMT 是一种特殊的通信外设，无法像 SPI 和 I2C 那样发送原始字
|
||||
|
||||
当接收器完成工作，即接收到持续时间大于 :cpp:member:`rmt_receive_config_t::signal_range_max_ns` 的信号时，驱动程序将停止接收器。如有需要，应再次调用 :cpp:func:`rmt_receive` 重新启动接收器。在 :cpp:member:`rmt_rx_event_callbacks_t::on_recv_done` 的回调中可以获取接收到的数据。要获取更多有关详情，请参阅 :ref:`rmt-register-event-callbacks`。
|
||||
|
||||
.. note::
|
||||
|
||||
调用 :cpp:func:`rmt_receive` 函数后， 实际接收会在第一次电平跳变的时候开始。如果需要获取开始接收的时间，可以在 RMT RX 通道的 GPIO 上注册 GPIO 中断，详情请参阅 :doc:`GPIO 文档 </api-reference/peripherals/gpio>`。
|
||||
|
||||
.. code:: c
|
||||
|
||||
static bool example_rmt_rx_done_callback(rmt_channel_handle_t channel, const rmt_rx_done_event_data_t *edata, void *user_data)
|
||||
|
||||
Reference in New Issue
Block a user