Add DeviceController: headless threaded wrapper for any PhysicalDevice

[dccote]

Why

Every interactive app built on a PhysicalDevice re-solves the same problems:

• Blocking calls — e.g. the Millennia confirms ON/OFF by write→settle→read, up to several seconds, so device calls can't run on a UI thread.
• Shared port — status polling and user actions touch the same port and must be serialized (writeCommand isn't under transactionLock), or bytes interleave.
• Drops — cables get pulled, ports vanish; apps want to recover.
• Toolkit independence — none of the above should know about Tk/Qt/etc.

I just hand-wrote exactly this controller for a Millennia GUI; it's generic enough to live in the library so the next device app (Cobolt, Sutter, …) doesn't redo it.

What

DeviceController wraps any PhysicalDevice and runs all device access — submitted commands and the periodic status poll — through one worker thread. No races, ordering preserved. It reports through the existing NotificationCenter, so any front-end just observes notifications (marshalling to a UI thread is the front-end's job). The module imports only the stdlib + NotificationCenter — no toolkit dependency, and it's wired into the top-level package.

from hardwarelibrary.devicecontroller import DeviceController, DeviceControllerNotification as N
from hardwarelibrary.notificationcenter import NotificationCenter

controller = DeviceController(MillenniaDevice(portPath="/dev/cu.usbmodem1"))
NotificationCenter().addObserver(self, on_status, N.status)   # userInfo = doGetStatusUserInfo()
controller.start(); controller.connect()
controller.submit(lambda device: device.turnOn())

Notifications: didConnect / didDisconnect / connectionLost / connectionFailed / status / commandFailed.

Features:

• submit(action) — async commands on the worker thread; failures post commandFailed; a status poll is forced after a successful command so observers see new state promptly.
• connect() / disconnect() with intent, and auto-reconnect (configurable interval) that an explicit disconnect() cancels.
• Status polling via doGetStatusUserInfo() that disables itself for devices without a snapshot (returns None).
• connection_error_reason(error) — toolkit-agnostic helper that classifies busy/missing/permission off the exception chain (pairs with the preserved init error from Millennia eV: status snapshot + preserve init error #98).

Design boundary

This is the GUI-agnostic half of an app controller. The Tk/mytk half (observe these notifications, marshal to the main thread, bind widgets) deliberately stays out of this library so PyHardwareLibrary never depends on a UI toolkit. Scoped per discussion to just the headless controller; the mytk binding / capability-driven panels are a possible follow-up once validated against a second device.

Tests

Adds testDeviceController.py — 9 unittest cases driven by the Debug Millennia device (connect/status, command success + failure, command-while-disconnected, drop→auto-reconnect, explicit-disconnect-no-reconnect, no-auto-reconnect-gives-up, statusless device, error classification). All pass; existing testMillennia suite unaffected.

🤖 Generated with Claude Code

[dccote]

Follow-up for full generality: submit() now returns a concurrent.futures.Future resolving with the action's return value (or exception), so query-style devices (powermeters, oscilloscopes) can read data back — not just actuators. commandFailed is still posted for observers that don't hold the Future. Added two tests (result via Future, failure raises in Future); suite is now 10/10.