Uniformize capability mixins: single *Capability convention, single module, single base (#114)

* Rename DAQ capability mixins from *Device to *Capability

Problem: The DAQ family named its interface-segregated capability mixins
with a *Device suffix (AnalogInputDevice, TriggerableDevice, ...), while
the same objects are features a device *has*, not devices themselves.
This collided conceptually with instantiable hardware drivers, which are
also named *Device (LabjackDevice, SR830Device), making it unclear from
a name whether a class is a mixin or a real device.

Solution: Rename all nine DAQ mixins to the *Capability suffix, reserving
*Device for instantiable hardware drivers. Public methods and behavior are
unchanged; only the mixin class names change.

  AnalogInputDevice        -> AnalogInputCapability
  AnalogOutputDevice       -> AnalogOutputCapability
  AnalogIODevice           -> AnalogIOCapability
  AnalogInputStreamDevice  -> AnalogInputStreamCapability
  DigitalInputDevice       -> DigitalInputCapability
  DigitalOutputDevice      -> DigitalOutputCapability
  DigitalIODevice          -> DigitalIOCapability
  PhaseLockedDetectionDevice -> PhaseLockedDetectionCapability
  TriggerableDevice        -> TriggerCapability

Updates the LabjackDevice and SR830Device base-class lists and imports,
the daq package exports, and the SR830 tests. Documents the rename in
CHANGELOG (Unreleased, marked Breaking) and the *Capability/*Device rule
in CLAUDE.md and the skill doc.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Rename source and power-meter capability mixins to *Capability

Problem: After the DAQ rename, two families still used their own
conventions for capability mixins: laser sources used a *Control suffix
(OnOffControl, PowerControl, ...) and power meters used adjective forms
(WavelengthCalibratable, AutoScalable, ScaleAdjustable). This left three
naming styles for the same concept -- a feature a device may have -- and
made it inconsistent which classes are mixins versus instantiable
devices.

Solution: Rename these mixins to the same *Capability suffix adopted for
DAQ, completing the uniform rule: *Capability for mixins, *Device for
instantiable hardware. Public methods and behavior are unchanged.

Laser sources (sources/capabilities.py):
  OnOffControl        -> OnOffCapability
  ShutterControl      -> ShutterCapability
  PowerControl        -> PowerCapability
  InterlockControl    -> InterlockCapability
  AutostartControl    -> AutostartCapability
  WavelengthControl   -> WavelengthCapability
  DispersionControl   -> DispersionCapability

Power meters (powermeters/capabilities.py):
  WavelengthCalibratable -> WavelengthCalibrationCapability
  AutoScalable           -> AutoScaleCapability
  ScaleAdjustable        -> ScaleCapability

Updates the CoboltDevice, MillenniaEv25Device, MatisseDevice,
VerdiGDevice, FieldMasterDevice, and IntegraDevice base-class lists and
imports, the sources/powermeters package exports, the source/powermeter
tests, and the physicaldevice.py doc comment. Documents the rename in
CHANGELOG (Unreleased, folded into the Breaking capability-rename entry)
and CLAUDE.md / the skill doc, and aligns the HOPS and Millennia manuals.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Consolidate capability mixins into one module with a single Capability base

Problem: Capability mixins were spread across three modules with two
independent Capability base classes: sources/capabilities.py and
powermeters/capabilities.py each defined their own Capability(ABC), while
the DAQ mixins in daq/daqdevice.py inherited bare ABC with no shared base
at all. Capability introspection (capabilities() / hasCapability()) was
duplicated verbatim on LaserSourceDevice and PowerMeterDevice, each bound
to its family's local Capability, and DAQ devices had no introspection.

Solution: Move every capability mixin into a single top-level module,
hardwarelibrary/capabilities.py, all subclassing one Capability base. The
DAQ enums (InputSource, TriggerSource, SampleClock, DAQNotification) move
with their mixins. Hoist capabilities() / hasCapability() onto
PhysicalDevice, bound to the single Capability, so every device -- DAQ
included -- gets capability introspection, and the duplicated methods are
removed (LaserSourceDevice becomes a pure marker; PowerMeterDevice keeps
only its power hooks).

The per-family capabilities.py / daqdevice.py files are deleted. All
internal imports point at hardwarelibrary.capabilities; the family package
__init__s still re-export their own mixins, so existing consumers such as
`from hardwarelibrary.daq import AnalogIOCapability` keep working.

Docs updated: capabilities are documented once on the Core page; the
per-family automodule sections and their file-path references are removed.

Full suite: 470 passed, 247 skipped, no regressions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Nest the acquisition notification inside AnalogInputStreamCapability

Problem: DAQNotification (willAcquire/didAcquire) sat as a free-floating
module-level enum in capabilities.py, unattached to the capability that
posts it.

Solution: Nest it as AnalogInputStreamCapability.Notification, inside the
acquisition capability it belongs to, so the notification is discoverable
from the capability that raises it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dccote

.claude/skills/pyhardwarelibrary/SKILL.md

@@ -131,11 +131,11 @@ the capabilities it declares — check the table.
 
 | Capability | Methods |
 |---|---|
-| `OnOffControl` | `turnOn()`, `turnOff()`, `isLaserOn()`, `canTurnOn()` |
-| `ShutterControl` | `openShutter()`, `closeShutter()`, `isShutterOpen()` |
-| `PowerControl` | `setPower(watts)`, `power()` |
-| `InterlockControl` | `interlock()` |
-| `WavelengthControl` | `setWavelength(nm)`, `wavelength()`, `wavelengthRange()` |
+| `OnOffCapability` | `turnOn()`, `turnOff()`, `isLaserOn()`, `canTurnOn()` |
+| `ShutterCapability` | `openShutter()`, `closeShutter()`, `isShutterOpen()` |
+| `PowerCapability` | `setPower(watts)`, `power()` |
+| `InterlockCapability` | `interlock()` |
+| `WavelengthCapability` | `setWavelength(nm)`, `wavelength()`, `wavelengthRange()` |
 
 ```python
 from hardwarelibrary.sources.millennia import MillenniaEv25Device
@@ -153,7 +153,7 @@ laser.shutdownDevice()
 
 - Cobolt: `CoboltDevice(portPath="COM3")` — OnOff + Power (+ autostart constraints; it
   may refuse `turnOn()` when autostart is on, raising `CoboltCantTurnOnWithAutostartOn`).
-- Matisse: `MatisseDevice(...)` over TCP — `WavelengthControl` (`setWavelength`/`wavelength`)
+- Matisse: `MatisseDevice(...)` over TCP — `WavelengthCapability` (`setWavelength`/`wavelength`)
   plus BiFi/etalon/piezo/scan methods.
 
 ### Power meters — Gentec-EO Integra
@@ -181,7 +181,7 @@ v = daq.getAnalogVoltage(channel=0)        # read
 daq.setAnalogVoltage(2.5, channel=1)       # write (U3 DACs are slow PWM)
 bit = daq.getDigitalValue(channel=4)
 daq.setDigitalValue(1, channel=5)
-# Hardware-timed acquisition: daq.acquireWaveform(...) (AnalogInputStreamDevice)
+# Hardware-timed acquisition: daq.acquireWaveform(...) (AnalogInputStreamCapability)
 daq.shutdownDevice()
 ```
 

CHANGELOG.md

@@ -12,8 +12,8 @@ API changes can land even when the minor version is unchanged.
   lab Genesis CX-Vis (head `G532`). A HOPS supply is not a serial device: its
   FTDI FT2232 (`0x0403:0x6010`) is driven as bit-banged I2C, with power DAC, ADC,
   shutter/enable GPIO, and the head identity/calibration EEPROM all on one I2C
-  bus (see `manuals/Coherent-HOPS-*`). `VerdiGDevice` combines `OnOffControl`,
-  `ShutterControl`, `PowerControl`, and `InterlockControl`, and drives the bus
+  bus (see `manuals/Coherent-HOPS-*`). `VerdiGDevice` combines `OnOffCapability`,
+  `ShutterCapability`, `PowerCapability`, and `InterlockCapability`, and drives the bus
   through an interchangeable `HOPSInterface`:
   - `HOPSNativeInterface` (`sources/hopsnative.py`): **pure-Python** pyftdi I2C,
     no DLL (macOS/Linux). Hardware-confirmed end to end on the lab unit
@@ -28,6 +28,39 @@ API changes can land even when the minor version is unchanged.
   decode in `manuals/Coherent-HOPS-2-USB-and-DLL-Protocol.md` and
   `manuals/Coherent-HOPS-3-I2C-Wire-Protocol.md`.
 
+### Changed
+- **Breaking:** capability mixins across all families now use a uniform
+  `*Capability` suffix, reserving `*Device` for instantiable hardware drivers.
+  Public methods and behavior are unchanged; only the mixin class names change.
+  Drivers subclassing these must update their base-class lists and imports.
+  - DAQ: `AnalogInputDevice` -> `AnalogInputCapability`, `AnalogOutputDevice` ->
+    `AnalogOutputCapability`, `AnalogIODevice` -> `AnalogIOCapability`,
+    `AnalogInputStreamDevice` -> `AnalogInputStreamCapability`,
+    `DigitalInputDevice` -> `DigitalInputCapability`, `DigitalOutputDevice` ->
+    `DigitalOutputCapability`, `DigitalIODevice` -> `DigitalIOCapability`,
+    `PhaseLockedDetectionDevice` -> `PhaseLockedDetectionCapability`,
+    `TriggerableDevice` -> `TriggerCapability`.
+  - Laser sources: `OnOffControl` -> `OnOffCapability`, `ShutterControl` ->
+    `ShutterCapability`, `PowerControl` -> `PowerCapability`, `InterlockControl`
+    -> `InterlockCapability`, `AutostartControl` -> `AutostartCapability`,
+    `WavelengthControl` -> `WavelengthCapability`, `DispersionControl` ->
+    `DispersionCapability`.
+  - Power meters: `WavelengthCalibratable` -> `WavelengthCalibrationCapability`,
+    `AutoScalable` -> `AutoScaleCapability`, `ScaleAdjustable` ->
+    `ScaleCapability`.
+- **Breaking:** all capability mixins are consolidated into a single module,
+  `hardwarelibrary/capabilities.py`, and share one `Capability` base class (the
+  per-family `sources/capabilities.py`, `powermeters/capabilities.py`, and
+  `daq/daqdevice.py` are removed; the DAQ enums `InputSource`, `TriggerSource`,
+  `SampleClock` move there too, and the acquisition notification enum is now
+  nested as `AnalogInputStreamCapability.Notification`). Imports must point at
+  `hardwarelibrary.capabilities` (the family package `__init__`s still re-export
+  their own mixins, so `from hardwarelibrary.daq import AnalogIOCapability` and
+  the like keep working). `capabilities()` / `hasCapability()` are hoisted onto
+  `PhysicalDevice`, so every device -- including DAQ drivers -- now supports
+  capability introspection; the duplicated methods on `LaserSourceDevice` and
+  `PowerMeterDevice` are gone (`LaserSourceDevice` is now a pure marker).
+
 ## [1.4.0] - 2026-07-08
 
 ### Added

CLAUDE.md

@@ -59,16 +59,17 @@ Each family has an **abstract base class**. A driver subclasses it and implement
 
 **Thorlabs linear motion** is a backend dispatcher: `ThorlabsDevice` (in `motion/thorlabs.py`) routes to `ThorlabsKinesisDevice`, which drives the stage through `pylablib`'s Kinesis support. The old FTDI path (`ThorlabsFTDIDevice`) was dropped. Install with the `thorlabs` extra (`pip install -e .[thorlabs]`).
 
-Both the **DAQ and laser-source families use interface-segregated capability mixins** instead of one fat base class, because a device may implement any subset of the capabilities.
+All families **use interface-segregated capability mixins** instead of one fat base class, because a device may implement any subset of the capabilities. Every mixin lives in the single module `hardwarelibrary/capabilities.py` and subclasses the one `Capability` base there; mixins carry the `*Capability` suffix, and only instantiable hardware drivers are named `*Device`. `PhysicalDevice` provides `capabilities()` / `hasCapability(cls)`, which introspect any device by walking its MRO for `Capability` subclasses — so every family gets capability introspection for free.
 
-- DAQ (`daq/daqdevice.py`): `AnalogInputDevice` (`getAnalogVoltage`), `AnalogOutputDevice` (`setAnalogVoltage`), `DigitalInputDevice` (`getDigitalValue`), `DigitalOutputDevice` (`setDigitalValue`), plus `AnalogIODevice` / `DigitalIODevice` that combine each pair, and `AnalogInputStreamDevice` for hardware-timed acquisition. The `configure*` and `direction*` methods are optional no-op hooks. Example: `class LabjackDevice(PhysicalDevice, AnalogIODevice, DigitalIODevice, AnalogInputStreamDevice)`.
-- Laser sources (`sources/capabilities.py`): `OnOffControl` (`turnOn`/`turnOff`/`isLaserOn`), `ShutterControl` (`openShutter`/`closeShutter`/`isShutterOpen`), `PowerControl` (`setPower`/`power`), `InterlockControl` (`interlock`), `AutostartControl`, `WavelengthControl` (`setWavelength`/`wavelength`), `DispersionControl`. Each exposes a public method that calls a `do*` abstract hook the driver implements. `LaserSourceDevice` is a thin marker base; the behavior comes from the mixins. Examples: `class CoboltDevice(LaserSourceDevice, OnOffControl, PowerControl, ...)`, `class MillenniaEv25Device(LaserSourceDevice, OnOffControl, ShutterControl, PowerControl)`, `class MatisseDevice(PhysicalDevice, WavelengthControl)`.
+- DAQ: `AnalogInputCapability` (`getAnalogVoltage`), `AnalogOutputCapability` (`setAnalogVoltage`), `DigitalInputCapability` (`getDigitalValue`), `DigitalOutputCapability` (`setDigitalValue`), plus `AnalogIOCapability` / `DigitalIOCapability` that combine each pair, and `AnalogInputStreamCapability` for hardware-timed acquisition. The `configure*` and `direction*` methods are optional no-op hooks. Example: `class LabjackDevice(PhysicalDevice, AnalogIOCapability, DigitalIOCapability, AnalogInputStreamCapability)`.
+- Laser sources: `OnOffCapability` (`turnOn`/`turnOff`/`isLaserOn`), `ShutterCapability` (`openShutter`/`closeShutter`/`isShutterOpen`), `PowerCapability` (`setPower`/`power`), `InterlockCapability` (`interlock`), `AutostartCapability`, `WavelengthCapability` (`setWavelength`/`wavelength`), `DispersionCapability`. Each exposes a public method that calls a `do*` abstract hook the driver implements. `LaserSourceDevice` is a thin marker base; the behavior comes from the mixins. Examples: `class CoboltDevice(LaserSourceDevice, OnOffCapability, PowerCapability, ...)`, `class MillenniaEv25Device(LaserSourceDevice, OnOffCapability, ShutterCapability, PowerCapability)`, `class MatisseDevice(PhysicalDevice, WavelengthCapability)`.
+- Power meters: `WavelengthCalibrationCapability`, `AutoScaleCapability`, `ScaleCapability` (on top of the base `doGetAbsolutePower` every meter implements).
 
 ## Adding a new device
 
 Reference implementation: `hardwarelibrary/daq/labjackdevice.py`. The pattern:
 
-1. Subclass the family base (it already extends `PhysicalDevice`). For DAQ, combine `PhysicalDevice` with the capability mixins you need, e.g. `class FooDAQ(PhysicalDevice, AnalogIODevice)`.
+1. Subclass the family base (it already extends `PhysicalDevice`). For DAQ, combine `PhysicalDevice` with the capability mixins you need, e.g. `class FooDAQ(PhysicalDevice, AnalogIOCapability)`.
 2. Set class attributes `classIdVendor` and `classIdProduct` (USB VID/PID, or the equivalent for serial-only devices).
 3. Implement `doInitializeDevice` and `doShutdownDevice`. Keep them minimal — open the port, close the port.
 4. Implement the family's abstract hooks (see the table). Omitting one raises `TypeError` at instantiation, so the class will not even construct until the contract is complete.

docs/source/api/core.rst

@@ -9,6 +9,15 @@ PhysicalDevice
 
 .. automodule:: hardwarelibrary.physicaldevice
 
+Capabilities
+------------
+
+Interface-segregated capability mixins shared by every device family. Each
+subclasses the single ``Capability`` base; ``PhysicalDevice`` introspects them
+through ``capabilities()`` / ``hasCapability()``.
+
+.. automodule:: hardwarelibrary.capabilities
+
 DeviceManager
 -------------
 

docs/source/api/daq.rst

@@ -1,12 +1,9 @@
 Data acquisition (DAQ)
 ======================
 
-Capability mixins and DAQ drivers.
-
-DAQDevice
----------
-
-.. automodule:: hardwarelibrary.daq.daqdevice
+DAQ drivers. The DAQ capability mixins (``AnalogIOCapability``,
+``DigitalIOCapability``, ``AnalogInputStreamCapability``, ...) live in
+:mod:`hardwarelibrary.capabilities`; see the Core page.
 
 LabJack
 -------

docs/source/api/sources.rst

@@ -8,10 +8,8 @@ LaserSourceDevice
 
 .. automodule:: hardwarelibrary.sources.lasersourcedevice
 
-Capabilities
-------------
-
-.. automodule:: hardwarelibrary.sources.capabilities
+The laser-source capability mixins (``OnOffCapability``, ``ShutterCapability``,
+...) live in :mod:`hardwarelibrary.capabilities`; see the Core page.
 
 Cobolt
 ------