git.sur5r.net Git - tio/blob - README.md

   1 # tio - a simple serial device I/O tool
   2
   3 [![CircleCI](https://circleci.com/gh/tio/tio/tree/master.svg?style=shield)](https://circleci.com/gh/tio/tio/tree/master)
   4 [![tio](https://snapcraft.io/tio/badge.svg)](https://snapcraft.io/tio)
   5 [![Packaging status](https://repology.org/badge/tiny-repos/tio.svg)](https://repology.org/project/tio/versions)
   6
   7 ## 1. Introduction
   8
   9 tio is a simple serial device tool which features a straightforward
  10 command-line and configuration file interface to easily connect to serial TTY
  11 devices for basic I/O operations.
  12
  13 <p align="center">
  14 <img src="images/tio-demo.gif">
  15 </p>
  16
  17 ### 1.1 Motivation
  18
  19 To make a simpler serial device tool for talking with serial TTY devices with
  20 less focus on classic terminal/modem features and more focus on the needs of
  21 embedded developers and hackers.
  22
  23 tio was originally created to replace
  24 [screen](https://www.gnu.org/software/screen) for connecting to serial devices
  25 when used in combination with [tmux](https://tmux.github.io).
  26
  27 ## 2. Features
  28
  29  * Easily connect to serial TTY devices
  30  * Automatic connect
  31  * Support for arbitrary baud rates
  32  * List available serial devices
  33  * Show RX/TX statistics
  34  * Toggle serial lines
  35  * Local echo support
  36  * Remap special characters (nl, cr-nl, bs, etc.)
  37  * Line timestamps
  38  * Support for delayed output
  39  * Hexadecimal mode
  40  * Log to file
  41  * Autogeneration of log filename
  42  * Configuration file support
  43  * Activate sub-configurations by name or pattern
  44  * Redirect I/O to socket for scripting or TTY sharing
  45  * Pipe input and/or output
  46  * Bash completion
  47  * Color support
  48  * Man page documentation
  49
  50 ## 3. Usage
  51
  52 ### 3.1 Command-line
  53
  54 The command-line interface is straightforward as reflected in the output from
  55 'tio --help':
  56 ```
  57     Usage: tio [<options>] <tty-device|sub-config>
  58
  59     Connect to tty-device directly or via sub-configuration.
  60
  61     Options:
  62       -b, --baudrate <bps>             Baud rate (default: 115200)
  63       -d, --databits 5|6|7|8           Data bits (default: 8)
  64       -f, --flow hard|soft|none        Flow control (default: none)
  65       -s, --stopbits 1|2               Stop bits (default: 1)
  66       -p, --parity odd|even|none       Parity (default: none)
  67       -o, --output-delay <ms>          Character output delay (default: 0)
  68       -n, --no-autoconnect             Disable automatic connect
  69       -e, --local-echo                 Enable local echo
  70       -t, --timestamp                  Enable line timestamp
  71           --timestamp-format <format>  Set timestamp format (default: 24hour)
  72       -L, --list-devices               List available serial devices
  73       -l, --log                        Enable log to file
  74           --log-file <filename>        Set log filename
  75           --log-strip                  Strip control characters and escape sequences
  76       -m, --map <flags>                Map special characters
  77       -c, --color 0..255|none|list     Colorize tio text (default: 15)
  78       -S, --socket <socket>            Redirect I/O to socket
  79       -x, --hexadecimal                Enable hexadecimal mode
  80       -v, --version                    Display version
  81       -h, --help                       Display help
  82
  83     Options and sub-configurations may be set via configuration file.
  84
  85     In session, press ctrl-t q to quit.
  86
  87     See the man page for more details.
  88 ```
  89
  90 By default tio automatically connects to the provided TTY device if present.
  91 If the device is not present, it will wait for it to appear and then connect.
  92 If the connection is lost (eg. device is unplugged), it will wait for the
  93 device to reappear and then reconnect. However, if the `--no-autoconnect`
  94 option is provided, tio will exit if the device is not present or an
  95 established connection is lost.
  96
  97 tio features full bash autocompletion.
  98
  99 ### 3.2 Key commands
 100
 101 Various in session key commands are supported. When tio is started, press
 102 ctrl-t ? to list the available key commands.
 103
 104 ```
 105 [20:19:12.040] Key commands:
 106 [20:19:12.040]  ctrl-t ?   List available key commands
 107 [20:19:12.040]  ctrl-t b   Send break
 108 [20:19:12.040]  ctrl-t c   Show configuration
 109 [20:19:12.040]  ctrl-t d   Toggle DTR line
 110 [20:19:12.040]  ctrl-t e   Toggle local echo mode
 111 [20:19:12.040]  ctrl-t h   Toggle hexadecimal mode
 112 [20:19:12.040]  ctrl-t l   Clear screen
 113 [20:19:12.040]  ctrl-t L   Show line states
 114 [20:19:12.040]  ctrl-t q   Quit
 115 [20:19:12.040]  ctrl-t r   Toggle RTS line
 116 [20:19:12.041]  ctrl-t s   Show statistics
 117 [20:19:12.041]  ctrl-t t   Send ctrl-t key code
 118 [20:19:12.041]  ctrl-t T   Toggle line timestamp mode
 119 [20:19:12.041]  ctrl-t v   Show version
 120 ```
 121
 122 ### 3.3 Configuration file
 123
 124 Options can be set via the configuration file first found in any of the
 125 following locations in the order listed:
 126  - $XDG_CONFIG_HOME/tio/tiorc
 127  - $HOME/.config/tio/tiorc
 128  - $HOME/.tiorc
 129
 130 The configuration file supports sub-configurations using named sections which can
 131 be activated via the command-line by name or pattern.
 132
 133 Example configuration file:
 134
 135 ```
 136 # Defaults
 137 baudrate = 115200
 138 databits = 8
 139 parity = none
 140 stopbits = 1
 141 color = 10
 142
 143 [ftdi]
 144 tty = /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
 145 baudrate = 9600
 146 no-autoconnect = enable
 147 log = enable
 148 log-file = ftdi.log
 149 color = 12
 150
 151 [usb devices]
 152 pattern = usb([0-9]*)
 153 tty = /dev/ttyUSB%s
 154 color = 13
 155 ```
 156
 157 To use a specific sub-configuration by name simply start tio like so:
 158 ```
 159 $ tio ftdi
 160 ```
 161 Or by pattern match:
 162 ```
 163 $ tio usb12
 164 ```
 165
 166
 167 ## 4. Installation
 168
 169 ### 4.1 Installation using package manager
 170
 171 Packages for various GNU/Linux distributions are available. Please consult your
 172 package manager tool to find and install tio.
 173
 174 If you would like to see tio included in your favorite distribution, please
 175 reach out to their package maintainers team.
 176
 177 ### 4.2 Installation using snap
 178
 179 Install latest stable version:
 180 ```
 181     $ snap install tio
 182 ```
 183 Install bleeding edge:
 184 ```
 185     $ snap install tio --edge
 186 ```
 187
 188 ### 4.3 Installation from source
 189
 190 The latest source releases can be found [here](https://github.com/tio/tio/releases).
 191
 192 Install steps:
 193 ```
 194     $ meson build
 195     $ meson compile -C build
 196     $ meson install -C build
 197 ```
 198
 199 See meson\_options.txt for tio specific build options.
 200
 201 Note: Please do no try to install from source if you are not familiar with
 202 how to build stuff using meson.
 203
 204
 205 ## 5. Contributing
 206
 207 tio is open source. If you want to help out with the project please feel free
 208 to join in.
 209
 210 All contributions (bug reports, code, doc, ideas, etc.) are welcome.
 211
 212 Please use the github issue tracker and pull request features.
 213
 214 Also, if you find this free open source software useful please feel free to
 215 consider making a donation of your choice:
 216
 217 [![Donate](images/paypal.png)](https://www.paypal.me/lundmar)
 218
 219
 220 ## 6. Support
 221
 222 Submit bug reports via GitHub: https://github.com/tio/tio/issues
 223
 224
 225 ## 7. Website
 226
 227 Visit [tio.github.io](https://tio.github.io)
 228
 229
 230 ## 8. License
 231
 232 tio is GPLv2+. See LICENSE file for more details.
 233
 234
 235 ## 9. Authors
 236
 237 Created by Martin Lund \<martin.lund@keep-it-simple.com>
 238
 239 See the AUTHORS file for full list of contributors.