This project is a lightweight, low-level UART driver for the Espressif ESP32. It was written from scratch in pure C, and works directly with hardware to manipulate registers neccessary for UART communication. The register code bypasses the abstractions in the ESP-IDF driver.
Technical reference manual - [ESP32 Technical Reference Manual Version 5.5] (https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#uart)
Board used for testing - ESP32 Devkit V1 Chip - ESP32-WROOM-32
- Direct Register Access: Interacts directly with UART and GPIO matrix registers bypassing the IO Mux
- Support for all UART Ports: Compatible with
UART0,UART1, andUART2. Note:UART1is not exposed on the board used for testing, and by default,UART0is connected to USB output and used by logging functions. - Dynamic Pin Configuration: Using the GPIO matrix, any RX/TX pin can be assigned to any UART controller.
- Basic I/O Functions: Provides basic functions for reading and writing bytes as well as strings.
- Non-Blocking Read: Includes a non-blocking
uart_read_bytefunction to enable greater control.
This driver enables UART by direct manipulation of the ESP32's hardware registers. Here are the registers:
DPORT_PERIP_CLK_EN_REG: Enables the clock, thus activating the target UART peripheral.DPORT_PERIP_RST_EN_REG: Resets the UART peripheral before configuring it to ensure it starts in a known state
UART_CONF0_REG: Configures the UART data format. In this case: 1 low start bit, 8 data bits, no parity, and 1 high stop bit (8N1).UART_CLKDIV_REG: Configures the clock divider based on thebaud_rate. This value assumes a 80MHz APB clock as found in the TRM.UART_CONF1_REG: Configures FIFO settings: thresholds for TX and RX FIFO buffers and RX timeout (enabled).
GPIO_ENABLE_REG: Configures the flow direction of the GPIO pins (input for RX, output for TX).GPIO_FUNC_OUT_SEL_REG: Connects the UART's TX to the correct GPIO pin via the GPIO matrix.GPIO_FUNC_IN_SEL_CFG_REG: Connects the signal from the desired GPIO pin to the RX UART via the GPIO matrix.GPIO_PINN_REG: Clear any pre-existing special GPIO pin configuration.
UART_STATUS_REG: Used in checking the number of bytes in the TX and RX FIFOs (txfifo_cntandrxfifo_cnt) and ensuring they are not full or empty when performing operations.UART_FIFO_REG: The combined TX RX register: write sends data to TX FIFO; read gets data from RX FIFO.
Initializes UART peripheral and configures the GPIO pins and baud_rate.
uart_num: A pointer to the UART instance to initialize (&uart0,&uart1,&uart2).baud_rate: The communication speed (9600, 115200, etc.).rx_gpio_num: GPIO pin for receiving data.tx_gpio_num: GPIO pin for transmitting data.
Writes 1 byte to the chosen UART's TX FIFO buffer.
uart_num: A pointer to the UART instance to initialize (&uart0,&uart1,&uart2).byte: The byte to be written
Reads 1 byte from the chosen UART's RX FIFO buffer (non-blocking).
uart_num: A pointer to the UART instance to initialize (&uart0,&uart1,&uart2).out_byte: The pointer to where the read byte should be stored- Returns:
1- success;0- no data / error
Reads 1 byte from the chosen UART's RX FIFO buffer. Note: this function is blocking - if no string is available the watchdog will throw an error, since the function fails to yield for too long.
uart_num: A pointer to the UART instance to initialize (&uart0,&uart1,&uart2).out_byte: The pointer to where the read byte should be stored
Writes a string to the UART port.
uart_num: A pointer to the UART instance to initialize (&uart0,&uart1,&uart2).str: The string to be written in the form of a char array
Reads characters from the UART port until delimeter is read or max_len is reached. Note: this function is blocking - if the end of the string is not reached the watchdog will throw an error, since the function fails to yield for too long.
uart_num: A pointer to the UART instance to initialize (&uart0,&uart1,&uart2).buffer: The pointer to where the read chars should be storedmax-len: The maximum length of string to read (usually the buffer size)delimeter: The character to look for to end the string
main.c - an example usage of reading and writing bytes and strings.
This project is built using the ESP-IDF framework.
-
Configure:
idf.py menuconfig
Set the TX and RX pins in
sdkconfig.defaults -
Build:
idf.py build
-
Flash:
idf.py -p /dev/ttyUSB0 flash
-
Monitor:
idf.py -p /dev/ttyUSB0 monitor
- The write and read functions feature busy loops which can trigger the watch dog
- This driver enables only a single UART configuration type
- UART1 and UART0 remain untested using this driver