docs: update CN translation for idf-monitor.rst

pull/9141/head
daiziyan 2022-05-25 19:51:33 +08:00 zatwierdzone przez daiziyan
rodzic 2a733ceca5
commit 59453d0e78
5 zmienionych plików z 76 dodań i 66 usunięć

Wyświetl plik

@ -4,64 +4,64 @@ IDF Monitor
:link_to_translation:`zh_CN:[中文]`
The IDF monitor tool is mainly a serial terminal program which relays serial data to and from the target device's serial port. It also provides some IDF-specific features.
IDF Monitor is mainly a serial terminal program which relays serial data to and from the target device's serial port. It also provides some IDF-specific features.
This tool can be launched from an IDF project by running ``idf.py monitor``.
IDF Monitor can be launched from an IDF project by running ``idf.py monitor``.
Keyboard Shortcuts
==================
For easy interaction with IDF Monitor, use the keyboard shortcuts given in the table.
.. list-table::
:header-rows: 1
:widths: 15 25 55
.. list-table::
:header-rows: 1
:widths: 15 25 55
* - Keyboard Shortcut
- Action
- Description
- Description
* - Ctrl+]
- Exit the program
-
-
* - Ctrl+T
- Menu escape key
- Press and follow it by one of the keys given below.
- Press and follow it by one of the keys given below.
* - * Ctrl+T
- Send the menu character itself to remote
-
-
* - * Ctrl+]
- Send the exit character itself to remote
-
-
* - * 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 bootloader via the RTS line (if connected), so that the board runs nothing. Useful when you need to wait for another device to startup.
* - * Ctrl+R
- Reset target board via RTS
- Resets the target board and re-starts the application via the RTS line (if connected).
- Resets the target board and re-starts the application via the RTS line (if connected).
* - * Ctrl+F
- Build and flash the project
- Pauses idf_monitor to run the project ``flash`` target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. Target ``encrypted-flash`` is run if idf_monitor was started with argument ``-E``.
- Pauses idf_monitor to run the project ``flash`` target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. Target ``encrypted-flash`` is run if idf_monitor was started with argument ``-E``.
* - * Ctrl+A (or A)
- Build and flash the app only
- Pauses idf_monitor to run the ``app-flash`` target, then resumes idf_monitor. Similar to the ``flash`` target, but only the main app is built and re-flashed. Target ``encrypted-app-flash`` is run if idf_monitor was started with argument ``-E``.
- Pauses idf_monitor to run the ``app-flash`` target, then resumes idf_monitor. Similar to the ``flash`` target, but only the main app is built and re-flashed. Target ``encrypted-app-flash`` is run if idf_monitor was started with argument ``-E``.
* - * Ctrl+Y
- Stop/resume log output printing on screen
- Discards all incoming serial data while activated. Allows to quickly pause and examine log output without quitting the monitor.
- Discards all incoming serial data while activated. Allows to quickly pause and examine log output without quitting the monitor.
* - * Ctrl+L
- Stop/resume log output saved to file
- Creates a file in the project directory and the output is written to that file until this is disabled with the same keyboard shortcut (or IDF Monitor exits).
- Creates a file in the project directory and the output is written to that file until this is disabled with the same keyboard shortcut (or IDF Monitor exits).
* - * Ctrl+I (or I)
- Stop/resume printing timestamps
- IDF Monitor can print a timestamp in the beginning of each line. The timestamp format can be changed by the ``--timestamp-format`` command line argument.
* - * Ctrl+H (or H)
- Display all keyboard shortcuts
-
-
* - * Ctrl+X (or X)
- Exit the program
-
-
* - Ctrl+C
- Interrupt running application
- Pauses IDF monitor and run GDB_ project debugger to debug the application at runtime. This requires :ref:CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME option to be enabled.
- Pauses IDF Monitor and run GDB_ project debugger to debug the application at runtime. This requires :ref:CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME option to be enabled.
Any keys pressed, other than ``Ctrl-]`` and ``Ctrl-T``, will be sent through the serial port.
@ -72,7 +72,7 @@ IDF-specific features
Automatic Address Decoding
~~~~~~~~~~~~~~~~~~~~~~~~~~
Whenever ESP-IDF outputs a hexadecimal code address of the form ``0x4_______``, IDF Monitor uses addr2line_ to look up the location in the source code and find the function name.
Whenever ESP-IDF outputs a hexadecimal code address of the form ``0x4_______``, IDF Monitor uses ``addr2line_`` to look up the location in the source code and find the function name.
.. highlight:: none
@ -184,31 +184,31 @@ To decode each address, IDF Monitor runs the following command in the background
Set environment variable ``ESP_MONITOR_DECODE`` to ``0`` or call idf_monitor.py with specific command line option: ``idf_monitor.py --disable-address-decoding`` to disable address decoding.
Reset of the chip target on connect
Target Reset on Connection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The reset of the target chip is performed using DTR and RTS serial lines. For preventing the reset of the target on idf monitor startup call idf_monitor.py with specific command line option: ``idf_monitor.py --no-reset``.
By default, IDF Monitor will reset the target when connecting to it. The reset of the target chip is performed using the DTR and RTS serial lines. To prevent IDF Monitor from automatically resetting the target on connection, call IDF Monitor with the ``--no-reset`` option (e.g., ``idf_monitor.py --no-reset``).
.. note::
The same behavior can be achieved using ``idf.py monitor`` interface with specific command line option: ``--no-reset``. To prevent the reset on startup is required to call the command with explicitly set port ``idf.py monitor --no-reset -p [PORT]``
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]``).
Launching GDB with GDBStub
~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, if esp-idf crashes, the panic handler prints relevant registers and the stack dump (similar to the ones above) over the serial port. Then it resets the board.
GDBStub is a useful runtime debugging feature that runs on the target and connects to the host over the serial port to receive debugging commands. GDBStub supports commands such as reading memory and variables, examining call stack frames etc. Although GDBStub is less versatile than JTAG debugging, it does not require any special hardware (such as a JTAG to USB bridge) as communication is done entirely over the serial port.
Furthermore, the application can be configured to run GDBStub in the background and handle the Ctrl+C event from the monitor.
A target can be configured to run GDBStub in the background by setting the :ref:`CONFIG_ESP_SYSTEM_PANIC` to ``GDBStub on runtime``. GDBStub will run in the background until a ``Ctrl+C`` message is sent over the serial port and causes the GDBStub to break (i.e., stop the execution of) the program, thus allowing GDBStub to handle debugging commands.
Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB_ project debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as JTAG debugging, but this method does not require any special hardware.
Furthermore, the panic handler can be configured to run GDBStub on a crash by setting the :ref:`CONFIG_ESP_SYSTEM_PANIC` to ``GDBStub on panic``. When a crash occurs, GDBStub will output a special string pattern over the serial port to indicate that it is running.
To enable GDBStub on panic, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP_SYSTEM_PANIC` to ``GDBStub on panic`` or set :ref:`CONFIG_ESP_SYSTEM_PANIC` to ``GDBStub on runtime``.
In both cases (i.e., sending the ``Ctrl+C`` message, or receiving the special string pattern), IDF Monitor will automatically launch GDB in order to allow the user to send debugging commands. After GDB exits, the target is reset via the RTS serial line. If this line is not connected, users can reset their target (by pressing the board's Reset button).
In this case, if the panic handler or Ctrl+C command is triggered, as soon as IDF Monitor sees that GDBStub has loaded, it automatically pauses serial monitoring and runs GDB with necessary arguments. After GDB exits, the board is reset via the RTS serial line. If this line is not connected, please reset the board manually by pressing its Reset button.
.. note::
In the background, IDF Monitor runs the following command to launch GDB::
In the background, IDF Monitor runs the following command::
{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf :idf_target:`Hello NAME chip`
{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf :idf_target:`Hello NAME chip`
Output Filtering
@ -227,7 +227,7 @@ Your app tags must not contain spaces, asterisks ``*``, or colons ``:`` to be co
If the last line of the output in your app is not followed by a carriage return, the output filtering might get confused, i.e., the monitor starts to print the line and later finds out that the line should not have been written. This is a known issue and can be avoided by always adding a carriage return (especially when no output follows immediately afterwards).
Examples Of Filtering Rules:
Examples of Filtering Rules:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- ``*`` can be used to match any tags. However, the string ``PRINT_FILTER="*:I tag1:E"`` with regards to ``tag1`` prints errors only, because the rule for ``tag1`` has a higher priority over the rule for ``*``.

Wyświetl plik

@ -135,7 +135,7 @@ For an example, see :example:`storage/fatfsgen`.
FatFs Partition Analyzer
------------------------
We provide a partition analyzer for FatFs (:component_file:`fatfsparse.py<fatfs/fatfsparse.py>`). The tool is still in active progress and provides only restricted functionality.
We provide a partition analyzer for FatFs (:component_file:`fatfsparse.py<fatfs/fatfsparse.py>`). The tool is still in active progress and provides only restricted functionality.
It is only guaranteed that the tool is able to analyze images generated by FatFs partition generator (:component_file:`fatfsgen.py<fatfs/fatfsgen.py>`) (without support for wear levelling and long names) and generate the folder structure on host with the same name as a FatFs volume label.

Wyświetl plik

@ -6,62 +6,62 @@ IDF 监视器
IDF 监视器是一个串行终端程序用于收发目标设备串口的串行数据IDF 监视器同时还兼具 IDF 的其他特性。
在 IDF 中调用 idf.py monitor 可以启用此监视器
在 IDF 中调用 ``idf.py monitor`` 可以启用此监视器
操作快捷键
==================
为了方便与 IDF 监视器进行交互,请使用表中给出的快捷键。
.. list-table::
:header-rows: 1
:widths: 15 25 55
.. list-table::
:header-rows: 1
:widths: 15 25 55
* - 快捷键
- 操作
- 描述
- 描述
* - Ctrl+]
- 退出监视器程序
-
-
* - Ctrl+T
- 菜单退出键
- 按下如下给出的任意键之一,并按指示操作。
- 按下如下给出的任意键之一,并按指示操作。
* - * Ctrl+T
- 将菜单字符发送至远程
-
-
* - * Ctrl+]
- 将 exit 字符发送至远程
-
-
* - * Ctrl+P
- 重置目标设备,进入 Bootloader,通过 RTS 线暂停应用程序
- 重置目标设备,通过 RTS 线(如已连接)进入 Bootloader,此时开发板不运行任何程序。等待其他设备启动时可以使用此操作。
- 重置目标设备,进入引导加载程序,通过 RTS 线暂停应用程序
- 重置目标设备,通过 RTS 线(如已连接)进入引导加载程序,此时开发板不运行任何程序。等待其他设备启动时可以使用此操作。
* - * Ctrl+R
- 通过 RTS 线重置目标设备
- 重置设备,并通过 RTS 线(如已连接)重新启动应用程序。
- 重置设备,并通过 RTS 线(如已连接)重新启动应用程序。
* - * Ctrl+F
- 编译并烧录此项目
- 暂停 idf_monitor运行 ``flash`` 目标,然后恢复 idf_monitor。任何改动的源文件都会被重新编译然后重新烧录。如果 idf_monitor 是以参数 ``-E`` 启动的,则会运行目标 ``encrypted-flash``
- 暂停 idf_monitor运行 ``flash`` 目标,然后恢复 idf_monitor。任何改动的源文件都会被重新编译然后重新烧录。如果 idf_monitor 是以参数 ``-E`` 启动的,则会运行目标 ``encrypted-flash``
* - * Ctrl+A (或者 A)
- 仅编译及烧录应用程序
- 暂停 idf_monitor运行 ``app-flash`` 目标,然后恢复 idf_monitor。 这与 ``flash`` 类似,但只有主应用程序被编译并被重新烧录。如果 idf_monitor 是以参数 ``-E`` 启动的,则会运行目标 ``encrypted-flash``
- 暂停 idf_monitor运行 ``app-flash`` 目标,然后恢复 idf_monitor。 这与 ``flash`` 类似,但只有主应用程序被编译并被重新烧录。如果 idf_monitor 是以参数 ``-E`` 启动的,则会运行目标 ``encrypted-flash``
* - * Ctrl+Y
- 停止/恢复在屏幕上打印日志输出
- 激活时,会丢弃所有传入的串行数据。允许在不退出监视器的情况下快速暂停和检查日志输出。
- 激活时,会丢弃所有传入的串行数据。允许在不退出监视器的情况下快速暂停和检查日志输出。
* - * Ctrl+L
- 停止/恢复向文件写入日志输出
- 在工程目录下创建一个文件,用于写入日志输出。可使用快捷键停止/恢复该功能(退出 IDF 监视器也会终止该功能)
- 在工程目录下创建一个文件,用于写入日志输出。可使用快捷键停止/恢复该功能(退出 IDF 监视器也会终止该功能)
* - * Ctrl+I (或者 I)
- 停止/恢复打印时间标记
- IDF 监视器可以在每一行的开头打印一个时间标记。时间标记的格式可以通过 ``--timestamp-format`` 命令行参数来改变。
- IDF 监视器可以在每一行的开头打印一个时间标记。时间标记的格式可以通过 ``--timestamp-format`` 命令行参数来改变。
* - * Ctrl+H (或者 H)
- 显示所有快捷键
-
-
* - * Ctrl+X (或者 X)
- 退出监视器程序
-
-
* - Ctrl+C
- 中断正在运行的应用程序
- 暂停 IDF 监视器并运行 GDB_ 项目调试器,从而在运行时调试应用程序。这需要启 :ref:CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME 选项。
- 暂停 IDF 监视器并运行 GDB_ 项目调试器,从而在运行时调试应用程序。这需要启 :ref:CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME 选项。
除了 ``Ctrl-]````Ctrl-T``,其他快捷键信号会通过串口发送到目标设备。
@ -72,7 +72,7 @@ IDF 监视器是一个串行终端程序,用于收发目标设备串口的串
自动解码地址
~~~~~~~~~~~~~~~~
ESP-IDF 输出形式为 ``0x4_______`` 的十六进制代码地址后IDF 监视器将使用 addr2line_ 查找该地址在源代码中的位置和对应的函数名。
ESP-IDF 输出形式为 ``0x4_______`` 的十六进制代码地址后IDF 监视器将使用 ``addr2line_`` 查找该地址在源代码中的位置和对应的函数名。
.. highlight:: none
@ -182,24 +182,33 @@ IDF 监视器在后台运行以下命令,解码各地址::
.. note::
将环境变量 ``ESP_MONITOR_DECODE`` 设置为 ``0`` 或者调用 idf_monitor.py 的特定命令行选项:``idf_monitor.py --disable-address-decoding`` 来禁止地址解码。
将环境变量 ``ESP_MONITOR_DECODE`` 设置为 ``0`` 或者调用 idf_monitor.py 的特定命令行选项 ``idf_monitor.py --disable-address-decoding`` 来禁止地址解码。
连接时复位目标芯片
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
默认情况下IDF 监视器会在目标芯片连接时通过 DTR 和 RTS 串行线自动复位芯片。要防止 IDF 监视器在连接时自动复位,请在调用 IDF 监视器时加上选项 ``--no-reset``,如 ``idf_monitor.py --no-reset``
.. note::
``--no-reset`` 选项在 IDF 监视器连接到特定端口时可以实现同样的效果,如 ``idf.py monitor --no-reset -p [PORT]``
配置 GDBStub 以启用 GDB
~~~~~~~~~~~~~~~~~~~~~~~~~
默认情况下,如果 ESP-IDF 应用程序发生 crash 事件panic 处理器将在串口上打印相关寄存器和堆栈转储(类似上述情况),然后重置开发板。
GDBStub 支持在运行时进行调试。GDBStub 在目标上运行并通过串口连接到主机从而接收调试命令。GDBStub 支持读取内存和变量、检查调用堆栈帧等命令。虽然没有 JTAG 调试通用,但由于 GDBStub 完全通过串行端口完成通信,故不需要使用特殊硬件(如 JTAG/USB 桥接器)
此外,可以配置应用程序在后台运行 GDBStub 并处理运行中的应用程序突然中断事件 (Ctrl+C)。
通过将 :ref:`CONFIG_ESP_SYSTEM_PANIC` 设置为 ``GDBStub on runtime``,可以将目标配置为在后台运行 GDBStub。GDBStub 将保持在后台运行,直到通过串行端口发送 ``Ctrl+C`` 导致应用程序中断(即停止程序执行),从而让 GDBStub 处理调试命令
或者选择配置 panic 处理器以运行 GDBStubGDBStub 工具可以与 GDB_ 项目调试器进行通信允许读取内存、检查调用堆栈帧和变量等。GDBStub 虽然没有 JTAG 通用,但不需要使用特殊硬件。
此外,还可以通过设置 :ref:`CONFIG_ESP_SYSTEM_PANIC```GDBStub on panic`` 来配置 panic 处理程序,使其在发生 crash 事件时运行 GDBStub。当 crash 发生时GDBStub 将通过串口输出特殊的字符串模式,表示 GDBStub 正在运行
如需在发生 panic 事件时启用 GDBStub请运行 ``idf.py menuconfig`` 打开项目配置菜单,并将 :ref:`CONFIG_ESP_SYSTEM_PANIC` 选项设置为 ``GDBStub on panic``,或者将 :ref:`CONFIG_ESP_SYSTEM_PANIC` 设置为 ``GDBStub on runtime``
无论是通过发送 ``Ctrl+C`` 还是收到特殊字符串模式IDF 监视器都会自动启动 GDB从而让用户发送调试命令。GDB 退出后,通过 RTS 串口线复位目标。如果未连接 RTS 串口线,请按复位键,手动复位开发板。
在这种情况下,如果 panic 处理器被触发或应用程序突然中断 (Ctrl+C),只要 IDF 监视器监控到 GDBStub 已经加载panic 处理器就会自动暂停串行监控并使用必要的参数运行 GDB。GDB 退出后,通过 RTS 串口线复位开发板。如果未连接 RTS 串口线,请按复位键,手动复位开发板。
.. note::
IDF 监视器在后台运行如下命令启用 GDB::
IDF 监控器在后台运行如下命令::
{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf :idf_target:`Hello NAME chip`
{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf :idf_target:`Hello NAME chip`
输出筛选

Wyświetl plik

@ -98,6 +98,7 @@ FatFs 分区生成器
目前最新版本支持短文件名、长文件名、FAT12 和 FAT16。长文件名的上限是 255 个字符,文件名中可以包含多个 "." 字符以及其他字符如 "+"、","、";"、"="、"[" and also "]" 等。长文件名字符采用 utf-16 编码,而短文件名采用 utf-8 编码。
构建系统中使用 FatFs 分区生成器
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Wyświetl plik

@ -266,4 +266,4 @@ R19 CLK SD_CLK
- `ESP32-SOLO-1 技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32-solo-1_datasheet_cn.pdf>`_ (PDF)
- `ESP32-WROVER 技术规格书 <https://espressif.com/sites/default/files/documentation/esp32_wrover_datasheet_cn.pdf>`_ (PDF)
- `ESP32-WROVER-B 技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32-wrover-b_datasheet_cn.pdf>`_ (PDF)
- `乐鑫产品选型工具 <https://products.espressif.com/#/product-selector?names=>`__
- `乐鑫产品选型工具 <https://products.espressif.com/#/product-selector?names=>`__