SupernovaController

Python SDK for the Binho Supernova Host Adapter

Summary

SupernovaController is a Python-based tool designed to interface with the Supernova host-adapter USB HID device. Offering a blocking API, it simplifies command sequences and interactions in the context of asynchronous operation environments like the one offered by the Supernova host-adapter. This approach enhances usability and efficiency, providing a streamlined experience for developers working with the Supernova device.

The SupernovaController currently supports I2C and I3C protocols, allowing effortless communication with I2C and I3C devices as the host adapter acts as a controller device. In the near future, we are excited to announce that the SupernovaController will also support I3C Target mode, further expanding its capabilities and offering more versatile communication options for developers.

Prerequisites

Before installing and using the SupernovaSDK, please ensure your system meets the following requirements:

• Python 3.5 or higher.

• Windows, MacOS or Linux operating systems.

• Binho Supernova USB host adapter with up-to-date firmware.

• It's recommended to use a virtual environment for the installation to avoid any conflicts with other Python packages. You can create a virtual environment using tools like venv or conda.

Installation

• Open your command line interface (CLI).

• Navigate to your project directory or the directory where you want to install the SupernovaController.

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

supernovacontrollerPyPI

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:

   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 you don't need to specify a particular device.

2. Creating an I3C Interface:

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

3. Setting Bus Voltage:

   This step is required before initializing the bus if you don't specify the voltage parameter in init_bus:

   i3c.set_bus_voltage(3300)

4. 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 wasn't set earlier, you can initialize the bus with the voltage parameter:

   i3c.init_bus(3300)  # Setting the voltage directly in init_bus

5. Discovering Devices on the Bus:

   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:

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

   device.close()

Examples

After installing the SupernovaController package, you can further explore its capabilities by trying out 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 (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

To access the examples, you first need to find the installation directory of the SupernovaController package. This can be done using the following Python commands:

import supernovacontroller
import os

examples_path = os.path.join(supernovacontroller.__path__[0], 'examples')
print(f"Examples are located in: {examples_path}")

Navigate to this directory to find the example scripts. You can 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 you wish to run.