`kazunoko read EVENTS_OR_SECS`¶

Read detection events from the OSECHI detector.

Unlike measure, this command does not configure thresholds — it uses whatever thresholds are currently set on the device.

Basic Usage¶

# Count-based (default): read exactly N events
kazunoko read 10

# Time-based: read for N seconds
kazunoko read 60 --use-sec

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 when events may be rare

If the threshold is set very high, few events are detected and count-based mode may hang. Use --use-sec to guarantee the command terminates.

CLI Options¶

Option	Short	Default	Description
`--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 read 1000 > data.jsonl

Time-based collection¶

kazunoko read 60 --use-sec > data.jsonl

Show statistics with `--verbose`¶

kazunoko read 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

Specify serial port¶

kazunoko read 1000 --port /dev/ttyUSB0 > data.jsonl

Increase per-event timeout¶

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

kazunoko read 100 --event-timeout 10.0

Compress output on the fly¶

kazunoko read 10000 | gzip > data.jsonl.gz

Test without hardware¶

kazunoko read 50 --mock

Set thresholds once, then read multiple times¶

kazunoko threshold "1:300;2:360;3:330"

kazunoko read 1000 > run1.jsonl
kazunoko read 1000 > run2.jsonl
kazunoko read 1000 > run3.jsonl

`read` vs `measure`¶

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

kazunoko measure — configure thresholds and collect events in one step
kazunoko threshold — set thresholds before reading
kazunoko status — check device status including current threshold values

kazunoko read EVENTS_OR_SECS¶