1 // Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #include "esp_err.h" 22 #include "esp_intr_alloc.h" 23 #include "soc/soc_caps.h" 24 #include "freertos/FreeRTOS.h" 25 #include "freertos/semphr.h" 26 #include "freertos/task.h" 27 #include "freertos/queue.h" 28 #include "freertos/ringbuf.h" 29 #include "hal/uart_types.h" 30 31 // Valid UART port number 32 #define UART_NUM_0 (0) /*!< UART port 0 */ 33 #define UART_NUM_1 (1) /*!< UART port 1 */ 34 #if SOC_UART_NUM > 2 35 #define UART_NUM_2 (2) /*!< UART port 2 */ 36 #endif 37 #define UART_NUM_MAX (SOC_UART_NUM) /*!< UART port max */ 38 39 #define UART_PIN_NO_CHANGE (-1) /*!< Constant for uart_set_pin function which indicates that UART pin should not be changed */ 40 41 #define UART_FIFO_LEN SOC_UART_FIFO_LEN ///< Length of the UART HW FIFO 42 #define UART_BITRATE_MAX SOC_UART_BITRATE_MAX ///< Maximum configurable bitrate 43 44 /** 45 * @brief UART interrupt configuration parameters for uart_intr_config function 46 */ 47 typedef struct { 48 uint32_t intr_enable_mask; /*!< UART interrupt enable mask, choose from UART_XXXX_INT_ENA_M under UART_INT_ENA_REG(i), connect with bit-or operator*/ 49 uint8_t rx_timeout_thresh; /*!< UART timeout interrupt threshold (unit: time of sending one byte)*/ 50 uint8_t txfifo_empty_intr_thresh; /*!< UART TX empty interrupt threshold.*/ 51 uint8_t rxfifo_full_thresh; /*!< UART RX full interrupt threshold.*/ 52 } uart_intr_config_t; 53 54 /** 55 * @brief UART event types used in the ring buffer 56 */ 57 typedef enum { 58 UART_DATA, /*!< UART data event*/ 59 UART_BREAK, /*!< UART break event*/ 60 UART_BUFFER_FULL, /*!< UART RX buffer full event*/ 61 UART_FIFO_OVF, /*!< UART FIFO overflow event*/ 62 UART_FRAME_ERR, /*!< UART RX frame error event*/ 63 UART_PARITY_ERR, /*!< UART RX parity event*/ 64 UART_DATA_BREAK, /*!< UART TX data and break event*/ 65 UART_PATTERN_DET, /*!< UART pattern detected */ 66 UART_EVENT_MAX, /*!< UART event max index*/ 67 } uart_event_type_t; 68 69 /** 70 * @brief Event structure used in UART event queue 71 */ 72 typedef struct { 73 uart_event_type_t type; /*!< UART event type */ 74 size_t size; /*!< UART data size for UART_DATA event*/ 75 bool timeout_flag; /*!< UART data read timeout flag for UART_DATA event (no new data received during configured RX TOUT)*/ 76 /*!< If the event is caused by FIFO-full interrupt, then there will be no event with the timeout flag before the next byte coming.*/ 77 } uart_event_t; 78 79 typedef intr_handle_t uart_isr_handle_t; 80 81 /** 82 * @brief Install UART driver and set the UART to the default configuration. 83 * 84 * UART ISR handler will be attached to the same CPU core that this function is running on. 85 * 86 * @note Rx_buffer_size should be greater than UART_FIFO_LEN. Tx_buffer_size should be either zero or greater than UART_FIFO_LEN. 87 * 88 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 89 * @param rx_buffer_size UART RX ring buffer size. 90 * @param tx_buffer_size UART TX ring buffer size. 91 * If set to zero, driver will not use TX buffer, TX function will block task until all data have been sent out. 92 * @param queue_size UART event queue size/depth. 93 * @param uart_queue UART event queue handle (out param). On success, a new queue handle is written here to provide 94 * access to UART events. If set to NULL, driver will not use an event queue. 95 * @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred) 96 * ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. Do not set ESP_INTR_FLAG_IRAM here 97 * (the driver's ISR handler is not located in IRAM) 98 * 99 * @return 100 * - ESP_OK Success 101 * - ESP_FAIL Parameter error 102 */ 103 esp_err_t uart_driver_install(uart_port_t uart_num, int rx_buffer_size, int tx_buffer_size, int queue_size, QueueHandle_t* uart_queue, int intr_alloc_flags); 104 105 /** 106 * @brief Uninstall UART driver. 107 * 108 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 109 * 110 * @return 111 * - ESP_OK Success 112 * - ESP_FAIL Parameter error 113 */ 114 esp_err_t uart_driver_delete(uart_port_t uart_num); 115 116 /** 117 * @brief Checks whether the driver is installed or not 118 * 119 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 120 * 121 * @return 122 * - true driver is installed 123 * - false driver is not installed 124 */ 125 bool uart_is_driver_installed(uart_port_t uart_num); 126 127 /** 128 * @brief Set UART data bits. 129 * 130 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 131 * @param data_bit UART data bits 132 * 133 * @return 134 * - ESP_OK Success 135 * - ESP_FAIL Parameter error 136 */ 137 esp_err_t uart_set_word_length(uart_port_t uart_num, uart_word_length_t data_bit); 138 139 /** 140 * @brief Get the UART data bit configuration. 141 * 142 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 143 * @param data_bit Pointer to accept value of UART data bits. 144 * 145 * @return 146 * - ESP_FAIL Parameter error 147 * - ESP_OK Success, result will be put in (*data_bit) 148 */ 149 esp_err_t uart_get_word_length(uart_port_t uart_num, uart_word_length_t* data_bit); 150 151 /** 152 * @brief Set UART stop bits. 153 * 154 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 155 * @param stop_bits UART stop bits 156 * 157 * @return 158 * - ESP_OK Success 159 * - ESP_FAIL Fail 160 */ 161 esp_err_t uart_set_stop_bits(uart_port_t uart_num, uart_stop_bits_t stop_bits); 162 163 /** 164 * @brief Get the UART stop bit configuration. 165 * 166 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 167 * @param stop_bits Pointer to accept value of UART stop bits. 168 * 169 * @return 170 * - ESP_FAIL Parameter error 171 * - ESP_OK Success, result will be put in (*stop_bit) 172 */ 173 esp_err_t uart_get_stop_bits(uart_port_t uart_num, uart_stop_bits_t* stop_bits); 174 175 /** 176 * @brief Set UART parity mode. 177 * 178 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 179 * @param parity_mode the enum of uart parity configuration 180 * 181 * @return 182 * - ESP_FAIL Parameter error 183 * - ESP_OK Success 184 */ 185 esp_err_t uart_set_parity(uart_port_t uart_num, uart_parity_t parity_mode); 186 187 /** 188 * @brief Get the UART parity mode configuration. 189 * 190 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 191 * @param parity_mode Pointer to accept value of UART parity mode. 192 * 193 * @return 194 * - ESP_FAIL Parameter error 195 * - ESP_OK Success, result will be put in (*parity_mode) 196 * 197 */ 198 esp_err_t uart_get_parity(uart_port_t uart_num, uart_parity_t* parity_mode); 199 200 /** 201 * @brief Set UART baud rate. 202 * 203 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 204 * @param baudrate UART baud rate. 205 * 206 * @return 207 * - ESP_FAIL Parameter error 208 * - ESP_OK Success 209 */ 210 esp_err_t uart_set_baudrate(uart_port_t uart_num, uint32_t baudrate); 211 212 /** 213 * @brief Get the UART baud rate configuration. 214 * 215 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 216 * @param baudrate Pointer to accept value of UART baud rate 217 * 218 * @return 219 * - ESP_FAIL Parameter error 220 * - ESP_OK Success, result will be put in (*baudrate) 221 * 222 */ 223 esp_err_t uart_get_baudrate(uart_port_t uart_num, uint32_t* baudrate); 224 225 /** 226 * @brief Set UART line inverse mode 227 * 228 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 229 * @param inverse_mask Choose the wires that need to be inverted. Using the ORred mask of `uart_signal_inv_t` 230 * 231 * @return 232 * - ESP_OK Success 233 * - ESP_FAIL Parameter error 234 */ 235 esp_err_t uart_set_line_inverse(uart_port_t uart_num, uint32_t inverse_mask); 236 237 /** 238 * @brief Set hardware flow control. 239 * 240 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 241 * @param flow_ctrl Hardware flow control mode 242 * @param rx_thresh Threshold of Hardware RX flow control (0 ~ UART_FIFO_LEN). 243 * Only when UART_HW_FLOWCTRL_RTS is set, will the rx_thresh value be set. 244 * 245 * @return 246 * - ESP_OK Success 247 * - ESP_FAIL Parameter error 248 */ 249 esp_err_t uart_set_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t flow_ctrl, uint8_t rx_thresh); 250 251 /** 252 * @brief Set software flow control. 253 * 254 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 255 * @param enable switch on or off 256 * @param rx_thresh_xon low water mark 257 * @param rx_thresh_xoff high water mark 258 * 259 * @return 260 * - ESP_OK Success 261 * - ESP_FAIL Parameter error 262 */ 263 esp_err_t uart_set_sw_flow_ctrl(uart_port_t uart_num, bool enable, uint8_t rx_thresh_xon, uint8_t rx_thresh_xoff); 264 265 /** 266 * @brief Get the UART hardware flow control configuration. 267 * 268 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 269 * @param flow_ctrl Option for different flow control mode. 270 * 271 * @return 272 * - ESP_FAIL Parameter error 273 * - ESP_OK Success, result will be put in (*flow_ctrl) 274 */ 275 esp_err_t uart_get_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t* flow_ctrl); 276 277 /** 278 * @brief Clear UART interrupt status 279 * 280 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 281 * @param clr_mask Bit mask of the interrupt status to be cleared. 282 * 283 * @return 284 * - ESP_OK Success 285 * - ESP_FAIL Parameter error 286 */ 287 esp_err_t uart_clear_intr_status(uart_port_t uart_num, uint32_t clr_mask); 288 289 /** 290 * @brief Set UART interrupt enable 291 * 292 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 293 * @param enable_mask Bit mask of the enable bits. 294 * 295 * @return 296 * - ESP_OK Success 297 * - ESP_FAIL Parameter error 298 */ 299 esp_err_t uart_enable_intr_mask(uart_port_t uart_num, uint32_t enable_mask); 300 301 /** 302 * @brief Clear UART interrupt enable bits 303 * 304 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 305 * @param disable_mask Bit mask of the disable bits. 306 * 307 * @return 308 * - ESP_OK Success 309 * - ESP_FAIL Parameter error 310 */ 311 esp_err_t uart_disable_intr_mask(uart_port_t uart_num, uint32_t disable_mask); 312 313 /** 314 * @brief Enable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT) 315 * 316 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 317 * 318 * @return 319 * - ESP_OK Success 320 * - ESP_FAIL Parameter error 321 */ 322 esp_err_t uart_enable_rx_intr(uart_port_t uart_num); 323 324 /** 325 * @brief Disable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT) 326 * 327 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 328 * 329 * @return 330 * - ESP_OK Success 331 * - ESP_FAIL Parameter error 332 */ 333 esp_err_t uart_disable_rx_intr(uart_port_t uart_num); 334 335 /** 336 * @brief Disable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT) 337 * 338 * @param uart_num UART port number 339 * 340 * @return 341 * - ESP_OK Success 342 * - ESP_FAIL Parameter error 343 */ 344 esp_err_t uart_disable_tx_intr(uart_port_t uart_num); 345 346 /** 347 * @brief Enable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT) 348 * 349 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 350 * @param enable 1: enable; 0: disable 351 * @param thresh Threshold of TX interrupt, 0 ~ UART_FIFO_LEN 352 * 353 * @return 354 * - ESP_OK Success 355 * - ESP_FAIL Parameter error 356 */ 357 esp_err_t uart_enable_tx_intr(uart_port_t uart_num, int enable, int thresh); 358 359 /** 360 * @brief Register UART interrupt handler (ISR). 361 * 362 * @note UART ISR handler will be attached to the same CPU core that this function is running on. 363 * 364 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 365 * @param fn Interrupt handler function. 366 * @param arg parameter for handler function 367 * @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred) 368 * ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. 369 * @param handle Pointer to return handle. If non-NULL, a handle for the interrupt will 370 * be returned here. 371 * 372 * @return 373 * - ESP_OK Success 374 * - ESP_FAIL Parameter error 375 */ 376 esp_err_t uart_isr_register(uart_port_t uart_num, void (*fn)(void*), void * arg, int intr_alloc_flags, uart_isr_handle_t *handle); 377 378 /** 379 * @brief Free UART interrupt handler registered by uart_isr_register. Must be called on the same core as 380 * uart_isr_register was called. 381 * 382 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 383 * 384 * @return 385 * - ESP_OK Success 386 * - ESP_FAIL Parameter error 387 */ 388 esp_err_t uart_isr_free(uart_port_t uart_num); 389 390 /** 391 * @brief Set UART pin number 392 * 393 * @note Internal signal can be output to multiple GPIO pads. 394 * Only one GPIO pad can connect with input signal. 395 * 396 * @note Instead of GPIO number a macro 'UART_PIN_NO_CHANGE' may be provided 397 to keep the currently allocated pin. 398 * 399 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 400 * @param tx_io_num UART TX pin GPIO number. 401 * @param rx_io_num UART RX pin GPIO number. 402 * @param rts_io_num UART RTS pin GPIO number. 403 * @param cts_io_num UART CTS pin GPIO number. 404 * 405 * @return 406 * - ESP_OK Success 407 * - ESP_FAIL Parameter error 408 */ 409 esp_err_t uart_set_pin(uart_port_t uart_num, int tx_io_num, int rx_io_num, int rts_io_num, int cts_io_num); 410 411 /** 412 * @brief Manually set the UART RTS pin level. 413 * @note UART must be configured with hardware flow control disabled. 414 * 415 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 416 * @param level 1: RTS output low (active); 0: RTS output high (block) 417 * 418 * @return 419 * - ESP_OK Success 420 * - ESP_FAIL Parameter error 421 */ 422 esp_err_t uart_set_rts(uart_port_t uart_num, int level); 423 424 /** 425 * @brief Manually set the UART DTR pin level. 426 * 427 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 428 * @param level 1: DTR output low; 0: DTR output high 429 * 430 * @return 431 * - ESP_OK Success 432 * - ESP_FAIL Parameter error 433 */ 434 esp_err_t uart_set_dtr(uart_port_t uart_num, int level); 435 436 /** 437 * @brief Set UART idle interval after tx FIFO is empty 438 * 439 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 440 * @param idle_num idle interval after tx FIFO is empty(unit: the time it takes to send one bit 441 * under current baudrate) 442 * 443 * @return 444 * - ESP_OK Success 445 * - ESP_FAIL Parameter error 446 */ 447 esp_err_t uart_set_tx_idle_num(uart_port_t uart_num, uint16_t idle_num); 448 449 /** 450 * @brief Set UART configuration parameters. 451 * 452 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 453 * @param uart_config UART parameter settings 454 * 455 * @return 456 * - ESP_OK Success 457 * - ESP_FAIL Parameter error 458 */ 459 esp_err_t uart_param_config(uart_port_t uart_num, const uart_config_t *uart_config); 460 461 /** 462 * @brief Configure UART interrupts. 463 * 464 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 465 * @param intr_conf UART interrupt settings 466 * 467 * @return 468 * - ESP_OK Success 469 * - ESP_FAIL Parameter error 470 */ 471 esp_err_t uart_intr_config(uart_port_t uart_num, const uart_intr_config_t *intr_conf); 472 473 /** 474 * @brief Wait until UART TX FIFO is empty. 475 * 476 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 477 * @param ticks_to_wait Timeout, count in RTOS ticks 478 * 479 * @return 480 * - ESP_OK Success 481 * - ESP_FAIL Parameter error 482 * - ESP_ERR_TIMEOUT Timeout 483 */ 484 esp_err_t uart_wait_tx_done(uart_port_t uart_num, TickType_t ticks_to_wait); 485 486 /** 487 * @brief Send data to the UART port from a given buffer and length. 488 * 489 * This function will not wait for enough space in TX FIFO. It will just fill the available TX FIFO and return when the FIFO is full. 490 * @note This function should only be used when UART TX buffer is not enabled. 491 * 492 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 493 * @param buffer data buffer address 494 * @param len data length to send 495 * 496 * @return 497 * - (-1) Parameter error 498 * - OTHERS (>=0) The number of bytes pushed to the TX FIFO 499 */ 500 int uart_tx_chars(uart_port_t uart_num, const char* buffer, uint32_t len); 501 502 /** 503 * @brief Send data to the UART port from a given buffer and length, 504 * 505 * If the UART driver's parameter 'tx_buffer_size' is set to zero: 506 * This function will not return until all the data have been sent out, or at least pushed into TX FIFO. 507 * 508 * Otherwise, if the 'tx_buffer_size' > 0, this function will return after copying all the data to tx ring buffer, 509 * UART ISR will then move data from the ring buffer to TX FIFO gradually. 510 * 511 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 512 * @param src data buffer address 513 * @param size data length to send 514 * 515 * @return 516 * - (-1) Parameter error 517 * - OTHERS (>=0) The number of bytes pushed to the TX FIFO 518 */ 519 int uart_write_bytes(uart_port_t uart_num, const void* src, size_t size); 520 521 /** 522 * @brief Send data to the UART port from a given buffer and length, 523 * 524 * If the UART driver's parameter 'tx_buffer_size' is set to zero: 525 * This function will not return until all the data and the break signal have been sent out. 526 * After all data is sent out, send a break signal. 527 * 528 * Otherwise, if the 'tx_buffer_size' > 0, this function will return after copying all the data to tx ring buffer, 529 * UART ISR will then move data from the ring buffer to TX FIFO gradually. 530 * After all data sent out, send a break signal. 531 * 532 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 533 * @param src data buffer address 534 * @param size data length to send 535 * @param brk_len break signal duration(unit: the time it takes to send one bit at current baudrate) 536 * 537 * @return 538 * - (-1) Parameter error 539 * - OTHERS (>=0) The number of bytes pushed to the TX FIFO 540 */ 541 int uart_write_bytes_with_break(uart_port_t uart_num, const void* src, size_t size, int brk_len); 542 543 /** 544 * @brief UART read bytes from UART buffer 545 * 546 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 547 * @param buf pointer to the buffer. 548 * @param length data length 549 * @param ticks_to_wait sTimeout, count in RTOS ticks 550 * 551 * @return 552 * - (-1) Error 553 * - OTHERS (>=0) The number of bytes read from UART FIFO 554 */ 555 int uart_read_bytes(uart_port_t uart_num, void* buf, uint32_t length, TickType_t ticks_to_wait); 556 557 /** 558 * @brief Alias of uart_flush_input. 559 * UART ring buffer flush. This will discard all data in the UART RX buffer. 560 * @note Instead of waiting the data sent out, this function will clear UART rx buffer. 561 * In order to send all the data in tx FIFO, we can use uart_wait_tx_done function. 562 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 563 * 564 * @return 565 * - ESP_OK Success 566 * - ESP_FAIL Parameter error 567 */ 568 esp_err_t uart_flush(uart_port_t uart_num); 569 570 /** 571 * @brief Clear input buffer, discard all the data is in the ring-buffer. 572 * @note In order to send all the data in tx FIFO, we can use uart_wait_tx_done function. 573 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 574 * 575 * @return 576 * - ESP_OK Success 577 * - ESP_FAIL Parameter error 578 */ 579 esp_err_t uart_flush_input(uart_port_t uart_num); 580 581 /** 582 * @brief UART get RX ring buffer cached data length 583 * 584 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 585 * @param size Pointer of size_t to accept cached data length 586 * 587 * @return 588 * - ESP_OK Success 589 * - ESP_FAIL Parameter error 590 */ 591 esp_err_t uart_get_buffered_data_len(uart_port_t uart_num, size_t* size); 592 593 /** 594 * @brief UART disable pattern detect function. 595 * Designed for applications like 'AT commands'. 596 * When the hardware detects a series of one same character, the interrupt will be triggered. 597 * 598 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 599 * 600 * @return 601 * - ESP_OK Success 602 * - ESP_FAIL Parameter error 603 */ 604 esp_err_t uart_disable_pattern_det_intr(uart_port_t uart_num); 605 606 #if CONFIG_IDF_TARGET_ESP32 607 /** 608 * @brief UART enable pattern detect function. 609 * Designed for applications like 'AT commands'. 610 * When the hardware detect a series of one same character, the interrupt will be triggered. 611 * @note This function only works for esp32. And this function is deprecated, please use 612 * uart_enable_pattern_det_baud_intr instead. 613 * 614 * @param uart_num UART port number. 615 * @param pattern_chr character of the pattern. 616 * @param chr_num number of the character, 8bit value. 617 * @param chr_tout timeout of the interval between each pattern characters, 24bit value, unit is APB (80Mhz) clock cycle. 618 * When the duration is less than this value, it will not take this data as at_cmd char. 619 * @param post_idle idle time after the last pattern character, 24bit value, unit is APB (80Mhz) clock cycle. 620 * When the duration is less than this value, it will not take the previous data as the last at_cmd char 621 * @param pre_idle idle time before the first pattern character, 24bit value, unit is APB (80Mhz) clock cycle. 622 * When the duration is less than this value, it will not take this data as the first at_cmd char. 623 * 624 * @return 625 * - ESP_OK Success 626 * - ESP_FAIL Parameter error 627 */ 628 esp_err_t uart_enable_pattern_det_intr(uart_port_t uart_num, char pattern_chr, uint8_t chr_num, int chr_tout, int post_idle, int pre_idle) __attribute__((deprecated)); 629 #endif 630 631 /** 632 * @brief UART enable pattern detect function. 633 * Designed for applications like 'AT commands'. 634 * When the hardware detect a series of one same character, the interrupt will be triggered. 635 * 636 * @param uart_num UART port number. 637 * @param pattern_chr character of the pattern. 638 * @param chr_num number of the character, 8bit value. 639 * @param chr_tout timeout of the interval between each pattern characters, 16bit value, unit is the baud-rate cycle you configured. 640 * When the duration is more than this value, it will not take this data as at_cmd char. 641 * @param post_idle idle time after the last pattern character, 16bit value, unit is the baud-rate cycle you configured. 642 * When the duration is less than this value, it will not take the previous data as the last at_cmd char 643 * @param pre_idle idle time before the first pattern character, 16bit value, unit is the baud-rate cycle you configured. 644 * When the duration is less than this value, it will not take this data as the first at_cmd char. 645 * 646 * @return 647 * - ESP_OK Success 648 * - ESP_FAIL Parameter error 649 */ 650 esp_err_t uart_enable_pattern_det_baud_intr(uart_port_t uart_num, char pattern_chr, uint8_t chr_num, int chr_tout, int post_idle, int pre_idle); 651 652 /** 653 * @brief Return the nearest detected pattern position in buffer. 654 * The positions of the detected pattern are saved in a queue, 655 * this function will dequeue the first pattern position and move the pointer to next pattern position. 656 * @note If the RX buffer is full and flow control is not enabled, 657 * the detected pattern may not be found in the rx buffer due to overflow. 658 * 659 * The following APIs will modify the pattern position info: 660 * uart_flush_input, uart_read_bytes, uart_driver_delete, uart_pop_pattern_pos 661 * It is the application's responsibility to ensure atomic access to the pattern queue and the rx data buffer 662 * when using pattern detect feature. 663 * 664 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 665 * @return 666 * - (-1) No pattern found for current index or parameter error 667 * - others the pattern position in rx buffer. 668 */ 669 int uart_pattern_pop_pos(uart_port_t uart_num); 670 671 /** 672 * @brief Return the nearest detected pattern position in buffer. 673 * The positions of the detected pattern are saved in a queue, 674 * This function do nothing to the queue. 675 * @note If the RX buffer is full and flow control is not enabled, 676 * the detected pattern may not be found in the rx buffer due to overflow. 677 * 678 * The following APIs will modify the pattern position info: 679 * uart_flush_input, uart_read_bytes, uart_driver_delete, uart_pop_pattern_pos 680 * It is the application's responsibility to ensure atomic access to the pattern queue and the rx data buffer 681 * when using pattern detect feature. 682 * 683 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 684 * @return 685 * - (-1) No pattern found for current index or parameter error 686 * - others the pattern position in rx buffer. 687 */ 688 int uart_pattern_get_pos(uart_port_t uart_num); 689 690 /** 691 * @brief Allocate a new memory with the given length to save record the detected pattern position in rx buffer. 692 * 693 * @param uart_num UART port number, the max port number is (UART_NUM_MAX -1). 694 * @param queue_length Max queue length for the detected pattern. 695 * If the queue length is not large enough, some pattern positions might be lost. 696 * Set this value to the maximum number of patterns that could be saved in data buffer at the same time. 697 * @return 698 * - ESP_ERR_NO_MEM No enough memory 699 * - ESP_ERR_INVALID_STATE Driver not installed 700 * - ESP_FAIL Parameter error 701 * - ESP_OK Success 702 */ 703 esp_err_t uart_pattern_queue_reset(uart_port_t uart_num, int queue_length); 704 705 /** 706 * @brief UART set communication mode 707 * 708 * @note This function must be executed after uart_driver_install(), when the driver object is initialized. 709 * @param uart_num Uart number to configure, the max port number is (UART_NUM_MAX -1). 710 * @param mode UART UART mode to set 711 * 712 * @return 713 * - ESP_OK Success 714 * - ESP_ERR_INVALID_ARG Parameter error 715 */ 716 esp_err_t uart_set_mode(uart_port_t uart_num, uart_mode_t mode); 717 718 /** 719 * @brief Set uart threshold value for RX fifo full 720 * @note If application is using higher baudrate and it is observed that bytes 721 * in hardware RX fifo are overwritten then this threshold can be reduced 722 * 723 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 724 * @param threshold Threshold value above which RX fifo full interrupt is generated 725 * 726 * @return 727 * - ESP_OK Success 728 * - ESP_ERR_INVALID_ARG Parameter error 729 * - ESP_ERR_INVALID_STATE Driver is not installed 730 */ 731 esp_err_t uart_set_rx_full_threshold(uart_port_t uart_num, int threshold); 732 733 /** 734 * @brief Set uart threshold values for TX fifo empty 735 * 736 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 737 * @param threshold Threshold value below which TX fifo empty interrupt is generated 738 * 739 * @return 740 * - ESP_OK Success 741 * - ESP_ERR_INVALID_ARG Parameter error 742 * - ESP_ERR_INVALID_STATE Driver is not installed 743 */ 744 esp_err_t uart_set_tx_empty_threshold(uart_port_t uart_num, int threshold); 745 746 /** 747 * @brief UART set threshold timeout for TOUT feature 748 * 749 * @param uart_num Uart number to configure, the max port number is (UART_NUM_MAX -1). 750 * @param tout_thresh This parameter defines timeout threshold in uart symbol periods. The maximum value of threshold is 126. 751 * tout_thresh = 1, defines TOUT interrupt timeout equal to transmission time of one symbol (~11 bit) on current baudrate. 752 * If the time is expired the UART_RXFIFO_TOUT_INT interrupt is triggered. If tout_thresh == 0, 753 * the TOUT feature is disabled. 754 * 755 * @return 756 * - ESP_OK Success 757 * - ESP_ERR_INVALID_ARG Parameter error 758 * - ESP_ERR_INVALID_STATE Driver is not installed 759 */ 760 esp_err_t uart_set_rx_timeout(uart_port_t uart_num, const uint8_t tout_thresh); 761 762 /** 763 * @brief Returns collision detection flag for RS485 mode 764 * Function returns the collision detection flag into variable pointed by collision_flag. 765 * *collision_flag = true, if collision detected else it is equal to false. 766 * This function should be executed when actual transmission is completed (after uart_write_bytes()). 767 * 768 * @param uart_num Uart number to configure the max port number is (UART_NUM_MAX -1). 769 * @param collision_flag Pointer to variable of type bool to return collision flag. 770 * 771 * @return 772 * - ESP_OK Success 773 * - ESP_ERR_INVALID_ARG Parameter error 774 */ 775 esp_err_t uart_get_collision_flag(uart_port_t uart_num, bool* collision_flag); 776 777 /** 778 * @brief Set the number of RX pin signal edges for light sleep wakeup 779 * 780 * UART can be used to wake up the system from light sleep. This feature works 781 * by counting the number of positive edges on RX pin and comparing the count to 782 * the threshold. When the count exceeds the threshold, system is woken up from 783 * light sleep. This function allows setting the threshold value. 784 * 785 * Stop bit and parity bits (if enabled) also contribute to the number of edges. 786 * For example, letter 'a' with ASCII code 97 is encoded as 0100001101 on the wire 787 * (with 8n1 configuration), start and stop bits included. This sequence has 3 788 * positive edges (transitions from 0 to 1). Therefore, to wake up the system 789 * when 'a' is sent, set wakeup_threshold=3. 790 * 791 * The character that triggers wakeup is not received by UART (i.e. it can not 792 * be obtained from UART FIFO). Depending on the baud rate, a few characters 793 * after that will also not be received. Note that when the chip enters and exits 794 * light sleep mode, APB frequency will be changing. To make sure that UART has 795 * correct baud rate all the time, select REF_TICK as UART clock source, 796 * by setting use_ref_tick field in uart_config_t to true. 797 * 798 * @note in ESP32, the wakeup signal can only be input via IO_MUX (i.e. 799 * GPIO3 should be configured as function_1 to wake up UART0, 800 * GPIO9 should be configured as function_5 to wake up UART1), UART2 801 * does not support light sleep wakeup feature. 802 * 803 * @param uart_num UART number, the max port number is (UART_NUM_MAX -1). 804 * @param wakeup_threshold number of RX edges for light sleep wakeup, value is 3 .. 0x3ff. 805 * @return 806 * - ESP_OK on success 807 * - ESP_ERR_INVALID_ARG if uart_num is incorrect or wakeup_threshold is 808 * outside of [3, 0x3ff] range. 809 */ 810 esp_err_t uart_set_wakeup_threshold(uart_port_t uart_num, int wakeup_threshold); 811 812 /** 813 * @brief Get the number of RX pin signal edges for light sleep wakeup. 814 * 815 * See description of uart_set_wakeup_threshold for the explanation of UART 816 * wakeup feature. 817 * 818 * @param uart_num UART number, the max port number is (UART_NUM_MAX -1). 819 * @param[out] out_wakeup_threshold output, set to the current value of wakeup 820 * threshold for the given UART. 821 * @return 822 * - ESP_OK on success 823 * - ESP_ERR_INVALID_ARG if out_wakeup_threshold is NULL 824 */ 825 esp_err_t uart_get_wakeup_threshold(uart_port_t uart_num, int* out_wakeup_threshold); 826 827 /** 828 * @brief Wait until UART tx memory empty and the last char send ok (polling mode). 829 * 830 * @param uart_num UART number 831 * 832 * * @return 833 * - ESP_OK on success 834 * - ESP_ERR_INVALID_ARG Parameter error 835 * - ESP_FAIL Driver not installed 836 */ 837 esp_err_t uart_wait_tx_idle_polling(uart_port_t uart_num); 838 839 /** 840 * @brief Configure TX signal loop back to RX module, just for the test usage. 841 * 842 * @param uart_num UART number 843 * @param loop_back_en Set ture to enable the loop back function, else set it false. 844 * 845 * * @return 846 * - ESP_OK on success 847 * - ESP_ERR_INVALID_ARG Parameter error 848 * - ESP_FAIL Driver not installed 849 */ 850 esp_err_t uart_set_loop_back(uart_port_t uart_num, bool loop_back_en); 851 852 /** 853 * @brief Configure behavior of UART RX timeout interrupt. 854 * 855 * When always_rx_timeout is true, timeout interrupt is triggered even if FIFO is full. 856 * This function can cause extra timeout interrupts triggered only to send the timeout event. 857 * Call this function only if you want to ensure timeout interrupt will always happen after a byte stream. 858 * 859 * @param uart_num UART number 860 * @param always_rx_timeout_en Set to false enable the default behavior of timeout interrupt, 861 * set it to true to always trigger timeout interrupt. 862 * 863 */ 864 void uart_set_always_rx_timeout(uart_port_t uart_num, bool always_rx_timeout_en); 865 866 #ifdef __cplusplus 867 } 868 #endif 869
