1RMT
2===
3
4The 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.
5
6The 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.
7
8.. blockdiag::
9    :scale: 100
10    :caption: RMT Transmitter Overview
11    :align: center
12
13    blockdiag rmt_tx {
14
15        node_width = 80;
16        node_height = 60;
17        default_group_color = lightgrey;
18
19        a -> b -> c -> d;
20        e -> f -> g -- h;
21        d -> o [label=GPIO];
22        h -> d [folded];
23
24        a [style=none, width=100, label="{11,high,7,low},\n{5,high,5,low},\n..."]
25        b [label="Waveform\nGenerator"]
26        c [style=none, label="", background="../../../_static/rmt-waveform.png"]
27        d [shape=beginpoint, label="mod"]
28        e [style=none, width=60, height=40, label="Carrier\nenable"]
29        f [label="Carrier\nGenerator"]
30        g [style=none, label="", background="../../../_static/rmt-carrier.png"]
31        h [shape=none]
32        o [style=none, label="", background="../../../_static/rmt-waveform-modulated.png"]
33
34        group {
35            label = Input
36            a,e;
37        }
38        group {
39            label = "RMT Transmitter"
40            b,f,c,g,d,h;
41        }
42        group {
43            label = Output
44            o;
45        }
46    }
47
48The 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.
49
50.. blockdiag::
51    :scale: 90
52    :caption: RMT Receiver Overview
53    :align: center
54
55    blockdiag rmt_rx {
56
57        node_width = 80;
58        node_height = 60;
59        default_group_color = lightgrey;
60
61        a -> b [label=GPIO];
62        b -> c -> d;
63        e -- f;
64        f -> b [folded];
65
66        a [style=none, label="", background="../../../_static/rmt-waveform.png"]
67        b [label=Filter]
68        c [label="Edge\nDetect"]
69        d [style=none, width=100, label="{11,high,7,low},\n{5,high,5,low},\n..."]
70        e [style=none, width=60, height=40, label="Filter\nenable"]
71        f [shape=none, label=""]
72
73        group {
74            label = Input
75            a,e;
76        }
77        group {
78            label = "RMT Receiver"
79            b,c;
80        }
81        group {
82            label = Output
83            d;
84        }
85    }
86
87There couple of typical steps to setup and operate the RMT and they are discussed in the following sections:
88
891. `Configure Driver`_
902. `Transmit Data`_ or `Receive Data`_
913. `Change Operation Parameters`_
924. `Use Interrupts`_
93
94.. only:: esp32
95
96    The RMT has eight channels numbered from zero to seven. Each channel is able to independently transmit or receive data. They are referred to using indexes defined in structure :cpp:type:`rmt_channel_t`.
97
98.. only:: esp32s2
99
100    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 :cpp:type:`rmt_channel_t`.
101
102.. only:: esp32c3
103
104    The RMT has four channels numbered from zero to three. The first half (i.e. Channel 0 ~ 1) channels can only be configured for transmitting, and the other half (i.e. Channel 2 ~ 3) channels can only be configured for receiving. They are referred to using indexes defined in structure :cpp:type:`rmt_channel_t`.
105
106Configure Driver
107----------------
108
109There are several parameters that define how particular channel operates. Most of these parameters are configured by setting specific members of :cpp:type:`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.
110
111
112Common Parameters
113^^^^^^^^^^^^^^^^^
114
115* The **channel** to be configured, select one from the :cpp:type:`rmt_channel_t` enumerator.
116* 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 :cpp:type:`rmt_mode_t`.
117* What is the **pin number** to transmit or receive RMT signals, selected by setting **gpio_num**.
118* How many **memory blocks** will be used by the channel, set with **mem_block_num**.
119* Extra miscellaneous parameters for the channel can be set in the **flags**.
120
121    * 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 :doc:`power_management <../system/power_management>` for more information.
122
123* 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.
124
125.. note::
126
127    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'.
128
129There are also couple of specific parameters that should be set up depending if selected channel is configured in `Transmit Mode`_ or `Receive Mode`_:
130
131
132Transmit Mode
133^^^^^^^^^^^^^
134
135When configuring channel in transmit mode, set **tx_config** and the following members of :cpp:type:`rmt_tx_config_t`:
136
137.. list::
138
139    * Transmit the currently configured data items in a loop - **loop_en**
140    * Enable the RMT carrier signal - **carrier_en**
141    * Frequency of the carrier in Hz - **carrier_freq_hz**
142    * Duty cycle of the carrier signal in percent (%) - **carrier_duty_percent**
143    * Level of the RMT output, when the carrier is applied - **carrier_level**
144    * Enable the RMT output if idle - **idle_output_en**
145    * Set the signal level on the RMT output if idle - **idle_level**
146    :esp32s2: * Specify maximum number of transmissions in a loop - **loop_count**
147
148Receive Mode
149^^^^^^^^^^^^
150
151In receive mode, set **rx_config** and the following members of :cpp:type:`rmt_rx_config_t`:
152
153.. list::
154
155    * Enable a filter on the input of the RMT receiver - **filter_en**
156    * 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].
157    * 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.
158    :esp32s2: * Enable the RMT carrier demodulation - **carrier_rm**
159    :esp32s2: * Frequency of the carrier in Hz - **carrier_freq_hz**
160    :esp32s2: * Duty cycle of the carrier signal in percent (%) - **carrier_duty_percent**
161    :esp32s2: * Level of the RMT input, where the carrier is modulated to - **carrier_level**
162
163Finalize Configuration
164^^^^^^^^^^^^^^^^^^^^^^
165
166Once the :cpp:type:`rmt_config_t` structure is populated with parameters, it should be then invoked with :cpp:func:`rmt_config` to make the configuration effective.
167
168The last configuration step is installation of the driver in memory by calling :cpp:func:`rmt_driver_install`. If :cpp:type:`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`_.
169
170Now, depending on how the channel is configured, we are ready to either `Transmit Data`_ or `Receive Data`_. This is described in next two sections.
171
172
173Transmit Data
174-------------
175
176Before 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 :cpp:type:`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.
177
178.. packetdiag::
179    :caption: Structure of RMT items (L - signal level)
180    :align: center
181
182    packetdiag rmt_items {
183        colwidth = 32
184        node_width = 10
185        node_height = 24
186        default_fontsize = 12
187
188        0-14: Period (15)
189        15: L
190        16-30: Period (15)
191        31: L
192        32-95: ... [colheight=2]
193        96-110: Period (15)
194        111: L
195        112-126: Period (15)
196        127: L
197    }
198
199For a simple example how to define a block of items see :example:`peripherals/rmt/morse_code`.
200
201The items are provided to the RMT controller by calling function :cpp:func:`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 :cpp:func:`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.
202
203Another way to provide data for transmission is by calling :cpp:func:`rmt_fill_tx_items`. In this case transmission is not started automatically. To control the transmission process use :cpp:func:`rmt_tx_start` and :cpp:func:`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 :cpp:func:`rmt_set_mem_block_num`.
204
205
206Receive Data
207------------
208
209.. only:: esp32
210
211    Before starting the receiver we need some storage for incoming items. The RMT controller has 512 x 32-bits of internal RAM shared between all eight channels.
212
213.. only:: esp32s2
214
215    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.
216
217.. only:: esp32c3
218
219    Before starting the receiver we need some storage for incoming items. The RMT controller has 192 x 32-bits of internal RAM shared between all four channels.
220
221In 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 :cpp:func:`rmt_driver_install` discussed above. To get a handle to this buffer call :cpp:func:`rmt_get_ringbuf_handle`.
222
223With the above steps complete we can start the receiver by calling :cpp:func:`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 :example:`peripherals/rmt/ir_protocols`.
224
225To stop the receiver, call :cpp:func:`rmt_rx_stop`.
226
227
228Change Operation Parameters
229---------------------------
230
231Previously described function :cpp:func:`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.
232
233
234Parameters Common to Transmit and Receive Mode
235^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
236
237* Selection of a GPIO pin number on the input or output of the RMT - :cpp:func:`rmt_set_pin`
238* Number of memory blocks allocated for the incoming or outgoing data - :cpp:func:`rmt_set_mem_pd`
239* Setting of the clock divider - :cpp:func:`rmt_set_clk_div`
240* Selection of the clock source, note that currently one clock source is supported, the APB clock which is 80Mhz - :cpp:func:`rmt_set_source_clk`
241
242
243Transmit Mode Parameters
244^^^^^^^^^^^^^^^^^^^^^^^^
245
246* Enable or disable the loop back mode for the transmitter - :cpp:func:`rmt_set_tx_loop_mode`
247* Binary level on the output to apply the carrier - :cpp:func:`rmt_set_tx_carrier`, selected from :cpp:type:`rmt_carrier_level_t`
248* Determines the binary level on the output when transmitter is idle - :cpp:func:`rmt_set_idle_level()`, selected from :cpp:type:`rmt_idle_level_t`
249
250
251Receive Mode Parameters
252^^^^^^^^^^^^^^^^^^^^^^^
253
254* The filter setting - :cpp:func:`rmt_set_rx_filter`
255* The receiver threshold setting - :cpp:func:`rmt_set_rx_idle_thresh`
256* Whether the transmitter or receiver is entitled to access RMT's memory - :cpp:func:`rmt_set_memory_owner`, selection is from :cpp:type:`rmt_mem_owner_t`.
257
258
259Use Interrupts
260--------------
261
262Registering of an interrupt handler for the RMT controller is done be calling :cpp:func:`rmt_isr_register`.
263
264.. note::
265
266    When calling :cpp:func:`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 :cpp:func:`rmt_isr_register`.
267
268The RMT controller triggers interrupts on four specific events describes below. To enable interrupts on these events, the following functions are provided:
269
270* The RMT receiver has finished receiving a signal - :cpp:func:`rmt_set_rx_intr_en`
271* The RMT transmitter has finished transmitting the signal - :cpp:func:`rmt_set_tx_intr_en`
272* The number of events the transmitter has sent matches a threshold value :cpp:func:`rmt_set_tx_thr_intr_en`
273* Ownership to the RMT memory block has been violated - :cpp:func:`rmt_set_err_intr_en`
274
275Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling :cpp:func:`rmt_set_intr_enable_mask` or :cpp:func:`rmt_clr_intr_enable_mask`.
276
277When 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 :component_file:`soc/{IDF_TARGET_PATH_NAME}/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.
278
279If you do not need an ISR anymore, you can deregister it by calling a function :cpp:func:`rmt_isr_deregister`.
280
281.. warning::
282
283    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``.
284    Instead, if what you want is to get a notification when transaction is done, go ahead with :cpp:func:`rmt_register_tx_end_callback`.
285
286
287Uninstall Driver
288----------------
289
290If the RMT driver has been installed with :cpp:func:`rmt_driver_install` for some specific period of time and then not required, the driver may be removed to free allocated resources by calling :cpp:func:`rmt_driver_uninstall`.
291
292
293Application Examples
294--------------------
295
296* Using RMT to send morse code: :example:`peripherals/rmt/morse_code`.
297* Using RMT to drive RGB LED strip: :example:`peripherals/rmt/led_strip`.
298* NEC remote control TX and RX example: :example:`peripherals/rmt/ir_protocols`.
299* Musical buzzer example: :example:`peripherals/rmt/musical_buzzer`.
300
301
302API Reference
303-------------
304
305.. include-build-file:: inc/rmt.inc
306.. include-build-file:: inc/rmt_types.inc
307
308