CSV schemas

CLI monitor

host,schema_version,elapsed_seconds,rdt_sequence,ft_sequence,status,
raw_fx,raw_fy,raw_fz,raw_tx,raw_ty,raw_tz,
fx,fy,fz,tx,ty,tz,force_unit,torque_unit,receive_rate_hz,
lost_count,duplicate_count,out_of_order_count,state

Monitor CSV is observation output. Its bounded presentation rate can be lower than the native receive rate.

CLI recording

schema_version,timestamp_utc,elapsed_seconds,rdt_sequence,ft_sequence,status,
raw_fx,raw_fy,raw_fz,raw_tx,raw_ty,raw_tz,
fx,fy,fz,tx,ty,tz,force_unit,torque_unit

timestamp_utc is for cross-system correlation. elapsed_seconds is the monotonic capture timeline and should be used for interval analysis.

Viewer recording

host_receive_timestamp_ns,elapsed_recording_time_ns,
rdt_sequence,ft_sequence,status,configuration_revision,
raw_fx,raw_fy,raw_fz,raw_tx,raw_ty,raw_tz,
force_x,force_y,force_z,torque_x,torque_y,torque_z,
force_unit,torque_unit

host_receive_timestamp_ns uses the system clock. elapsed_recording_time_ns is monotonic from recording start. Configuration revision and unit columns keep calibration changes visible across reconnects.

CLI and Viewer recorders write a temporary .partial file and promote it only after a clean queue drain and flush. A partial file is not proof of a complete capture.

Recording metadata (unreleased candidate)

After successful data finalization, the candidate writes <output>.metadata.json using schema version 1 and kind netft-recording. CLI and Viewer share these 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.

The CLI candidate appends configuration_revision to CSV without moving existing columns and adds it inside the NDJSON sample object. Viewer already records revisions in each CSV row. Existing published releases retain their documented formats until these changes are released.