From 826e9674d89ac42f3a8e84da5dbf598221adc7e8 Mon Sep 17 00:00:00 2001 From: Roland Dobai Date: Mon, 10 May 2021 15:27:12 +0200 Subject: [PATCH 1/2] docs: Suggest how to use JTAG for ESP32-C3 on Windows --- .../api-guides/jtag-debugging/configure-builtin-jtag.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/en/api-guides/jtag-debugging/configure-builtin-jtag.rst b/docs/en/api-guides/jtag-debugging/configure-builtin-jtag.rst index 16074103e9..0ff04e4f6a 100644 --- a/docs/en/api-guides/jtag-debugging/configure-builtin-jtag.rst +++ b/docs/en/api-guides/jtag-debugging/configure-builtin-jtag.rst @@ -32,5 +32,10 @@ Please verify that the {IDF_TARGET_NAME} pins used for USB communication are not Configure USB Drivers ^^^^^^^^^^^^^^^^^^^^^ -JTAG communication should work out-of-box on Linux and macOS. Windows users might get `LIBUSB_ERROR_NOT_FOUND` errors. -This is a known issue and will be addressed soon. +JTAG communication should work on all supported platforms. Windows users might get `LIBUSB_ERROR_NOT_FOUND` errors. +Please use version 2.8 (or newer) of the :ref:`get-started-windows-tools-installer` and select the driver +"Espressif - WinUSB support for JTAG (ESP32-C3)" in order to resolve this issue. If you don't want to re-run the +installer then the same can be achieved with `idf-env `_ by running the +following command from PowerShell:: + + Invoke-WebRequest 'https://dl.espressif.com/dl/idf-env/idf-env.exe' -OutFile .\idf-env.exe; .\idf-env.exe driver install --espressif From c68781c269be26cebff57825a95b6a6da7f9393d Mon Sep 17 00:00:00 2001 From: Roland Dobai Date: Mon, 10 May 2021 16:19:20 +0200 Subject: [PATCH 2/2] docs: Generate JTAG debugging guide based on feature instead of chip It is better to check feature SOC_USB_SERIAL_JTAG_SUPPORTED which will support other chip targets beside ESP32-C3. --- docs/en/api-guides/jtag-debugging/index.rst | 14 ++++++++------ docs/zh_CN/api-guides/jtag-debugging/index.rst | 2 +- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst index b08ca4bba3..1ba519de07 100644 --- a/docs/en/api-guides/jtag-debugging/index.rst +++ b/docs/en/api-guides/jtag-debugging/index.rst @@ -66,17 +66,19 @@ Under "Application Loading and Monitoring" there is another software and hardwar Debugging using JTAG and application loading / monitoring is integrated under the `Eclipse `_ environment, to provide quick and easy transition from writing, compiling and loading the code to debugging, back to writing the code, and so on. All the software is available for Windows, Linux and MacOS platforms. -.. only:: not esp32c3 +.. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED If the |devkit-name-with-link| is used, then connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the FT2232H chip, which provides two USB channels, one for JTAG and the one for UART connection. -.. only:: esp32c3 +.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED The connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the {IDF_TARGET_NAME} chip itself, which provides two USB channels, one for JTAG and one for the USB terminal connection. The USB cable should be connected the D+/D- USB pins of {IDF_TARGET_NAME} and not to the serial RxD/TxD throught an USB-to-UART chip. The proper connection is explained later in subsection :ref:`jtag-debugging-configuring-target`. +.. only:: esp32c3 + .. note:: - Debugging through the USB interface implemented in {IDF_TARGET_NAME} requires to have a chip with revision 3 or newer. Please use other debugging options (e.g. with ESP-Prog) for chip revision 1 and 2. The easiest way to determine the chip revision is to look for the `Chip is ESP32-C3 (revision 3)` message near the end of a successful chip flashing done by `idf.py flash`. + Debugging through the USB interface implemented in ESP32-C3 requires to have a chip with revision 3 or newer. Please use other debugging options (e.g. with ESP-Prog) for chip revision 1 and 2. The easiest way to determine the chip revision is to look for the `Chip is ESP32-C3 (revision 3)` message near the end of a successful chip flashing done by `idf.py flash`. Depending on user preferences, both `debugger` and `idf.py build` can be operated directly from terminal/command line, instead from Eclipse. @@ -86,11 +88,11 @@ Depending on user preferences, both `debugger` and `idf.py build` can be operate Selecting JTAG Adapter ---------------------- -.. only:: not esp32c3 +.. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED The quickest and most convenient way to start with JTAG debugging is by using |devkit-name-with-link|. Each version of this development board has JTAG interface already built in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. |devkit-name| is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter. -.. only:: esp32c3 +.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED The quickest and most convenient way to start with JTAG debugging is through an USB cable connected to the D+/D- USB pins of {IDF_TARGET_NAME}. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. @@ -152,7 +154,7 @@ This step depends on JTAG and {IDF_TARGET_NAME} board you are using - see the tw :esp32: configure-ft2232h-jtag :esp32s2: configure-ft2232h-jtag - :esp32c3: configure-builtin-jtag + :SOC_USB_SERIAL_JTAG_SUPPORTED: configure-builtin-jtag configure-other-jtag diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst index 6671432a21..faf74c79fa 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -135,7 +135,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G :esp32: configure-ft2232h-jtag :esp32s2: configure-ft2232h-jtag - :esp32c3: configure-builtin-jtag + :SOC_USB_SERIAL_JTAG_SUPPORTED: configure-builtin-jtag configure-other-jtag