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

* detach UART pins * fixes uartEnd() call

Author: SuGlider

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 @@ class HardwareSerial: public Stream
  // 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 @@ class HardwareSerial: public Stream
  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 @@ class HardwareSerial: public Stream
  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