[](https://github.com/jetperch/joulescope_driver/actions/workflows/packaging.yml) # Joulescope Driver Welcome to the Joulescope™ Driver project. [Joulescope](https://www.joulescope.com) is an affordable, precision DC energy analyzer that enables you to build better products. This user-space C library communicates with Joulescope products to configure operation and receive data. It supports the JS110, JS220, and JS320 Joulescope models. The first-generation driver introduced in 2019 was written in Python. While Python proved to be a very flexible language enabling many user scripts, it was difficult to support other languages.
\\\\ This second-generation driver launched in 2022 addresses several issues with the first-generation python driver including: 1. Improved event-driven API based upon PubSub for easier integration with user interfaces and other complicated software packages. 2. Improved portability for easier language bindings. 3. Improved performance. For more information, see: * [getting started](https://github.com/jetperch/joulescope_driver/blob/main/doc/getting_started.md) (Python and C lifecycle) * [streaming topics](https://github.com/jetperch/joulescope_driver/blob/main/doc/streaming_topics.md) (statistics and sample payloads) * [source code](https://github.com/jetperch/joulescope_driver) * [documentation](https://joulescope-driver.readthedocs.io/en/latest/) * [pypi](https://pypi.org/project/pyjoulescope-driver/) * [Joulescope](https://www.joulescope.com/) (Joulescope web store) * [jls](https://github.com/jetperch/jls) (Joulescope file format) * [forum](https://forum.joulescope.com/) ## Python Installation The python bindings work with the [supported Python versions](https://docs.joulescope.com/en/getting_started/install_ui.html#supported-platforms). To use the python bindings, ensure that you have a compatible version of python installed on your host computer. Then: ```none python -m pip install pyjoulescope_driver ``` For Ubuntu, you will also need to [install the udev rules](). You can then run the pyjoulescope_driver python entry points: ```none python -m pyjoulescope_driver --help python -m pyjoulescope_driver scan python -m pyjoulescope_driver info python -m pyjoulescope_driver values --device js320 ``` Note that you may need to change “python” to “python3” or the full path.
\\\\ You can also use a python [virtual environment](https://docs.python.org/3/tutorial/venv.html). ## Building Ensure that your computer has a development environment including CMake. ### Windows Install cmake and your favorite build toolchain such as Visual Studio, mingw64, wsl, ninja. ### macOS For macOS, install homebrew, then: ```none brew install pkgconfig python3 ``` ### Ubuntu For Ubuntu: ```none sudo apt install cmake build-essential ninja-build libudev-dev ``` You will also need to install the udev rules. If you are using a modern Linux distribution managed by systemd, using tag-based rules is most likely the right choice: ```none $ wget https://raw.githubusercontent.com/jetperch/joulescope_driver/main/72-joulescope.rules $ sudo cp 72-joulescope.rules /etc/udev/rules.d/ $ sudo udevadm control --reload-rules ``` If your system is not managed by systemd or your user is not assigned a proper login seat (as may be the case when logging in via SSH), using group-based rules is necessery (note that the plugdev group must exist/be created and your user must belong to it): ```none $ wget https://raw.githubusercontent.com/jetperch/joulescope_driver/main/99-joulescope.rules $ sudo cp 99-joulescope.rules /etc/udev/rules.d/ $ sudo udevadm control --reload-rules ``` ### Common ```none cd {your/repos/joulescope_driver} mkdir build && cd build cmake .. cmake --build . && ctest . ``` This package includes a command-line tool, jsdrv: ```none jsdrv --help jsdrv scan ``` The build also produces `jsdrv_quickstart` from [example/quickstart.c](https://github.com/jetperch/joulescope_driver/blob/main/example/quickstart.c), the minimal C program described in [getting started](https://github.com/jetperch/joulescope_driver/blob/main/doc/getting_started.md). ### Build python bindings Install a [supported version of Python](https://docs.joulescope.com/en/getting_started/install_ui.html#supported-platforms). To install the pyjoulescope_driver dependencies: ```none cd {your/repos/joulescope_driver} python -m pip install -U -r requirements.txt ``` You should then be able to build the native bindings: ```none python setup.py build_ext --inplace ``` You can build the package using isolation: ```none python -m build ``` Depending upon your system configuration, you may need to replace “python” with “python3” or the full path to your desired python installation. On Windows, you may be prompted to install the [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/). ## License The Joulescope driver source code is licensed under the [Apache-2.0 license](https://github.com/jetperch/joulescope_driver/blob/main/LICENSES/Apache-2.0.txt). The project is free for commercial and non-commercial use. The bundled [third-party](https://github.com/jetperch/joulescope_driver/blob/main/third-party/README.md) libraries are provided under their respective licenses, as recorded in [REUSE.toml](https://github.com/jetperch/joulescope_driver/blob/main/REUSE.toml). The project is compliant with [Reuse Software](https://reuse.software/). ```default python -m pip install reuse[charset-normalizer] python -m reuse lint ``` The reuse tool can generate a software bill of materials (SBOM) in [SPDX format](https://spdx.dev/). ```default python -m reuse spdx ``` Each GitHub release includes this SPDX SBOM as the `joulescope_driver-vX.Y.Z.spdx` asset.