Skip to content

Commit abc428d

Browse files
rasen68rasen68
committed
Chore: update READMEs
1 parent 4e25fd8 commit abc428d

2 files changed

Lines changed: 66 additions & 70 deletions

File tree

‎README.md‎

Lines changed: 22 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,32 @@
11
# Twinleaf I/O Tools in Rust
22

3-
This repository contains a library and a set of tools that are useful for working with Twinleaf quantum sensors and accessories.
3+
This repository contains two Rust crates, a library (`twinleaf`) and a set of tools (`twinleaf-tools`) that are useful for working with Twinleaf quantum sensors and accessories.
44

5-
## CLI Usage
6-
All the tools mentioned can have the `--help` argument added to display more information. 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.
5+
**Note**: In versions <2.0.0, this crate contained binaries named `tio-proxy`, `tio-monitor`, `tio-health`, and `tio-tool`. These commands have been packaged into subcommands under the single binary `tio`. The former three original commands can be simply used without the `-`, while `tio-tool {toolname}` calls have largely been replaced with `tio {toolname}`.
76

8-
### tio-proxy
7+
## Basic Usage
8+
### See `twinleaf-tools/README.md` for more usage details
99

10-
The proxy makes a device attached via serial port available via Ethernet. The following will automatically scan for a `twinleaf` serial device:
10+
Connect a proxy to the device to communicate with the other tools:
1111

12-
tio-proxy --auto
12+
tio proxy
1313

14-
When there are more than one serial port available, it is necessary to specify the port using:
14+
Terminal interface (TUI) to monitor sample data and issue commands with tab completion:
1515

16-
[linux]> tio-proxy -r /dev/ttyACM0
17-
[macOS]> tio-proxy -r /dev/cu.usbserialXXXXXX
18-
[wsl1] > tio-proxy -r COM3
16+
tio monitor
1917

20-
The proxy allows multiple tools to connect to the device over TCP simultaneously.
18+
Dump data to terminal:
2119

22-
### tio-tool
20+
tio dump --data --meta
2321

24-
Logging data:
25-
26-
tio-tool log
22+
Issue commands from terminal:
2723

28-
Issuing commands:
29-
30-
tio-tool rpc dev.name
24+
tio rpc {command name} [arg]
3125

32-
### tio-monitor
26+
Log data to csv:
3327

34-
Displays a live stream of incoming data with an optional color-coded threshold option.
35-
36-
Running the tool:
37-
38-
tio-monitor [yaml_path]
39-
40-
Yaml format to specify desired ranges:
41-
field_name: {min: 0.0, max: 10000.0}
42-
43-
### tio-health
44-
45-
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.
46-
47-
Running the tool:
48-
49-
tio-health
28+
tio log -f {file.tio} # blocking
29+
tio log csv {stream name} {file.tio}
5030

5131
## Installation
5232

@@ -56,4 +36,10 @@ With rust language tools, install the tools using:
5636

5737
It can be installed with the ability to convert to HDF5 using
5838

59-
cargo install twinleaf-tools --features hdf5
39+
cargo install twinleaf-tools --features hdf5
40+
41+
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.
42+
43+
The `serialport` library depends on `libudev` that is not included on certain linux distributions. To install it use:
44+
45+
sudo apt install libudev-dev # debian linux

‎twinleaf-tools/README.md‎

Lines changed: 44 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,84 @@
11
# Twinleaf I/O Tools in Rust
22

3-
This repository contains a set of tools that are useful for working with Twinleaf quantum sensors and accessories. The repository contains the twinleaf library and a set of command line tools: a proxy, a utility, and a data monitoring tool.
3+
Command-line tools for working with Twinleaf quantum sensors and accessories. Contains a proxy, terminal UIs, and command line utilities.
44

5+
**Note**: In versions <2.0.0, this crate contained binaries named `tio-proxy`, `tio-monitor`, `tio-health`, and `tio-tool`. These commands have been packaged into subcommands under the single binary `tio`. The former three original commands can be simply used without the `-`, while `tio-tool {toolname}` calls have largely been replaced with `tio {toolname}`.
56

6-
## Proxy
7+
## CLI Usage
8+
All the tools mentioned can have the `--help` argument added to display more information. 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.
79

8-
The proxy makes the device's serial port available via Ethernet, and supports multiple simultaneous client connections to a single device:
10+
### Connecting to the device
911

10-
tio-proxy --auto
12+
The proxy makes a device attached via serial port available via Ethernet. The following will automatically scan for a `twinleaf` serial device:
1113

12-
When there are more than one serial port available, it is necessary to specify the port
14+
tio proxy --auto
1315

14-
[linux] > tio-proxy -r /dev/ttyACM0
15-
[macOS] > tio-proxy -r /dev/cu.usbserialXXXXXX
16-
[windows]> tio-proxy.exe -r COM3
16+
When there are more than one serial port available, it is necessary to specify the port using:
1717

18-
When a sensor is attached to a hub at port `0`, it is possible to proxy the data directly to that port using the `-s` flag:
18+
[linux] tio proxy -r /dev/ttyACM0
19+
[macOS] tio proxy -r /dev/cu.usbserialXXXXXX
20+
[wsl1] tio proxy -r COM3
21+
22+
The proxy allows multiple tools to connect to the device over TCP simultaneously.
1923

20-
tio-proxy --auto -s /0
24+
When a sensor is attached to a hub at port `0`, it is possible to proxy the data directly to that port using the `-s` flag:
2125

22-
With the proxy running, a set of tools can be used on the data stream.
26+
tio proxy --auto -s /0
2327

24-
Log data to a raw binary file:
28+
### Interacting with the device in terminal
2529

26-
tio-tool log
30+
Logging metadata:
2731

28-
Parse that log data for stream id 1 to a `.csv` file. Assumes root route if unspecified.
32+
tio log meta # Write metadata to meta.tio
33+
tio log dump meta.tio # Parse meta.tio and print to terminal
2934

30-
tio-tool log-csv 1 logfile.tio
35+
Logging sample data:
3136

32-
Parse that log data to an HDF5 file (requires --features hdf5 on crate installation)
37+
# Log samples and write to log.{date-time}.tio until quit (Ctrl+C)
38+
tio log
3339

34-
tio-tool log-hdf logfile.tio -g "[device_route]/[stream_name]/[column_name]"
35-
tio-tool log-hdf logfile.tio -g "*/vector"
40+
# Parse a stream from .tio file and write to csv
41+
tio log csv {stream name/id} {file}
3642

37-
Issue commands:
43+
# Write to HDF5 file (requires `--features hdf5` on install)
44+
tio log hdf {file} -g "{route}/{stream}/{column}"
45+
tio log hdf {file} -g "*/{stream or column}"
3846

39-
tio-tool rpc dev.name
47+
Dump data to terminal:
4048

41-
List available commands:
49+
tio dump --data # Continuously print parsed samples
50+
tio dump --data --meta # Same as above, with metadata header
4251

43-
tio-tool rpc-list
52+
Device commands:
4453

45-
Firmware upgrade:
54+
tio rpc list # List of rpc commands with types
55+
tio rpc {command} [arg] # Issue command with optional argument
4656

47-
tio-tool firmware-upgrade <firmware.bin>
57+
## Terminal UIs
4858

49-
Monitoring the data stream:
59+
### tio monitor
5060

51-
tio-tool data-dump
61+
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 {port}` to specify which port to open or `tio monitor -a` to open all ports.
5262

53-
A TUI device data monitor:
63+
Run with:
5464

55-
tio-monitor
65+
tio monitor
5666

57-
A TUI device health monitor:
67+
### tio health
5868

59-
tio-health
69+
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.
6070

61-
And a variety of additional functions for use with Twinleaf sensors. Each tool can be called with the `--help` argument for more information.
71+
Run with:
6272

73+
tio health
6374

6475
## Installation
6576

6677
The tools can be installed using
6778

6879
cargo install twinleaf-tools
6980

70-
It can be installed with the ability to convert to HDF5 using
81+
They can be installed with the ability to convert to HDF5 using
7182

7283
cargo install twinleaf-tools --features hdf5
7384

@@ -77,7 +88,7 @@ The `serialport` library depends on `libudev` that is not included on certain li
7788

7889
sudo apt install libudev-dev # debian linux
7990

80-
## Cross compilation
91+
## Cross compilation
8192

8293
The tools can be compiled for other platforms by first adding those platform targets:
8394

@@ -87,4 +98,3 @@ The tools can be compiled for other platforms by first adding those platform tar
8798
And then building for the new target:
8899

89100
cargo build --target x86_64-pc-windows-gnu
90-

0 commit comments

Comments
 (0)