1. Unveiling tio: Your Go-To Serial Device I/O Tool
In the realm of embedded systems development and hardware hacking, efficient communication with serial devices is paramount. Enter tio, a versatile serial device tool meticulously designed to simplify interactions with serial TTY devices. With its user-friendly command-line interface and flexible configuration options, tio empowers users to effortlessly manage basic input/output (I/O) operations.
A demonstration of tio in action, showcasing its straightforward interface for serial communication.
1.1 The Need for a Streamlined Serial Tool
For developers immersed in the world of embedded systems and hardware enthusiasts exploring the intricacies of serial communication, the need for a dedicated, uncomplicated tool becomes apparent. While traditional terminal emulators often come laden with features geared towards classic terminal or modem functionalities, tio emerges as a refreshing alternative. It strategically shifts focus towards the core requirements of embedded developers and hackers, prioritizing simplicity and efficiency.
Initially conceived as a leaner substitute for venerable tools like screen, particularly when paired with terminal multiplexers such as tmux, tio addresses the specific demands of modern serial communication in embedded environments. It streamlines workflows, reduces complexity, and allows users to concentrate on the essential aspects of serial device interaction.
2. Key Features that Set tio Apart
Tio boasts a rich feature set tailored to enhance the serial device communication experience:
- Effortless Serial Connection: Establishing connections to serial TTY devices is made simple and intuitive.
- Smart Default Settings: Pre-configured with sensible defaults (115200 8n1), tio is ready to use out-of-the-box for common serial communication scenarios.
- Intelligent Auto-Connection Management:
- Automatic Port Detection: Tio intelligently detects available serial ports, eliminating manual configuration hassles.
- Seamless Auto-Reconnect: In cases of connection drops, tio automatically attempts to reconnect, ensuring uninterrupted workflows.
- Dynamic Device Connection: Tio can automatically connect to the first newly detected serial device or the latest registered device, adapting to changing hardware configurations.
- Topology ID (TID) Based Connection: Connect to specific port/device combinations reliably using unique Topology IDs (TIDs). This is particularly useful for consistent reconnection even when device enumeration changes.
- Support for Non-Standard Baud Rates: Go beyond standard baud rates and utilize custom communication speeds as needed.
- Mark and Space Parity Support: Accommodates diverse parity requirements, including the less common mark and space parity types.
- File Transfer Capabilities: Integrated X-modem (1K/CRC) and Y-modem protocols facilitate efficient file uploads to connected devices.
- RS-485 Mode Compatibility: Enables communication in RS-485 environments, expanding tio’s versatility.
- Comprehensive Serial Device Listing:
- Device-Centric Listing: View detailed information about serial devices, including TID, uptime, driver, and descriptive details. Devices are conveniently sorted by uptime, with the newest devices appearing last.
- Listing by ID & Path: Provides options to list devices based on their IDs or paths for targeted device identification.
- Real-time RX/TX Statistics: Monitor communication performance with live receive (RX) and transmit (TX) statistics.
- Serial Line Control: Toggle serial lines to manage device behavior directly.
- Configurable Line Pulsing: Pulse serial lines with adjustable durations for precise control signals.
- Local Echo Functionality: Enable local echo for convenient command input verification.
- Character Remapping: Transform characters on-the-fly with remapping options for newline (nl), carriage return-newline (cr-nl), backspace (bs), and case conversion.
- Versatile Input and Output Modes:
- Normal Mode: Standard character-based I/O.
- Hex Mode: Inspect data in hexadecimal format, with variable width output support.
- Line Mode (Input Only): Process input line by line.
- Timestamping for Data Analysis:
- Line Timestamps (Normal Mode): Add timestamps to each line in normal output mode for chronological tracking.
- Timeout Timestamps (Hex Mode): Timestamp output timeouts in hex mode for timing analysis.
- Delayed Output Control:
- Per-Character Delay: Introduce delays between character transmissions for specific timing-sensitive applications.
- Per-Line Delay: Delay output on a line-by-line basis.
- Extensive Logging Options:
- Automatic Log Naming: Automatically generate filenames for log files for streamlined organization.
- Configurable Log Directory: Specify a dedicated directory for storing automatically named log files.
- Manual Log Naming: Option to define custom log filenames.
- Overwrite or Append: Choose between overwriting existing logs or appending new data.
- Control Character Stripping: Remove control characters and escape sequences from logs for cleaner data.
- Flexible Configuration File Support:
- Configuration Profiles: Utilize profiles to manage different settings for various serial communication scenarios.
- Profile Activation by Name or Pattern: Activate profiles via name or pattern matching for quick configuration switching.
- Include Other Configuration Files: Modularize configurations by including settings from external files.
- Shell Command I/O Redirection: Seamlessly redirect input and output of shell commands to serial devices.
- Socket Redirection (UNIX & Network): Redirect I/O to UNIX sockets or IPv4/v6 network sockets, enabling scripting and TTY sharing possibilities.
- Input/Output Piping: Integrate tio into pipelines by piping input and/or output streams.
- Bash Completion: Enhance command-line efficiency with bash completion for options, device names, and profile names.
- Customizable Message Color: Personalize the tio message text color for visual customization.
- Visual/Audible Connect/Disconnect Alerts: Receive alerts upon connection or disconnection events through visual or audible cues.
- Remappable Prefix Key: Customize the prefix key (default: ctrl-t) to suit personal preferences.
- Lua Scripting for Automation: Harness the power of Lua scripting to automate complex serial communication tasks:
- Script Execution Control: Run scripts manually or automatically upon connection (once, always, or never).
- Expect/Send Functionality: Implement expect-send patterns with regular expression support for interactive communication.
- Modem Line Manipulation: Control port modem lines for tasks like microcontroller resets or boot sequences.
- File Transfer via X/Y-modem: Automate file transfers using x/y-modem protocols within scripts.
- Serial Device Discovery: Programmatically search for available serial devices.
- Comprehensive Man Page Documentation: Detailed man page documentation for in-depth usage information.
- Seamless Integration with Terminal Multiplexers: Designed to work harmoniously with
tmuxand similar terminal multiplexers.
3. Getting Started with tio: Usage Guide
For comprehensive usage instructions, refer to the detailed man page documentation available here.
3.1 Command-Line Interface Explained
Tio’s command-line interface is designed for clarity and ease of use. The tio --help command provides a concise overview of available options:
Usage: tio [<options>] <tty-device>
Connect to TTY device directly or via configuration profile or topology ID.
Options:
-b, --baudrate <bps> Baud rate (default: 115200)
-d, --databits 5|6|7|8 Data bits (default: 8)
-f, --flow hard|soft|none Flow control (default: none)
-s, --stopbits 1|2 Stop bits (default: 1)
-p, --parity odd|even|none|mark|space Parity (default: none)
-o, --output-delay <ms> Output character delay (default: 0)
-O, --output-line-delay <ms> Output line delay (default: 0)
--line-pulse-duration <duration> Set line pulse duration
-a, --auto-connect new|latest|direct Automatic connect strategy (default: direct)
--exclude-devices <pattern> Exclude devices by pattern
--exclude-drivers <pattern> Exclude drivers by pattern
--exclude-tids <pattern> Exclude topology IDs by pattern
-n, --no-reconnect Do not reconnect
-e, --local-echo Enable local echo
--input-mode normal|hex|line Select input mode (default: normal)
--output-mode normal|hex|hexN Select output mode (default: normal)
-t, --timestamp Enable line timestamp
--timestamp-format <format> Set timestamp format (default: 24hour)
--timestamp-timeout <ms> Set timestamp timeout (default: 200)
-l, --list List available serial devices, TIDs, and profiles
-L, --log Enable log to file
--log-file <filename> Set log filename
--log-directory <path> Set log directory path for automatic named logs
--log-append Append to log file
--log-strip Strip control characters and escape sequences
-m, --map <flags> Map characters
-c, --color 0..255|bold|none|list Colorize tio text (default: bold)
-S, --socket <socket> Redirect I/O to socket
--rs-485 Enable RS-485 mode
--rs-485-config <config> Set RS-485 configuration
--alert bell|blink|none Alert on connect/disconnect (default: none)
--mute Mute tio messages
--script <string> Run script from string
--script-file <filename> Run script from file
--script-run once|always|never Run script on connect (default: always)
--exec <shell-command> Execute shell command with I/O redirected to deviceBy default, tio intelligently attempts to connect to the specified TTY device. If the device is not immediately available, tio patiently waits for its appearance and establishes a connection. Should the connection be interrupted, for instance, by unplugging the device, tio will automatically attempt reconnection upon device re-emergence. However, the --no-reconnect option modifies this behavior, causing tio to exit if the device is absent or if an active connection is lost.
3.1.1 Practical Examples of tio Usage
In its simplest form, tio can be invoked without any options:
$ tio /dev/ttyUSB0This command leverages tio’s default settings, equivalent to:
$ tio --baudrate 115200 --databits 8 --flow none --stopbits 1 --parity none /dev/ttyUSB0To list all available serial devices along with their topology IDs and other details, use the --list option:
$ tio --list
Device TID Uptime [s] Driver Description
---------------- ----- ------------ ----------- --------------------------
/dev/ttyS4 BaaB 19526.576 port 16550A UART
/dev/ttyS5 eV0Z 19525.845 port 16550A UART
/dev/ttyUSB1 bCC2 1023.274 ftdi_sio TTL232R-3V3
/dev/ttyUSB0 SPpw 978.527 ftdi_sio TTL232RG-VREG3V3
/dev/ttyACM0 i5q4 2.079 cdc_acm ST-Link VCP Ctrl
By-id
--------------------------------------------------------------------------------
/dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTCHUV56-if00-port0
/dev/serial/by-id/usb-FTDI_TTL232RG-VREG3V3_FT1NELUB-if00-port0
/dev/serial/by-id/usb-STMicroelectronics_STLINK-V3_004900343438510234313939-if02
By-path
--------------------------------------------------------------------------------
/dev/serial/by-path/pci-0000:00:14.0-usb-0:8.1.3.1.4:1.0-port0
/dev/serial/by-path/pci-0000:00:14.0-usbv2-0:8.1.3.1.4:1.0-port0
/dev/serial/by-path/pci-0000:00:14.0-usbv2-0:6.4:1.0-port0
/dev/serial/by-path/pci-0000:00:14.0-usb-0:6.4:1.0-port0
/dev/serial/by-path/pci-0000:00:14.0-usbv2-0:6.3:1.2
/dev/serial/by-path/pci-0000:00:14.0-usb-0:6.3:1.2
Configuration profiles (/home/lundmar/.config/tio/config)
--------------------------------------------------------------------------------
rpi3
stm32
esp32
am64-evm
imx8mp-evk
nucleo-h743zi2
usb-devicesIt’s generally recommended to connect to serial TTY devices using their IDs for robust reconnection behavior:
$ tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTCHUV56-if00-port0Connecting to a serial device by its ID ensures consistent reconnection, even if the device enumeration changes.
In situations where device IDs are unavailable, connecting via Topology ID (TID) offers a reliable alternative:
$ tio bCC2Topology IDs provide a persistent way to reconnect to the same serial device as long as it’s plugged into the same USB topology.
For automatic connection strategies, tio provides options like connecting to the first new serial device:
$ tio --auto-connect newOr connecting to the latest registered serial device:
$ tio --auto-connect latestExclusion options allow fine-tuning automatic connection behavior by excluding specific devices:
$ tio --auto-connect new --exclude-devices "/dev/ttyACM?,/dev/ttyUSB2"Or by excluding drivers based on patterns:
$ tio --auto-connect new --exclude-drivers "cdc_acm,ftdi_sio"Driver inclusion can be achieved by negating the exclude option:
$ tio --auto-connect new --exclude-drivers !("cp2102")Logging serial communication to a file with an automatically generated filename is as simple as:
$ tio --log /dev/ttyUSB0For specific filenames, use the --log-file option:
$ tio --log --log-file my-log.txtTo enable ISO8601 timestamps for each line in the output:
$ tio --timestamp --timestamp-format iso8601 /dev/ttyUSB0Outputting data in hexadecimal format with a width of 16 columns:
$ tio --output-mode hex16 /dev/ttyUSB0Redirecting serial I/O to an IPv4 network socket on port 4242:
$ tio --socket inet:4242 /dev/ttyUSB0Mapping newline (NL) to carriage return-newline (CR-NL) on input and delete (DEL) to backspace (BS) on output:
$ tio --map INLCRNL,ODELBS /dev/ttyUSB0Piping data to a serial device is straightforward:
$ cat data.bin | tio /dev/ttyUSB0Manipulating modem lines upon connection using a script:
$ tio --script "set{DTR=high,RTS=low}; msleep(100); set{DTR=toggle,RTS=toggle}" /dev/ttyUSB0Piping a command to a serial device and waiting for a line response within 1 second using a script:
$ echo "*IDN?" | tio /dev/ttyACM0 --script "expect('rn', 1000)" --mute
KORAD KD3305P V4.2 SN:324750453.2 Interactive Key Commands
Tio offers a range of in-session key commands for interactive control. While tio is running, pressing ctrl-t ? will display a list of available commands:
[15:02:53.269] Key commands:
[15:02:53.269] ctrl-t ? List available key commands
[15:02:53.269] ctrl-t b Send break
[15:02:53.269] ctrl-t c Show configuration
[15:02:53.269] ctrl-t e Toggle local echo mode
[15:02:53.269] ctrl-t f Toggle log to file
[15:02:53.269] ctrl-t F Flush data I/O buffers
[15:02:53.269] ctrl-t g Toggle serial port line
[15:02:53.269] ctrl-t i Toggle input mode
[15:02:53.269] ctrl-t l Clear screen
[15:02:53.269] ctrl-t L Show line states
[15:02:53.269] ctrl-t m Change mapping of characters on input or output
[15:02:53.269] ctrl-t o Toggle output mode
[15:02:53.269] ctrl-t p Pulse serial port line
[15:02:53.269] ctrl-t q Quit
[15:02:53.269] ctrl-t r Run script
[15:02:53.269] ctrl-t R Execute shell command with I/O redirected to device
[15:02:53.269] ctrl-t s Show statistics
[15:02:53.269] ctrl-t t Toggle line timestamp mode
[15:02:53.269] ctrl-t v Show version
[15:02:53.269] ctrl-t x Send file via Xmodem
[15:02:53.269] ctrl-t y Send file via Ymodem
[15:02:53.269] ctrl-t ctrl-t Send ctrl-t characterThe default prefix key ctrl-t can be reconfigured within the configuration file if needed.
3.3 Configuration File Essentials
Tio’s behavior can be extensively customized through configuration files. Tio searches for a configuration file in the following locations, prioritizing the first one found:
$XDG_CONFIG_HOME/tio/config$HOME/.config/tio/config$HOME/.tioconfig
The configuration file supports profiles, which are named sections allowing you to predefine settings for different scenarios. Profiles can be activated via the command-line by name or pattern. A profile typically specifies the TTY device to connect to and any desired options.
3.3.1 Configuration File Example
[default]
baudrate = 115200
databits = 8
parity = none
stopbits = 1
color = 10
[rpi3]
device = /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
no-reconnect = true
log = true
log-file = rpi3.log
line-pulse-duration = DTR=200,RTS=150
color = 11
[svf2]
device = /dev/ttyUSB0
baudrate = 9600
script = expect("login: "); write("rootn"); expect("Password: "); write("rootn")
color = 12
[esp32]
device = /dev/serial/by-id/usb-0403_6014-if00-port0
script = set{DTR=high,RTS=low}; msleep(100); set{DTR=low,RTS=high}; msleep(100); set{RTS=low}
script-run = once
color = 13
[usb-devices]
pattern = ^usb([0-9]*)
device = /dev/ttyUSB%m1
color = 14To utilize a specific profile by name, simply invoke tio followed by the profile name:
$ tio rpi3Profiles can also be activated using pattern matching:
$ tio usb12A more comprehensive configuration file example is available here.
3.4 Lua Scripting API for Advanced Automation
Tio’s Lua scripting capabilities empower users to create sophisticated automation sequences for interacting with serial devices.
Beyond standard Lua functions, tio provides a specialized API with the following functions:
expect(string, timeout) -- Expect string - waits for string match or timeout. Supports regex.
read(size, timeout) -- Read from serial device.
read_line(timeout) -- Read line from serial device.
write(string) -- Write string to serial device.
send(file, protocol) -- Send file via x/y-modem (XMODEM_1K, XMODEM_CRC, YMODEM).
tty_search() -- Search for serial devices, returns a table of device info.
set{line=state, ...} -- Set modem line states (DTR, RTS, CTS, DSR, CD, RI - high, low, toggle).
sleep(seconds) -- Sleep for seconds.
msleep(ms) -- Sleep for milliseconds.
exit(code) -- Exit with exit code.4. Installation Guide
4.1 Package Manager Installation (Linux)
Pre-built packages for various GNU/Linux distributions are readily available. Consult your distribution’s package manager (e.g., apt, yum, pacman) to search for and install tio.
If you wish to see tio included in your preferred distribution’s repositories, consider reaching out to its package maintainers.
4.2 Snap Installation (Linux)
For a convenient installation on Linux systems using Snap packages, utilize the following command to install the latest stable version:
$ snap install tio --classicNote: Classic confinement is currently required due to snapcraft framework limitations. Refer to Issue #187 for further details and discussions.
4.3 Brew Installation (macOS, Linux)
If you have brew installed on your macOS or Linux system, installation is as simple as:
$ brew install tio4.4 MSYS2 Installation (Windows)
For Windows users with MSYS2 installed, tio can be installed using pacman:
$ pacman -S tio4.5 Building from Source
The latest source code releases can be found here.
Before proceeding with the installation steps, ensure that you have the glib and lua development libraries installed. For Debian/Ubuntu-based systems, this can be achieved with:
$ sudo apt install libglib2.0-dev liblua5.2-devInstallation steps using Meson build system:
$ meson setup build
$ meson compile -C build
$ meson install -C buildRefer to meson_options.txt for tio-specific build configuration options.
Note: The exact meson installation steps might vary slightly depending on your specific system configuration.
4.6 Resolving Permission Issues
Encountering permission errors when trying to access your serial device? This typically indicates that your user account lacks the necessary permissions to access serial ports.
To resolve this permanently, add your user to the group that manages serial device access, often the ‘dialout’ group. For example, to add your user to the ‘dialout’ group:
sudo usermod -a -G dialout <username>Alternatively, for a temporary solution in the current session, switch to the ‘dialout’ group:
newgrp dialout5. Contributing to tio
As an open-source project, contributions of all forms are highly encouraged and welcomed – be it bug reports, code enhancements, documentation improvements, or feature suggestions.
Please utilize the GitHub issue tracker and pull request mechanisms for contributions.
If you find tio valuable and wish to support its development, consider making a donation of your choice:
6. Seeking Support
For bug reports and support inquiries, please use the GitHub issue tracker: https://github.com/tio/tio/issues
7. Explore the Website
Visit the official tio website at tio.github.io for additional information and resources.
8. License Information
tio is licensed under GPLv2+. See the LICENSE file for complete license details.
9. Authors and Contributors
Maintained by Martin Lund <[email protected]>
Refer to the AUTHORS file for a comprehensive list of contributors.
