> Complete documentation index: [llms.txt](/llms.txt). Markdown versions of all pages are available by appending `.md` to page URLs.

# SupernovaController

> Legacy: Python SDK for the Binho Supernova Host Adapter.

:::caution
**Legacy:** SupernovaController only supports Supernova firmware 3.x. For firmware 4.x, and for the Pulsar, use [PyCosmicSDK](/software/pycosmicsdk/). Existing SupernovaController scripts run on PyCosmicSDK with a changed import: see [Migrating to PyCosmicSDK](/software/pycosmicsdk/migrating-to-pycosmicsdk/). New projects should start with [CosmicSDK](/software/cosmicsdk/) or PyCosmicSDK.

:::

## 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:

    ```sh
    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/](https://pypi.org/project/supernovacontroller/)

## Getting Started

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

1.  **Initializing the Supernova Device:**

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

    ```python
    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.
2.  **Creating an I3C Interface:**

    ```python
    i3c = device.create_interface("i3c.controller")
    ```
3.  **Setting Bus Voltage:**

    This step is required before initializing the bus if the voltage parameter is not specified in `init_bus`:

    ```python
    i3c.set_bus_voltage(3300)
    ```
4.  **Initializing the I3C Bus:**

    The voltage parameter is optional here if already set via `set_bus_voltage`:

    ```python
    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:

    ```python
    i3c.init_bus(3300)  # Setting the voltage directly in init_bus
    ```
5.  **Discovering Devices on the Bus:**

    ```python
    success, targets = i3c.targets()
    if success:
        for target in targets:
            print(f"Found device: {target}")
    ```
6.  **Reading and Writing to a Target Device:**

    Replace `0x08` with the dynamic address of the device:

    ```python
    # 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}")
    ```
7.  **Closing the Device:**

    ```python
    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:

```python
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:

```sh
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](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:

<figure><img src="/files/287535620-107e83d5-790f-44d2-81d0-73047f33b08d.png" alt=""><figcaption><p>Plot showing Accelerometer and Gyroscope real-time data</p></figcaption></figure>