From 273afb73f450b4bede7ed92bc16195051d1c6b6e Mon Sep 17 00:00:00 2001 From: Martin Lund Date: Sun, 28 Apr 2024 17:20:41 +0200 Subject: [PATCH] Update README --- README.md | 179 ++++++++++++++++++------------------------------------ 1 file changed, 58 insertions(+), 121 deletions(-) diff --git a/README.md b/README.md index 96712c6..2356298 100644 --- a/README.md +++ b/README.md @@ -147,14 +147,12 @@ Options and profiles may be set via configuration file. See the man page for more details. ``` -By default tio automatically connects to the provided TTY device if present. -If the device is not present, it will wait for it to appear and then connect. -If the connection is lost (eg. device is unplugged), it will wait for the -device to reappear and then reconnect. However, if the `--no-reconnect` -option is provided, tio will exit if the device is not present or an -established connection is lost. - -tio features full bash autocompletion. +By default tio automatically connects to the provided TTY device. If the device +is not present, tio will wait for it to appear and then connect. If the +connection is lost (e.g. device is unplugged), it will wait for the device to +reappear and then reconnect. However, if the `--no-reconnect` option is +provided, tio will exit if the device is not present or an established +connection is lost. #### 3.1.1 Examples @@ -168,12 +166,39 @@ Which corresponds to the commonly used default options: $ tio --baudrate 115200 --databits 8 --flow none --stopbits 1 --parity none /dev/ttyUSB0 ``` +List available serial devices: +``` +$ 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 +``` + It is recommended to connect serial TTY devices by ID: ``` -$ tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTGQVXBL-if00-port0 +$ tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTCHUV56-if00-port0 ``` -Using serial devices by ID ensures that tio automatically reconnects to the -correct serial device if it is disconnected and then reconnected. +Using serial devices by ID helps ensure that tio automatically reconnects to +the same serial device when reattached, even when it enumerates differently. If no serial device by ID is available it is recommended to connect via topology ID (TID): @@ -181,27 +206,38 @@ topology ID (TID): $ tio bCC2 ``` The TID is unique and will stay the same as long as your USB serial port device -plugs into the same USB topology (same ports, same hubs, etc.). This way tio -will successfully reconnect to the same device each time. +plugs into the same USB topology (same ports, same hubs, etc.). This way it is +possible for tio to successfully reconnect to the same device. -List available serial devices: -``` -$ tio --list -``` -Note: One can also use tio bash shell completion on /dev which will -automatically list all available serial TTY devices by ID. - -Automatically connect to first new appearing serial device: +Connect automatically to first new appearing serial device: ``` $ tio --auto-connect new ``` +Connect automatically to latest registered serial device: +``` +$ tio --auto-connect latest +``` + +It is also possible to use exclude options to affect which serial devices are +involved in the automatic connection strategy: +``` +$ tio --auto-connect new --exclude-devices "/dev/ttyACM?,/dev/ttyUSB2" +``` + +Exclude drivers by pattern: +``` +$ tio --auto-connect new --exclude-drivers "cdc_acm,ftdi_sio" +``` +Note: Pattern matching supports '*' and '?'. Use comma separation to define +multiple patterns. + Log to file with autogenerated filename: ``` $ tio --log /dev/ttyUSB0 ``` -Log to file with filename: +Log to file with specific filename: ``` $ tio --log --log-file my-log.txt ``` @@ -232,105 +268,6 @@ $ echo "*IDN?" | tio /dev/ttyACM0 --script "expect('\r\n', 1000)" --mute KORAD KD3305P V4.2 SN:32475045 ``` -### 3.1.2 Different ways to connect to serial devices - -Using tio there are up to 4 recommended ways to connect to a specific serial -device: - -Connect by ID (preferred method): -``` -$ tio /dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTCHUV56-if00-port0 -``` - -Connect by topology ID: -``` -$ tio bCC2 -``` - -Connect to enumerated device in /dev: -``` -$ tio /dev/ttyUSB4 -``` - -Connect by path: -``` -$ tio /dev/serial/by-path/pci-0000:00:14.0-usb-0:8.1.3.1.4:1.0-port0 -``` - -Which serial device to connect becomes more clear from tio's serial device -listing which provides more information about each serial device. For example: -``` -$ tio --list -Device TID Uptime [s] Driver Description ------------------ ---- ------------- ---------------- -------------------------- -/dev/ttyS4 8xSh 32532.317 port 16550A UART -/dev/ttyS5 HJhB 32530.578 port 16550A UART -/dev/ttyUSB3 yW07 32464.194 ftdi_sio TTL232RG-VREG3V3 -/dev/ttyUSB4 bCC2 26066.573 ftdi_sio TTL232R-3V3 -/dev/ttyUSB0 g5q4 136.717 ftdi_sio Flyswatter2 -/dev/ttyUSB1 h5q4 136.715 ftdi_sio Flyswatter2 -/dev/ttyACM0 EOEs 10.449 cdc_acm ST-Link VCP Ctrl - -By-id --------------------------------------------------------------------------------- -/dev/serial/by-id/usb-FTDI_TTL232RG-VREG3V3_FT1NC2D0-if00-port0 -/dev/serial/by-id/usb-FTDI_TTL232R-3V3_FTCHUV56-if00-port0 -/dev/serial/by-id/usb-TinCanTools_Flyswatter2_FS20000-if00-port0 -/dev/serial/by-id/usb-TinCanTools_Flyswatter2_FS20000-if01-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.2.2:1.0-port0 -/dev/serial/by-path/pci-0000:00:14.0-usbv2-0:8.1.3.2.2:1.0-port0 -/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-usb-0:6.3:1.0-port0 -/dev/serial/by-path/pci-0000:00:14.0-usbv2-0:6.3:1.0-port0 -/dev/serial/by-path/pci-0000:00:14.0-usb-0:6.3:1.1-port0 -/dev/serial/by-path/pci-0000:00:14.0-usbv2-0:6.3:1.1-port0 -/dev/serial/by-path/pci-0000:00:14.0-usb-0:6.4:1.2 -/dev/serial/by-path/pci-0000:00:14.0-usbv2-0:6.4:1.2 -``` - -Note: The topology ID (TID) is a unique hash of the full topology path of the -connected device. This means that every time e.g. a USB serial port device is -plugged into to the exact same USB topology (same ports, same hubs, etc.) it -will get the exact same TID. This helps solve the problem of reconnecting to -serical devices which do not provide a unique device by ID. - -Additonally tio offers two convenient ways of connecting to serial devices. - -Connect automatically to first new appearing serial device: -``` -$ tio --auto-connect new -``` - -Connect automatically to latest registered serial device: -``` -$ tio --auto-connect latest -``` - -It is also possible to use exclude options to affect which serial devices are -involved in the strategy decisions: - -Exclude devices by pattern: -``` -$ tio --auto-connect new --exclude-devices "/dev/ttyACM?,/dev/ttyUSB2" -``` - -Exclude drivers by pattern: -``` -$ tio --auto-connect new --exclude-drivers "cdc_acm,ftdi_sio" -``` - -Exclude topology IDs by pattern: -``` -$ tio --auto-connect new --exclude-tids "EOEs" -``` - -Note: Pattern matching supports '*' and '?'. Use comma separation to define multiple patterns. - ### 3.2 Key commands Various in session key commands are supported. When tio is started, press