Skip to content

v0.1.62 - Improved Port Detection Error Messages (2025-12-21)

What Changed?

This release improves the error handling in the detect_port() function. When no suitable serial port is found for the OSECHI detector, the function now displays a list of all available ports to help users identify which port to use. This change removes the previous behavior of silently connecting to the first available port.

What's New

Improved Error Messages: Enhanced Port Detection Feedback

What it does: When detect_port() cannot find a suitable serial port matching the expected patterns (macOS USB serial, Linux USB, ACM, or built-in serial), it now raises a DeviceError with a helpful message listing all available ports on the system.

How to use it: Simply use the existing detect_port() function or the connect() factory function with port="auto". If no suitable port is found, you'll see a clear error message with available alternatives:

DeviceError: No suitable serial port found for OSECHI detector.

Available ports:
  - /dev/ttyS0 (COM1)
  - /dev/ttyUSB1 (USB Serial Port)

Code example:

from kazunoko import connect, device

# Auto-detect port - now shows helpful error if no match
try:
    dev = connect()  # or connect(port="auto")
except DeviceError as e:
    print(e)  # Shows available ports
    # User can now specify port explicitly:
    dev = connect(port="/dev/ttyUSB1")

Installation

Quick Start

# Get the release
git checkout v0.1.62

# Setup
task env:setup

# Run CLI with auto-detection
uv run kazunoko status

# Or specify port explicitly
uv run kazunoko status --port /dev/ttyUSB0

What's Different from the Last Version?

✅ Added

  • Enhanced error messages showing available ports when no suitable serial port is detected

🔧 Changed

  • detect_port() now explicitly raises an error with port list instead of silently connecting to the first available port
  • Improved user feedback for port detection failures with device descriptions

Is It Safe to Upgrade?

Backward Compatible: Mostly Yes, with minor behavior change

  • If you use detect_port() with a port that doesn't match the preferred patterns (macOS USB serial, Linux USB, ACM, or built-in serial), the function will now raise an error instead of connecting silently. Users should explicitly specify the port using connect(port="/dev/ttyXXX").
  • For most users with standard USB serial adapters, there is no change in behavior.

Tests Passed

  • ✅ Builds without errors
  • ✅ Code passes ruff linting
  • ✅ Code passes mypy type checking

Release Details

  • Date: 2025-12-21
  • Version: v0.1.62
  • Files Changed: 1 (src/kazunoko/device.py)
  • Commits:
  • db00fcb refactor: improve detect_port error message with available ports list
  • 5e70650 bump: version 0.1.61 → 0.1.62

Next Steps

Future improvements could include:

  • Interactive port selection when multiple ports are available
  • Configuration file support for preferred port settings
  • Device validation to confirm the selected port is actually an OSECHI detector