docs: align UART documentation with the current API

Signed-off-by: Frederic Pillon <frederic.pillon@st.com>

Author: fpistm

docs/API.md

@@ -132,7 +132,7 @@ An example that reads and converts the three internal channels and A0 is provide
 > [!WARNING]
 > This example is provided as-is and may require updates for device-specific datasheet values.
 
-### HardwareSerial
+### Uart
 
 STM32 MCUs have several _U(S)ART_ peripherals. For convenience, the _U(S)ART_**x** number is used to define the `Serialx` instance:
 
@@ -150,10 +150,10 @@ For _LPUART_ peripherals:
 
 **By default, only one `Serialx` instance is available mapped to the generic `Serial` name.**
 
-To use a second serial port, a `HardwareSerial` object should be declared in the sketch before the `setup()` function:
+To use a second serial port, a `Uart` object should be declared in the sketch before the `setup()` function:
 ```C++
 //                      RX    TX
-HardwareSerial Serial1(PA10, PA9);
+Uart Serial1(PA10, PA9);
 
 void setup() {
   Serial1.begin(115200);
@@ -196,8 +196,8 @@ Example for the `Serial3`:
 ##### Change default `Serial` instance pins
 It is also possible to change the default pins used by the `Serial` instance using above API:
 
-* `void setRx(uint32_t rx)`
-* `void setTx(uint32_t tx)`
+* `void setRx(pin_size_t rx)`
+* `void setTx(pin_size_t tx)`
 * `void setRx(PinName rx)`
 * `void setTx(PinName tx)`
 
@@ -215,17 +215,17 @@ It is also possible to change the default pins used by the `Serial` instance usi
 
 Available in core version greater than **1.7.0**
 
-It is now possible to set a `HardwareSerial` in half-duplex mode.
+It is now possible to set a `Uart` in half-duplex mode.
 
 The `U(S)ART` can be configured to follow a single-wire half-duplex protocol where the Tx and Rx lines are internally connected. In this communication mode, only the Tx pin is used for both transmission and reception.
 
-* Extended `HardwareSerial` constructors:
-  * `HardwareSerial(uint32_t _rxtx)`: U(S)ART Tx pin number (`PYn`) used for half-duplex
-  * `HardwareSerial(PinName _rxtx)`: U(S)ART Tx pin name (`PY_n`) used for half-duplex
+* Extended `Uart` constructors:
+  * `Uart(pin_size_t _rxtx)`: U(S)ART Tx pin number (`PYn`) used for half-duplex
+  * `Uart(PinName _rxtx)`: U(S)ART Tx pin name (`PY_n`) used for half-duplex
   * if `Rx == Tx` then assume half-duplex mode:
-    * `HardwareSerial(uint32_t _rx, uint32_t _tx)`: U(S)ART Tx pin number (`PYn`) used for half-duplex
-    * `HardwareSerial(PinName _rx, PinName tx)`: U(S)ART Tx pin name (`PY_n`) used for half-duplex
-  * `HardwareSerial(void *peripheral, HalfDuplexMode_t halfDuplex = HALF_DUPLEX_DISABLED)`: if `HALF_DUPLEX_ENABLED` get the first Tx pin for requested peripheral in the` PeripheralPins.c` used for half-duplex
+    * `Uart(pin_size_t _rx, pin_size_t _tx)`: U(S)ART Tx pin number (`PYn`) used for half-duplex
+    * `Uart(PinName _rx, PinName tx)`: U(S)ART Tx pin name (`PY_n`) used for half-duplex
+  * `Uart(void *peripheral, HalfDuplexMode_t halfDuplex = HALF_DUPLEX_DISABLED)`: if `HALF_DUPLEX_ENABLED` get the first Tx pin for requested peripheral in the` PeripheralPins.c` used for half-duplex
 
 * Add `enableHalfDuplexRx()` to enable Serial in Rx mode. Doing a `read()` could be used but will avoid to perform a read. Useful before `available()` usage
 * `void setHalfDuplex()`: enable half-duplex mode of an instance when it not instantiate in half-duplex mode. Must be call before `begin()` in this case.
@@ -237,26 +237,26 @@ Require to connect `PA0` and` PB10`.
 _All possible constructor are listed._
 
 ```C++
-HardwareSerial Serial3(PA0);
-HardwareSerial Serial4(PB10);
+Uart Serial3(PA0);
+Uart Serial4(PB10);
 
-//HardwareSerial Serial3(PA_0);
-//HardwareSerial Serial4(PB_10);
+//Uart Serial3(PA_0);
+//Uart Serial4(PB_10);
 
-//HardwareSerial Serial3(UART4, HALF_DUPLEX_ENABLED);
-//HardwareSerial Serial4(USART3, HALF_DUPLEX_ENABLED);
+//Uart Serial3(UART4, HALF_DUPLEX_ENABLED);
+//Uart Serial4(USART3, HALF_DUPLEX_ENABLED);
 
-//HardwareSerial Serial3(PA0, PA0);
-//HardwareSerial Serial4(PB10, PB10);
+//Uart Serial3(PA0, PA0);
+//Uart Serial4(PB10, PB10);
 
-//HardwareSerial Serial3(PA_0, PA_0);
-//HardwareSerial Serial4(PB_10, PB_10);
+//Uart Serial3(PA_0, PA_0);
+//Uart Serial4(PB_10, PB_10);
 
-//HardwareSerial Serial3(NC, PA_0);
-//HardwareSerial Serial4(NC, PB_10);
+//Uart Serial3(NC, PA_0);
+//Uart Serial4(NC, PB_10);
 
-//HardwareSerial Serial3(NUM_DIGITAL_PINS, PA0);
-//HardwareSerial Serial4(NUM_DIGITAL_PINS, PB10);
+//Uart Serial3(NUM_DIGITAL_PINS, PA0);
+//Uart Serial4(NUM_DIGITAL_PINS, PB10);
 
 static uint32_t nbTestOK = 0;
 static uint32_t nbTestKO = 0;
@@ -331,13 +331,13 @@ void loop() {
 
 Available in core version **2.3.0** or later
 
-* `HardwareSerial` constructors accept optional RTS/CTS pins:
-  * `HardwareSerial(uint32_t _rx, uint32_t _tx, uint32_t _rts = NUM_DIGITAL_PINS, uint32_t _cts = NUM_DIGITAL_PINS)`
-  * `HardwareSerial(PinName _rx, PinName _tx, PinName _rts = NC, PinName _cts = NC)`
-* You can also enable RTS/CTS pins on `HardwareSerial` instances:
-  * `void setRts(uint32_t _rts)`
-  * `void setCts(uint32_t _cts)`
-  * `void setRtsCts(uint32_t _rts, uint32_t _cts)`
+* `Uart` constructors accept optional RTS/CTS pins:
+  * `Uart(pin_size_t _rx, pin_size_t _tx, pin_size_t _rts = NUM_DIGITAL_PINS, pin_size_t _cts = NUM_DIGITAL_PINS)`
+  * `Uart(PinName _rx, PinName _tx, PinName _rts = NC, PinName _cts = NC)`
+* You can also enable RTS/CTS pins on `Uart` instances:
+  * `void setRts(pin_size_t _rts)`
+  * `void setCts(pin_size_t _cts)`
+  * `void setRtsCts(pin_size_t _rts, pin_size_t _cts)`
   * `void setRts(PinName _rts)`
   * `void setCts(PinName _cts)`
   * `void setRtsCts(PinName _rts, PinName _cts)`
@@ -346,10 +346,10 @@ Available in core version **2.3.0** or later
 
 ```C++
 // Enable hardware flow control on construction.
-HardwareSerial serial(PA10, PA9, PA12, PA11);
+Uart serial(PA10, PA9, PA12, PA11);
 
 // Or, enable later (but before calling begin()).
-HardwareSerial serial(PA10, PA9);
+Uart serial(PA10, PA9);
 serial.setRtsCts(PA12, PA11);
 serial.begin(460800);
 ```
@@ -361,10 +361,10 @@ Available in core version greater than **2.10.1**
 The U(S)ART Tx and Rx pin signal values can be inverted (VDD = 0/mark, Gnd = 1/idle), and the U(S)ART can send and receive data in negative/inverse logic (1 = L, 0 = H); the
 parity bit is also inverted.
 
-* Enable Tx and Rx active level inversion on `HardwareSerial` instances, respectively:
+* Enable Tx and Rx active level inversion on `Uart` instances, respectively:
   * `void setTxInvert(void)`
   * `void setRxInvert(void)`
-* Enable data inversion on `HardwareSerial` instances:
+* Enable data inversion on `Uart` instances:
   * `void setDataInvert(void)`
 
 ### HardwareTimer library

docs/Pin-naming.md

@@ -17,6 +17,8 @@ Serial.begin(9600);
 
 Arduino functions such as `pinMode()` and `digitalWrite()` normally use the digital pin numbering defined by the selected board variant. The variant may also define aliases such as `PA0`, `PB7`, `A0`, or `LED_BUILTIN`. These aliases are board-specific and can map to Arduino digital numbers; they are not interchangeable with the `PinName` constant `PA_0`.
 
+`digitalRead()` returns a `PinStatus` value (`HIGH` or `LOW`).
+
 For example, a variant may map `PA0` to `PIN_A0`, while another maps a port-pin alias to a different digital pin number. Use the aliases and labels documented for the selected board:
 
 ```cpp
@@ -126,7 +128,7 @@ Internal ADC channels are different from external analog inputs. When supported
 Use the underscore form when a constructor or function expects a `PinName`. For example, these peripheral instances use the physical STM32 pins directly:
 
 ```cpp
-HardwareSerial Serial3(PA_10, PA_9); // RX, TX
+Uart Serial3(PA_10, PA_9);          // RX, TX
 TwoWire Wire2(PB_9, PB_8);           // SDA, SCL
 ```
 
@@ -139,7 +141,7 @@ Some board variants define names such as `PA2_ALT1` in addition to the default r
 For example, an alternate pin can be passed to a peripheral constructor when the variant provides that route:
 
 ```cpp
-HardwareSerial Serial2(PA2_ALT1, PA3_ALT1); // Only if defined by the variant
+Uart Serial2(PA2_ALT1, PA3_ALT1); // Only if defined by the variant
 ```
 
 Check `PeripheralPins.c` before using an `_ALT1` or similar name; the name alone does not guarantee that the requested peripheral supports that route. An unsupported route can prevent the peripheral from being configured correctly.

docs/Tools-menu.md

@@ -10,7 +10,7 @@ Menu: "**Tools > U(S)ART support**"
 | Option | Description |
 |--------|-------------|
 | Enabled (generic 'Serial') | U(S)ART support is enabled and the generic `Serial` object is available. It is mapped to the board's default serial interface (e.g. the ST-LINK virtual COM port on Nucleo boards). |
-| Enabled (no generic 'Serial') | U(S)ART support is enabled (`-DHAL_UART_MODULE_ENABLED -DHWSERIAL_NONE`) but the generic `Serial` is not defined. Instances have to be created by the user (e.g. `HardwareSerial Serial2(PA3, PA2);`). |
+| Enabled (no generic 'Serial') | U(S)ART support is enabled (`-DHAL_UART_MODULE_ENABLED -DHWSERIAL_NONE`) but the generic `Serial` is not defined. Instances have to be created by the user (e.g. `Uart Serial2(PA3, PA2);`). |
 | Disabled (No Serial support) | U(S)ART support is disabled. Reduces the code size when serial is not used. |
 
 ## USB support

doxygen/mainpage.md

@@ -11,7 +11,7 @@ sidebar to switch between the development (`dev`) and the released versions.
 
 ## Where to start
 
-- [Classes](annotated.html): classes and structures such as `HardwareTimer`, `HardwareSerial` or `TwoWire`.
+- [Classes](annotated.html): classes and structures such as `HardwareTimer`, `Uart` or `TwoWire`.
 - [Files](files.html): browse the documented source files.
 - [Functions](globals_func.html): documented C functions.
 

keywords.txt

@@ -266,7 +266,7 @@ PIN_WIRE_SDA	LITERAL1
 PIN_WIRE_SCL	LITERAL1
 
 # Serial
-HardwareSerial	KEYWORD2
+Uart	KEYWORD2
 setRx	KEYWORD2
 setTx	KEYWORD2
 HALF_DUPLEX_DISABLED	LITERAL1

variants/STM32L0xx/L072R(B-Z)T_L073R(B-Z)T_L083R(B-Z)T/variant_PX_HER0.h

@@ -196,7 +196,7 @@
 
 // Optional PIN_SERIALn_RX and PIN_SERIALn_TX where 'n' is the U(S)ART number
 // Used when user instantiate a hardware Serial using its peripheral name.
-// Example: HardwareSerial mySerial(USART3);
+// Example: Uart mySerial(USART3);
 // will use PIN_SERIAL3_RX and PIN_SERIAL3_TX if defined.
 #define ENABLE_HWSERIAL1
 #ifndef PIN_SERIAL1_RX

variants/STM32L4xx/L433C(B-C)(T-U)_L443CC(T-U)/variant_CYGNET.h

@@ -212,7 +212,7 @@
 
 // Virtual COM Port for Cygnet with a 14-pin STLink Connector mounted.
 // To use the STLINK's Virtual COM port, add the following line to an Arduino project:
-//     HardwareSerial SerialVCP(PIN_VCP_RX, PIN_VCP_TX);
+//     Uart SerialVCP(PIN_VCP_RX, PIN_VCP_TX);
 #ifndef PIN_VCP_RX
   #define PIN_VCP_RX              PIN_SERIAL_LP1_RX
 #endif

variants/STM32L4xx/L4R5Z(G-I)Y_L4R9Z(G-I)Y_L4S5ZIY_L4S9ZIY/variant_SWAN_R5.h

@@ -261,7 +261,7 @@
 
 // Virtual COM Port for Swans with a 14-pin STLink Connector mounted.
 // To use the STLINK's Virtual COM port, this would be added to an Arduino project:
-//     HardwareSerial SerialVCP(PIN_VCP_RX, PIN_VCP_TX);
+//     Uart SerialVCP(PIN_VCP_RX, PIN_VCP_TX);
 #ifndef PIN_VCP_RX
   #define PIN_VCP_RX              PIN_SERIAL_LP1_RX
 #endif

variants/STM32U5xx/U575O(G-I)YxQ_U585OIYxQ/variant_HERON.h

@@ -275,7 +275,7 @@
 
 // Virtual COM Port for Heron with a 14-pin STLink Connector mounted.
 // To use the STLINK's Virtual COM port, add the following line to an Arduino project:
-//     HardwareSerial SerialVCP(PIN_VCP_RX, PIN_VCP_TX);
+//     Uart SerialVCP(PIN_VCP_RX, PIN_VCP_TX);
 #ifndef PIN_VCP_RX
   #define PIN_VCP_RX              PIN_SERIAL3_RX
 #endif