From 3a74f62fe402402d39abb4f331512565b45ca7cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Radim=20Karni=C5=A1?= Date: Tue, 10 Sep 2024 14:40:27 +0200 Subject: [PATCH] docs(troubleshooting): Add info about debugging in USB-Serial/JTAG and USB-OTG modes --- docs/en/troubleshooting.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/en/troubleshooting.rst b/docs/en/troubleshooting.rst index ae5d2dec9..5f6fbead0 100644 --- a/docs/en/troubleshooting.rst +++ b/docs/en/troubleshooting.rst @@ -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 `_ or a `USB-OTG console `_, 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 `_ or a `USB-OTG `_ 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 ` and then using the :ref:`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 ` and then use the :ref:`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 ------------------------