diff --git a/docs/firmware/flash_esp.md b/docs/firmware/flash_esp.md index fae8c44..33b9df5 100644 --- a/docs/firmware/flash_esp.md +++ b/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 diff --git a/docs/firmware/webinstall.md b/docs/firmware/webinstall.md index 531ddc1..d20f922 100644 --- a/docs/firmware/webinstall.md +++ b/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). diff --git a/docs/hardware/esp32nodemcu_38pin.md b/docs/hardware/esp32nodemcu_38pin.md index 4c68ca6..8543489 100644 --- a/docs/hardware/esp32nodemcu_38pin.md +++ b/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 diff --git a/docs/hardware/esp32s3_devkit.md b/docs/hardware/esp32s3_devkit.md index 92d56f1..fa84c97 100644 --- a/docs/hardware/esp32s3_devkit.md +++ b/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 diff --git a/docs/hardware/limitations.md b/docs/hardware/limitations.md index d621e09..d9865d8 100644 --- a/docs/hardware/limitations.md +++ b/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.