IDF Monitor
IDF Monitor uses the esp-idf-monitor package as a serial terminal program which relays serial data to and from the target device's serial port. It also provides some ESP-IDF-specific features.
IDF Monitor can be launched from an ESP-IDF project by running idf.py monitor
.
Keyboard Shortcuts
For easy interaction with IDF Monitor, use the keyboard shortcuts given in the table. These keyboard shortcuts can be customized, for more details see Configuration File section.
Keyboard Shortcut |
Action |
Description |
---|---|---|
Ctrl + ] |
Exit the program |
|
Ctrl + T |
Menu escape key |
Press and follow it by one of the keys given below. |
|
Send the menu character itself to remote |
|
|
Send the exit character itself to remote |
|
|
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. |
|
Reset target board via RTS |
Resets the target board and re-starts the application via the RTS line (if connected). |
|
Build and flash the project |
Pauses idf_monitor to run the project |
|
Build and flash the app only |
Pauses idf_monitor to run the |
|
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. |
|
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). |
|
Stop/resume printing timestamps |
IDF Monitor can print a timestamp in the beginning of each line. The timestamp format can be changed by the |
|
Display all keyboard shortcuts |
|
|
Exit the program |
|
Ctrl + C |
Interrupt running application |
Pauses IDF Monitor and runs GDB project debugger to debug the application at runtime. This requires 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.
ESP-IDF-specific Features
Automatic Address Decoding
Whenever the chip outputs a hexadecimal address that points to executable code, IDF monitor looks up the location in the source code (file name and line number) and prints the location on the next line in yellow.
If an ESP-IDF app crashes and panics, a register dump and backtrace are produced, such as the following:
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
IDF Monitor adds more details to the dump:
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47
0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42
0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33
0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32s3/./cpu_start.c:254
To decode each address, IDF Monitor runs the following command in the background:
xtensa-esp32s3-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
If an address is not matched in the app source code, IDF monitor also checks the ROM code. Instead of printing the source file name and line number, only the function name followed by in ROM
is displayed:
abort() was called at PC 0x40007c69 on core 0
0x40007c69: ets_write_char in ROM
Backtrace: 0x40081656:0x3ffb4ac0 0x40085729:0x3ffb4ae0 0x4008a7ce:0x3ffb4b00 0x40007c69:0x3ffb4b70 0x40008148:0x3ffb4b90 0x400d51d7:0x3ffb4c20 0x400e31bc:0x3ffb4c50 0x40087bc5:0x3ffb4c80
0x40081656: panic_abort at /Users/espressif/esp-idf/components/esp_system/panic.c:452
0x40085729: esp_system_abort at /Users/espressif/esp-idf/components/esp_system/port/esp_system_chip.c:90
0x4008a7ce: abort at /Users/espressif/esp-idf/components/newlib/abort.c:38
0x40007c69: ets_write_char in ROM
0x40008148: ets_printf in ROM
0x400d51d7: app_main at /Users/espressif/esp-idf/examples/get-started/hello_world/main/hello_world_main.c:49
0x400e31bc: main_task at /Users/espressif/esp-idf/components/freertos/app_startup.c:208 (discriminator 13)
0x40087bc5: vPortTaskWrapper at /Users/espressif/esp-idf/components/freertos/FreeRTOS-Kernel/portable/xtensa/port.c:162
.....
The ROM ELF file is automatically loaded from a location based on the IDF_PATH
and ESP_ROM_ELF_DIR
environment variables. This can be overridden by calling esp_idf_monitor
and providing a path to a specific ROM ELF file: python -m esp_idf_monitor --rom-elf-file [path to ROM ELF file]
.
Note
Set environment variable ESP_MONITOR_DECODE
to 0
or call esp_idf_monitor with specific command line option: python -m esp_idf_monitor --disable-address-decoding
to disable address decoding.
Target Reset on Connection
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.py monitor --no-reset
).
Note
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
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.
A target can be configured to run GDBStub in the background by setting the CONFIG_ESP_SYSTEM_GDBSTUB_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.
Furthermore, the panic handler can be configured to run GDBStub on a crash by setting the 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.
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).
Note
In the background, IDF Monitor runs the following command to launch GDB:
xtensa-esp32s3-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf :idf_target:`Hello NAME chip`
Output Filtering
IDF monitor can be invoked as idf.py monitor --print-filter="xyz"
, where --print-filter
is the parameter for output filtering. The default value is an empty string, which means that everything is printed. Filtering can also be configured using the ESP_IDF_MONITOR_PRINT_FILTER
environment variable.
Note
When using both the environment variable ESP_IDF_MONITOR_PRINT_FILTER
and the argument --print-filter
, the setting from the CLI argument will take precedence.
Restrictions on what to print can be specified as a series of <tag>:<log_level>
items where <tag>
is the tag string and <log_level>
is a character from the set {N, E, W, I, D, V, *}
referring to a level for logging.
For example, --print_filter="tag1:W"
matches and prints only the outputs written with ESP_LOGW("tag1", ...)
or at lower verbosity level, i.e., ESP_LOGE("tag1", ...)
. Not specifying a <log_level>
or using *
defaults to a Verbose level.
Note
Use primary logging to disable at compilation the outputs you do not need through the logging library. Output filtering with the IDF monitor is a secondary solution that can be useful for adjusting the filtering options without recompiling the application.
Your app tags must not contain spaces, asterisks *
, or colons :
to be compatible with the output filtering feature.
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:
*
can be used to match any tags. However, the string--print_filter="*:I tag1:E"
with regards totag1
prints errors only, because the rule fortag1
has a higher priority over the rule for*
.The default (empty) rule is equivalent to
*:V
because matching every tag at the Verbose level or lower means matching everything."*:N"
suppresses not only the outputs from logging functions, but also the prints made byprintf
, etc. To avoid this, use*:E
or a higher verbosity level.Rules
"tag1:V"
,"tag1:v"
,"tag1:"
,"tag1:*"
, and"tag1"
are equivalent.Rule
"tag1:W tag1:E"
is equivalent to"tag1:E"
because any consequent occurrence of the same tag name overwrites the previous one.Rule
"tag1:I tag2:W"
only printstag1
at the Info verbosity level or lower andtag2
at the Warning verbosity level or lower.Rule
"tag1:I tag2:W tag3:N"
is essentially equivalent to the previous one becausetag3:N
specifies thattag3
should not be printed.tag3:N
in the rule"tag1:I tag2:W tag3:N *:V"
is more meaningful because withouttag3:N
thetag3
messages could have been printed; the errors fortag1
andtag2
will be printed at the specified (or lower) verbosity level and everything else will be printed by default.
A More Complex Filtering Example
The following log snippet was acquired without any filtering options:
load:0x40078000,len:13564
entry 0x40078d4c
E (31) esp_image: image at 0x30000 has invalid magic byte
W (31) esp_image: image at 0x30000 has invalid SPI mode 255
E (39) boot: Factory app partition is not bootable
I (568) cpu_start: Pro cpu up.
I (569) heap_init: Initializing. RAM available for dynamic allocation:
I (603) cpu_start: Pro cpu start user code
D (309) light_driver: [light_init, 74]:status: 1, mode: 2
D (318) vfs: esp_vfs_register_fd_range is successful for range <54; 64) and VFS ID 1
I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0
The captured output for the filtering options --print_filter="wifi esp_image:E light_driver:I"
is given below:
E (31) esp_image: image at 0x30000 has invalid magic byte
I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0
The options --print_filter="light_driver:D esp_image:N boot:N cpu_start:N vfs:N wifi:N *:V"
show the following output:
load:0x40078000,len:13564
entry 0x40078d4c
I (569) heap_init: Initializing. RAM available for dynamic allocation:
D (309) light_driver: [light_init, 74]:status: 1, mode: 2
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: [
, ]
, \
, ^
, _
.
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:
Option Name |
Description |
Default Value |
---|---|---|
menu_key |
Key to access the main menu. |
|
exit_key |
Key to exit the monitor. |
|
chip_reset_key |
Key to initiate a chip reset. |
|
recompile_upload_key |
Key to recompile and upload. |
|
recompile_upload_app_key |
Key to recompile and upload just the application. |
|
toggle_output_key |
Key to toggle the output display. |
|
toggle_log_key |
Key to toggle the logging feature. |
|
toggle_timestamp_key |
Key to toggle timestamp display. |
|
chip_reset_bootloader_key |
Key to reset the chip to bootloader mode. |
|
exit_menu_key |
Key to exit the monitor from the menu. |
|
skip_menu_key |
Pressing the menu key can be skipped for menu commands. |
|
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.
# 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
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.