espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-07-30 02:37:19 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs(tools/idf-monitor): Add note about autocoloring limitation on multiline logs

Browse Source 
Closes https://github.com/espressif/esp-idf/issues/15793
This commit is contained in:
Peter Dragun
2025-04-29 10:30:06 +02:00
committed by BOT
parent 7aabeaeab9
commit 9859f5e690
2 changed files with 23 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
components/log/Kconfig.format
View File

@ -8,6 +8,9 @@ menu "Format"
Enable ANSI terminal color codes. Logs (info, errors, warnings) will contain color codes.
In order to view these, your terminal program must support ANSI color codes.
This is disabled by default, as colors are added in IDF Monitor. If you want to use new lines
in the messages or you are using a different terminal program, you may want to enable this option.
config LOG_COLORS_SUPPORT
bool "Allow enabling color output at run time"
depends on LOG_VERSION_2

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

@ -40,10 +40,10 @@ For easy interaction with IDF Monitor, use the keyboard shortcuts given in the t
- 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.
@ -66,6 +66,21 @@ For easy interaction with IDF Monitor, use the keyboard shortcuts given in the t
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 {IDF_TARGET_NAME} side, see :ref:`CONFIG_LOG_COLORS`.
For more details on the log, see :doc:`Logging <../../api-reference/system/log>`.
.. 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.
ESP-IDF-specific Features
=========================
@ -351,6 +366,9 @@ Known Issues with IDF Monitor
The following issues are currently known:
- Autocoloring cannot detect the log level if the message contains new lines. In this case, the IDF Monitor will only color the first line of the message.
To work around this issue, enable :ref:`CONFIG_LOG_COLORS` in menuconfig. Please note that this might have some impact on binary size and performance.
- On Windows, if the terminal is closed without first closing the IDF Monitor, some drivers may fail to release the serial port. To release the port, you may need to unplug and replug the USB cable, or in some cases even restart the computer. This issue has been observed with the CH9102 USB-to-UART bridge. Other drivers, such as CP210x and CH340, should work fine.
To prevent this issue, make sure to close the IDF Monitor properly before exiting the terminal, or consider using an alternative USB-to-UART bridge.