feat(uart): backports UART pin attachment from 3.0.0 to 2.0.15 (#9176)

* feat(uart): backports UART pin attachment from 3.0.0 to 2.0.15

* Fix (uart): Fixes additional Serial HardwareSerial errors for 2.0.14

* Update esp32-hal-uart.c

* Update HardwareSerial.h

* Apply suggestions from code review

* Fixes UartAvailableForWrite #9319

* Fixes  (set RX/TX buffer size)

cores/esp32/HardwareSerial.h

@@ -49,13 +49,45 @@
 #include <functional>
 #include "Stream.h"
 #include "esp32-hal.h"
+#include "hal/uart_types.h"
 #include "soc/soc_caps.h"
 #include "HWCDC.h"
+#include "USBCDC.h"
 
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 #include "freertos/semphr.h"
 
+enum SerialConfig {
+    SERIAL_5N1 = 0x8000010,
+    SERIAL_6N1 = 0x8000014,
+    SERIAL_7N1 = 0x8000018,
+    SERIAL_8N1 = 0x800001c,
+    SERIAL_5N2 = 0x8000030,
+    SERIAL_6N2 = 0x8000034,
+    SERIAL_7N2 = 0x8000038,
+    SERIAL_8N2 = 0x800003c,
+    SERIAL_5E1 = 0x8000012,
+    SERIAL_6E1 = 0x8000016,
+    SERIAL_7E1 = 0x800001a,
+    SERIAL_8E1 = 0x800001e,
+    SERIAL_5E2 = 0x8000032,
+    SERIAL_6E2 = 0x8000036,
+    SERIAL_7E2 = 0x800003a,
+    SERIAL_8E2 = 0x800003e,
+    SERIAL_5O1 = 0x8000013,
+    SERIAL_6O1 = 0x8000017,
+    SERIAL_7O1 = 0x800001b,
+    SERIAL_8O1 = 0x800001f,
+    SERIAL_5O2 = 0x8000033,
+    SERIAL_6O2 = 0x8000037,
+    SERIAL_7O2 = 0x800003b,
+    SERIAL_8O2 = 0x800003f
+};
+
+typedef uart_mode_t SerialMode;
+typedef uart_hw_flowcontrol_t SerialHwFlowCtrl;
+
 typedef enum {
     UART_NO_ERROR,
     UART_BREAK_ERROR,
@@ -65,6 +97,91 @@ typedef enum {
     UART_PARITY_ERROR
 } hardwareSerial_error_t;
 
+
+#ifndef ARDUINO_SERIAL_EVENT_TASK_STACK_SIZE
+  #define ARDUINO_SERIAL_EVENT_TASK_STACK_SIZE 2048
+#endif
+
+#ifndef ARDUINO_SERIAL_EVENT_TASK_PRIORITY
+  #define ARDUINO_SERIAL_EVENT_TASK_PRIORITY (configMAX_PRIORITIES-1)
+#endif
+
+#ifndef ARDUINO_SERIAL_EVENT_TASK_RUNNING_CORE
+  #define ARDUINO_SERIAL_EVENT_TASK_RUNNING_CORE -1
+#endif
+
+// UART0 pins are defined by default by the bootloader.
+// The definitions for SOC_* should not be changed unless the bootloader pins
+// have changed and you know what you are doing.
+
+#ifndef SOC_RX0
+  #if CONFIG_IDF_TARGET_ESP32
+    #define SOC_RX0 (gpio_num_t)3
+  #elif CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3
+    #define SOC_RX0 (gpio_num_t)44
+  #elif CONFIG_IDF_TARGET_ESP32C3
+    #define SOC_RX0 (gpio_num_t)20
+  #endif
+#endif
+
+#ifndef SOC_TX0
+  #if CONFIG_IDF_TARGET_ESP32
+    #define SOC_TX0 (gpio_num_t)1
+  #elif CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3
+    #define SOC_TX0 (gpio_num_t)43
+  #elif CONFIG_IDF_TARGET_ESP32C3
+    #define SOC_TX0 (gpio_num_t)21
+  #endif
+#endif
+
+// Default pins for UART1 are arbitrary, and defined here for convenience.
+
+#if SOC_UART_NUM > 1
+  #ifndef RX1
+    #if CONFIG_IDF_TARGET_ESP32
+      #define RX1 (gpio_num_t)26
+    #elif CONFIG_IDF_TARGET_ESP32S2
+      #define RX1 (gpio_num_t)4
+    #elif CONFIG_IDF_TARGET_ESP32C3
+      #define RX1 (gpio_num_t)18
+    #elif CONFIG_IDF_TARGET_ESP32S3
+      #define RX1 (gpio_num_t)15
+    #endif
+  #endif
+
+  #ifndef TX1
+    #if CONFIG_IDF_TARGET_ESP32
+      #define TX1 (gpio_num_t)27
+    #elif CONFIG_IDF_TARGET_ESP32S2
+      #define TX1 (gpio_num_t)5
+    #elif CONFIG_IDF_TARGET_ESP32C3
+      #define TX1 (gpio_num_t)19
+    #elif CONFIG_IDF_TARGET_ESP32S3
+      #define TX1 (gpio_num_t)16
+    #endif
+  #endif
+#endif /* SOC_UART_NUM > 1 */
+
+// Default pins for UART2 are arbitrary, and defined here for convenience.
+
+#if SOC_UART_NUM > 2
+  #ifndef RX2
+    #if CONFIG_IDF_TARGET_ESP32
+      #define RX2 (gpio_num_t)4
+    #elif CONFIG_IDF_TARGET_ESP32S3
+      #define RX2 (gpio_num_t)19
+    #endif
+  #endif
+
+  #ifndef TX2
+    #if CONFIG_IDF_TARGET_ESP32
+      #define TX2 (gpio_num_t)25
+    #elif CONFIG_IDF_TARGET_ESP32S3
+      #define TX2 (gpio_num_t)20
+    #endif
+  #endif
+#endif /* SOC_UART_NUM > 2 */
+
 typedef std::function<void(void)> OnReceiveCb;
 typedef std::function<void(hardwareSerial_error_t)> OnReceiveErrorCb;
 
@@ -106,8 +223,13 @@ 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 end(void);
     void updateBaudRate(unsigned long baud);
     int available(void);
     int availableForWrite(void);
@@ -160,12 +282,22 @@ 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
+    //    UART_HW_FLOWCTRL_DISABLE = 0x0   disable hardware flow control
+    //    UART_HW_FLOWCTRL_RTS     = 0x1   enable RX hardware flow control (rts)
+    //    UART_HW_FLOWCTRL_CTS     = 0x2   enable TX hardware flow control (cts)
+    //    UART_HW_FLOWCTRL_CTS_RTS = 0x3   enable hardware flow control
+    bool setHwFlowCtrlMode(SerialHwFlowCtrl mode = UART_HW_FLOWCTRL_CTS_RTS, uint8_t threshold = 64);   // 64 is half FIFO Length
     // Used to set RS485 modes such as UART_MODE_RS485_HALF_DUPLEX for Auto RTS function on ESP32
-    bool setMode(uint8_t mode);
+    //    UART_MODE_UART                   = 0x00    mode: regular UART mode
+    //    UART_MODE_RS485_HALF_DUPLEX      = 0x01    mode: half duplex RS485 UART mode control by RTS pin
+    //    UART_MODE_IRDA                   = 0x02    mode: IRDA UART mode
+    //    UART_MODE_RS485_COLLISION_DETECT = 0x03    mode: RS485 collision detection UART mode (used for test purposes)
+    //    UART_MODE_RS485_APP_CTRL         = 0x04    mode: application control RS485 UART mode (used for test purposes)
+    bool setMode(SerialMode mode);
     size_t setRxBufferSize(size_t new_size);
     size_t setTxBufferSize(size_t new_size);
 
@@ -183,7 +315,6 @@ protected:
 #if !CONFIG_DISABLE_HAL_LOCKS
     SemaphoreHandle_t _lock;
 #endif
-    int8_t _rxPin, _txPin, _ctsPin, _rtsPin;
 
     void _createEventTask(void *args);
     void _destroyEventTask(void);
@@ -197,10 +328,6 @@ extern void serialEventRun(void) __attribute__((weak));
 #define ARDUINO_USB_CDC_ON_BOOT 0
 #endif
 #if ARDUINO_USB_CDC_ON_BOOT //Serial used for USB CDC
-#if !ARDUINO_USB_MODE
-#include "USB.h"
-#include "USBCDC.h"
-#endif
 extern HardwareSerial Serial0;
 #else
 extern HardwareSerial Serial;
@@ -211,6 +338,5 @@ extern HardwareSerial Serial1;
 #if SOC_UART_NUM > 2
 extern HardwareSerial Serial2;
 #endif
-#endif
-
+#endif // !defined(NO_GLOBAL_INSTANCES) && !defined(NO_GLOBAL_SERIAL)
 #endif // HardwareSerial_h

cores/esp32/esp32-hal-uart.h

-// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+// Copyright 2015-2024 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.
@@ -24,83 +24,14 @@ extern "C" {
 #include <stdlib.h>
 #include "freertos/FreeRTOS.h"
 #include "freertos/queue.h"
-
-#ifdef __cplusplus
-enum SerialConfig {
-SERIAL_5N1 = 0x8000010,
-SERIAL_6N1 = 0x8000014,
-SERIAL_7N1 = 0x8000018,
-SERIAL_8N1 = 0x800001c,
-SERIAL_5N2 = 0x8000030,
-SERIAL_6N2 = 0x8000034,
-SERIAL_7N2 = 0x8000038,
-SERIAL_8N2 = 0x800003c,
-SERIAL_5E1 = 0x8000012,
-SERIAL_6E1 = 0x8000016,
-SERIAL_7E1 = 0x800001a,
-SERIAL_8E1 = 0x800001e,
-SERIAL_5E2 = 0x8000032,
-SERIAL_6E2 = 0x8000036,
-SERIAL_7E2 = 0x800003a,
-SERIAL_8E2 = 0x800003e,
-SERIAL_5O1 = 0x8000013,
-SERIAL_6O1 = 0x8000017,
-SERIAL_7O1 = 0x800001b,
-SERIAL_8O1 = 0x800001f,
-SERIAL_5O2 = 0x8000033,
-SERIAL_6O2 = 0x8000037,
-SERIAL_7O2 = 0x800003b,
-SERIAL_8O2 = 0x800003f
-};
-#else
-#define SERIAL_5N1 0x8000010
-#define SERIAL_6N1 0x8000014
-#define SERIAL_7N1 0x8000018
-#define SERIAL_8N1 0x800001c
-#define SERIAL_5N2 0x8000030
-#define SERIAL_6N2 0x8000034
-#define SERIAL_7N2 0x8000038
-#define SERIAL_8N2 0x800003c
-#define SERIAL_5E1 0x8000012
-#define SERIAL_6E1 0x8000016
-#define SERIAL_7E1 0x800001a
-#define SERIAL_8E1 0x800001e
-#define SERIAL_5E2 0x8000032
-#define SERIAL_6E2 0x8000036
-#define SERIAL_7E2 0x800003a
-#define SERIAL_8E2 0x800003e
-#define SERIAL_5O1 0x8000013
-#define SERIAL_6O1 0x8000017
-#define SERIAL_7O1 0x800001b
-#define SERIAL_8O1 0x800001f
-#define SERIAL_5O2 0x8000033
-#define SERIAL_6O2 0x8000037
-#define SERIAL_7O2 0x800003b
-#define SERIAL_8O2 0x800003f
-#endif // __cplusplus
-
-// These are Hardware Flow Contol possible usage
-// equivalent to UDF enum uart_hw_flowcontrol_t from 
-// https://github.com/espressif/esp-idf/blob/master/components/hal/include/hal/uart_types.h#L75-L81
-#define HW_FLOWCTRL_DISABLE   0x0       // disable HW Flow Control
-#define HW_FLOWCTRL_RTS       0x1       // use only RTS PIN for HW Flow Control
-#define HW_FLOWCTRL_CTS       0x2       // use only CTS PIN for HW Flow Control
-#define HW_FLOWCTRL_CTS_RTS   0x3       // use both CTS and RTS PIN for HW Flow Control
-
-// These are Hardware Uart Modes possible usage
-// equivalent to UDF enum uart_mode_t from
-// https://github.com/espressif/esp-idf/blob/master/components/hal/include/hal/uart_types.h#L34-L40
-#define MODE_UART 0x00                   // mode: regular UART mode
-#define MODE_RS485_HALF_DUPLEX 0x01      // mode: half duplex RS485 UART mode control by RTS pin
-#define MODE_IRDA 0x02                   // mode: IRDA  UART mode
-#define MODE_RS485_COLLISION_DETECT 0x03 // mode: RS485 collision detection UART mode (used for test purposes)
-#define MODE_RS485_APP_CTRL 0x04
+#include "hal/uart_types.h"
 
 struct uart_struct_t;
 typedef struct uart_struct_t uart_t;
 
+bool _testUartBegin(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);
 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); 
@@ -130,16 +61,30 @@ int uartGetDebug();
 
 bool uartIsDriverInstalled(uart_t* uart);
 
-// Negative Pin Number will keep it unmodified, thus this function can set/reset individual pins
+// 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);
-void uartDetachPins(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);
 
 // 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);
+//    UART_HW_FLOWCTRL_DISABLE = 0x0   disable hardware flow control
+//    UART_HW_FLOWCTRL_RTS     = 0x1   enable RX hardware flow control (rts)
+//    UART_HW_FLOWCTRL_CTS     = 0x2   enable TX hardware flow control (cts)
+//    UART_HW_FLOWCTRL_CTS_RTS = 0x3   enable hardware flow control
+bool uartSetHwFlowCtrlMode(uart_t *uart, uart_hw_flowcontrol_t mode, uint8_t threshold);
 
 // Used to set RS485 function -- needs to disable HW Flow Control and set RTS pin to use
 // RTS pin becomes RS485 half duplex RE/DE
-bool uartSetMode(uart_t *uart, uint8_t mode);
+//    UART_MODE_UART                   = 0x00    mode: regular UART mode
+//    UART_MODE_RS485_HALF_DUPLEX      = 0x01    mode: half duplex RS485 UART mode control by RTS pin
+//    UART_MODE_IRDA                   = 0x02    mode: IRDA  UART mode
+//    UART_MODE_RS485_COLLISION_DETECT = 0x03    mode: RS485 collision detection UART mode (used for test purposes)
+//    UART_MODE_RS485_APP_CTRL         = 0x04    mode: application control RS485 UART mode (used for test purposes)
+bool uartSetMode(uart_t *uart, uart_mode_t mode);
 
 void uartStartDetectBaudrate(uart_t *uart);
 unsigned long uartDetectBaudrate(uart_t *uart);