# SupernovaController

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

  ```sh
  pip install supernovacontroller
  ```

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

{% embed url="<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 you don't need to specify a particular device.
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 you don't specify the voltage parameter 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 wasn't set earlier, you can 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, 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:

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

```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 you wish to run.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.binho.io/getting-started/python-sdks/supernovacontroller.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.