Remote Control (RMT)

The RMT (Remote Control) module driver can be used to send and receive infrared remote control signals. Due to flexibility of RMT module, the driver can also be used to generate or receive many other types of signals.

The signal, which consists of a series of pulses, is generated by RMT’s transmitter based on a list of values. The values define the pulse duration and a binary level, see below. The transmitter can also provide a carrier and modulate it with provided pulses.

RMT Transmitter Overview

The reverse operation is performed by the receiver, where a series of pulses is decoded into a list of values containing the pulse duration and binary level. A filter may be applied to remove high frequency noise from the input signal.

RMT Receiver Overview

There couple of typical steps to setup and operate the RMT and they are discussed in the following sections:

Configure Driver
Transmit Data or Receive Data
Change Operation Parameters
Use Interrupts

The RMT has four channels numbered from zero to three. Each channel is able to independently transmit or receive data. They are referred to using indexes defined in structure rmt_channel_t.

Configure Driver

There are several parameters that define how particular channel operates. Most of these parameters are configured by setting specific members of rmt_config_t structure. Some of the parameters are common to both transmit or receive mode, and some are mode specific. They are all discussed below.

Common Parameters

The channel to be configured, select one from the rmt_channel_t enumerator.
The RMT operation mode - whether this channel is used to transmit or receive data, selected by setting a rmt_mode members to one of the values from rmt_mode_t.
What is the pin number to transmit or receive RMT signals, selected by setting gpio_num.
How many memory blocks will be used by the channel, set with mem_block_num.
Extra miscellaneous parameters for the channel can be set in the flags.
- When RMT_CHANNEL_FLAGS_AWARE_DFS is set, RMT channel will take REF_TICK or XTAL as source clock. The benefit is, RMT channel can continue work even when APB clock is changing. See power_management for more information.
- When RMT_CHANNEL_FLAGS_INVERT_SIG is set, the driver will invert the RMT signal sending to or receiving from the channel. It just works like an external inverter connected to the GPIO of certain RMT channel.
A clock divider, that will determine the range of pulse length generated by the RMT transmitter or discriminated by the receiver. Selected by setting clk_div to a value within [1 .. 255] range. The RMT source clock is typically APB CLK, 80Mhz by default. But when RMT_CHANNEL_FLAGS_AWARE_DFS is set in flags, RMT source clock is changed to REF_TICK or XTAL.

Note

The period of a square wave after the clock divider is called a ‘tick’. The length of the pulses generated by the RMT transmitter or discriminated by the receiver is configured in number of ‘ticks’.

There are also couple of specific parameters that should be set up depending if selected channel is configured in Transmit Mode or Receive Mode:

Transmit Mode

When configuring channel in transmit mode, set tx_config and the following members of rmt_tx_config_t:

Transmit the currently configured data items in a loop - loop_en
Enable the RMT carrier signal - carrier_en
Frequency of the carrier in Hz - carrier_freq_hz
Duty cycle of the carrier signal in percent (%) - carrier_duty_percent
Level of the RMT output, when the carrier is applied - carrier_level
Enable the RMT output if idle - idle_output_en
Set the signal level on the RMT output if idle - idle_level
Specify maximum number of transmissions in a loop - loop_count

Receive Mode

In receive mode, set rx_config and the following members of rmt_rx_config_t:

Enable a filter on the input of the RMT receiver - filter_en
A threshold of the filter, set in the number of ticks - filter_ticks_thresh. Pulses shorter than this setting will be filtered out. Note, that the range of entered tick values is [0..255].
A pulse length threshold that will turn the RMT receiver idle, set in number of ticks - idle_threshold. The receiver will ignore pulses longer than this setting.
Enable the RMT carrier demodulation - carrier_rm
Frequency of the carrier in Hz - carrier_freq_hz
Duty cycle of the carrier signal in percent (%) - carrier_duty_percent
Level of the RMT input, where the carrier is modulated to - carrier_level

Finalize Configuration

Once the rmt_config_t structure is populated with parameters, it should be then invoked with rmt_config() to make the configuration effective.

The last configuration step is installation of the driver in memory by calling rmt_driver_install(). If rx_buf_size parameter of this function is > 0, then a ring buffer for incoming data will be allocated. A default ISR handler will be installed, see a note in Use Interrupts.

Now, depending on how the channel is configured, we are ready to either Transmit Data or Receive Data. This is described in next two sections.

Transmit Data

Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an ‘item’, is provided in a structure rmt_item32_t. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below.

Structure of RMT items (L - signal level)

For a simple example how to define a block of items see peripherals/rmt/morse_code.

The items are provided to the RMT controller by calling function rmt_write_items(). This function also automatically triggers start of transmission. It may be called to wait for transmission completion or exit just after transmission start. In such case you can wait for the transmission end by calling rmt_wait_tx_done(). This function does not limit the number of data items to transmit. It is using an interrupt to successively copy the new data chunks to RMT’s internal memory as previously provided data are sent out.

Another way to provide data for transmission is by calling rmt_fill_tx_items(). In this case transmission is not started automatically. To control the transmission process use rmt_tx_start() and rmt_tx_stop(). The number of items to sent is restricted by the size of memory blocks allocated in the RMT controller’s internal memory, see rmt_set_mem_block_num().

Receive Data

Before starting the receiver we need some storage for incoming items. The RMT controller has 256 x 32-bits of internal RAM shared between all four channels.

In typical scenarios it is not enough as an ultimate storage for all incoming (and outgoing) items. Therefore this API supports retrieval of incoming items on the fly to save them in a ring buffer of a size defined by the user. The size is provided when calling rmt_driver_install() discussed above. To get a handle to this buffer call rmt_get_ringbuf_handle().

With the above steps complete we can start the receiver by calling rmt_rx_start() and then move to checking what’s inside the buffer. To do so, you can use common FreeRTOS functions that interact with the ring buffer. Please see an example how to do it in peripherals/rmt/ir_protocols.

To stop the receiver, call rmt_rx_stop().

Change Operation Parameters

Previously described function rmt_config() provides a convenient way to set several configuration parameters in one shot. This is usually done on application start. Then, when the application is running, the API provides an alternate way to update individual parameters by calling dedicated functions. Each function refers to the specific RMT channel provided as the first input parameter. Most of the functions have _get_ counterpart to read back the currently configured value.

Parameters Common to Transmit and Receive Mode

Selection of a GPIO pin number on the input or output of the RMT - rmt_set_gpio()
Number of memory blocks allocated for the incoming or outgoing data - rmt_set_mem_pd()
Setting of the clock divider - rmt_set_clk_div()
Selection of the clock source, note that currently one clock source is supported, the APB clock which is 80Mhz - rmt_set_source_clk()

Transmit Mode Parameters

Enable or disable the loop back mode for the transmitter - rmt_set_tx_loop_mode()
Binary level on the output to apply the carrier - rmt_set_tx_carrier(), selected from rmt_carrier_level_t
Determines the binary level on the output when transmitter is idle - rmt_set_idle_level(), selected from rmt_idle_level_t

Enable or disable loop count feature to automatically transmit items for N iterations, then trigger an ISR callback - rmt_set_tx_loop_count()
Enable automatically stopping when the number of iterations matches the set loop count. Note this is not reliable for target that doesn’t support SOC_RMT_SUPPORT_TX_LOOP_AUTOSTOP. - rmt_enable_tx_loop_autostop()

Receive Mode Parameters

The filter setting - rmt_set_rx_filter()
The receiver threshold setting - rmt_set_rx_idle_thresh()
Whether the transmitter or receiver is entitled to access RMT’s memory - rmt_set_memory_owner(), selection is from rmt_mem_owner_t.

Use Interrupts

Registering of an interrupt handler for the RMT controller is done be calling rmt_isr_register().

Note

When calling rmt_driver_install() to use the system RMT driver, a default ISR is being installed. In such a case you cannot register a generic ISR handler with rmt_isr_register().

The RMT controller triggers interrupts on four specific events describes below. To enable interrupts on these events, the following functions are provided:

The RMT receiver has finished receiving a signal - rmt_set_rx_intr_en()
The RMT transmitter has finished transmitting the signal - rmt_set_tx_intr_en()
The number of events the transmitter has sent matches a threshold value rmt_set_tx_thr_intr_en()
Ownership to the RMT memory block has been violated - rmt_set_err_intr_en()

Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling rmt_set_intr_enable_mask() or rmt_clr_intr_enable_mask().

When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as RMT.int_clr.val.chN_event_name and defined as a volatile struct in soc/esp32s2/include/soc/rmt_struct.h, where N is the RMT channel number [0, n] and the event_name is one of four events described above.

If you do not need an ISR anymore, you can deregister it by calling a function rmt_isr_deregister().

Warning

It’s not recommended for users to register an interrupt handler in their applications. RMT driver is highly dependent on interrupt, especially when doing transaction in a ping-pong way, so the driver itself has registered a default handler called rmt_driver_isr_default. Instead, if what you want is to get a notification when transaction is done, go ahead with rmt_register_tx_end_callback().

Uninstall Driver

If the RMT driver has been installed with rmt_driver_install() for some specific period of time and then not required, the driver may be removed to free allocated resources by calling rmt_driver_uninstall().

Application Examples

Using RMT to send morse code: peripherals/rmt/morse_code.
Using RMT to drive RGB LED strip: peripherals/rmt/led_strip.
NEC remote control TX and RX example: peripherals/rmt/ir_protocols.
Musical buzzer example: peripherals/rmt/musical_buzzer.

API Reference

Header File

components/driver/include/driver/rmt.h

Functions

esp_err_t rmt_set_clk_div(rmt_channel_t channel, uint8_t div_cnt)

Set RMT clock divider, channel clock is divided from source clock.

Parameters

channel – RMT channel
div_cnt – RMT counter clock divider

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_get_clk_div(rmt_channel_t channel, uint8_t *div_cnt)

Get RMT clock divider, channel clock is divided from source clock.

Parameters

channel – RMT channel
div_cnt – pointer to accept RMT counter divider

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_rx_idle_thresh(rmt_channel_t channel, uint16_t thresh)

Set RMT RX idle threshold value.

In receive mode, when no edge is detected on the input signal for longer than idle_thres channel clock cycles, the receive process is finished.

Parameters

channel – RMT channel
thresh – RMT RX idle threshold

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_get_rx_idle_thresh(rmt_channel_t channel, uint16_t *thresh)

Get RMT idle threshold value.

In receive mode, when no edge is detected on the input signal for longer than idle_thres channel clock cycles, the receive process is finished.

Parameters

channel – RMT channel
thresh – pointer to accept RMT RX idle threshold value

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_mem_block_num(rmt_channel_t channel, uint8_t rmt_mem_num)

Set RMT memory block number for RMT channel.

This function is used to configure the amount of memory blocks allocated to channel n The 8 channels share a 512x32-bit RAM block which can be read and written by the processor cores over the APB bus, as well as read by the transmitters and written by the receivers.

The RAM address range for channel n is start_addr_CHn to end_addr_CHn, which are defined by: Memory block start address is RMT_CHANNEL_MEM(n) (in soc/rmt_reg.h), that is, start_addr_chn = RMT base address + 0x800 + 64 ∗ 4 ∗ n, and end_addr_chn = RMT base address + 0x800 + 64 ∗ 4 ∗ n + 64 ∗ 4 ∗ RMT_MEM_SIZE_CHn mod 512 ∗ 4

Note

If memory block number of one channel is set to a value greater than 1, this channel will occupy the memory block of the next channel. Channel 0 can use at most 8 blocks of memory, accordingly channel 7 can only use one memory block.

Parameters

channel – RMT channel
rmt_mem_num – RMT RX memory block number, one block has 64 * 32 bits.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_get_mem_block_num(rmt_channel_t channel, uint8_t *rmt_mem_num)

Get RMT memory block number.

Parameters

channel – RMT channel
rmt_mem_num – Pointer to accept RMT RX memory block number

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_tx_carrier(rmt_channel_t channel, bool carrier_en, uint16_t high_level, uint16_t low_level, rmt_carrier_level_t carrier_level)

Configure RMT carrier for TX signal.

Set different values for carrier_high and carrier_low to set different frequency of carrier. The unit of carrier_high/low is the source clock tick, not the divided channel counter clock.

Parameters

channel – RMT channel
carrier_en – Whether to enable output carrier.
high_level – High level duration of carrier
low_level – Low level duration of carrier.
carrier_level – Configure the way carrier wave is modulated for channel.
- 1’b1:transmit on low output level
- 1’b0:transmit on high output level

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_mem_pd(rmt_channel_t channel, bool pd_en)

Set RMT memory in low power mode.

Reduce power consumed by memory. 1:memory is in low power state.

Parameters

channel – RMT channel
pd_en – RMT memory low power enable.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_get_mem_pd(rmt_channel_t channel, bool *pd_en)

Get RMT memory low power mode.

Parameters

channel – RMT channel
pd_en – Pointer to accept RMT memory low power mode.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_tx_start(rmt_channel_t channel, bool tx_idx_rst)

Set RMT start sending data from memory.

Parameters

channel – RMT channel
tx_idx_rst – Set true to reset memory index for TX. Otherwise, transmitter will continue sending from the last index in memory.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_tx_stop(rmt_channel_t channel)

Set RMT stop sending.

Parameters

channel – RMT channel

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_rx_start(rmt_channel_t channel, bool rx_idx_rst)

Set RMT start receiving data.

Parameters

channel – RMT channel
rx_idx_rst – Set true to reset memory index for receiver. Otherwise, receiver will continue receiving data to the last index in memory.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_rx_stop(rmt_channel_t channel)

Set RMT stop receiving data.

Parameters

channel – RMT channel

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_tx_memory_reset(rmt_channel_t channel)

Reset RMT TX memory.

Parameters

channel – RMT channel

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_rx_memory_reset(rmt_channel_t channel)

Reset RMT RX memory.

Parameters

channel – RMT channel

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_memory_owner(rmt_channel_t channel, rmt_mem_owner_t owner)

Set RMT memory owner.

Note

Setting memroy is only valid for RX channel.

Parameters

channel – RMT channel
owner – To set when the transmitter or receiver can process the memory of channel.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_get_memory_owner(rmt_channel_t channel, rmt_mem_owner_t *owner)

Get RMT memory owner.

Parameters

channel – RMT channel
owner – Pointer to get memory owner.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_tx_loop_mode(rmt_channel_t channel, bool loop_en)

Set RMT tx loop mode.

Parameters

channel – RMT channel
loop_en – Enable RMT transmitter loop sending mode. If set true, transmitter will continue sending from the first data to the last data in channel over and over again in a loop.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_get_tx_loop_mode(rmt_channel_t channel, bool *loop_en)

Get RMT tx loop mode.

Parameters

channel – RMT channel
loop_en – Pointer to accept RMT transmitter loop sending mode.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_rx_filter(rmt_channel_t channel, bool rx_filter_en, uint8_t thresh)

Set RMT RX filter.

In receive mode, channel will ignore input pulse when the pulse width is smaller than threshold. Counted in source clock, not divided counter clock.

Parameters

channel – RMT channel
rx_filter_en – To enable RMT receiver filter.
thresh – Threshold of pulse width for receiver.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_source_clk(rmt_channel_t channel, rmt_source_clk_t base_clk)

Set RMT source clock.

RMT module has two clock sources:

APB clock which is 80Mhz
REF tick clock, which would be 1Mhz (not supported in this version).

Parameters

channel – RMT channel
base_clk – To choose source clock for RMT module.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_get_source_clk(rmt_channel_t channel, rmt_source_clk_t *src_clk)

Get RMT source clock.

RMT module has two clock sources:

APB clock which is 80Mhz
REF tick clock, which would be 1Mhz (not supported in this version).

Parameters

channel – RMT channel
src_clk – Pointer to accept source clock for RMT module.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_idle_level(rmt_channel_t channel, bool idle_out_en, rmt_idle_level_t level)

Set RMT idle output level for transmitter.

Parameters

channel – RMT channel
idle_out_en – To enable idle level output.
level – To set the output signal’s level for channel in idle state.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_get_idle_level(rmt_channel_t channel, bool *idle_out_en, rmt_idle_level_t *level)

Get RMT idle output level for transmitter.

Parameters

channel – RMT channel
idle_out_en – Pointer to accept value of enable idle.
level – Pointer to accept value of output signal’s level in idle state for specified channel.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_get_status(rmt_channel_t channel, uint32_t *status)

Get RMT status.

Parameters

channel – RMT channel
status – Pointer to accept channel status. Please refer to RMT_CHnSTATUS_REG(n=0~7) in rmt_reg.h for more details of each field.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_rx_intr_en(rmt_channel_t channel, bool en)

Set RMT RX interrupt enable.

Parameters

channel – RMT channel
en – enable or disable RX interrupt.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_err_intr_en(rmt_channel_t channel, bool en)

Set RMT RX error interrupt enable.

Parameters

channel – RMT channel
en – enable or disable RX err interrupt.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_tx_intr_en(rmt_channel_t channel, bool en)

Set RMT TX interrupt enable.

Parameters

channel – RMT channel
en – enable or disable TX interrupt.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_tx_thr_intr_en(rmt_channel_t channel, bool en, uint16_t evt_thresh)

Set RMT TX threshold event interrupt enable.

An interrupt will be triggered when the number of transmitted items reaches the threshold value

Parameters

channel – RMT channel
en – enable or disable TX event interrupt.
evt_thresh – RMT event interrupt threshold value

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_gpio(rmt_channel_t channel, rmt_mode_t mode, gpio_num_t gpio_num, bool invert_signal)

Configure the GPIO used by RMT channel.

Parameters

channel – RMT channel
mode – RMT mode, either RMT_MODE_TX or RMT_MODE_RX
gpio_num – GPIO number, which is connected with certain RMT signal
invert_signal – Invert RMT signal physically by GPIO matrix

Returns

ESP_ERR_INVALID_ARG Configure RMT GPIO failed because of wrong parameter
ESP_OK Configure RMT GPIO successfully

esp_err_t rmt_config(const rmt_config_t *rmt_param)

Configure RMT parameters.

Parameters

rmt_param – RMT parameter struct

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_isr_register(void (*fn)(void*), void *arg, int intr_alloc_flags, rmt_isr_handle_t *handle)

Register RMT interrupt handler, the handler is an ISR.

The handler will be attached to the same CPU core that this function is running on.

Note

If you already called rmt_driver_install to use system RMT driver, please do not register ISR handler again.

Parameters

fn – Interrupt handler function.
arg – Parameter for the handler function
intr_alloc_flags – Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
handle – If non-zero, a handle to later clean up the ISR gets stored here.

Returns

ESP_OK Success
ESP_ERR_INVALID_ARG Function pointer error.
ESP_FAIL System driver installed, can not register ISR handler for RMT

esp_err_t rmt_isr_deregister(rmt_isr_handle_t handle)

Deregister previously registered RMT interrupt handler.

Parameters

handle – Handle obtained from rmt_isr_register

Returns

ESP_OK Success
ESP_ERR_INVALID_ARG Handle invalid

esp_err_t rmt_fill_tx_items(rmt_channel_t channel, const rmt_item32_t *item, uint16_t item_num, uint16_t mem_offset)

Fill memory data of channel with given RMT items.

Parameters

channel – RMT channel
item – Pointer of items.
item_num – RMT sending items number.
mem_offset – Index offset of memory.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_driver_install(rmt_channel_t channel, size_t rx_buf_size, int intr_alloc_flags)

Initialize RMT driver.

Parameters

channel – RMT channel
rx_buf_size – Size of RMT RX ringbuffer. Can be 0 if the RX ringbuffer is not used.
intr_alloc_flags – Flags for the RMT driver interrupt handler. Pass 0 for default flags. See esp_intr_alloc.h for details. If ESP_INTR_FLAG_IRAM is used, please do not use the memory allocated from psram when calling rmt_write_items.

Returns

ESP_ERR_INVALID_STATE Driver is already installed, call rmt_driver_uninstall first.
ESP_ERR_NO_MEM Memory allocation failure
ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_driver_uninstall(rmt_channel_t channel)

Uninstall RMT driver.

Parameters

channel – RMT channel

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_get_channel_status(rmt_channel_status_result_t *channel_status)

Get the current status of eight channels.

Note

Do not call this function if it is possible that rmt_driver_uninstall will be called at the same time.

Parameters

channel_status – [out] store the current status of each channel

Returns

ESP_ERR_INVALID_ARG Parameter is NULL
ESP_OK Success

esp_err_t rmt_get_counter_clock(rmt_channel_t channel, uint32_t *clock_hz)

Get speed of channel’s internal counter clock.

Parameters

channel – RMT channel
clock_hz – [out] counter clock speed, in hz

Returns

ESP_ERR_INVALID_ARG Parameter is NULL
ESP_OK Success

esp_err_t rmt_write_items(rmt_channel_t channel, const rmt_item32_t *rmt_item, int item_num, bool wait_tx_done)

RMT send waveform from rmt_item array.

This API allows user to send waveform with any length.

Note

This function will not copy data, instead, it will point to the original items, and send the waveform items. If wait_tx_done is set to true, this function will block and will not return until all items have been sent out. If wait_tx_done is set to false, this function will return immediately, and the driver interrupt will continue sending the items. We must make sure the item data will not be damaged when the driver is still sending items in driver interrupt.

Parameters

channel – RMT channel
rmt_item – head point of RMT items array. If ESP_INTR_FLAG_IRAM is used, please do not use the memory allocated from psram when calling rmt_write_items.
item_num – RMT data item number.
wait_tx_done –
- If set 1, it will block the task and wait for sending done.
- If set 0, it will not wait and return immediately.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_wait_tx_done(rmt_channel_t channel, TickType_t wait_time)

Wait RMT TX finished.

Parameters

channel – RMT channel
wait_time – Maximum time in ticks to wait for transmission to be complete. If set 0, return immediately with ESP_ERR_TIMEOUT if TX is busy (polling).

Returns

ESP_OK RMT Tx done successfully
ESP_ERR_TIMEOUT Exceeded the ‘wait_time’ given
ESP_ERR_INVALID_ARG Parameter error
ESP_FAIL Driver not installed

esp_err_t rmt_get_ringbuf_handle(rmt_channel_t channel, RingbufHandle_t *buf_handle)

Get ringbuffer from RMT.

Users can get the RMT RX ringbuffer handle, and process the RX data.

Parameters

channel – RMT channel
buf_handle – Pointer to buffer handle to accept RX ringbuffer handle.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_translator_init(rmt_channel_t channel, sample_to_rmt_t fn)

Init rmt translator and register user callback. The callback will convert the raw data that needs to be sent to rmt format. If a channel is initialized more than once, tha user callback will be replaced by the later.

Parameters

channel – RMT channel .
fn – Point to the data conversion function.

Returns

ESP_FAIL Init fail.
ESP_OK Init success.

esp_err_t rmt_translator_set_context(rmt_channel_t channel, void *context)

Set user context for the translator of specific channel.

Parameters

channel – RMT channel number
context – User context

Returns

ESP_FAIL Set context fail
ESP_OK Set context success

esp_err_t rmt_translator_get_context(const size_t *item_num, void **context)

Get the user context set by ‘rmt_translator_set_context’.

Note

This API must be invoked in the RMT translator callback function, and the first argument must be the actual parameter ‘item_num’ you got in that callback function.

Parameters

item_num – Address of the memory which contains the number of translated items (It’s from driver’s internal memroy)
context – Returned User context

Returns

ESP_FAIL Get context fail
ESP_OK Get context success

esp_err_t rmt_write_sample(rmt_channel_t channel, const uint8_t *src, size_t src_size, bool wait_tx_done)

Translate uint8_t type of data into rmt format and send it out. Requires rmt_translator_init to init the translator first.

Parameters

channel – RMT channel .
src – Pointer to the raw data.
src_size – The size of the raw data.
wait_tx_done – Set true to wait all data send done.

Returns

ESP_FAIL Send fail
ESP_OK Send success

rmt_tx_end_callback_t rmt_register_tx_end_callback(rmt_tx_end_fn_t function, void *arg)

Registers a callback that will be called when transmission ends.

Called by rmt_driver_isr_default in interrupt context.

Note

Requires rmt_driver_install to install the default ISR handler.

Parameters

function – Function to be called from the default interrupt handler or NULL.
arg – Argument which will be provided to the callback when it is called.

Returns

the previous callback settings (members will be set to NULL if there was none)

esp_err_t rmt_add_channel_to_group(rmt_channel_t channel)

Add channel into a synchronous group (channels in the same group can start transaction simultaneously)

Parameters

channel – RMT channel

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_remove_channel_from_group(rmt_channel_t channel)

Remove channel out of a group.

Parameters

channel – RMT channel

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_set_tx_loop_count(rmt_channel_t channel, uint32_t count)

Set loop count threshold value for RMT TX channel.

When tx loop count reaches this value, an ISR callback will notify user

Parameters

channel – RMT channel
count – loop count, 1 ~ 1023

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_enable_tx_loop_autostop(rmt_channel_t channel, bool en)

Enable or disable the feature that when loop count reaches the threshold, RMT will stop transmitting.

When the loop auto-stop feature is enabled will halt RMT transmission after the loop count reaches a certain threshold
When disabled, the RMT transmission continue indefinitely until halted by the users

Note

The auto-stop feature is implemented in hardware on particular targets (i.e. those with SOC_RMT_SUPPORT_TX_LOOP_AUTOSTOP defined). Otherwise, the auto-stop feature is implemented in software via the interrupt.

Parameters

channel – RMT channel
en – enable bit

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

esp_err_t rmt_memory_rw_rst(rmt_channel_t channel)

Reset RMT TX/RX memory index.

Parameters

channel – RMT channel

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

void rmt_set_intr_enable_mask(uint32_t mask)

Set mask value to RMT interrupt enable register.

Parameters: mask – Bit mask to set to the register

void rmt_clr_intr_enable_mask(uint32_t mask)

Clear mask value to RMT interrupt enable register.

Parameters: mask – Bit mask to clear the register

esp_err_t rmt_set_pin(rmt_channel_t channel, rmt_mode_t mode, gpio_num_t gpio_num)

Set RMT pin.

Parameters

channel – RMT channel
mode – TX or RX mode for RMT
gpio_num – GPIO number to transmit or receive the signal.

Returns

ESP_ERR_INVALID_ARG Parameter error
ESP_OK Success

Structures

struct rmt_tx_config_t

Data struct of RMT TX configure parameters.

Public Members

uint32_t carrier_freq_hz: RMT carrier frequency

rmt_carrier_level_t carrier_level: Level of the RMT output, when the carrier is applied

rmt_idle_level_t idle_level: RMT idle level

uint8_t carrier_duty_percent: RMT carrier duty (%)

uint32_t loop_count: Maximum loop count

bool carrier_en: RMT carrier enable

bool loop_en: Enable sending RMT items in a loop

bool idle_output_en: RMT idle level output enable

struct rmt_rx_config_t

Data struct of RMT RX configure parameters.

Public Members

uint16_t idle_threshold: RMT RX idle threshold

uint8_t filter_ticks_thresh: RMT filter tick number

bool filter_en: RMT receiver filter enable

bool rm_carrier: RMT receiver remove carrier enable

uint32_t carrier_freq_hz: RMT carrier frequency

uint8_t carrier_duty_percent: RMT carrier duty (%)

rmt_carrier_level_t carrier_level: The level to remove the carrier

struct rmt_config_t

Data struct of RMT configure parameters.

Public Members

rmt_mode_t rmt_mode: RMT mode: transmitter or receiver

rmt_channel_t channel: RMT channel

gpio_num_t gpio_num: RMT GPIO number

uint8_t clk_div: RMT channel counter divider

uint8_t mem_block_num: RMT memory block number

uint32_t flags: RMT channel extra configurations, OR’d with RMT_CHANNEL_FLAGS_[*]

rmt_tx_config_t tx_config: RMT TX parameter

rmt_rx_config_t rx_config: RMT RX parameter

struct rmt_tx_end_callback_t

Structure encapsulating a RMT TX end callback.

Public Members

rmt_tx_end_fn_t function: Function which is called on RMT TX end

void *arg: Optional argument passed to function

Macros

RMT_CHANNEL_FLAGS_AWARE_DFS: Channel can work during APB clock scaling

RMT_CHANNEL_FLAGS_INVERT_SIG: Invert RMT signal

RMT_MEM_ITEM_NUM: Define memory space of each RMT channel (in words = 4 bytes)

RMT_DEFAULT_CONFIG_TX(gpio, channel_id): Default configuration for Tx channel.

RMT_DEFAULT_CONFIG_RX(gpio, channel_id): Default configuration for RX channel.

Type Definitions

typedef intr_handle_t rmt_isr_handle_t: RMT interrupt handle.

typedef void (*rmt_tx_end_fn_t)(rmt_channel_t channel, void *arg): Type of RMT Tx End callback function.

typedef void (*sample_to_rmt_t)(const void *src, rmt_item32_t *dest, size_t src_size, size_t wanted_num, size_t *translated_size, size_t *item_num)

User callback function to convert uint8_t type data to rmt format(rmt_item32_t).

This function may be called from an ISR, so, the code should be short and efficient.

Note

In fact, item_num should be a multiple of translated_size, e.g. : When we convert each byte of uint8_t type data to rmt format data, the relation between item_num and translated_size should be item_num = translated_size*8.

Param src: Pointer to the buffer storing the raw data that needs to be converted to rmt format.
Param dest: [out] Pointer to the buffer storing the rmt format data.
Param src_size: The raw data size.
Param wanted_num: The number of rmt format data that wanted to get.
Param translated_size: [out] The size of the raw data that has been converted to rmt format, it should return 0 if no data is converted in user callback.
Param item_num: [out] The number of the rmt format data that actually converted to, it can be less than wanted_num if there is not enough raw data, but cannot exceed wanted_num. it should return 0 if no data was converted.

Header File

components/hal/include/hal/rmt_types.h

Structures

struct rmt_channel_status_result_t

Data struct of RMT channel status.

Public Members

rmt_channel_status_t status[RMT_CHANNEL_MAX]: Store the current status of each channel

Enumerations

enum rmt_channel_t

RMT channel ID.

Values:

enumerator RMT_CHANNEL_0: RMT channel number 0

enumerator RMT_CHANNEL_1: RMT channel number 1

enumerator RMT_CHANNEL_2: RMT channel number 2

enumerator RMT_CHANNEL_3: RMT channel number 3

enumerator RMT_CHANNEL_MAX: Number of RMT channels

enum rmt_mem_owner_t

RMT Internal Memory Owner.

Values:

enumerator RMT_MEM_OWNER_TX: RMT RX mode, RMT transmitter owns the memory block

enumerator RMT_MEM_OWNER_RX: RMT RX mode, RMT receiver owns the memory block

enumerator RMT_MEM_OWNER_MAX

enum rmt_source_clk_t

Clock Source of RMT Channel.

Values:

enumerator RMT_BASECLK_REF: RMT source clock is REF_TICK, 1MHz by default

enumerator RMT_BASECLK_APB: RMT source clock is APB CLK, 80Mhz by default

enumerator RMT_BASECLK_MAX

enum rmt_data_mode_t

RMT Data Mode.

Note

We highly recommended to use MEM mode not FIFO mode since there will be some gotcha in FIFO mode.

Values:

enumerator RMT_DATA_MODE_FIFO

enumerator RMT_DATA_MODE_MEM

enumerator RMT_DATA_MODE_MAX

enum rmt_mode_t

RMT Channel Working Mode (TX or RX)

Values:

enumerator RMT_MODE_TX: RMT TX mode

enumerator RMT_MODE_RX: RMT RX mode

enumerator RMT_MODE_MAX

enum rmt_idle_level_t

RMT Idle Level.

Values:

enumerator RMT_IDLE_LEVEL_LOW: RMT TX idle level: low Level

enumerator RMT_IDLE_LEVEL_HIGH: RMT TX idle level: high Level

enumerator RMT_IDLE_LEVEL_MAX

enum rmt_carrier_level_t

RMT Carrier Level.

Values:

enumerator RMT_CARRIER_LEVEL_LOW: RMT carrier wave is modulated for low Level output

enumerator RMT_CARRIER_LEVEL_HIGH: RMT carrier wave is modulated for high Level output

enumerator RMT_CARRIER_LEVEL_MAX

enum rmt_channel_status_t

RMT Channel Status.

Values:

enumerator RMT_CHANNEL_UNINIT: RMT channel uninitialized

enumerator RMT_CHANNEL_IDLE: RMT channel status idle

enumerator RMT_CHANNEL_BUSY: RMT channel status busy

Provide feedback about this document