pio device monitor [OPTIONS]
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
The possible values are the same as documented for monitor_port option.
Set baud rate, default 9600.
Can be customized in “platformio.ini” (Project Configuration File) using monitor_speed option.
Set parity (None, Even, Odd, Space, Mark), one of
[N, E, O, S, M], default N
Enable RTS/CTS flow control, default Off
Enable software flow control, default Off
Set initial RTS line state (0 or 1).
Can be customized in “platformio.ini” (Project Configuration File) using monitor_rts option.
Set initial DTR line state (0 or 1).
Can be customized in “platformio.ini” (Project Configuration File) using monitor_dtr option.
Enable local echo, default Off
Set the encoding for the serial port (e.g. hexlify, Latin1, UTF-8),
default UTF-8.
Add text transformation. See available filters at Filters.
End of line mode (CR, LF or CRLF), default CRLF
NEW: Available in Miniterm/PySerial 3.0
Do not apply any encodings/transformations
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.
ASCII code of special character that is used to control miniterm (menu),
default 20 (DEC)
Diagnostics: suppress non-error messages, default Off
Specify the path to project directory. By default, --project-dir is equal
to current working directory (CWD).
Process specified environments.
You can also specify which environments should be processed by default using default_envs option from “platformio.ini” (Project Configuration File).
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.
Name |
Description |
|---|---|
|
Remove typical terminal control codes from input |
|
Apply different colors for received and echo |
|
Print what is sent and received |
|
Do-nothing: forward all data unchanged |
|
Show a hexadecimal representation of the data (code point of each character) |
|
Log data to a file “platformio-device-monitor-%date%.log” located in the current working directory |
|
Remove all control codes, incl. CR+LF |
|
Show decimal code for all non-ASCII characters and replace most control codes |
|
Add timestamp with milliseconds for each new line |
|
Send a text to device on ENTER |
|
Custom filter for Espressif 32 which decodes crash exception |
|
Custom filter for Espressif 8266 which decodes crash exception |
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 |
|---|---|
Serial Plotter compatible with Arduino syntax (output) |
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.shared 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
You need to use a log2file filter from Filters:
> pio device monitor -f log2file -f default
or using “platformio.ini” (Project Configuration File) and monitor_filters
[env:log_output_to_file]
...
platform = ...
monitor_filters = log2file, default
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.
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 ---