7 releases
0.0.7 | Jan 6, 2021 |
---|---|
0.0.6 | Jan 6, 2021 |
0.0.5 | May 7, 2020 |
0.0.4 | Apr 29, 2020 |
#1855 in Command line utilities
34KB
584 lines
serial-monitor
A serial monitor for USB Serial devices, written in rust.
serial-monitor
is a command line program which will connect to, and allow you to
interact with USB serial devices connected to your host computer. It has been tested on
Mac OSX, Linux and Windows.
You can use the --list
option to display all of the detected USB serial
devices, and you can use the --vid
, --pid
, --port
, --serial
,
--manufacturer
, or --product
options to filter your list.
serial-monitor
will open the first USB serial port which satifies the
filtering criteria.
Once connected, you can use Control-X (or Control-Y if started with the -y
option)
to exit from serial-monitor
and return you to your prompt.
Installation
Install rust. The recommended way is to use rustup.
Once rust is installed you can install directly from crates.io by using:
cargo install serial-monitor
This installs serial-monitor into ~/.cargo/bin
If you want to build and install from source locally, then clone the repository:
git clone https://github.com/dhylands/serial-monitor.git
cd serial-monitor
You can then build and install serial-monitor
using:
cargo install --path .
This will build serial-monitor
and install it into ~/.cargo/bin
Usage
$ serial-monitor --help
serial-monitor 0.0.5
USAGE:
serial-monitor.exe [FLAGS] [OPTIONS]
FLAGS:
-y Exit using Control-Y rather than Control-X
-d, --debug Turn on debugging
-e, --echo
-f, --find Like list, but only prints the name of the port that was found. This is
useful for using from scripts or makefiles
-h, --help Prints help information
-l, --list List USB serial devices which are currently connected
-V, --version Prints version information
-v, --verbose Turn on verbose messages
OPTIONS:
-b, --baud <baud> Baud rate to use [default: 115200]
--databits <databits> Data bits (5, 6, 7, 8) [default: 8]
--enter <enter> Enter character to send (cr, lf, crlf) [default: cr]
--flow <flow> Flow control (none, software, hardware) [default: none]
--index <index> Return the index'th result
-m, --manufacturer <manufacturer> Filter based on manufacturer name
--parity <parity> Parity checking (none, odd, even) [default: none]
--pid <pid> Filter based on Product ID (PID)
-p, --port <port> Filter based on name of port
--product <product> Filter based on product name
-s, --serial <serial> Filter based on serial number
--stopbits <stopbits> Stop bits (1, 2) [default: 1]
--vid <vid> Filter based on Vendor ID (VID)
The --list
(or -l
) option will list all of the connected USB Serial Adapters, for example:
$ serial-monitor --list
USB Serial Device f055:9800 with manufacturer 'MicroPython' serial '336F338F3433' product 'Pyboard Virtual Comm Port in FS Mode' found @/dev/cu.usbmodem336F338F34332
USB Serial Device 0403:6001 with manufacturer 'FTDI' serial 'A700e6Lr' product 'FT232R USB UART' found @/dev/cu.usbserial-A700e6Lr
Monitoring the serial port
To connect to the MicroPython board (assuming the list shown above), you might do: serial-monitor -m Micro
or perhaps serial-monitor --vid f055
.
You can experiment with filtering options by combining with the --list
option which will only show you the USB Serial Adapters which
match the filter criteria.
Once you're connected you should see something like the following:
Connected to /dev/cu.usbmodem336F338F34332
Press Control-X to exit
MicroPython v1.11-47-g1a51fc9dd on 2019-06-18; PYBv1.1 with STM32F405RG
Type "help()" for more information.
>>>
To exit from serial-monitor
use Control-X (or Control-Y if you started with the -y
option). Using Control-X allows characters like Control-C and Control-D
to be passed on to the device on the serial port.
Filtering ports
You can use the --vid
, --pid
, --port
, --serial
, --manufacturer
, or --product
options to filter the selection of the serial ports.
All of these options allow the use of *
or ?
wildcards. Note that you'll probably need to quote these to prevent your shell from expanding them.
*
means to match 0 or more characters and ?
means to match one character. If you don't specify any wildcards then it is assumed that there is a *
at the beginning and the end of the string. So --product FS
will behave as if you had typed --product '*FS*'
.
The --index
option can be used to return the index'th result. This is useful for devices like the Black Magic Probe which return multiple
serial ports which all have identical attributes.
Finding ports from within a script
The --find
option behaves very similary to the --list
command, but it only displays the port name of the first port found.
For example, serial-monitor --list
might show:
USB Serial Device 1d50:6018 with manufacturer 'Black Sphere Technologies' serial '7ABA4DC1' product 'Black Magic Probe' found @/dev/cu.usbmodem7ABA4DC11
USB Serial Device 1d50:6018 with manufacturer 'Black Sphere Technologies' serial '7ABA4DC1' product 'Black Magic Probe' found @/dev/cu.usbmodem7ABA4DC13
and the command serial-monitor --find --product 'Black Magic Probe' --index 0
would show:
/dev/cu.usbmodem7ABA4DC11
This can be quite useful from within a script:
GDB_PORT = $(serial-monitor --find --product 'Black Magic Probe' --index 0)
arm-none-eabi-gdb -ex 'target extended-remote ${GDB_PORT}' -x gdbinit myprogram.elf
Supporting Home/End keys on Mac OS
On the regular Mac keyboard Fn-Left generates ESC [ H
(which corresponds to Home) and
Fn-Right generates ESC [ F
(which corresponds to End). For some reason, pressing the
Home and End keys on an external keyboard are mapped to ESC O H
and ESC O F
and
crossterm wasn't reporting any events when these keys were pressed. If you go into
Terminal->Preferences, select your Profile and then the Keyboard tab, you can change
Home from ESC O H
to be ESC [ H
and End from ESC O F
to be ESC [ F
then the
Home and End keys are reported properly via crossterm. Here's a picture of what the
Home and End keys look like in the Keyboard tab:
This has the nice side-effect of making the Home/End keys work properly in bash in the Mac's Terminal window as well.
Dependencies
~13MB
~221K SLoC