clarify why UART0 should be avoided

docs/firmware/flash_esp.md

@@ -35,6 +35,14 @@ flash utility automatically, but sometimes that is not working.
       the power supply, possibly by plugging in the USB cable.
 3. Release the `BOOT` button.
 
+## Free UART0
+
+You must disconnect a peripheral from UART0 to flash the ESP32, as [UART0 is
+used](../hardware/limitations.md#using-uart0) to interact with the bootloader.
+
+Exception: An ESP32-S3 board is connected through the native USB port to the PC
+attempting to interact with the bootloader.
+
 ## Write to Flash Memory
 
 The actual procedure to flash the ESP32 depends on the tool used. Click on the

docs/firmware/webinstall.md

@@ -15,3 +15,4 @@ The WebFlasher is platform-independent, but requires the Chrome or Edge browser.
   erasing the flash memory and actually installing the firmware. This can help
   when a reset is performed in the preparation step, as holding the `BOOT`
   button ensures that the ESP32 restarts into bootloader mode.
+* Make sure to [disconnect peripherals from UART0](flash_esp.md#free-uart0).

docs/hardware/esp32nodemcu_38pin.md

@@ -3,7 +3,15 @@
 !!!note "Flash Memory"
     Get a version with at least 8 MB of flash memory to be able to use OTA updates.
 
-To use this board please refer to the [Device Profile](../firmware/device_profiles.md) called `nodemcu_esp32.json` or `blinkyparts_esp32.json`. Both are nicely compatible with the dev board. Open the JSON file with a text editor and have a look at the specific pin numbers.
+!!!warning "UART0"
+    Do **NOT** connect a peripheral to UART0 (GPIO1, GPIO3). [UART0 is
+    used](limitations.md#using-uart0) by the ESP32's bootloader and by the
+    firmware to print messages.
+
+To use this board please refer to the [Device
+Profile](../firmware/device_profiles.md) called `nodemcu_esp32.json` or
+`blinkyparts_esp32.json`. Both are nicely compatible with the dev board. Open
+the JSON file with a text editor and have a look at the specific pin numbers.
 
 ## Schematic
 

docs/hardware/esp32s3_devkit.md

@@ -5,15 +5,19 @@ to assemble your own hardware components. Have a look at the [user
 guide](https://docs.espressif.com/projects/esp-idf/en/stable/esp32s3/hw-reference/esp32s3/user-guide-devkitc-1.html).
 
 !!!note "Flash Memory"
-    The original boards by Espressig as well as the imitations should all have
+    The original boards by Espressif as well as the imitations should all have
     at least 8 MB of flash memory, making it possible to use OTA updates.
 
-!!!warning
+!!!warning "Reserved Pins"
     Modules with 8 MB of PSRAM or 16 MB or more of flash memory use an octal
     SPI interface. Pins GPIO35, GPIO36 and GPIO37 are used for the internal
     communication between ESP32-S3 and SPI flash/PSRAM memory, thus not
     available for external use.
 
+!!!warning "Avoid UART0"
+    Avoid using UART0 (GPIO43, GPIO44) to connect a peripheral, as it is
+    [reserved for the bootloader](limitations.md#using-uart0).
+
 ## Overview
 
 The following is an overview of the original Espressif ESP32-S3 DevKit (USB-C

docs/hardware/limitations.md

@@ -38,3 +38,41 @@ once all hardware UARTs are occupied, features/peripherals requiring a hardware
 UART will fail to initialize. Have a look at the output on the [serial
 console](../firmware/howto/serial_console.md) when booting to know how hardware
 UARTs are assigned.
+
+## Using UART0
+
+In general, avoid using UART0 to connect peripherals.
+
+* On ESP32, GPIO1 and GPIO3 are in use by UART0.
+* On ESP32-S3, GPIO43 and GPIO44 are in use by UART0.
+
+### Bootloader Interaction
+
+Connecting a peripheral to UART0 of your ESP32 can break interaction with the
+bootloader. The bootloader uses UART0 to communicate with the flash tool. A
+peripheral connected to UART0 might therefore interfere in the communication
+with the bootloader, preventing writing to the flash memory over USB in
+particular.
+
+* On ESP32 boards, UART0 is connected to the USB-UART bridge.
+* On ESP32-S3 boards with multiple USB ports, the port connected to the
+  USB-UART bridge on the USB side is connected to UART0 on the UART side
+  of the bridge.
+
+### Bootloader Output
+
+The ESP32's bootloader will print messages on UART0 on every boot. If a
+peripheral is connected to UART0, this peripheral will receive these messages.
+If the peripheral is not robust against invalid messages and, depending on the
+baud rate, invalid UART chararacters, it may cease to function properly.
+
+### Firmware Messages
+
+OpenDTU-OnBattery uses UART0 to print messages. These are the same messages
+appearing in the web console, except that connecting to UART0 allows to read
+messages even while the firmware is still booting and not yet connected to the
+network.
+
+On ESP32-S3 using firmware variant `generic_esp32s3_usb` (all environments that
+define `ARDUINO_USB_MODE=1` and `ARDUINO_USB_CDC_ON_BOOT=1`), the messages are
+instead available on the virtual serial interface of the native USB connection.