PPK2 API

0.9.2 · active · verified Fri Apr 17

The ppk2-api is a Python library providing an API for Nordic Semiconductor's Power Profiler Kit II (PPK 2). It enables programmatic control and data acquisition from the PPK 2 device, facilitating power consumption measurements and analysis for embedded development. The current version is 0.9.2, with active development and frequent releases (e.g., v0.9.0, v0.9.1, v0.9.2 in quick succession, aiming for v1.0.0).

Common errors

```
ModuleNotFoundError: No module named 'ppk2_api'
```
cause The `ppk2-api` package has not been installed in the current Python environment.

fix Run `pip install ppk2-api` to install the library.
```
ppk2_api.exceptions.NoPPK2FoundException: No PPK2 device found.
```
cause The `PPK2.discover()` method could not locate a connected Power Profiler Kit II device.

fix Ensure the PPK2 device is physically connected via USB, powered on, and its drivers are correctly installed. Check if another application is already using the device. Try restarting the PPK2 or your computer.
```
serial.serialutil.SerialException: [Errno 13] could not open port /dev/ttyACM0: Permission denied: '/dev/ttyACM0'
```
cause The current user does not have read/write permissions for the serial port associated with the PPK2 device.

fix On Linux, add your user to the `dialout` group: `sudo usermod -a -G dialout $USER`. Then, log out and log back in for the changes to take effect. On Windows/macOS, ensure proper drivers are installed and no conflicting software is running.
```
AttributeError: module 'ppk2_api' has no attribute 'PowerProfiler'
```
cause Attempting to import `PowerProfiler` directly from the top-level `ppk2_api` module.

fix `PowerProfiler` is an example class, not a core API component. If you intend to use the example, import it from `from ppk2_api.examples.power_profiler import PowerProfiler`.

Warnings

breaking The internal concurrency mechanism was changed from `multiprocessing` to `threading` in version 0.9.1. Applications relying on specific process isolation or resource handling behaviors introduced by multiprocessing should review their implementation.
Fix: Review concurrent code that interacts with ppk2-api. Adapt to threading model for internal operations. Consider explicit process management if isolation is critical for your application logic.
gotcha Prior to version 0.9.0, current measurements could be incorrect due to 'incorrect spike filtering'. Data collected with older versions may be unreliable.
Fix: Always use version 0.9.0 or newer for accurate current measurements. Re-run experiments if data was collected using affected versions.
gotcha The `PPK2.discover()` method may raise a `NoPPK2FoundException` if no device is connected or detectable. Ensure the PPK2 device is properly connected and recognized by the operating system.
Fix: Wrap `PPK2.discover()` in a `try...except NoPPK2FoundException` block. Verify the PPK2 is powered on and connected. Check USB drivers and permissions. Ensure no other application is using the device.

Install

pip install ppk2-api Install stable version

Imports

PPK2
```
from ppk2_api import PPK2
```
PPK2_Port
```
from ppk2_api import PPK2_Port
```
PPK2_Mode
```
from ppk2_api import PPK2_Mode
```
PowerProfiler
wrong:
```
from ppk2_api import PowerProfiler
```
correct:
```
from ppk2_api.examples.power_profiler import PowerProfiler
```
PowerProfiler is an example implementation, not a core API class directly available under the main ppk2_api namespace. It resides in the examples subdirectory.

Quickstart

This quickstart demonstrates how to discover a PPK2 device, set it to ampere meter mode, start a measurement, wait for a period, and then stop it. It also shows how to retrieve some sample data. Note that actual data streaming involves more continuous polling with `ppk2.get_data()` in a loop.

from ppk2_api import PPK2, PPK2_Port, PPK2_Mode

def main():
    try:
        # Discover and connect to the PPK2 device
        ppk2 = PPK2.discover()
        print(f"Connected to PPK2: {ppk2.get_device_id()}")

        # Set mode to ampere meter and connect to channel 0
        ppk2.set_mode(PPK2_Mode.AMPERE_METER)
        ppk2.connect_to_port(PPK2_Port.PORT_0)
        ppk2.start_measurement()

        print("Measuring for 5 seconds...")
        # In a real application, you'd typically stream data
        # For simplicity, we'll just wait and then stop.
        # Data streaming would involve a loop and calling ppk2.get_data()
        import time
        time.sleep(5)

        ppk2.stop_measurement()
        print("Measurement stopped.")

        # Example of getting some data (note: real streaming is more complex)
        data = ppk2.get_data(num_samples=1000)
        if data:
            print(f"Average current: {sum(data['current'])/len(data['current']):.2f} mA")
            print(f"Average voltage: {sum(data['voltage'])/len(data['voltage']):.2f} V")
        else:
            print("No data collected or available in this simple example.")

    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        # Ensure the device is properly closed
        if 'ppk2' in locals() and ppk2.is_connected():
            ppk2.close()
            print("PPK2 connection closed.")

if __name__ == "__main__":
    main()

view raw JSON →