Add PowerStrip device family and PwrUSBDevice driver

Problem: A PwrUSB / PowerUSB power bar (USB HID 04d8:003f, enumerates as
"Simple HID Device Demo") with three switchable outlets was attached, but
PyHardwareLibrary had no power-strip family or driver for it.

Solution: Add hardwarelibrary/powerstrips/ following the interface-segregated
capability-mixin pattern of sources/ and daq/. PowerStripDevice is a thin
marker base over PhysicalDevice exposing capabilities()/hasCapability();
capabilities.py defines OutletSwitchingControl, DefaultOutletControl, and
CurrentMeteringControl, each a public method over a do* hook. PwrUSBDevice
implements all three, speaking the device's single-byte HID report protocol
entirely through this library's USBPort (no HID or third-party dependency).
The protocol was reverse-engineered publicly and cross-checked against
aarossig/pwrusbctl (Apache-2.0) and pwrusb.com; the implementation is our own,
with attribution in the module docstring and CHANGELOG. Outlet state is cached
on write because live readback is unreliable on this firmware. DebugPwrUSBPort
decodes the real command bytes so DebugPwrUSBDevice exercises the encoding end
to end without hardware. On macOS the OS IOHIDFamily driver claims the HID
interface, so initializeDevice fails cleanly with USBError (hardware tests skip
per the project's no-hardware policy); the driver is usable on Linux/Windows.

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

Author: dccote

CHANGELOG.md

@@ -7,6 +7,23 @@ API changes can land even when the minor version is unchanged.
 ## [Unreleased]
 
 ### Added
+- PowerStrip device family (`hardwarelibrary/powerstrips/`) plus its first driver
+  `PwrUSBDevice` (and `DebugPwrUSBDevice`) for the PwrUSB / PowerUSB controllable
+  power strip (USB HID `04d8:003f`, enumerates as "Simple HID Device Demo"). The
+  family follows the interface-segregated capability-mixin pattern used by
+  `sources/` and `daq/`: `PowerStripDevice` is a thin marker base over
+  `PhysicalDevice`, and behaviour comes from `OutletSwitchingControl`
+  (`turnOutletOn`/`turnOutletOff`/`setOutletState`/`isOutletOn`/`outletCount`,
+  outlets 1-based), `DefaultOutletControl` (per-outlet power-on default state),
+  and `CurrentMeteringControl` (`current()` in A, `accumulatedCharge()` in Ah,
+  `resetAccumulatedCharge()`). The strip speaks a single-byte HID report protocol
+  driven entirely through this library's `USBPort` (no HID/third-party dependency);
+  the protocol was reverse-engineered publicly and cross-checked against
+  aarossig/pwrusbctl (Apache-2.0) and pwrusb.com, but the implementation is our
+  own. Outlet state is cached on write because live readback is unreliable on this
+  firmware. Note: on macOS the OS `IOHIDFamily` driver claims the HID interface, so
+  `initializeDevice` fails with `USBError [Errno 13] Access denied`; the driver is
+  usable on Linux (with a udev rule granting access) and Windows.
 - `VerdiGDevice` (and `DebugVerdiGDevice`): a laser-source driver for the Coherent
   "HOPS" (High Output Power Supply) laser -- Genesis heads / Verdi G-C, e.g. the
   lab Genesis CX-Vis (head `G532`). A HOPS supply is not a serial device: its

hardwarelibrary/powerstrips/__init__.py

@@ -0,0 +1,6 @@
+from .capabilities import (
+    Capability,
+    OutletSwitchingControl, DefaultOutletControl, CurrentMeteringControl,
+)
+from .powerstripdevice import PowerStripDevice
+from .pwrusb import PwrUSBDevice, DebugPwrUSBDevice, DebugPwrUSBPort

hardwarelibrary/powerstrips/capabilities.py

@@ -0,0 +1,99 @@
+from abc import ABC, abstractmethod
+
+
+class Capability(ABC):
+    pass
+
+
+class OutletSwitchingControl(Capability):
+    """Switch individual outlets on and off and read their state.
+
+    Outlets are addressed by their physical label (1-based): the first
+    switchable outlet is outlet 1. Some strips also carry an always-on outlet
+    that is not switchable and is not counted here.
+    """
+
+    def turnOutletOn(self, outlet: int):
+        self.doSetOutletState(outlet, True)
+
+    def turnOutletOff(self, outlet: int):
+        self.doSetOutletState(outlet, False)
+
+    def setOutletState(self, outlet: int, isOn: bool):
+        self.doSetOutletState(outlet, isOn)
+
+    def isOutletOn(self, outlet: int) -> bool:
+        return self.doGetOutletState(outlet)
+
+    @property
+    def outletCount(self) -> int:
+        return self.doGetOutletCount()
+
+    @abstractmethod
+    def doSetOutletState(self, outlet: int, isOn: bool):
+        ...
+
+    @abstractmethod
+    def doGetOutletState(self, outlet: int) -> bool:
+        ...
+
+    @abstractmethod
+    def doGetOutletCount(self) -> int:
+        ...
+
+
+class DefaultOutletControl(Capability):
+    """Set the power-on (boot) state of individual outlets.
+
+    Distinct from OutletSwitchingControl: this configures the state each outlet
+    powers up in after the strip loses and regains mains power, not its state
+    right now.
+    """
+
+    def setOutletDefaultOn(self, outlet: int):
+        self.doSetOutletDefaultState(outlet, True)
+
+    def setOutletDefaultOff(self, outlet: int):
+        self.doSetOutletDefaultState(outlet, False)
+
+    def setOutletDefaultState(self, outlet: int, isOn: bool):
+        self.doSetOutletDefaultState(outlet, isOn)
+
+    @abstractmethod
+    def doSetOutletDefaultState(self, outlet: int, isOn: bool):
+        ...
+
+
+class CurrentMeteringControl(Capability):
+    """Measure the strip's total current draw and accumulated charge.
+
+    Only metering-capable strips (e.g. the PowerUSB "Smart" model) implement
+    this; a driver mixes it in only when the hardware supports it. Values are in
+    SI units at this boundary: current in amperes, accumulated charge in
+    ampere-hours.
+    """
+
+    unit = "A"
+    isReadable = True
+    isWritable = False
+
+    def current(self) -> float:
+        return self.doGetCurrent()
+
+    def accumulatedCharge(self) -> float:
+        return self.doGetAccumulatedCharge()
+
+    def resetAccumulatedCharge(self):
+        self.doResetAccumulatedCharge()
+
+    @abstractmethod
+    def doGetCurrent(self) -> float:
+        ...
+
+    @abstractmethod
+    def doGetAccumulatedCharge(self) -> float:
+        ...
+
+    @abstractmethod
+    def doResetAccumulatedCharge(self):
+        ...

hardwarelibrary/powerstrips/powerstripdevice.py

@@ -0,0 +1,23 @@
+from hardwarelibrary.physicaldevice import PhysicalDevice
+from hardwarelibrary.powerstrips.capabilities import Capability
+
+
+class PowerStripDevice(PhysicalDevice):
+    """Family marker base for controllable power strips (switched outlets).
+
+    A driver subclasses this and mixes in the capability classes from
+    capabilities.py (OutletSwitchingControl, DefaultOutletControl,
+    CurrentMeteringControl). The behaviour lives in the mixins; this base only
+    reports which capabilities a given driver actually implements.
+    """
+
+    def capabilities(self) -> list:
+        # The capability mixins, not the marker nor the device class itself
+        # (a driver is a Capability subclass too, but it is a PhysicalDevice).
+        return [klass for klass in type(self).__mro__
+                if issubclass(klass, Capability)
+                and klass is not Capability
+                and not issubclass(klass, PhysicalDevice)]
+
+    def hasCapability(self, capabilityClass) -> bool:
+        return isinstance(self, capabilityClass)