Maarrk/tio
1
0
Fork 0
mirror of https://github.com/tio/tio.git synced 2026-05-01 14:57:59 +02:00
Code Issues Projects Releases 1 Packages Wiki Activity Actions

Add documentation and examples for new features.

Browse source
This commit is contained in:
yabu76 2026-03-08 11:17:50 +09:00
parent 1b0ef08d95
commit 2316c0216a
7 changed files with 702 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

47
README.md
View file

@ -43,8 +43,9 @@ when used in combination with [tmux](https://tmux.github.io).
* Useful for reconnecting when serial device has no serial device by ID
* Support for non-standard baud rates
* Support for mark and space parity
* X-modem (1K/CRC) and Y-modem file upload
* X-modem (1K/CRC/Checksum) and Y-modem file upload
* Support for RS-485 mode
* Support for raw mode and switching by key operations
* List available serial devices
* By device
* Including topology ID, uptime, driver, description
@ -59,7 +60,7 @@ when used in combination with [tmux](https://tmux.github.io).
* Switchable independent input and output
* Normal mode
* Hex mode (output supports variable width)
* Line mode (input only)
* Line mode (input only, it supports line-editing and history)
* Timestamp support
* Per line in normal output mode
* Output timeout timestamps in hex output mode
@ -87,6 +88,7 @@ when used in combination with [tmux](https://tmux.github.io).
* Remapping of prefix key
* Lua scripting support for automation
* Run script manually or automatically at connect (once/always/never)
* Run script and preload functions and variables when tio starts up
* Simple expect/send like functionality with support for regular expressions
* Manipulate port modem lines (useful for microcontroller reset/boot etc.)
* Send files via x/y-modem protocol
@ -116,6 +118,7 @@ Options:
-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)
--output-line-delay-char cr|lf Output line delay trigger character (default: lf)
--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
@ -136,16 +139,21 @@ Options:
--log-append Append to log file
--log-strip Strip control characters and escape sequences
-m, --map <flags> Map characters
--keymap <keymaps> Set key-script mappings
-c, --color 0..255|bold|none|list Colorize tio text (default: bold)
-S, --socket <socket> Redirect I/O to socket
--raw off|on|on-nodelay Select raw mode for non-interactive use (default: on)
--raw-interactive off|on|on-nodelay Select raw mode for interactive use (default: off)
--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-init-file <filename> Set initial script file to run at startup
--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 <command> Execute shell command with I/O redirected to device
--complete-profiles Prints profiles (for shell completion)
-v, --version Display version
-h, --help Display help
@ -313,6 +321,9 @@ ctrl-t ? to list the available key commands.
[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 j Toggle raw mode for non-interactive use
[15:02:53.269] ctrl-t J Toggle raw mode for interactive use
[15:02:53.269] ctrl-t k Set key-script mappings
[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
@ -330,6 +341,10 @@ ctrl-t ? to list the available key commands.
```
If needed, the prefix key (ctrl-t) can be remapped via configuration file.
And you can also map scripts as user key commands using keymap entries in the configuration file.
When key commands request line input, you can edit the line and call the history by using the cursor keys and backspace key.
The history is maintained while tio is running.
### 3.3 Configuration file
@ -354,6 +369,9 @@ databits = 8
parity = none
stopbits = 1
color = 10
script-init-file = /home/user/.tio-init-script.lua
# ctrl-t 1 runs setup-script.lua and ctrl-t 9 runs the tio file transfer built-in with xmodem-checksum.
keymap = @1=setup-device.lua @9=!tio.send("firmfile", tio.C.XM_SUM)
[rpi3]
device = /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0
@ -396,20 +414,29 @@ Another more elaborate configuration file example is available [here](examples/c
Tio suppots Lua scripting to easily automate interaction with the tty device.
In addition to the standard Lua API tio makes the following functions
and variables available:
In addition to the standard Lua API tio makes the functions and variables available
The following are representative. See the man page for the complete list.:
#### `tio.expect(pattern, timeout)`
Waits for the Lua pattern to match or timeout before continuing.
Timeout is in milliseconds, defaults to 0 meaning it will wait forever.
Timeout is in milliseconds, defaults to tio.C.WAIT_FOREVER(==0) meaning it will wait forever.
Returns the captures from the pattern or `nil` on timeout.
Returns the captures from the pattern and all received data if matched.
Or return nil and all received data if timeout.
#### `tio.expects(pattern-table, timeout)`
Waits for any of the multiple Lua pattens to match or timeout before continuing.
Timeout is in milliseconds, defaults to tio.C.WAIT_FOREVER(==0) meaning it will wait forever.
Returns the index of the matched pattern, the captures from it and all recieved data.
Or return nil, nil and all received data if timeout.
#### `tio.read(size, timeout)`
Read up to `size` bytes from serial device. If timeout is 0 or not provided it
Read up to `size` bytes from serial device. If timeout is tio.C.WAIT_FOREVER(==0) or not provided it
will wait forever until data is ready to read.
Returns a string up to `size` bytes long on success and `nil` on timeout.
@ -438,7 +465,8 @@ Returns the tio table on success or nil on error.
Send file using x/y-modem protocol.
Protocol can be any of `XMODEM_1K`, `XMODEM_CRC`, `YMODEM`.
Protocol can be any of `XMODEM_1K`, `XMODEM_CRC`, `XMODEM_SUM`, `YMODEM`.
Alternatively, it can be one of tio.C.XM_1K, tio.C.XM_CRC, tio.C.XM_SUM, or tio.C.YM_NORMAL.
#### `tio.ttysearch()`
@ -457,6 +485,7 @@ Set state of one or multiple tty modem lines.
Line can be any of `DTR`, `RTS`, `CTS`, `DSR`, `CD`, `RI`
State is `high`, `low`, or `toggle`.
Alternatively, it can be one of tio.C.LN_HIGH, tio.C.LN_LOW, tio.C.LN_TOGGLE.
#### `tio.sleep(seconds)`
@ -537,7 +566,7 @@ Note: The meson install steps may differ depending on your specific system.
Getting permission access errors trying to open your serial device?
Add your user to the group which allows serial device access permanently. For example, to add your user to the 'dialout' group do:
```bash
ppp```bash
sudo usermod -a -G dialout <username>
```
Switch to the "dialout" group, temporary but immediately for this session.

216
docs/interactive-lua-scripting.md Normal file
View file

@ -0,0 +1,216 @@
# Interactive Lua Scripting
## Introduction
Tio provides an **interactive Lua scripting interface** that allows scripts and Lua commands to be executed while Tio is running.
In earlier versions, the script interpreter was restarted for each script execution.
The interpreter now **remains active**, preserving its state across executions.
This makes it possible to:
* run Lua commands interactively
* reuse functions defined in previously loaded scripts
* experiment with Lua code without restarting the interpreter
* avoid repeated initialization overhead when working with large scripts
---
## Starting Interactive Script Mode
To start interactive script mode, press:
**Ctrl-t r**
Tio displays the script prompt:
```
[08:45:46.514] Run Lua script
[08:45:46.514] Enter file name or "!" Lua commands or "@" interpreter directive:
>>
```
At this prompt you can:
| Input | Description |
| ------------ | ---------------------------------------- |
| `filename` | Execute a Lua script file |
| `!commands` | Execute Lua commands |
| `@directive` | Execute an interpreter control directive |
You can use the cursor keys and backspace key to edit the line and recall command history.
The history is maintained while tio is running.
---
## Running a Script File
To execute a Lua script file, enter the filename at the prompt.
Example script (`banner.tio`):
```lua
function tio.banner()
local banner = [[
_ _ _ _ __
| |_ (_) ___ ___ | |_ __ _ _ __ | |_ _ \ \
| __|| | / _ \ / __|| __|/ _` || '__|| __| (_)_____ | |
| |_ | || (_) | \__ \| |_| (_| || | | |_ _ _|_____|| |
\__||_| \___/ |___/ \__|\__,_||_| \__|(_) (_) | |
/_/
]]
tio.echo(string.gsub(banner, "\n", "\r\n"))
end
tio.banner()
```
Run the script:
```
>> banner.tio
[09:08:13.786] Running script banner.tio
_ _ _ _ __
| |_ (_) ___ ___ | |_ __ _ _ __ | |_ _ \ \
| __|| | / _ \ / __|| __|/ _` || '__|| __| (_)_____ | |
| |_ | || (_) | \__ \| |_| (_| || | | |_ _ _|_____|| |
\__||_| \___/ |___/ \__|\__,_||_| \__|(_) (_) | |
/_/
```
The script is loaded and executed immediately.
Any functions defined in the script remain available in the interpreter.
---
## Executing Lua Commands
Lua commands can be executed directly by prefixing them with `!`.
This allows you to interact with previously defined functions or variables.
Example script (`calc_sum.tio`):
```lua
function tio.calc_sum(t)
local sum = 0
for _, v in ipairs(t) do
sum = sum + v
end
return sum
end
function tio.disp_sum(t)
local sum = tio.calc_sum(t)
tio.echo(sum)
tio.echo("\r\n")
end
```
Example session:
```
>> calc_sum.tio
[09:15:22.372] Running script calc_sum.tio
<<press Ctrl-t r again>>
>> !t = {1,2,3,4,5,6,7,8,9,10}
<<press Ctrl-t r again>>
>> !tio.disp_sum(t)
55
>> !sum = tio.calc_sum(t); tio.echo(sum); tio.echo("\r\n")
55
```
---
## Interpreter Directives
Interpreter behavior can be controlled using directives prefixed with `@`.
### `@new`
Restart the script interpreter.
All interpreter state is cleared and the interpreter is reinitialized.
If a `script-init-file` is configured, it is executed again.
---
### `@doopt`
Execute the script specified by the `script` or `script-file` option, if present.
---
### `@nuldo=opt`
If **Ctrl-t r** is pressed and **Enter** is pressed without entering a command, `@doopt` is executed.
This is the default behavior for compatibility with Tio v3.9.
---
### `@nuldo=none`
If **Ctrl-t r** is pressed and **Enter** is pressed without entering a command, no action is performed.
This helps prevent accidental script execution.
---
### `@repl`
Start **REPL (Read–Eval–Print Loop)** mode.
---
## REPL Mode
Enter:
```
@repl
```
to start REPL mode.
In REPL mode:
* Lua commands can be entered continuously
* each line is executed immediately
* multi-line statements can be continued using a trailing `\`
* `@exit` leaves REPL mode
Example:
```
[10:17:30.215] Run Lua script
[10:17:30.215] Enter file name or "!" Lua commands or "@" interpreter directive:
>> @repl
[10:17:31.956] Enter Lua REPL mode (@exit to exit)
>> p=1
>> for i=1,10 do\
>> p = p * i\
>> end
>> print(p, "\r")
3628800
>> @exit
```
---
## Summary
The interactive Lua scripting interface provides:
* persistent interpreter state
* interactive Lua command execution
* script reuse without interpreter restart
* an integrated REPL environment
These capabilities make it easier to develop, test, and experiment with Tio scripts while the program is running.
Enjoy using Tio's Interactive Lua Scripting.

1
examples/config/config
View file

@ -17,6 +17,7 @@ stopbits = 1
parity = none
output-delay = 0
output-line-delay = 0
output-line-delay-char = lf
auto-connect = direct
no-reconnect = false
no-tty-restore = false

21
examples/lua/expects.lua Normal file
View file

@ -0,0 +1,21 @@
--
-- example of intaction with AT modem.
--
tio.write("AT\r")
local matches, all = tio.expect("OK", 1000)
if matches == nil then
tio.echo("no response 1\r\n")
os.exit(0)
end
msleep(200)
tio.read(1000, tio.C.NOWAIT)
tio.write("ATFANTASYCMD\r")
local idx, matches, all = tio.expects({"OK", "ERROR", "BUSY"}, 1000)
if idx == nil then
tio.echo("no response 2\r\n")
os.exit(0)
end
-- this display 2, ERROR
print(idx, matches[1])
os.exit(0)

41
examples/lua/tio-script-init.lua Normal file
View file

@ -0,0 +1,41 @@
--
-- tio's script-init file
--
-- Please add following to your tio config file.
--
-- script-init-file = /<<your-full-path>>/.tio-scipt-init.lua
--
-- note: tio module is already loaded.
--
function tio.conv_lf_to_crlf(str)
local new_str = str:gsub("\n", "\r\n")
return new_str
end
function tio.lprint(...)
local args = {...}
local argN = #args
for i = 1, argN - 1 do
io.write(tio.conv_lf_to_crlf(tostring(args[i])))
io.write("\t")
end
if argN > 0 then
io.write(tio.conv_lf_to_crlf(tostring(args[argN])))
end
io.write("\r\n")
end
function tio.banner()
local banner = [[
_ _ _ _ __
| |_ (_) ___ ___ | |_ __ _ _ __ | |_ _ \ \
| __|| | / _ \ / __|| __|/ _` || '__|| __| (_)_____ | |
| |_ | || (_) | \__ \| |_| (_| || | | |_ _ _|_____|| |
\__||_| \___/ |___/ \__|\__,_||_| \__|(_) (_) | |
/_/]]
tio.lprint(banner)
end
tio.banner()

218
man/tio.1.in
View file

@ -51,6 +51,11 @@ Set output delay [ms] inserted between each sent character (default: 0).
Set output delay [ms] inserted between each sent line (default: 0).
.TP
.BR " \-\-output\-line\-delay\-char " cr | lf
Set trigger character of output line delay (default: lf).
.TP
.BR " \-\-line\-pulse\-duration " \fI<duration>
@ -124,7 +129,7 @@ This means that tio will exit if it fails to connect to device or an
established connection is lost.
.TP
.BR \-n ", " \-\-no\-tty\-restore
.BR \-N ", " \-\-no\-tty\-restore
Do not restore initial TTY device settings.
@ -244,7 +249,7 @@ Map lowercase characters to uppercase on output
Map nul (zero) to send break signal on output
.IP "\fBOIGNCR"
Ignore CR on output
.P
.PP
If defining more than one flag, the flags must be comma separated.
.RE
@ -259,8 +264,9 @@ In hex input mode bytes can be sent by typing the \fBtwo-character
hexadecimal\fR representation of the 1 byte value, e.g.: to send \fI0xA\fR you
must type \fI0a\fR or \fI0A\fR.
In line input mode input characters are sent when you press enter. The only
editing feature supported in this mode is backspace.
In line input mode input characters are sent when you press enter.
You can use the cursor keys and backspace key to edit the line and recall command
history. The history is maintained while tio is running.
Default value is "normal".
@ -309,12 +315,42 @@ Unix Domain Socket (file)
Internet Socket (network)
.IP "\fBinet6:<port>"
Internet IPv6 Socket (network)
.P
.PP
If port is 0 or no port is provided default port 3333 is used.
.P
.PP
At present there is a hardcoded limit of 16 clients connected at one time.
.RE
.TP
.BR " \-\-raw " off|on|on-nodelay
nSet raw mode for non-interactive use.
Non-interactive use is Piped-input / Shell command execution / XYMODEM transferring.
The raw option can be set to one of the following:
.RS
.TP 20n
.IP "\fBoff"
flow control, character mapping and output delay are enabled
.IP "\fBon"
software flow control and character mapping are disabled; output delay remains enabled
.IP "\fBon-nodelay"
software flow control, character mapping and output delay is disabled
.PP
Default value is "on".
.RE
.TP
.BR " \-\-raw-interactive " off|on|on-nodelay
Set raw mode for interactive use.
Interactive use is normal terminal input/output and socket redirection.
This is useful when transferring files through socket redirection.
Default value is "off".
.TP
.BR " \-\-rs\-485"
@ -338,7 +374,7 @@ Set RTS delay (ms) before sending
Set RTS delay (ms) after sending
.IP \fBRX_DURING_TX
Receive data even while sending data
.P
.PP
If defining more than one key or key value pair, they must be comma separated.
.RE
@ -357,15 +393,24 @@ Default value is "none".
Mute tio messages.
.TP
.BR "\-\-script\-init\-file \fI<filename>"
Run script from file with filename on tio's startup.
Execution occurs before connecting to the device, and loaded functions and variables are preserved.
The default is <<not\-specified>>, which only loads built\-in functions and variables.
.TP
.BR "\-\-script \fI<string>
Run script from string.
Run script from string on connect.
.TP
.BR "\-\-script\-file \fI<filename>
Run script from file with filename.
Run script from file with filename on connect.
.TP
.BR "\-\-script\-run once|always|never"
@ -379,6 +424,11 @@ Default value is "always".
Execute shell command with I/O redirected to device
The standard output and standard error of a shell command are redirected to the device through tio's output filters (with output mapping and output delay enabled), and input from the device is redirected to
the standard input of the shell command.
If you specify '?' as a shell commands prefix, standard error output will not be redirected. This allows you to use some communication commands such as sz/rz.
.TP
.BR "\-\-complete-profiles
@ -411,6 +461,10 @@ Flush data I/O buffers (discard data written but not transmitted and data receiv
Toggle serial port line
.IP "\fBctrl-t i"
Toggle input mode
.IP "\fBctrl-t j"
Toggle raw mode for non-interactive use
.IP "\fBctrl-t J"
Toggle raw mode for interactive use
.IP "\fBctrl-t l"
Clear screen
.IP "\fBctrl-t L"
@ -434,7 +488,7 @@ Toggle line timestamp mode
.IP "\fBctrl-t v"
Show version
.IP "\fBctrl-t x"
Send file using the XMODEM-1K or XMODEM-CRC protocol (prompts for file name and protocol)
Send file using the XMODEM-1K, XMODEM-CRC or XMODEM-SUM protocol (prompts for file name and protocol)
.IP "\fBctrl-t y"
Send file using the YMODEM protocol (prompts for file name)
.IP "\fBctrl-t ctrl-t"
@ -442,7 +496,7 @@ Send ctrl-t character
.SH "SCRIPT API"
.PP
Tio suppots Lua scripting to easily automate interaction with the tty device.
Tio supports Lua scripting to easily automate interaction with the tty device.
In addition to the standard Lua API tio makes the following functions
and variables available:
@ -450,38 +504,48 @@ and variables available:
.TP 6n
.IP "\fBtio.expect(pattern, timeout)"
Waits for the Lua pattern to match or timeout before continuing.
Timeout is in milliseconds, defaults to 0 meaning it will wait forever.
Waits for the Lua pattern to match or timeout before continuing. Special characters must be escaped with '\\' or '%'.
Timeout is in milliseconds, defaults to tio.C.WAIT_FOREVER(==0) meaning it will wait forever.
Returns the captures from the pattern or nil on timeout.
On success, returns the captures from the pattern and all received data.
On timeout, returns nil and all received data.
.IP "\fBtio.expects(pattern-table, timeout)"
Waits for any of the multiple Lua patterns to match or timeout before continuing. Special characters must be escaped with '\\' or '%'.
Timeout is in milliseconds, defaults to tio.C.WAIT_FOREVER(==0) meaning it will wait forever.
On success, returns the index of the matched pattern, the captures from it and all received data.
On timeout, returns nil, nil and all received data.
.IP "\fBtio.read(size, timeout)"
Read up to size bytes from serial device. If timeout is 0 or not provided it
will wait forever until data is ready to read.
Read up to size bytes from serial device. If timeout is tio.C.WAIT_FOREVER(==0) or not provided it will wait forever until data is ready to read.
If the timeout is tio.C.NOWAIT (==-1), the function immediately reads as much data as possible from the serial device's RX buffer, up to a maximum of <size> bytes, and returns.
Returns a string up to size bytes long on success and nil on timeout.
On success, returns read data as string. Also emits a single timestamp to stdout and log file per options.timestamp and options.log.
On timeout, returns nil and received data.
.IP "\fBtio.readline(timeout)"
Read line from serial device. If timeout is 0 or not provided it will wait
forever until data is ready to read.
Read line from serial device. If timeout is tio.C.WAIT_FOREVER(==0) or not provided it will wait forever until data is ready to read.
The line separater is LF (0x0a).
Returns a string on success and nil on timeout. On timeout a partially read
line may be returned as a second return value.
On success, returns received line as string. Also emits a single timestamp to stdout and log file per options.timestamp and options.log.
On timeout, returns nil and received data.
.IP "\fBtio.write(string)"
Write string to serial device without Input-editing, Output-mapping nor Output-delay.
Write string to serial device without input-editing, output-mapping, or output-delay.
Returns the tio table on success or nil on error.
.IP "\fBtio.twrite(string)"
Write string to serial device with Input-editing, Output-mapping and Output-delay.
Write string to serial device with input-editing, output-mapping and output-delay.
Returns tio table on success or nil on error.
.IP "\fBtio.send(file, protocol)"
Send file using x/y-modem protocol.
Protocol can be any of XMODEM_1K, XMODEM_CRC, YMODEM.
Protocol can be any of XMODEM_1K, XMODEM_CRC, XMODEM_SUM, YMODEM.
It can alternatively be one of tio.C.XM_1K, tio.C.XM_CRC, tio.C.XM_SUM, tio.C.YM_NORMAL.
.IP "\fBtio.ttysearch()"
Search for serial devices.
@ -502,9 +566,83 @@ State is high, low, or toggle.
.IP "\fBtio.sleep(seconds)"
Sleep for seconds.
.IP "\fBtio.msleep(ms)"
Sleep for milliseconds.
.IP "\fBtio.send_break()"
Send break signal.
It is equivalent to the key command ctrl-t b.
.IP "\fBtio.line_get()"
Get state of multiple tty modem lines.
It is equivalent to the key command ctrl-t L.
Return 6 values DTR, RTS, CTS, DSR, CD, RI.
Each return value is high (==tio.C.LN_HIGH) or low (==tio.C.LN_LOW).
.IP "\fBtio.set_local_echo(on_off)"
Change the local echo setting.
It is equivalent to the key command ctrl-t e.
The argument on_off is a boolean value. true means on and false means off. If omitted, it is set to true.
.IP "\fBtio.set_log(on_off)"
Change the log-file setting.
It is equivalent to the key command ctrl-t f.
The argument on_off is a boolean value. true means on and false means off. If omitted, it is set to true.
.IP "\fBtio.flush_data_io_buffer()"
Flush read/write data in I/O buffers.
It is equivalent to the key command ctrl-t F.
.IP "\fBtio.set_input_mode(input_mode)"
Change the input mode.
It is equivalent to the key command ctrl-t i.
The argument input_mode is one of tio.C.IM_NORMAL, tio.C.IM_HEX, tio.C.IM_LINE.
.IP "\fBtio.set_output_mode(output_mode)"
Change the output mode.
It is equivalent to the key command ctrl-t o.
The argument output_mode is one of tio.C.OM_NORMAL, tio.C.OM_HEX.
.IP "\fBtio.set_raw_mode(raw_mode)"
Change the raw mode for non-interactive use.
It is equivalent to the key command ctrl-t j.
The argument raw_mode is one of tio.C.RAW_OFF, tio.C.RAW_ON, tio.C.RAW_ON_NODELAY.
.IP "\fBtio.set_raw_mode_interactive(raw_mode)"
Change the raw mode for interactive use.
It is equivalent to the key command ctrl-t J.
The argument raw_mode is one of tio.C.RAW_OFF, tio.C.RAW_ON, tio.C.RAW_ON_NODELAY.
.IP "\fBtio.set_timestamp_mode(timestamp_mode)"
Change the timestamp mode.
It is equivalent to the key command ctrl-t t.
The argument timestamp_mode is one of tio.C.TS_OFF, tio.C.TS_24HOUR, tio.C.TS_24HOUR_START, tio.C.TS_24HOUR_DELTA, tio.C.TS_ISO861, tio.C.TS_EPOCH, tio.C.TS_EPOCH_USEC.
.IP "\fBtio.exec_shell_command(shell_commands)"
Execute /bin/sh -c <<shell_commands>>.
Normally, standard output / standard error is forwarded to tio's output filter which do output mapping and output delay.
If the shell commands starts with '?', '?' is removed and standard error is not forwarded.
It is equivalent to the key command ctrl-t R.
The argument shell_commands is string.
.IP "\fBtio.get_state()"
Return the main state of tio as a integer.
Return value is one of tio.C.SA_INTERACTIVE, tio.C.SA_STARTING, tio.C.SA_PIPED_INPUT, tio.C.SA_PIPED_INPUT, tio.C.SA_EXEC_SHELL_COMMAND, tio.C.SA_XYMODEM.
.IP "\fBtio.get_version()"
Return the version of tio as a string.
It is equivalent to the key command ctrl-t v.
.IP "\fBtio.alwaysecho"
A boolean value, defaults to true.
@ -514,6 +652,10 @@ will only be returned from the function and not logged or printed.
If tio.alwaysecho is set to true, reading functions also emit a single
timestamp to stdout and log file per options.timestamp and options.log.
.IP "\fBos.exit(code)"
Exit tio process with exit code (like ctrl-t q).
.SH "CONFIGURATION FILE"
.PP
Options can be set via configuration file using the INI format. \fBtio\fR uses
@ -563,6 +705,8 @@ Set parity
Set output character delay
.IP "\fBoutput-line-delay"
Set output line delay
.IP "\fBoutput-line-delay-char"
Set trigger character of output line delay
.IP "\fBline-pulse-duration"
Set line pulse duration
.IP "\fBno-reconnect"
@ -587,6 +731,8 @@ Set timestamp format
Set timestamp timeout
.IP "\fBmap"
Map characters on input or output
.IP "\fBkeymap"
Set key-script mappings
.IP "\fBcolor"
Colorize tio text using ANSI color code ranging from 0 to 255
.IP "\fBinput-mode"
@ -605,12 +751,14 @@ Set RS-485 configuration
Set alert action on connect/disconnect
.IP "\fBmute"
Mute tio messages
.IP "\fBscript-init-file"
Run script from file on tio's startup
.IP "\fBscript"
Run script from string
Run script from string on connect
.IP "\fBscript-file"
Run script from file
Run script from file on connect
.IP "\fBscript-run"
Run script on connect
Set condition to run script on connect
.IP "\fBexec"
Execute shell command with I/O redirected to device
@ -785,6 +933,22 @@ Manipulate DTR and RTS lines upon first connect to reset connected microcontroll
$ tio --script "tio.set{DTR=high,RTS=low}; tio.msleep(100); tio.set{RTS=toggle}" --script-run once /dev/ttyUSB0
.TP
Manipulate DTR and RTS lines by pressing ctrl-t 1:
$ tio --keymap '@1=!tio.set{DTR=high,RTS=low}; tio.msleep(100); tio.set{RTS=toggle}' /dev/ttyUSB0
.TP
Send file to device by sz command:
$ tio --exec '?sz -b file' /dev/ttyUSB0
.TP
Receive file from device by rz command:
$ tio --exec '?rz -b' /dev/ttyUSB0
.SH "WEBSITE"
.PP
Visit https://tio.github.io

231
man/tio.1.txt
View file

@ -40,6 +40,10 @@ OPTIONS
Set output delay [ms] inserted between each sent line (default: 0).
--output-line-delay-char cr|lf
Set trigger character of output line delay (default: lf).
--line-pulse-duration <duration>
Set the pulse duration [ms] of each serial port line using the following key value pair format in the duration field: <key>=<value>
@ -122,7 +126,7 @@ OPTIONS
epoch Seconds since Unix epoch (1970-01-01)
epoch-usec Seconds since Unix epoch (1970-01-01) with subdivision microseconds
epoch-usec Seconds since Unix epoch (1970-01-01) with subdivision in microseconds
Default format is 24hour
@ -194,6 +198,12 @@ OPTIONS
If defining more than one flag, the flags must be comma separated.
--keymap <keymaps>
Specify the mappings as @<key-1>=<script-description-1> @<key-2>=<script-description-2>... @<key-N>=<script-description-N>.
Script-description is script-filename or '!'script-commands.
--input-mode normal|hex|line
Set input mode.
@ -202,7 +212,7 @@ OPTIONS
In hex input mode bytes can be sent by typing the two-character hexadecimal representation of the 1 byte value, e.g.: to send 0xA you must type 0a or 0A.
In line input mode input characters are sent when you press enter. The only editing feature supported in this mode is backspace.
In line input mode input characters are sent when you press enter. You can use the cursor keys and backspace key to edit the line and recall command history. The history is maintained while tio is running.
Default value is "normal".
@ -245,6 +255,30 @@ OPTIONS
At present there is a hardcoded limit of 16 clients connected at one time.
--raw off|on|on-nodelay
Set raw mode for non-interactive use.
Non-interactive use is Piped-input / Shell command execution / XYMODEM transfering.
The raw option can be set to one of the following:
off flow control, character mapping and output delay are enabled
on software flow control and character mapping are disabled; output delay remains enabled
on-nodelay software flow control, character mapping and output delay is disabled
Default value is "on".
--raw-interactive off|on|on-nodelay
Set raw mode for interactive use.
Interactive use is normal terminal input/output and socket redirection.
This is useful when transferring files through socket redirection.
Default value is "off".
--rs-485
Enable RS-485 mode.
@ -277,13 +311,21 @@ OPTIONS
Mute tio messages.
--script-init-file <filename>
Run script from file with filename on tio's startup.
Execution occurs before connecting to the device, and loaded functions and variables are preserved.
The default is <<not-specified>>, which only loads built-in functions and variables.
--script <string>
Run script from string.
Run script from string on connect.
--script-file <filename>
Run script from file with filename.
Run script from file with filename on connect.
--script-run once|always|never
@ -295,6 +337,11 @@ OPTIONS
Execute shell command with I/O redirected to device
The standard output and standard error of a shell command are redirected to the device through tio's output filters (with output mapping and output delay enabled), and input from the device is redirected to
the standard input of the shell command.
If you specify '?' as a shell commands prefix, standard error output will not be redirected. This allows you to use some communication commands such as sz/rz.
--complete-profiles
Prints profiles (for shell completion)
@ -326,6 +373,10 @@ KEY COMMANDS
ctrl-t i Toggle input mode
ctrl-t j Toggle raw mode for non-interactive use
ctrl-t J Toggle raw mode for interactive use
ctrl-t l Clear screen
ctrl-t L Show line states (DTR, RTS, CTS, DSR, DCD, RI)
@ -348,54 +399,62 @@ KEY COMMANDS
ctrl-t v Show version
ctrl-t x Send file using the XMODEM-1K or XMODEM-CRC protocol (prompts for file name and protocol)
ctrl-t x Send file using the XMODEM-1K, XMODEM-CRC or XMODEM-SUM protocol (prompts for file name and protocol)
ctrl-t y Send file using the YMODEM protocol (prompts for file name)
ctrl-t ctrl-t Send ctrl-t character
SCRIPT API
Tio suppots Lua scripting to easily automate interaction with the tty device.
Tio supports Lua scripting to easily automate interaction with the tty device.
In addition to the standard Lua API tio makes the following functions available:
expect(string, timeout)
Expect string - waits for string to match or timeout before continuing. Supports regular expressions. Special characters must be escaped with '\\'. Timeout is in milliseconds, defaults to 0 meaning it will wait forever.
tio.expect(pattern, timeout)
Waits for the Lua pattern to match or timeout before continuing. Special characters must be escaped with '\\' or '%'.
Timeout is in milliseconds, defaults to tio.C.WAIT_FOREVER(==0) meaning it will wait forever.
Returns 1 on successful match, 0 on timeout, or -1 on error.
On success, returns the captures from the pattern and all received data.
On timeout, returns nil and all received data.
On successful match it also returns the match string as second return value.
tio.expects(pattern-table, timeout)
Waits for any of the multiple Lua patterns to match or timeout before continuing. Special characters must be escaped with '\\' or '%'.
Timeout is in milliseconds, defaults to tio.C.WAIT_FOREVER(==0) meaning it will wait forever.
read(size, timeout)
Read up to size bytes from serial device. If timeout is 0 or not provided it will wait forever until data is ready to read.
On success, returns the index of the matched pattern, the captures from it and all received data.
On timeout, returns nil, nil and all received data.
Returns number of bytes read on success, 0 on timeout, or -1 on error.
tio.read(size, timeout)
Read up to size bytes from serial device. If timeout is tio.C.WAIT_FOREVER(==0) or not provided it will wait forever until data is ready to read.
If the timeout is tio.C.NOWAIT (==-1), the function immediately reads as much data as possible from the serial device's RX buffer, up to a maximum of <size> bytes, and returns.
On success, returns read string as second return value. Also emits a single timestamp to stdout and log file per options.timestamp and options.log.
On success, returns read data as string. Also emits a single timestamp to stdout and log file per options.timestamp and options.log.
On timeout, returns nil and received data.
read_line(timeout)
Read line from serial device. If timeout is 0 or not provided it will wait forever until data is ready to read.
tio.readline(timeout)
Read line from serial device. If timeout is tio.C.WAIT_FOREVER(==0) or not provided it will wait forever until data is ready to read.
The line separater is LF (0x0a).
Returns number of bytes read on success, 0 on timeout, or -1 on error.
On success, returns received line as string. Also emits a single timestamp to stdout and log file per options.timestamp and options.log.
On timeout, returns nil and received data.
On success, returns the string that was read as second return value. Also emits a single timestamp to stdout and log file per options.timestamp and options.log.
write(string)
Write string to serial device without Input-editing, Output-mapping nor Output-delay.
tio.write(string)
Write string to serial device without input-editing, output-mapping nor output-delay.
Returns the tio table on success or nil on error.
twrite(string)
Write string to serial device with Input-editing, Output-mapping and Output-delay.
tio.twrite(string)
Write string to serial device with input-editing, output-mapping and output-delay.
Returns the tio table on success or nil on error.
send(file, protocol)
tio.send(file, protocol)
Send file using x/y-modem protocol.
Protocol can be any of XMODEM_1K, XMODEM_CRC, YMODEM.
Protocol can be any of XMODEM_1K, XMODEM_CRC, XMODEM_SUM, YMODEM.
It can alternatively be one of tio.C.XM_1K, tio.C.XM_CRC, tio.C.XM_SUM, tio.C.YM_NORMAL.
tty_search()
tio.ttysearch()
Search for serial devices.
Returns a table of number indexed tables, one for each serial device found. Each of these tables contains the serial device information accessible via the following string indexed elements "path", "tid", "uptime", "dri‐
@ -403,21 +462,101 @@ SCRIPT API
Returns nil if no serial devices are found.
set{line=state, ...}
tio.set{line=state, ...}
Set state of one or multiple tty modem lines.
Line can be any of DTR, RTS, CTS, DSR, CD, RI
State is high, low, or toggle.
State is high (==tio.C.LN_HIGH), low (==tio.C.LN_LOW), or toggle (==tio.C.LN_TOGGLE).
sleep(seconds)
tio.sleep(seconds)
Sleep for seconds.
msleep(ms)
tio.msleep(ms)
Sleep for milliseconds.
exit(code)
Exit with exit code.
tio.send_break()
Send break signal.
It is equivalent to the key command ctrl-t b.
tio.line_get()
Get state of multiple tty modem lines.
It is equivalent to the key command ctrl-t L.
Return 6 values DTR, RTS, CTS, DSR, CD, RI.
Each return value is high (==tio.C.LN_HIGH) or low (==tio.C.LN_LOW).
tio.set_local_echo(on_off)
Change the local echo setting.
It is equivalent to the key command ctrl-t e.
The argument on_off is a boolean value. true means on and false means off. If omitted, it is set to true.
tio.set_log(on_off)
Change the log-file setting.
It is equivalent to the key command ctrl-t f.
The argument on_off is a boolean value. true means on and false means off. If omitted, it is set to true.
tio.flush_data_io_buffer()
Flush read/write data in I/O buffers.
It is equivalent to the key command ctrl-t F.
tio.set_input_mode(input_mode)
Change the input mode.
It is equivalent to the key command ctrl-t i.
The argument input_mode is one of tio.C.IM_NORMAL, tio.C.IM_HEX, tio.C.IM_LINE.
tio.set_output_mode(output_mode)
Change the output mode.
It is equivalent to the key command ctrl-t o.
The argument output_mode is one of tio.C.OM_NORMAL, tio.C.OM_HEX.
tio.set_raw_mode(raw_mode)
Change the raw mode for non-interactive use.
It is equivalent to the key command ctrl-t j.
The argument raw_mode is one of tio.C.RAW_OFF, tio.C.RAW_ON, tio.C.RAW_ON_NODELAY.
tio.set_raw_mode_interactive(raw_mode)
Change the raw mode for interactive use.
It is equivalent to the key command ctrl-t J.
The argument raw_mode is one of tio.C.RAW_OFF, tio.C.RAW_ON, tio.C.RAW_ON_NODELAY.
tio.set_timestamp_mode(timestamp_mode)
Change the timestamp mode.
It is equivalent to the key command ctrl-t t.
The argument timestamp_mode is one of tio.C.TS_OFF, tio.C.TS_24HOUR, tio.C.TS_24HOUR_START, tio.C.TS_24HOUR_DELTA, tio.C.TS_ISO861, tio.C.TS_EPOCH, tio.C.TS_EPOCH_USEC.
tio.exec_shell_command(shell_commands)
Execute /bin/sh -c <<shell_commands>>.
Normally, standard output / standard error is forwarded to tio's output filter which do output mapping and output delay.
If the shell commands starts with '?', '?' is removed and standard error is not forwarded.
It is equivalent to the key command ctrl-t R.
The argument shell_commands is string.
tio.get_state()
Return the main state of tio as a integer.
Return value is one of tio.C.SA_INTERACTIVE, tio.C.SA_STARTING, tio.C.SA_PIPED_INPUT, tio.C.SA_PIPED_INPUT, tio.C.SA_EXEC_SHELL_COMMAND, tio.C.SA_XYMODEM.
tio.get_version()
Return the version of tio as a string.
It is equivalent to the key command ctrl-t v.
tio.alwaysecho
A boolean value, defaults to true.
If tio.alwaysecho is false, the result of tio.read, tio.readline or tio.expect will only be returned from the function and not logged or printed.
If tio.alwaysecho is set to true, reading functions also emit a single timestamp to stdout and log file per options.timestamp and options.log.
os.exit(code)
Exit tio process with exit code (like ctrl-t q).
CONFIGURATION FILE
Options can be set via configuration file using the INI format. tio uses the configuration file first found in the following locations in the order listed:
@ -456,6 +595,8 @@ CONFIGURATION FILE
output-line-delay Set output line delay
output-line-delay-char Set trigger character of output line delay
line-pulse-duration Set line pulse duration
no-reconnect Do not reconnect
@ -480,6 +621,8 @@ CONFIGURATION FILE
map Map characters on input or output
keymap Set key-script mappings
color Colorize tio text using ANSI color code ranging from 0 to 255
input-mode Set input mode
@ -498,11 +641,13 @@ CONFIGURATION FILE
mute Mute tio messages
script Run script from string
script-init-file Run script from file on tio's startup
script-file Run script from file
script Run script from string on connect
script-run Run script on connect
script-file Run script from file on connect
script-run Set condition to run script on connect
exec Execute shell command with I/O redirected to device
@ -593,7 +738,7 @@ EXAMPLES
It is also possible to use tio's own simpler expect/send script functionality to e.g. automate logins:
$ tio --script 'expect("login: "); write("root\n"); expect("Password: "); write("root\n")' /dev/ttyUSB0
$ tio --script 'tio.expect("login: "); tio.write("root\n"); tio.expect("Password: "); tio.write("root\n")' /dev/ttyUSB0
Redirect device I/O to network file socket for remote TTY sharing:
@ -625,7 +770,19 @@ EXAMPLES
Manipulate DTR and RTS lines upon first connect to reset connected microcontroller:
$ tio --script "set{DTR=high,RTS=low}; msleep(100); set{RTS=toggle}" --script-run once /dev/ttyUSB0
$ tio --script "tio.set{DTR=high,RTS=low}; tio.msleep(100); tio.set{RTS=toggle}" --script-run once /dev/ttyUSB0
Manipulate DTR and RTS lines by pressing ctrl-t 1:
$ tio --keymap '@1=!tio.set{DTR=high,RTS=low}; tio.msleep(100); tio.set{RTS=toggle}' /dev/ttyUSB0
Send file to device by sz command:
$ tio --exec "?sz -b file" /dev/ttyUSB0
Receive file from device by rz command:
$ tio --exec "?rz -b" /dev/ttyUSB0
WEBSITE
Visit https://tio.github.io