RMT

Overview

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 many other types of signals.

Application Example

NEC remote control TX and RX example: examples/11_rmt_nec_tx_rx.

API Reference

Header Files

Macros

RMT_MEM_BLOCK_BYTE_NUM (256)
RMT_MEM_ITEM_NUM (RMT_MEM_BLOCK_BYTE_NUM/4)

Enumerations

enum rmt_channel_t

Values:

RMT_CHANNEL_0 =0

RMT Channel0

RMT_CHANNEL_1

RMT Channel1

RMT_CHANNEL_2

RMT Channel2

RMT_CHANNEL_3

RMT Channel3

RMT_CHANNEL_4

RMT Channel4

RMT_CHANNEL_5

RMT Channel5

RMT_CHANNEL_6

RMT Channel6

RMT_CHANNEL_7

RMT Channel7

RMT_CHANNEL_MAX
enum rmt_mem_owner_t

Values:

RMT_MEM_OWNER_TX = 0

RMT RX mode, RMT transmitter owns the memory block

RMT_MEM_OWNER_RX = 1

RMT RX mode, RMT receiver owns the memory block

RMT_MEM_OWNER_MAX
enum rmt_source_clk_t

Values:

RMT_BASECLK_REF = 0

RMT source clock system reference tick, 1MHz by default(Not supported in this version)

RMT_BASECLK_APB

RMT source clock is APB CLK, 80Mhz by default

RMT_BASECLK_MAX
enum rmt_data_mode_t

Values:

RMT_DATA_MODE_FIFO = 0
RMT_DATA_MODE_MEM = 1
RMT_DATA_MODE_MAX
enum rmt_mode_t

Values:

RMT_MODE_TX =0

RMT TX mode

RMT_MODE_RX

RMT RX mode

RMT_MODE_MAX
enum rmt_idle_level_t

Values:

RMT_IDLE_LEVEL_LOW =0

RMT TX idle level: low Level

RMT_IDLE_LEVEL_HIGH

RMT TX idle level: high Level

RMT_IDLE_LEVEL_MAX
enum rmt_carrier_level_t

Values:

RMT_CARRIER_LEVEL_LOW =0

RMT carrier wave is modulated for low Level output

RMT_CARRIER_LEVEL_HIGH

RMT carrier wave is modulated for high Level output

RMT_CARRIER_LEVEL_MAX

Structures

struct rmt_tx_config_t

Data struct of RMT TX configure parameters.

Public Members

bool loop_en

RMT loop output mode

uint32_t carrier_freq_hz

RMT carrier frequency

uint8_t carrier_duty_percent

RMT carrier duty (%)

rmt_carrier_level_t carrier_level

RMT carrier level

bool carrier_en

RMT carrier enable

rmt_idle_level_t idle_level

RMT idle level

bool idle_output_en

RMT idle level output enable

struct rmt_rx_config_t

Data struct of RMT RX configure parameters.

Public Members

bool filter_en

RMT receiver filer enable

uint8_t filter_ticks_thresh

RMT filter tick number

uint16_t idle_threshold

RMT RX idle threshold

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

uint8_t clk_div

RMT channel counter divider

gpio_num_t gpio_num

RMT GPIO number

uint8_t mem_block_num

RMT memory block number

rmt_tx_config_t tx_config

RMT TX parameter

rmt_rx_config_t rx_config

RMT RX parameter

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.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • div_cnt: RMT counter clock divider

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.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • div_cnt: pointer to accept RMT counter divider

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.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • thresh: RMT RX idle threshold

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.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • thresh: pointer to accept RMT RX idle threshold value

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. Channel0 can use at most 8 blocks of memory, accordingly channel7 can only use one memory block.
Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • rmt_mem_num: RMT RX memory block number, one block has 64 * 32 bits.

esp_err_t rmt_get_mem_block_num(rmt_channel_t channel, uint8_t *rmt_mem_num)

Get RMT memory block number.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • rmt_mem_num: Pointer to accept RMT RX memory block number

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.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • 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 channel0-7.
                     1'b1:transmit on low output level
    
                     1'b0:transmit on high output level
    

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.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • pd_en: RMT memory low power enable.

esp_err_t rmt_get_mem_pd(rmt_channel_t channel, bool *pd_en)

Get RMT memory low power mode.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • pd_en: Pointer to accept RMT memory low power mode.

esp_err_t rmt_tx_start(rmt_channel_t channel, bool tx_idx_rst)

Set RMT start sending data from memory.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • tx_idx_rst: Set true to reset memory index for TX. Otherwise, transmitter will continue sending from the last index in memory.

esp_err_t rmt_tx_stop(rmt_channel_t channel)

Set RMT stop sending.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)

esp_err_t rmt_rx_start(rmt_channel_t channel, bool rx_idx_rst)

Set RMT start receiving data.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • rx_idx_rst: Set true to reset memory index for receiver. Otherwise, receiver will continue receiving data to the last index in memory.

esp_err_t rmt_rx_stop(rmt_channel_t channel)

Set RMT stop receiving data.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)

esp_err_t rmt_memory_rw_rst(rmt_channel_t channel)

Reset RMT TX/RX memory index.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)

esp_err_t rmt_set_memory_owner(rmt_channel_t channel, rmt_mem_owner_t owner)

Set RMT memory owner.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • owner: To set when the transmitter or receiver can process the memory of channel.

esp_err_t rmt_get_memory_owner(rmt_channel_t channel, rmt_mem_owner_t *owner)

Get RMT memory owner.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • owner: Pointer to get memory owner.

esp_err_t rmt_set_tx_loop_mode(rmt_channel_t channel, bool loop_en)

Set RMT tx loop mode.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • loop_en: To enable RMT transmitter loop sending mode.
               If set true, transmitter will continue sending from the first data
               to the last data in channel0-7 again and again.
    

esp_err_t rmt_get_tx_loop_mode(rmt_channel_t channel, bool *loop_en)

Get RMT tx loop mode.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • loop_en: Pointer to accept RMT transmitter loop sending mode.

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, channel0-7 will ignore input pulse when the pulse width is smaller than threshold. Counted in source clock, not divided counter clock.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • rx_filter_en: To enable RMT receiver filter.
  • thresh: Threshold of pulse width for receiver.

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 source clock:

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

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • base_clk: To choose source clock for RMT module.

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 source clock:

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

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • src_clk: Pointer to accept source clock for RMT module.

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.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • idle_out_en: To enable idle level output.
  • level: To set the output signal’s level for channel0-7 in idle state.

esp_err_t rmt_get_status(rmt_channel_t channel, uint32_t *status)

Get RMT status.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0-7)
  • status: Pointer to accept channel status.

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_rx_intr_en(rmt_channel_t channel, bool en)

Set RMT RX interrupt enable.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0 - 7)
  • en: enable or disable RX interrupt.

esp_err_t rmt_set_err_intr_en(rmt_channel_t channel, bool en)

Set RMT RX error interrupt enable.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0 - 7)
  • en: enable or disable RX err interrupt.

esp_err_t rmt_set_tx_intr_en(rmt_channel_t channel, bool en)

Set RMT TX interrupt enable.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0 - 7)
  • en: enable or disable TX interrupt.

esp_err_t rmt_set_evt_intr_en(rmt_channel_t channel, bool en, uint16_t evt_thresh)

Set RMT TX event interrupt enable.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0 - 7)
  • en: enable or disable TX event interrupt.
  • evt_thresh: RMT event interrupt threshold value

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

Set RMT pins.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0 - 7)
  • mode: TX or RX mode for RMT
  • gpio_num: GPIO number to transmit or receive the signal.

esp_err_t rmt_config(rmt_config_t *rmt_param)

Configure RMT parameters.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • rmt_param: RMT parameter structor

esp_err_t rmt_isr_register(uint8_t rmt_intr_num, void (*fn)(void *), void *arg, )

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. Users should know that which CPU is running and then pick a INUM that is not used by system. We can find the information of INUM and interrupt level in soc.h.

Note
If you already called rmt_driver_install to use system RMT driver, please do not register ISR handler again.
Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Function pointer error.
  • ESP_FAIL System driver installed, can not register ISR handler for RMT
Parameters
  • rmt_intr_num: RMT interrupt number, check the info in soc.h, and please see the core-isa.h for more details
  • fn: Interrupt handler function.
         @note
         the handler function MUST be defined with attribution of "IRAM_ATTR".
    
  • arg: Parameter for handler function

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

Fill memory data of channel with given RMT items.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0 - 7)
  • item: Pointer of items.
  • item_num: RMT sending items number.
  • mem_offset: Index offset of memory.

esp_err_t rmt_driver_install(rmt_channel_t channel, size_t rx_buf_size, int rmt_intr_num)

Initialize RMT driver.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0 - 7)
  • rx_buf_size: Size of RMT RX ringbuffer.
       @note
       If we do not need RX ringbuffer, just set rx_buf_size to 0.
    
       @note
       When we call rmt_driver_install function, it will register a driver ISR handler,
       DO NOT REGISTER ISR HANDLER AGAIN.
    
  • rmt_intr_num: RMT interrupt number.

esp_err_t rmt_driver_uninstall(rmt_channel_t channel)

Uninstall RMT driver.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0 - 7)

esp_err_t rmt_write_items(rmt_channel_t channel, 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.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0 - 7)
  • rmt_item: head point of RMT items array.
  • 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.
    
                    @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.
    

esp_err_t rmt_wait_tx_done(rmt_channel_t channel)

Wait RMT TX finished.

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0 - 7)

esp_err_t rmt_get_ringbuf_handler(rmt_channel_t channel, RingbufHandle_t *buf_handler)

Get ringbuffer from UART.

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

Return
  • ESP_ERR_INVALID_ARG Parameter error
  • ESP_OK Success
Parameters
  • channel: RMT channel (0 - 7)
  • buf_handler: Pointer to buffer handler to accept RX ringbuffer handler.