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
37 Set parity (default: none).
39 -o, --output-delay <ms>
41 Set output delay [ms] inserted between each sent character (de‐
43 fault: 0).
44 --dtr-pulse-duration <ms>
47 Set the duration [ms] of the DTR pulse (default: 100).
49 -n, --no-autoconnect
52 Disable automatic connect.
54 By default tio automatically connects to the provided device if
56 present. If the device is not present, it will wait for it to
57 appear and then connect. If the connection is lost (eg. device
58 disconnects), it will wait for the device to reappear and then
59 reconnect.
60 However, if the --no-autoconnect option is provided, tio will
62 exit if the device is not present or an established connection
63 is lost.
64 -e, --local-echo
67 Enable local echo.
69 -t, --timestamp
72 Enable line timestamp.
74 --timestamp-format <format>
77 Set timestamp format to any of the following timestamp formats:
79 24hour 24-hour format ("hh:mm:ss.sss")
83 24hour-start 24-hour format relative to start time
85 24hour-delta 24-hour format relative to previous timestamp
87 iso8601 ISO8601 format ("YYYY-MM-DDThh:mm:ss.sss")
89 Default format is 24hour
91 -L, --list-devices
94 List available serial devices.
96 -l, --log
99 Enable log to file. If no filename is provided the filename will
101 be automatically generated.
102 --log-file <filename>
105 Set log filename.
107 --log-strip
110 Strip control characters and escape sequences from log.
112 -m, --map <flags>
115 Map (replace, translate) special characters on input or output.
117 The following mapping flags are supported:
118 ICRNL Map CR to NL on input (unless IGNCR is set).
121 IGNCR Ignore CR on input.
123 INLCR Map NL to CR on input.
125 INLCRNL Map NL to CR-NL on input.
127 OCRNL Map CR to NL on output.
129 ODELBS Map DEL to BS on output.
131 ONLCRNL Map NL to CR-NL on output.
133 If defining more than one flag, the flags must be comma sepa‐
135 rated.
136 -x, --hexadecimal
139 Enable hexadecimal mode.
141 -c, --color 0..255|none|list
144 Colorize tio text using ANSI color code value ranging from 0 to
146 255 or use "none" for no color.
147 Use "list" to print a list of available ANSI color codes.
149 Default value is 15.
151 -S, --socket <socket>
154 Redirect I/O to socket. Any input from clients connected to the
156 socket is sent on the serial port as if entered at the terminal
157 where tio is running (except that ctrl-t sequences are not rec‐
158 ognized), and any input from the serial port is multiplexed to
159 the terminal and all connected clients.
160 Sockets remain open while the serial port is disconnected, and
162 writes will block.
163 Various socket types are supported using the following prefixes
165 in the socket field:
166 unix:<filename> Unix Domain Socket (file)
170 inet:<port> Internet Socket (network)
172 inet6:<port> Internet IPv6 Socket (network)
174 If port is 0 or no port is provided default port 3333 is used.
176 At present there is a hardcoded limit of 16 clients connected at
178 one time.
179 -v, --version
182 Display program version.
184 -h, --help
186 Display help.
188
190 In session, the following key sequences are intercepted as tio com‐
191 mands:
192 ctrl-t ? List available key commands
194 ctrl-t b Send serial break (triggers SysRq on Linux, etc.)
196 ctrl-t c Show configuration (baudrate, databits, etc.)
198 ctrl-t e Toggle local echo mode
200 ctrl-t h Toggle hexadecimal mode
202 ctrl-t l Clear screen
204 ctrl-t q Quit
206 ctrl-t s Show TX/RX statistics
208 ctrl-t t Send ctrl-t key code
210 ctrl-t L Show line states (DTR, RTS, CTS, DSR, DCD, RI)
212 ctrl-t d Toggle DTR
214 ctrl-t D Pulse DTR
216 ctrl-t r Toggle RTS
218 ctrl-t v Show version
220
223 In hexadecimal mode each incoming byte is printed out as a hexadecimal
224 value.
225 Bytes can be sent in this mode by typing the two-character hexadecimal
227 representation of the value, e.g.: to send 0xA you must type 0a or 0A.
228
231 Options can be set via configuration file using the INI format. tio
232 uses the configuration file first found in the following locations in
233 the order listed:
234 $XDG_CONFIG_HOME/tio/tiorc
236 $HOME/.config/tio/tiorc
238 $HOME/.tiorc
240 Labels can be used to group settings into named sub-configurations
243 which can be activated from the command-line when starting tio.
244 tio will try to match the user input to a sub-configuration by name or
248 by pattern to get the tty and other options.
249 Options without any label change the default options.
252 Any options set via command-line will override options set in the con‐
255 figuration file.
256 The following configuration file options are available:
259 pattern Pattern matching user input. This pattern can be an
263 extended regular expression with a single group.
264 tty tty device to open. If it contains a "%s" it is
266 substituted with the first group match.
267 baudrate Set baud rate
269 databits Set data bits
271 flow Set flow control
273 stopbits Set stop bits
275 parity Set parity
277 output-delay Set output delay
279 dtr-pulse-duration Set DTR pulse duration
281 no-autoconnect Disable automatic connect
283 log Enable log to file
285 log-file Set log filename
287 log-strip Enable strip of control and escape sequences from
289 log
290 local-echo Enable local echo
292 timestamp Enable line timestamp
294 timestamp-format Set timestamp format
296 map Map special characters on input or output
298 color Colorize tio text using ANSI color code ranging
300 from 0 to 255
301 hexadecimal Enable hexadecimal mode
303 socket Set socket to redirect I/O to
305
308 To change the default configuration simply set options like so:
309 # Defaults
311 baudrate = 9600
312 databits = 8
313 parity = none
314 stopbits = 1
315 color = 10
316 dtr-pulse-duration = 50
317 Named sub-configurations can be added via labels:
320 [rpi3]
322 tty = /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
323 baudrate = 115200
324 color = 11
325 Activate the sub-configuration by name:
328 $ tio rpi3
330 Which is equivalent to:
333 $ tio -b 115200 -c 11 /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FT‐
335 GQVXBL-if00-port0
336 A sub-configuration can also be activated by its pattern which supports
339 regular expressions:
340 [usb device]
342 pattern = usb([0-9]*)
343 tty = /dev/ttyUSB%s
344 baudrate = 115200
345 Activate the sub-configuration by pattern match:
348 $ tio usb12
350 Which is equivalent to:
353 $ tio -b 115200 /dev/ttyUSB12
355 It is also possible to combine use of sub-configuration and command-
358 line options. For example:
359 $ tio -l -t usb12
361
364 Typical use is without options:
365 $ tio /dev/ttyUSB0
367 Which corresponds to the commonly used default options:
369 $ tio -b 115200 -d 8 -f none -s 1 -p none /dev/ttyUSB0
371 It is recommended to connect serial tty devices by ID:
373 $ tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
375 Using serial devices by ID ensures that tio automatically reconnects to
377 the correct serial device if it is disconnected and then reconnected.
378 Redirect serial device I/O to Unix file socket for scripting:
380 $ tio -S unix:/tmp/tmux-socket0 /dev/ttyUSB0
382 Then, to issue a command via the file socket simply do:
385 $ echo "ls -la" | nc -UN /tmp/tmux-socket0 > /dev/null
387 Or use the expect command to script an interaction:
390 #!/usr/bin/expect -f
392 set timeout -1
394 log_user 0
395 spawn nc -UN /tmp/tio-socket0
397 set uart $spawn_id
398 send -i $uart "date\n"
400 expect -i $uart "prompt> "
401 send -i $uart "ls -la\n"
402 expect -i $uart "prompt> "
403 Redirect device I/O to network file socket for remote tty sharing:
406 $ tio --socket inet:4444 /dev/ttyUSB0
408 Then, use netcat to connect to the shared tty session over network (as‐
412 suming tio is hosted on IP 10.0.0.42):
413 $ nc -N 10.0.0.42 4444
415 Pipe data from file to the serial device:
418 $ cat data.bin | tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FT‐
420 GQVXBL-if00-port0
421
424 Visit https://tio.github.io
425
428 Created by Martin Lund <martin.lund@keep-it-simple.com>.
429tio 1.43 2022-07-09 tio(1)