Skip to content

kazunoko measure THRESHOLDS EVENTS_OR_SECS

Configure thresholds and collect detection events in one step.

Basic Usage

# Count-based (default): collect exactly N events
kazunoko measure "1:300;2:360;3:330" 1000

# Time-based: collect for N seconds
kazunoko measure "1:300;2:360;3:330" 60 --use-sec

What This Command Does

measure combines threshold configuration and event collection:

  1. Sets detection thresholds on the specified channels
  2. Synchronizes the device RTC to the current time
  3. Collects device metadata (MAC address, firmware version, thresholds)
  4. Streams detection events with that metadata merged into every event

Every event is self-contained — no need to track configuration separately.

Threshold Format

CHANNEL:VALUE;CHANNEL:VALUE;...
  • CHANNEL: Channel number (1, 2, or 3)
  • VALUE: Threshold value in DAC units (integer)

If you specify only some channels, the device retains the previous values for the others. All three threshold values are always included in every output event.

See cli-threshold.md for background on thresholds.

Collection Modes

Mode Option Argument Description
Count-based --use-event (default) number of events Stops after exactly N events
Time-based --use-sec duration in seconds Stops after N seconds

In count-based mode, each event waits up to --event-timeout seconds (default: 5.0). If no event arrives within the timeout, that attempt is skipped and the next is tried.

Use --use-sec for threshold scanning

If the threshold is set very high, few events are detected and count-based mode may hang. Always use --use-sec when scanning across threshold values.

CLI Options

Option Short Default Description
--poll-count -pc 10 Poll cycles per event read (range: 1–65535)
--port -p auto Serial port, or auto for auto-detection
--timeout -t 0.1 Serial communication timeout in seconds
--event-timeout -et 5.0 Per-event timeout in seconds
--verbose / --quiet -v / -q --quiet Show or suppress status messages
--format -f jsonl Output format: jsonl, table, json, csv, ssv, tsv, ltsv
--use-flat / --use-raw --use-flat Use flattened or raw field names
--use-event / --use-sec --use-event Count-based or time-based collection
--mock off Use mock device (no hardware needed)

Usage Examples

Save to a file

kazunoko measure "1:300;2:360;3:330" 1000 > data.jsonl

Time-based collection

kazunoko measure "1:300;2:360;3:330" 60 --use-sec > data.jsonl

Show statistics with --verbose

kazunoko measure "1:300;2:360;3:330" 1000 --verbose

At the end of the measurement, statistics are printed:

✓ Total events received: 998
⚠ Skipped events: 2 (99.8% success)
  - Timeout: 2
  - Protocol errors: 0
  - Response errors: 0

Threshold scanning

Collect fixed-duration measurements at each threshold value:

kazunoko measure "1:300;2:1000;3:1000" 10 --use-sec > threshold_300.jsonl
kazunoko measure "1:310;2:1000;3:1000" 10 --use-sec > threshold_310.jsonl
kazunoko measure "1:320;2:1000;3:1000" 10 --use-sec > threshold_320.jsonl

Specify serial port

kazunoko measure "1:300;2:360;3:330" 1000 --port /dev/ttyUSB0 > data.jsonl

Increase per-event timeout

Use -et when thresholds are high and events are rare:

kazunoko measure "1:300;2:360;3:330" 100 --event-timeout 10.0

Compress output on the fly

kazunoko measure "1:300;2:360;3:330" 10000 | gzip > data.jsonl.gz

Test without hardware

kazunoko measure "1:300;2:360;3:330" 50 --mock

measure vs read

measure read
Sets thresholds Yes No
Merges device metadata Yes No
Use case Single self-contained measurement Multiple runs with one setup