Merge pull request #18 from twinleaf/qol

feat(twinleaf-tools, twinleaf): QOL improvements for tio CLI and device workflows

Author: tkornack

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "twinleaf-tools"
-version = "2.1.0"
+version = "2.2.0"
 edition = "2021"
 license = "MIT"
 description = "Tools for the Twinleaf I/O protocol for reading data from Twinleaf quantum sensors."
@@ -16,13 +16,19 @@ hdf5 = ["twinleaf/hdf5"]
 crossbeam = "0.8"
 serialport = "4.5"
 toml_edit = {version = "0.25", features = ["parse"]}
-twinleaf = {version = "1.7", path = "../twinleaf" }
+twinleaf = {version = "1.8", path = "../twinleaf" }
 time = {version = "0.3", features = ["local-offset", "macros", "formatting"]}
 clap = { version = "4.5", features = ["derive"] }
 ratatui = "0.30"
 tui-prompts = "0.6"
 welch-sde = "0.1"
 memmap2 = "0.9"
 indicatif = "0.18"
+console = "0.16"
 chrono = "0.4"
 clap_complete = "4.5"
+eyre = "0.6"
+color-eyre = "0.6"
+termtree = "1"
+nucleo-matcher = "0.3"
+humantime = "2.2"

twinleaf-tools/Cargo.toml

@@ -2,28 +2,43 @@
 
 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 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}`.
+**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}`.
 
-## CLI Usage
-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.
+### 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 proxy makes a device attached via serial port available via Ethernet. The following will automatically scan for a `twinleaf` serial 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 --auto
+		tio proxy
 
-When there are more than one serial port available, it is necessary to specify the port using:
+When more than one serial port is available, specify the URL:
 
-		[linux] tio proxy -r /dev/ttyACM0
-		[macOS] tio proxy -r /dev/cu.usbserialXXXXXX
-		[wsl1]  tio proxy -r COM3
+		[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`, it is possible to proxy the data directly to that port using the `-s` flag:
+When a sensor is attached to a hub at port `0`, restrict the proxy's subtree using the `-s` flag:
 
-		tio proxy --auto -s /0
+		tio proxy -s /0
 
 ### Interacting with the device in terminal
 
@@ -58,7 +73,7 @@ Device commands:
 
 ### 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 {port}` to specify which port to open or `tio monitor -a` to open all ports.
+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:
 

twinleaf-tools/README.md

@@ -1,32 +1,39 @@
 use clap::{CommandFactory, Parser};
-use std::process::ExitCode;
 use twinleaf_tools::tools::{
-    tio_health::run_health,
-    tio_monitor::run_monitor,
-    tio_proxy::run_proxy,
-    tio_text_proxy::run_text_proxy,
-    tio_tool::{
-        data_dump_all_deprecated, data_dump_deprecated, dump, firmware_upgrade, list_rpcs, log,
-        log_csv, log_data_dump_deprecated, log_dump, log_hdf, log_metadata, meta_dump_deprecated,
-        meta_reroute, rpc, rpc_dump,
+    health::run_health,
+    list::list_devices,
+    monitor::run_monitor,
+    proxy::run_proxy,
+    proxy_nmea::run_nmea_proxy,
+    tool::{
+        dump, firmware_upgrade, list_rpcs, log, log_csv, log_dump, log_hdf, log_inspect,
+        log_metadata, meta_reroute, rpc, rpc_dump,
     },
 };
-use twinleaf_tools::{Commands, DumpSubcommands, LogSubcommands, RPCSubcommands, TioCli};
+use twinleaf_tools::{
+    Commands, LogSubcommands, MetaSubcommands, ProxySubcommands, RPCSubcommands, TioCli,
+};
 
-fn main() -> ExitCode {
+fn main() -> eyre::Result<()> {
+    color_eyre::config::HookBuilder::default()
+        .display_env_section(false)
+        .display_location_section(false)
+        .install()?;
     let cli = TioCli::parse();
 
-    //TODO: Work on exit code logic
-    let result = match cli.command {
-        Commands::Proxy(proxy_cli) => run_proxy(proxy_cli),
+    match cli.command {
+        Commands::List { all } => list_devices(all),
+        Commands::Proxy(mut proxy_cli) => match proxy_cli.subcommands.take() {
+            Some(ProxySubcommands::Nmea { tio, tcp_port }) => run_nmea_proxy(tio, tcp_port),
+            None => run_proxy(proxy_cli),
+        },
         Commands::Monitor {
             tio,
-            all,
             fps,
             colors,
-        } => run_monitor(tio, all, fps, colors),
+            depth,
+        } => run_monitor(tio, fps, colors, depth),
         Commands::Health(health_cli) => run_health(health_cli),
-        Commands::NmeaProxy { tio, tcp_port } => run_text_proxy(tio, tcp_port),
         Commands::Rpc {
             tio,
             subcommands,
@@ -35,90 +42,82 @@ fn main() -> ExitCode {
             req_type,
             rep_type,
             debug,
-        } => {
-            let _ = match subcommands {
-                Some(RPCSubcommands::List { tio }) => list_rpcs(&tio),
-                Some(RPCSubcommands::Dump {
-                    tio,
-                    rpc_name,
-                    capture,
-                }) => rpc_dump(&tio, rpc_name, capture),
-                None => rpc(
-                    &tio,
-                    rpc_name.unwrap_or("".to_string()),
-                    rpc_arg,
-                    req_type,
-                    rep_type,
-                    debug,
-                ),
-            };
-            Ok(())
-        }
+        } => match subcommands {
+            Some(RPCSubcommands::List { tio }) => list_rpcs(&tio),
+            Some(RPCSubcommands::Dump {
+                tio,
+                rpc_name,
+                capture,
+            }) => rpc_dump(&tio, rpc_name, capture),
+            None => rpc(
+                &tio,
+                rpc_name.unwrap_or("".to_string()),
+                rpc_arg,
+                req_type,
+                rep_type,
+                debug,
+            ),
+        },
         Commands::Dump {
             tio,
-            subcommands,
             data,
             meta,
             depth,
-        } => {
-            let _ = match subcommands {
-                Some(DumpSubcommands::Data { tio }) => data_dump_deprecated(&tio),
-                Some(DumpSubcommands::DataAll { tio }) => data_dump_all_deprecated(&tio),
-                Some(DumpSubcommands::Meta { tio }) => meta_dump_deprecated(&tio),
-                None => dump(&tio, data, meta, depth),
-            };
-            Ok(())
-        }
+        } => dump(&tio, data, meta, depth),
         Commands::Log {
             tio,
             subcommands,
             file,
             unbuffered,
             raw,
             depth,
-        } => {
-            let _ = match subcommands {
-                Some(LogSubcommands::Metadata { tio, file }) => log_metadata(&tio, file),
-                Some(LogSubcommands::Dump {
-                    files,
-                    data,
-                    meta,
-                    sensor,
-                    depth,
-                }) => log_dump(files, data, meta, sensor, depth),
-                Some(LogSubcommands::DataDump { files }) => log_data_dump_deprecated(files),
-                Some(LogSubcommands::Csv {
-                    args,
-                    sensor,
-                    output,
-                }) => log_csv(args, sensor, output),
-                Some(LogSubcommands::Hdf {
-                    files,
-                    output,
-                    filter,
-                    compress,
-                    debug,
-                    split_level,
-                    split_policy,
-                }) => log_hdf(
-                    files,
+            duration,
+        } => match subcommands {
+            Some(LogSubcommands::Meta {
+                tio,
+                subcommands,
+                file,
+            }) => match subcommands {
+                Some(MetaSubcommands::Reroute {
+                    input,
+                    route,
                     output,
-                    filter,
-                    compress,
-                    debug,
-                    split_level,
-                    split_policy,
-                ),
-                None => log(&tio, file, unbuffered, raw, depth),
-            };
-            Ok(())
-        }
-        Commands::MetaReroute {
-            input,
-            route,
-            output,
-        } => meta_reroute(input, route, output),
-        Commands::FirmwareUpgrade {
+                }) => meta_reroute(input, route, output),
+                None => log_metadata(&tio, file),
+            },
+            Some(LogSubcommands::Dump {
+                files,
+                data,
+                meta,
+                sensor,
+                depth,
+            }) => log_dump(files, data, meta, sensor, depth),
+            Some(LogSubcommands::Inspect { files }) => log_inspect(files),
+            Some(LogSubcommands::Csv {
+                args,
+                sensor,
+                output,
+            }) => log_csv(args, sensor, output),
+            Some(LogSubcommands::Hdf {
+                files,
+                output,
+                filter,
+                compress,
+                debug,
+                split_level,
+                split_policy,
+            }) => log_hdf(
+                files,
+                output,
+                filter,
+                compress,
+                debug,
+                split_level,
+                split_policy,
+            ),
+            None => log(&tio, file, unbuffered, raw, depth, duration),
+        },
+        Commands::Upgrade {
             tio,
             firmware_path,
             yes,
@@ -127,12 +126,5 @@ fn main() -> ExitCode {
             clap_complete::generate(shell, &mut TioCli::command(), "tio", &mut std::io::stdout());
             Ok(())
         }
-    };
-
-    if result.is_ok() {
-        ExitCode::SUCCESS
-    } else {
-        eprintln!("FAILED");
-        ExitCode::FAILURE
     }
 }

twinleaf-tools/src/bin/tio.rs

@@ -1,18 +1,34 @@
 use clap::Parser;
+use std::path::PathBuf;
 use std::time::Duration;
 use tio::proto::DeviceRoute;
 use tio::util;
 use twinleaf::tio;
 pub mod tools;
+pub mod tui;
 include!("tio_cli.rs");
 
+fn parse_device_route(s: &str) -> Result<DeviceRoute, String> {
+    DeviceRoute::from_str(s).map_err(|_| format!("invalid sensor route: {s:?}"))
+}
+
+fn parse_existing_file(s: &str) -> Result<PathBuf, String> {
+    let p = PathBuf::from(s);
+    match std::fs::metadata(&p) {
+        Ok(m) if m.is_file() => Ok(p),
+        Ok(_) => Err(format!("not a regular file: {s:?}")),
+        Err(e) => Err(format!("cannot read {s:?}: {e}")),
+    }
+}
+
 #[derive(Parser, Debug, Clone)]
 pub struct TioOpts {
     /// Sensor root address (e.g., tcp://localhost, serial:///dev/ttyUSB0)
     #[arg(
         short = 'r',
         long = "root",
         default_value_t = util::default_proxy_url().to_string(),
+        value_hint = clap::ValueHint::Url,
         help = "Sensor root address"
     )]
     pub root: String,
@@ -22,13 +38,8 @@ pub struct TioOpts {
         short = 's',
         long = "sensor",
         default_value = "/",
+        value_parser = parse_device_route,
         help = "Sensor path in the sensor tree"
     )]
-    pub route_path: String,
-}
-
-impl TioOpts {
-    pub fn parse_route(&self) -> DeviceRoute {
-        DeviceRoute::from_str(&self.route_path).unwrap_or_else(|_| DeviceRoute::root())
-    }
+    pub route: DeviceRoute,
 }