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. |
| - 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 and DTR lines | Reset 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 | Reset the target board and re-starts the application via the RTS line (if connected). |
| - Ctrl + F | Build and flash the project | Pause 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 | Pause 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 | Discard 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 | Create 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 | Pause 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.
Automatic Coloring
IDF Monitor automatically colors the output based on the log level. This feature reduces the number of bytes transferred over the serial console by avoiding redundant log formatting, which can improve performance by reducing latency in log transmission. Other benefits include adding colors to precompiled libraries (such as Wi-Fi) and reduced binary size of the application.
The automatic coloring is enabled by default. To disable it, use the command line option --disable-auto-color.
The coloring is done based on the log level followed by optional timestamp and tag. For option to enable coloring on the ESP32 side, see CONFIG_LOG_COLORS.
For more details on the log, see Logging.
Note
The automatic coloring will not work properly if the message contains new lines. In this case the IDF Monitor will only color the first line of the message.
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). You can also set the environment variable ESP_IDF_MONITOR_NO_RESET to 1 to achieve the same behavior.
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]).