{"id":24341,"library":"pyjoulescope-driver","title":"Joulescope Driver","description":"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.","status":"active","version":"2.1.0","language":"python","source_language":"en","source_url":"https://github.com/jetperch/joulescope_driver","tags":["joulescope","energy","driver","measurement","instrumentation"],"install":[{"cmd":"pip install pyjoulescope-driver","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required for signal data handling","package":"numpy","optional":false},{"reason":"Binary package for non-compilation platforms (use via extras)","package":"pyjoulescope-driver-bin","optional":true}],"imports":[{"note":"JoulescopeDriver is exposed at package level","wrong":"from pyjoulescope_driver.driver import JoulescopeDriver","symbol":"JoulescopeDriver","correct":"from pyjoulescope_driver import JoulescopeDriver"},{"note":"Scanner is a class under the driver module, not a submodule","wrong":"import pyjoulescope_driver.Scanner","symbol":"Scanner","correct":"from pyjoulescope_driver import Scanner"}],"quickstart":{"code":"from pyjoulescope_driver import JoulescopeDriver\nfrom pyjoulescope_driver import Scanner\nimport numpy as np\n\ndriver = JoulescopeDriver()\nscanner = Scanner(driver)\nscanner.open()\ndevices = scanner.devices\nprint(f\"Found {len(devices)} device(s)\")\nif devices:\n    device_info = devices[0]\n    print(f\"Device: {device_info['name']}\")\n    driver.close(device_info['handle'])\nscanner.close()","lang":"python","description":"Minimal script to open the driver, scan for devices, and print the first found device name."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Replace ref counting with jsdrv_tmap_free / jsdrv_tmap_copy calls. Update code that obtained tmap references.","message":"tmap API removed ref counting functions (jsdrv_tmap_ref_incr, jsdrv_tmap_ref_decr) and reader enter/exit. Now uses copy-on-publish.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Use a dedicated thread for driver operations and queue commands to it.","message":"The driver is not thread-safe. All calls to the same JoulescopeDriver instance must be made from the same thread.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade Python to 3.11 or later.","message":"Python 3.10 support dropped in v1.11.0. Requires Python ~=3.10 (3.11, 3.12, 3.13, 3.14).","severity":"deprecated","affected_versions":">=1.11.0"},{"fix":"Run 'brew install libusb' and then retry pip install.","message":"On macOS, you may need to install libusb via Homebrew before installing the driver: brew install libusb","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install pyjoulescope-driver-bin or build from source with Cython and a C compiler. See https://github.com/jetperch/joulescope_driver/#building","cause":"Missing binary wheel or compilation failure on your platform.","error":"Could not find module 'pyjoulescope_driver._pyjoulescope_driver'"},{"fix":"On Ubuntu/Debian: sudo apt-get install libusb-1.0-0-dev. On macOS: brew install libusb.","cause":"libusb is not installed on the system.","error":"OSError: libusb-1.0.so.0: cannot open shared object file"},{"fix":"Use 'from pyjoulescope_driver import Scanner' with pyjoulescope-driver >=2.0.0.","cause":"Importing Scanner from the wrong location or using an outdated version (<2.0.0).","error":"AttributeError: module 'pyjoulescope_driver' has no attribute 'Scanner'"},{"fix":"Upgrade to pyjoulescope-driver >=2.0.4.","cause":"Bug in driver version 2.0.3 or earlier fixed in 2.0.4.","error":"Segmentation fault (core dumped) on Linux / macOS"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}