Skip to content

v0.1.39 - Threshold Measurement Command (2025-12-13)

What Changed?

This release introduces the measure command, a new CLI feature that combines threshold configuration with event measurement. Each detection event now includes the threshold settings used during collection, enabling systematic detector sensitivity characterization. The event reading logic has been refactored for better code reuse between read and measure commands.

What's New

Main Feature: measure Command

What it does: The measure command sets specific detection thresholds and collects events with metadata. Each event includes threshold values for all three detector channels, making it ideal for sensitivity studies and threshold scanning workflows.

How to use it: 

# Basic usage: measure at thresholds 300 ADC on all channels, collect 10 events
uv run kazunoko measure "1:300;2:300;3:300" 10

# With poll count configuration: set to 50000 polls per cycle
uv run kazunoko measure "1:300;2:300;3:300" 10 --poll-count 50000

# With timeout and verbose output
uv run kazunoko measure "1:300;2:300;3:300" 10 --event-timeout 3.0 -v

# Different format output
uv run kazunoko measure "1:300;2:300;3:300" 10 --format json | jq '.threshold1'

Code example:

# Scan sensitivity across threshold values (using shell loop)
for threshold in 100 200 300 400 500; do
  echo "Measuring at ${threshold} ADC..."
  uv run kazunoko measure "1:${threshold};2:${threshold};3:${threshold}" 5 >> scan_results.jsonl
done

Installation

Quick Start

# Get the release
git checkout v0.1.39

# Setup
uv sync

# Run CLI
uv run kazunoko --help

What's Different from the Last Version?

✅ Added

  • New measure command for threshold-based event collection with metadata
  • --poll-count option with validation (range: 1-65535, default: 50000)
  • Optional metadata parameter to _read_one_event() for flexible response merging
  • Metadata support in _read_events() for passing threshold info to event reading

🔧 Changed

  • Refactored _read_one_event() to return tuple (success_count, response_object) instead of int
  • Extended _read_one_event() and _read_events() to support optional metadata merging
  • Improved event response handling with Pydantic model_validate() for safe metadata merging

🐛 Fixed

  • Better separation of concerns between event reading and event display logic

Is It Safe to Upgrade?

Backward Compatible: Yes

  • Existing read command behavior unchanged
  • New measure command is additive, no impact on existing functionality
  • _read_one_event() return type changed but it's an internal function

Tests Passed

  • ✅ Builds without errors
  • ✅ measure command accepts valid threshold formats
  • ✅ --poll-count validates range 1-65535
  • ✅ Events include threshold1, threshold2, threshold3 metadata
  • ✅ Multiple output formats work with measure command (jsonl, json, table, csv)
  • ✅ Mock device integration tested

Release Details

  • Date: 2025-12-13
  • Version: v0.1.39
  • Files Changed: 2
  • Commits: c45ffba, a2e0731

Next Steps

Future enhancements could include: - Integration with threshold_scan.sh for automated sensitivity characterization - Per-channel threshold scanning in the measure command - Event statistics aggregation during measurement - Real-time sensitivity curve plotting