Skip to content

v0.26.0 - monitor_events.py TUI Improvements (2026-06-26)

What Changed?

This release improves the monitor_events.py example script with a redesigned TUI layout, new GNSS display, detector efficiency calculation, and error tracking. All changes are confined to the example script and technical notes; the library API is unchanged.

What's New

Redesigned TUI Layout

The monitor now uses a four-panel vertical layout:

┌─────────────────────────────────────┐
│ Summary (file / elapsed / events)   │
├──────────┬──────────┬───────────────┤
│ Hit      │ BME280   │ GNSS          │
├──────────┴──────────┴───────────────┤
│ Hit Types        │ Efficiency       │
├─────────────────────────────────────┤
│ Event Stream (last 10 lines)        │
└─────────────────────────────────────┘
  • SummaryPanel: file, elapsed time, total events, errors, detected timestamp, uptime
  • DetectorPanel: Hit pattern | BME280 | GNSS in three columns
  • DetailPanel: Hit type counts | Detector efficiency side by side
  • EventStreamPanel: last 10 JSONL lines with separators between events

GNSS Display

GNSS fields are now shown in the detector panel: fix status, satellite count, HDOP, latitude, longitude, and altitude.

Detector Efficiency

The Detail panel shows four efficiency values derived from hit_type counts:

  • η(T) = TMB / (TMB + MB) — top panel efficiency given mid & bottom
  • η(M) = TMB / (TMB + TB) — mid panel efficiency given top & bottom
  • η(B) = TMB / (TMB + TM) — bottom panel efficiency given top & mid
  • TMB% = TMB / all events — triple-coincidence fraction

Error Tracking

The Summary panel now tracks and displays two error types:

  • status_error: events where the device returned status: "error"
  • json_decode: JSON parse failures during file reading

Installation

Quick Start

# Get the release
git checkout v0.26.0

# Setup
uv sync

# Run CLI
uv run kazunoko --help

# Run monitor
uv run examples/monitor_events.py /path/to/data/directory

What's Different from the Last Version?

✅ Added

  • GNSS data display in DetectorPanel (fix status, satellites, HDOP, lat/lon/alt)
  • Detector efficiency calculation in DetailPanel (η(T), η(M), η(B), TMB%)
  • Error tracking in SummaryPanel (status_error, json_decode counts)
  • Event separators in EventStreamPanel using Rich Rule
  • TN-007 technical note: output filename convention with multi-session and run number details

🔧 Changed

  • TUI layout reorganized into SummaryPanel / DetectorPanel / DetailPanel / EventStreamPanel
  • Detected timestamp and Uptime moved from DetectorPanel border title to SummaryPanel
  • All panel borders unified to mediumpurple
  • Panel classes renamed: SummaryPanel, DetectorPanel, DetailPanel, EventStreamPanel

🐛 Fixed

  • Column width not applied on startup (Textual CSS > Static selector does not match subclasses)

Is It Safe to Upgrade?

Backward Compatible: Yes

  • No changes to the library API (kazunoko package)
  • monitor_events.py is an example script; no downstream code depends on it

Tests Passed

  • ✅ Builds without errors
  • ✅ uv run pytest passes (12 tests)
  • ✅ uvx ruff check src/ passes

Release Details

  • Date: 2026-06-26
  • Version: v0.26.0
  • Files Changed: examples/monitor_events.py, docs/technotes/