Skip to content

First Measurement

Learn how to collect your first data with the OSECHI detector.

Prerequisites

  • kazunoko is installed (see Installation)
  • OSECHI detector is connected to your computer via USB cable
  • A terminal is available on your computer

Terminal and Shell

A terminal is a window where you type commands and see results. Common combinations by OS:

  • Linux: GNOME Terminal + bash (or zsh or fish)
  • macOS: Terminal.app + zsh
  • Windows: Windows Terminal + PowerShell
  • WSL2: Windows Terminal + Linux bash

PowerShell users

This documentation assumes UNIX-style commands. Command names may differ in PowerShell — please look up the equivalent commands for your environment.

1. Start a measurement

Use the kazunoko measure command to start collecting events. The command requires a threshold configuration and an event count:

kazunoko measure [THRESHOLDS] [EVENTS]

Thresholds are specified as channel:value;channel:value;... for all three channels simultaneously.

Let's collect 10 events as a quick test:

kazunoko measure "1:300;2:360;3:330" 10

Each event is printed to the terminal as a single JSON line:

$ uv run kazunoko measure "1:300;2:360;3:330" 10
{"type": "event", "status": "ok", "received_us": 1765586456.560016, "sent_us": 1765586455777801, "hit1": 0, "hit2": 1, "hit3": 0, "adc": 0, "hit_type": 2, "adc_raw": 1152, "adc_mv": 1064, "tmp_c": 0, "atm_pa": 0, "hmd_pct": 0, "uptime_ms": 1431078, "timedelta_us": 3290980, "detected_us": 1765586455777486, ...}
{"type": "event", "status": "ok", "received_us": 1765586456.648044, "sent_us": 1765586455865921, "hit1": 2, "hit2": 2, "hit3": 0, "adc": 1422, "hit_type": 3, ...}
...

Stop a measurement with Ctrl+C

Press Ctrl + C at any time to interrupt a measurement.

After 10 events the measurement stops automatically. Check that the output looks reasonable before moving on.

Why start small

Even a short test run can reveal problems like missing columns, constant values, or unexpectedly high event rates.

2. Save measurement results to a file

Redirect (>) the command output to save events to a file.

Let's collect 1000 events and save them:

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

Redirect operators

Redirects change where command output goes. By default it goes to the terminal (stdout).

  • > filename — overwrite file
  • >> filename — append to file

Stop a measurement with Ctrl+C

Press Ctrl + C to interrupt a running measurement.

3. Watch the file while measuring

When you redirect output to a file, nothing is printed to the terminal. Open a second terminal tab and run tail -f to watch the file as it grows:

tail -f osechi_data.jsonl

# PowerShell equivalent
Get-Content osechi_data.jsonl -Wait

tail -f

tail prints the end of a file. The -f flag keeps it running and shows new lines as they are appended.

Stop watching with Ctrl+C

Press Ctrl + C to stop tail -f. Make sure you stop the right terminal tab — not the one running the measurement.

4. Verify the results

After saving, do a quick sanity check on the data.

Check file size (ls -lh)

ls -lh osechi_data.jsonl

The file should be at least a few KB. A size of 0 bytes (or suspiciously small) indicates something went wrong.

Count events (wc -l)

wc -l osechi_data.jsonl

Each line is one event. The count should be close to the number you requested.

Inspect the first event (head -1)

head -1 osechi_data.jsonl

Pretty-print the JSON

head -1 osechi_data.jsonl | python3 -m json.tool

What to check

  • type is "event" (not "response" or "data")
  • status is "ok"
  • hit1, hit2, hit3 fields are present
  • threshold1, threshold2, threshold3 match your configured values
  • received_us and detected_us timestamps are present

If all checks pass, the measurement was successful!

Searching and filtering data

Many tools can search and filter JSON data. jq is great for JSON, xan works well for CSV. Install whichever fits your workflow.

5. Compress the output

For large datasets, compress the output on the fly to save disk space:

Compression commands

Common options: gzip, bzip2, zstd. gzip is the most widely supported. Use zstd if you need faster or higher compression.

kazunoko measure "1:300;2:310;3:330" 1000 | gzip > events.jsonl.gz

Save both compressed and uncompressed

kazunoko measure "1:300;2:310;3:330" 1000 | tee events.jsonl | gzip > events.jsonl.gz

tee splits the stream so both files are written simultaneously.

6. Available options

Verbose output (--verbose)

kazunoko measure "1:300;2:360;3:330" 100 -v

Shows connection status and command details. At the end of a measurement, statistics are printed:

✓ Total events received: 98
⚠ Skipped events: 2 (98.0% success)
  - Timeout: 1
  - Protocol errors: 0
  - Response errors: 1

Useful for diagnosing:

  • Timeout: event not received within timeout (threshold may be too high)
  • Protocol errors: incomplete JSON response (transient communication issue)
  • Response errors: JSON validation failure (unexpected device response)

All skipped events are handled automatically — measurement continues.

Specify serial port (--port)

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

Use -p when multiple serial devices are connected.

Adjust event timeout (--event-timeout)

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

Use -et to increase the wait time per event. Helpful when thresholds are set high and events are rare.

Adjust poll count (--poll-count)

kazunoko measure "1:300;2:360;3:330" 100 --poll-count 50000

Use -pc to adjust the number of device polling cycles.

Adjust serial timeout (--timeout)

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

Use -t to extend the serial communication timeout (default: 0.1s). Increase if the connection is slow or unstable.

7. Quick data check

# Inspect first event as formatted JSON
head -1 osechi_data.jsonl | python3 -m json.tool

# Count events
wc -l osechi_data.jsonl

# Check file size
du -h osechi_data.jsonl

Next Steps

Collect events to a file automatically

get_events.py provides a convenient wrapper around kazunoko measure with auto-generated filenames and a progress bar.

Collect multiple runs

get_runs.py splits a long measurement session into multiple files automatically, reusing a single device setup for efficiency.

Monitor events in real time

monitor_events.py provides a live TUI that watches a directory for new event files and displays hit patterns and statistics as data arrives.

Analyze the data

See First Data Analysis for how to process saved event files.

More advanced measurements

For threshold scanning and long-term measurements, see the API Guide and Tutorials.

References