tio - 一个串行设备 I/O 工具

1. 简介

tio 是一个串行设备工具，具有直观的命令行和配置文件界面，可轻松连接到串行 TTY 设备进行基本的 I/O 操作。

1.1 动机

为嵌入式开发人员和黑客创建一个更简单的串行设备工具，用于处理串行 TTY 设备，减少对传统终端/调制解调器功能的关注，更多地关注嵌入式开发人员和黑客的需求。

tio 最初是作为 screen 的替代品创建的，用于与 tmux 结合使用时连接串行设备。

2. 功能

轻松连接串行 TTY 设备
合理的默认设置（115200 8n1）
自动连接管理
- 自动检测串行端口
- 自动重新连接
- 自动连接到首个新出现的串行设备
- 自动连接到最新注册的串行设备
通过唯一拓扑 ID（TID）连接到相同的端口/设备组合
- 当串行设备没有设备 ID 时，用于重新连接
支持非标准波特率
支持标记和空格奇偶校验
X-modem（1K/CRC）和 Y-modem 文件上传
支持 RS-485 模式
列出可用的串行设备
- 按设备
  - 包括拓扑 ID、运行时间、驱动程序、描述
  - 按运行时间排序（最新设备列在最后）
- 按 ID
- 按路径
显示 RX/TX 统计信息
切换串行线路
使用可配置的脉冲持续时间对串行线路进行脉冲
本地回显支持
字符重映射（nl、cr-nl、bs、小写转大写等）
可切换的独立输入和输出
- 正常模式
- 十六进制模式（输出支持可变宽度）
- 行模式（仅输入）
时间戳支持
- 正常输出模式下每行
- 十六进制输出模式下的输出超时时间戳
支持延迟输出
- 每个字符
- 每行
记录到文件
- 自动命名日志文件（默认）
- 可配置自动命名日志文件的保存目录
- 手动命名日志文件
- 覆盖（默认）或追加到日志文件
- 去除控制字符和转义序列
配置文件支持
- 支持配置文件配置
- 通过名称或模式激活配置文件
- 支持包含其他配置文件
将 shell 命令的 I/O 重定向到串行设备
将 I/O 重定向到 UNIX 套接字或 IPv4/v6 网络套接字
- 对脚本编写或 TTY 共享有用
管道输入和/或输出
Bash 补全选项、串行设备名称和配置文件名称
可配置的 tio 消息文本颜色
- 支持 NO_COLOR 环境变量，符合 no-color.org 标准
连接/断开时的视觉或听觉提醒
前缀键重映射
Lua 脚本支持自动化
- 手动运行脚本或在连接时自动运行（一次/始终/从不）
- 简单的 expect/send 类功能，支持正则表达式
- 操作端口调制解调器线路（用于微控制器复位/引导等）
- 通过 x/y-modem 协议发送文件
- 搜索串行设备
Man 页面文档
与 tmux 和类似的终端复用器配合良好

3. 使用方法

有关更多使用详情，请参阅此处的 man 页面文档。

3.1 命令行

命令行界面很直观，如 tio --help 输出所示：

用法：tio [<选项>] <tty-设备|配置文件|tid>

直接连接到 TTY 设备或通过配置文件或拓扑 ID 连接。

选项： -b, --baudrate <bps> 波特率（默认：115200） -d, --databits 5|6|7|8 数据位（默认：8） -f, --flow hard|soft|none 流控制（默认：无） -s, --stopbits 1|2 停止位（默认：1） -p, --parity odd|even|none|mark|space 校验（默认：无） -o, --output-delay <ms> 输出字符延迟（默认：0） -O, --output-line-delay <ms> 输出行延迟（默认：0） --line-pulse-duration <duration> 设置线路脉冲持续时间 -a, --auto-connect new|latest|direct 自动连接策略（默认：直接） --exclude-devices <pattern> 按模式排除设备 --exclude-drivers <pattern> 按模式排除驱动 --exclude-tids <pattern> 按模式排除拓扑ID -n, --no-reconnect 不重新连接 -e, --local-echo 启用本地回显 --input-mode normal|hex|line 选择输入模式（默认：正常） --output-mode normal|hex|hexN 选择输出模式（默认：正常） -t, --timestamp 启用行时间戳 --timestamp-format <format> 设置时间戳格式（默认：24小时制） --timestamp-timeout <ms> 设置时间戳超时（默认：200） -l, --list 列出可用的串行设备、TID和配置文件 -L, --log 启用日志记录到文件 --log-file <filename> 设置日志文件名 --log-directory <path> 为自动命名的日志设置日志目录路径 --log-append 追加到日志文件 --log-strip 去除控制字符和转义序列 -m, --map <flags> 映射字符 -c, --color 0..255|bold|none|list 为tio文本着色（默认：粗体） -S, --socket <socket> 将I/O重定向到套接字 --rs-485 启用RS-485模式 --rs-485-config <config> 设置RS-485配置 --alert bell|blink|none 连接/断开连接时发出提醒（默认：无） --mute 静音tio消息 --script <string> 从字符串运行脚本 --script-file <filename> 从文件运行脚本 --script-run once|always|never 连接时运行脚本（默认：始终） --exec <command> 执行shell命令，将I/O重定向到设备 -v, --version 显示版本 -h, --help 显示帮助

选项和配置文件可以通过配置文件设置。

在会话中，您可以按Ctrl-t ?列出可用的键盘命令。

有关更多详细信息，请参阅手册页。

默认情况下，tio会自动连接到提供的TTY设备。如果设备不存在，tio将等待它出现然后连接。如果连接丢失（例如设备被拔出），它将等待设备重新出现然后重新连接。但是，如果提供了--no-reconnect选项，当设备不存在或已建立的连接丢失时，tio将退出。

3.1.1 示例

典型用法是不带选项：

$ tio /dev/ttyUSB0

这相当于常用的默认选项：

$ tio --baudrate 115200 --databits 8 --flow none --stopbits 1 --parity none /dev/ttyUSB0

列出可用的串行设备：

$ tio --list
设备               TID     运行时间[秒] 驱动              描述
----------------- ---- ------------- ---------------- --------------------------
/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

按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

按路径
--------------------------------------------------------------------------------
/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
配置文件 (/home/lundmar/.config/tio/config)
--------------------------------------------------------------------------------
rpi3                stm32               esp32               am64-evm
imx8mp-evk          nucleo-h743zi2      usb-devices

建议通过ID连接串行TTY设备：

$ tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTCHUV56-if00-port0

注意：使用ID连接串行设备有助于确保tio在设备重新连接时自动重连到同一串行设备，即使设备枚举不同。

如果没有可用的ID串行设备，建议通过拓扑ID (TID) 连接：

$ tio bCC2

注意：TID是唯一的，只要USB串行端口设备插入相同的USB拓扑（相同的端口、集线器、连接等），它就会保持不变。这样tio就可以成功重连到同一设备。

自动连接到首个新出现的串行设备：

$ tio --auto-connect new

自动连接到最新注册的串行设备：

$ tio --auto-connect latest

也可以使用排除选项来影响自动连接策略涉及的串行设备：

$ tio --auto-connect new --exclude-devices "/dev/ttyACM?,/dev/ttyUSB2"

按模式排除驱动：

$ tio --auto-connect new --exclude-drivers "cdc_acm,ftdi_sio"

注意：模式匹配支持'*'和'?'。使用逗号分隔多个模式。

使用自动生成的文件名记录日志：

$ tio --log /dev/ttyUSB0

使用指定文件名记录日志：

$ tio --log --log-file my-log.txt

启用每行ISO8601时间戳：

$ tio --timestamp --timestamp-format iso8601 /dev/ttyUSB0

以16宽度的十六进制格式输出：

$ tio --output-mode hex16 /dev/ttyUSB0

将I/O重定向到端口4242的IPv4网络套接字：

$ tio --socket inet:4242 /dev/ttyUSB0

将数据通过管道传输到串行设备：

$ cat data.bin | tio /dev/ttyUSB0

在连接时操作调制解调器线路：

$ tio --script "set{DTR=high,RTS=low}; msleep(100); set{DTR=toggle,RTS=toggle}" /dev/ttyUSB0

通过管道将命令发送到串行设备并在1秒内等待行响应：

$ echo "*IDN?" | tio /dev/ttyACM0 --script "expect('\r\n', 1000)" --mute
KORAD KD3305P V4.2 SN:32475045

### 3.2 按键命令

支持各种会话内按键命令。启动tio后，按ctrl-t ?列出可用的按键命令。

[15:02:53.269] 按键命令：
[15:02:53.269]  ctrl-t ?       列出可用的按键命令
[15:02:53.269]  ctrl-t b       发送中断
[15:02:53.269]  ctrl-t c       显示配置
[15:02:53.269]  ctrl-t e       切换本地回显模式
[15:02:53.269]  ctrl-t f       切换文件日志记录
[15:02:53.269]  ctrl-t F       刷新数据I/O缓冲区
[15:02:53.269]  ctrl-t g       切换串行端口线路
[15:02:53.269]  ctrl-t i       切换输入模式
[15:02:53.269]  ctrl-t l       清屏
[15:02:53.269]  ctrl-t L       显示线路状态
[15:02:53.269]  ctrl-t m       更改输入或输出字符映射
[15:02:53.269]  ctrl-t o       切换输出模式
[15:02:53.269]  ctrl-t p       脉冲串行端口线路
[15:02:53.269]  ctrl-t q       退出
[15:02:53.269]  ctrl-t r       运行脚本
[15:02:53.269]  ctrl-t R       执行shell命令，I/O重定向到设备
[15:02:53.269]  ctrl-t s       显示统计信息
[15:02:53.269]  ctrl-t t       切换行时间戳模式
[15:02:53.269]  ctrl-t v       显示版本
[15:02:53.269]  ctrl-t x       通过Xmodem发送文件
[15:02:53.269]  ctrl-t y       通过Ymodem发送文件
[15:02:53.269]  ctrl-t ctrl-t  发送ctrl-t字符

如有需要，可以通过配置文件重新映射前缀键（ctrl-t）。

### 3.3 配置文件

可以通过按以下顺序首先找到的配置文件设置选项：
 - $XDG_CONFIG_HOME/tio/config
 - $HOME/.config/tio/config
 - $HOME/.tioconfig

配置文件支持使用命名部分的配置文件，可以通过命令行按名称或模式激活。配置文件指定要连接的TTY设备和其他选项。

### 3.3.1 示例

配置文件示例：

[default]
baudrate = 115200
databits = 8
parity = none
stopbits = 1
color = 10
[rpi3]
设备 = /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
不重连 = true
记录 = true
日志文件 = rpi3.log
线路脉冲持续时间 = DTR=200,RTS=150
颜色 = 11

[svf2]
设备 = /dev/ttyUSB0
波特率 = 9600
脚本 = expect("login: "); send("root\n"); expect("Password: "); send("root\n")
颜色 = 12

[esp32]
设备 = /dev/serial/by-id/usb-0403_6014-if00-port0
脚本 = set{DTR=high,RTS=low}; msleep(100); set{DTR=low,RTS=high}; msleep(100); set{RTS=low}
脚本运行 = 一次
颜色 = 13

[usb-devices]
模式 = ^usb([0-9]*)
设备 = /dev/ttyUSB%m1
颜色 = 14

要按名称使用特定配置文件,只需像这样启动tio:

$ tio rpi3

或通过模式匹配:

$ tio usb12

另一个更详细的配置文件示例可在此处获得。

### 3.4 Lua 脚本 API

Tio 支持 Lua 脚本以轻松自动化与 tty 设备的交互。

除了 Lua API 之外,tio 还提供以下功能:

expect(字符串, 超时)
      期望字符串 - 等待字符串匹配或超时后继续。
      支持正则表达式。特殊字符必须用'\\'转义。
      超时以毫秒为单位,默认为0表示永远等待。

      成功匹配时返回1,超时时返回0,错误时返回-1。

      成功匹配时还会将匹配字符串作为第二个返回值返回。

send(字符串)
      发送字符串。

      成功时返回写入的字节数,错误时返回-1。

modem_send(文件, 协议)
      使用 x/y-modem 协议发送文件。

      协议可以是 XMODEM_1K、XMODEM_CRC、YMODEM 中的任何一个。

tty_search()
      搜索串行设备。

      返回一个数字索引表的表,每个串行设备对应一个表。
      这些表包含可通过以下字符串索引元素访问的串行设备信息:
      "path"、"tid"、"uptime"、"driver"、"description"。

      如果未找到串行设备,则返回 nil。

read(大小, 超时)
      从串行设备读取。如果超时为0或未提供,将永远等待直到数据准备好读取。

      成功时返回读取的字节数,超时时返回0,错误时返回-1。

      成功时,将读取的字符串作为第二个返回值返回。

set{线路=状态, ...}
      设置一个或多个 tty 调制解调器线路的状态。

      线路可以是 DTR、RTS、CTS、DSR、CD、RI 中的任何一个。

      状态是 high、low 或 toggle。

sleep(秒)
      休眠指定秒数。

msleep(毫秒)
      休眠指定毫秒数。

exit(代码)
      以指定的退出代码退出。

## 4. 安装

### 4.1 使用包管理器安装(Linux)

各种 GNU/Linux 发行版都提供了软件包。请查阅您的包管理工具以查找和安装 tio。

如果您希望在您喜欢的发行版中包含 tio,请联系其软件包维护团队。

### 4.2 使用 snap 安装(Linux)

安装最新稳定版本:

$ snap install tio --classic

注意:由于 snapcraft 框架的限制,目前需要经典限制。
有关讨论,请参阅 Issue #187。

### 4.3 使用 brew 安装(MacOS, Linux)

如果您已安装 brew:

$ brew install tio

### 4.4 使用 MSYS2 安装(Windows)

如果您已安装 MSYS2:

$ pacman -S tio

### 4.5 从源代码安装

最新的源代码发布可以在这里找到。

在运行安装步骤之前,请确保已安装 glib 和 lua 库。例如:

$ sudo apt install libglib2.0-dev liblua5.2-dev

安装步骤:

$ meson setup build
$ meson compile -C build
$ meson install -C build

有关 tio 特定的构建选项,请参阅 meson_options.txt。

注意:根据您的特定系统,meson 安装步骤可能会有所不同。

### 4.6 已知问题

尝试打开串行设备时遇到权限访问错误?

将您的用户添加到允许串行设备访问的组。例如,要将您的用户添加到"dialout"组,请执行以下操作:

$ sudo usermod -a -G dialout <用户名>

## 5. 贡献

这是一个开源项目 - 欢迎所有贡献(错误报告、代码、文档、想法等)。

请使用 GitHub 问题跟踪器和拉取请求功能。

此外,如果您发现这个免费开源软件有用,请随意考虑捐赠您选择的金额:

[捐赠]

## 6. 支持

通过 GitHub 提交错误报告:https://github.com/tio/tio/issues

## 7. 网站

访问 tio.github.io
## 8. 许可证

tio 采用 GPLv2+ 许可证。更多详情请参阅 LICENSE 文件。


## 9. 作者

由 Martin Lund <martin.lund@keep-it-simple.com> 维护

完整的贡献者名单请参见 AUTHORS 文件。