UART (Universal Asynchronous Receiver-Transmitter) is an hardware peripheral which allows serial, asynchronous communication with configurable data format and speed. The UART interface usually works at logic level: the electric signals are generated by an external circuit, following the standards of the communication bus you chose.
For example the classical “serial port” of many personal computers is based on the EIA RS-232 standard, which defines how – at the physical layer – signals are generated on the communication medium. There are dedicated chips (the most famous of which is surely the MAX232 by Maxim Integrated) to convert the logic levels of a UART peripheral to the physical signals of the EIA RS232 standard:
The esp32 chip offers 3 UART controllers. These controllers are connected to the GPIO matrix; this allows to assign them most of the digital pins of the chip:
The esp-idf framework includes a driver (uart.c) to simplify the configuration and the use of the controllers; to use it, include its header file in your program:
#include "driver/uart.h" |
For the driver, the 3 controllers are named as follows:
In this first post, I’ll explain the basic use of a controller; events and interrupts will be covered in a future article.
The first thing to do is to configure the controller using the uart_config_t struct:
uart_config_t uart_config = { .baud_rate = 115200, .data_bits = UART_DATA_8_BITS, .parity = UART_PARITY_DISABLE, .stop_bits = UART_STOP_BITS_1, .flow_ctrl = UART_HW_FLOWCTRL_DISABLE }; |
- baud_rate is the transmission speed
- data_bits, and stop_bits are the number of bits for each “word” and the number of stop bits
- parity defines if the controller must send the parity bit or not
- flow_ctrl is the type of flow control (hardware, software or disabled)
There are two additional parameters (rx_flow_ctrl_thresh and use_ref_tick) you can use to set the threshold for the RTS signal if hardware flow control is selected and to enable the REF_TICK signal as clock for the UART controller.
The constant values for data_bits, stop_bits… are declared in the uart.h file.
Often the parameters required to communicate with a serial device are expressed in a “condensed” format, for example if you read 9600,8N1 it means:
[checklist]
- speed 9600 baud
- “word” of 8 bits
- No parity
- 1 stop bit
[/checklist]
Configure the controller with the method:
uart_param_config(uart_port_t uart_num, const uart_config_t *uart_config); |
passing as parameters the number of the controller (uart_num) and the struct with the configuration previously defined (uart_config).
Conclude the configuration setting the pins the controller have to use for the different signals:
uart_set_pin(uart_port_t uart_num, int tx_io_num, int rx_io_num, int rts_io_num, int cts_io_num); |
You can use the UART_PIN_NO_CHANGE constant if that specific signal is not used or if you want to keep the default pin.
For example to map the controller to pins 4 and 5 without using the RTS and CTS signals:
uart_set_pin(UART_NUM_0, 4, 5, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE); |
Now you can install the driver with:
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); |
In addition to the controller number, you have to pass the size for the receive and transmit buffers. The parameters about queue and interrupts will be discussed in a future article.
Let’s now learn how to send data. To better understand the differences between the available commands, you have to understand that there are two buffers: one hardware, included in the UART controller, and one software, implemented in the driver: The first command to send data – to be used only if the software trasmit buffer is disabled – is uart_tx_chars(): This command sends len bytes from buffer. As you’re not using a software buffer, it may happens that the command cannot send all the bytes because the hardware buffer is full; the uart_tx_chars method therefore returns the number of bytes actually sent. To use the software buffer, the uart_write_bytes() is available: This command copies size bytes from the src array to the driver’s buffer: the driver will take care of filling the hardware buffer of the controller until all the data is transmitted. The uart_write_bytes() also retuns the number of bytes actually copied in the tx buffer. When receiving, you can use the uart_read_bytes() command: The command reads a maximum of length bytes from the receive buffer and copies them in the buf array. The command waits for data the number of specified ticks, then returns the number of bytes actually read. You can know the number of bytes at each moment available in the receive buffer with: The framework allows to use a UART controller as a peripheral for standard I/O. Unix streams stdin, stdout and stderr are indeed linked to RX and TX operations on that controller: you can therefore use standard C functions like printf(), scanf()… to write and read from the UART controller. Via menuconfig you can specify which controller to use, the parameters for the controller and you can also disable this feature at all: In the following video I’ll show how to work with UART controllers connecting one of them to a USB->serial converter. Both the converter and the esp32 devboard are connected to my laptop: in this way I can send data from the laptop to UART1 via the converter, read it and send it back to my laptop using the UART0 controller.int uart_tx_chars(uart_port_t uart_num, const char* buffer, uint32_t len);
int uart_write_bytes(uart_port_t uart_num, const char* src, size_t size);
int uart_read_bytes(uart_port_t uart_num, uint8_t* buf, uint32_t length,
TickType_t ticks_to_wait);
uart_get_buffered_data_len(uart_port_t uart_num, size_t* size);
UART and stdio
Demo
Hello Luca,
I think the arrows in the representation of the data flow are not all correct.
There is no arrow that goes into the driver.
see: http://www.lucadentella.it/en/2017/11/06/esp32-26-uart/
Kind regards. Rolf Spilger
Hi Rolf, the program calls two functions (uart_write_bytes and uart_tx_chars) of the driver
Hi luca, thanks for example.
i would like to know if you have ever implementred UART interrupt handler. i am lloking to use UART interrupt directly, however i didnt come across any example or support.
regards
sushant
Hi, not at the moment but it’s a good suggestion for a new post… stay tuned 😉
Ciao Luca e grazie per il tuo tutorial.
Vorrei avere una traccia per capire una cosa. Se io volessi “trasmettere” dei dati ricevuti via seriale da un ESP32 utilizzando il wifi.. per spiegarmi meglio… un software manda delle info per muovere due motori passo passo ad un Arduino via usb. Posso interporre un ESP32 in modo che l’Arduino (dotato di scheda wifi) riceva i dati dall’ESP32 “via radio” e svolga il lavoro che il software gli manda?
Spero di essermi spiegato perché Arduino lo uso da molti anni, ma di wifi e di dati seriali sono completamente a digiuno…
Grazie per ogni dritta.
lanfranco
Ciao! Si, puoi farlo. Immagino che la tua idea sia di utilizzare ESP32 per ricevere via wifi dei dati dal computer e inviarli poi via seriale ad Arduino giusto? In tal caso ti basta anche un semplice ESP8266,