Joulescope Driver

2.1.0 verified Fri May 01 auth: no python

Official Python driver for Joulescope™ energy measurement instruments (JS110, JS220, JS320). Current version 2.1.0 supports Python ~=3.10, Windows 11 ARM, and includes breaking changes in the 2.x series. Release cadence is irregular, typically several times per year.

pip install pyjoulescope-driver

Common errors

error Could not find module 'pyjoulescope_driver._pyjoulescope_driver' ↓

cause Missing binary wheel or compilation failure on your platform.

fix

Install pyjoulescope-driver-bin or build from source with Cython and a C compiler. See https://github.com/jetperch/joulescope_driver/#building

error OSError: libusb-1.0.so.0: cannot open shared object file ↓

cause libusb is not installed on the system.

fix

On Ubuntu/Debian: sudo apt-get install libusb-1.0-0-dev. On macOS: brew install libusb.

error AttributeError: module 'pyjoulescope_driver' has no attribute 'Scanner' ↓

cause Importing Scanner from the wrong location or using an outdated version (<2.0.0).

fix

Use 'from pyjoulescope_driver import Scanner' with pyjoulescope-driver >=2.0.0.

error Segmentation fault (core dumped) on Linux / macOS ↓

cause Bug in driver version 2.0.3 or earlier fixed in 2.0.4.

fix

Upgrade to pyjoulescope-driver >=2.0.4.

Warnings

breaking 2.x introduced a new C API with struct layout changes: JSDRV_STREAM_HEADER_SIZE increased from 48 to 56 bytes. Any code that directly reads stream data from the underlying buffer must be updated. ↓

fix Rebuild/update any code that depends on the raw stream header size. Use pyjoulescope_driver's high-level API instead of direct C struct manipulation.

breaking tmap API removed ref counting functions (jsdrv_tmap_ref_incr, jsdrv_tmap_ref_decr) and reader enter/exit. Now uses copy-on-publish. ↓

fix Replace ref counting with jsdrv_tmap_free / jsdrv_tmap_copy calls. Update code that obtained tmap references.

gotcha The driver is not thread-safe. All calls to the same JoulescopeDriver instance must be made from the same thread. ↓

fix Use a dedicated thread for driver operations and queue commands to it.

deprecated Python 3.10 support dropped in v1.11.0. Requires Python ~=3.10 (3.11, 3.12, 3.13, 3.14). ↓

fix Upgrade Python to 3.11 or later.

gotcha On macOS, you may need to install libusb via Homebrew before installing the driver: brew install libusb ↓

fix Run 'brew install libusb' and then retry pip install.

Imports

JoulescopeDriver

wrong

from pyjoulescope_driver.driver import JoulescopeDriver

correct

from pyjoulescope_driver import JoulescopeDriver

JoulescopeDriver is exposed at package level

Scanner
wrong
```
import pyjoulescope_driver.Scanner
```
correct
```
from pyjoulescope_driver import Scanner
```
Scanner is a class under the driver module, not a submodule

Quickstart

Minimal script to open the driver, scan for devices, and print the first found device name.

from pyjoulescope_driver import JoulescopeDriver
from pyjoulescope_driver import Scanner
import numpy as np

driver = JoulescopeDriver()
scanner = Scanner(driver)
scanner.open()
devices = scanner.devices
print(f"Found {len(devices)} device(s)")
if devices:
    device_info = devices[0]
    print(f"Device: {device_info['name']}")
    driver.close(device_info['handle'])
scanner.close()