Skip to content

v0.1.0 - Initial Release with Serial Communication & CLI (2025-12-01)

What Changed?

This is the initial release of kazunoko, a lightweight Python library for serial communication with the OSECHI cosmic ray detector. It provides a complete Python API and CLI tool for sending text commands to the detector and parsing JSONL-formatted responses. The listen command now outputs pure JSONL and gracefully handles malformed JSON.

What's New

Main Feature: Serial Device Communication & CLI Interface

What it does: Provides a Python library and command-line tool to communicate with OSECHI cosmic ray detectors over serial connections. The library handles device initialization, command transmission, and JSONL response parsing with a flexible response model that adapts to varying device firmware responses.

How to use it: 

# Send a command and get response
kazunoko send "STATUS"

# Listen for detection events
kazunoko listen

# Display device status
kazunoko info

Code example(if relevant):

from kazunoko import connect

# Connect to device
device = connect(port="/dev/ttyUSB0")

# Send command
device.send_command("STATUS")

# Parse response
response = device.receive_response()
print(response.type, response.status)

Installation

Quick Start

# Install the library
uv pip install kazunoko

# Or install from source
git checkout v0.1.0
uv sync

What's Different from the Last Version?

✅ Added

  • Device class for serial communication with OSECHI detector
  • Configuration constants for serial connection (port, baudrate, timeout)
  • Custom exception hierarchy (KazunokoError, DeviceError, CommandError, ResponseError, TimeoutError)
  • JSONL protocol parsing with Pydantic Response model
  • CLI commands: send, listen, info for device interaction
  • Pure JSONL output from listen command
  • Graceful handling of malformed JSON in listen command
  • Public API module with clean exports

🔧 Changed

  • Listen command continues listening when JSON validation fails (instead of stopping)

🐛 Fixed

  • Catch ResponseError instead of ProtocolError in listen command
  • Make listen command expect data type responses
  • Remove invalid err parameter from Rich console output

Is It Safe to Upgrade?

Backward Compatible: Yes

  • This is the initial release, so there are no breaking changes from previous versions
  • The library is ready for production use with OSECHI detectors
  • Serial port configuration is flexible and can be customized per connection

Tests Passed

  • ✅ Builds without errors
  • ✅ Serial communication with device
  • ✅ JSONL parsing and validation
  • ✅ CLI commands execute correctly
  • ✅ Graceful error handling for malformed JSON

Release Details

  • Date: 2025-12-01
  • Version: v0.1.0
  • Files Changed: 8
  • Commits: Initial release

Next Steps

Planned improvements for future releases: - Add async support for non-blocking communication - Implement retry logic for unreliable connections - Add data logging and export capabilities - Expand CLI with additional analysis commands