haniwers.v1.cli.port

`haniwers.v1.cli.port`#

Port management commands for haniwers v1 CLI.

Provides commands for discovering and testing serial ports. Helps users identify which port connects to the OSECHI detector.

Commands: list: Show all available serial ports test: Test connectivity to OSECHI detector diagnose: Diagnose ESP32 flash chip using esptool

Dependencies: - pyserial (serial.tools.list_ports): Serial port enumeration - esptool: ESP32 flash chip diagnostics - loguru: Structured logging

Module Contents#

Classes#

`DetectorData`	One line of data from OSECHI detector.
`FlashInfo`	ESP32 flash chip information from esptool.
`TestResult`	Result of a port connectivity test.

Functions#

`list`	List all available serial ports.
`test_port_connectivity`	Test connectivity to OSECHI detector.
`diagnose`	Diagnose ESP32 flash chip using esptool.
`_parse_flash_output`	Parse esptool flash_id output into FlashInfo.

Data#

app

API#

haniwers.v1.cli.port.app#: ‘Typer(…)’

class haniwers.v1.cli.port.DetectorData#

One line of data from OSECHI detector.

Format: “top mid btm adc tmp atm hmd” Example: “2 0 0 936 27.37 100594.35 41.43”

Fields: top: Top layer hit count (0-10) mid: Middle layer hit count (0-10) btm: Bottom layer hit count (0-10) adc: ADC value (0-1023, 10-bit) tmp: Temperature in °C (15-35) atm: Atmospheric pressure in Pa (95000-105000) hmd: Humidity in % (0-100)

top: int#: None

mid: int#: None

btm: int#: None

adc: int#: None

tmp: float#: None

atm: float#: None

hmd: float#: None

classmethod from_line(line: str) → haniwers.v1.cli.port.DetectorData#

Parse a line of detector data.

Args: line: Space-separated values string

Returns: DetectorData instance

Raises: ValueError: If line format is invalid

Example: >>> data = DetectorData.from_line(“2 0 0 936 27.37 100594.35 41.43”) >>> data.tmp 27.37

is_valid() → bool#

Check if values are within expected ranges.

Returns: True if all values are reasonable, False otherwise

class haniwers.v1.cli.port.FlashInfo#

ESP32 flash chip information from esptool.

Stores flash chip details obtained via esptool flash_id command.

Fields: manufacturer: Flash chip manufacturer ID (hex string) device: Flash chip device ID (hex string) flash_size: Detected flash size (e.g., “8MB”) flash_voltage: Flash voltage setting (e.g., “3.3V”) chip_type: ESP32 chip variant (e.g., “ESP32-D0WD-V3”) crystal: Crystal frequency (e.g., “40MHz”) mac_address: MAC address of the chip

manufacturer: Optional[str]#: None

device: Optional[str]#: None

flash_size: Optional[str]#: None

flash_voltage: Optional[str]#: None

chip_type: Optional[str]#: None

crystal: Optional[str]#: None

mac_address: Optional[str]#: None

is_healthy() → bool#

Check if flash chip communication is successful.

Returns: True if flash chip responds normally, False otherwise

A manufacturer ID of “ff” indicates communication failure.

get_diagnosis() → str#

Get diagnostic message based on flash chip status.

Returns: Human-readable diagnostic message with recommendations

class haniwers.v1.cli.port.TestResult#

Result of a port connectivity test.

Stores whether the test succeeded and why.

Fields: success: True if test passed, False otherwise message: Human-readable result message response_time: Time to receive data in seconds (optional) data_sample: First line of data received (optional) error_type: Error category if failed (optional)

success: bool#: None

message: str#: None

response_time: Optional[float]#: None

data_sample: Optional[str]#: None

error_type: Optional[str]#: None

classmethod success_result(response_time: float, data_sample: str) → haniwers.v1.cli.port.TestResult#

Create a successful test result.

Args: response_time: Time taken to receive data (seconds) data_sample: First line of valid data

Returns: TestResult with success=True

classmethod failure_result(error_type: str, message: str) → haniwers.v1.cli.port.TestResult#

Create a failed test result.

Args: error_type: Category of error (timeout, permission, etc.) message: Human-readable error explanation

Returns: TestResult with success=False

format_for_display() → str#

Format result for user-friendly display.

Returns: Multi-line formatted string with all relevant info

haniwers.v1.cli.port.list() → None#

List all available serial ports.

Shows device paths, descriptions, and USB information for all serial ports on the system.

Example: $ haniwers-v1 port list

haniwers.v1.cli.port.test_port_connectivity(device: str = typer.Argument(..., help='Device path to test (e.g., /dev/ttyUSB0, COM3)'), baudrate: Optional[int] = DeviceOptions.baudrate, timeout: Optional[float] = DeviceOptions.timeout) → None#

Test connectivity to OSECHI detector.

Opens the specified port and attempts to read detector data to verify it’s the correct device.

Args: device: Path to serial device (e.g., /dev/ttyUSB0, COM3) baudrate: Baud rate in bits per second (default: 115200) timeout: Read timeout in seconds (default: 5.0)

Example: $ haniwers-v1 port test /dev/ttyUSB0 $ haniwers-v1 port test COM3 --timeout 10 $ haniwers-v1 port test /dev/ttyUSB0 --baudrate 9600 $ haniwers-v1 port test /dev/ttyUSB0 --baudrate 9600 --timeout 10

haniwers.v1.cli.port.diagnose(device: str = typer.Argument(..., help='Device path to diagnose (e.g., /dev/ttyUSB0, COM3)'), baudrate: int = typer.Option(115200, help='Baud rate for communication'), flash_id: bool = typer.Option(False, '--flash-id', help='Show flash chip ID only'), chip_id: bool = typer.Option(False, '--chip-id', help='Show chip ID only'), summary: bool = typer.Option(False, '--summary', help='Show chip summary only')) → None#

Diagnose ESP32 flash chip using esptool.

Connects to ESP32 device and retrieves flash chip information. Useful for troubleshooting firmware upload issues.

Args: device: Path to serial device (e.g., /dev/ttyUSB0, COM3) baudrate: Baud rate in bits per second (default: 115200) flash_id: Show only flash chip ID information chip_id: Show only chip ID information summary: Show only chip summary information

Example: $ haniwers-v1 port diagnose /dev/ttyUSB0 $ haniwers-v1 port diagnose /dev/ttyUSB0 --flash-id $ haniwers-v1 port diagnose COM3 --baudrate 9600

haniwers.v1.cli.port._parse_flash_output(output: str) → haniwers.v1.cli.port.FlashInfo#

Parse esptool flash_id output into FlashInfo.

Args: output: Raw output from esptool.flash_id()

Returns: FlashInfo instance with parsed fields

The output format looks like: Manufacturer: 20 Device: 4017 Detected flash size: 8MB Flash voltage set by a strapping pin: 3.3V