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 The filename will be automatically generated using the following
138 format tio_DEVICE_YYYY-MM-DDTHH:MM:SS.log.
139 The filename can be manually set using the --log-file option.
141 --log-file <filename>
144 Set log filename.
146 --log-append
149 Append to log file.
151 --log-strip
154 Strip control characters and escape sequences from log.
156 -m, --map <flags>
159 Map (replace, translate) characters on input or output. The fol‐
161 lowing mapping flags are supported:
162 ICRNL Map CR to NL on input (unless IGNCR is set)
166 IGNCR Ignore CR on input
168 INLCR Map NL to CR on input
170 INLCRNL Map NL to CR-NL on input
172 OCRNL Map CR to NL on output
174 ODELBS Map DEL to BS on output
176 ONLCRNL Map NL to CR-NL on output
178 OLTU Map lowercase characters to uppercase on output
180 MSB2LSB Map MSB bit order to LSB on output
182 If defining more than one flag, the flags must be comma sepa‐
184 rated.
185 -x, --hexadecimal
188 Enable hexadecimal mode.
190 -c, --color 0..255|bold|none|list
193 Colorize tio text using ANSI color code value ranging from 0 to
195 255 or use "none" for no color or use "bold" to apply bold for‐
196 matting to existing system color.
197 Use "list" to print a list of available ANSI color codes.
199 Default value is "bold".
201 -S, --socket <socket>
204 Redirect I/O to socket.
206 Any input from clients connected to the socket is sent on the
208 serial port as if entered at the terminal where tio is running
209 (except that ctrl-t sequences are not recognized), and any input
210 from the serial port is multiplexed to the terminal and all con‐
211 nected clients.
212 Sockets remain open while the serial port is disconnected, and
214 writes will block.
215 Various socket types are supported using the following prefixes
217 in the socket field:
218 unix:<filename> Unix Domain Socket (file)
222 inet:<port> Internet Socket (network)
224 inet6:<port> Internet IPv6 Socket (network)
226 If port is 0 or no port is provided default port 3333 is used.
228 At present there is a hardcoded limit of 16 clients connected at
230 one time.
231 -r, --response-wait
234 Wait for line response then quit. A line is considered any
236 string terminated with a NL character. If no line is received
237 tio will quit after response timeout.
238 Any tio text is automatically muted when piping a string to tio
240 while in response mode to make it easy to parse the response.
241 --response-timeout <ms>
244 Set timeout [ms] of line response (default: 100).
246 --rs-485
249 Enable RS-485 mode.
251 --rs-485-config <config>
254 Set the RS-485 configuration using the following key or key
256 value pair format in the configuration field:
257 RTS_ON_SEND=value Set logical level (0 or 1) for RTS
261 pin when sending
262 RTS_AFTER_SEND=value Set logical level (0 or 1) for RTS
264 pin after sending
265 RTS_DELAY_BEFORE_SEND=value Set RTS delay (ms) before sending
267 RTS_DELAY_AFTER_SEND=value Set RTS delay (ms) after sending
269 RX_DURING_TX Receive data even while sending
271 data
272 If defining more than one key or key value pair, they must be
274 comma separated.
275 --alert none|bell|blink
278 Set alert action on connect/disconnect.
280 It will sound the bell once or blink once on successful connect.
282 Likewise it will sound the bell twice or blink twice on discon‐
283 nect.
284 Default value is "none".
286 -v, --version
289 Display program version.
291 -h, --help
293 Display help.
295
297 In session, all key strokes are forwarded to the serial device except
298 the following key sequence: a prefix key (default: ctrl-t) followed by
299 a command key. These sequences are intercepted as tio commands:
300 ctrl-t ? List available key commands
302 ctrl-t b Send serial break (triggers SysRq on Linux, etc.)
304 ctrl-t c Show configuration (baudrate, databits, etc.)
306 ctrl-t e Toggle local echo mode
308 ctrl-t f Toggle log to file
310 ctrl-t F Flush data I/O buffers (discard data written but not
312 transmitted and data received but not read)
313 ctrl-t g Toggle serial port line
315 ctrl-t h Toggle hexadecimal mode
317 ctrl-t l Clear screen
319 ctrl-t L Show line states (DTR, RTS, CTS, DSR, DCD, RI)
321 ctrl-t m Toggle MSB to LSB bit order
323 ctrl-t p Pulse serial port line
325 ctrl-t q Quit
327 ctrl-t s Show TX/RX statistics
329 ctrl-t t Toggle line timestamp mode
331 ctrl-t U Toggle conversion to uppercase on output
333 ctrl-t v Show version
335 ctrl-t x Send a file using the XMODEM protocol (prompts for file
337 name)
338 ctrl-t y Send a file using the YMODEM protocol (prompts for file
340 name)
341 ctrl-t ctrl-t Send ctrl-t character
343
346 In hexadecimal mode each incoming byte is printed out as a hexadecimal
347 value.
348 Bytes can be sent in this mode by typing the two-character hexadecimal
351 representation of the value, e.g.: to send 0xA you must type 0a or 0A.
352
355 Options can be set via configuration file using the INI format. tio
356 uses the configuration file first found in the following locations in
357 the order listed:
358 $XDG_CONFIG_HOME/tio/config
361 $HOME/.config/tio/config
363 $HOME/.tioconfig
365 Labels can be used to group settings into named sub-configurations
368 which can be activated from the command-line when starting tio.
369 tio will try to match the user input to a sub-configuration by name or
372 by pattern to get the TTY device and other options.
373 Options without any label change the default options.
376 Any options set via command-line will override options set in the con‐
379 figuration file.
380 The following configuration file options are available:
383 pattern Pattern matching user input. This pattern can
387 be an extended regular expression with a sin‐
388 gle group.
389 device TTY device to open. If it contains a "%s" it
391 is substituted with the first group match.
392 baudrate Set baud rate
394 databits Set data bits
396 flow Set flow control
398 stopbits Set stop bits
400 parity Set parity
402 output-delay Set output character delay
404 output-line-delay Set output line delay
406 line-pulse-duration Set line pulse duration
408 no-autoconnect Disable automatic connect
410 log Enable log to file
412 log-file Set log filename
414 log-append Append to log file
416 log-strip Enable strip of control and escape sequences
418 from log
419 local-echo Enable local echo
421 timestamp Enable line timestamp
423 timestamp-format Set timestamp format
425 map Map characters on input or output
427 color Colorize tio text using ANSI color code rang‐
429 ing from 0 to 255
430 hexadecimal Enable hexadecimal mode
432 socket Set socket to redirect I/O to
434 prefix-ctrl-key Set prefix ctrl key (a..z, default: t)
436 response-wait Enable wait for line response
438 response-timeout Set line response timeout
440 rs-485 Enable RS-485 mode
442 rs-485-config Set RS-485 configuration
444 alert Set alert action on connect/disconnect
446
449 To change the default configuration simply set options like so:
450 # Defaults
452 baudrate = 9600
453 databits = 8
454 parity = none
455 stopbits = 1
456 color = 10
457 line-pulse-duration = DTR=200,RTS=400
458 Named sub-configurations can be added via labels:
461 [rpi3]
463 device = /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
464 baudrate = 115200
465 color = 11
466 Activate the sub-configuration by name:
469 $ tio rpi3
471 Which is equivalent to:
474 $ tio -b 115200 -c 11 /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FT‐
476 GQVXBL-if00-port0
477 A sub-configuration can also be activated by its pattern which supports
480 regular expressions:
481 [usb device]
483 pattern = usb([0-9]*)
484 device = /dev/ttyUSB%s
485 baudrate = 115200
486 Activate the sub-configuration by pattern match:
489 $ tio usb12
491 Which is equivalent to:
494 $ tio -b 115200 /dev/ttyUSB12
496 It is also possible to combine use of sub-configuration and command-
499 line options. For example:
500 $ tio -l -t usb12
502
505 Typical use is without options:
506 $ tio /dev/ttyUSB0
508 Which corresponds to the commonly used default options:
510 $ tio -b 115200 -d 8 -f none -s 1 -p none /dev/ttyUSB0
512 It is recommended to connect serial TTY devices by ID:
514 $ tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
516 Using serial devices by ID ensures that tio automatically reconnects to
518 the correct serial device if it is disconnected and then reconnected.
519 Redirect serial device I/O to Unix file socket for scripting:
521 $ tio -S unix:/tmp/tio-socket0 /dev/ttyUSB0
523 Then, to issue a command via the file socket simply do:
526 $ echo "ls -la" | nc -UN /tmp/tio-socket0 > /dev/null
528 Or use the expect command to script an interaction:
531 #!/usr/bin/expect -f
533 set timeout -1
535 log_user 0
536 spawn nc -UN /tmp/tio-socket0
538 set uart $spawn_id
539 send -i $uart "date\n"
541 expect -i $uart "prompt> "
542 send -i $uart "ls -la\n"
543 expect -i $uart "prompt> "
544 Redirect device I/O to network file socket for remote TTY sharing:
547 $ tio --socket inet:4444 /dev/ttyUSB0
549 Then, use netcat to connect to the shared TTY session over network (as‐
553 suming tio is hosted on IP 10.0.0.42):
554 $ nc -N 10.0.0.42 4444
556 Pipe command to the serial device:
559 $ echo "ls -la" | tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FT‐
561 GQVXBL-if00-port0
562 Pipe command to the serial device and wait for line response (string
565 ending with CR or NL):
566 $ echo "*IDN?" | tio /dev/ttyACM0 --response-wait
568 In this mode, only the response will be printed.
570 Likewise, to pipe data from file to the serial device:
573 $ cat data.bin | tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FT‐
575 GQVXBL-if00-port0
576 Enable RS-485 mode:
579 $ tio --rs-485 --rs-485-config=RTS_ON_SEND=1,RX_DURING_TX
581 /dev/ttyUSB0
582
585 Visit https://tio.github.io
586
589 Created by Martin Lund <martin.lund@keep-it-simple.com>.
590tio 2.7 2023-09-19 tio(1)