esp32-hal-uart.c

// Copyright 2015-2025 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at

// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#include"esp32-hal-uart.h"

#ifSOC_UART_SUPPORTED
#include"esp32-hal.h"
#include"esp32-hal-periman.h"

#include"freertos/FreeRTOS.h"
#include"freertos/semphr.h"

#include"driver/uart.h"
#include"hal/uart_ll.h"
#include"soc/soc_caps.h"
#include"soc/uart_struct.h"
#include"soc/uart_periph.h"
#include"rom/ets_sys.h"
#include"rom/gpio.h"

#include"driver/gpio.h"
#include"hal/gpio_hal.h"
#include"esp_rom_gpio.h"

#include"driver/rtc_io.h"
#include"driver/lp_io.h"
#include"soc/uart_periph.h"
#include"esp_private/uart_share_hw_ctrl.h"

staticints_uart_debug_nr=0; // UART number for debug output
#defineREF_TICK_BAUDRATE_LIMIT 250000 // this is maximum UART badrate using REF_TICK as clock

structuart_struct_t {

#if !CONFIG_DISABLE_HAL_LOCKS
SemaphoreHandle_tlock; // UART lock
#endif

uint8_tnum; // UART number for IDF driver API
boolhas_peek; // flag to indicate that there is a peek byte pending to be read
uint8_tpeek_byte; // peek byte that has been read but not consumed
QueueHandle_tuart_event_queue; // export it by some uartGetEventQueue() function
// configuration data:: Arduino API typical data
int8_t_rxPin, _txPin, _ctsPin, _rtsPin; // UART GPIOs
uint32_t_baudrate, _config; // UART baudrate and config
// UART ESP32 specific data
uint16_t_rx_buffer_size, _tx_buffer_size; // UART RX and TX buffer sizes
bool_inverted; // UART inverted signal
uint8_t_rxfifo_full_thrhd; // UART RX FIFO full threshold
};

#ifCONFIG_DISABLE_HAL_LOCKS

#defineUART_MUTEX_LOCK()
#defineUART_MUTEX_UNLOCK()

staticuart_t_uart_bus_array[] = {
 {0, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#ifSOC_UART_NUM>1
 {1, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#endif
#ifSOC_UART_NUM>2
 {2, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#endif
#ifSOC_UART_NUM>3
 {3, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#endif
#ifSOC_UART_NUM>4
 {4, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#endif
#ifSOC_UART_NUM>5
 {5, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#endif
};

#else

#defineUART_MUTEX_LOCK() \
 if (uart->lock != NULL) \
 do { \
 } while (xSemaphoreTake(uart->lock, portMAX_DELAY) != pdPASS)
#defineUART_MUTEX_UNLOCK() \
 if (uart->lock != NULL) \
 xSemaphoreGive(uart->lock)

staticuart_t_uart_bus_array[] = {
 {NULL, 0, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#ifSOC_UART_NUM>1
 {NULL, 1, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#endif
#ifSOC_UART_NUM>2
 {NULL, 2, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#endif
#ifSOC_UART_NUM>3
 {NULL, 3, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#endif
#ifSOC_UART_NUM>4
 {NULL, 4, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#endif
#ifSOC_UART_NUM>5
 {NULL, 5, false, 0, NULL, -1, -1, -1, -1, 0, 0, 0, 0, false, 0},
#endif
};

#endif

#ifSOC_UART_LP_NUM >= 1
// LP UART enable pins routine
staticboollp_uart_config_io(uint8_tuart_num, int8_tpin, rtc_gpio_mode_tdirection, uint32_tidx) {
/* Skip configuration if the LP_IO is -1 */
if (pin<0) {
return true;
 }

// Initialize LP_IO
if (rtc_gpio_init(pin) !=ESP_OK) {
log_e("Failed to initialize LP_IO %d", pin);
return false;
 }

// Set LP_IO direction
if (rtc_gpio_set_direction(pin, direction) !=ESP_OK) {
log_e("Failed to set LP_IO %d direction", pin);
return false;
 }

// Connect pins
constuart_periph_sig_t*upin=&uart_periph_signal[uart_num].pins[idx];
#if !SOC_LP_GPIO_MATRIX_SUPPORTED// ESP32-C6/C61/C5
// When LP_IO Matrix is not support, LP_IO Mux must be connected to the pins
if (rtc_gpio_iomux_func_sel(pin, upin->iomux_func) !=ESP_OK) {
log_e("Failed to set LP_IO pin %d into Mux function", pin);
return false;
 }
#else// So far, only ESP32-P4
// If the configured pin is the default LP_IO Mux pin for LP UART, then set the LP_IO MUX function
if (upin->default_gpio==pin) {
if (rtc_gpio_iomux_func_sel(pin, upin->iomux_func) !=ESP_OK) {
log_e("Failed to set LP_IO pin %d into Mux function", pin);
return false;
 }
 } else {
// Otherwise, set the LP_IO Matrix and select FUNC1
if (rtc_gpio_iomux_func_sel(pin, 1) !=ESP_OK) {
log_e("Failed to set LP_IO pin %d into Mux function GPIO", pin);
return false;
 }
// Connect the LP_IO to the LP UART peripheral signal
esp_err_tret;
if (direction==RTC_GPIO_MODE_OUTPUT_ONLY) {
ret=lp_gpio_connect_out_signal(pin, UART_PERIPH_SIGNAL(uart_num, idx), 0, 0);
 } else {
ret=lp_gpio_connect_in_signal(pin, UART_PERIPH_SIGNAL(uart_num, idx), 0);
 }
if (ret!=ESP_OK) {
log_e("Failed to connect LP_IO pin %d to UART%d signal", pin, uart_num);
return false;
 }
 }
#endif// SOC_LP_GPIO_MATRIX_SUPPORTED

return true;
}

// When LP UART needs the RTC IO MUX to set the pin, it will always have fixed pins for RX, TX, CTS and RTS
staticboollpuartCheckPins(int8_trxPin, int8_ttxPin, int8_tctsPin, int8_trtsPin, uint8_tuart_nr) {
// check if LP UART is being used and if the pins are valid
#if !SOC_LP_GPIO_MATRIX_SUPPORTED// ESP32-C6/C61/C5
uint16_tlp_uart_fixed_pin=uart_periph_signal[uart_nr].pins[SOC_UART_RX_PIN_IDX].default_gpio;
if (uart_nr >= SOC_UART_HP_NUM) { // it is a LP UART NUM
if (rxPin>0&&rxPin!=lp_uart_fixed_pin) {
log_e("UART%d LP UART requires RX pin to be set to %d.", uart_nr, lp_uart_fixed_pin);
return false;
 }
lp_uart_fixed_pin=uart_periph_signal[uart_nr].pins[SOC_UART_TX_PIN_IDX].default_gpio;
if (txPin>0&&txPin!=lp_uart_fixed_pin) {
log_e("UART%d LP UART requires TX pin to be set to %d.", uart_nr, lp_uart_fixed_pin);
return false;
 }
lp_uart_fixed_pin=uart_periph_signal[uart_nr].pins[SOC_UART_CTS_PIN_IDX].default_gpio;
if (ctsPin>0&&ctsPin!=lp_uart_fixed_pin) {
log_e("UART%d LP UART requires CTS pin to be set to %d.", uart_nr, lp_uart_fixed_pin);
return false;
 }
lp_uart_fixed_pin=uart_periph_signal[uart_nr].pins[SOC_UART_RTS_PIN_IDX].default_gpio;
if (rtsPin>0&&rtsPin!=lp_uart_fixed_pin) {
log_e("UART%d LP UART requires RTS pin to be set to %d.", uart_nr, lp_uart_fixed_pin);
return false;
 }
 }
return true;
#else// ESP32-P4 can set any pin for LP UART
return true;
#endif// SOC_LP_GPIO_MATRIX_SUPPORTED
}
#endif// SOC_UART_LP_NUM >= 1

// Negative Pin Number will keep it unmodified, thus this function can detach individual pins
// This function will also unset the pins in the Peripheral Manager and set the pin to -1 after detaching
staticbool_uartDetachPins(uint8_tuart_num, int8_trxPin, int8_ttxPin, int8_tctsPin, int8_trtsPin) {
if (uart_num >= SOC_UART_NUM) {
log_e("Serial number is invalid, please use number from 0 to %u", SOC_UART_NUM-1);
return false;
 }
// get UART information
uart_t*uart=&_uart_bus_array[uart_num];
boolretCode= true;
//log_v("detaching UART%d pins: prev,pin RX(%d,%d) TX(%d,%d) CTS(%d,%d) RTS(%d,%d)", uart_num,
// uart->_rxPin, rxPin, uart->_txPin, txPin, uart->_ctsPin, ctsPin, uart->_rtsPin, rtsPin); vTaskDelay(10);

// detaches HP and LP pins and sets Peripheral Manager and UART information
if (rxPin >= 0&&uart->_rxPin==rxPin&&perimanGetPinBusType(rxPin) ==ESP32_BUS_TYPE_UART_RX) {
gpio_hal_iomux_func_sel(GPIO_PIN_MUX_REG[rxPin], PIN_FUNC_GPIO);
// avoids causing BREAK in the UART line
if (uart->_inverted) {
esp_rom_gpio_connect_in_signal(GPIO_FUNC_IN_LOW, UART_PERIPH_SIGNAL(uart_num, SOC_UART_RX_PIN_IDX), false);
 } else {
esp_rom_gpio_connect_in_signal(GPIO_FUNC_IN_HIGH, UART_PERIPH_SIGNAL(uart_num, SOC_UART_RX_PIN_IDX), false);
 }
uart->_rxPin=-1; // -1 means unassigned/detached
if (!perimanClearPinBus(rxPin)) {
retCode= false;
log_e("UART%d failed to detach RX pin %d", uart_num, rxPin);
 }
 }
if (txPin >= 0&&uart->_txPin==txPin&&perimanGetPinBusType(txPin) ==ESP32_BUS_TYPE_UART_TX) {
gpio_hal_iomux_func_sel(GPIO_PIN_MUX_REG[txPin], PIN_FUNC_GPIO);
esp_rom_gpio_connect_out_signal(txPin, SIG_GPIO_OUT_IDX, false, false);
uart->_txPin=-1; // -1 means unassigned/detached
if (!perimanClearPinBus(txPin)) {
retCode= false;
log_e("UART%d failed to detach TX pin %d", uart_num, txPin);
 }
 }
if (ctsPin >= 0&&uart->_ctsPin==ctsPin&&perimanGetPinBusType(ctsPin) ==ESP32_BUS_TYPE_UART_CTS) {
gpio_hal_iomux_func_sel(GPIO_PIN_MUX_REG[ctsPin], PIN_FUNC_GPIO);
esp_rom_gpio_connect_in_signal(GPIO_FUNC_IN_LOW, UART_PERIPH_SIGNAL(uart_num, SOC_UART_CTS_PIN_IDX), false);
uart->_ctsPin=-1; // -1 means unassigned/detached
if (!perimanClearPinBus(ctsPin)) {
retCode= false;
log_e("UART%d failed to detach CTS pin %d", uart_num, ctsPin);
 }
 }
if (rtsPin >= 0&&uart->_rtsPin==rtsPin&&perimanGetPinBusType(rtsPin) ==ESP32_BUS_TYPE_UART_RTS) {
gpio_hal_iomux_func_sel(GPIO_PIN_MUX_REG[rtsPin], PIN_FUNC_GPIO);
esp_rom_gpio_connect_out_signal(rtsPin, SIG_GPIO_OUT_IDX, false, false);
uart->_rtsPin=-1; // -1 means unassigned/detached
if (!perimanClearPinBus(rtsPin)) {
retCode= false;
log_e("UART%d failed to detach RTS pin %d", uart_num, rtsPin);
 }
 }
returnretCode;
}

// Peripheral Manager detach callback for each specific UART PIN
staticbool_uartDetachBus_RX(void*busptr) {
// sanity check - it should never happen
assert(busptr&&"_uartDetachBus_RX bus NULL pointer.");
uart_t*bus= (uart_t*)busptr;
return_uartDetachPins(bus->num, bus->_rxPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
}

staticbool_uartDetachBus_TX(void*busptr) {
// sanity check - it should never happen
assert(busptr&&"_uartDetachBus_TX bus NULL pointer.");
uart_t*bus= (uart_t*)busptr;
return_uartDetachPins(bus->num, UART_PIN_NO_CHANGE, bus->_txPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
}

staticbool_uartDetachBus_CTS(void*busptr) {
// sanity check - it should never happen
assert(busptr&&"_uartDetachBus_CTS bus NULL pointer.");
uart_t*bus= (uart_t*)busptr;
return_uartDetachPins(bus->num, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, bus->_ctsPin, UART_PIN_NO_CHANGE);
}

staticbool_uartDetachBus_RTS(void*busptr) {
// sanity check - it should never happen
assert(busptr&&"_uartDetachBus_RTS bus NULL pointer.");
uart_t*bus= (uart_t*)busptr;
return_uartDetachPins(bus->num, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, bus->_rtsPin);
}

// Attach function for UART
// connects the IO Pad, set Paripheral Manager and internal UART structure data
staticbool_uartAttachPins(uint8_tuart_num, int8_trxPin, int8_ttxPin, int8_tctsPin, int8_trtsPin) {
if (uart_num >= SOC_UART_NUM) {
log_e("Serial number is invalid, please use number from 0 to %u", SOC_UART_NUM-1);
return false;
 }
// get UART information
uart_t*uart=&_uart_bus_array[uart_num];
//log_v("attaching UART%d pins: prev,new RX(%d,%d) TX(%d,%d) CTS(%d,%d) RTS(%d,%d)", uart_num,
// uart->_rxPin, rxPin, uart->_txPin, txPin, uart->_ctsPin, ctsPin, uart->_rtsPin, rtsPin); vTaskDelay(10);

// IDF uart_set_pin() checks if the pin is used within LP UART and if it is a valid RTC IO pin
// No need for Arduino Layer to check it again
boolretCode= true;
if (rxPin >= 0) {
// forces a clean detaching from a previous peripheral
if (perimanGetPinBusType(rxPin) !=ESP32_BUS_TYPE_INIT) {
perimanClearPinBus(rxPin);
 }
// connect RX Pad
boolret=ESP_OK==uart_set_pin(uart->num, UART_PIN_NO_CHANGE, rxPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
#ifSOC_UART_LP_NUM >= 1
if (ret&&uart_num >= SOC_UART_HP_NUM) { // it is a LP UART NUM
ret &= lp_uart_config_io(uart->num, rxPin, RTC_GPIO_MODE_INPUT_ONLY, SOC_UART_RX_PIN_IDX);
 }
#endif
if (ret) {
ret &= perimanSetPinBus(rxPin, ESP32_BUS_TYPE_UART_RX, (void*)uart, uart_num, -1);
if (ret) {
uart->_rxPin=rxPin;
 }
 }
if (!ret) {
log_e("UART%d failed to attach RX pin %d", uart_num, rxPin);
 }
retCode &= ret;
 }
if (txPin >= 0) {
// forces a clean detaching from a previous peripheral
if (perimanGetPinBusType(txPin) !=ESP32_BUS_TYPE_INIT) {
perimanClearPinBus(txPin);
 }
// connect TX Pad
boolret=ESP_OK==uart_set_pin(uart->num, txPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
#ifSOC_UART_LP_NUM >= 1
if (ret&&uart_num >= SOC_UART_HP_NUM) { // it is a LP UART NUM
ret &= lp_uart_config_io(uart->num, txPin, RTC_GPIO_MODE_OUTPUT_ONLY, SOC_UART_TX_PIN_IDX);
 }
#endif
if (ret) {
ret &= perimanSetPinBus(txPin, ESP32_BUS_TYPE_UART_TX, (void*)uart, uart_num, -1);
if (ret) {
uart->_txPin=txPin;
 }
 }
if (!ret) {
log_e("UART%d failed to attach TX pin %d", uart_num, txPin);
 }
retCode &= ret;
 }
if (ctsPin >= 0) {
// forces a clean detaching from a previous peripheral
if (perimanGetPinBusType(ctsPin) !=ESP32_BUS_TYPE_INIT) {
perimanClearPinBus(ctsPin);
 }
// connect CTS Pad
boolret=ESP_OK==uart_set_pin(uart->num, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, ctsPin);
#ifSOC_UART_LP_NUM >= 1
if (ret&&uart_num >= SOC_UART_HP_NUM) { // it is a LP UART NUM
ret &= lp_uart_config_io(uart->num, ctsPin, RTC_GPIO_MODE_INPUT_ONLY, SOC_UART_CTS_PIN_IDX);
 }
#endif
if (ret) {
ret &= perimanSetPinBus(ctsPin, ESP32_BUS_TYPE_UART_CTS, (void*)uart, uart_num, -1);
if (ret) {
uart->_ctsPin=ctsPin;
 }
 }
if (!ret) {
log_e("UART%d failed to attach CTS pin %d", uart_num, ctsPin);
 }
retCode &= ret;
 }
if (rtsPin >= 0) {
// forces a clean detaching from a previous peripheral
if (perimanGetPinBusType(rtsPin) !=ESP32_BUS_TYPE_INIT) {
perimanClearPinBus(rtsPin);
 }
// connect RTS Pad
boolret=ESP_OK==uart_set_pin(uart->num, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, rtsPin, UART_PIN_NO_CHANGE);
#ifSOC_UART_LP_NUM >= 1
if (ret&&uart_num >= SOC_UART_HP_NUM) { // it is a LP UART NUM
ret &= lp_uart_config_io(uart->num, rtsPin, RTC_GPIO_MODE_OUTPUT_ONLY, SOC_UART_RTS_PIN_IDX);
 }
#endif
if (ret) {
ret &= perimanSetPinBus(rtsPin, ESP32_BUS_TYPE_UART_RTS, (void*)uart, uart_num, -1);
if (ret) {
uart->_rtsPin=rtsPin;
 }
 }
if (!ret) {
log_e("UART%d failed to attach RTS pin %d", uart_num, rtsPin);
 }
retCode &= ret;
 }
returnretCode;
}

// just helper functions
int8_tuart_get_RxPin(uint8_tuart_num) {
return_uart_bus_array[uart_num]._rxPin;
}

int8_tuart_get_TxPin(uint8_tuart_num) {
return_uart_bus_array[uart_num]._txPin;
}

voiduart_init_PeriMan(void) {
// set Peripheral Manager deInit Callback for each UART pin
perimanSetBusDeinit(ESP32_BUS_TYPE_UART_RX, _uartDetachBus_RX);
perimanSetBusDeinit(ESP32_BUS_TYPE_UART_TX, _uartDetachBus_TX);
perimanSetBusDeinit(ESP32_BUS_TYPE_UART_CTS, _uartDetachBus_CTS);
perimanSetBusDeinit(ESP32_BUS_TYPE_UART_RTS, _uartDetachBus_RTS);
}

// Routines that take care of UART events will be in the HardwareSerial Class code
voiduartGetEventQueue(uart_t*uart, QueueHandle_t*q) {
// passing back NULL for the Queue pointer when UART is not initialized yet
*q=NULL;
if (uart==NULL) {
return;
 }
*q=uart->uart_event_queue;
return;
}

booluartIsDriverInstalled(uart_t*uart) {
if (uart==NULL) {
return false;
 }

if (uart_is_driver_installed(uart->num)) {
return true;
 }
return false;
}

// Negative Pin Number will keep it unmodified, thus this function can set individual pins
// When pins are changed, it will detach the previous one
booluartSetPins(uint8_tuart_num, int8_trxPin, int8_ttxPin, int8_tctsPin, int8_trtsPin) {
if (uart_num >= SOC_UART_NUM) {
log_e("Serial number is invalid, please use number from 0 to %u", SOC_UART_NUM-1);
return false;
 }
// get UART information
uart_t*uart=&_uart_bus_array[uart_num];

#ifSOC_UART_LP_NUM >= 1
// check if LP UART is being used and if the pins are valid
if (!lpuartCheckPins(rxPin, txPin, ctsPin, rtsPin, uart_num)) {
return false; // failed to set pins
 }
#endif

boolretCode= true;
UART_MUTEX_LOCK();

//log_v("setting UART%d pins: prev->new RX(%d->%d) TX(%d->%d) CTS(%d->%d) RTS(%d->%d)", uart_num,
// uart->_rxPin, rxPin, uart->_txPin, txPin, uart->_ctsPin, ctsPin, uart->_rtsPin, rtsPin); vTaskDelay(10);

// First step: detaches all previous UART pins
boolrxPinChanged=rxPin >= 0&&rxPin!=uart->_rxPin;
if (rxPinChanged) {
retCode &= _uartDetachPins(uart_num, uart->_rxPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
 }
booltxPinChanged=txPin >= 0&&txPin!=uart->_txPin;
if (txPinChanged) {
retCode &= _uartDetachPins(uart_num, UART_PIN_NO_CHANGE, uart->_txPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
 }
boolctsPinChanged=ctsPin >= 0&&ctsPin!=uart->_ctsPin;
if (ctsPinChanged) {
retCode &= _uartDetachPins(uart_num, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, uart->_ctsPin, UART_PIN_NO_CHANGE);
 }
boolrtsPinChanged=rtsPin >= 0&&rtsPin!=uart->_rtsPin;
if (rtsPinChanged) {
retCode &= _uartDetachPins(uart_num, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, uart->_rtsPin);
 }

// Second step: attach all UART new pins
if (rxPinChanged) {
retCode &= _uartAttachPins(uart_num, rxPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
 }
if (txPinChanged) {
retCode &= _uartAttachPins(uart_num, UART_PIN_NO_CHANGE, txPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
 }
if (ctsPinChanged) {
retCode &= _uartAttachPins(uart->num, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, ctsPin, UART_PIN_NO_CHANGE);
 }
if (rtsPinChanged) {
retCode &= _uartAttachPins(uart->num, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, rtsPin);
 }
UART_MUTEX_UNLOCK();

if (!retCode) {
log_e("UART%d set pins failed.", uart_num);
 }
returnretCode;
}

//
booluartSetHwFlowCtrlMode(uart_t*uart, uart_hw_flowcontrol_tmode, uint8_tthreshold) {
if (uart==NULL) {
return false;
 }
// IDF will issue corresponding error message when mode or threshold are wrong and prevent crashing
// IDF will check (mode > HW_FLOWCTRL_CTS_RTS || threshold >= SOC_UART_FIFO_LEN)
UART_MUTEX_LOCK();
boolretCode= (ESP_OK==uart_set_hw_flow_ctrl(uart->num, mode, threshold));
UART_MUTEX_UNLOCK();
returnretCode;
}

// This helper function will return true if a new IDF UART driver needs to be restarted and false if the current one can continue its execution
bool_testUartBegin(
uint8_tuart_nr, uint32_tbaudrate, uint32_tconfig, int8_trxPin, int8_ttxPin, uint32_trx_buffer_size, uint32_ttx_buffer_size, boolinverted,
uint8_trxfifo_full_thrhd
) {
if (uart_nr >= SOC_UART_NUM) {
return false; // no new driver has to be installed
 }
uart_t*uart=&_uart_bus_array[uart_nr];
// verify if is necessary to restart the UART driver
if (uart_is_driver_installed(uart_nr)) {
// some parameters can't be changed unless we end the UART driver
if (uart->_rx_buffer_size!=rx_buffer_size||uart->_tx_buffer_size!=tx_buffer_size||uart->_inverted!=inverted
||uart->_rxfifo_full_thrhd!=rxfifo_full_thrhd) {
return true; // the current IDF UART driver must be terminated and a new driver shall be installed
 } else {
return false; // The current IDF UART driver can continue its execution
 }
 } else {
return true; // no IDF UART driver is running and a new driver shall be installed
 }
}

uart_t*uartBegin(
uint8_tuart_nr, uint32_tbaudrate, uint32_tconfig, int8_trxPin, int8_ttxPin, uint32_trx_buffer_size, uint32_ttx_buffer_size, boolinverted,
uint8_trxfifo_full_thrhd
) {
if (uart_nr >= SOC_UART_NUM) {
log_e("UART number is invalid, please use number from 0 to %u", SOC_UART_NUM-1);
returnNULL; // no new driver was installed
 }
uart_t*uart=&_uart_bus_array[uart_nr];
log_v("UART%d baud(%ld) Mode(%x) rxPin(%d) txPin(%d)", uart_nr, baudrate, config, rxPin, txPin);

#ifSOC_UART_LP_NUM >= 1
// check if LP UART is being used and if the pins are valid
if (!lpuartCheckPins(rxPin, txPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, uart_nr)) {
if (uart_is_driver_installed(uart_nr)) {
returnuart; // keep the same installed driver
 } else {
returnNULL; // no new driver was installed
 }
 }
#endif

#if !CONFIG_DISABLE_HAL_LOCKS
if (uart->lock==NULL) {
uart->lock=xSemaphoreCreateMutex();
if (uart->lock==NULL) {
log_e("HAL LOCK error.");
returnNULL; // no new driver was installed
 }
 }
#endif

if (uart_is_driver_installed(uart_nr)) {
log_v("UART%d Driver already installed.", uart_nr);
// some parameters can't be changed unless we end the UART driver
if (uart->_rx_buffer_size!=rx_buffer_size||uart->_tx_buffer_size!=tx_buffer_size||uart->_inverted!=inverted
||uart->_rxfifo_full_thrhd!=rxfifo_full_thrhd) {
log_v("UART%d changing buffer sizes or inverted signal or rxfifo_full_thrhd. IDF driver will be restarted", uart_nr);
log_v("RX buffer size: %d -> %d", uart->_rx_buffer_size, rx_buffer_size);
log_v("TX buffer size: %d -> %d", uart->_tx_buffer_size, tx_buffer_size);
log_v("Inverted signal: %s -> %s", uart->_inverted ? "true" : "false", inverted ? "true" : "false");
log_v("RX FIFO full threshold: %d -> %d", uart->_rxfifo_full_thrhd, rxfifo_full_thrhd);
uartEnd(uart_nr);
 } else {
boolretCode= true;
UART_MUTEX_LOCK();
//User may just want to change some parameters, such as baudrate, data length, parity, stop bits or pins
if (uart->_baudrate!=baudrate) {
if (ESP_OK!=uart_set_baudrate(uart_nr, baudrate)) {
log_e("UART%d changing baudrate failed.", uart_nr);
retCode= false;
 } else {
log_v("UART%d changed baudrate to %d", uart_nr, baudrate);
uart->_baudrate=baudrate;
 }
 }
uart_word_length_tdata_bits= (config&0xc) >> 2;
uart_parity_tparity=config&0x3;
uart_stop_bits_tstop_bits= (config&0x30) >> 4;
if (retCode&& (uart->_config&0xc) >> 2!=data_bits) {
if (ESP_OK!=uart_set_word_length(uart_nr, data_bits)) {
log_e("UART%d changing data length failed.", uart_nr);
retCode= false;
 } else {
log_v("UART%d changed data length to %d", uart_nr, data_bits+5);
 }
 }
if (retCode&& (uart->_config&0x3) !=parity) {
if (ESP_OK!=uart_set_parity(uart_nr, parity)) {
log_e("UART%d changing parity failed.", uart_nr);
retCode= false;
 } else {
log_v("UART%d changed parity to %s", uart_nr, parity==0 ? "NONE" : parity==2 ? "EVEN" : "ODD");
 }
 }
if (retCode&& (uart->_config&0xc30) >> 4!=stop_bits) {
if (ESP_OK!=uart_set_stop_bits(uart_nr, stop_bits)) {
log_e("UART%d changing stop bits failed.", uart_nr);
retCode= false;
 } else {
log_v("UART%d changed stop bits to %d", uart_nr, stop_bits==3 ? 2 : 1);
 }
 }
if (retCode) {
uart->_config=config;
 }
if (retCode&&rxPin>0&&uart->_rxPin!=rxPin) {
retCode &= _uartDetachPins(uart_nr, uart->_rxPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
retCode &= _uartAttachPins(uart_nr, rxPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
if (!retCode) {
log_e("UART%d changing RX pin failed.", uart_nr);
 } else {
log_v("UART%d changed RX pin to %d", uart_nr, rxPin);
 }
 }
if (retCode&&txPin>0&&uart->_txPin!=txPin) {
retCode &= _uartDetachPins(uart_nr, UART_PIN_NO_CHANGE, uart->_txPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
retCode &= _uartAttachPins(uart_nr, UART_PIN_NO_CHANGE, txPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
if (!retCode) {
log_e("UART%d changing TX pin failed.", uart_nr);
 } else {
log_v("UART%d changed TX pin to %d", uart_nr, txPin);
 }
 }
UART_MUTEX_UNLOCK();
if (retCode) {
// UART driver was already working, just return the uart_t structure, saying that no new driver was installed
returnuart;
 }
// if we reach this point, it means that we need to restart the UART driver
uartEnd(uart_nr);
 }
 } else {
log_v("UART%d not installed. Starting installation", uart_nr);
 }
uart_config_tuart_config;
memset(&uart_config, 0, sizeof(uart_config_t));
uart_config.flags.backup_before_sleep= false; // new flag from IDF v5.3
uart_config.data_bits= (config&0xc) >> 2;
uart_config.parity= (config&0x3);
uart_config.stop_bits= (config&0x30) >> 4;
uart_config.flow_ctrl=UART_HW_FLOWCTRL_DISABLE;
uart_config.rx_flow_ctrl_thresh=rxfifo_full_thrhd >= UART_HW_FIFO_LEN(uart_nr) ? UART_HW_FIFO_LEN(uart_nr) -6 : rxfifo_full_thrhd;
log_v(
"UART%d RX FIFO full threshold set to %d (value requested: %d || FIFO Max = %d)", uart_nr, uart_config.rx_flow_ctrl_thresh, rxfifo_full_thrhd,
UART_HW_FIFO_LEN(uart_nr)
 );
rxfifo_full_thrhd=uart_config.rx_flow_ctrl_thresh; // makes sure that it will be set correctly in the struct
uart_config.baud_rate=baudrate;
#ifSOC_UART_LP_NUM >= 1
if (uart_nr >= SOC_UART_HP_NUM) { // it is a LP UART NUM
uart_config.lp_source_clk=LP_UART_SCLK_DEFAULT; // use default LP clock
log_v("Setting UART%d to use LP clock", uart_nr);
 } else
#endif
 {
// there is an issue when returning from light sleep with the C6 and H2: the uart baud rate is not restored
// therefore, uart clock source will set to XTAL for all SoC that support it. This fix solves the C6|H2 issue.
#ifSOC_UART_SUPPORT_XTAL_CLK
uart_config.source_clk=UART_SCLK_XTAL; // valid for C2, S3, C3, C6, H2 and P4
log_v("Setting UART%d to use XTAL clock", uart_nr);
#elifSOC_UART_SUPPORT_REF_TICK
if (baudrate <= REF_TICK_BAUDRATE_LIMIT) {
uart_config.source_clk=UART_SCLK_REF_TICK; // valid for ESP32, S2 - MAX supported baud rate is 250 Kbps
log_v("Setting UART%d to use REF_TICK clock", uart_nr);
 } else {
uart_config.source_clk=UART_SCLK_APB; // baudrate may change with the APB Frequency!
log_v("Setting UART%d to use APB clock", uart_nr);
 }
#else
// Default CLK Source: CLK_APB for ESP32|S2|S3|C3 -- CLK_PLL_F40M for C2 -- CLK_PLL_F48M for H2 -- CLK_PLL_F80M for C6
uart_config.source_clk=UART_SCLK_DEFAULT; // baudrate may change with the APB Frequency!
log_v("Setting UART%d to use DEFAULT clock", uart_nr);
#endif
 }

UART_MUTEX_LOCK();
boolretCode=ESP_OK==uart_driver_install(uart_nr, rx_buffer_size, tx_buffer_size, 20, &(uart->uart_event_queue), 0);

if (retCode) {
retCode &= ESP_OK==uart_param_config(uart_nr, &uart_config);
 }

if (retCode) {
if (inverted) {
// invert signal for both Rx and Tx
retCode &= ESP_OK==uart_set_line_inverse(uart_nr, UART_SIGNAL_TXD_INV | UART_SIGNAL_RXD_INV);
 } else {
// disable invert signal for both Rx and Tx
retCode &= ESP_OK==uart_set_line_inverse(uart_nr, UART_SIGNAL_INV_DISABLE);
 }
 }
// if all fine, set internal parameters
if (retCode) {
uart->_baudrate=baudrate;
uart->_config=config;
uart->_inverted=inverted;
uart->_rxfifo_full_thrhd=rxfifo_full_thrhd;
uart->_rx_buffer_size=rx_buffer_size;
uart->_tx_buffer_size=tx_buffer_size;
uart->has_peek= false;
uart->peek_byte=0;
 }
UART_MUTEX_UNLOCK();

// uartSetPins detaches previous pins if new ones are used over a previous begin()
if (retCode) {
retCode &= uartSetPins(uart_nr, rxPin, txPin, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
 }
if (!retCode) {
log_e("UART%d initialization error.", uart->num);
uartEnd(uart_nr);
uart=NULL;
 } else {
uartFlush(uart);
log_v("UART%d initialization done.", uart->num);
 }
returnuart; // a new driver was installed
}

// This function code is under testing - for now just keep it here
voiduartSetFastReading(uart_t*uart) {
if (uart==NULL) {
return;
 }

UART_MUTEX_LOCK();
// override default RX IDF Driver Interrupt - no BREAK, PARITY or OVERFLOW
uart_intr_config_tuart_intr= {
 .intr_enable_mask=UART_INTR_RXFIFO_FULL | UART_INTR_RXFIFO_TOUT, // only these IRQs - no BREAK, PARITY or OVERFLOW
 .rx_timeout_thresh=1,
 .txfifo_empty_intr_thresh=10,
 .rxfifo_full_thresh=2,
 };

ESP_ERROR_CHECK(uart_intr_config(uart->num, &uart_intr));
UART_MUTEX_UNLOCK();
}

booluartSetRxTimeout(uart_t*uart, uint8_tnumSymbTimeout) {
if (uart==NULL) {
return false;
 }

UART_MUTEX_LOCK();
boolretCode= (ESP_OK==uart_set_rx_timeout(uart->num, numSymbTimeout));
UART_MUTEX_UNLOCK();
returnretCode;
}

booluartSetRxFIFOFull(uart_t*uart, uint8_tnumBytesFIFOFull) {
if (uart==NULL) {
return false;
 }
uint8_trxfifo_full_thrhd=numBytesFIFOFull >= UART_HW_FIFO_LEN(uart->num) ? UART_HW_FIFO_LEN(uart->num) -6 : numBytesFIFOFull;
UART_MUTEX_LOCK();
boolretCode= (ESP_OK==uart_set_rx_full_threshold(uart->num, rxfifo_full_thrhd));
if (retCode) {
uart->_rxfifo_full_thrhd=rxfifo_full_thrhd;
if (rxfifo_full_thrhd!=numBytesFIFOFull) {
log_w("The RX FIFO Full value for UART%d was set to %d instead of %d", uart->num, rxfifo_full_thrhd, numBytesFIFOFull);
 }
log_v("UART%d RX FIFO Full value set to %d from a requested value of %d", uart->num, rxfifo_full_thrhd, numBytesFIFOFull);
 } else {
log_e("UART%d failed to set RX FIFO Full value to %d", uart->num, numBytesFIFOFull);
 }
UART_MUTEX_UNLOCK();
returnretCode;
}

voiduartEnd(uint8_tuart_num) {
if (uart_num >= SOC_UART_NUM) {
log_e("Serial number is invalid, please use number from 0 to %u", SOC_UART_NUM-1);
return;
 }
// get UART information
uart_t*uart=&_uart_bus_array[uart_num];

UART_MUTEX_LOCK();
_uartDetachPins(uart_num, uart->_rxPin, uart->_txPin, uart->_ctsPin, uart->_rtsPin);
if (uart_is_driver_installed(uart_num)) {
uart_driver_delete(uart_num);
 }
UART_MUTEX_UNLOCK();
}

voiduartSetRxInvert(uart_t*uart, boolinvert) {
if (uart==NULL) {
return;
 }
#ifCONFIG_IDF_TARGET_ESP32C6||CONFIG_IDF_TARGET_ESP32H2||CONFIG_IDF_TARGET_ESP32P4
// POTENTIAL ISSUE :: original code only set/reset rxd_inv bit
// IDF or LL set/reset the whole inv_mask!
// if (invert)
// ESP_ERROR_CHECK(uart_set_line_inverse(uart->num, UART_SIGNAL_RXD_INV));
// else
// ESP_ERROR_CHECK(uart_set_line_inverse(uart->num, UART_SIGNAL_INV_DISABLE));
log_e("uartSetRxInvert is not supported in ESP32C6, ESP32H2 and ESP32P4");
#else
// this implementation is better over IDF API because it only affects RXD
// this is supported in ESP32, ESP32-S2 and ESP32-C3
uart_dev_t*hw=UART_LL_GET_HW(uart->num);
if (invert) {
hw->conf0.rxd_inv=1;
 } else {
hw->conf0.rxd_inv=0;
 }
#endif
}

uint32_tuartAvailable(uart_t*uart) {

if (uart==NULL) {
return0;
 }

UART_MUTEX_LOCK();
size_tavailable;
uart_get_buffered_data_len(uart->num, &available);
if (uart->has_peek) {
available++;
 }
UART_MUTEX_UNLOCK();
returnavailable;
}

uint32_tuartAvailableForWrite(uart_t*uart) {
if (uart==NULL) {
return0;
 }
UART_MUTEX_LOCK();
uint32_tavailable=uart_ll_get_txfifo_len(UART_LL_GET_HW(uart->num));
size_ttxRingBufferAvailable=0;
if (ESP_OK==uart_get_tx_buffer_free_size(uart->num, &txRingBufferAvailable)) {
available=txRingBufferAvailable==0 ? available : txRingBufferAvailable;
 }
UART_MUTEX_UNLOCK();
returnavailable;
}

size_tuartReadBytes(uart_t*uart, uint8_t*buffer, size_tsize, uint32_ttimeout_ms) {
if (uart==NULL||size==0||buffer==NULL) {
return0;
 }

size_tbytes_read=0;

UART_MUTEX_LOCK();

if (uart->has_peek) {
uart->has_peek= false;
*buffer++=uart->peek_byte;
size--;
bytes_read=1;
 }

if (size>0) {
intlen=uart_read_bytes(uart->num, buffer, size, pdMS_TO_TICKS(timeout_ms));
if (len<0) {
len=0; // error reading UART
 }
bytes_read+=len;
 }

UART_MUTEX_UNLOCK();
returnbytes_read;
}

// DEPRECATED but the original code will be kepts here as future reference when a final solution
// to the UART driver is defined in the use case of reading byte by byte from UART.
uint8_tuartRead(uart_t*uart) {
if (uart==NULL) {
return0;
 }
uint8_tc=0;

UART_MUTEX_LOCK();

if (uart->has_peek) {
uart->has_peek= false;
c=uart->peek_byte;
 } else {

intlen=uart_read_bytes(uart->num, &c, 1, 20 / portTICK_PERIOD_MS);
if (len <= 0) { // includes negative return from IDF in case of error
c=0;
 }
 }
UART_MUTEX_UNLOCK();
returnc;
}

uint8_tuartPeek(uart_t*uart) {
if (uart==NULL) {
return0;
 }
uint8_tc=0;

UART_MUTEX_LOCK();

if (uart->has_peek) {
c=uart->peek_byte;
 } else {
intlen=uart_read_bytes(uart->num, &c, 1, 20 / portTICK_PERIOD_MS);
if (len <= 0) { // includes negative return from IDF in case of error
c=0;
 } else {
uart->has_peek= true;
uart->peek_byte=c;
 }
 }
UART_MUTEX_UNLOCK();
returnc;
}

voiduartWrite(uart_t*uart, uint8_tc) {
if (uart==NULL) {
return;
 }
UART_MUTEX_LOCK();
uart_write_bytes(uart->num, &c, 1);
UART_MUTEX_UNLOCK();
}

voiduartWriteBuf(uart_t*uart, constuint8_t*data, size_tlen) {
if (uart==NULL||data==NULL|| !len) {
return;
 }

UART_MUTEX_LOCK();
uart_write_bytes(uart->num, data, len);
UART_MUTEX_UNLOCK();
}

voiduartFlush(uart_t*uart) {
uartFlushTxOnly(uart, true);
}

voiduartFlushTxOnly(uart_t*uart, booltxOnly) {
if (uart==NULL) {
return;
 }

UART_MUTEX_LOCK();
while (!uart_ll_is_tx_idle(UART_LL_GET_HW(uart->num)));

if (!txOnly) {
ESP_ERROR_CHECK(uart_flush_input(uart->num));
 }
UART_MUTEX_UNLOCK();
}

voiduartSetBaudRate(uart_t*uart, uint32_tbaud_rate) {
if (uart==NULL) {
return;
 }
UART_MUTEX_LOCK();
#ifSOC_UART_SUPPORT_XTAL_CLK// ESP32-S3, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2 and ESP32-P4
soc_module_clk_tnewClkSrc=UART_SCLK_XTAL;
#ifSOC_UART_LP_NUM >= 1
if (uart->num >= SOC_UART_HP_NUM) { // it is a LP UART NUM
newClkSrc=LP_UART_SCLK_DEFAULT; // use default LP clock
 }
#endif
// ESP32-P4 demands an atomic operation for setting the clock source
HP_UART_SRC_CLK_ATOMIC() {
uart_ll_set_sclk(UART_LL_GET_HW(uart->num), newClkSrc);
 }
#else// ESP32, ESP32-S2
soc_module_clk_tnewClkSrc=baud_rate <= REF_TICK_BAUDRATE_LIMIT ? SOC_MOD_CLK_REF_TICK : SOC_MOD_CLK_APB;
uart_ll_set_sclk(UART_LL_GET_HW(uart->num), newClkSrc);
#endif
if (uart_set_baudrate(uart->num, baud_rate) ==ESP_OK) {
log_v("Setting UART%d baud rate to %d.", uart->num, baud_rate);
uart->_baudrate=baud_rate;
 } else {
log_e("Setting UART%d baud rate to %d has failed.", uart->num, baud_rate);
 }