Skip to content

kazunoko

kazunoko is a lightweight Python library for serial communication with the OSECHI cosmic ray detector. It provides both a Python API and a CLI tool for sending commands to the detector and parsing JSONL-formatted responses.

Current version: 0.20.0

Features

  • Simple serial communication interface
  • JSONL response parsing with Pydantic
  • Both Python API and CLI tool
  • Type-safe Command API with IDE completion
  • Multiple output formats: jsonl, table, json, csv, tsv, ltsv, ssv
  • Mock device for testing without hardware
  • Streaming statistics and error handling
  • Comprehensive diagnostics via kazunoko status

Installation

Install from GitLab:

uv pip install "osechi-kazunoko @ git+https://gitlab.com/osechi/kazunoko.git"

See Installation for full details.

Quick Start

CLI

# Display diagnostic information
kazunoko status

# Set detector thresholds
kazunoko threshold "1:300;2:330;3:310"

# Read 10 detection events
kazunoko read 10

# Read for 30 seconds
kazunoko read 30 --use-sec

# Collect events and save to file
kazunoko measure "1:300;2:330;3:310" 100 > events.jsonl

Cosmic Ray Measurement

Collect events continuously and monitor them in real time:

# Collect events with auto-generated filenames (port is auto-detected)
uv run examples/get_events.py

# Monitor incoming events in a live TUI
uv run examples/monitor_events.py ./20260320/

See get_events.py and monitor_events.py for details.

Threshold Measurement

Scan threshold values, fit the detector response, and visualize the results:

# Scan each channel: center=300, 50 steps, step size 1, 10 seconds per threshold
uv run examples/get_thresholds.py "1:300;2:300;3:300" 10 1 --use-sec --nsteps 50 --step-size 1

# Monitor the scan in real time
uv run examples/monitor_thresholds.py ./20260320/ --xmin 250 --xmax 350 --ymax 130

# Fit the scan results to an erfc curve
uv run examples/fit_thresholds.py ./20260320/ --use-summary

# Plot the detector response curves
uv run examples/plot_thresholds.py ./20260320/ --save

See get_thresholds.py, fit_thresholds.py, and plot_thresholds.py for details.

Documentation