Skip to content

Commit

Permalink
docs(troubleshooting): Add info about debugging in USB-Serial/JTAG an…
Browse files Browse the repository at this point in the history
…d USB-OTG modes
  • Loading branch information
radimkarnis committed Sep 10, 2024
1 parent 0472846 commit 3a74f62
Showing 1 changed file with 7 additions and 4 deletions.
11 changes: 7 additions & 4 deletions docs/en/troubleshooting.rst
Original file line number Diff line number Diff line change
Expand Up @@ -106,14 +106,17 @@ Early Stage Crash

.. only:: not esp8266 and not esp32 and not esp32c2

Issues When Using USB-Serial/JTAG or USB-OTG
--------------------------------------------
Issues and Debugging in USB-Serial/JTAG or USB-OTG modes
--------------------------------------------------------

When working with ESP chips that implement a `USB-Serial/JTAG Controller <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/usb-serial-jtag-console.html>`_ or a `USB-OTG console <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/usb-otg-console.html>`_, it's essential to be aware of potential issues related to the loaded application interfering with or reprogramming the GPIO pins used for USB communication.
When working with ESP chips that implement a `USB-Serial/JTAG <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/usb-serial-jtag-console.html>`_ or a `USB-OTG <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/usb-otg-console.html>`_ console (you are not using a classic USB-to-Serial adapter), it's essential to be aware of potential issues related to the loaded application interfering with or reprogramming the GPIO pins used for USB communication.

If the application accidentally reconfigures the USB peripheral pins or disables the USB peripheral, the device disappears from the system. You can also encounter unstable flashing or errors like ``OSError: [Errno 71] Protocol error``.

If that happens, try :ref:`manually entering the download mode <manual-bootloader>` and then using the :ref:`erase_flash <erase_flash>` command to wipe the flash memory. Then, make sure to fix the issue in the application before flashing again.
If that happens, try to :ref:`manually enter the download mode <manual-bootloader>` and then use the :ref:`erase_flash <erase_flash>` command to wipe the flash memory. Then, make sure to fix the issue in the application before flashing again.

On boards with two USB ports (usually marked as USB and UART), you can use the USB port for flashing while listening on the UART port for debugging purposes. This setup is useful for retrieving core dumps or the reset reason in the event of a crash. To implement this, connect the UART port to another instance of any of the `serial terminal programs`_, while repeating the failing action over the USB port. You'll be able to monitor the crash log without interference from the USB port used for communication or it disappearing due to a firmware crash.
If your devkit doesn't have a dedicated USB port connected to an on-board USB-to-UART bridge, you can use a separate adapter to connect to the UART pins on the board.

Serial Terminal Programs
------------------------
Expand Down

0 comments on commit 3a74f62

Please sign in to comment.