netft-cli

netft-cli is a cross-platform command-line application for commissioning, diagnosing, monitoring, recording, and biasing ATI Net F/T Ethernet sensors. It discovers the active calibration and native units before consuming the RDT force/torque stream.

Features

• Inspect sensor identity, calibration, and measurement units.
• Check stream continuity, packet loss, rate, reconnects, and device status.
• Monitor the latest six-axis sample in a live table or structured stream.
• Record every accepted sample to CSV or NDJSON with integrity safeguards.
• Apply software bias through an explicit confirmation step.

Installation

Install method	Platform	Support
GitHub Releases or installer	Linux x86-64/ARM64, macOS Intel/Apple silicon, Windows x86-64	Self-contained executable
Source	Linux, macOS, Windows	CMake 3.16+, C++17, Threads, libcurl 7.63+

On Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/netft/netft-cli/main/scripts/install/install.sh | sh

On Windows PowerShell:

irm https://raw.githubusercontent.com/netft/netft-cli/main/scripts/install/install.ps1 | iex

The installers select and verify the latest stable release. Release binaries include the private netft-cpp core and libcurl, so no separate runtime is required.

Quick start

The examples use 192.168.1.1, the ATI factory-default sensor address. Replace it with the address configured for your sensor.

# Inspect identity, calibration, and units.
netft info 192.168.1.1

# Run a bounded health check.
netft check 192.168.1.1 --duration 10s

# Monitor the latest sample in a live table.
netft monitor 192.168.1.1

# Record every accepted sample for one minute.
netft record 192.168.1.1 --output measurement.csv --duration 60s

Run netft help <COMMAND> or netft <COMMAND> --help for the options supported by the installed version.

Documentation

• Inspect and validate a sensor
• Monitor live data
• Record a capture
• Command reference
• Data formats
• Security and safety

monitor presents the latest sample without maintaining a backlog. Use record when every accepted sample must be preserved. Bias changes the measurement zero; perform it only when the sensor and connected equipment are in a safe state.

Contributing

See CONTRIBUTING.md for development setup, tests, hardware-safety requirements, and core synchronization. Report security issues through SECURITY.md.

License

This project is licensed under the Apache License 2.0. Release archives include the notices for the synchronized netft-cpp core and libcurl.

Recording integrity (0.3.0)

record never replaces existing destination or partial paths, including dangling links. The first sample and subsequent accepted samples must arrive within --timeout. A zero-sample session, terminal fault, queue overflow, writer failure or data timeout returns recording error 8 and retains .partial; inspect partial data before using it. Recoverable interruptions can resume within the timeout. --count can wait for the selected sample count while data keeps arriving; combine it with --duration for a total time limit. Ctrl-C drains nonempty recordings, finalizes them and returns 130. Publication protects file names but does not promise power-loss durability.

Recording metadata (0.3.0)

CLI 0.3.0 and later write <output>.metadata.json after successful data finalization, using schema version 1 and kind netft-recording. Viewer 0.2.1 and later use the same schema and these shared meanings:

Field	Meaning
producer, result	netft-cli or netft-viewer; complete or CLI interrupted after a successful nonempty drain.
accepted_samples, written_samples	Samples accepted into the recording queue and rows successfully written. These are not power-loss durability guarantees.
sample_span_seconds	Nonnegative host receive-time span between first and last written sample; zero for fewer than two samples.
configuration_revisions	Unique revision identifiers in written rows, scoped to the producer session. They do not contain full calibration snapshots.
force_units, torque_units	Unique native unit symbols observed in written rows.
recorded_rdt_gaps	Sum of forward sequence gaps between written rows, using unsigned wraparound and ignoring backward jumps. Pauses, rate filtering and reconnects can contribute; this is not the SDK packet-loss counter.
pause_count	Accepted Viewer pauses; CLI has no pause operation and reports zero.
reconnect_count	CLI SDK reconnect counter for the run; null for Viewer because its recorder does not own connection health.
error	null on successful finalization. Failure details remain in the CLI error or Viewer recorder state.

Partial or failed captures do not receive a completed summary. Metadata creation and promotion follow the data file's overwrite policy. The two files are finalized separately: a metadata failure reports an error and preserves the completed data file, and may leave a metadata partial for recovery. Keep both files when archiving a successful capture.

CLI 0.3.0 and later append configuration_revision to CSV without moving existing columns and add it inside the NDJSON sample object. Viewer records revisions in each CSV row. Older releases retain their documented formats.

Machine interface (0.3.0)

netft --schema prints schema-version-1 JSON without opening a sensor connection. Commands refer to option identifiers, typed positionals and exit statuses from the same command definitions used by parsing and help. version, sourceCommit and sourceDirty identify the configured build. Archives with no Git metadata report unknown provenance; documentation generation requires a clean checkout and matching executable. Consumers must reject unsupported schema versions and should tolerate additive fields.