Chapter 2. API Reference
Software Flow Control If the hardware flow control is disabled, you can manually set the RTS and DTR signal
levels by using the functions uart_set_rts() and uart_set_dtr() respectively.
Communication Mode Selection The UART controller supports a number of communication modes. A mode
can be selected using the function uart_set_mode(). Once a specific mode is selected, the UART driver will
handle the behavior of a connected UART device accordingly. As an example, it can control the RS485 driver chip
using the RTS line to allow half-duplex RS485 communication.
// Setup UART in rs485 half duplex mode
ESP_ERROR_CHECK(uart_set_mode(uart_num, UART_MODE_RS485_HALF_DUPLEX));
Using Interrupts There are many interrupts that can be generated following specific UART states or detected
errors. The full list of available interrupts is provided in ESP32-S2 Technical Reference Manual > UART Controller
(UART) > UART Interrupts and UHCI Interrupts [PDF]. You can enable or disable specific interrupts by calling
uart_enable_intr_mask() or uart_disable_intr_mask() respectively. The mask of all interrupts
is available as UART_INTR_MASK.
By default, the uart_driver_install() function installs the driver’s internal interrupt handler to man-
age the Tx and Rx ring buffers and provides high-level API functions like events (see below). It is also possi-
ble to register a lower level interrupt handler instead using uart_isr_register(), and to free it again using
uart_isr_free(). Some UART driver functions which use the Tx and Rx ring buffers, events, etc. will not
automatically work in this case - it is necessary to handle the interrupts directly in the ISR. Inside the custom handler
implementation, clear the interrupt status bits using uart_clear_intr_status().
The API provides a convenient way to handle specific interrupts discussed in this document by wrapping them into
dedicated functions:
• Event detection: There are several events defined in uart_event_type_t that may be reported to a
user application using the FreeRTOS queue functionality. You can enable this functionality when calling
uart_driver_install() described in Driver Installation. An example of using Event detection can be
found in peripherals/uart/uart_events.
• FIFO space threshold or transmission timeout reached: The Tx and Rx FIFO buffers can trigger an inter-
rupt when they are filled with a specific number of characters, or on a timeout of sending or receiving data. To
use these interrupts, do the following:
– Configure respective threshold values of the buffer length and timeout by entering them in the structure
uart_intr_config_t and calling uart_intr_config()
– Enable the interrupts using the functions uart_enable_tx_intr() and
uart_enable_rx_intr()
– Disable these interrupts using the corresponding functions uart_disable_tx_intr() or
uart_disable_rx_intr()
• Pattern detection: An interrupt triggered on detecting a‘pattern’of the same character being received/sent re-
peatedly for a number of times. This functionality is demonstrated in the example peripherals/uart/uart_events.
It can be used, e.g., to detect a command string followed by a specific number of identical characters (the‘pat-
tern’) added at the end of the command string. The following functions are available:
– Configure and enable this interrupt using uart_enable_pattern_det_intr()
– Disable the interrupt using uart_disable_pattern_det_intr()
Macros The API also defines several macros. For example, UART_FIFO_LEN defines the length of hardware
FIFO buffers; UART_BITRATE_MAX gives the maximum baud rate supported by the UART controllers, etc.
Deleting a Driver If the communication established with uart_driver_install() is no longer required,
the driver can be removed to free allocated resources by calling uart_driver_delete().
Espressif Systems 461
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General