From fea3671c7c3911fa12868726fb0248851cbac1e2 Mon Sep 17 00:00:00 2001
From: Keith Burzinski <kbx81x@gmail.com>
Date: Tue, 19 Dec 2023 20:45:10 -0600
Subject: [PATCH] Update logger component docs for new USB support (#3469)

---
 components/logger.rst | 110 +++++++++++++++++++++++++++++++++++-------
 1 file changed, 93 insertions(+), 17 deletions(-)

diff --git a/components/logger.rst b/components/logger.rst
index 95d420962..4db85eb2c 100644
--- a/components/logger.rst
+++ b/components/logger.rst
@@ -35,8 +35,8 @@ Advanced settings:
 -  **tx_buffer_size** (*Optional*, int): The size of the buffer used
    for log messages. Decrease this if you’re having memory problems.
    Defaults to ``512``.
--  **hardware_uart** (*Optional*, string): The Hardware UART to use for logging.
-   Defaults to ``UART0``.
+-  **hardware_uart** (*Optional*, string): The Hardware UART to use for logging. The default varies depending on
+   the specific processor/chip and framework you are using. See the :ref:`table below <logger-default_hardware_interfaces>`.
 -  **esp8266_store_log_strings_in_flash** (*Optional*, boolean): If set to false, disables storing
    log strings in the flash section of the device (uses more memory). Defaults to true.
 -  **on_message** (*Optional*, :ref:`Automation <automation>`): An action to be
@@ -52,23 +52,99 @@ Advanced settings:
 Hardware UARTs
 --------------
 
-The logger component makes use of platform-specific hardware UARTs for serial logging.
-By default, the logger will occupy ``UART0``. The ESP32 has three hardware UARTs, all of
-which can be used for both transmit and receive. The ESP8266 only has two hardware UARTs,
-one of which is transmit-only. The ESP8266 ``UART0`` can also be 'swapped' to TX/RX on the
-CTS/RTS pins, if you need to use GPIO1 and GPIO3 for something else. Note that the common
-NodeMCU boards have their USB-UART Adapters fixed to the default GPIOs used by ``UART0``,
-so if you use anything else you will not get log messages over the on-board USB.
+The logger component makes use of platform-specific hardware UARTs for serial logging. For example, the ESP32
+has three hardware UARTs, all of which can be used for both transmit and receive. The ESP8266 only has two
+hardware UARTs, one of which is transmit-only. The ESP8266's ``UART0`` can also be "swapped" to TX/RX on the
+CTS/RTS pins in the event that you need to use GPIO1 and GPIO3 for something else.
 
-Possible Hardware UART configurations:
+Note that many common boards have their USB-to-serial adapters fixed to the default GPIOs used by ``UART0``,
+so if you use any other configuration you will not get log messages over the on-board USB.
 
-- ``UART0`` - TX: GPIO1, RX: GPIO3
-- ``UART0_SWAP`` - TX: GPIO15, RX: GPIO13  (Only on ESP8266)
-- ``UART1`` - TX: GPIO2, RX: None  (Only on ESP8266)
-- ``UART1`` - TX: GPIO9, RX: GPIO10  (Only on ESP32)
-- ``UART2`` - TX: GPIO16, RX: GPIO17  (Only on ESP32 but not ESP32S2, ESP32S3 or ESP32C3)
-- ``USB_CDC`` - uses the USB CDC driver (Only on ESP32S2 and ESP32S3)
-- ``USB_SERIAL_JTAG`` - uses the USB Serial/JTAG driver (Only on ESP32S3 and ESP32C3)
+Default UART GPIO Pins
+**********************
+
+.. list-table::
+    :header-rows: 1
+
+    * - 
+      - ``UART0``
+      - ``UART0_SWAP``
+      - ``UART1``
+      - ``UART2``
+      - ``USB_CDC``
+      - ``USB_SERIAL_JTAG``
+    * - ESP8266
+      - TX: 1, RX: 3
+      - TX: 15, RX: 13
+      - TX: 2, RX: N/A
+      - N/A
+      - N/A
+      - N/A
+    * - ESP32
+      - TX: 1, RX: 3
+      - N/A
+      - TX: 9, RX: 10
+      - TX: 16, RX: 17
+      - N/A
+      - N/A
+    * - ESP32-C3
+      - TX: 21, RX: 20
+      - N/A
+      - Undefined
+      - N/A
+      - N/A
+      - 18/19
+    * - ESP32-S2
+      - TX: 43, RX: 44
+      - N/A
+      - TX: 17, RX: 18
+      - N/A
+      - 19/20
+      - N/A
+    * - ESP32-S3
+      - TX: 43, RX: 44
+      - N/A
+      - TX: 17, RX: 18
+      - Undefined
+      - 19/20
+      - 19/20
+
+*Undefined* means that the logger component cannot use this harware UART at this time.
+
+.. _logger-default_hardware_interfaces:
+
+Default Hardware Interfaces
+---------------------------
+
+Because of the wide variety of boards and processors/chips available, we've selected varying default
+hardware interfaces for logging. Many newer boards based on ESP32 variants (such as the C3, S2 and S3)
+are using the ESP's on-board USB hardware peripheral while boards based on older processors (such as
+the original ESP32 or ESP8266) continue to use USB-to-serial bridge ICs for communication.
+
+.. list-table::
+    :header-rows: 1
+
+    * - 
+      - Arduino
+      - ESP-IDF
+    * - ESP8266
+      - ``UART0``
+      - N/A
+    * - ESP32
+      - ``UART0``
+      - ``UART0``
+    * - ESP32-C3
+      - ``USB_CDC``
+      - ``USB_SERIAL_JTAG``
+    * - ESP32-S2
+      - ``USB_CDC``
+      - ``USB_CDC``
+    * - ESP32-S3
+      - ``USB_CDC``
+      - ``USB_SERIAL_JTAG``
+    * - RP2040
+      - ``USB_CDC``
+      - N/A
 
 .. _logger-log_levels: