1 /* 2 * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 #include <stdbool.h> 14 #include <stdint.h> 15 #include "esp_err.h" 16 #include "soc/soc_caps.h" 17 #include "driver/gpio.h" 18 #include "freertos/FreeRTOS.h" 19 #include "freertos/ringbuf.h" 20 #include "soc/rmt_struct.h" 21 #include "hal/rmt_types.h" 22 23 #define RMT_CHANNEL_FLAGS_AWARE_DFS (1 << 0) /*!< Channel can work during APB clock scaling */ 24 #define RMT_CHANNEL_FLAGS_INVERT_SIG (1 << 1) /*!< Invert RMT signal */ 25 26 /** @cond */ 27 #define RMT_CHANNEL_FLAGS_ALWAYS_ON RMT_CHANNEL_FLAGS_AWARE_DFS /*!< Deprecated name, defined here for compatibility */ 28 /** @endcond */ 29 30 /** 31 * @brief Define memory space of each RMT channel (in words = 4 bytes) 32 * 33 */ 34 #define RMT_MEM_ITEM_NUM SOC_RMT_MEM_WORDS_PER_CHANNEL 35 36 /** 37 * @brief Data struct of RMT TX configure parameters 38 */ 39 typedef struct { 40 uint32_t carrier_freq_hz; /*!< RMT carrier frequency */ 41 rmt_carrier_level_t carrier_level; /*!< Level of the RMT output, when the carrier is applied */ 42 rmt_idle_level_t idle_level; /*!< RMT idle level */ 43 uint8_t carrier_duty_percent; /*!< RMT carrier duty (%) */ 44 #if SOC_RMT_SUPPORT_TX_LOOP_COUNT 45 uint32_t loop_count; /*!< Maximum loop count */ 46 #endif 47 bool carrier_en; /*!< RMT carrier enable */ 48 bool loop_en; /*!< Enable sending RMT items in a loop */ 49 bool idle_output_en; /*!< RMT idle level output enable */ 50 } rmt_tx_config_t; 51 52 /** 53 * @brief Data struct of RMT RX configure parameters 54 */ 55 typedef struct { 56 uint16_t idle_threshold; /*!< RMT RX idle threshold */ 57 uint8_t filter_ticks_thresh; /*!< RMT filter tick number */ 58 bool filter_en; /*!< RMT receiver filter enable */ 59 #if SOC_RMT_SUPPORT_RX_DEMODULATION 60 bool rm_carrier; /*!< RMT receiver remove carrier enable */ 61 uint32_t carrier_freq_hz; /*!< RMT carrier frequency */ 62 uint8_t carrier_duty_percent; /*!< RMT carrier duty (%) */ 63 rmt_carrier_level_t carrier_level; /*!< The level to remove the carrier */ 64 #endif 65 } rmt_rx_config_t; 66 67 /** 68 * @brief Data struct of RMT configure parameters 69 */ 70 typedef struct { 71 rmt_mode_t rmt_mode; /*!< RMT mode: transmitter or receiver */ 72 rmt_channel_t channel; /*!< RMT channel */ 73 gpio_num_t gpio_num; /*!< RMT GPIO number */ 74 uint8_t clk_div; /*!< RMT channel counter divider */ 75 uint8_t mem_block_num; /*!< RMT memory block number */ 76 uint32_t flags; /*!< RMT channel extra configurations, OR'd with RMT_CHANNEL_FLAGS_[*] */ 77 union { 78 rmt_tx_config_t tx_config; /*!< RMT TX parameter */ 79 rmt_rx_config_t rx_config; /*!< RMT RX parameter */ 80 }; 81 } rmt_config_t; 82 83 /** 84 * @brief Default configuration for Tx channel 85 * 86 */ 87 #define RMT_DEFAULT_CONFIG_TX(gpio, channel_id) \ 88 { \ 89 .rmt_mode = RMT_MODE_TX, \ 90 .channel = channel_id, \ 91 .gpio_num = gpio, \ 92 .clk_div = 80, \ 93 .mem_block_num = 1, \ 94 .flags = 0, \ 95 .tx_config = { \ 96 .carrier_freq_hz = 38000, \ 97 .carrier_level = RMT_CARRIER_LEVEL_HIGH, \ 98 .idle_level = RMT_IDLE_LEVEL_LOW, \ 99 .carrier_duty_percent = 33, \ 100 .carrier_en = false, \ 101 .loop_en = false, \ 102 .idle_output_en = true, \ 103 } \ 104 } 105 106 /** 107 * @brief Default configuration for RX channel 108 * 109 */ 110 #define RMT_DEFAULT_CONFIG_RX(gpio, channel_id) \ 111 { \ 112 .rmt_mode = RMT_MODE_RX, \ 113 .channel = channel_id, \ 114 .gpio_num = gpio, \ 115 .clk_div = 80, \ 116 .mem_block_num = 1, \ 117 .flags = 0, \ 118 .rx_config = { \ 119 .idle_threshold = 12000, \ 120 .filter_ticks_thresh = 100, \ 121 .filter_en = true, \ 122 } \ 123 } 124 125 /** 126 * @brief RMT interrupt handle 127 * 128 */ 129 typedef intr_handle_t rmt_isr_handle_t; 130 131 /** 132 * @brief Type of RMT Tx End callback function 133 * 134 */ 135 typedef void (*rmt_tx_end_fn_t)(rmt_channel_t channel, void *arg); 136 137 /** 138 * @brief Structure encapsulating a RMT TX end callback 139 */ 140 typedef struct { 141 rmt_tx_end_fn_t function; /*!< Function which is called on RMT TX end */ 142 void *arg; /*!< Optional argument passed to function */ 143 } rmt_tx_end_callback_t; 144 145 /** 146 * @brief User callback function to convert uint8_t type data to rmt format(rmt_item32_t). 147 * 148 * This function may be called from an ISR, so, the code should be short and efficient. 149 * 150 * @param src Pointer to the buffer storing the raw data that needs to be converted to rmt format. 151 * @param[out] dest Pointer to the buffer storing the rmt format data. 152 * @param src_size The raw data size. 153 * @param wanted_num The number of rmt format data that wanted to get. 154 * @param[out] translated_size The size of the raw data that has been converted to rmt format, 155 * it should return 0 if no data is converted in user callback. 156 * @param[out] item_num The number of the rmt format data that actually converted to, 157 * it can be less than wanted_num if there is not enough raw data, but cannot exceed wanted_num. 158 * it should return 0 if no data was converted. 159 * 160 * @note 161 * In fact, item_num should be a multiple of translated_size, e.g. : 162 * When we convert each byte of uint8_t type data to rmt format data, 163 * the relation between item_num and translated_size should be `item_num = translated_size*8`. 164 */ 165 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); 166 167 /** 168 * @brief Set RMT clock divider, channel clock is divided from source clock. 169 * 170 * @param channel RMT channel 171 * @param div_cnt RMT counter clock divider 172 * 173 * @return 174 * - ESP_ERR_INVALID_ARG Parameter error 175 * - ESP_OK Success 176 */ 177 esp_err_t rmt_set_clk_div(rmt_channel_t channel, uint8_t div_cnt); 178 179 /** 180 * @brief Get RMT clock divider, channel clock is divided from source clock. 181 * 182 * @param channel RMT channel 183 * @param div_cnt pointer to accept RMT counter divider 184 * 185 * @return 186 * - ESP_ERR_INVALID_ARG Parameter error 187 * - ESP_OK Success 188 */ 189 esp_err_t rmt_get_clk_div(rmt_channel_t channel, uint8_t *div_cnt); 190 191 /** 192 * @brief Set RMT RX idle threshold value 193 * 194 * In receive mode, when no edge is detected on the input signal 195 * for longer than idle_thres channel clock cycles, 196 * the receive process is finished. 197 * 198 * @param channel RMT channel 199 * @param thresh RMT RX idle threshold 200 * 201 * @return 202 * - ESP_ERR_INVALID_ARG Parameter error 203 * - ESP_OK Success 204 */ 205 esp_err_t rmt_set_rx_idle_thresh(rmt_channel_t channel, uint16_t thresh); 206 207 /** 208 * @brief Get RMT idle threshold value. 209 * 210 * In receive mode, when no edge is detected on the input signal 211 * for longer than idle_thres channel clock cycles, 212 * the receive process is finished. 213 * 214 * @param channel RMT channel 215 * @param thresh pointer to accept RMT RX idle threshold value 216 * 217 * @return 218 * - ESP_ERR_INVALID_ARG Parameter error 219 * - ESP_OK Success 220 */ 221 esp_err_t rmt_get_rx_idle_thresh(rmt_channel_t channel, uint16_t *thresh); 222 223 /** 224 * @brief Set RMT memory block number for RMT channel 225 * 226 * This function is used to configure the amount of memory blocks allocated to channel n 227 * The 8 channels share a 512x32-bit RAM block which can be read and written 228 * by the processor cores over the APB bus, as well as read by the transmitters 229 * and written by the receivers. 230 * 231 * The RAM address range for channel n is start_addr_CHn to end_addr_CHn, which are defined by: 232 * Memory block start address is RMT_CHANNEL_MEM(n) (in soc/rmt_reg.h), 233 * that is, start_addr_chn = RMT base address + 0x800 + 64 ∗ 4 ∗ n, and 234 * end_addr_chn = RMT base address + 0x800 + 64 ∗ 4 ∗ n + 64 ∗ 4 ∗ RMT_MEM_SIZE_CHn mod 512 ∗ 4 235 * 236 * @note 237 * If memory block number of one channel is set to a value greater than 1, this channel will occupy the memory 238 * block of the next channel. 239 * Channel 0 can use at most 8 blocks of memory, accordingly channel 7 can only use one memory block. 240 * 241 * @param channel RMT channel 242 * @param rmt_mem_num RMT RX memory block number, one block has 64 * 32 bits. 243 * 244 * @return 245 * - ESP_ERR_INVALID_ARG Parameter error 246 * - ESP_OK Success 247 */ 248 esp_err_t rmt_set_mem_block_num(rmt_channel_t channel, uint8_t rmt_mem_num); 249 250 /** 251 * @brief Get RMT memory block number 252 * 253 * @param channel RMT channel 254 * @param rmt_mem_num Pointer to accept RMT RX memory block number 255 * 256 * @return 257 * - ESP_ERR_INVALID_ARG Parameter error 258 * - ESP_OK Success 259 */ 260 esp_err_t rmt_get_mem_block_num(rmt_channel_t channel, uint8_t *rmt_mem_num); 261 262 /** 263 * @brief Configure RMT carrier for TX signal. 264 * 265 * Set different values for carrier_high and carrier_low to set different frequency of carrier. 266 * The unit of carrier_high/low is the source clock tick, not the divided channel counter clock. 267 * 268 * @param channel RMT channel 269 * @param carrier_en Whether to enable output carrier. 270 * @param high_level High level duration of carrier 271 * @param low_level Low level duration of carrier. 272 * @param carrier_level Configure the way carrier wave is modulated for channel. 273 * - 1'b1:transmit on low output level 274 * - 1'b0:transmit on high output level 275 * 276 * @return 277 * - ESP_ERR_INVALID_ARG Parameter error 278 * - ESP_OK Success 279 */ 280 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); 281 282 /** 283 * @brief Set RMT memory in low power mode. 284 * 285 * Reduce power consumed by memory. 1:memory is in low power state. 286 * 287 * @param channel RMT channel 288 * @param pd_en RMT memory low power enable. 289 * 290 * @return 291 * - ESP_ERR_INVALID_ARG Parameter error 292 * - ESP_OK Success 293 */ 294 esp_err_t rmt_set_mem_pd(rmt_channel_t channel, bool pd_en); 295 296 /** 297 * @brief Get RMT memory low power mode. 298 * 299 * @param channel RMT channel 300 * @param pd_en Pointer to accept RMT memory low power mode. 301 * 302 * @return 303 * - ESP_ERR_INVALID_ARG Parameter error 304 * - ESP_OK Success 305 */ 306 esp_err_t rmt_get_mem_pd(rmt_channel_t channel, bool *pd_en); 307 308 /** 309 * @brief Set RMT start sending data from memory. 310 * 311 * @param channel RMT channel 312 * @param tx_idx_rst Set true to reset memory index for TX. 313 * Otherwise, transmitter will continue sending from the last index in memory. 314 * 315 * @return 316 * - ESP_ERR_INVALID_ARG Parameter error 317 * - ESP_OK Success 318 */ 319 esp_err_t rmt_tx_start(rmt_channel_t channel, bool tx_idx_rst); 320 321 /** 322 * @brief Set RMT stop sending. 323 * 324 * @param channel RMT channel 325 * 326 * @return 327 * - ESP_ERR_INVALID_ARG Parameter error 328 * - ESP_OK Success 329 */ 330 esp_err_t rmt_tx_stop(rmt_channel_t channel); 331 332 /** 333 * @brief Set RMT start receiving data. 334 * 335 * @param channel RMT channel 336 * @param rx_idx_rst Set true to reset memory index for receiver. 337 * Otherwise, receiver will continue receiving data to the last index in memory. 338 * 339 * @return 340 * - ESP_ERR_INVALID_ARG Parameter error 341 * - ESP_OK Success 342 */ 343 esp_err_t rmt_rx_start(rmt_channel_t channel, bool rx_idx_rst); 344 345 /** 346 * @brief Set RMT stop receiving data. 347 * 348 * @param channel RMT channel 349 * 350 * @return 351 * - ESP_ERR_INVALID_ARG Parameter error 352 * - ESP_OK Success 353 */ 354 esp_err_t rmt_rx_stop(rmt_channel_t channel); 355 356 /** 357 * @brief Reset RMT TX memory 358 * 359 * @param channel RMT channel 360 * 361 * @return 362 * - ESP_ERR_INVALID_ARG Parameter error 363 * - ESP_OK Success 364 */ 365 esp_err_t rmt_tx_memory_reset(rmt_channel_t channel); 366 367 /** 368 * @brief Reset RMT RX memory 369 * 370 * @param channel RMT channel 371 * 372 * @return 373 * - ESP_ERR_INVALID_ARG Parameter error 374 * - ESP_OK Success 375 */ 376 esp_err_t rmt_rx_memory_reset(rmt_channel_t channel); 377 378 /** 379 * @brief Set RMT memory owner. 380 * @note Setting memroy is only valid for RX channel. 381 * 382 * @param channel RMT channel 383 * @param owner To set when the transmitter or receiver can process the memory of channel. 384 * 385 * @return 386 * - ESP_ERR_INVALID_ARG Parameter error 387 * - ESP_OK Success 388 */ 389 esp_err_t rmt_set_memory_owner(rmt_channel_t channel, rmt_mem_owner_t owner); 390 391 /** 392 * @brief Get RMT memory owner. 393 * 394 * @param channel RMT channel 395 * @param owner Pointer to get memory owner. 396 * 397 * @return 398 * - ESP_ERR_INVALID_ARG Parameter error 399 * - ESP_OK Success 400 */ 401 esp_err_t rmt_get_memory_owner(rmt_channel_t channel, rmt_mem_owner_t *owner); 402 403 /** 404 * @brief Set RMT tx loop mode. 405 * 406 * @param channel RMT channel 407 * @param loop_en Enable RMT transmitter loop sending mode. 408 * If set true, transmitter will continue sending from the first data 409 * to the last data in channel over and over again in a loop. 410 * 411 * @return 412 * - ESP_ERR_INVALID_ARG Parameter error 413 * - ESP_OK Success 414 */ 415 esp_err_t rmt_set_tx_loop_mode(rmt_channel_t channel, bool loop_en); 416 417 /** 418 * @brief Get RMT tx loop mode. 419 * 420 * @param channel RMT channel 421 * @param loop_en Pointer to accept RMT transmitter loop sending mode. 422 * 423 * @return 424 * - ESP_ERR_INVALID_ARG Parameter error 425 * - ESP_OK Success 426 */ 427 esp_err_t rmt_get_tx_loop_mode(rmt_channel_t channel, bool *loop_en); 428 429 /** 430 * @brief Set RMT RX filter. 431 * 432 * In receive mode, channel will ignore input pulse when the pulse width is smaller than threshold. 433 * Counted in source clock, not divided counter clock. 434 * 435 * @param channel RMT channel 436 * @param rx_filter_en To enable RMT receiver filter. 437 * @param thresh Threshold of pulse width for receiver. 438 * 439 * @return 440 * - ESP_ERR_INVALID_ARG Parameter error 441 * - ESP_OK Success 442 */ 443 esp_err_t rmt_set_rx_filter(rmt_channel_t channel, bool rx_filter_en, uint8_t thresh); 444 445 /** 446 * @brief Set RMT source clock 447 * 448 * RMT module has two clock sources: 449 * 1. APB clock which is 80Mhz 450 * 2. REF tick clock, which would be 1Mhz (not supported in this version). 451 * 452 * @param channel RMT channel 453 * @param base_clk To choose source clock for RMT module. 454 * 455 * @return 456 * - ESP_ERR_INVALID_ARG Parameter error 457 * - ESP_OK Success 458 */ 459 esp_err_t rmt_set_source_clk(rmt_channel_t channel, rmt_source_clk_t base_clk); 460 461 /** 462 * @brief Get RMT source clock 463 * 464 * RMT module has two clock sources: 465 * 1. APB clock which is 80Mhz 466 * 2. REF tick clock, which would be 1Mhz (not supported in this version). 467 * 468 * @param channel RMT channel 469 * @param src_clk Pointer to accept source clock for RMT module. 470 * 471 * @return 472 * - ESP_ERR_INVALID_ARG Parameter error 473 * - ESP_OK Success 474 */ 475 esp_err_t rmt_get_source_clk(rmt_channel_t channel, rmt_source_clk_t *src_clk); 476 477 /** 478 * @brief Set RMT idle output level for transmitter 479 * 480 * @param channel RMT channel 481 * @param idle_out_en To enable idle level output. 482 * @param level To set the output signal's level for channel in idle state. 483 * 484 * @return 485 * - ESP_ERR_INVALID_ARG Parameter error 486 * - ESP_OK Success 487 */ 488 esp_err_t rmt_set_idle_level(rmt_channel_t channel, bool idle_out_en, rmt_idle_level_t level); 489 490 /** 491 * @brief Get RMT idle output level for transmitter 492 * 493 * @param channel RMT channel 494 * @param idle_out_en Pointer to accept value of enable idle. 495 * @param level Pointer to accept value of output signal's level in idle state for specified channel. 496 * 497 * @return 498 * - ESP_ERR_INVALID_ARG Parameter error 499 * - ESP_OK Success 500 */ 501 esp_err_t rmt_get_idle_level(rmt_channel_t channel, bool *idle_out_en, rmt_idle_level_t *level); 502 503 /** 504 * @brief Get RMT status 505 * 506 * @param channel RMT channel 507 * @param status Pointer to accept channel status. 508 * Please refer to RMT_CHnSTATUS_REG(n=0~7) in `rmt_reg.h` for more details of each field. 509 * 510 * @return 511 * - ESP_ERR_INVALID_ARG Parameter error 512 * - ESP_OK Success 513 */ 514 esp_err_t rmt_get_status(rmt_channel_t channel, uint32_t *status); 515 516 /** 517 * @brief Set RMT RX interrupt enable 518 * 519 * @param channel RMT channel 520 * @param en enable or disable RX interrupt. 521 * 522 * @return 523 * - ESP_ERR_INVALID_ARG Parameter error 524 * - ESP_OK Success 525 */ 526 esp_err_t rmt_set_rx_intr_en(rmt_channel_t channel, bool en); 527 528 /** 529 * @brief Set RMT RX error interrupt enable 530 * 531 * @param channel RMT channel 532 * @param en enable or disable RX err interrupt. 533 * 534 * @return 535 * - ESP_ERR_INVALID_ARG Parameter error 536 * - ESP_OK Success 537 */ 538 esp_err_t rmt_set_err_intr_en(rmt_channel_t channel, bool en); 539 540 /** 541 * @brief Set RMT TX interrupt enable 542 * 543 * @param channel RMT channel 544 * @param en enable or disable TX interrupt. 545 * 546 * @return 547 * - ESP_ERR_INVALID_ARG Parameter error 548 * - ESP_OK Success 549 */ 550 esp_err_t rmt_set_tx_intr_en(rmt_channel_t channel, bool en); 551 552 /** 553 * @brief Set RMT TX threshold event interrupt enable 554 * 555 * An interrupt will be triggered when the number of transmitted items reaches the threshold value 556 * 557 * @param channel RMT channel 558 * @param en enable or disable TX event interrupt. 559 * @param evt_thresh RMT event interrupt threshold value 560 * 561 * @return 562 * - ESP_ERR_INVALID_ARG Parameter error 563 * - ESP_OK Success 564 */ 565 esp_err_t rmt_set_tx_thr_intr_en(rmt_channel_t channel, bool en, uint16_t evt_thresh); 566 567 /** 568 * @brief Configure the GPIO used by RMT channel 569 * 570 * @param channel RMT channel 571 * @param mode RMT mode, either RMT_MODE_TX or RMT_MODE_RX 572 * @param gpio_num GPIO number, which is connected with certain RMT signal 573 * @param invert_signal Invert RMT signal physically by GPIO matrix 574 * 575 * @return 576 * - ESP_ERR_INVALID_ARG Configure RMT GPIO failed because of wrong parameter 577 * - ESP_OK Configure RMT GPIO successfully 578 */ 579 esp_err_t rmt_set_gpio(rmt_channel_t channel, rmt_mode_t mode, gpio_num_t gpio_num, bool invert_signal); 580 581 /** 582 * @brief Configure RMT parameters 583 * 584 * @param rmt_param RMT parameter struct 585 * 586 * @return 587 * - ESP_ERR_INVALID_ARG Parameter error 588 * - ESP_OK Success 589 */ 590 esp_err_t rmt_config(const rmt_config_t *rmt_param); 591 592 /** 593 * @brief Register RMT interrupt handler, the handler is an ISR. 594 * 595 * The handler will be attached to the same CPU core that this function is running on. 596 * 597 * @note If you already called rmt_driver_install to use system RMT driver, 598 * please do not register ISR handler again. 599 * 600 * @param fn Interrupt handler function. 601 * @param arg Parameter for the handler function 602 * @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred) 603 * ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. 604 * @param handle If non-zero, a handle to later clean up the ISR gets stored here. 605 * 606 * @return 607 * - ESP_OK Success 608 * - ESP_ERR_INVALID_ARG Function pointer error. 609 * - ESP_FAIL System driver installed, can not register ISR handler for RMT 610 */ 611 esp_err_t rmt_isr_register(void (*fn)(void *), void *arg, int intr_alloc_flags, rmt_isr_handle_t *handle); 612 613 /** 614 * @brief Deregister previously registered RMT interrupt handler 615 * 616 * @param handle Handle obtained from rmt_isr_register 617 * 618 * @return 619 * - ESP_OK Success 620 * - ESP_ERR_INVALID_ARG Handle invalid 621 */ 622 esp_err_t rmt_isr_deregister(rmt_isr_handle_t handle); 623 624 /** 625 * @brief Fill memory data of channel with given RMT items. 626 * 627 * @param channel RMT channel 628 * @param item Pointer of items. 629 * @param item_num RMT sending items number. 630 * @param mem_offset Index offset of memory. 631 * 632 * @return 633 * - ESP_ERR_INVALID_ARG Parameter error 634 * - ESP_OK Success 635 */ 636 esp_err_t rmt_fill_tx_items(rmt_channel_t channel, const rmt_item32_t *item, uint16_t item_num, uint16_t mem_offset); 637 638 /** 639 * @brief Initialize RMT driver 640 * 641 * @param channel RMT channel 642 * @param rx_buf_size Size of RMT RX ringbuffer. Can be 0 if the RX ringbuffer is not used. 643 * @param intr_alloc_flags Flags for the RMT driver interrupt handler. Pass 0 for default flags. See esp_intr_alloc.h for details. 644 * If ESP_INTR_FLAG_IRAM is used, please do not use the memory allocated from psram when calling rmt_write_items. 645 * 646 * @return 647 * - ESP_ERR_INVALID_STATE Driver is already installed, call rmt_driver_uninstall first. 648 * - ESP_ERR_NO_MEM Memory allocation failure 649 * - ESP_ERR_INVALID_ARG Parameter error 650 * - ESP_OK Success 651 */ 652 esp_err_t rmt_driver_install(rmt_channel_t channel, size_t rx_buf_size, int intr_alloc_flags); 653 654 /** 655 * @brief Uninstall RMT driver. 656 * 657 * @param channel RMT channel 658 * 659 * @return 660 * - ESP_ERR_INVALID_ARG Parameter error 661 * - ESP_OK Success 662 */ 663 esp_err_t rmt_driver_uninstall(rmt_channel_t channel); 664 665 /** 666 * @brief Get the current status of eight channels. 667 * 668 * @note Do not call this function if it is possible that `rmt_driver_uninstall` will be called at the same time. 669 * 670 * @param[out] channel_status store the current status of each channel 671 * 672 * @return 673 * - ESP_ERR_INVALID_ARG Parameter is NULL 674 * - ESP_OK Success 675 */ 676 esp_err_t rmt_get_channel_status(rmt_channel_status_result_t *channel_status); 677 678 /** 679 * @brief Get speed of channel's internal counter clock. 680 * 681 * @param channel RMT channel 682 * @param[out] clock_hz counter clock speed, in hz 683 * 684 * @return 685 * - ESP_ERR_INVALID_ARG Parameter is NULL 686 * - ESP_OK Success 687 */ 688 esp_err_t rmt_get_counter_clock(rmt_channel_t channel, uint32_t *clock_hz); 689 690 /** 691 * @brief RMT send waveform from rmt_item array. 692 * 693 * This API allows user to send waveform with any length. 694 * 695 * @param channel RMT channel 696 * @param rmt_item head point of RMT items array. 697 * If ESP_INTR_FLAG_IRAM is used, please do not use the memory allocated from psram when calling rmt_write_items. 698 * @param item_num RMT data item number. 699 * @param wait_tx_done 700 * - If set 1, it will block the task and wait for sending done. 701 * - If set 0, it will not wait and return immediately. 702 * 703 * @note 704 * This function will not copy data, instead, it will point to the original items, 705 * and send the waveform items. 706 * If wait_tx_done is set to true, this function will block and will not return until 707 * all items have been sent out. 708 * If wait_tx_done is set to false, this function will return immediately, and the driver 709 * interrupt will continue sending the items. We must make sure the item data will not be 710 * damaged when the driver is still sending items in driver interrupt. 711 * 712 * @return 713 * - ESP_ERR_INVALID_ARG Parameter error 714 * - ESP_OK Success 715 */ 716 esp_err_t rmt_write_items(rmt_channel_t channel, const rmt_item32_t *rmt_item, int item_num, bool wait_tx_done); 717 718 /** 719 * @brief Wait RMT TX finished. 720 * 721 * @param channel RMT channel 722 * @param 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). 723 * 724 * @return 725 * - ESP_OK RMT Tx done successfully 726 * - ESP_ERR_TIMEOUT Exceeded the 'wait_time' given 727 * - ESP_ERR_INVALID_ARG Parameter error 728 * - ESP_FAIL Driver not installed 729 */ 730 esp_err_t rmt_wait_tx_done(rmt_channel_t channel, TickType_t wait_time); 731 732 /** 733 * @brief Get ringbuffer from RMT. 734 * 735 * Users can get the RMT RX ringbuffer handle, and process the RX data. 736 * 737 * @param channel RMT channel 738 * @param buf_handle Pointer to buffer handle to accept RX ringbuffer handle. 739 * 740 * @return 741 * - ESP_ERR_INVALID_ARG Parameter error 742 * - ESP_OK Success 743 */ 744 esp_err_t rmt_get_ringbuf_handle(rmt_channel_t channel, RingbufHandle_t *buf_handle); 745 746 /** 747 * @brief Init rmt translator and register user callback. 748 * The callback will convert the raw data that needs to be sent to rmt format. 749 * If a channel is initialized more than once, tha user callback will be replaced by the later. 750 * 751 * @param channel RMT channel . 752 * @param fn Point to the data conversion function. 753 * 754 * @return 755 * - ESP_FAIL Init fail. 756 * - ESP_OK Init success. 757 */ 758 esp_err_t rmt_translator_init(rmt_channel_t channel, sample_to_rmt_t fn); 759 760 /** 761 * @brief Set user context for the translator of specific channel 762 * 763 * @param channel RMT channel number 764 * @param context User context 765 * 766 * @return 767 * - ESP_FAIL Set context fail 768 * - ESP_OK Set context success 769 */ 770 esp_err_t rmt_translator_set_context(rmt_channel_t channel, void *context); 771 772 /** 773 * @brief Get the user context set by 'rmt_translator_set_context' 774 * 775 * @note This API must be invoked in the RMT translator callback function, 776 * and the first argument must be the actual parameter 'item_num' you got in that callback function. 777 * 778 * @param item_num Address of the memory which contains the number of translated items (It's from driver's internal memroy) 779 * @param context Returned User context 780 * 781 * @return 782 * - ESP_FAIL Get context fail 783 * - ESP_OK Get context success 784 */ 785 esp_err_t rmt_translator_get_context(const size_t *item_num, void **context); 786 787 /** 788 * @brief Translate uint8_t type of data into rmt format and send it out. 789 * Requires rmt_translator_init to init the translator first. 790 * 791 * @param channel RMT channel . 792 * @param src Pointer to the raw data. 793 * @param src_size The size of the raw data. 794 * @param wait_tx_done Set true to wait all data send done. 795 * 796 * @return 797 * - ESP_FAIL Send fail 798 * - ESP_OK Send success 799 */ 800 esp_err_t rmt_write_sample(rmt_channel_t channel, const uint8_t *src, size_t src_size, bool wait_tx_done); 801 802 /** 803 * @brief Registers a callback that will be called when transmission ends. 804 * 805 * Called by rmt_driver_isr_default in interrupt context. 806 * 807 * @note Requires rmt_driver_install to install the default ISR handler. 808 * 809 * @param function Function to be called from the default interrupt handler or NULL. 810 * @param arg Argument which will be provided to the callback when it is called. 811 * 812 * @return the previous callback settings (members will be set to NULL if there was none) 813 */ 814 rmt_tx_end_callback_t rmt_register_tx_end_callback(rmt_tx_end_fn_t function, void *arg); 815 816 #if SOC_RMT_SUPPORT_RX_PINGPONG 817 /** 818 * @brief Set RMT RX threshold event interrupt enable 819 * 820 * An interrupt will be triggered when the number of received items reaches the threshold value 821 * 822 * @param channel RMT channel 823 * @param en enable or disable RX event interrupt. 824 * @param evt_thresh RMT event interrupt threshold value 825 * 826 * @return 827 * - ESP_ERR_INVALID_ARG Parameter error 828 * - ESP_OK Success 829 */ 830 esp_err_t rmt_set_rx_thr_intr_en(rmt_channel_t channel, bool en, uint16_t evt_thresh); 831 #endif 832 833 #if SOC_RMT_SUPPORT_TX_SYNCHRO 834 /** 835 * @brief Add channel into a synchronous group (channels in the same group can start transaction simultaneously) 836 * 837 * @param channel RMT channel 838 * 839 * @return 840 * - ESP_ERR_INVALID_ARG Parameter error 841 * - ESP_OK Success 842 */ 843 esp_err_t rmt_add_channel_to_group(rmt_channel_t channel); 844 845 /** 846 * @brief Remove channel out of a group 847 * 848 * @param channel RMT channel 849 * 850 * @return 851 * - ESP_ERR_INVALID_ARG Parameter error 852 * - ESP_OK Success 853 */ 854 esp_err_t rmt_remove_channel_from_group(rmt_channel_t channel); 855 #endif 856 857 #if SOC_RMT_SUPPORT_TX_LOOP_COUNT 858 /** 859 * @brief Set loop count threshold value for RMT TX channel 860 * 861 * When tx loop count reaches this value, an ISR callback will notify user 862 * 863 * @param channel RMT channel 864 * @param count loop count, 1 ~ 1023 865 * @return 866 * - ESP_ERR_INVALID_ARG Parameter error 867 * - ESP_OK Success 868 */ 869 esp_err_t rmt_set_tx_loop_count(rmt_channel_t channel, uint32_t count); 870 871 /** 872 * @brief Enable or disable the feature that when loop count reaches the threshold, RMT will stop transmitting. 873 * 874 * - When the loop auto-stop feature is enabled will halt RMT transmission after the loop count reaches a certain threshold 875 * - When disabled, the RMT transmission continue indefinitely until halted by the users 876 * 877 * @note The auto-stop feature is implemented in hardware on particular targets (i.e. those with SOC_RMT_SUPPORT_TX_LOOP_AUTOSTOP defined). 878 * Otherwise, the auto-stop feature is implemented in software via the interrupt. 879 * 880 * @param channel RMT channel 881 * @param en enable bit 882 * @return 883 * - ESP_ERR_INVALID_ARG Parameter error 884 * - ESP_OK Success 885 */ 886 esp_err_t rmt_enable_tx_loop_autostop(rmt_channel_t channel, bool en); 887 #endif // SOC_RMT_SUPPORT_TX_LOOP_COUNT 888 889 /** 890 * @brief Reset RMT TX/RX memory index. 891 * 892 * @param channel RMT channel 893 * 894 * @return 895 * - ESP_ERR_INVALID_ARG Parameter error 896 * - ESP_OK Success 897 */ 898 esp_err_t rmt_memory_rw_rst(rmt_channel_t channel) 899 __attribute__((deprecated("use rmt_tx_memory_reset or rmt_rx_memory_reset instead"))); 900 901 /** 902 * @brief Set mask value to RMT interrupt enable register. 903 * 904 * @param mask Bit mask to set to the register 905 * 906 */ 907 void rmt_set_intr_enable_mask(uint32_t mask) 908 __attribute__((deprecated("interrupt should be handled by driver"))); 909 910 /** 911 * @brief Clear mask value to RMT interrupt enable register. 912 * 913 * @param mask Bit mask to clear the register 914 * 915 */ 916 void rmt_clr_intr_enable_mask(uint32_t mask) 917 __attribute__((deprecated("interrupt should be handled by driver"))); 918 919 /** 920 * @brief Set RMT pin 921 * 922 * @param channel RMT channel 923 * @param mode TX or RX mode for RMT 924 * @param gpio_num GPIO number to transmit or receive the signal. 925 * 926 * @return 927 * - ESP_ERR_INVALID_ARG Parameter error 928 * - ESP_OK Success 929 */ 930 esp_err_t rmt_set_pin(rmt_channel_t channel, rmt_mode_t mode, gpio_num_t gpio_num) 931 __attribute__((deprecated("use rmt_set_gpio instead"))); 932 933 #ifdef __cplusplus 934 } 935 #endif 936
