From 31dc7b6f07a2063c9b74bebcc0eea82eb135274b Mon Sep 17 00:00:00 2001 From: Peter Dragun Date: Tue, 3 Sep 2024 14:58:51 +0200 Subject: [PATCH] docs: Move monitor configuration documentation to its own repository --- docs/en/api-guides/tools/idf-monitor.rst | 166 +------------------ docs/zh_CN/api-guides/tools/idf-monitor.rst | 168 +------------------- 2 files changed, 9 insertions(+), 325 deletions(-) diff --git a/docs/en/api-guides/tools/idf-monitor.rst b/docs/en/api-guides/tools/idf-monitor.rst index 5c4408209d..9505a76210 100644 --- a/docs/en/api-guides/tools/idf-monitor.rst +++ b/docs/en/api-guides/tools/idf-monitor.rst @@ -252,63 +252,7 @@ Custom Reset Sequence For more advanced users or specific use cases, IDF Monitor supports the configuration of a custom reset sequence using :ref:`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. - +If you would like to use a custom reset sequence, take a look at the `IDF Monitor documentation`_ for more details. Launching GDB with GDBStub ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -397,107 +341,9 @@ The options ``--print_filter="light_driver:D esp_image:N boot:N cpu_start:N vfs: Configuration File ================== -``esp-idf-monitor`` is using `C0 control codes`_ to interact with the console. Characters from the config file are converted to their C0 control codes. Available characters include the English alphabet (A-Z) and special symbols: ``[``, ``]``, ``\``, ``^``, ``_``. +``esp-idf-monitor`` offers option to change its default behavior with configuration file. This file can be used for example to set custom key bindings, or set a custom reset sequence for resetting the chip into bootloader mode. -.. warning:: - - Please note that some characters may not work on all platforms or can be already reserved as a shortcut for something else. Use this feature with caution! - - -File Location -~~~~~~~~~~~~~ - -The default name for a configuration file is ``esp-idf-monitor.cfg``. First, the same directory ``esp-idf-monitor`` is being run if is inspected. - -If a configuration file is not found here, the current user's OS configuration directory is inspected next: - - - Linux: ``/home//.config/esp-idf-monitor/`` - - MacOS ``/Users//.config/esp-idf-monitor/`` - - Windows: ``c:\Users\\AppData\Local\esp-idf-monitor\`` - -If a configuration file is still not found, the last inspected location is the home directory: - - - Linux: ``/home//`` - - MacOS ``/Users//`` - - Windows: ``c:\Users\\`` - -On Windows, the home directory can be set with the ``HOME`` or ``USERPROFILE`` environment variables. Therefore, the Windows configuration directory location also depends on these. - -A different location for the configuration file can be specified with the ``ESP_IDF_MONITOR_CFGFILE`` environment variable, e.g., ``ESP_IDF_MONITOR_CFGFILE = ~/custom_config.cfg``. This overrides the search priorities described above. - -``esp-idf-monitor`` will read settings from other usual configuration files if no other configuration file is used. It automatically reads from ``setup.cfg`` or ``tox.ini`` if they exist. - -Configuration Options -~~~~~~~~~~~~~~~~~~~~~ - -Below is a table listing the available configuration options: - -.. list-table:: - :header-rows: 1 - :widths: 30 50 20 - :align: center - - * - Option Name - - Description - - Default Value - * - menu_key - - Key to access the main menu. - - ``T`` - * - exit_key - - Key to exit the monitor. - - ``]`` - * - chip_reset_key - - Key to initiate a chip reset. - - ``R`` - * - recompile_upload_key - - Key to recompile and upload. - - ``F`` - * - recompile_upload_app_key - - Key to recompile and upload just the application. - - ``A`` - * - toggle_output_key - - Key to toggle the output display. - - ``Y`` - * - toggle_log_key - - Key to toggle the logging feature. - - ``L`` - * - toggle_timestamp_key - - Key to toggle timestamp display. - - ``I`` - * - chip_reset_bootloader_key - - Key to reset the chip to bootloader mode. - - ``P`` - * - exit_menu_key - - Key to exit the monitor from the menu. - - ``X`` - * - 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. - - N/A - - -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:: ini - - # esp-idf-monitor.cfg file to configure internal settings of esp-idf-monitor - [esp-idf-monitor] - menu_key = T - exit_key = ] - chip_reset_key = R - recompile_upload_key = F - recompile_upload_app_key = A - toggle_output_key = Y - toggle_log_key = L - toggle_timestamp_key = I - chip_reset_bootloader_key = P - exit_menu_key = X - skip_menu_key = False +For more details on the configuration file, see the `IDF Monitor documentation`_. Known Issues with IDF Monitor @@ -505,10 +351,6 @@ Known Issues with IDF Monitor 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 +.. _IDF Monitor documentation: https://github.com/espressif/esp-idf-monitor/blob/v1.5.0/README.md#documentation .. _gdb: https://sourceware.org/gdb/download/onlinedocs/ -.. _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/zh_CN/api-guides/tools/idf-monitor.rst b/docs/zh_CN/api-guides/tools/idf-monitor.rst index 7e38c5a187..8c186f6539 100644 --- a/docs/zh_CN/api-guides/tools/idf-monitor.rst +++ b/docs/zh_CN/api-guides/tools/idf-monitor.rst @@ -252,63 +252,7 @@ IDF 监视器的默认复位序列可在大多数环境中使用。使用默认 对于高级用户或特定用例，IDF 监视器支持使用 :ref:`configuration-file` 配置自定义复位序列。这在默认序列可能不足的极端情况下特别有用。 -复位序列可通过以下格式的字符串定义： - -- 各个命令由 ``|`` 分隔（例如 ``R0|D1|W0.5``）。 -- 命令（例如 ``R0``）由代码（``R``）和参数（``0``）定义。 - -.. list-table:: - :header-rows: 1 - :widths: 15 50 35 - :align: center - - * - 代码 - - 操作 - - 参数 - * - D - - 设置 DTR 控制线 - - ``1``/``0`` - * - R - - 设置 RTS 控制线 - - ``1``/``0`` - * - U - - 同时设置 DTR 和 RTS 控制线（仅适用于类 Unix 系统） - - ``0,0``/``0,1``/``1,0``/``1,1`` - * - W - - 等待 ``N`` 秒（其中 ``N`` 为浮点数） - - N - -示例： - -.. code-block:: ini - - [esp-idf-monitor] - custom_reset_sequence = U0,1|W0.1|D1|R0|W0.5|D0 - -有关更多详细信息，请参阅 Esptool 文档中 `custom reset sequence`_ 章节。请注意，IDF 监视器只使用了 Esptool 配置中的 ``custom_reset_sequence`` 值，其他值会被 IDF 监视器忽略。 - -IDF 监视器和 Esptool 之间共享配置 ----------------------------------------------- - -自定义复位序列的配置可以在 IDF 监视器和 Esptool 之间的共享配置文件中指定。在这种情况下，为了使两个工具都能识别配置文件，其名称应为 ``setup.cfg`` 或 ``tox.ini``。 - -共享配置文件的示例： - -.. 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:: - - 当在 ``[esp-idf-monitor]`` 部分和 ``[esptool]`` 部分都使用 ``custom_reset_sequence`` 参数时，IDF 监视器会优先使用 ``[esp-idf-monitor]`` 部分的配置。``[esptool]`` 部分中任何与之冲突的配置都将被忽略。 - - 当配置分散在多个文件中时，此优先规则也适用。全局 esp-idf-monitor 配置将优先于本地 esptool 配置。 - +如需使用自定义复位序列，请参阅 `IDF 监视器文档`_ 获取更多详细信息。 配置 GDBStub 以启用 GDB ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -397,118 +341,16 @@ GDBStub 支持在运行时进行调试。GDBStub 在目标上运行，并通过 配置文件 ======== -``esp-idf-monitor`` 使用 `C0 控制字符`_ 与控制台进行交互。配置文件中的字符会被转换为对应的 C0 控制代码。可用字符包括英文字母 (A-Z) 和特殊符号：``[``、``]``、``\``、``^``、和 ``_``. +``esp-idf-monitor`` 支持通过配置文件更改其默认行为。该配置文件可用于设置自定义快捷键，或设置自定义复位序列以重置芯片进入引导加载程序。 -.. warning:: - - 注意，一些字符可能无法在所有平台通用，或被保留作为其他用途的快捷键。请谨慎使用此功能。 - - -文件位置 -~~~~~~~~~~ - -配置文件的默认名称为 ``esp-idf-monitor.cfg``。首先，在 ``esp-idf-monitor`` 路径中检测配置文件并运行。 - -如果此目录中没有检测到配置文件，则检查当前用户操作系统的配置目录： - - - Linux: ``/home//.config/esp-idf-monitor/`` - - MacOS ``/Users//.config/esp-idf-monitor/`` - - Windows: ``c:\Users\\AppData\Local\esp-idf-monitor\`` - -如仍未检测到配置文件，会最后再检查主目录： - - - Linux: ``/home//`` - - MacOS ``/Users//`` - - Windows: ``c:\Users\\`` - -在 Windows 中，可以使用 ``HOME`` 或 ``USERPROFILE`` 环境变量设置主目录，因此，Windows 配置目录的位置也取决于这些变量。 - -还可以使用 ``ESP_IDF_MONITOR_CFGFILE`` 环境变量为配置文件指定一个不同的位置，例如 ``ESP_IDF_MONITOR_CFGFILE = ~/custom_config.cfg``。这一设置的检测优先级高于上述所有位置检测的优先级。 - -如果没有使用其他配置文件，``esp-idf-monitor`` 会从其他常用的配置文件中读取设置。如果存在 ``setup.cfg`` 或 ``tox.ini`` 文件，``esp-idf-monitor`` 会自动从这些文件中读取设置。 - -配置选项 -~~~~~~~~~~ - -下表列出了可用的配置选项： - -.. list-table:: - :header-rows: 1 - :widths: 30 50 20 - :align: center - - * - 选项名称 - - 描述 - - 默认值 - * - menu_key - - 访问主菜单 - - ``T`` - * - exit_key - - 退出监视器 - - ``]`` - * - chip_reset_key - - 初始化芯片重置 - - ``R`` - * - recompile_upload_key - - 重新编译并上传 - - ``F`` - * - recompile_upload_app_key - - 仅重新编译并上传应用程序 - - ``A`` - * - toggle_output_key - - 切换输出显示 - - ``Y`` - * - toggle_log_key - - 切换日志功能 - - ``L`` - * - toggle_timestamp_key - - 切换时间戳显示 - - ``I`` - * - chip_reset_bootloader_key - - 将芯片重置为引导加载模式 - - ``P`` - * - exit_menu_key - - 从菜单中退出监视器 - - ``X`` - * - skip_menu_key - - 设置使用菜单命令时无需按下主菜单键 - - ``False`` - * - custom_reset_sequence - - 复位目标到引导加载程序的自定义复位序列 - - 无默认值 - - -语法 -~~~~ - -配置文件为 .ini 文件格式，必须以 ``[esp-idf-monitor]`` 标头引入才能被识别为有效文件。以下语法以“配置名称 = 配置值”形式列出。以 ``#`` 或 ``;`` 开头的行是注释，将被忽略。 - -.. code-block:: ini - - # esp-idf-monitor.cfg file to configure internal settings of esp-idf-monitor - [esp-idf-monitor] - menu_key = T - exit_key = ] - chip_reset_key = R - recompile_upload_key = F - recompile_upload_app_key = A - toggle_output_key = Y - toggle_log_key = L - toggle_timestamp_key = I - chip_reset_bootloader_key = P - exit_menu_key = X - skip_menu_key = False +有关配置文件的更多详细信息，请参阅 `IDF 监视器文档`_。 IDF 监视器已知问题 ================================= -如果在使用 IDF 监视器过程中遇到任何问题，请查看我们的 `GitHub 仓库 `_ 以获取已知问题列表及其当前状态。如果遇到的问题没有相关记录，请创建一个新的问题报告。 +如果在使用 IDF 监视器过程中遇到任何问题，请查看 `GitHub 仓库 `_ 以获取已知问题列表及其当前状态。如果遇到的问题没有相关记录，请创建一个新的问题报告。 -.. _addr2line: https://sourceware.org/binutils/docs/binutils/addr2line.html .. _esp-idf-monitor: https://github.com/espressif/esp-idf-monitor +.. _IDF 监视器文档: https://github.com/espressif/esp-idf-monitor/blob/v1.5.0/README.md#documentation .. _gdb: https://sourceware.org/gdb/download/onlinedocs/ -.. _pySerial: https://github.com/pyserial/pyserial -.. _miniterm: https://pyserial.readthedocs.org/en/latest/tools.html#module-serial.tools.miniterm -.. _C0 控制字符: https://zh.wikipedia.org/wiki/C0%E4%B8%8EC1%E6%8E%A7%E5%88%B6%E5%AD%97%E7%AC%A6#C0_(ASCII%E5%8F%8A%E5%85%B6%E6%B4%BE%E7%94%9F) -.. _custom reset sequence: https://docs.espressif.com/projects/esptool/en/latest/{IDF_TARGET_PATH_NAME}/esptool/configuration-file.html#custom-reset-sequence