Merge branch 'docs_add_usb_flash_procedure' into 'master'

[Docs] Added procedures for the USB peripheral flashing

See merge request espressif/esp-idf!18484

docs/en/get-started/establish-serial-connection.rst

@@ -3,20 +3,187 @@ Establish Serial Connection with {IDF_TARGET_NAME}
 
 :link_to_translation:`zh_CN:[中文]`
 
-This section provides guidance how to establish serial connection between {IDF_TARGET_NAME} and PC.
+.. only:: not SOC_USB_OTG_SUPPORTED and not SOC_USB_SERIAL_JTAG_SUPPORTED
 
+    Establishing a serial connection with the {IDF_TARGET_NAME} target device could be done using a USB-to-UART bridge. 
+
+.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
+
+    Establishing a serial connection with the {IDF_TARGET_NAME} target device could be done using USB-to-UART bridge or USB peripheral supported in {IDF_TARGET_NAME}.
+
+Some development boards have the USB-to-UART bridge installed. If a board does not have a bridge then an external bridge may be used.
+
+.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
+
+    Supported USB Peripheral
+    ------------------------
+
+    The {IDF_TARGET_NAME} supports the USB peripheral. In this case, the USB-to-UART bridge is not needed and the device can be flashed directly.
+
+    .. blockdiag::
+        :scale: 70%
+        :caption: SoC with Supported USB
+        :align: center
+
+        blockdiag usb_capable_esp {
+
+            node_height = 80;
+            span_width = 160;
+            span_height = 140;
+            default_fontsize = 16
+
+            # labels of diagram nodes
+            PC [label="Personal\n Computer"];  
+            CHIP [label="{IDF_TARGET_NAME}", width=120];
+            DUMMY [shape=none, width=1]
+
+
+                # node connections
+                PC  <- DUMMY [label = "USB", fontsize=14];
+                DUMMY -> CHIP [fontsize=14];
+
+                group {
+                    shape = line;
+                    style = dotted;
+                    color = "#FF0000";
+                    label = "Development Board\n\n\n";
+                    CHIP; DUMMY;
+                }
+
+        }
+
+    Apart from the USB peripheral, some development boards also include the USB-to-UART bridge.
+
+USB-to-UART Bridge on Development Board
+---------------------------------------
+
+For boards with an installed USB-to-UART bridge, the connection between the personal computer and the bridge is USB and between the bridge and {IDF_TARGET_NAME} is UART.
+
+.. blockdiag::
+    :caption: Development Board with USB-to-UART Bridge
+    :align: center
+
+    blockdiag esp_dev_board_with_usb_to_uart_bridge {
+
+        node_height = 80;
+        span_width = 160;
+        span_height = 140;
+        default_fontsize = 16
+
+        # labels of diagram nodes
+        PC [label="Personal\nComputer"];  
+        BRIDGE [label="USB-to-UART\n Bridge"];  
+        CHIP [label="{IDF_TARGET_NAME}", width=120];
+
+            # node connections
+            PC <-> BRIDGE [label = "USB", fontsize=14];
+            BRIDGE <-> CHIP [label = "UART", fontsize=14];
+
+            group {
+                shape = line;
+                style = dotted;
+                color = "#FF0000";
+                label = "Developmment Board\n\n\n";
+                BRIDGE; CHIP;
+            }
+    }
+
+
+External USB-to-UART Bridge
+---------------------------
+
+Sometimes the USB-to-UART bridge is external. This is often used in small development boards or finished products when space and costs are crucial.
+
+.. blockdiag::
+    :caption: External USB-to-UART Bridge
+    :align: center
+
+    blockdiag external_usb_to_uart_bridge_to_esp {
+
+        node_height = 80;
+        span_width = 160;
+        span_height = 140;
+        default_fontsize = 16
+
+        # labels of diagram nodes
+        PC [label="Personal\n Computer"];  
+        BRIDGE [label="USB-to-UART\n Bridge", width=180];  
+        CHIP [label="{IDF_TARGET_NAME}", width=120];
+        DUMMY [shape=none, width=1]
+
+
+            # node connections
+            PC <-> BRIDGE [label = "USB", fontsize=14];
+            BRIDGE <- DUMMY [label = "UART", fontsize=14];
+            DUMMY -> CHIP [fontsize=14];
+
+            group {
+                shape = line;
+                style = dotted;
+                color = "#FF0000";
+                label = "Programmmer Board\n\n\n";
+                BRIDGE
+            }
+            group {
+                shape = line;
+                style = dotted;
+                color = "#FF0000";
+                label = "Development Board\n\n\n";
+                CHIP; DUMMY;
+            }
+    }
+
+
+.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
+
+    Flash using USB
+    ---------------
+
+    For the {IDF_TARGET_NAME}, the USB peripheral is available, allowing you to flash the binaries without the need for an external USB-to-UART bridge.
+
+    {IDF_TARGET_USB_PIN_DM:default="Not Updated!", esp32c3="GPIO18", esp32s3="GPIO19", esp32s2="GPIO19"}
+    {IDF_TARGET_USB_PIN_DP:default="Not Updated!", esp32c3="GPIO19", esp32s3="GPIO20", esp32s2="GPIO20"}
+
+    The USB on the {IDF_TARGET_NAME} uses the **{IDF_TARGET_USB_PIN_DP}** for **D+** and **{IDF_TARGET_USB_PIN_DM}** for **D-**.
+
+    .. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
+
+        .. note:: The {IDF_TARGET_NAME} supports only *USB CDC and JTAG*.
+
+        If you are flashing for the first time, you need to get the {IDF_TARGET_NAME} into the download mode manually. To do so, press and hold the ``BOOT`` button and then press the ``RESET`` button once. After that release the ``BOOT`` button.
+
+    .. only:: esp32s2
+
+        After flashing the binaries, a manual reset is needed.
+
+Flash using UART
+----------------
+
+This section provides guidance on how to establish a serial connection between {IDF_TARGET_NAME} and PC using USB-to-UART Bridge, either installed on the development board or external.
 
 Connect {IDF_TARGET_NAME} to PC
-----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Connect the {IDF_TARGET_NAME} board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your {IDF_TARGET_NAME} board (or external converter dongle), search for drivers in internet and install them.
+Connect the {IDF_TARGET_NAME} board to the PC using the USB cable. If device driver does not install automatically, identify USB-to-UART bridge on your {IDF_TARGET_NAME} board (or external converter dongle), search for drivers in internet and install them.
 
 Below is the list of USB to serial converter chips installed on most of the {IDF_TARGET_NAME} boards produced by Espressif together with links to the drivers:
 
 * CP210x: `CP210x USB to UART Bridge VCP Drivers <https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers>`_
 * FTDI: `FTDI Virtual COM Port Drivers <https://ftdichip.com/drivers/vcp-drivers/>`_
 
-Please check the board user guide for specific USB to serial converter chip used. The drivers above are primarily for reference. Under normal circumstances, the drivers should be bundled with an operating system and automatically installed upon connecting the board to the PC.
+Please check the board user guide for specific USB-to-UART bridge chip used. The drivers above are primarily for reference. Under normal circumstances, the drivers should be bundled with an operating system and automatically installed upon connecting the board to the PC.
+
+For devices downloaded using a USB-to-UART bridge, you can run the following command including the optional argument to define the baud rate.
+
+.. code-block:: bash
+
+    idf.py -p PORT [-b BAUD] flash
+
+You can change the flasher baud rate by replacing ``BAUD`` with the baud rate you need. The default baud rate is ``460800``.
+
+.. note::
+
+    If the device does not support the auto download mode, you need to get into the download mode manually. To do so, press and hold the ``BOOT`` button and then press the ``RESET`` button once. After that release the ``BOOT`` button.
 
 Check port on Windows
 ---------------------
@@ -39,7 +206,6 @@ Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT
 
     Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
 
-
 Check port on Linux and macOS
 -----------------------------
 
@@ -57,7 +223,6 @@ macOS ::
 
     macOS users: if you don't see the serial port then check you have the USB/serial drivers installed. See Section `Connect {IDF_TARGET_NAME} to PC`_ for links to drivers. For macOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI.
 
-
 .. _linux-dialout-group:
 
 Adding user to ``dialout`` on Linux
@@ -73,7 +238,6 @@ on Arch Linux this is done by adding the user to ``uucp`` group with the followi
 
 Make sure you re-login to enable read and write permissions for the serial port.
 
-
 Verify serial connection
 ------------------------
 
@@ -100,15 +264,14 @@ Run terminal, set identified serial port, baud rate = 115200, data bits = 8, sto
 
     Setting Serial Communication in PuTTY on Linux
 
-
 Then open serial port in terminal and check, if you see any log printed out by {IDF_TARGET_NAME}. The log contents will depend on application loaded to {IDF_TARGET_NAME}, see `Example Output`_.
 
 .. note::
 
    Close the serial terminal after verification that communication is working. If you keep the terminal session open, the serial port will be inaccessible for uploading firmware later.
 
 macOS
-^^^^^^^^
+^^^^^
 
 To spare you the trouble of installing a serial terminal program, macOS offers the **screen** command.
 
@@ -132,7 +295,6 @@ To spare you the trouble of installing a serial terminal program, macOS offers t
 
    Do not forget to **exit the screen session** after verifying that the communication is working. If you fail to do it and just close the terminal window, the serial port will be inaccessible for uploading firmware later.
 
-
 Example Output
 ^^^^^^^^^^^^^^
 
@@ -158,7 +320,6 @@ An example log is shown below. Reset the board if you do not see anything.
     entry 0x40080034
     I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader
     I (45) boot: compile time 18:48:10
-
     ...
 
 If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to {IDF_TARGET_NAME}.

docs/en/get-started/flashing-troubleshooting.rst

@@ -0,0 +1,24 @@
+Flashing Troubleshooting
+========================
+
+:link_to_translation:`zh_CN:[中文]`
+
+Failed to Connect
+-----------------
+
+{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9"}
+
+If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is to manually reset as described below. If it does not help, you can find more details about possible issues in the `esptool troubleshooting <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ page.
+
+``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB-to-UART bridge, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
+
+In general, you should have no problems with the `official esp-idf development boards <https://www.espressif.com/en/products/devkits>`_. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases:
+
+- Your hardware does not have the DTR and RTS lines connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU``.
+- The DTR and RTS lines are configured differently.
+- There are no such serial control lines at all.
+
+Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset).
+
+- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an ESP-IDF development board, hold down the ``Boot`` button (``{IDF_TARGET_STRAP_GPIO}``) and press the ``EN`` button (``CHIP_PU``).
+- For other types of hardware, try pulling ``{IDF_TARGET_STRAP_GPIO}`` down.

docs/en/get-started/linux-macos-setup.rst

@@ -284,6 +284,7 @@ Related Documents
     :maxdepth: 1
 
     establish-serial-connection
+    flashing-troubleshooting
     ../api-guides/tools/idf-monitor
 
 .. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository

docs/en/get-started/linux-macos-start-project.rst

@@ -76,3 +76,20 @@ You are using this menu to set up project specific variables, e.g., Wi-Fi networ
 .. only:: esp32 or esp32s2 or esp32s3
 
     If you are using one of the supported development boards, you can speed up your development by using Board Support Package. See `Additional Tips <#additional-tips>`__ for more information.
+
+.. only:: esp32s2
+
+    Console Output Configuration
+    ----------------------------
+
+    If you are using the USB for flashing the {IDF_TARGET_NAME}, you need to change the channel for the console output from UART (default) to USB.
+
+    1. Navigate to the option ``Channel for console output``.
+
+        ``Component config`` > ``ESP System Settings`` > ``Channel for console output``
+
+    2. Change to the option (the default will be always UART):
+
+        ``USB CDC``
+
+    3. Save the new configuration and exit the ``menuconfig`` screen.

docs/en/get-started/start-project.rst

@@ -41,41 +41,21 @@ If there are no errors, the build will finish by generating the firmware binary
 Flash onto the Device
 =====================
 
-Flash the binaries that you just built (bootloader.bin, partition-table.bin and hello_world.bin) onto your {IDF_TARGET_NAME} board by running:
+To flash the binaries that you just built for the {IDF_TARGET_NAME} in the previous step, you need to run the following command:
 
 .. code-block:: bash
 
-    idf.py -p PORT [-b BAUD] flash
+    idf.py -p PORT flash
 
-Replace PORT with your {IDF_TARGET_NAME} board's serial port name.
+Replace ``PORT`` with your {IDF_TARGET_NAME} board's USB port name. If the ``PORT`` is not defined, the :ref:`idf.py` will try to connect automatically using the available USB ports.
 
-You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``.
-
-For more information on idf.py arguments, see :ref:`idf.py`.
+For more information on ``idf.py`` arguments, see :ref:`idf.py`.
 
 .. note::
 
     The option ``flash`` automatically builds and flashes the project, so running ``idf.py build`` is not necessary.
 
-Encountered Issues While Flashing?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9"}
-
-If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is manual reset described below, and if it does not help you can find more details about possible issues in `Troubleshooting <https://github.com/espressif/esptool#bootloader-wont-respond>`_.
-
-``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB to serial converter chip, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
-
-In general, you should have no problems with the `official esp-idf development boards <https://www.espressif.com/en/products/devkits>`_. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases:
-
-- Your hardware does not have the DTR and RTS lines connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU``
-- The DTR and RTS lines are configured differently
-- There are no such serial control lines at all
-
-Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset).
-
-- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an ESP-IDF development board, hold down the **Boot** button (``{IDF_TARGET_STRAP_GPIO}``) and press the **EN** button (``CHIP_PU``).
-- For other types of hardware, try pulling ``{IDF_TARGET_STRAP_GPIO}`` down.
+Encountered Issues While Flashing? See this :doc:`flashing-troubleshooting` page or :doc:`establish-serial-connection` for more detailed information.
 
 Normal Operation
 ~~~~~~~~~~~~~~~~
@@ -428,3 +408,20 @@ ESP-IDF supports Python 3.7 or newer. It is recommended to upgrade your operatin
             idf.py add-dependency esp-box 
 
     More examples of BSP usage can be found in `BSP examples folder <https://github.com/espressif/esp-bsp/tree/master/examples>`_.
+
+Flash Erase
+~~~~~~~~~~~
+
+Erasing the flash is also possible. To erase the entire flash memory you can run the following command:
+
+.. code-block:: bash
+
+    idf.py -p PORT erase-flash
+
+For erasing the OTA data, if present, you can run this command:
+
+.. code-block:: bash
+
+    idf.py -p PORT erase-otadata
+
+The flash erase command can take a while to be done. Do not disconnect your device while the flash erasing is in progress.

docs/en/get-started/windows-setup.rst

@@ -131,6 +131,7 @@ For advanced users who want to customize the install process:
 
     windows-setup-update
     establish-serial-connection
+    flashing-troubleshooting
     ../api-guides/tools/idf-monitor
 
 .. _CMake: https://cmake.org/download/

docs/en/get-started/windows-start-project.rst

@@ -76,3 +76,17 @@ You are using this menu to set up project specific variables, e.g., Wi-Fi networ
 .. only:: esp32 or esp32s2 or esp32s3
 
     If you are using one of the supported development boards, you can speed up your development by using Board Support Package. See `Additional Tips <#additional-tips>`__ for more information.
+
+.. only:: esp32s2
+
+    To use the USB for flashing the {IDF_TARGET_NAME}, you need to change the channel for the console output to USB. For the {IDF_TARGET_NAME}, the default console output channel is the UART.
+
+    1. Navigate to the option ``Channel for console output``.
+
+        ``Component config  --->  ESP System Settings  ---> Channel for console output``
+
+    2. Change to the option (the default will be always UART):
+
+        ``USB CDC``
+
+    3. Save the new configuration and exit the ``menuconfig`` screen.