feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

docs: Move monitor configuration documentation to its own repository

Browse Source
This commit is contained in:
Peter Dragun
2024-09-03 14:58:51 +02:00
parent 91ad4bcbce
commit 31dc7b6f07
2 changed files with 9 additions and 325 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
docs/en/api-guides/tools/idf-monitor.rst
View File

@@ -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/<user>/.config/esp-idf-monitor/``
- MacOS ``/Users/<user>/.config/esp-idf-monitor/``
- Windows: ``c:\Users\<user>\AppData\Local\esp-idf-monitor\``
If a configuration file is still not found, the last inspected location is the home directory:
- Linux: ``/home/<user>/``
- MacOS ``/Users/<user>/``
- Windows: ``c:\Users\<user>\``
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 <https://github.com/espressif/esp-idf-monitor/issues>`_ 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

168
docs/zh_CN/api-guides/tools/idf-monitor.rst
View File

@@ -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/<user>/.config/esp-idf-monitor/``
- MacOS ``/Users/<user>/.config/esp-idf-monitor/``
- Windows: ``c:\Users\<user>\AppData\Local\esp-idf-monitor\``
如仍未检测到配置文件，会最后再检查主目录：
- Linux: ``/home/<user>/``
- MacOS ``/Users/<user>/``
- Windows: ``c:\Users\<user>\``
在 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 仓库 <https://github.com/espressif/esp-idf-monitor/issues>`_ 以获取已知问题列表及其当前状态。如果遇到的问题没有相关记录，请创建一个新的问题报告。
如果在使用 IDF 监视器过程中遇到任何问题，请查看 `GitHub 仓库 <https://github.com/espressif/esp-idf-monitor/issues>`_ 以获取已知问题列表及其当前状态。如果遇到的问题没有相关记录，请创建一个新的问题报告。
.. _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