Picocom enhancements
Problem
Picocom
is a lightweight, simple terminal
software for working with serial ports. It is good, almost perfect for most tasks
dealing with embedded electronics. However, some features are missing in the stock
version. When bad data come to the port, they are echoed in binary form and the
random control characters then can break the terminal setting and result in weird
character mapping and other oddities; this was a problem especially with the ESP8266
chip, which sends garbage on reset. There was also missing control of the RTS pin.
Solution
Several functions were added in the form of a patch:
- Hex dump - control characters (anything that is <0x20 or >=0x80, and
is not CR and LF) are displayed as [xx] formatted hex numbers. It can be switched off by the --nohex option or extended to all bytes by the --hexall one.
- Hex send - on Ctrl-A Ctrl-H]] an input line shows, allowing entering of a string
of hexadecimal values, with or without separators; these are then translated to binary and sent to the port.
- Colorizing - different messages are shown in colors; by default, system is
yellow, local echo is red, and data from remote are green. Hex numbers are shown in dark (if the foreground is bright) or vice versa.
- Terminal reset - Ctrl-A Ctrl-O runs the "reset" utility, which resets the
terminal. Good when it gets confused by control characters.
- Shell - Ctrl-A Ctrl-Z spawns local shell. Good for quick tasks or lookups
without having to leave the terminal. Can be also used for setting the serial line parameters via e.g. stty, but this may confuse the picocom's port state reporting.
- Real port state reading - on startup, when port is not being reset, its actual
configuration is read from the port's own control structures instead of using fixed assumptions.
- Custom baud rates - the commandline setting now takes an arbitrary speed,
on Ctrl-A G a baud rate can be entered directly. If the value is nonstandard, it is inserted into the array for manual baud rate changes by up/down.
- List of baud rates - the default list of baud rates for manual up/down changes
can be set to custom values or values can be added as a comma-separated list. The --baudlist option replaces the default list, the --baudadd adds the values to the list. Preexisting lists are DEFAULT, CP2101, CP2102, MIDI, and CAN. Up to 64 values can be specified. Handy for easier swapping between few different baud rates.
- Toggling RTS - in addition to toggling and pulsing DTR the software can now
toggle the RTS line, by Ctrl-A Ctrl-E.
- Setting of DTR and RTS - the --dtr 0|1 and --rts 0|1
set the state of the port's outputs to the desired value on startup.
- Port modem line display - on showing of options (Ctrl-A Ctrl-V), and on every
output control line change, the control signal changes are shown.
- Real time monitoring of port modem lines - the select() call is amended with a
timeout, the modem bits are checked, discrepancies are listed; e.g. RI going up is shown as [RI+] , DSR going down is shown as [dsr-] . Can be disabled with --nomodem. Limited to 20 times per second as the call takes time and it throttled faster data flows.
- Key help - on Ctrl-A ? the list of control key combinations is shown.
- Autoargs, configuration sets with port-match or names; -a matches port, -A <name> uses a named configuration
- Stopbits, specify 1 or 2 stopbits; --stopbits 2 selects two stopbits
- Atypical port setting, for MSB-first or inverted-bits systems (common for smartcards)
for --imap, --omap, --emap
[link?:msb] reverses the bit order, so usual LSB-first becomes MSB-first
[link?:inv] inverts bits
(handy for testing smartcards, which require MSB-first, inverted bits, with 2 stopbits) - Loose port name match, keyword match on serial port name.
Command syntax
Example: run picocom on /dev/ttyUSB0, at 115200 bps, with local echo and colors, with DTR high and RTS low:
picocom -b 115200 -c -C --dtr 1 --rts 0 /dev/ttyUSB0
Options:
picocom v1.8-Shad-200714-0147
Usage is: picocom [options] <tty device>
Options for port settings:
--<b>aud <baudrate>
--<f>low <s|h|n> (s=soft=XON/XOFF, h=hardware, n=none=default)
--<p>arity <o|e|n> (o=odd, e=even, n=none=default)
--<d>atabits <5|6|7|8> (8=default)
--<S>topbits <1|2> (1=default, 1.5 not supported)
Options for control lines:
--<D>tr <1|0> (set DTR to value)
--<R>ts <1|0> (set RTS to value)
--nomodem (do not check for control lines changes)
Options for terminal:
--<e>scape <char> (ctrl-char as escape, default 'a')
--e<c>ho (local echo)
--no<i>nit (do not initialize port)
--no<r>eset (do not reset port)
--no<l>ock (do not lock port)
--color (-C), --colorbright (-B)
--baudadd <list_of_baudrates|set_name>
--baudlist <list_of_baudrates|set_name>
--lf<w>ait <msec> (forced wait after CR/LF from terminal)
--autol<f> <msec> (newline after inactivity, for chunked data)
--nohex, --hexall (disable hex byte display or force for all)
--imap <map> (input mappings)
--omap <map> (output mappings)
--emap <map> (local-echo mappings)
--<s>end-cmd <command>
--recei<v>e-cmd <command>
General options:
--<A>utoargs <name> (set arguments by name from picocom_autoport)
--<a>utoport (set by keyword match on port name from picocom_autoport)
--<h>elp
<map> is a comma-separated list of one or more of:
crlf : map CR --> LF
crcrlf : map CR --> CR + LF
igncr : ignore CR
lfcr : map LF --> CR
lfcrlf : map LF --> CR + LF
ignlf : ignore LF
bsdel : map BS --> DEL
delbs : map DEL --> BS
swcase : lowercase <--> uppercase
hexmap : show unprintable (or all) bytes as hex values
msb : bit order MSB first (usual LSB first)
inv : invert bit values
<?> indicates the equivalent short option.
Short options are prefixed by "-" instead of by "--". Long are all lowercase.
Autoargs, loose matches
Sets of commandline arguments can be predefined to automatically match desired devices. The definitions are stored in
configuration file that can be placed in three locations; ./.picocom-autoargs, ~/.picocom-autoargs, and /etc/picocom-autoargs, looked up
in this order.
Autoargs from port name
For match of options to port name, use argument -a.
The directives are placed in the files in the format of <match-spec><match-string> <...arguments...>.
The match spec for port name determines if the keyword has to match the port name partially anywhere (**), or if it has to match only the end part of the string (*).
"*ttyUSB1" will match /dev/ttyUSB1 but not /dev/ttyUSB12, while "**ttyUSB1" will match both.
This is especially useful for meaningful port names, e.g. those populated as symlinks in /dev/serial/by-id/.
With configurable device namem strings in some USB-serial chips, matching names and rules conventions can be established. Eg. match on "_2400bps_" can be set to
automatically specify -b 2400. (Todo, allow more submatches, do not stop on the first one.)
Named autoarg sets
One or more option sets to match can be specified by -A <name>.
The match spec for named argument has to match fully, and starts with "$". "$esp" can be used for a set of configs
usual for the ESP8266 modules.
For more than one name, comma is used as a delimiter.
Parameter sets are looked up in the order of their specification. If a match on port should be done, _PORT is used as an equivalent of -a, in forced sequence position.
For more detailed reporting of matches and files accessed, -v or -V can be added to the beginning of the names string.
Loose port names
If there is no direct match on the port name specified, a keyword match gets performed in /dev/serial/by-id/ directory.
Exactly one match has to exist. More or less, and the program fails with listing of the possibilities available.
Downloads
Version compiled at
Tue Jul 14 01:47:54 CEST 2020
The binary is compiled for PC Linux, using gcc-4.9.2.
Compiling for Raspberry Pi (armhf architecture) was uneventful; make did the job smoothly. Binaries of the version of code compiled at Sat Mar 3 10:24:27 CET 2018:
Changes
A fault was found in the select() call, where the timeout for checking modem flags was specified in microseconds instead of in nanoseconds (some odd specs shenanigans).
The changes were therefore read 10,000 times per second instead of 10 times. This was very noticeably slowing the code on slower machines, namely raspberry pi.
The term_get_modem_flags was unnecessarily calling term_find, iterating through the term structure without need to.
250000 and 500000 were added to list of default baudrates.
Reading from port was done via a 64-byte buffer, to significantly increase speed at 115k2.
Code notes
No warranty, it's software and so it has more bugs than an anthill. Original code is GPLv2
, this naturally follows.
Custom baud rates are implemented by using term.c from jmesmon's fork, here.
The files are:
TODO
- maybe a line interface with command history (readline?) - ctrl-L for entering a line with command history, allow history file?
(with a #define in source code, to avoid need for libreadline and to avoid additional memory footprint), allow some escape sequences for entering hex bytes (maybe "[01]" as send 0x01, "\[01]" as send "[01]"?)
- in hexall mode, generate new line on a timeout (to show binary data that come in chunks)
- maybe populating the baudrates field from a command, for CAN bus, MIDI, DMX, and other buses
- screenshots of the terminal window
| If you have any comments or questions about the topic, please let me know here: |
- source and binary archive of the entire version