Skip to content

v0.20.0 - Real-time TUI Monitor Scripts (2026-03-20)

What Changed?

This release adds two real-time TUI monitor scripts for the OSECHI detector. monitor_events.py replaces the previous monitor.py with a cleaner interface, and monitor_thresholds.py is a new script for monitoring threshold scan results. Both scripts now use the standard read_from positional argument convention.

What's New

Main Feature: Real-time TUI Monitor Scripts

What it does: Two Textual-based TUI scripts for monitoring OSECHI detector data in real-time:

  • monitor_events.py: Watches a directory for new event files and displays event counts, detector hit patterns, and BME280 sensor data
  • monitor_thresholds.py: Watches a directory for threshold scan results and displays scatter plots (threshold vs hit count) for each channel

How to use it:

# Monitor detector events
uv run monitor_events.py ./20260320/

# Monitor with custom file pattern
uv run monitor_events.py ./20260320/ --pattern "run_*.jsonl"

# Test without hardware (generate then monitor)
uv run kazunoko generate random > ./20260320/events.jsonl
uv run monitor_events.py ./20260320/ --pattern "events.jsonl"

# Monitor threshold scan results
uv run monitor_thresholds.py ./20260320/
uv run monitor_thresholds.py ./20260320/ --xmin 280 --xmax 320 --ymax 100

Installation

Quick Start

# Get the release
git checkout v0.20.0

# Setup
task env:setup

# Run CLI
uv run kazunoko --help

What's Different from the Last Version?

✅ Added

  • monitor_thresholds.py: new real-time TUI monitor for threshold scan results with scatter plots per channel
  • monitor_events.py: replaces monitor.py with cleaner file-watch-only interface
  • Usage examples for kazunoko generate random and pre-recorded event replay in monitor_events.py

🔧 Changed

  • monitor.py renamed to monitor_events.py for consistency with monitor_thresholds.py
  • Both monitor scripts now use read_from positional argument (aligned with other example scripts)
  • Stdin/pipe mode removed from monitor_events.py to simplify the interface

🐛 Fixed

  • Typo in usage docs: monitor_threshold.py → monitor_thresholds.py
  • Stale monitor.py references updated to monitor_events.py

Is It Safe to Upgrade?

Backward Compatible: No

  • monitor.py has been renamed to monitor_events.py — update any scripts or aliases that call monitor.py
  • --watch option replaced by positional read_from argument — update existing command lines
  • Stdin/pipe mode (kazunoko read 100 | uv run monitor_events.py) is no longer supported

Tests Passed

  • ✅ Builds without errors
  • ✅ commitizen pre-commit hook passed

Release Details

  • Date: 2026-03-20
  • Version: v0.20.0
  • Commits: 8439eb9, 3b8ad33, 48760a9, 45a4249, 33b7550, d207904

Next Steps

  • Add docs pages for monitor_events.py and monitor_thresholds.py in the examples guide