Skip to content

v0.1.6 - Serial Port Auto-Detection (2025-12-02)

What Changed?

This release adds automatic UART port detection to the CLI, eliminating the need to manually specify the --port option in most cases. The feature intelligently prioritizes common serial port types (USB > ACM > Serial) and maintains full backward compatibility with explicit port specifications.

What's New

Main Feature: Serial Port Auto-Detection

What it does: The CLI now automatically detects available serial ports when the --port option is not specified. The detection logic prioritizes USB adapters (ttyUSB) first, then Arduino-style ACM ports (ttyACM), then built-in serial ports (ttyS*), with a fallback to any available port.

How to use it: Simply omit the --port option to enable auto-detection:

# Auto-detect port
kazunoko send STATUS

# Or explicitly specify a port (unchanged behavior)
kazunoko send STATUS --port /dev/ttyUSB0

# Verbose mode shows which port was detected
kazunoko send STATUS -v

Code example:

from kazunoko.device import connect, detect_port

# Auto-detect and connect
device = connect()  # Automatically finds available port

# Or manually detect and handle the port
port = detect_port()  # Returns first available port by priority
device = connect(port)

Installation

Quick Start

# Get the release
git checkout v0.1.6

# Setup
uv sync

# Run CLI
uv run kazunoko --help

What's Different from the Last Version?

✅ Added

  • detect_port() function in device layer for serial port auto-discovery
  • Auto-detection support for send, listen, and info CLI commands
  • Intelligent port prioritization (USB > ACM > Serial > any available)
  • Improved verbose output showing detected port names

🔧 Changed

  • connect() function now accepts Optional[str] for port (defaults to None for auto-detection)
  • CLI --port option default changed from /dev/ttyUSB0 to None for all commands
  • Verbose messages now indicate when port auto-detection is used

🐛 Fixed

  • N/A (no bug fixes in this release)

Is It Safe to Upgrade?

Backward Compatible: Yes

  • Existing code and CLI commands with explicit --port specifications continue to work unchanged
  • The DEFAULT_PORT constant remains available in constants.py for legacy uses
  • No breaking changes to the public API

Tests Passed

  • ✅ Ruff linting checks pass
  • ✅ Code structure verified
  • ✅ All CLI commands functional with auto-detection
  • ✅ Mock device testing confirms feature works correctly
  • ✅ Backward compatibility maintained

Release Details

  • Date: 2025-12-02
  • Version: v0.1.6
  • Files Changed: 2 (device.py, cli.py)
  • Commits: 649e51e feat(cli): add auto-detection of serial port when --port is not specified

Next Steps

Future enhancements could include:

  • Windows serial port detection support (COM ports)
  • Configuration file support for port preferences
  • Port availability validation before connection attempts