diff --git a/docs/en/api-guides/tools/idf-monitor.rst b/docs/en/api-guides/tools/idf-monitor.rst index 71def9e968..414a4d0ca3 100644 --- a/docs/en/api-guides/tools/idf-monitor.rst +++ b/docs/en/api-guides/tools/idf-monitor.rst @@ -34,7 +34,7 @@ For easy interaction with IDF Monitor, use the keyboard shortcuts given in the t - * - * Ctrl + P - Reset target into bootloader to pause app via RTS line - - Resets the target, into bootloader via the RTS line (if connected), so that the board runs nothing. Useful when you need to wait for another device to startup. + - Resets the target into the bootloader using the RTS and DTR lines (if connected). This stops the board from executing the application, making it useful when waiting for another device to start. For additional details, refer to `Target Reset into Bootloader`_. * - * Ctrl + R - Reset target board via RTS - Resets the target board and re-starts the application via the RTS line (if connected). @@ -235,6 +235,79 @@ By default, IDF Monitor will reset the target when connecting to it. The reset o The ``--no-reset`` option applies the same behavior even when connecting IDF Monitor to a particular port (e.g., ``idf.py monitor --no-reset -p [PORT]``). +Target Reset into Bootloader +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +IDF Monitor provides the capability to reset a chip into the bootloader using a pre-defined reset sequence that has been tuned to work in most environments. Additionally, users have the flexibility to set a custom reset sequence, allowing for fine-tuning and adaptability to diverse scenarios. + +Using Pre-defined Reset Sequence +-------------------------------- + +IDF Monitor's default reset sequence is designed to work seamlessly across a wide range of environments. To trigger a reset into the bootloader using the default sequence, no additional configuration is required. + +Custom Reset Sequence +--------------------- + +For more advanced users or specific use cases, IDF Monitor supports the configuration of a custom reset sequence using `Configuration File`_. This is particularly useful in extreme edge cases where the default sequence may not suffice. + +The sequence is defined with a string in the following format: + +- Consists of individual commands divided by ``|`` (e.g. ``R0|D1|W0.5``). +- Commands (e.g. ``R0``) are defined by a code (``R``) and an argument (``0``). + +.. list-table:: + :header-rows: 1 + :widths: 15 50 35 + :align: center + + * - Code + - Action + - Argument + * - D + - Set DTR control line + - ``1``/``0`` + * - R + - Set RTS control line + - ``1``/``0`` + * - U + - Set DTR and RTS control lines at the same time (Unix-like systems only) + - ``0,0``/``0,1``/``1,0``/``1,1`` + * - W + - Wait for ``N`` seconds (where ``N`` is a float) + - N + +Example: + +.. code-block:: ini + + [esp-idf-monitor] + custom_reset_sequence = U0,1|W0.1|D1|R0|W0.5|D0 + +Refer to `custom reset sequence`_ from Esptool documentation for further details. Please note that ``custom_reset_sequence`` is the only used value from the Esptool configuration, and others will be ignored in IDF Monitor. + +Share Configuration Across Tools +-------------------------------- + +The configuration for the custom reset sequence can be specified in a shared configuration file between IDF Monitor and Esptool. In this case, your configuration file name should be either ``setup.cfg`` or ``tox.ini`` so it would be recognized by both tools. + +Example of a shared configuration file: + +.. code-block:: ini + + [esp-idf-monitor] + menu_key = T + skip_menu_key = True + + [esptool] + custom_reset_sequence = U0,1|W0.1|D1|R0|W0.5|D0 + +.. note:: + + When using the ``custom_reset_sequence`` parameter in both the ``[esp-idf-monitor]`` section and the ``[esptool]`` section, the configuration from the ``[esp-idf-monitor]`` section will take precedence in IDF Monitor. Any conflicting configuration in the ``[esptool]`` section will be ignored. + + This precedence rule also applies when the configuration is spread across multiple files. The global esp-idf-monitor configuration will take precedence over the local esptool configuration. + + Launching GDB with GDBStub ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -396,6 +469,9 @@ Below is a table listing the available configuration options: * - skip_menu_key - Pressing the menu key can be skipped for menu commands. - ``False`` + * - custom_reset_sequence + - Custom reset sequence for resetting into the bootloader. + - Syntax @@ -403,7 +479,7 @@ Syntax The configuration file is in .ini file format: it must be introduced by an ``[esp-idf-monitor]`` header to be recognized as valid. This section then contains name = value entries. Lines beginning with ``#`` or ``;`` are ignored as comments. -.. code-block:: text +.. code-block:: ini # esp-idf-monitor.cfg file to configure internal settings of esp-idf-monitor [esp-idf-monitor] @@ -423,12 +499,7 @@ The configuration file is in .ini file format: it must be introduced by an ``[es Known Issues with IDF Monitor ============================= -Issues Observed on Windows -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Arrow keys, as well as some other keys, do not work in GDB due to Windows Console limitations. -- Occasionally, when "idf.py" exits, it might stall for up to 30 seconds before IDF Monitor resumes. -- When "gdb" is run, it might stall for a short time before it begins communicating with the GDBStub. +If you encounter any issues while using IDF Monitor, check our `GitHub repository `_ for a list of known issues and their current status. If you come across a problem that hasn't been documented yet, we encourage you to create a new issue report. .. _addr2line: https://sourceware.org/binutils/docs/binutils/addr2line.html .. _esp-idf-monitor: https://github.com/espressif/esp-idf-monitor @@ -436,3 +507,4 @@ Issues Observed on Windows .. _pySerial: https://github.com/pyserial/pyserial .. _miniterm: https://pyserial.readthedocs.org/en/latest/tools.html#module-serial.tools.miniterm .. _C0 control codes: https://en.wikipedia.org/wiki/C0_and_C1_control_codes#C0_controls +.. _custom reset sequence: https://docs.espressif.com/projects/esptool/en/latest/{IDF_TARGET_PATH_NAME}/esptool/configuration-file.html#custom-reset-sequence diff --git a/docs/en/get-started/linux-macos-setup.rst b/docs/en/get-started/linux-macos-setup.rst index cf4c800ba6..ccfba88fbb 100644 --- a/docs/en/get-started/linux-macos-setup.rst +++ b/docs/en/get-started/linux-macos-setup.rst @@ -294,7 +294,6 @@ Related Documents establish-serial-connection flashing-troubleshooting - ../api-guides/tools/idf-monitor .. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository .. _First Steps on ESP-IDF: ../get-started/first-steps.html diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst index 7c74ff8e57..b9a0ad6dee 100644 --- a/docs/en/get-started/windows-setup.rst +++ b/docs/en/get-started/windows-setup.rst @@ -132,7 +132,6 @@ 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/ .. _Ninja: https://ninja-build.org/ diff --git a/docs/zh_CN/get-started/linux-macos-setup.rst b/docs/zh_CN/get-started/linux-macos-setup.rst index 1df948783b..3b7e1d8e36 100644 --- a/docs/zh_CN/get-started/linux-macos-setup.rst +++ b/docs/zh_CN/get-started/linux-macos-setup.rst @@ -294,7 +294,6 @@ ESP-IDF 工具安装器会下载 Github 发布版本中附带的一些工具， establish-serial-connection flashing-troubleshooting - ../api-guides/tools/idf-monitor .. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository .. _First Steps on ESP-IDF: ../get-started/first-steps.html diff --git a/docs/zh_CN/get-started/windows-setup.rst b/docs/zh_CN/get-started/windows-setup.rst index 13fdb60ad5..2c109110c9 100644 --- a/docs/zh_CN/get-started/windows-setup.rst +++ b/docs/zh_CN/get-started/windows-setup.rst @@ -132,7 +132,6 @@ ESP-IDF 工具安装器可在“开始”菜单中，创建一个打开 ESP-IDF windows-setup-update establish-serial-connection flashing-troubleshooting - ../api-guides/tools/idf-monitor .. _CMake: https://cmake.org/download/ .. _Ninja: https://ninja-build.org/