Skip to content

CLI Guide

kazunoko is a command-line tool for communicating with OSECHI cosmic ray detectors. This guide covers all available commands, options, and practical examples.

Quick Start

Installation

See Installation for setup instructions.

First Measurement

# Collect 10 events with threshold settings
kazunoko measure "1:300;2:360;3:330" 10

# Save to file
kazunoko measure "1:300;2:360;3:330" 1000 > detector_data.jsonl

Commands Overview

Information Commands

  • kazunoko version - Display kazunoko and device firmware versions
  • kazunoko status - Show device status (connection, uptime, temperature, etc.)

Data Collection Commands

  • kazunoko read - Read raw detection events
  • kazunoko measure - Measure events with threshold configuration

Configuration Commands

  • kazunoko threshold - Configure detector thresholds
  • kazunoko query - Send custom commands to device

Simulation Commands

  • kazunoko generate - Generate simulated detection events (testing)

Common Options

Most commands support these standard options:

Connection

--port PORT, -p PORT              Serial port or 'auto' for auto-detection (default: auto)
--timeout SECONDS, -t SECONDS     Serial communication timeout in seconds (default: 0.1)

Output & Display

--verbose, -v / --quiet, -q       Show verbose status messages or suppress them (default: quiet)
--format FORMAT, -f FORMAT        Output format: jsonl, table, json, csv, ssv, tsv, ltsv (default: jsonl)
--use-flat / --use-raw            Use flattened field names or raw structure (default: use-flat)
--mock                            Use mock device for testing (no hardware needed)

Event Collection (for read and measure)

--use-event / --use-sec           Read/collect by event count (default) or by duration in seconds

For example:

# Count-based (read N events)
kazunoko read 1000

# Duration-based (read for N seconds)
kazunoko read 60 --use-sec

Advanced Options

--event-timeout SECONDS, -et SECONDS
                                Event timeout in seconds to wait before moving to next
                                (default: 5.0 for measure, varies for other commands)
--poll-count COUNT, -pc COUNT     Device poll cycles per event read (range: 1-65535, default: 10)

Data Quality & Statistics

Kazunoko provides detailed statistics about data collection quality when using verbose mode.

Viewing Statistics

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

Output shows:

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

Understanding Statistics

  • Total events received - Successfully collected events
  • Skipped events - Events skipped due to errors
  • Success rate - Percentage of successful events out of total attempts
  • Timeout - Events timeout (threshold settings may be too high)
  • Protocol errors - Malformed JSON from device (communication glitch)
  • Response errors - Invalid response structure (device malfunction)

Graceful Error Handling

Malformed responses are automatically skipped and collection continues. This improves reliability in environments with temporary communication glitches.

Output Formats

All commands support multiple output formats via --format:

jsonl (default)

JSON Lines format (one JSON object per line) - best for data pipelines and scripting.

table

Human-readable table format with colored output.

json

Compact JSON on single line.

csv

Comma-separated values.

ssv / tsv / ltsv

Space/Tab/Label-separated variants.

Practical Examples

Check Detector Status

kazunoko status --verbose

Collect Events with Statistics

# See data quality statistics
kazunoko read 1000 --verbose --format jsonl > events.jsonl

Save Compressed Data

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

# Uncompress and process
zcat data.jsonl.gz | python analyze.py

Test with Simulated Data

# Generate 100 simulated events for testing
kazunoko generate 100 --speed 2.0 --jitter 0.1

Pipe to Analysis Script

# Stream events to Python for real-time analysis
kazunoko read 1000 --format jsonl | python real_time_analysis.py

Troubleshooting

No Response from Device

# Check connection with verbose output
kazunoko status -v

# Specify port explicitly
kazunoko status --port /dev/ttyUSB0

Timeout Errors

# Increase event timeout
kazunoko measure "1:300;2:360;3:330" 100 --event-timeout 5.0

# Increase serial communication timeout
kazunoko measure "1:300;2:360;3:330" 100 --timeout 1.0

Check Data Quality

# View statistics with verbose flag
kazunoko measure "1:300;2:360;3:330" 1000 --verbose

# High success rate means stable connection
# Low success rate may indicate device issues or wrong thresholds

Next Steps