3.0.0 - UART Peripheral Manager + Detach UART pins on begin()/setPins() (#8719)

* detach UART pins

* fixes uartEnd() call

cores/esp32/HardwareSerial.cpp

@@ -149,7 +149,7 @@ void serialEventRun(void)
 #define HSERIAL_MUTEX_UNLOCK()
 #endif
 
-HardwareSerial::HardwareSerial(int uart_nr) :
+HardwareSerial::HardwareSerial(uint8_t uart_nr) :
 _uart_nr(uart_nr),
 _uart(NULL),
 _rxBufferSize(256),
@@ -173,6 +173,12 @@ _eventTask(NULL)
         }
     }
 #endif
+    // sets UART0 (default console) RX/TX pins as already configured in boot
+    if (uart_nr == 0) {
+        setPins(SOC_RX0, SOC_TX0);
+    }
+    // set deinit function in the Peripheral Manager
+    uart_init_PeriMan();
 }
 
 HardwareSerial::~HardwareSerial()
@@ -342,8 +348,8 @@ void HardwareSerial::_uartEventTask(void *args)
 
 void HardwareSerial::begin(unsigned long baud, uint32_t config, int8_t rxPin, int8_t txPin, bool invert, unsigned long timeout_ms, uint8_t rxfifo_full_thrhd)
 {
-    if(0 > _uart_nr || _uart_nr >= SOC_UART_NUM) {
-        log_e("Serial number is invalid, please use numers from 0 to %u", SOC_UART_NUM - 1);
+    if(_uart_nr >= SOC_UART_NUM) {
+        log_e("Serial number is invalid, please use a number from 0 to %u", SOC_UART_NUM - 1);
         return;
     }
 
@@ -357,26 +363,32 @@ void HardwareSerial::begin(unsigned long baud, uint32_t config, int8_t rxPin, in
     HSERIAL_MUTEX_LOCK();
     // First Time or after end() --> set default Pins
     if (!uartIsDriverInstalled(_uart)) {
+        // get previously used RX/TX pins, if any.
+        int8_t _rxPin = uart_get_RxPin(_uart_nr);
+        int8_t _txPin = uart_get_TxPin(_uart_nr);
         switch (_uart_nr) {
             case UART_NUM_0:
                 if (rxPin < 0 && txPin < 0) {
-                    rxPin = SOC_RX0;
-                    txPin = SOC_TX0;
+                    // do not change RX0/TX0 if it has already been set before
+                    rxPin = _rxPin < 0 ? SOC_RX0 : _rxPin;
+                    txPin = _txPin < 0 ? SOC_TX0 : _txPin;
                 }
             break;
 #if SOC_UART_NUM > 1                   // may save some flash bytes...
             case UART_NUM_1:
                if (rxPin < 0 && txPin < 0) {
-                    rxPin = RX1;
-                    txPin = TX1;
+                    // do not change RX1/TX1 if it has already been set before
+                    rxPin = _rxPin < 0 ? RX1 : _rxPin;
+                    txPin = _txPin < 0 ? TX1 : _txPin;
                 }
             break;
 #endif
 #if SOC_UART_NUM > 2                   // may save some flash bytes...
             case UART_NUM_2:
                if (rxPin < 0 && txPin < 0) {
-                    rxPin = RX2;
-                    txPin = TX2;
+                    // do not change RX2/TX2 if it has already been set before
+                    rxPin = _rxPin < 0 ? RX2 : _rxPin;
+                    txPin = _txPin < 0 ? TX2 : _txPin;
                 }
             break;
 #endif
@@ -390,6 +402,7 @@ void HardwareSerial::begin(unsigned long baud, uint32_t config, int8_t rxPin, in
     }
 
     // IDF UART driver keeps Pin setting on restarting. Negative Pin number will keep it unmodified.
+    // it will detach previous UART attached pins
     _uart = uartBegin(_uart_nr, baud ? baud : 9600, config, rxPin, txPin, _rxBufferSize, _txBufferSize, invert, rxfifo_full_thrhd);
     if (!baud) {
         // using baud rate as zero, forces it to try to detect the current baud rate in place
@@ -452,13 +465,13 @@ void HardwareSerial::end(bool fullyTerminate)
             uartSetDebug(0);
         }
         _rxFIFOFull = 0;
-        uartEnd(_uart);  // fully detach all pins and delete the UART driver
+        uartEnd(_uart_nr);  // fully detach all pins and delete the UART driver
     } else {
       // do not invalidate callbacks, detach pins, invalidate DBG output
       uart_driver_delete(_uart_nr);
     }
 
-    uartEnd(_uart);
+    uartEnd(_uart_nr);
     _uart = 0;
     _destroyEventTask();
 }
@@ -540,8 +553,8 @@ size_t HardwareSerial::write(const uint8_t *buffer, size_t size)
     uartWriteBuf(_uart, buffer, size);
     return size;
 }
-uint32_t  HardwareSerial::baudRate()
 
+uint32_t  HardwareSerial::baudRate()
 {
   return uartGetBaudRate(_uart);
 }
@@ -556,19 +569,11 @@ void HardwareSerial::setRxInvert(bool invert)
 }
 
 // negative Pin value will keep it unmodified
+// can be called after or before begin()
 bool HardwareSerial::setPins(int8_t rxPin, int8_t txPin, int8_t ctsPin, int8_t rtsPin)
 {
-    if(_uart == NULL) {
-        log_e("setPins() shall be called after begin() - nothing done\n");
-        return false;
-    }
-
-    // uartSetPins() checks if pins are valid for each function and for the SoC
-    if (uartSetPins(_uart, rxPin, txPin, ctsPin, rtsPin)) {
-        return true;
-    } else {
-        return false;
-    }
+    // uartSetPins() checks if pins are valid and, if necessary, detaches the previous ones
+    return uartSetPins(_uart_nr, rxPin, txPin, ctsPin, rtsPin);
 }
 
 // Enables or disables Hardware Flow Control using RTS and/or CTS pins (must use setAllPins() before)

cores/esp32/HardwareSerial.h

@@ -71,7 +71,7 @@ typedef std::function<void(hardwareSerial_error_t)> OnReceiveErrorCb;
 class HardwareSerial: public Stream
 {
 public:
-    HardwareSerial(int uart_nr);
+    HardwareSerial(uint8_t uart_nr);
     ~HardwareSerial();
 
     // setRxTimeout sets the timeout after which onReceive callback will be called (after receiving data, it waits for this time of UART rx inactivity to call the callback fnc)
@@ -106,6 +106,11 @@ public:
     // eventQueueReset clears all events in the queue (the events that trigger onReceive and onReceiveError) - maybe usefull in some use cases
     void eventQueueReset();
  
+    // When pins are changed, it will detach the previous ones
+    // if pin is negative, it won't be set/changed and will be kept as is
+    // timeout_ms is used in baudrate detection (ESP32, ESP32S2 only)
+    // invert will invert RX/TX polarity
+    // rxfifo_full_thrhd if the UART Flow Control Threshold in the UART FIFO (max 127)
     void begin(unsigned long baud, uint32_t config=SERIAL_8N1, int8_t rxPin=-1, int8_t txPin=-1, bool invert=false, unsigned long timeout_ms = 20000UL, uint8_t rxfifo_full_thrhd = 112);
     void end(bool fullyTerminate = true);
     void updateBaudRate(unsigned long baud);
@@ -160,7 +165,8 @@ public:
     void setRxInvert(bool);
 
     // Negative Pin Number will keep it unmodified, thus this function can set individual pins
-    // SetPins shall be called after Serial begin()
+    // setPins() can be called after or before begin()
+    // When pins are changed, it will detach the previous ones
     bool setPins(int8_t rxPin, int8_t txPin, int8_t ctsPin = -1, int8_t rtsPin = -1);
     // Enables or disables Hardware Flow Control using RTS and/or CTS pins (must use setAllPins() before)
     bool setHwFlowCtrlMode(uint8_t mode = HW_FLOWCTRL_CTS_RTS, uint8_t threshold = 64);   // 64 is half FIFO Length
@@ -170,7 +176,7 @@ public:
     size_t setTxBufferSize(size_t new_size);
 
 protected:
-    int _uart_nr;
+    uint8_t _uart_nr;
     uart_t* _uart;
     size_t _rxBufferSize;
     size_t _txBufferSize;

cores/esp32/chip-debug-report.cpp

@@ -253,7 +253,10 @@ static void printPerimanInfo(void){
     chip_report_printf("  %17u : ", i);
     switch(type){
       case ESP32_BUS_TYPE_GPIO: chip_report_printf("GPIO\n"); break;
-      case ESP32_BUS_TYPE_UART: chip_report_printf("UART\n"); break;
+      case ESP32_BUS_TYPE_UART_RX: chip_report_printf("UART_RX\n"); break;
+      case ESP32_BUS_TYPE_UART_TX: chip_report_printf("UART_TX\n"); break;
+      case ESP32_BUS_TYPE_UART_CTS: chip_report_printf("UART_CTS\n"); break;
+      case ESP32_BUS_TYPE_UART_RTS: chip_report_printf("UART_RTS\n"); break;
 #if SOC_SDM_SUPPORTED
       case ESP32_BUS_TYPE_SIGMADELTA: chip_report_printf("SIGMADELTA\n"); break;
 #endif

cores/esp32/esp32-hal-periman.h

@@ -17,7 +17,10 @@ extern "C"
 typedef enum {
 	ESP32_BUS_TYPE_INIT, 		// IO has not been attached to a bus yet
 	ESP32_BUS_TYPE_GPIO, 		// IO is used as GPIO
-	ESP32_BUS_TYPE_UART, 		// IO is used as UART pin
+	ESP32_BUS_TYPE_UART_RX,  	// IO is used as UART RX pin
+	ESP32_BUS_TYPE_UART_TX, 	// IO is used as UART TX pin
+	ESP32_BUS_TYPE_UART_CTS,	// IO is used as UART CTS pin
+	ESP32_BUS_TYPE_UART_RTS,	// IO is used as UART RTS pin
 #if SOC_SDM_SUPPORTED
 	ESP32_BUS_TYPE_SIGMADELTA, 	// IO is used as SigmeDelta output
 #endif

cores/esp32/esp32-hal-uart.h

@@ -103,7 +103,7 @@ struct uart_struct_t;
 typedef struct uart_struct_t uart_t;
 
 uart_t* uartBegin(uint8_t uart_nr, uint32_t baudrate, uint32_t config, int8_t rxPin, int8_t txPin, uint16_t rx_buffer_size, uint16_t tx_buffer_size, bool inverted, uint8_t rxfifo_full_thrhd);
-void uartEnd(uart_t* uart);
+void uartEnd(uint8_t uart_num);
 
 // This is used to retrieve the Event Queue pointer from a UART IDF Driver in order to allow user to deal with its events
 void uartGetEventQueue(uart_t* uart, QueueHandle_t *q); 
@@ -133,8 +133,16 @@ int uartGetDebug();
 
 bool uartIsDriverInstalled(uart_t* uart);
 
-// Negative Pin Number will keep it unmodified, thus this function can set/reset individual pins
-bool uartSetPins(uart_t* uart, int8_t rxPin, int8_t txPin, int8_t ctsPin, int8_t rtsPin);
+// Negative Pin Number will keep it unmodified, thus this function can set individual pins
+// When pins are changed, it will detach the previous ones
+// Can be called before or after begin()
+bool uartSetPins(uint8_t uart_num, int8_t rxPin, int8_t txPin, int8_t ctsPin, int8_t rtsPin);
+
+// helper functions
+int8_t uart_get_RxPin(uint8_t uart_num);
+int8_t uart_get_TxPin(uint8_t uart_num);
+void uart_init_PeriMan(void);
+
 
 // Enables or disables HW Flow Control function -- needs also to set CTS and/or RTS pins
 bool uartSetHwFlowCtrlMode(uart_t *uart, uint8_t mode, uint8_t threshold);