haniwers.v1.cli.scan

Threshold scanning command.

This module provides the scan command for systematic threshold exploration. The scan mode helps users find optimal detector threshold settings by collecting data across a range of threshold values.

Subcommands: serial: Serial threshold scanning with manual parameter control

Module Contents

Classes

ScanResult

Result of measuring detector at a specific threshold.

Functions

aggregate_scan_result	Aggregate events into ScanResult.
save_scan_result	Append scan result to CSV file.
serial	Perform serial threshold scan.

Data

scan_app

API

haniwers.v1.cli.scan.scan_app

‘Typer(…)’

class haniwers.v1.cli.scan.ScanResult(/, **data: typing.Any)

Bases: pydantic.BaseModel

Result of measuring detector at a specific threshold.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

timestamp: datetime.datetime

None

channel: int

‘Field(…)’

vth: int

‘Field(…)’

duration: int

‘Field(…)’

counts: int

‘Field(…)’

hit_top: int

‘Field(…)’

hit_mid: int

‘Field(…)’

hit_btm: int

‘Field(…)’

tmp: float

None

atm: float

None

hmd: float

None

to_csv_row() → list

Convert to CSV row format.

classmethod csv_header() → list[str]

Get CSV header.

haniwers.v1.cli.scan.aggregate_scan_result(events: list[haniwers.v1.daq.model.RawEvent], channel: int, vth: int, duration: int) → Optional[haniwers.v1.cli.scan.ScanResult]

Aggregate events into ScanResult.

haniwers.v1.cli.scan.save_scan_result(csv_path: pathlib.Path, result: haniwers.v1.cli.scan.ScanResult) → None

Append scan result to CSV file.

haniwers.v1.cli.scan.serial(ctx: typer.Context, config: Optional[pathlib.Path] = typer.Option(None, '--config', help='Configuration file path (config.toml, etc). If not specified, ConfigLoader searches default locations.'), port: Optional[str] = typer.Option(None, '--port', help="Serial port path for OSECHI detector (e.g., /dev/ttyUSB0, COM3). Use 'haniwers-v1 port list' to find available ports.", rich_help_panel='Device Settings'), baudrate: Optional[int] = typer.Option(None, '--baudrate', min=1, help='Serial communication baud rate in bits per second (e.g., 9600, 115200).', rich_help_panel='Device Settings'), timeout: Optional[float] = typer.Option(None, '--timeout', min=0.1, help='Serial read timeout in seconds (e.g., 1.0, 2.0).', rich_help_panel='Device Settings'), device_label: Optional[str] = typer.Option(None, '--device-label', help='Device identifier label for logging and documentation.', rich_help_panel='Device Settings'), thresholds: str = typer.Option(..., '--thresholds', '-t', help="Threshold configuration: 'channel:threshold;channel:threshold;...'. Examples: '1:290' (single channel), '1:290;2:320;3:298' (all channels).", rich_help_panel='Scan Settings'), nsteps: Optional[int] = typer.Option(10, '--nsteps', min=1, help='Number of steps on each side of center (default: 10).', rich_help_panel='Scan Settings'), step: Optional[int] = typer.Option(1, '--step', min=1, help='Threshold increment between measurement points (default: 1).', rich_help_panel='Scan Settings'), duration: Optional[int] = typer.Option(10, '--duration', min=1, help='Measurement duration per threshold in seconds (default: 10).', rich_help_panel='Scan Settings'), suppress: Optional[int] = typer.Option(1000, '--suppress', min=1, max=1023, help='Threshold value for non-target channels (default: 1000).', rich_help_panel='Scan Settings'), max_retry: int = typer.Option(3, '--max-retry', min=1, help='Maximum number of retry attempts on communication failure (default: 3).', rich_help_panel='Scan Settings'), history: pathlib.Path = typer.Option('threshold_history.csv', '--history', help='Audit log file for threshold operations (CSV format with timestamp). Automatically saved in workspace directory.', rich_help_panel='Scan Settings'), workspace: Optional[pathlib.Path] = typer.Option(None, '--workspace', help='Output directory for data files. Timestamped subdirectory created automatically.', rich_help_panel='Output Settings'), filename_prefix: Optional[str] = typer.Option('scan_data', '--filename-prefix', help="Prefix for output file names (default: 'scan_data').", rich_help_panel='Output Settings'), filename_suffix: Optional[str] = typer.Option(None, '--filename-suffix', help="File extension/suffix for output files (e.g., '.csv').", rich_help_panel='Output Settings'), events_per_file: Optional[int] = typer.Option(1000, '--events-per-file', min=1, help='Number of detector events per output file before rollover (default: 1000).', rich_help_panel='Output Settings'), number_of_files: Optional[int] = typer.Option(1, '--number-of-files', min=1, help='Maximum number of files to create per threshold level (default: 1).', rich_help_panel='Output Settings'), stream_mode: bool = typer.Option(False, '--stream-mode', help='Enable continuous streaming mode (output buffering disabled).', rich_help_panel='Output Settings'), daq_label: Optional[str] = typer.Option(None, '--daq-label', help='Session identifier label for this DAQ run.', rich_help_panel='Output Settings'), mock: bool = typer.Option(False, '--mock', help='Use RandomMocker instead of real device for testing (no hardware required).', rich_help_panel='Testing')) → None

Perform serial threshold scan.

Supports both single-channel and multi-channel scanning modes with flexible configuration loading: CLI options override config file values override defaults.

Includes automatic audit logging of threshold operations with configurable retry behavior and result saving.

Single-channel mode: $ haniwers-v1 scan serial --thresholds 1:280 --nsteps 10 --step 5

Multi-channel mode: $ haniwers-v1 scan serial --thresholds “1:290;2:320;3:298”
–nsteps 10 --step 5

With custom retry and logging: $ haniwers-v1 scan serial --thresholds 1:280 --max-retry 5
–history scan_ops.csv

Config-file mode: $ haniwers-v1 scan serial --config config.toml

Config with CLI override: $ haniwers-v1 scan serial --config config.toml --port /dev/ttyUSB0