The idf_monitor tool is a Python program which runs when the ``idf.py monitor`` target is invoked in IDF.
It is mainly a serial terminal program which relays serial data to and from the target device's serial port, but it has some other IDF-specific features.
Interacting With IDF Monitor
============================
-``Ctrl-]`` will exit the monitor.
-``Ctrl-T Ctrl-H`` will display a help menu with all other keyboard shortcuts.
- Any other key apart from ``Ctrl-]`` and ``Ctrl-T`` is sent through the serial port.
Automatically Decoding Addresses
================================
Any time esp-idf prints a hexadecimal code address of the form ``0x4_______``, IDF Monitor will use addr2line_ to look up the source code location and function name.
..highlight:: none
When an esp-idf app crashes and panics a register dump and backtrace such as this is produced::
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
By default, if an esp-idf app crashes then the panic handler prints registers and a stack dump as shown above, and then resets.
Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required.
If this option is enabled and IDF Monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.)
Behind the scenes, the command IDF Monitor runs is::
The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause idf_monitor, run the ``idf.py flash`` target, then resume idf_monitor. Any changed source files will be recompiled before re-flashing.
The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause idf-monitor, run the ``idf.py app-flash`` target, then resume idf_monitor. This is similar to ``idf.py flash``, but only the main app is compiled and reflashed.
Quick Reset
===========
The keyboard shortcut ``Ctrl-T Ctrl-R`` will reset the target board via the RTS line (if it is connected.)
Pause the Application
=====================
The keyboard shortcut ``Ctrl-T Ctrl-P`` will reset the target into bootloader, so that the board will run nothing. This is
useful when you want to wait for another device to startup. Then shortcut ``Ctrl-T Ctrl-R`` can be used to restart the
application.
Toggle Output Display
=====================
Sometimes you may want to stop new output printed to screen, to see the log before. The keyboard shortcut ``Ctrl-T Ctrl-Y`` will
toggle the display (discard all serial data when the display is off) so that you can stop to see the log, and revert
again quickly without quitting the monitor.
Simple Monitor
==============
Earlier versions of ESP-IDF used the pySerial_ command line program miniterm_ as a serial console program.
This program can still be run, via ``make simple_monitor``.
IDF Monitor is based on miniterm and shares the same basic keyboard shortcuts.
..note:: This target only works in the GNU Make based build system, not the CMake-based build system preview.
Known Issues with IDF Monitor
=============================
Issues Observed on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~
- If you are using the supported Windows environment and receive the error "winpty: command not found" then run ``pacman -S winpty`` to fix.
- Arrow keys and some other special keys in gdb don't work, due to Windows Console limitations.
- Occasionally when "make" exits, it may stall for up to 30 seconds before idf_monitor resumes.
- Occasionally when "gdb" is run, it may stall for a short time before it begins communicating with the gdbstub.
