# Twinleaf I/O Tools in Rust
Command-line tools for working with Twinleaf quantum sensors and accessories. Contains a proxy, terminal UIs, and command line utilities.
**Note**: In versions <2.0.0, this crate contained binaries named `tio-proxy`, `tio-monitor`, `tio-health`, and `tio-tool`. These commands are now packaged as subcommands under a singular binary `tio`. These commmands are now used without the `-`, with `tio-tool {toolname}` calls having been replaced with `tio {toolname}`.
### Shell completions
`tio` can generate completion scripts for bash, zsh, fish, and PowerShell. Add the matching line to your shell's config file:
# Bash (~/.bashrc)
eval "$(tio completions bash)"
# Zsh (~/.zshrc)
eval "$(tio completions zsh)"
# Fish (~/.config/fish/config.fish)
tio completions fish | source
# PowerShell ($PROFILE)
tio completions powershell | Invoke-Expression
Run `tio completions --help` to see the full list of supported shells. Zsh users may need to prepend `autoload -Uz compinit && compinit`.
### Connecting to the device
The general workflow is to connect using `tio proxy` which allows all the CLI tools to work with the single device at the same time. The proxy makes a device attached via serial port available via Ethernet. With no arguments it automatically scans for a `twinleaf` serial device:
tio proxy
When more than one serial port is available, specify the URL:
[linux] tio proxy serial:///dev/ttyACM0
[macOS] tio proxy serial:///dev/cu.usbserialXXXXXX
[wsl1] tio proxy serial://COM3
The proxy allows multiple tools to connect to the device over TCP simultaneously.
When a sensor is attached to a hub at port `0`, restrict the proxy's subtree using the `-s` flag:
tio proxy -s /0
### Interacting with the device in terminal
Logging metadata:
tio log meta # Write metadata to meta.tio
tio log dump meta.tio # Parse meta.tio and print to terminal
Logging sample data:
# Log samples and write to log.{date-time}.tio until quit (Ctrl+C)
tio log
# Parse a stream from .tio file and write to csv
tio log csv {stream name/id} {file}
# Write to HDF5 file (requires `--features hdf5` on install)
tio log hdf {file} -g "{route}/{stream}/{column}"
tio log hdf {file} -g "*/{stream or column}"
Dump data to terminal:
tio dump --data # Continuously print parsed samples
tio dump --data --meta # Same as above, with metadata header
Device commands:
tio rpc list # List of rpc commands with types
tio rpc {command} [arg] # Issue command with optional argument
## Terminal UIs
### tio monitor
Displays a live stream of incoming data with in-terminal graphs and command suggestions. Graph a stream by selecting it with the arrow keys and pressing Enter, and enter command mode by typing `:` (colon). Use `tio monitor -s {route}` to scope the view to a single device subtree (e.g. `-s /0/1`), or `--depth N` to limit how deep the device tree is traversed.
Run with:
tio monitor
### tio health
Displays a live table of all incoming data with some statistics to verify the behavior of devices. It also outputs a history of events derived from the `Sample` protocol implemented in the `twinleaf` crate, derived within the `data/buffer.rs` file.
Run with:
tio health
## Installation
The tools can be installed using
cargo install twinleaf-tools
They can be installed with the ability to convert to HDF5 using
cargo install twinleaf-tools --features hdf5
It is convenient to add the cargo binary directory to the default search paths. Cargo will report where the binaries and installed and which path to add to your environment, if necessary.
The `serialport` library depends on `libudev` that is not included on certain linux distributions. To install it use:
sudo apt install libudev-dev # debian linux
## Cross compilation
The tools can be compiled for other platforms by first adding those platform targets:
rustup target add x86_64-pc-windows-gnu
rustup toolchain install stable-x86_64-pc-windows-gnu
And then building for the new target:
cargo build --target x86_64-pc-windows-gnu