2 [![tio](images/tio-icon.png)]()
4 # tio - a simple serial device I/O tool
6 [![](https://img.shields.io/circleci/build/github/tio/tio)](https://circleci.com/github/tio/tio/tree/master)
7 [![](https://img.shields.io/github/v/release/tio/tio?sort=semver)](https://github.com/tio/tio/releases)
8 [![](https://img.shields.io/repology/repositories/tio)](https://repology.org/project/tio/versions)
9 <!-- [![](https://img.shields.io/tokei/lines/github/tio/tio)](https://github.com/tio/tio) -->
13 tio is a simple serial device tool which features a straightforward
14 command-line and configuration file interface to easily connect to serial TTY
15 devices for basic I/O operations.
18 <img src="images/tio-demo.gif">
23 To make a simpler serial device tool for talking with serial TTY devices with
24 less focus on classic terminal/modem features and more focus on the needs of
25 embedded developers and hackers.
27 tio was originally created to replace
28 [screen](https://www.gnu.org/software/screen) for connecting to serial devices
29 when used in combination with [tmux](https://tmux.github.io).
33 * Easily connect to serial TTY devices
34 * Automatic connect and reconnect
35 * Sensible defaults (115200 8n1)
36 * Support for non-standard baud rates
37 * Support for RS-485 mode
38 * X-modem (1K) and Y-modem file upload
39 * Support for mark and space parity
40 * List available serial devices by ID
41 * Show RX/TX statistics
43 * Pulse serial lines with configurable pulse duration
45 * Remapping of characters (nl, cr-nl, bs, lowercase to uppercase, etc.)
47 * Support for delayed output per character
48 * Support for delayed output per line
51 * Autogeneration of log filename
52 * Configuration file support
53 * Activate sub-configurations by name or pattern
54 * Redirect I/O to UNIX socket or IPv4/v6 network socket for scripting or TTY sharing
55 * Pipe input and/or output
56 * Support for simple line request/response handling
57 * Bash completion on options, serial device names, and sub-configuration names
58 * Configurable text color
59 * Visual or audible alert on connect/disconnect
60 * Remapping of prefix key
61 * Man page documentation
62 * Binary size less than 80kB
63 * Plays nicely with [tmux](https://tmux.github.io)
67 For more usage details please see the man page documentation
68 [here](https://raw.githubusercontent.com/tio/tio/master/man/tio.1.txt).
72 The command-line interface is straightforward as reflected in the output from
75 Usage: tio [<options>] <tty-device|sub-config>
77 Connect to TTY device directly or via sub-configuration.
80 -b, --baudrate <bps> Baud rate (default: 115200)
81 -d, --databits 5|6|7|8 Data bits (default: 8)
82 -f, --flow hard|soft|none Flow control (default: none)
83 -s, --stopbits 1|2 Stop bits (default: 1)
84 -p, --parity odd|even|none|mark|space Parity (default: none)
85 -o, --output-delay <ms> Output character delay (default: 0)
86 -O, --output-line-delay <ms> Output line delay (default: 0)
87 --line-pulse-duration <duration> Set line pulse duration
88 -n, --no-autoconnect Disable automatic connect
89 -e, --local-echo Enable local echo
90 -t, --timestamp Enable line timestamp
91 --timestamp-format <format> Set timestamp format (default: 24hour)
92 -L, --list-devices List available serial devices
93 -l, --log Enable log to file
94 --log-file <filename> Set log filename
95 --log-append Append to log file
96 --log-strip Strip control characters and escape sequences
97 -m, --map <flags> Map characters
98 -c, --color 0..255|bold|none|list Colorize tio text (default: bold)
99 -S, --socket <socket> Redirect I/O to socket
100 -x, --hexadecimal Enable hexadecimal mode
101 -r, --response-wait Wait for line response then quit
102 --response-timeout <ms> Response timeout (default: 100)
103 --rs-485 Enable RS-485 mode
104 --rs-485-config <config> Set RS-485 configuration
105 --alert bell|blink|none Alert on connect/disconnect (default: none)
106 -v, --version Display version
107 -h, --help Display help
109 Options and sub-configurations may be set via configuration file.
111 See the man page for more details.
115 By default tio automatically connects to the provided TTY device if present.
116 If the device is not present, it will wait for it to appear and then connect.
117 If the connection is lost (eg. device is unplugged), it will wait for the
118 device to reappear and then reconnect. However, if the `--no-autoconnect`
119 option is provided, tio will exit if the device is not present or an
120 established connection is lost.
122 tio features full bash autocompletion.
126 Typical use is without options:
131 Which corresponds to the commonly used default options:
133 $ tio -b 115200 -d 8 -f none -s 1 -p none /dev/ttyUSB0
136 It is recommended to connect serial TTY devices by ID:
138 $ tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
140 Using serial devices by ID ensures that tio automatically reconnects to the
141 correct serial device if it is disconnected and then reconnected.
143 List available serial devices by ID:
147 Note: One can also use tio shell completion on /dev which will automatically
148 list all available serial TTY devices.
150 Log to file with autogenerated filename:
152 $ tio --log /dev/ttyUSB0
155 Enable ISO8601 timestamps per line:
157 $ tio --timestamp --timestamp-format iso8601 /dev/ttyUSB0
160 Redirect I/O to IPv4 network socket on port 4242:
162 $ tio --socket inet:4242 /dev/ttyUSB0
165 Inject data to the serial device:
167 $ cat data.bin | tio /dev/ttyUSB0
170 Send command to serial device and wait for line response:
172 $ echo "*IDN?" | tio /dev/ttyACM0 --response-wait
173 KORAD KD3305P V4.2 SN:32475045
178 Various in session key commands are supported. When tio is started, press
179 ctrl-t ? to list the available key commands.
182 [20:19:12.040] Key commands:
183 [20:19:12.040] ctrl-t ? List available key commands
184 [20:19:12.040] ctrl-t b Send break
185 [20:19:12.040] ctrl-t c Show configuration
186 [20:19:12.040] ctrl-t e Toggle local echo mode
187 [20:19:12.040] ctrl-t f Toggle log to file
188 [20:19:12.040] ctrl-t g Toggle serial port line
189 [20:19:12.040] ctrl-t h Toggle hexadecimal mode
190 [20:19:12.040] ctrl-t l Clear screen
191 [20:19:12.040] ctrl-t L Show line states
192 [20:19:12.040] ctrl-t p Pulse serial port line
193 [20:19:12.040] ctrl-t q Quit
194 [20:19:12.041] ctrl-t s Show statistics
195 [20:19:12.041] ctrl-t t Toggle line timestamp mode
196 [20:19:12.041] ctrl-t U Toggle conversion to uppercase
197 [20:19:12.041] ctrl-t v Show version
198 [20:19:12.041] ctrl-t x Send file using the XMODEM protocol
199 [20:19:12.041] ctrl-t y Send file using the YMODEM protocol
200 [20:19:12.041] ctrl-t ctrl-t Send ctrl-t character
203 If needed, the prefix key (ctrl-t) can be remapped via configuration file.
205 ### 3.3 Configuration file
207 Options can be set via the configuration file first found in any of the
208 following locations in the order listed:
209 - $XDG_CONFIG_HOME/tio/config
210 - $HOME/.config/tio/config
213 The configuration file supports sub-configurations using named sections which can
214 be activated via the command-line by name or pattern. A sub-configuration
215 specifies which TTY device to connect to and other options.
217 Example configuration file:
228 device = /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
230 no-autoconnect = enable
233 line-pulse-duration = DTR=200,RTS=150
237 pattern = usb([0-9]*)
238 device = /dev/ttyUSB%s
242 To use a specific sub-configuration by name simply start tio like so:
251 Another more elaborate configuration file example is available [here](example/config).
255 ### 4.1 Installation using package manager (Linux)
257 Packages for various GNU/Linux distributions are available. Please consult your
258 package manager tool to find and install tio.
260 If you would like to see tio included in your favorite distribution, please
261 reach out to its package maintainers team.
263 ### 4.2 Installation using snap (Linux)
265 Install latest stable version:
267 $ snap install tio --classic
270 Note: Classic confinement is currently required due to limitations of the snapcraft framework.
271 See [Issue #187](https://github.com/tio/tio/issues/187) for discussion.
273 ### 4.3 Installation using brew (MacOS, Linux)
275 If you have [brew](http://brew.sh) installed:
280 ### 4.4 Installation using MSYS2 (Windows)
282 If you have [MSYS2](https://www.msys2.org) installed:
287 ### 4.5 Installation from source
289 The latest source releases can be found [here](https://github.com/tio/tio/releases).
294 $ meson compile -C build
295 $ meson install -C build
298 See meson\_options.txt for tio specific build options.
300 Note: The meson install steps may differ depending on your specific system.
304 Getting permission access errors trying to open your serial device?
306 Add your user to the group which allows serial device access. For example, to add your user to the 'dialout' group do:
308 $ sudo usermod -a -G dialout <username>
314 tio is open source. If you want to help out with the project please feel free
317 All contributions (bug reports, code, doc, ideas, etc.) are welcome.
319 Please use the github issue tracker and pull request features.
321 Also, if you find this free open source software useful please feel free to
322 consider making a donation of your choice:
324 [![Donate](images/paypal.png)](https://www.paypal.me/lundmar)
329 Submit bug reports via GitHub: https://github.com/tio/tio/issues
334 Visit [tio.github.io](https://tio.github.io)
339 tio is GPLv2+. See LICENSE file for more details.
344 Created by Martin Lund \<martin.lund@keep-it-simple.com>
346 See the AUTHORS file for full list of contributors.