[Andrey1994]

When Cyton or Cyton Daisy is prepared with an empty serial_port, enumerate USB serial metadata without opening devices and connect only if exactly one FT231X candidate matches. An existing serial_number can select a USB dongle; ambiguous or missing matches fail before any port is opened. Explicit ports continue to bypass discovery.

Related to #187. This is a first implementation for Cyton/Cyton Daisy, not a claim of autodiscovery for every serial board. Keep the issue open for additional verified device descriptors and board-specific selection rules.

Implementation

• Add internal Serial::get_port_info with Windows SetupAPI/Config Manager, Linux sysfs and macOS IOKit backends. No third-party runtime dependency; iOS/Android retain explicit-port operation.
• Keep the Cyton VID/PID policy in C++ board-controller code rather than expanding public board-description JSON. No C ABI, binding signatures or input fields change.
• Require a unique candidate after optional USB-serial filtering; never select by enumeration order or try alternate ports after an open/handshake failure. macOS uses only callout paths; Windows traverses to the physical USB device and excludes generated location IDs from USB serial numbers.
• Replace the six-empty-read/500-read welcome limit with a monotonic deadline, empty-read backoff and bounded diagnostic storage. timeout=0 means six seconds; 1–600 means a custom welcome timeout. Flush before v, not after it, and clean up on a failed default-configuration write.
• Document the native/libserialport/per-binding/probing alternatives, public API behaviour, limitations and concrete hardware acceptance criteria in docs/SerialPortDiscovery.rst.

Validation

• Linux BoardController build with WARNINGS_AS_ERRORS=ON passed.
• Dependency-free C++ regressions passed: zero/one/multiple candidates, ordering, duplicate/missing serials and metadata, Windows instance parsing, Linux sysfs fixtures, delayed/fragmented welcome, continuous noise, read failure and deadline expiry.
• POSIX pseudo-terminal integration passed against the rebuilt library: Cyton and Daisy, two prepared sessions, explicit-port precedence, release/reopen and retry after handshake timeout.
• AddressSanitizer/UndefinedBehaviorSanitizer passed with leak detection disabled because LeakSanitizer cannot inspect processes in this environment.
• clang-format 12.0.1 and whitespace checks passed. Sphinx built the new design page and changed Cyton/Daisy documentation sections with warnings as errors.
• Added a Windows/Linux/macOS CI matrix for the native tests and a Linux integration job. Native Windows/macOS execution is delegated to CI, not claimed as a local result.

Limits needing hardware verification

FT231X VID/PID identifies an adapter, not a guaranteed Cyton; unrelated FT231X products may match. A known USB serial or explicit port is recommended when these coexist, and the normal board handshake remains required. Physical dongles and driver variants have not been tested here. Ganglion/FreeEEG are not automatically enabled: their transport paths, USB identities and existing parameter semantics need separate verification. The synchronous welcome deadline can overrun by one backend read timeout.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-27T07:50:07.526893Z	669e0d5	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.