tio

Changes since tio v3.2:

• Force destructive backspace when using local echo

  Only takes effect in normal output mode.

• Fix local-echo in configuration file

• Clean up includes

• Force socket write operation to ignore any signals

• Man page cleanup

Changes since tio v3.1:

• Do not print error when using --list with broken config file

• Clean up completion script

• Add option '--exec ' for running shell command

  Runs shell command with I/O redirected to device.

• Make sure all error output is directed to stderr

• Fix shadow variables

• Update man page

• Fix build on older GNU/Linux systems without statx

• Fix line ending in --list output

• Print location of configuratin file in --list output

• Fix alignment of profile listing

Changes since tio v3.0:

• Improve --list feature on non-linux platform

• List available profiles in --list output

• Always message when saving log file

• Add support for using TID as device in config file

• Fix use of invalid flag with regexec()

• Fix potential buffer overflow in match_and_replace()

• Fix profile autocompletion

• Remove inih dependency from CI builds

• Replace use of stat() with fstat()

  For better security.

• Fix hexN output mode

• Update pattern matching example

• Fix submenu response when invalid key hit

• Replace inih with glib key file parser

  After including the use of glib we might as well replace inih
  with the glib key file parser.

  All configuraiton file parsing has been reworked and also the options
  parsing has been cleaned up, resulting in better and stricter
  configuration file and option value checks.

  Compared to old, configuration files now requires any default
  configurations to be put in a group/section named [default].

  Configuration file keywords such as "enable", "disable", "on",
  "off", "yes", "no", "0", "1" have been retired. Now only "true" and
  "false" apply to boolean configuration options. This is done to simplify
  things and avoid any confusion.

  The pattern option feature has been reworked so now the user can now
  access the full match string and any matching subexpression using the
  %mN syntax.

  For example:

  [usb devices]
  pattern = usb([0-9]*)
  device = /dev/ttyUSB%m1

  Then when using tio:
  $ tio usb12

  %m0 = 'usb12' // Full match string
  %m1 = 12 // First match subexpression

  Which results in device = /dev/ttyUSB12

• Remove CircleCI

  Replaced with github workflow CI.

• Add github workflow for Ubuntu build

• Enable extended pattern matching

  So that the exclude options can also work as include using special
  pattern syntax.

  For example, to only include /dev/ttyUSB* devices simply do:

  $ tio --exclude-devices=!(/dev/ttyUSB*) --list

  See the man page of fnmatch() for all available extended pattern
  options.

• Update lua read() description

Rui Chen:

• fix: add build patch for FNM_EXTMATCH

• feat: add macos workflow

• fix: add macos build patch for fs_get_creation_time

Changes since tio v2.8:

• Simplify lua line manipulation API

  Collapses lua high(), low(), toggle(), config_high(), config_low(),
  config_apply() into one simple function:

  set{<line>=<state>, ...}

  Line can be any of DTR, RTS, CTS, DSR, CD, RI.

  State is high, low, or toggle.

  Example:
  script = set{DTR=high, RTS=low}; msleep(100); set{DTR=low, RTS=high}; msleep(100); set{RTS=low}

  Notice the use of {} instad of () when calling the set function. This is
  required to pass parameters by name in lua.

• Disable DEC Special Graphics at exit if vt100

  If a vt100 terminal receives the Shift In character '\016' it will
  enable the 7 bit DEC Special Graphics character set used for line drawing.

  For most users this can happen due to line noise from the tty device and
  will likely mess up your terminal even after tio exits.

  To better handle this we want to make sure that tio disables this mode
  by sending the Shift Out character '\017' at exit.

  This mechanism will only activate if environment variable TERM assumes
  value "vt100".

• Add hexN output mode

  Adds support for hexN mode where N is a number in the range 1 to 4096
  which defines how many hex values will be printed before a line break.

  In short, it defines the width of the hex output.

  In this mode, if timestamps are enabled they will be added to each hex
  line.

• Rename sub-config to profile

  Because better naming.

• Use lua io.write() instead of print()

  io.write() gives better output control as print() is hardcoded to always
  print a newline.

• Add new ways to manage serial devices

  • Rename --list-devices to --list

  • Rename --no-autoconnect to --no-reconnect

  • Switch -l and -L options

    • -l now lists available serial devices

    • -L enables log to file

  • Add option --auto-connect

    • Supported strategies:

      • "new" - Waits to connect first new appearing serial device

      • "latest" - Connects to latest registered serial device

      • "direct" - Connect directly to specified serial device (default)

  • Add options to exclude serial devices from auto connect strategy by
    pattern

    • Supported exclude options:

      • --exclude-devices

        Example: '--exclude-devices "/dev/ttyUSB2,/dev/ttyS?"'

      • --exclude-drivers

        Example: '--exclude-drivers "cdc_acm"'

      • --exclude-tids

        Example: '--exclude-tids "yW07,bCC2"'

      • Patterns support '*' and '?'

  • Connect to same port/device combination via unique topology ID (TID)

    • Topology ID is a 4 digit base62 encoded hash of a device topology
      string coming from the Linux kernel. This means that whenever you
      plug in the same e.g. USB serial port device to the same USB hub
      port connected via the exact same hub topology all the way to your
      computer, you will get the same unique TID.

    • Useful for stable reconnections when serial device has no serial
      device by ID

    • For now, only tested on Linux.

  • Reworked and improved listing of serial devices to show serial devices:

    • By device

      • Including TID, uptime, driver, and description.

      • Sorted by uptime (newest device listed last)

    • By unique topology ID

    • By ID

    • By path

  • Add script interface 'list = tty_search()' for searching for serial
    devices.

• Clean up timestamp enum definition

• Add missing options to show configuration

• Update description of mute option

• Add lua read_string() function

• Don't forget to log output in lua expect()

• Generalize automatic login example for Linux

• Fix log output in hex output mode

• Add timeout based timestamps in hex output mode

  This change reintroduces timestamping in hex output mode but based on
  timeout instead of new lines which made no sense. This means that
  timestamps will only be printed when timeout time has elapsed with no
  output activity from serial device.

  Adds option --timestamp-timeout for setting the timeout value in
  milliseconds.

  Defaults to 200 ms.

• Improve switched messages

• Extend lua expect() to also return matched string

• Add automatic login script example

• Organize examples directory

• Introduce basic line input mode

• Cleanup global variable name shadowing

Davis C:

• Updated login example with new expect logic

• Reset buffer size at start of expect

• Return 1 when expect matches

Changes since tio v2.7:

• Rework resolve_config_file()

• Rework line_pulse_duration_option_parse()

  Introduce proper sscanf() checks.

• Rework rs485_parse_config()

  Introduce proper sscanf() checks.

• Clean up file descriptor name shadowing

• Add missing header guard

• Upgrade inih subproject

• Remove options --response-wait, --response-timeout

  Remove options and rework input handling so it is possible to do the
  same thing but via script which is much more flexible.

  These options were always a bit of a hardcoded solution. With the new
  script expect feature we can wait for any type of response.

  For example, pipe command to serial device and wait for line response within 1 second:

  $ echo "*IDN?" | tio /dev/ttyACM0 --script "expect('\r\n', 1000)" --mute

• Add lua exit(code)

• Add timeout feature to expect()

• Add lua expect(string)

  Add simple expect functionality.

  The expect(string) function will wait for input from the tty device and
  only return when there is a string match. Regular expressions are
  supported.

  Example:

  script = expect('password:'); send('my_password\n')

• Add lua send(string)

• Add lua modem_send(file,protocol)

• Fix xymodem error print outs

• Rework x/y-modem transfer command

  Remove ctrl-t X optin and instead introduce submenu to ctrl-t x option
  for picking which xmodem protocol to use.

• Update README

• Cleanup options

• Add independent input and output mode

  Replaces -x, --hexadecimal option with --intput-mode and --output-mode
  so it is possible to select hex or normal mode for both input and output
  independently.

  To obtain same behaviour as -x, --hexadecimal use the following
  configuration:

  input-mode = hex
  output-mode = hex

• Fix file descriptor handling on MacOS

• Add tty line configuration script API

  On some platforms calling high()/low() to switch line states result in
  costly system calls whick makes it impossible to swith two or more tty
  lines simultaneously.

  To help solve this timing issue we introduce a tty line state
  configuration API which can be used instead of using
  high()/low().

  Using config_low(line) and config_high(line) one can set up a new line
  state configuration for multiple lines and then use config_apply() to
  finally apply the configuration. This will result in only one system
  call to instruct the serial port drive to switch all the configured line
  states which should help ensure that the lines are switched
  simultaneously.

  Example:

  script = config_high(DTR); config_low(RTS); config_apply()

• Add ONULBRK mapping flag

  Add ONULBRK mapping to map nul (zero) to send break signal on output.

  This is useful if one needs to e.g. send the break signal to the tty
  device when connected via socket.

• Add --log-directory option

  For specifying directory path in which to save automatically named log
  files.

• Add Lua scripting feature

  Add support for running Lua scripts that can manipulate the tty control
  lines. Script is activated automatically on connect or manually via in
  session key command.

  The Lua scripting feature opens up for many posibilities in the future
  such as adding expect like functionality to easily and programatically
  interact with the connected device.

• Invert line states to reflect true electrical level

• Add support for disabling prefix key handling

  To disable prefix key input handing simply set prefix-ctrl-key to
  'none'.

  Based on original patch from Sebastian Krahmer.

• Add meson man pages install option

  Defaults to installing man pages.

HiFiPhile:

• Poll on serial port read instead of delay.

• Add Xmodem-CRC support.

• CYGWIN: Fix port auto connection.

Mingjie Shen:

• Check return values of sscanf()

  Failing to check that a call to 'sscanf' actually writes to an output
  variable can lead to unexpected behavior at reading time.

Jakob Haufe:

• Support NO_COLOR env variable as per no-color.org

• Fix troff warning

  .eo/.ec sections seemingly need explicit empty lines using .sp

  Otherwise, troff complains:

  troff::535: warning: expected numeric expression, got ''
  troff::538: warning: expected numeric expression, got ''
  troff::541: warning: expected numeric expression, got ''

Fredrik Svedberg:

• Add map FF to ESC-c on input

  Added map of form feed to ESC-c on input for terminals that
  do not clear screen on ^L but do on ESC-c.

Brian:

• Add CodeQL Workflow for Code Security Analysis

Sylvain LAFRASSE:

• Fix double call of tty_disconnect() on macOS/Darwin.

Changes since tio v2.6:

Paul Ruizendaal:

• Add xmodem and ymodem file send support

HiFiPhile:

• tty_stdin_input_thread(): write to pipe only if byte_count > 0.

• Ignore EINTR error.

• CYGWIN: Add support for "COM*" naming.

Wes Koerber:

• chore: reorder log-strip and log-append

  reorder to maintain consistency with documentation

• chore: update readme, bash completion, man page

• fix: support --log-append in cli options

Changes since tio v2.5:

• Remove warning when using pattern option

• Add --log-append option

  Add --log-append option which makes tio append to any existing log file.

  This also changes the default behaviour of tio from appending to
  overwriting any existing log file. Now you have to use this new option
  to make tio append.

• Update man page

• Update README

• Fix line termination for response wait feature

  The response wait feature waited for a line response, a string
  terminated with either CR or NL. However, some devices may send a CR and
  then their line content and then NL. This means tio will quit before
  receiving and printing the line response. To solve this we simply ignore
  the CR character and only consider lines terminated with a NL character.

  This should work for all devices as lines are AFAIK always terminated
  with either CRNL or a NL.

• Update tty device listing configuration

  Cleanup and add FreeBSD tty device listing support.

Braden Young:

• Move map variables to tty to keep them all in one spot

• Configure socket mapping flags from tty parsing logic. Remove duplicate parsing logic in socket

• Support input mapping modes for sockets

Josh Soref:

• Various spelling fixes

Peter van Dijk:

• avoid "warning: unused parameter" on setspeed stub

• use right /dev/ path on Haiku

Bill Hass:

• Update README with details on snap confinement

Changes since tio v2.4:

• Update configuration file documentation

  Rename .tiorc to .tioconfig, tiorc to config, etc.

• Add support for $HOME/.tioconfig

  Replaces what used to be $HOME/.tiorc

• Fix double prefix key regression

Vyacheslav Patkov:

• Better error checking in config file, rename the file

  Accept "true", "enable", "on", "yes", "1" as true values, their
  counterparts as false ones. Check integer values for errors and range.
  Warn about ignored (e.g. misspelled) options.

  Check getenv() return value for NULL.

  Rename "tiorc" to "config", as it's a static INI file, not an executable
  "run commands".

Changes since tio v2.3:

• Add threaded input handling

  To make tio more responsive to quit and I/O flush key command when main I/O
  thread is blocked on output.

• Fix so that is it possible to quit tio in tio etc.

  Fix regression so that it is possible to send the prefix key code to the
  remote tio session without local tio session reacting to same key code
  (quitting etc.).

• Add key command to toggle log on/off

  Add key command 'ctrl-t f' which will toggle log on/off.

  If no log filename has been specified via the 'log-filename' option then
  tio will automatically generate a new log filename every time the log
  feature is toggled on. Meaning, when toggled multiple times, multiple
  log files will be generated.

  However, if a log filename has been specified, tio will only write and
  append to that same file.

Changes since tio v2.2:

• Add mute feature

  This will make tio go fully silent and not print anything.

• Rename config variable 'tty' to 'device'

• Deprecate tty config keyword but keep it around for now

• Update show config

• Update example tiorc

Changes since tio v2.1:

• Add shell completion of sub-configuration names

  Does not work with sub configuration names that contains one or more
  white spaces.

• Beautify help

• Fix error message

• Simplify configfile implementation

Changes since tio v2.0:

• Fix output line delay

  Apply output line delay on lines ending with \n.

  On most systems lines ends with \n or \r\n.

• Do not print timestamps in hex mode

• Improve input mechanism in hex mode

  Print the 2 character hex code that you input in hex mode but then
  delete it before sending. This way it is easier to keep track of what
  you are inputting. It basically mimics the ctrl-shift-u input mechanism
  that is used to input unicode.

• Add support for sending prefix character to serial device

  Do so by inputting prefix key twice, e.g. input ctrl-t ctrl-t to send
  ctrl-t character to serial device.

• Clean up indentation

• Update example tiorc

Attila Veghelyi:

• Add bit reverse order feature

Changes since tio v1.47:

• Handle stale unix socket file

  Delete existing unix socket file if it is tested to be stale, meaning no
  one is listening on it.

• Add visual or audible alert support on connect/disconnect

  The feature is detailed via the following option:

  --alert none|bell|blink

  Set alert action on connect/disconnect.

  It will sound the bell once or blink once on successful connect.
  Likewise it will sound the bell twice or blink twice on disconnect.

  Default value is "none" for no alert.

• Add experimental RS-485 support

  Many modern RS-485 serial devices such as the ones from FTDI already
  operate in RS-485 mode by default and will work with tio out of the box.
  However, there are some RS-232/485 devices which need to be switched
  from e.g. RS-232 to RS-485 mode to operate accordingly on the physical
  level.

  This commit implements the switching mechanism and interface required to
  enable RS-485 mode. It only works on Linux and with serial devices which
  use device drivers that support the Linux RS-485 control interface.

  The RS-485 feature is detailed via the following options:

  --rs-485 Enable RS-485 mode
  --rs-485-config Set RS-485 configuration

  Set the RS-485 configuration using the following key or key value pair
  format in the configuration field:

  RTS_ON_SEND=value Set logical level (0 or 1) for RTS pin when sending
  RTS_AFTER_SEND=value Set logical level (0 or 1) for RTS pin after sending
  RTS_DELAY_BEFORE_SEND=value Set RTS delay (ms) before sending
  RTS_DELAY_AFTER_SEND=value Set RTS delay (ms) after sending
  RX_DURING_TX Receive data even while sending data

  If defining more than one key or key value pair, they must be comma
  separated.

  Example use:

  $ tio /dev/ttyUSB0 --rs-485 --rs-r485-config=RTS_DELAY_AFTER_SEND=50,RX_DURING_TX

• Add line response feature

  Add a simple line response feature to make it possible to send e.g. a
  command string to your serial device and easily receive and parse a line
  response.

  This is a convenience feature for simple request/response interaction
  based on lines. For more advanced interaction the socket feature should
  be used instead.

  The line response feature is detailed via the following options:

  -r, --response-wait

  Wait for line response then quit. A line is considered any string ending
  with either CR or NL character. If no line is received tio will quit
  after response timeout.

  Any tio text is automatically muted when piping a string to tio while in
  response mode to make it easy to parse the response.

  --response-timeout

  Set timeout [ms] of line response (default: 100).

  Example:

  Sending a string (SCPI command) to a test instrument (Korad PSU) and
  print line response:

  $ echo "*IDN?" | tio /dev/ttyACM0 --response-wait
  KORAD KD3305P V4.2 SN:32477045

• Fix potential sscanf() overflow

• Only print version on '--version'

• Remove duplicate show config entry of DTR pulse duration

• Remove MacPorts instructions

  Remove instructions for MacPorts because the port has no maintainer and
  the port build definition is broken (missing dependency on libinih etc.).

  It is recommended to use brew instead.

Peter Collingbourne:

• Ignore SIGPIPE signals

  If the remote end of a socket is closed between when an input character
  is received from the serial port and when it is written to the socket,
  tio will receive a SIGPIPE signal when writing the character to the
  socket, which will terminate the program. To prevent this, ignore the
  signal, which will cause write(2) to return -EPIPE, causing tio to close
  the socket.

Changes since tio v1.46:

• Enable log feature when using --log-filename

  No reason to not assume that the user wants to enable log when the
  --log-filename is used. This way uses can skip the use of --log to
  enable log.

• Enable line buffering of log

  Replace flushing/writing of log at every log write operation with line
  buffering, meaning log will be written line by line to make it more I/O
  friendly but still update frequently.

• Avoid invalid hex character messages when switching hex mode

• Force flushing of log writes

• Renamed tty_flush() to tty_sync()

• Fix sync output to serial port

  Using fsync() on filedescriptors for serial ports can not be relied on.
  Add use of tcdrain() to make sure data has been written by the serial
  port before proceeding.

  This fixes a problem with tio sometimes not writing piped input data to
  the serial port before exiting which results in the pending writes being
  cancelled / flushed.

• Clean up tty_flush()

• Force frequent sync on tty_flush()

• Update README

• Update example tiorc

• Quit from non-interactive mode using ctrl-c

  When piping to tio it will automatically enter "non-interactive" mode
  which means it will not react to any input key sequences but simple read
  the input stream and write it to the tty device.

  This also means that ctrl-t q can not be used to quit and so tio would
  hang forever when used in non-interactive mode.

  This change allows to send the standard termination signal by pressing
  ctrl-c on tio in non-interactive mode to make it quit.

• Make sure we flush output buffer to tty when piping to tio

• Do not return false read error when piping to tio

• Show error message when reading port settings fail

Victor Oliveira

• add macports install instructions

Changes since tio v1.45:

• Rework toggle and pulse feature to support all lines

  Replace existing toggle and pulse key commands with the following
  generalized key commands which allows to toggle or pulse all serial port
  lines:

  ctrl-t g Toggle serial port line
  ctrl-t p Pulse serial port line

  When used, user will be asked which serial line to toggle or pulse.

  Also introduce --line-pulse-duration option for setting specific pulse
  duration in milliseconds for each serial line using a key value pair
  format. Each key represents a serial line. The following keys are
  available: DTR, RTS, CTS, DSR, DCD, RI.

  Example:

  $ tio /dev/ttyUSB0 --line-pulse-duration DTR=200,RTS=300,RI=50

  Likewise, the pulse duration can also be set via configuration file
  using the line-pulse-duration variable:

  line-pulse-duration = DTR=200,RTS=300,RI=50

• Upgrade inih wrap to r56

• Optimization

• Add example configuration file

• Introduce bold color option

  Introduce "bold" color option which only apply bold color formatting to
  existing system color.

  Also make "bold" the default color option.

  Fixes all white issue with black on white tio text.

• Update README

• Change 'ctrl-t T' to 'ctrl-t t' for timestamp toggle

• Add support for remapping prefix key

  Make it possible to remap the prefix key (default: ctrl-t) by setting
  the prefix-ctrl-key variable in the configuration file.

  Allowed values are in the range a..z.

  Example, to set the prefix key to ctrl-a simply do:

  prefix-ctrl-key = a

• Add plaintext man page

Rui Chen:

• docs: add homebrew installation note

• fix macOS build

• fix compilation error

Changes since tio v1.43:

• Simplify arbitrary baudrate code

• Cleanup error printing routines

  Clean up so that only the following error related printing functions are
  used: tio_error_printf(), tio_error_printf_silent(),
  tio_warning_printf().

  A session mode switch is introduced for error printing so that it will
  print error messages with better formatting depending on in or out of
  session.

• Update README

• Clean up man page

• Add support for space parity

• Rename EOL delay to Output line delay

• Replace -U,--upcase with mapping flag OLTU

• Simplify tty_write()

Robert Snell:

• Additional commands: EOL delay, lower to upper translation, added mark parity

  Added command line options:
  -O, --eol-delay to have a separate delay for end of line
  -U, --upper to enable translation of lower case alpha to upper case

  Added ability to set mark parity.
  Added ctrl-t U key sequence to allow enable/disable lower case alpha to
  upper case during a session.
  Updated Man page with command line options, ctrl-t sequences and
  configuration file options.
  Updated README.md, with above information.

Changes since tio v1.42:

• Add '24hour-delta' timestamp option

  When enabled this option will timestamp new lines with the time elapsed
  since the line before.

  This is a very useful feature to identify which events takes the most
  time.

• Improve description of socket option

• Rename ChangeLog to NEWS

• Update README

• Update man page

George Joseph:

• Add Pulse DTR command

  MCUs like the ESP32 can be reset if the serial port DTR line is
  pulsed for a short time. You could just type CTRL-t d CTRL-t d
  but that's a little awkward since you have to lift your finger
  off the CTRL key to type the Ds. Now you can just type CTRL-T D.

  • Added new command "D" to pulse the DTR line. I.E. Toggle its
    state twice with a configurable duration between toggles.

  • Added new config/command line option "--dtr-pulse-duration"
    to set the duration between the DTR state toggles. The default
    is 100ms.

Changes since tio v1.41:

• Update man page

ZeroMemoryEx:

• Handle malloc failure

Sylvain LAFRASSE:

• Add missing 'string.h' include.

Changes since tio v1.40:

• Rename --hex-mode to --hexadecimal

• Enable buffered writing

  Read block of bytes from input and process same block for output. This
  will speed things up by reducing I/O overhead.

• Enable buffered reading

  Read block of bytes from input and process byte by byte for output. This
  will speed things up by reducing I/O overhead.

• Refactoring

• Cleanup stdout flushing

  Flushing is not needed since we disabled buffering of stdout.

• Simplify stdout_configure() code

• Simplify stdin_configure() code

• Update man page

• Update README