Add Joulescope energy analyzer driver and EnergyAnalyzerProtocol

Add support for the Joulescope energy analyzer (JS110/JS220/JS320) via
pyjoulescope_driver:

- New EnergyAnalyzerProtocol (get_statistics/start/stop/capture)
- New JoulescopeDevice resource: a USBResource selected via udev matching;
  serial and model are derived from udev (ID_SERIAL_SHORT / ID_MODEL_ID)
- New JoulescopeDriver implementing EnergyAnalyzerProtocol and PowerProtocol
  (downstream power switch: JS110 via s/i/range/select, JS220/JS320 via
  s/i/range/mode). Statistics use the documented per-model base sample rate
  (h/fs reads back None on JS220/JS320).
- Remote/distributed support: exporting a JoulescopeDevice makes it available
  to clients as a NetworkJoulescopeDevice. pyjoulescope_driver runs on the
  exporting host through the labgrid agent (util/agents/joulescope.py), so the
  driver binds to both the local and network resource and works unchanged over
  the coordinator/exporter infrastructure; captures are recorded on the
  exporting host and copied back.
- Optional dependency extra labgrid[joulescope]
- Unit tests (mocked) for the driver and the agent, plus a hardware-in-the-loop
  suite gated behind --joulescope, configuration docs and changelog entry

Verified hardware-in-the-loop against a JS320, both locally and via a remote
coordinator/exporter.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Matt Liberty <matt.liberty@jetperch.com>

Author: mliberty1

CHANGES.rst

@@ -1,3 +1,18 @@
+Release 27.0 (Unreleased)
+-------------------------
+
+New Features in 27.0
+~~~~~~~~~~~~~~~~~~~~~~
+
+- Support for the Joulescope energy analyzer was added via the new
+  ``JoulescopeDriver`` and ``JoulescopeDevice``, which implement the new
+  ``EnergyAnalyzerProtocol`` (statistics, charge/energy accumulation and
+  high-rate sample capture) as well as the ``PowerProtocol``. Install the
+  optional dependency with ``pip install labgrid[joulescope]``. A Joulescope can
+  be shared over the distributed infrastructure: exporting a ``JoulescopeDevice``
+  makes it available to clients as a ``NetworkJoulescopeDevice``, with
+  ``pyjoulescope_driver`` running on the exporting host via the labgrid agent.
+
 Release 26.0 (Released Jun 06, 2026)
 ------------------------------------
 Sponsored by: Analog Devices GmbH

doc/configuration.rst

@@ -765,6 +765,55 @@ Arguments:
 Used by:
   - `SigrokDriver`_
 
+JoulescopeDevice
+~~~~~~~~~~~~~~~~
+A :any:`JoulescopeDevice` resource describes a *Joulescope* energy analyzer
+(JS110, JS220 or JS320).  It is a USB resource, so a specific device is selected
+via udev matching when more than one Joulescope is connected; with a single
+Joulescope an empty match is sufficient.  The device is then addressed through
+``pyjoulescope_driver``.
+
+.. code-block:: yaml
+
+   JoulescopeDevice:
+     match:
+       ID_SERIAL_SHORT: 'S3C8'
+
+Arguments:
+  - match (dict): key and value pairs for a udev match, see `udev Matching`_
+
+Used by:
+  - `JoulescopeDriver`_
+
+NetworkJoulescopeDevice
+~~~~~~~~~~~~~~~~~~~~~~~~~
+A :any:`NetworkJoulescopeDevice` resource describes a `JoulescopeDevice`_ that is
+attached to and exported by another host, making it usable over labgrid's
+distributed infrastructure.  It is created automatically when a `JoulescopeDevice`_
+is exported and acquired via a `RemotePlace`_, so it is not usually configured
+directly.  The `JoulescopeDriver`_ runs ``pyjoulescope_driver`` on the exporting
+host through the labgrid agent, so only that host needs the ``joulescope`` extra
+installed.
+
+.. note::
+   The labgrid agent is started on the exporting host over SSH as
+   ``python3 <agent>``, so the ``python3`` found on that host's *non-interactive*
+   SSH ``PATH`` must be able to import ``pyjoulescope_driver`` (and ``pyjls`` for
+   high-rate sample capture).  Installing the
+   ``joulescope`` extra into a virtualenv that is only activated for an
+   interactive shell is not sufficient; install it into the interpreter on the
+   default ``PATH`` (or make that virtualenv's ``python3`` the default).  This is
+   the same requirement as for other agent-based USB devices (for example the
+   ``pyusb`` dependency of the HID and Deditec relays).
+
+Arguments:
+  - host (str): hostname of the exporter the device is attached to
+  - serial (str): the Joulescope serial number
+  - model (str): the Joulescope model (``js110``, ``js220`` or ``js320``)
+
+Used by:
+  - `JoulescopeDriver`_
+
 IMXUSBLoader
 ~~~~~~~~~~~~
 An :any:`IMXUSBLoader` resource describes a USB device in the imx loader state.
@@ -3191,6 +3240,55 @@ samples is an iterable of samples.
 This driver relies on buffering of the subprocess call.
 Reading a few samples will very likely work - but obtaining a lot of samples may stall.
 
+JoulescopeDriver
+~~~~~~~~~~~~~~~~
+The :any:`JoulescopeDriver` uses a `JoulescopeDevice`_ or
+`NetworkJoulescopeDevice`_ resource to measure current, voltage and power,
+accumulate charge and energy, capture high-rate samples to a JLS file, and switch
+downstream power by connecting/disconnecting the device current path.
+
+``pyjoulescope_driver`` runs on the host the Joulescope is attached to (via the
+labgrid agent), so only that host needs the ``joulescope`` extra installed.  For a
+`NetworkJoulescopeDevice`_ a captured JLS file is recorded on the exporting host
+and copied back to the client.
+
+Binds to:
+  device:
+    - `JoulescopeDevice`_
+    - `NetworkJoulescopeDevice`_
+
+Implements:
+  - :any:`EnergyAnalyzerProtocol`
+  - :any:`PowerProtocol`
+
+.. code-block:: yaml
+
+   JoulescopeDriver:
+     frequency: 10.0
+     delay: 2.0
+
+Arguments:
+  - frequency (float, default=2.0): statistics update frequency in Hz
+  - delay (float, default=2.0): delay in seconds between off and on during a
+    power cycle
+
+The latest measurement is read with ``get_statistics()``, which returns a dict
+with ``current``, ``voltage`` and ``power`` sub-dicts (each with ``avg``,
+``std``, ``min`` and ``max``) plus the accumulated ``charge_C`` (Coulombs) and
+``energy_J`` (Joules).
+``start()`` and ``stop()`` bracket a charge/energy accumulation window;
+``stop()`` returns the accumulated ``energy_J``, ``charge_C`` and the
+``duration_s`` of the window.
+``capture(filename, signals=None, duration=..., frequency=None)`` records
+high-rate samples to a JLS file for the requested duration.  ``frequency`` (in
+Hz) sets the device sample rate and is sticky: once set it stays in effect for
+later captures on the same activated driver until changed again, rather than
+reverting to the device default.
+
+Power switching via ``on()``, ``off()`` and ``cycle()`` connects and
+disconnects the device current path, controlling downstream power to the
+device under test.
+
 USBSDMuxDriver
 ~~~~~~~~~~~~~~
 The :any:`USBSDMuxDriver` uses a `USBSDMuxDevice`_ resource to control a

labgrid/driver/__init__.py

@@ -25,6 +25,7 @@
 from .modbusdriver import ModbusCoilDriver, WaveShareModbusCoilDriver
 from .modbusrtudriver import ModbusRTUDriver
 from .sigrokdriver import SigrokDriver, SigrokPowerDriver, SigrokDmmDriver
+from .joulescopedriver import JoulescopeDriver
 from .usbstoragedriver import USBStorageDriver, Mode
 from .resetdriver import DigitalOutputResetDriver
 from .gpiodriver import GpioDigitalOutputDriver

labgrid/driver/joulescopedriver.py

@@ -0,0 +1,130 @@
+import os
+import time
+import uuid
+
+import attr
+
+from ..factory import target_factory
+from ..protocol import EnergyAnalyzerProtocol, PowerProtocol
+from ..resource.joulescope import JoulescopeDevice
+from ..resource.remote import NetworkJoulescopeDevice
+from ..step import step
+from ..util.agentwrapper import AgentWrapper
+from ..util.ssh import sshmanager
+from .common import Driver
+
+
+@target_factory.reg_driver
+@attr.s(eq=False)
+class JoulescopeDriver(Driver, EnergyAnalyzerProtocol, PowerProtocol):
+    """The JoulescopeDriver controls a Joulescope energy analyzer.
+
+    It wraps ``pyjoulescope_driver`` to stream measurement statistics
+    (current, voltage, power and accumulated charge/energy), to capture
+    high-rate samples to a JLS file, and to connect/disconnect the device
+    current path (downstream power) as a :class:`PowerProtocol` power switch.
+
+    ``pyjoulescope_driver`` runs on the host the Joulescope is attached to
+    through labgrid's agent mechanism, so the same driver works for a locally
+    attached device and for one shared over the distributed infrastructure via
+    a :class:`~labgrid.resource.remote.NetworkJoulescopeDevice`.  Only the host
+    with the device attached needs the ``joulescope`` extra installed.
+
+    Power switching (``on``/``off``/``cycle``) controls downstream power to the
+    device under test: the JS110 uses the current range ``select`` and the JS220
+    and JS320 use the current range ``mode``.
+
+    Args:
+        frequency (float): statistics update frequency in Hz
+        delay (float): delay between off and on during a power cycle
+    """
+
+    bindings = {"device": {JoulescopeDevice, NetworkJoulescopeDevice}}
+    frequency = attr.ib(default=2.0, validator=attr.validators.instance_of(float))
+    delay = attr.ib(default=2.0, validator=attr.validators.instance_of(float))
+
+    def __attrs_post_init__(self):
+        super().__attrs_post_init__()
+        self.wrapper = None
+        self.proxy = None
+
+    # -- life cycle ---------------------------------------------------------
+
+    def on_activate(self):
+        host = self.device.host if isinstance(self.device, NetworkJoulescopeDevice) else None
+        self.wrapper = AgentWrapper(host)
+        try:
+            self.proxy = self.wrapper.load("joulescope")
+            self.proxy.open(self.device.serial, self.device.model, self.frequency)
+        except Exception:
+            # on_deactivate() only runs once the driver is active, so clean up
+            # the (possibly remote) agent subprocess if opening the device fails.
+            self.wrapper.close()
+            self.wrapper = None
+            self.proxy = None
+            raise
+
+    def on_deactivate(self):
+        try:
+            self.proxy.close(self.device.serial, self.device.model)
+        finally:
+            self.wrapper.close()
+            self.wrapper = None
+            self.proxy = None
+
+    # -- statistics ---------------------------------------------------------
+
+    @Driver.check_active
+    @step(result=True)
+    def get_statistics(self):
+        return self.proxy.get_statistics(self.device.serial, self.device.model)
+
+    @Driver.check_active
+    @step()
+    def start(self):
+        self.proxy.start(self.device.serial, self.device.model)
+
+    @Driver.check_active
+    @step(result=True)
+    def stop(self):
+        return self.proxy.stop(self.device.serial, self.device.model)
+
+    # -- sample capture -----------------------------------------------------
+
+    @Driver.check_active
+    @step(args=["filename", "duration"])
+    def capture(self, filename, signals=None, duration=None, frequency=None):
+        if duration is None:
+            raise ValueError("capture() requires a duration in seconds")
+        if isinstance(self.device, NetworkJoulescopeDevice):
+            # Record on the host the device is attached to, then copy the JLS
+            # file back to the client and remove the remote copy.
+            remote = f"/tmp/labgrid-joulescope-{uuid.uuid4()}.jls"
+            self.proxy.capture(self.device.serial, self.device.model, remote, signals, duration, frequency)
+            try:
+                sshmanager.get_file(self.device.host, remote, filename)
+            finally:
+                self.proxy.remove(remote)
+        else:
+            self.proxy.capture(
+                self.device.serial, self.device.model, os.fspath(filename), signals, duration, frequency
+            )
+
+    # -- power switch (PowerProtocol) --------------------------------------
+
+    @Driver.check_active
+    @step()
+    def on(self):
+        self.proxy.set_power(self.device.serial, self.device.model, True)
+
+    @Driver.check_active
+    @step()
+    def off(self):
+        self.proxy.set_power(self.device.serial, self.device.model, False)
+
+    @Driver.check_active
+    @step()
+    def cycle(self):
+        self.off()
+        time.sleep(self.delay)
+        self.on()

labgrid/protocol/__init__.py

@@ -3,6 +3,7 @@
 from .consoleprotocol import ConsoleProtocol
 from .linuxbootprotocol import LinuxBootProtocol
 from .powerprotocol import PowerProtocol
+from .energyanalyzerprotocol import EnergyAnalyzerProtocol
 from .filetransferprotocol import FileTransferProtocol
 from .infoprotocol import InfoProtocol
 from .digitaloutputprotocol import DigitalOutputProtocol

labgrid/protocol/energyanalyzerprotocol.py

@@ -0,0 +1,48 @@
+import abc
+
+
+class EnergyAnalyzerProtocol(abc.ABC):
+    """Protocol for energy analyzers such as the Joulescope.
+
+    An energy analyzer continuously measures current, voltage and power and
+    accumulates charge and energy.  Drivers implementing this protocol expose
+    the latest statistics, an accumulation window (start/stop) for charge and
+    energy, and high-rate sample capture to a file.
+    """
+
+    @abc.abstractmethod
+    def get_statistics(self):
+        """Return the latest measurement statistics as a dict.
+
+        The returned dict contains ``current``, ``voltage`` and ``power``
+        sub-dicts (each with ``avg``, ``std``, ``min`` and ``max`` keys) as
+        well as the accumulated ``charge_C`` (Coulombs) and ``energy_J``
+        (Joules).  Convenience values such as average current are read from
+        this return value rather than via dedicated accessors.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def start(self):
+        """Begin a charge/energy accumulation window."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def stop(self):
+        """End the accumulation window started by :meth:`start`.
+
+        Returns a dict with the accumulated ``energy_J`` (Joules),
+        ``charge_C`` (Coulombs) and the ``duration_s`` (seconds) of the window.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def capture(self, filename, signals=None, duration=None, frequency=None):
+        """Capture high-rate samples to a file for the given duration.
+
+        ``frequency`` (in Hz) sets the device sample rate for the capture.  It
+        is sticky: once set it remains in effect for subsequent captures on the
+        same activated driver until changed again, rather than reverting to the
+        device default.
+        """
+        raise NotImplementedError

labgrid/remote/exporter.py

@@ -386,6 +386,34 @@ def _get_params(self):
         }
 
 
+@attr.s(eq=False)
+class JoulescopeExport(USBGenericExport):
+    """ResourceExport for Joulescope energy analyzers"""
+
+    def __attrs_post_init__(self):
+        # USBGenericExport imports the local class from resource.udev, but the
+        # JoulescopeDevice lives in resource.joulescope, so build it here (the
+        # ProviderGenericExport does the same for its own module).
+        ResourceExport.__attrs_post_init__(self)
+        self.data["cls"] = f"Network{self.cls}"
+        from ..resource.joulescope import JoulescopeDevice
+
+        self.local = JoulescopeDevice(target=None, name=None, **self.local_params)
+
+    def _get_params(self):
+        """Helper function to return parameters"""
+        return {
+            "host": self.host,
+            "busnum": self.local.busnum,
+            "devnum": self.local.devnum,
+            "path": self.local.path,
+            "vendor_id": self.local.vendor_id,
+            "model_id": self.local.model_id,
+            "serial": self.local.serial,
+            "model": self.local.model,
+        }
+
+
 @attr.s(eq=False)
 class USBSDMuxExport(USBGenericExport):
     """ResourceExport for USB devices accessed directly from userspace"""
@@ -578,6 +606,7 @@ def __attrs_post_init__(self):
 exports["AlteraUSBBlaster"] = USBGenericExport
 exports["SigrokUSBDevice"] = USBSigrokExport
 exports["SigrokUSBSerialDevice"] = USBSigrokExport
+exports["JoulescopeDevice"] = JoulescopeExport
 exports["USBSDMuxDevice"] = USBSDMuxExport
 exports["USBSDWireDevice"] = USBSDWireExport
 exports["USBSDWire3Device"] = USBSDWire3Export

labgrid/resource/__init__.py

@@ -47,6 +47,7 @@
 from .dediprogflasher import DediprogFlasher, NetworkDediprogFlasher
 from .httpdigitalout import HttpDigitalOutput
 from .sigrok import SigrokDevice
+from .joulescope import JoulescopeDevice
 from .fastboot import AndroidNetFastboot
 from .eth008 import Eth008DigitalOutput
 from .laa import LAASerialPort, LAAPowerPort, LAAUSBGadgetMassStorage, \