HardwareSerial Available For Write (#9319)

* feat(uart): setBufferSize 

It makes sure that setting TX buffer size will match availableForWrite() response. It also sets the buffer to the minimum instead of doing nothing and returning an error.

For RX Buffer, it sets the minimum and also don't return an error.

This makes the APIs better and easy to understand its results.

* feat: sets TX buffer 

This will allow to set TX buffer to a minimum with no error message.
It also makes it works as in the Arduino API specification that is to return the buffer available space. In ESP32 case it will be the minmum the HW TX FIFO size of 128 bytes.

* feat: adjust availableForWrite

This change will make sure that if no TX Ringbuffer is used, it will return the UART FIFO available space. Otherwise, it will return the Ringbuffer available space, as defined in the Arduino especification.

Author: SuGlider

cores/esp32/HardwareSerial.cpp

@@ -537,35 +537,37 @@ bool HardwareSerial::setMode(SerialMode mode)
     return uartSetMode(_uart, mode);
 }
 
+// minimum total RX Buffer size is the UART FIFO space (128 bytes for most SoC) + 1. IDF imposition.
 size_t HardwareSerial::setRxBufferSize(size_t new_size) {
 
     if (_uart) {
-        log_e("RX Buffer can't be resized when Serial is already running.\n");
+        log_e("RX Buffer can't be resized when Serial is already running. Set it before calling begin().");
         return 0;
     }
 
     if (new_size <= SOC_UART_FIFO_LEN) {
-        log_e("RX Buffer must be higher than %d.\n", SOC_UART_FIFO_LEN);  // ESP32, S2, S3 and C3 means higher than 128
-        return 0;
+        log_w("RX Buffer set to minimum value: %d.", SOC_UART_FIFO_LEN + 1);  // ESP32, S2, S3 and C3 means higher than 128
+        new_size = SOC_UART_FIFO_LEN + 1;
     }
 
     _rxBufferSize = new_size;
     return _rxBufferSize;
 }
 
+// minimum total TX Buffer size is the UART FIFO space (128 bytes for most SoC).
 size_t HardwareSerial::setTxBufferSize(size_t new_size) {
 
     if (_uart) {
-        log_e("TX Buffer can't be resized when Serial is already running.\n");
+        log_e("TX Buffer can't be resized when Serial is already running. Set it before calling begin().");
         return 0;
     }
 
     if (new_size <= SOC_UART_FIFO_LEN) {
-        log_e("TX Buffer must be higher than %d.\n", SOC_UART_FIFO_LEN);  // ESP32, S2, S3 and C3 means higher than 128
-        return 0;
+        log_w("TX Buffer set to minimum value: %d.", SOC_UART_FIFO_LEN);  // ESP32, S2, S3 and C3 means higher than 128
+        _txBufferSize = 0; // it will use just UART FIFO with SOC_UART_FIFO_LEN bytes (128 for most SoC)
+        return SOC_UART_FIFO_LEN;
     }
-
+    // if new_size is higher than SOC_UART_FIFO_LEN, TX Ringbuffer will be active and it will be used to report back "availableToWrite()"
     _txBufferSize = new_size;
-    return _txBufferSize;
+    return new_size;
 }
-

cores/esp32/esp32-hal-uart.c

@@ -642,7 +642,7 @@ uint32_t uartAvailableForWrite(uart_t* uart)
     uint32_t available =  uart_ll_get_txfifo_len(UART_LL_GET_HW(uart->num));  
     size_t txRingBufferAvailable = 0;
     if (ESP_OK == uart_get_tx_buffer_free_size(uart->num, &txRingBufferAvailable)) {
-        available += txRingBufferAvailable; 
+        available = txRingBufferAvailable == 0 ? available : txRingBufferAvailable; 
     }
     UART_MUTEX_UNLOCK();
     return available;