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