pio device monitor

Usage

pio device monitor [OPTIONS]

Description

This is a console application that provides a small terminal application. It is based on Miniterm and itself does not implement any terminal features such as VT102 compatibility. However it inherits these features from the terminal it is run. For example on GNU/Linux running from an xterm it will support the escape sequences of the xterm. On Windows the typical console window is dumb and does not support any escapes. When ANSI.sys is loaded it supports some escapes.

Miniterm supports RFC 2217 remote serial ports and raw sockets using URL Handlers such as rfc2217://<host>:<port> respectively socket://<host>:<port> as port argument when invoking.

To control monitor please use these “hot keys”:

• Ctrl+C Quit

• Ctrl+T Menu

• Ctrl+T followed by Ctrl+H Help

Options

-p, --port

The possible values are the same as documented for monitor_port option.

-b, --baud

Set baud rate, default 9600.

Can be customized in “platformio.ini” (Project Configuration File) using monitor_speed option.

--parity

Set parity (None, Even, Odd, Space, Mark), one of [N, E, O, S, M], default is N.

Can be customized in “platformio.ini” (Project Configuration File) using monitor_parity option.

--rtscts

Enable RTS/CTS flow control.

--xonxoff

Enable software flow control.

--rts

Set initial RTS line state (0 or 1).

Can be customized in “platformio.ini” (Project Configuration File) using monitor_rts option.

--dtr

Set initial DTR line state (0 or 1).

Can be customized in “platformio.ini” (Project Configuration File) using monitor_dtr option.

--echo

Enable local echo.

Can be customized in “platformio.ini” (Project Configuration File) using monitor_echo option.

--encoding

Set the encoding for the serial port (e.g. hexlify, Latin-1, UTF-8), default UTF-8. See the full list of supported encodings.

Can be customized in “platformio.ini” (Project Configuration File) using monitor_encoding option.

-f, --filter

Add text transformation. See available filters at Filters.

--eol

End of line mode (CR, LF or CRLF), default CRLF.

Can be customized in “platformio.ini” (Project Configuration File) using monitor_eol option.

--raw

Do not apply any encodings/transformations.

Can be customized in “platformio.ini” (Project Configuration File) using monitor_raw option.

--exit-char

ASCII code of special character that is used to exit the application, default 3 (DEC, Ctrl+C).

For example, to use Ctrl+] run pio device monitor --exit-char 29.

--menu-char

ASCII code of special character that is used to control miniterm (menu), default 20 (DEC)

---quiet

Diagnostics: suppress non-error messages, default Off.

--no-reconnect

Disable automatic reconnection if the established connection fails.

-d, --project-dir

Specify the path to project directory. By default, --project-dir is equal to current working directory (CWD).

-e, --environment

Process specified environments.

You can also specify which environments should be processed by default using default_envs option from “platformio.ini” (Project Configuration File).

Filters

PlatformIO allows you to apply multiple filters to the device monitor INPUT & OUTPUT streams using the pio device monitor --filter command or monitor_filters option.

Built-in Filters

Name	Description
direct	Do-nothing: forward all data unchanged. Useful if data already contains ANSI escape codes (colors)
default	Remove typical terminal control codes from input
debug	Print what is sent and received
hexlify	Show a hexadecimal representation of the data (code point of each character)
log2file	Log data to a file “platformio-device-monitor-%date%.log” located in the current working directory
nocontrol	Remove all control codes, incl. CR+LF
printable	Show decimal code for all non-ASCII characters and replace most control codes
time	Add timestamp with milliseconds for each new line
send_on_enter	Send a text to device on ENTER
esp32_exception_decoder	Custom filter for Espressif 32 which decodes crash exception
esp8266_exception_decoder	Custom filter for Espressif 8266 which decodes crash exception

Community Filters

The Community Filters are not a part of PlatformIO Core installation. You need to install them manually. Please visit an official filter’s documentation on how to use it.

Name	Description
arduplot	Serial Plotter compatible with Arduino syntax (output)

Custom Filters

PlatformIO Core (CLI) provides an API to extend device monitor with custom filters. Each filter is a Python-based file and its name should have the filter_ prefix. In a Python code, you need to extend DeviceMonitorFilterBase class to get access to the rx() and tx() methods/callbacks.

PlatformIO Core (CLI) looks for the custom filters in the next locations:

• Project monitor_dir

• platforms_dir/<platform>/monitor

• packages_dir/<package>/monitor

See the base API below:

filter_demo.py

from platformio.public import DeviceMonitorFilterBase


class Demo(DeviceMonitorFilterBase):
    NAME = "demo"

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        print("Demo filter is loaded")

    def rx(self, text):
        return f"Received: {text}\n"

    def tx(self, text):
        print(f"Sent: {text}\n")
        return text

Examples

• https://github.com/platformio/platformio-core/tree/develop/platformio/device/monitor/filters

• https://github.com/platformio/platform-espressif32/tree/develop/monitor

• https://github.com/platformio/platform-espressif8266/tree/develop/monitor

Capture output to a file

To capture the output of the device monitor in a file, you can use the log2file filter from Filters. By default, the log file will be saved in the logs folder located in the project root directory.

> pio device monitor -f default -f log2file

Or using “platformio.ini” (Project Configuration File) and monitor_filters

[env:log_output_to_file]
...
platform = ...
monitor_filters = default, log2file

Examples

1. Show available options for monitor

> pio device monitor --help
Usage: pio device monitor [OPTIONS]

Options:
  -p, --port TEXT       Port, a number or a device name
  -b, --baud INTEGER    Set baud rate, default=9600
  --parity [N|E|O|S|M]  Set parity, default=N
  --rtscts              Enable RTS/CTS flow control, default=Off
  --xonxoff             Enable software flow control, default=Off
  --rts [0|1]           Set initial RTS line state, default=0
  --dtr [0|1]           Set initial DTR line state, default=0
  --echo                Enable local echo, default=Off
  --encoding TEXT       Set the encoding for the serial port (e.g. hexlify,
                        Latin1, UTF-8), default: UTF-8
  -f, --filter TEXT     Add filters / text transformation
  --eol [CR|LF|CRLF]    End of line mode, default=CRLF
  --raw                 Do not apply any encodings/transformations
  --exit-char INTEGER   ASCII code of special character that is used to exit
                        the application, default=29 (DEC)
  --menu-char INTEGER   ASCII code of special character that is used to
                        control miniterm (menu), default=20 (DEC)
  --quiet               Diagnostics: suppress non-error messages, default=Off
  -h, --help            Show this message and exit.

2. Communicate with serial device and print help inside terminal

> pio device monitor

--- Available ports:
--- /dev/cu.Bluetooth-Incoming-Port n/a
--- /dev/cu.Bluetooth-Modem n/a
--- /dev/cu.SLAB_USBtoUART CP2102 USB to UART Bridge Controller
--- /dev/cu.obd2ecu-SPPDev n/a
Enter port name:/dev/cu.SLAB_USBtoUART
--- Miniterm on /dev/cu.SLAB_USBtoUART: 9600,8,N,1 ---
--- Quit: Ctrl+C  |  Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
Hello PlatformIO!
---
--- Ctrl+]   Exit program
--- Ctrl+T   Menu escape key, followed by:
--- Menu keys:
---    Ctrl+T  Send the menu character itself to remote
---    Ctrl+]  Send the exit character itself to remote
---    Ctrl+I  Show info
---    Ctrl+U  Upload file (prompt will be shown)
--- Toggles:
---    Ctrl+R  RTS          Ctrl+E  local echo
---    Ctrl+D  DTR          Ctrl+B  BREAK
---    Ctrl+L  line feed    Ctrl+A  Cycle repr mode
---
--- Port settings (Ctrl+T followed by the following):
---    p          change port
---    7 8        set data bits
---    n e o s m  change parity (None, Even, Odd, Space, Mark)
---    1 2 3      set stop bits (1, 2, 1.5)
---    b          change baud rate
---    x X        disable/enable software flow control
---    r R        disable/enable hardware flow control
--- exit ---