1tio(1) User Commands tio(1)
2
6 tio - a simple serial device I/O tool
7
10 tio [<options>] <tty-device|sub-config>
11
14 tio is a simple serial device tool which features a straightforward
15 command-line and configuration file interface to easily connect to se‐
16 rial TTY devices for basic I/O operations.
17
20 -b, --baudrate <bps>
21 Set baud rate [bps] (default: 115200).
23 -d, --databits 5|6|7|8
25 Set data bits (default: 8).
27 -f, --flow hard|soft|none
29 Set flow control (default: none).
31 -s, --stopbits 1|2
33 Set stop bits (default: 1).
35 -p, --parity odd|even|none|mark|space
37 Set parity (default: none).
39 Note: With mark parity the parity bit is always 0. With space
41 parity the parity bit is always 1. Not all platforms support
42 mark and space parity.
43 -o, --output-delay <ms>
46 Set output delay [ms] inserted between each sent character (de‐
48 fault: 0).
49 -O, --output-line-delay <ms>
52 Set output delay [ms] inserted between each sent line (default:
54 0).
55 --line-pulse-duration <duration>
58 Set the pulse duration [ms] of each serial port line using the
60 following key value pair format in the duration field:
61 <key>=<value>
62 Each key represents a serial line. The following keys are avail‐
64 able:
65 DTR Data Terminal Ready
69 RTS Request To Send
71 CTS Clear To Send
73 DSR Data Set Ready
75 DCD Data Carrier Detect
77 RI Ring Indicator
79 If defining more than one key value pair, the pairs must be
81 comma separated.
82 The default pulse duration for each line is 100 ms.
84 -n, --no-autoconnect
87 Disable automatic connect.
89 By default tio automatically connects to the provided device if
91 present. If the device is not present, it will wait for it to
92 appear and then connect. If the connection is lost (eg. device
93 disconnects), it will wait for the device to reappear and then
94 reconnect.
95 However, if the --no-autoconnect option is provided, tio will
97 exit if the device is not present or an established connection
98 is lost.
99 -e, --local-echo
102 Enable local echo.
104 -t, --timestamp
107 Enable line timestamp.
109 --timestamp-format <format>
112 Set timestamp format to any of the following timestamp formats:
114 24hour 24-hour format ("hh:mm:ss.sss")
118 24hour-start 24-hour format relative to start time
120 24hour-delta 24-hour format relative to previous timestamp
122 iso8601 ISO8601 format ("YYYY-MM-DDThh:mm:ss.sss")
124 Default format is 24hour
126 -L, --list-devices
129 List available serial devices by ID.
131 -l, --log
134 Enable log to file.
136 If no filename is provided the filename will be automatically
138 generated.
139 --log-file <filename>
142 Set log filename.
144 --log-strip
147 Strip control characters and escape sequences from log.
149 -m, --map <flags>
152 Map (replace, translate) characters on input or output. The fol‐
154 lowing mapping flags are supported:
155 ICRNL Map CR to NL on input (unless IGNCR is set)
159 IGNCR Ignore CR on input
161 INLCR Map NL to CR on input
163 INLCRNL Map NL to CR-NL on input
165 OCRNL Map CR to NL on output
167 ODELBS Map DEL to BS on output
169 ONLCRNL Map NL to CR-NL on output
171 OLTU Map lowercase characters to uppercase on output
173 MSB2LSB Map MSB bit order to LSB on output
175 If defining more than one flag, the flags must be comma sepa‐
177 rated.
178 -x, --hexadecimal
181 Enable hexadecimal mode.
183 -c, --color 0..255|bold|none|list
186 Colorize tio text using ANSI color code value ranging from 0 to
188 255 or use "none" for no color or use "bold" to apply bold for‐
189 matting to existing system color.
190 Use "list" to print a list of available ANSI color codes.
192 Default value is "bold".
194 -S, --socket <socket>
197 Redirect I/O to socket.
199 Any input from clients connected to the socket is sent on the
201 serial port as if entered at the terminal where tio is running
202 (except that ctrl-t sequences are not recognized), and any input
203 from the serial port is multiplexed to the terminal and all con‐
204 nected clients.
205 Sockets remain open while the serial port is disconnected, and
207 writes will block.
208 Various socket types are supported using the following prefixes
210 in the socket field:
211 unix:<filename> Unix Domain Socket (file)
215 inet:<port> Internet Socket (network)
217 inet6:<port> Internet IPv6 Socket (network)
219 If port is 0 or no port is provided default port 3333 is used.
221 At present there is a hardcoded limit of 16 clients connected at
223 one time.
224 -r, --response-wait
227 Wait for line response then quit. A line is considered any
229 string ending with either CR or NL character. If no line is re‐
230 ceived tio will quit after response timeout.
231 Any tio text is automatically muted when piping a string to tio
233 while in response mode to make it easy to parse the response.
234 --response-timeout <ms>
237 Set timeout [ms] of line response (default: 100).
239 --rs-485
242 Enable RS-485 mode.
244 --rs-485-config <config>
247 Set the RS-485 configuration using the following key or key
249 value pair format in the configuration field:
250 RTS_ON_SEND=value Set logical level (0 or 1) for RTS
254 pin when sending
255 RTS_AFTER_SEND=value Set logical level (0 or 1) for RTS
257 pin after sending
258 RTS_DELAY_BEFORE_SEND=value Set RTS delay (ms) before sending
260 RTS_DELAY_AFTER_SEND=value Set RTS delay (ms) after sending
262 RX_DURING_TX Receive data even while sending
264 data
265 If defining more than one key or key value pair, they must be
267 comma separated.
268 --alert none|bell|blink
271 Set alert action on connect/disconnect.
273 It will sound the bell once or blink once on successful connect.
275 Likewise it will sound the bell twice or blink twice on discon‐
276 nect.
277 Default value is "none".
279 -v, --version
282 Display program version.
284 -h, --help
286 Display help.
288
290 In session, the following key sequences, a prefix key (default: ctrl-t)
291 followed by a command key, are intercepted as tio commands:
292 ctrl-t ? List available key commands
294 ctrl-t b Send serial break (triggers SysRq on Linux, etc.)
296 ctrl-t c Show configuration (baudrate, databits, etc.)
298 ctrl-t e Toggle local echo mode
300 ctrl-t f Toggle log to file
302 ctrl-t F Flush data I/O buffers (discard data written but not
304 transmitted and data received but not read)
305 ctrl-t g Toggle serial port line
307 ctrl-t h Toggle hexadecimal mode
309 ctrl-t l Clear screen
311 ctrl-t L Show line states (DTR, RTS, CTS, DSR, DCD, RI)
313 ctrl-t p Pulse serial port line
315 ctrl-t q Quit
317 ctrl-t s Show TX/RX statistics
319 ctrl-t t Toggle line timestamp mode
321 ctrl-t U Toggle conversion to uppercase on output
323 ctrl-t v Show version
325 ctrl-t ctrl-t Send ctrl-t character
327
330 In hexadecimal mode each incoming byte is printed out as a hexadecimal
331 value.
332 Bytes can be sent in this mode by typing the two-character hexadecimal
335 representation of the value, e.g.: to send 0xA you must type 0a or 0A.
336
339 Options can be set via configuration file using the INI format. tio
340 uses the configuration file first found in the following locations in
341 the order listed:
342 $XDG_CONFIG_HOME/tio/config
345 $HOME/.config/tio/config
347 $HOME/.tioconfig
349 Labels can be used to group settings into named sub-configurations
352 which can be activated from the command-line when starting tio.
353 tio will try to match the user input to a sub-configuration by name or
356 by pattern to get the TTY device and other options.
357 Options without any label change the default options.
360 Any options set via command-line will override options set in the con‐
363 figuration file.
364 The following configuration file options are available:
367 pattern Pattern matching user input. This pattern can
371 be an extended regular expression with a sin‐
372 gle group.
373 device TTY device to open. If it contains a "%s" it
375 is substituted with the first group match.
376 baudrate Set baud rate
378 databits Set data bits
380 flow Set flow control
382 stopbits Set stop bits
384 parity Set parity
386 output-delay Set output character delay
388 output-line-delay Set output line delay
390 line-pulse-duration Set line pulse duration
392 no-autoconnect Disable automatic connect
394 log Enable log to file
396 log-file Set log filename
398 log-strip Enable strip of control and escape sequences
400 from log
401 local-echo Enable local echo
403 timestamp Enable line timestamp
405 timestamp-format Set timestamp format
407 map Map characters on input or output
409 color Colorize tio text using ANSI color code rang‐
411 ing from 0 to 255
412 hexadecimal Enable hexadecimal mode
414 socket Set socket to redirect I/O to
416 prefix-ctrl-key Set prefix ctrl key (a..z, default: t)
418 response-wait Enable wait for line response
420 response-timeout Set line response timeout
422 rs-485 Enable RS-485 mode
424 rs-485-config Set RS-485 configuration
426 alert Set alert action on connect/disconnect
428
431 To change the default configuration simply set options like so:
432 # Defaults
434 baudrate = 9600
435 databits = 8
436 parity = none
437 stopbits = 1
438 color = 10
439 line-pulse-duration = DTR=200,RTS=400
440 Named sub-configurations can be added via labels:
443 [rpi3]
445 device = /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
446 baudrate = 115200
447 color = 11
448 Activate the sub-configuration by name:
451 $ tio rpi3
453 Which is equivalent to:
456 $ tio -b 115200 -c 11 /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FT‐
458 GQVXBL-if00-port0
459 A sub-configuration can also be activated by its pattern which supports
462 regular expressions:
463 [usb device]
465 pattern = usb([0-9]*)
466 device = /dev/ttyUSB%s
467 baudrate = 115200
468 Activate the sub-configuration by pattern match:
471 $ tio usb12
473 Which is equivalent to:
476 $ tio -b 115200 /dev/ttyUSB12
478 It is also possible to combine use of sub-configuration and command-
481 line options. For example:
482 $ tio -l -t usb12
484
487 Typical use is without options:
488 $ tio /dev/ttyUSB0
490 Which corresponds to the commonly used default options:
492 $ tio -b 115200 -d 8 -f none -s 1 -p none /dev/ttyUSB0
494 It is recommended to connect serial TTY devices by ID:
496 $ tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
498 Using serial devices by ID ensures that tio automatically reconnects to
500 the correct serial device if it is disconnected and then reconnected.
501 Redirect serial device I/O to Unix file socket for scripting:
503 $ tio -S unix:/tmp/tmux-socket0 /dev/ttyUSB0
505 Then, to issue a command via the file socket simply do:
508 $ echo "ls -la" | nc -UN /tmp/tmux-socket0 > /dev/null
510 Or use the expect command to script an interaction:
513 #!/usr/bin/expect -f
515 set timeout -1
517 log_user 0
518 spawn nc -UN /tmp/tio-socket0
520 set uart $spawn_id
521 send -i $uart "date\n"
523 expect -i $uart "prompt> "
524 send -i $uart "ls -la\n"
525 expect -i $uart "prompt> "
526 Redirect device I/O to network file socket for remote TTY sharing:
529 $ tio --socket inet:4444 /dev/ttyUSB0
531 Then, use netcat to connect to the shared TTY session over network (as‐
535 suming tio is hosted on IP 10.0.0.42):
536 $ nc -N 10.0.0.42 4444
538 Pipe command to the serial device:
541 $ echo "ls -la" | tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FT‐
543 GQVXBL-if00-port0
544 Pipe command to the serial device and wait for line response (string
547 ending with CR or NL):
548 $ echo "*IDN?" | tio /dev/ttyACM0 --response-wait
550 In this mode, only the response will be printed.
552 Likewise, to pipe data from file to the serial device:
555 $ cat data.bin | tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FT‐
557 GQVXBL-if00-port0
558 Enable RS-485 mode:
561 $ tio --rs-485 --rs-485-config=RTS_ON_SEND=1,RX_DURING_TX
563 /dev/ttyUSB0
564
567 Visit https://tio.github.io
568
571 Created by Martin Lund <martin.lund@keep-it-simple.com>.
572tio 2.5 2022-12-17 tio(1)