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

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