Check Status¶

The status command queries the detector for its current operational state and configuration. This provides a comprehensive snapshot of system health, hardware features, and detection settings.

Purpose of Status Check¶

The status response contains key information about:

System Health: Firmware version, uptime, connection status
Detection Settings: Poll count, deadtime, threshold values for each channel
Hardware Features: Available sensors (BME280, GNSS), RTC, WiFi, queue system
ADC Configuration: Active channel selection

This information is useful for:

Verifying detector is responding correctly before starting measurements
Confirming threshold values are set as intended
Monitoring system uptime and stability
Checking available hardware features

Basic Status Check¶

$ uv run kazunoko status
{"type": "response", "status": "ok", "received_us": 1765550619.910123, "sent_us": 1765550618984433, "version": "1.17.0", "build_type": "dev-next", "mac_address": "30:AE:A4:9D:08:2C", "poll_count": 65535, "deadtime_ms": 0, "stream_enabled": true, "uptime_ms": 670449, "thresholds_ch1": 250, "thresholds_ch2": 1000, "thresholds_ch3": 1000, "bme280_tmp_c": 0, "bme280_atm_pa": 0, "bme280_hmd_pct": 0, "gnss_latitude": 0, "gnss_longitude": 0, "gnss_altitude": 0, "gnss_gnss_time": 0, "gnss_satellites": 0, "gnss_quality": 0, "gnss_valid": false, "gnss_hdop": 0}

Periodic Monitoring¶

The status command has no side effects—it only queries the detector state. You can run it repeatedly to monitor the detector over time.

Recommended Timing:

Before data collection: Verify thresholds and settings are correct
At regular intervals during acquisition: Monitor system health and uptime
After changing settings: Confirm changes were applied (e.g., after threshold command)
Periodically during long-term DAQ: Watch for issues or configuration drift

Log Status to File¶

One common pattern is to periodically save status snapshots during data acquisition to track system behavior:

# Initial status snapshot
uv run kazunoko status >> status.jsonl

# Continue measuring events...
uv run kazunoko read --count 1000 >> events.jsonl

# Check status again
uv run kazunoko status >> status.jsonl

# Later, check status once more
uv run kazunoko status >> status.jsonl

Resulting status.jsonl:

{"type": "response", "status": "ok", "received_us": 1765550705.907118, "sent_us": 1765550704980425, "version": "1.17.0", "build_type": "dev-next", "mac_address": "30:AE:A4:9D:08:2C", "poll_count": 65535, "deadtime_ms": 0, "stream_enabled": true, "uptime_ms": 756445, "thresholds_ch1": 250, "thresholds_ch2": 1000, "thresholds_ch3": 1000, "bme280_tmp_c": 0, "bme280_atm_pa": 0, "bme280_hmd_pct": 0, "gnss_latitude": 0, "gnss_longitude": 0, "gnss_altitude": 0, "gnss_gnss_time": 0, "gnss_satellites": 0, "gnss_quality": 0, "gnss_valid": false, "gnss_hdop": 0}
{"type": "response", "status": "ok", "received_us": 1765550713.243175, "sent_us": 1765550712316429, "version": "1.17.0", "build_type": "dev-next", "mac_address": "30:AE:A4:9D:08:2C", "poll_count": 65535, "deadtime_ms": 0, "stream_enabled": true, "uptime_ms": 763781, "thresholds_ch1": 250, "thresholds_ch2": 1000, "thresholds_ch3": 1000, "bme280_tmp_c": 0, "bme280_atm_pa": 0, "bme280_hmd_pct": 0, "gnss_latitude": 0, "gnss_longitude": 0, "gnss_altitude": 0, "gnss_gnss_time": 0, "gnss_satellites": 0, "gnss_quality": 0, "gnss_valid": false, "gnss_hdop": 0}
{"type": "response", "status": "ok", "received_us": 1765550718.755426, "sent_us": 1765550717828425, "version": "1.17.0", "build_type": "dev-next", "mac_address": "30:AE:A4:9D:08:2C", "poll_count": 65535, "deadtime_ms": 0, "stream_enabled": true, "uptime_ms": 769293, "thresholds_ch1": 250, "thresholds_ch2": 1000, "thresholds_ch3": 1000, "bme280_tmp_c": 0, "bme280_atm_pa": 0, "bme280_hmd_pct": 0, "gnss_latitude": 0, "gnss_longitude": 0, "gnss_altitude": 0, "gnss_gnss_time": 0, "gnss_satellites": 0, "gnss_quality": 0, "gnss_valid": false, "gnss_hdop": 0}

Use Case: File Switching¶

A practical workflow when changing measurement files is to record status snapshots before and after each measurement to a single status log file.

Shell Script Example¶

#!/bin/bash
# measure_multiple_files.sh - Acquire data with status logging

for file_num in 1 2 3; do
    echo "=== Starting measurement $file_num ==="

    # Record status snapshot at start of measurement
    uv run kazunoko status >> status.jsonl

    # Acquire events into separate file
    echo "Recording 5000 events..."
    uv run kazunoko read 5000 >> "events_$file_num.jsonl"

    # Record status snapshot at end of measurement
    uv run kazunoko status >> status.jsonl

    echo "=== Completed measurement $file_num ==="
done

Python Script Example¶

#!/usr/bin/env python3
"""
measure_multiple_files.py - Acquire detector data with status logging
"""

from pathlib import Path
from kazunoko import connect, Command, Reader, ResponseView

def main(runs: int = 3, events: int = 5000):
    """Acquire multiple measurements with status logging."""
    status_path = Path("status.jsonl")

    with connect() as device:
        cmd = Command(device)
        reader = Reader(device)

        for i in range(1, runs + 1):
            print(f"=== Starting measurement {i} ===")

            # Record status snapshot at start (flat perspective)
            resp = cmd.status()
            view = ResponseView(resp)
            with status_path.open("a") as f:
                f.write(view.flat.model_dump_json() + "\n")

            # Acquire events into separate file
            events_path = Path(f"events_{i}.jsonl")
            print(f"Recording {events} events to {events_path}...")

            with events_path.open("a") as f:
                for count, event in enumerate(reader.stream_by_count(events), 1):
                    view = ResponseView(event)
                    f.write(view.flat.model_dump_json() + "\n")
                    if count % 1000 == 0:
                        print(f"  {count}/{events} events recorded")

            # Record status snapshot at end (flat perspective)
            resp = cmd.status()
            view = ResponseView(resp)
            with status_path.open("a") as f:
                f.write(view.flat.model_dump_json() + "\n")

            print(f"=== Completed measurement {i} ===\n")

if __name__ == "__main__":
    main()

This pattern provides:

Single status log: All status snapshots accumulate in status.jsonl with timestamps showing when each measurement started and ended
Separate event files: Each measurement's detection events are stored independently (events_1.jsonl, events_2.jsonl, etc.)
Easy analysis: Later, the status log can be analyzed to check for threshold drift, uptime changes, or system anomalies across all measurements

Example status.jsonl after three measurements:

{"type": "response", "status": "ok", "uptime_ms": 100000, "thresholds_ch1": 320, ...}
{"type": "response", "status": "ok", "uptime_ms": 152000, "thresholds_ch1": 320, ...}
{"type": "response", "status": "ok", "uptime_ms": 204000, "thresholds_ch1": 320, ...}
{"type": "response", "status": "ok", "uptime_ms": 256000, "thresholds_ch1": 320, ...}
{"type": "response", "status": "ok", "uptime_ms": 308000, "thresholds_ch1": 320, ...}
{"type": "response", "status": "ok", "uptime_ms": 360000, "thresholds_ch1": 320, ...}