SupernovaController

Summary

Blocking Python API for the Supernova on firmware 3.x. It wraps the Supernova’s asynchronous USB HID protocol so each call waits for its reply.

SupernovaController 2.1.0 supports I2C, I3C (controller and target mode), SPI controller, UART and GPIO.

Prerequisites

Before installing SupernovaController, make sure the system meets these requirements:

Python 3.10 or higher.
Windows, macOS or Linux operating systems.
Binho Supernova USB host adapter running firmware 3.x.
It’s recommended to use a virtual environment for the installation to avoid any conflicts with other Python packages. Create a virtual environment using tools like venv or conda.

Installation

Open a command line interface (CLI).
Navigate to the project directory or the directory to install the SupernovaController in.
Run the following command:
```
pip install supernovacontroller
```

This command will download and install the SupernovaController package along with its dependencies (transfer_controller and BinhoSupernova) from PyPI:

https://pypi.org/project/supernovacontroller/

Getting Started

This example showcases how to use the SupernovaController with a Supernova device using the I3C protocol interface.

Initializing the Supernova Device:

Import and initialize the SupernovaDevice. Optionally, specify the USB HID path if multiple devices are connected:
```
from supernovacontroller.sequential import SupernovaDevice

device = SupernovaDevice()
# Optionally specify the USB HID path
device.open(usb_address='your_usb_hid_path')
```
Call open() without parameters if no particular device needs to be specified.

Creating an I3C Interface:

i3c = device.create_interface("i3c.controller")

Setting Bus Voltage:

This step is required before initializing the bus if the voltage parameter is not specified in init_bus:
```
i3c.set_bus_voltage(3300)
```
Initializing the I3C Bus:

The voltage parameter is optional here if already set via set_bus_voltage:
```
i3c.init_bus()  # Voltage already set, so no need to specify it here
```
If the bus voltage was not set earlier, initialize the bus with the voltage parameter:
```
i3c.init_bus(3300)  # Setting the voltage directly in init_bus
```

Discovering Devices on the Bus:

success, targets = i3c.targets()
if success:
    for target in targets:
        print(f"Found device: {target}")

Reading and Writing to a Target Device:

Replace 0x08 with the dynamic address of the device:

# Write data
i3c.write(0x08, i3c.TransferMode.I3C_SDR, [0x00, 0x00], [0xDE, 0xAD, 0xBE, 0xEF])

# Read data
success, data = i3c.read(0x08, i3c.TransferMode.I3C_SDR, [0x00, 0x00], 4)
if success:
    print(f"Read data: {data}")

Closing the Device:
```
device.close()
```

Examples

After installing the SupernovaController package, try the examples included in the installation. These examples demonstrate practical applications of both I2C and I3C protocols:

Basic I3C Example (basic_i3c_example.py): Learn the basics of I3C bus initialization and device communication.
Basic I2C Example (basic_i2c_example.py): Get started with fundamental I2C operations.
IBI Example (i3c_ibi_example.py): Understand handling In-Band Interrupts (IBI) in I3C.
ICM42605 I3C Example (ICM42605_i3c_example.py): Explore a real-world application of I3C with the ICM42605 sensor.

Accessing the Examples

The examples are installed next to the package, in a separate supernovacontrollerexamples folder in site-packages. To find it:

import os
import sysconfig

examples_path = os.path.join(sysconfig.get_paths()["purelib"], "supernovacontrollerexamples")
print(f"Examples are located in: {examples_path}")

Navigate to this directory to find the example scripts. Run an example directly from this directory using Python. For instance:

python /path/to/examples/basic_i2c_example.py

Replace /path/to/examples/ with the actual path printed in the previous step and basic_i2c_example.py with the name of the example to run.

ICM42605 accelerometer/gyroscope example

Beyond the in-package scripts, the following repository holds a more advanced, standalone example of SupernovaController usage:

https://github.com/binhollc/demo_supernova_icm42605

The “demo_supernova_icm42605” repository offers a Python script for using an ICM42605 sensor with a Supernova host adapter, demonstrating real-time data reading and visualization. Setup requires at least Python 3.10, an ICM42605 sensor, and involves cloning the repo, environment setup, and dependency installation (see README in the repository).

Running the script displays live sensor data plots, as can be seen in the figure shown below: