### Run Example Script from Command Line

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Execute a specific SupernovaController example script directly from your terminal. Replace the path and script name with your actual details.

```sh
python /path/to/supernovacontrollerexamples/basic_i2c_example.py
```

--------------------------------

### Run Example from Python Script

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Import and run a SupernovaController example script from within another Python script. This allows for programmatic execution of examples.

```python
from supernovacontrollerexamples import basic_i2c_example

basic_i2c_example.main()
```

--------------------------------

### Find SupernovaController Examples Directory

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Use this Python code to locate the directory where SupernovaController example scripts are installed. This helps in accessing and running the examples.

```python
import sys
import os

examples_dir_name = "supernovacontrollerexamples"
examples_path = os.path.join(sys.prefix, "lib", "site-packages", examples_dir_name)
print(f"Examples are located in: {examples_path}")
```

--------------------------------

### SupernovaDevice - Open, query, and close a Supernova device

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

The SupernovaDevice class is the primary entry point for interacting with the Binho Supernova device. It handles device connection, metadata retrieval, and provides access to various protocol interfaces. Examples demonstrate opening a device automatically, by USB path, and listing/opening all connected devices.

```APIDOC
## SupernovaDevice

### Description
Provides methods to open, query, and close a Supernova device. It serves as the factory for all protocol interfaces.

### Method
`SupernovaDevice()`

### Parameters
None

### Open a single device (auto-detect)
```python
from supernovacontroller.sequential import SupernovaDevice
from supernovacontroller.errors import DeviceOpenError

device = SupernovaDevice()
try:
    info = device.open()  # Returns dict with hw_version, fw_version, serial_number, etc.
    print(info)
except DeviceOpenError as e:
    print(f"Connection failed: {e}")
    exit(1)
```

### Open a specific device by USB HID path
```python
device = SupernovaDevice()
device.open(usb_address='/dev/hidraw1')
```

### List and open all connected devices
```python
from supernovacontroller.sequential import SupernovaDevice

all_devices = SupernovaDevice.openAllConnectedSupernovaDevices()
for dev in all_devices:
    success, voltages = dev.measure_analog_signal()
    if success:
        print(voltages)
    dev.close()
```

### Close the device
```python
device.close()
```
```

--------------------------------

### Configuring a GPIO Pin

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Configures a GPIO pin with the specified functionality. For example, configuring GPIO pin 6 as a digital output.

```APIDOC
## Configuring a GPIO pin

### Description
Configures a GPIO pin with the specified functionality. For example, configuring GPIO pin 6 as a digital output.

### Method
```python
from BinhoSupernova.commands.definitions import GpioPinNumber, GpioFunctionality

success, response = gpio.configure_pin(GpioPinNumber.GPIO_6, GpioFunctionality.DIGITAL_OUTPUT)
```
```

--------------------------------

### I3C Target Notification Example

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

A sample I3C target notification dictionary, reporting details of the last I3C transaction addressed to the Supernova. This notification excludes CCCs and provides information on transfer type, memory address, length, USB result, manager result, driver result, and transferred data.

```python
{'transfer_type': 'I3C_TARGET_READ', 'memory_address': 7, 'transfer_length': 5, 'usb_result': 'CMD_SUCCESSFUL', 'manager_result': 'I3C_TARGET_TRANSFER_SUCCESS', 'driver_result': ['NO_ERROR'], 'data': [238, 238, 238, 238, 238]}
```

--------------------------------

### SupernovaDevice Initialization and Interface Creation

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Demonstrates how to import, initialize, and open the SupernovaDevice, and then create a UART interface.

```APIDOC
## SupernovaDevice Initialization and Interface Creation

### Description
Imports and initializes the `SupernovaDevice`. Optionally, specifies the USB HID path if multiple devices are connected. Then, creates a UART controller interface.

### Code
```python
from supernovacontroller.sequential import SupernovaDevice

device = SupernovaDevice()
# Optionally specify the USB HID path
device.open(usb_address='your_usb_hid_path')

# Create a UART controller interface
uart = device.create_interface("uart")

# Close the device when done
# device.close()
```
```

--------------------------------

### Disable Interrupt

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Disables an interrupt on a specified GPIO pin. For example, disabling the interrupt on GPIO pin 5.

```APIDOC
## Disable Interrupt

### Description
Disables an interrupt on a GPIO pin. For example, disabling the interrupt on GPIO pin 5.

### Method
```python
success, response = gpio.disable_interrupt(GpioPinNumber.GPIO_5)
```
```

--------------------------------

### Initialize SupernovaDevice

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Imports and initializes the SupernovaDevice. Optionally, specify the USB HID path if multiple devices are connected. Call open() without parameters if you don't need to specify a particular device.

```python
from supernovacontroller.sequential import SupernovaDevice

device = SupernovaDevice()
# Optionally specify the USB HID path
device.open(usb_address='your_usb_hid_path')
```

--------------------------------

### Initializing the Supernova Device

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Imports and initializes the SupernovaDevice. Optionally, specifies the USB HID path if multiple devices are connected. Call open() without parameters if you don't need to specify a particular device.

```APIDOC
## Initializing the Supernova Device

### Description
Imports and initializes the `SupernovaDevice`. Optionally, specifies the USB HID path if multiple devices are connected.

### Method
```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.
```

--------------------------------

### Digital Read

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Reads the digital logic level from a GPIO pin configured as a digital input. For example, reading the value from GPIO pin 5.

```APIDOC
## Digital Read

### Description
Reads the digital logic level from a GPIO pin configured as a digital input. For example, reading the value from GPIO pin 5.

### Method
```python
success, value = gpio.digital_read(GpioPinNumber.GPIO_5)
```
```

--------------------------------

### Open and Manage Supernova Devices

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Demonstrates how to open, query, and close a Supernova device. Includes auto-detection, opening a specific device by USB path, and opening all connected devices. Always ensure to close the device when finished.

```python
from supernovacontroller.sequential import SupernovaDevice
from supernovacontroller.errors import DeviceOpenError, DeviceAlreadyMountedError

# --- Open a single device (auto-detect) ---
device = SupernovaDevice()
try:
    info = device.open()  # Returns dict with hw_version, fw_version, serial_number, etc.
    print(info)
    # {'hw_version': 'HW-C1.0', 'fw_version': '5.0.0', 'serial_number': 'SN123456',
    #  'manufacturer': 'Binho LLC', 'product_name': 'Supernova'}
except DeviceOpenError as e:
    print(f"Connection failed: {e}")
    exit(1)

# --- Open a specific device by USB HID path ---
device2 = SupernovaDevice()
device2.open(usb_address='/dev/hidraw1')

# --- List and open all connected devices ---
all_devices = SupernovaDevice.openAllConnectedSupernovaDevices()
for dev in all_devices:
    success, voltages = dev.measure_analog_signal()
    if success:
        print(voltages)
        # {'i2c_spi_uart_vtarg_mV': 3300, 'i3c_high_voltage_vtarg_mV': 1800,
        #  'i3c_low_voltage_vtarg_mV': 1000}
    dev.close()

# --- Always close when done ---
device.close()
```

--------------------------------

### Digital Write

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Writes a digital logic level to a GPIO pin configured as a digital output. For example, setting GPIO pin 6 to LOW.

```APIDOC
## Digital Write

### Description
Writes a digital logic level to a GPIO pin configured as a digital output. For example, setting GPIO pin 6 to LOW.

### Method
```python
from BinhoSupernova.commands.definitions import GpioLogicLevel

success, response = gpio.digital_write(GpioPinNumber.GPIO_6, GpioLogicLevel.LOW)
```
```

--------------------------------

### SPI Interface Operations

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Demonstrates setting bus voltage, initializing the SPI bus, performing read operations, and modifying parameters at runtime.

```APIDOC
## SPI Interface

### `spi.set_bus_voltage()`

Sets the operating voltage for the SPI bus.

### `spi.init_bus()`

Initializes the SPI bus with specified parameters like bit order, mode, chip select, and frequency.

### `spi.transfer()`

Performs a data transfer (read/write) on the SPI bus. It takes a command list and the total expected length of the response.

### `spi.set_parameters()`

Modifies SPI bus parameters such as frequency and mode at runtime without re-initializing the bus.

### `spi.get_parameters()`

Retrieves the current configuration parameters of the SPI bus.
```

--------------------------------

### Set Interrupt

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Sets an interrupt on a GPIO pin configured as a digital input. For example, setting an interrupt on GPIO pin 5 for both rising and falling edges.

```APIDOC
## Set Interrupt

### Description
Sets an interrupt on a GPIO pin configured as a digital input. For example, setting an interrupt on GPIO pin 5 for both rising and falling edges.

### Method
```python
from BinhoSupernova.commands.definitions import GpioTriggerType

success, response = gpio.set_interrupt(GpioPinNumber.GPIO_5, GpioTriggerType.TRIGGER_BOTH_EDGES)
```
```

--------------------------------

### Initializing the Supernova Device

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Imports and initializes the SupernovaDevice. Optionally, specifies the USB HID path if multiple devices are connected.

```APIDOC
## Initializing the Supernova Device

### Description
Imports and initializes the `SupernovaDevice`. Optionally, specifies the USB HID path if multiple devices are connected.

### Method
```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.
```

--------------------------------

### Read from Supernova Memory

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Retrieves data from the Supernova's internal memory via USB. Provide the starting memory address and the number of bytes to read.

```python
success, data = i3c_target.read_memory(0x0000, 255)
```

--------------------------------

### Initialize Supernova Device

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Imports and initializes the SupernovaDevice. Optionally, specify the USB HID path if multiple devices are connected. Call open() without parameters if you don't need to specify a particular device.

```python
from supernovacontroller.sequential import SupernovaDevice

device = SupernovaDevice()

# Optionally specify the USB HID path
device.open(usb_address='your_usb_hid_path')
```

--------------------------------

### Write to Supernova Memory

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Writes data to the internal memory of the Supernova via USB. Specify the starting memory address and the data to be written as a list of bytes.

```python
success, error = i3c_target.write_memory(0x010A, [0xFF for i in range(0,10)])
```

--------------------------------

### Perform I3C CCCs

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Requests Common Command Codes (CCCs) on the I3C bus, directed to a specific target or broadcast. Examples include GETPID, SETMWL, and GETMWL.

```python
# Send a GETPID CCC specifying the dynamic address.
success, result = i3c_controller.ccc_getpid(0x08)

# Send a SETMWL CCC specifying the dynamic address and maximum write length.
i3c_controller.ccc_unicast_setmwl(0x08, 1024)
# Send a GETMWL CCC specifying the dynamic address
success, result = i3c_controller.ccc_getmwl(0x08)
```

--------------------------------

### Initialize and Discover I3C Devices

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Initialize the I3C bus, run Device Address Assignment (DAA), and discover connected targets. The Supernova automatically enters controller mode. Use `find_target_device_by_pid` to locate specific devices.

```python
from supernovacontroller.sequential import SupernovaDevice

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

# Initialize bus at 1.8 V
success, voltage = i3c.init_bus(1800)
assert success, f"Bus init failed: {voltage}"

# Discover targets
success, targets = i3c.targets()
if success:
    for t in targets:
        print(t)
        # {'static_address': '0x00', 'dynamic_address': '0x08',
        #  'bcr': 6, 'dcr': 196, 'pid': ['0x00', '0x00', '0x00', '0x00', '0x6A', '0x01']}

# Find a specific device by PID
success, device_info = i3c.find_target_device_by_pid(['0x00', '0x00', '0x00', '0x00', '0x6A', '0x01'])
if success:
    dyn_addr = device_info["dynamic_address"]

# Reset bus
i3c.reset_bus()

device.close()
```

--------------------------------

### Creating an I3C Interface

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Creates an I3C controller or target interface using the initialized SupernovaDevice.

```APIDOC
## Creating an I3C Interface

### Description
Creates an I3C controller or target interface using the initialized SupernovaDevice.

### Method
```python
# Creates an I3C controller interface:
i3c_controller = device.create_interface("i3c.controller")

# Or an I3C target interface:
i3c_target = device.create_interface("i3c.target")
```
```

--------------------------------

### Initialize UART Bus with Custom Parameters

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Initializes the Supernova UART peripheral with specified baudrate and parity. Other parameters will use their default values.

```python
success, response = uart.init_bus(baudrate=UartControllerBaudRate.UART_BAUD_115200, parity=UartControllerParity.UART_EVEN_PARITY)
```

--------------------------------

### Initializing the Supernova as an I3C controller

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Initializes the Supernova in I3C controller mode. This is often handled by the open() method by default.

```APIDOC
## Initializing the Supernova as an I3C controller

### Description
Initializes the Supernova in controller mode. By default, the Supernova is initialized by the open() method in controller mode, so it may not be needed to call it in most cases.

### Method
```python
success, status = i3c_controller.controller_init()
```
```

--------------------------------

### Create Protocol Interfaces

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Shows how to obtain interface objects for different protocols (I2C, I3C, SPI, UART, GPIO) from a mounted Supernova device. Calling `create_interface` multiple times for the same protocol returns the same instance.

```python
from supernovacontroller.sequential import SupernovaDevice
from supernovacontroller.errors import DeviceNotMountedError, UnknownInterfaceError

device = SupernovaDevice()
device.open()

i2c           = device.create_interface("i2c")
i3c_ctrl      = device.create_interface("i3c.controller")
i3c_target    = device.create_interface("i3c.target")
spi           = device.create_interface("spi.controller")
uart          = device.create_interface("uart")
gpio          = device.create_interface("gpio")

# Error handling for bad interface name
try:
    bad = device.create_interface("canbus")
except UnknownInterfaceError:
    print("Unknown interface name")

device.close()
```

--------------------------------

### Creating a SPI controller Interface

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Creates a SPI controller interface from an initialized SupernovaDevice.

```APIDOC
## Creating a SPI controller Interface

### Description
Creates a SPI controller interface from an initialized SupernovaDevice.

### Method
```python
spi_controller = device.create_interface("spi.controller")
```
```

--------------------------------

### Creating a GPIO Interface

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Creates a GPIO interface object from the initialized SupernovaDevice.

```APIDOC
## Creates a GPIO interface

### Description
Creates a GPIO interface object from the initialized SupernovaDevice.

### Method
```python
gpio = device.create_interface("gpio")
```
```

--------------------------------

### Initializing the Supernova as a SPI controller

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Initializes the Supernova in SPI controller mode with optional parameters for bit order and frequency.

```APIDOC
## Initializing the Supernova as a SPI controller

### Description
Initializes the Supernova in SPI controller mode. Default values are used if no parameters are specified. Optional parameters include `bit_order` and `frequency`.

### Method
```python
# Initialize with default parameters
success, response = spi_controller.init_bus()

# Initialize with custom parameters
success, response = spi_controller.init_bus(bit_order=SpiControllerBitOrder.LSB, frequency=20000000)
```

Without any parameters, the SPI controller initializes with the default values for bit order (MSB first), mode (Mode 0), chip select (CS0), chip select polarity (Active low) and frequency (10 MHz). Optionally, it is possible to set any of these parameters by specifying in the init_bus function.
```

--------------------------------

### Initialize I3C Controller

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Initializes the Supernova in I3C controller mode. This may not be needed if the device was already opened in controller mode.

```python
success, status = i3c_controller.controller_init()
```

--------------------------------

### Configure I2C Bus Parameters

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Initialize the I2C bus with a specific voltage and set clock frequency. Use `init_bus` for convenience or `set_bus_voltage` followed by `init_bus`. Ensure correct voltage and pull-up resistor settings for your hardware.

```python
from supernovacontroller.sequential import SupernovaDevice
from supernovacontroller.errors import BusVoltageError

device = SupernovaDevice()
device.open()
i2c = device.create_interface("i2c")

# Method 1 – set voltage and init in one call
success, voltage = i2c.init_bus(3300)          # 3.3 V
assert success, f"Bus init failed: {voltage}"

# Method 2 – set voltage separately, then init
success, _ = i2c.set_bus_voltage(1800)         # 1.8 V
success, _ = i2c.init_bus()                    # reuses stored voltage

# Set clock frequency (default 1 MHz)
success, freq = i2c.set_parameters(clock_frequency_hz=400000)
print(f"I2C clock: {freq} Hz")                 # 400000

# Configure pull-up resistors (Rev. C only, default 10 kΩ)
success, ohms = i2c.set_pull_up_resistors(2200)

# Use external power supply
success, ext_mv = i2c.use_external_i2c_power_source()
print(f"External bus voltage: {ext_mv} mV")

# Read back current parameters
success, clock = i2c.get_parameters()
print(clock)                                   # 400000

device.close()
```

--------------------------------

### SPI Controller: Initialization and Transfers

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Initialize the SPI peripheral with specific settings and perform full-duplex transfers. Ensure correct bit order, mode, chip select, polarity, and frequency are configured.

```python
from supernovacontroller.sequential import SupernovaDevice
from BinhoSupernova.commands.definitions import (
    SpiControllerBitOrder, SpiControllerMode,
    SpiControllerChipSelect, SpiControllerChipSelectPolarity,
)

device = SupernovaDevice()
device.open()
spi = device.create_interface("spi.controller")


```

--------------------------------

### Create SPI Controller Interface

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Creates a SPI controller interface from an initialized SupernovaDevice.

```python
spi_controller = device.create_interface("spi.controller")
```

--------------------------------

### Handle Device and Bus Errors with Exceptions

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Demonstrates how to catch specific exceptions raised by SupernovaController for structural errors, such as opening a non-existent device or attempting to open an already mounted device.

```python
from supernovacontroller.sequential import SupernovaDevice
from supernovacontroller.errors import (
    DeviceOpenError,
    DeviceAlreadyMountedError,
    DeviceNotMountedError,
    UnknownInterfaceError,
    BusVoltageError,
    BusNotInitializedError,
    BackendError,
)

device = SupernovaDevice()

# DeviceOpenError – bad USB path or device not connected
try:
    device.open(usb_address='/dev/nonexistent')
except DeviceOpenError as e:
    print(f"Cannot open device: {e}")
```

```python
# DeviceAlreadyMountedError – calling open() twice
device2 = SupernovaDevice()
device2.open()
try:
    device2.open()
except DeviceAlreadyMountedError:
    print("Already open")
```

--------------------------------

### Initialize UART Bus with Default Parameters

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Initializes the Supernova UART peripheral with default parameters: 9600bps baudrate, no parity, 8-bit data size, one stop bit, and no hardware handshake.

```python
success, response = uart.init_bus()
```

--------------------------------

### Initializing the Supernova as an I3C target

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Initializes the Supernova in target mode with specified memory layout, maximum read/write lengths, IBI timing, and target behavior flags.

```APIDOC
## Initializing the Supernova as an I3C target

### Description
Initializes the Supernova in target mode and sets its initial configuration which includes the internal memory layout, its maximum write length, maximum read length, seconds waited to allow an In-Band Interrupt (IBI) to drive SDA low when the controller is not doing so and some flags regarding the target behaviour in the I3C bus.

### Method
```python
success, status = i3c_target.target_init(I3cTargetMemoryLayout_t.MEM_1_BYTE, 0x69, 0x100, 0x100, TARGET_CONF)
```

### Parameters
- **memory layout**: `I3cTargetMemoryLayout_t` (MEM_1_BYTE, MEM_2_BYTES, or MEM_4_BYTES)
- **uSeconds to wait for IBI**: integer
- **Maximum Read Length (MRL)**: integer
- **Maximum Write Length (MWL)**: integer
- **Configuration flags**: `TARGET_CONF` (bitmask)
```

--------------------------------

### Initialize and Transfer Data via SPI

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Initializes the SPI bus with specified parameters and performs a read operation. Ensure the bus voltage is set before initialization.

```python
spi.set_bus_voltage(3300)
success, result = spi.init_bus(
    bit_order=SpiControllerBitOrder.MSB,
    mode=SpiControllerMode.MODE_0,
    chip_select=SpiControllerChipSelect.CHIP_SELECT_0,
    chip_select_pol=SpiControllerChipSelectPolarity.ACTIVE_LOW,
    frequency=20_000_000,   # 20 MHz
)
assert success, result
```

```python
# Read 6 bytes from SPI memory at address 0x000002 (opcode 0x03)
cmd   = [0x03, 0x00, 0x00, 0x02]    # READ opcode + 3-byte address
read_length = 6
success, response = spi.transfer(cmd, len(cmd) + read_length)
if success:
    data_from_target = response[len(cmd):]
    print(data_from_target)  # [0xFA, 0xFB, 0xFC, 0xFD, 0xFE, 0xFF]
```

--------------------------------

### Subscribe to Hardware Notifications

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Demonstrates how to register a notification handler for hardware events like GPIO interrupts. Requires setting up pins, configuring interrupts, and using threading Events for synchronization. Ensure to disable interrupts when done.

```python
from threading import Event
from supernovacontroller.sequential import SupernovaDevice
from BinhoSupernova.commands.definitions import GpioPinNumber, GpioFunctionality, GpioTriggerType, GpioLogicLevel

device = SupernovaDevice()
device.open()
gpio = device.create_interface("gpio")

gpio_event = Event()

def is_gpio_interrupt(name, message):
    return message['name'].strip() == "GPIO INTERRUPTION"

def handle_gpio_interrupt(name, message):
    print(f"GPIO interrupt received: {message}")
    gpio_event.set()

device.on_notification(
    name="GPIO INTERRUPTION",
    filter_func=is_gpio_interrupt,
    handler_func=handle_gpio_interrupt
)

gpio.set_pins_voltage(3300)
gpio.configure_pin(GpioPinNumber.GPIO_5, GpioFunctionality.DIGITAL_INPUT)
gpio.configure_pin(GpioPinNumber.GPIO_6, GpioFunctionality.DIGITAL_OUTPUT)
gpio.set_interrupt(GpioPinNumber.GPIO_5, GpioTriggerType.TRIGGER_BOTH_EDGES)

# Toggle GPIO_6 and wait for the interrupt on GPIO_5
gpio.digital_write(GpioPinNumber.GPIO_6, GpioLogicLevel.HIGH)
gpio_event.wait(timeout=5.0)
gpio_event.clear()
gpio.digital_write(GpioPinNumber.GPIO_6, GpioLogicLevel.LOW)
gpio_event.wait(timeout=5.0)

gpio.disable_interrupt(GpioPinNumber.GPIO_5)
device.close()
```

--------------------------------

### Initializing the UART Bus

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Initializes the Supernova UART peripheral with default or custom parameters.

```APIDOC
## Initializing the Supernova UART peripheral

### Description
Initializes the Supernova UART peripheral. If no parameters are specified, it uses default values (9600bps, no parity, 8-bit data, one stop bit, no hardware handshake). Custom parameters can be provided.

### Method
`uart.init_bus(baudrate, parity, data_size, stop_bit, hardware_handshake)`

### Parameters
- **baudrate** (UartControllerBaudRate) - Optional - The desired baud rate.
- **parity** (UartControllerParity) - Optional - The desired parity setting.
- **data_size** (UartControllerDataSize) - Optional - The desired data size (bits).
- **stop_bit** (UartControllerStopBit) - Optional - The desired number of stop bits.
- **hardware_handshake** (UartControllerHandshake) - Optional - The desired hardware handshake setting.

### Request Example (Default)
```python
success, response = uart.init_bus()
```

### Request Example (Custom)
```python
success, response = uart.init_bus(baudrate=UartControllerBaudRate.UART_BAUD_115200, parity=UartControllerParity.UART_EVEN_PARITY)
```
```

--------------------------------

### Open All Connected Supernova Devices

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Opens all connected Supernova devices and returns a list of `SupernovaDevice` instances.

```APIDOC
## Open All Connected Supernova Devices

### Description
Opens all connected Supernova devices and returns a list of `SupernovaDevice` instances.

### Method
`openAllConnectedSupernovaDevices()`

### Parameters
None

### Request Example
```python
from supernovacontroller.sequential import SupernovaDevice

devices = SupernovaDevice.openAllConnectedSupernovaDevices()
for device in devices:
    print("Opened device with the following info:")
    print(device.open())  # Prints device information
    device.close()  # Close the device when done
```

### Response
#### Success Response (List of SupernovaDevice instances)
- A list where each element is an instance of `SupernovaDevice` representing a connected device.

#### Response Example
```python
# Example output when iterating through the returned list and calling device.open()
# [
#   {'serial_number': 'SN123456789', 'path': '/dev/hidraw0'},
#   {'serial_number': 'SN987654321', 'path': '/dev/hidraw1'}
# ]
```
```

--------------------------------

### I3C Bus Initialization and Discovery

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Initializes the I3C bus using Dynamic Address Assignment (DAA) and discovers connected target devices.

```APIDOC
## i3c_ctrl.init_bus() / i3c_ctrl.targets() — Initialize and discover I3C devices

### Description
Initializes the I3C bus by running the Dynamic Address Assignment (DAA) process and returns a list of discovered target devices. The Supernova device is automatically configured in controller mode upon calling `create_interface("i3c.controller")`.

### Method
- `init_bus(voltage: int)`: Initializes the I3C bus with the specified voltage in mV. Returns a success status and the actual voltage set.
- `targets()`: Discovers and returns a list of all I3C target devices on the bus. Returns a success status and a list of device dictionaries.
- `find_target_device_by_pid(pid: list[str])`: Finds a specific I3C target device by its Product ID (PID). Returns a success status and the device information dictionary.
- `reset_bus()`: Resets the I3C bus.

### Parameters
- **voltage** (int): The bus voltage in millivolts (mV).
- **pid** (list[str]): A list of strings representing the Product ID (PID) of the target device to find.

### Request Example
```python
from supernovacontroller.sequential import SupernovaDevice

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

# Initialize bus at 1.8 V
success, voltage = i3c.init_bus(1800)
assert success, f"Bus init failed: {voltage}"

# Discover targets
success, targets = i3c.targets()
if success:
    for t in targets:
        print(t)
        # {'static_address': '0x00', 'dynamic_address': '0x08',
        #  'bcr': 6, 'dcr': 196, 'pid': ['0x00', '0x00', '0x00', '0x00', '0x6A', '0x01']}

# Find a specific device by PID
success, device_info = i3c.find_target_device_by_pid(['0x00', '0x00', '0x00', '0x00', '0x6A', '0x01'])
if success:
    dyn_addr = device_info["dynamic_address"]

# Reset bus
i3c.reset_bus()

device.close()
```
```

--------------------------------

### Create GPIO Interface

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Creates a GPIO interface object from the initialized Supernova device.

```python
gpio = device.create_interface("gpio")
```

--------------------------------

### Initialize Supernova as I3C Target

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Initializes the Supernova in target mode with specific configurations for memory layout, IBI wait time, Maximum Read Length (MRL), Maximum Write Length (MWL), and target behavior flags. Ensure the memory layout constants are correctly chosen.

```python
TARGET_CONF                 = I3cOffline.OFFLINE_UNFIT.value |  \
                                  PartNOrandom.PART_NUMB_DEFINED.value |  \
                                  DdrOk.ALLOWED_DDR.value |  \
                                  IgnoreTE0TE1Errors.IGNORE_ERRORS.value |  \
                                  MatchStartStop.NOT_MATCH.value |  \
                                  AlwaysNack.NOT_ALWAYS_NACK.value    

# Init Supernova in target mode specifying:
# memory layout, uSeconds to wait for IBI, MRL, MWL and configuration.
success, status = i3c_target.target_init(I3cTargetMemoryLayout_t.MEM_1_BYTE, 0x69, 0x100, 0x100, TARGET_CONF)
```

--------------------------------

### Initializing the I3C Bus

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Initializes the I3C bus. The voltage parameter is optional if already set via set_bus_voltage.

```APIDOC
## Initializing the I3C Bus

### Description
Initializes the I3C bus. The voltage parameter is optional here if already set via `set_bus_voltage`.

### Method
```python
# Voltage already set, so no need to specify it here
success, data = i3c_controller.init_bus()

# Setting the voltage directly in init_bus
success, data = i3c_controller.init_bus(3300)
```
```

--------------------------------

### Open All Connected Supernova Devices

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Opens all connected Supernova devices and returns a list of SupernovaDevice instances. Each device is then closed after printing its information.

```python
from supernovacontroller.sequential import SupernovaDevice

devices = SupernovaDevice.openAllConnectedSupernovaDevices()
for device in devices:
    print("Opened device with the following info:")
    print(device.open())  # Prints device information
    device.close()  # Close the device when done
```

--------------------------------

### Initialize SPI Bus

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Initializes the Supernova in SPI controller mode with default parameters. Default values include MSB first bit order, Mode 0, CS0 chip select, active low chip select polarity, and 10 MHz frequency. Custom parameters can be specified.

```python
success, response = spi_controller.init_bus()
```

```python
success, response = spi_controller.init_bus(bit_order=SpiControllerBitOrder.LSB, frequency=20000000)
```

--------------------------------

### I3C Target: Initialization and Memory Operations

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Initialize the Supernova as an I3C target with custom memory layout and features. Use `write_memory` and `read_memory` for direct USB access to emulated memory.

```python
from supernovacontroller.sequential import SupernovaDevice
from BinhoSupernova.commands.definitions import (
    I3cTargetMemoryLayout_t, I3cOffline, PartNOrandom, DdrOk,
    IgnoreTE0TE1Errors, MatchStartStop, AlwaysNack,
    I3cTargetMaxDataSpeedLimit_t, I3cTargetIbiCapable_t, I3cTargetIbiPayload_t,
    I3cTargetOfflineCap_t, I3cTargetVirtSupport_t, I3cTargetDeviceRole_t,
    I3cTargetDcr_t,
)

device = SupernovaDevice()
device.open()
i3c_t = device.create_interface("i3c.target")

# Build feature flags
TARGET_CONF = (
    I3cOffline.OFFLINE_UNFIT.value |
    PartNOrandom.PART_NUMB_DEFINED.value |
    DdrOk.ALLOWED_DDR.value |
    IgnoreTE0TE1Errors.IGNORE_ERRORS.value |
    MatchStartStop.NOT_MATCH.value |
    AlwaysNack.NOT_ALWAYS_NACK.value
)

# Initialize as target: 1-byte memory layout, MRL=MWL=256 bytes
success, status = i3c_t.target_init(
    I3cTargetMemoryLayout_t.MEM_1_BYTE,
    useconds_to_wait_for_ibi=0x69,
    max_read_length=0x100,
    max_write_length=0x100,
    features=TARGET_CONF
)
assert success, status

# Set identity registers
i3c_t.set_pid([0x07, 0x06, 0x05, 0x04, 0x03, 0x02])
i3c_t.set_bcr(
    I3cTargetMaxDataSpeedLimit_t.MAX_DATA_SPEED_LIMIT,
    I3cTargetIbiCapable_t.NOT_IBI_CAPABLE,
    I3cTargetIbiPayload_t.IBI_WITH_PAYLOAD,
    I3cTargetOfflineCap_t.OFFLINE_CAPABLE,
    I3cTargetVirtSupport_t.VIRTUAL_TARGET_SUPPORT,
    I3cTargetDeviceRole_t.I3C_TARGET,
)
i3c_t.set_dcr(I3cTargetDcr_t.I3C_TARGET_MEMORY)
i3c_t.set_static_address(0x73)

# Write to internal memory via USB
success, err = i3c_t.write_memory(0x0010, [0xFF] * 16)
print(success)  # True

# Read internal memory via USB
success, data = i3c_t.read_memory(0x0010, 16)
print(data)     # [0xFF, 0xFF, ..., 0xFF]

# Wait for an I3C controller to read/write (blocks until timeout)
success, notification = i3c_t.wait_for_notification(timeout=10.0)
if success:
    print(notification)
    # {'transfer_type': 'I3C_TARGET_READ', 'memory_address': 16,
    #  'transfer_length': 4, 'usb_result': 'CMD_SUCCESSFUL',
    #  'manager_result': 'I3C_TARGET_TRANSFER_SUCCESS',
    #  'driver_result': ['NO_ERROR'], 'data': [255, 255, 255, 255]}

device.close()
```

--------------------------------

### Initialize and Configure UART Communication

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Initializes the UART bus with custom parameters including baud rate, parity, data size, and stop bits. The bus voltage must be set prior to initialization.

```python
uart.set_bus_voltage(3300)

# Initialize with custom parameters
success, result = uart.init_bus(
    baudrate=UartControllerBaudRate.UART_BAUD_115200,
    parity=UartControllerParity.UART_NO_PARITY,
    data_size=UartControllerDataSize.UART_8BIT_BYTE,
    stop_bit=UartControllerStopBit.UART_ONE_STOP_BIT,
)
assert success, result
```

--------------------------------

### SupernovaDevice.create_interface() - Obtain a protocol interface

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

This method creates and returns an interface object for a specified protocol (e.g., 'i2c', 'spi.controller', 'uart'). It ensures that only one instance of each interface is created per device.

```APIDOC
## SupernovaDevice.create_interface()

### Description
Obtains a protocol interface object for the specified protocol name. Returns a singleton instance for each interface type.

### Method
`device.create_interface(interface_name: str)`

### Parameters
*   **interface_name** (str) - Required - The name of the protocol interface to create (e.g., "i2c", "spi.controller", "uart", "gpio", "i3c.controller", "i3c.target").

### Request Example
```python
from supernovacontroller.sequential import SupernovaDevice
from supernovacontroller.errors import UnknownInterfaceError

device = SupernovaDevice()
device.open()

i2c = device.create_interface("i2c")
spi = device.create_interface("spi.controller")

try:
    bad_interface = device.create_interface("canbus")
except UnknownInterfaceError:
    print("Unknown interface name")

device.close()
```

### Response
Returns the requested interface object (e.g., I2C, SPI, UART, GPIO).

### Error Handling
*   `UnknownInterfaceError`: Raised if the provided `interface_name` is not recognized.
```

--------------------------------

### Handle DeviceNotMountedError before open()

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Catch DeviceNotMountedError if attempting to create an interface before calling device.open(). Always open the device before creating interfaces.

```python
device3 = SupernovaDevice()
try:
    device3.create_interface("i2c")
except DeviceNotMountedError:
    print("Call device.open() first")
```

--------------------------------

### Initialize I3C Bus

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Initializes the I3C bus. The voltage parameter is optional if already set via set_bus_voltage. Alternatively, voltage can be set directly in this call.

```python
success, data = i3c_controller.init_bus()  # Voltage already set, so no need to specify it here
```

```python
success, data = i3c_controller.init_bus(3300)  # Setting the voltage directly in init_bus
```

--------------------------------

### SPI Controller Interface

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Provides functionality to initialize and perform data transfers using the SPI peripheral.

```APIDOC
## SPI Controller Interface

### `spi.init_bus()` / `spi.transfer()` — SPI controller transfers

### Description
Initializes the SPI peripheral with bit order, mode, chip select, polarity, and frequency, then performs full-duplex transfers of up to 1024 bytes.

### Methods
- `init_bus(bit_order, mode, chip_select, polarity, frequency)`: Initializes the SPI bus.
- `transfer(data)`: Performs a full-duplex SPI transfer.

### Parameters
- **bit_order** (`SpiControllerBitOrder`): The bit order for SPI communication (e.g., `MSB_FIRST`).
- **mode** (`SpiControllerMode`): The SPI mode (e.g., `MODE_0`).
- **chip_select** (`SpiControllerChipSelect`): The chip select line to use.
- **polarity** (`SpiControllerChipSelectPolarity`): The polarity of the chip select signal.
- **frequency** (int): The SPI clock frequency in Hz.
- **data** (list[int]): A list of bytes to send during the transfer. The length of the data determines the number of bytes transferred.

### Request Example
```python
from supernovacontroller.sequential import SupernovaDevice
from BinhoSupernova.commands.definitions import (
    SpiControllerBitOrder, SpiControllerMode,
    SpiControllerChipSelect, SpiControllerChipSelectPolarity,
)

device = SupernovaDevice()
device.open()
spi = device.create_interface("spi.controller")

# Example usage (assuming initialization parameters are defined elsewhere)
# spi.init_bus(SpiControllerBitOrder.MSB_FIRST, SpiControllerMode.MODE_0, SpiControllerChipSelect.CS_0, SpiControllerChipSelectPolarity.ACTIVE_LOW, 1000000)
# data_to_send = [0x01, 0x02, 0x03]
# read_data = spi.transfer(data_to_send)

# device.close()
```
```

--------------------------------

### SupernovaDevice.on_notification() - Subscribe to asynchronous hardware notifications

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Allows subscribing to asynchronous hardware notifications such as GPIO interrupts, I3C IBIs, or UART receive events. It requires a name, a filter function to identify relevant messages, and a handler function to process them.

```APIDOC
## SupernovaDevice.on_notification()

### Description
Registers a handler for asynchronous hardware notifications. This is used for events like GPIO interrupts, I3C IBIs, and UART receive events.

### Method
`device.on_notification(name: str, filter_func: callable, handler_func: callable)`

### Parameters
*   **name** (str) - Required - A unique name for this notification subscription.
*   **filter_func** (callable) - Required - A function that takes `name` and `message` and returns `True` if the message should be handled.
*   **handler_func** (callable) - Required - A function that takes `name` and `message` and is executed when a filtered message is received.

### Request Example
```python
from threading import Event
from supernovacontroller.sequential import SupernovaDevice
from BinhoSupernova.commands.definitions import GpioPinNumber, GpioFunctionality, GpioTriggerType, GpioLogicLevel

device = SupernovaDevice()
device.open()
gpio = device.create_interface("gpio")

gpio_event = Event()

def is_gpio_interrupt(name, message):
    return message['name'].strip() == "GPIO INTERRUPTION"

def handle_gpio_interrupt(name, message):
    print(f"GPIO interrupt received: {message}")
    gpio_event.set()

device.on_notification(
    name="GPIO INTERRUPTION",
    filter_func=is_gpio_interrupt,
    handler_func=handle_gpio_interrupt
)

gpio.set_pins_voltage(3300)
gpio.configure_pin(GpioPinNumber.GPIO_5, GpioFunctionality.DIGITAL_INPUT)
gpio.configure_pin(GpioPinNumber.GPIO_6, GpioFunctionality.DIGITAL_OUTPUT)
gpio.set_interrupt(GpioPinNumber.GPIO_5, GpioTriggerType.TRIGGER_BOTH_EDGES)

# Example usage: Toggle GPIO_6 and wait for interrupt on GPIO_5
gpio.digital_write(GpioPinNumber.GPIO_6, GpioLogicLevel.HIGH)
gpio_event.wait(timeout=5.0)
gpio_event.clear()
gpio.digital_write(GpioPinNumber.GPIO_6, GpioLogicLevel.LOW)
gpio_event.wait(timeout=5.0)

gpio.disable_interrupt(GpioPinNumber.GPIO_5)
device.close()
```

### Response
None. This method registers a callback.

### Error Handling
Exceptions may be raised for underlying communication or hardware issues.
```

--------------------------------

### Handle BusVoltageError during init_bus

Source: https://context7.com/binhollc/supernovacontroller/llms.txt

Catch BusVoltageError if init_bus is called before setting the bus voltage. Ensure bus voltage is set prior to initialization.

```python
try:
    i2c.init_bus()   # no voltage set yet
except BusVoltageError:
    print("Set bus voltage first")
```

--------------------------------

### Reading and Writing to a Device

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Performs I3C write and read operations on a target device using SDR mode.

```APIDOC
## Reading and Writing to a Device

### Description
Performs I3C write and read operations on a target device.

### Method
```python
# Write data specifying address, mode, register and a list of bytes.
i3c_controller.write(0x08, i3c_controller.TransferMode.I3C_SDR, [0x00, 0x00], [0xDE, 0xAD, 0xBE, 0xEF])

# Read data specifying address, mode, register and buffer length.
success, data = i3c_controller.read(0x08, i3c_controller.TransferMode.I3C_SDR, [0x00, 0x00], 4)
if success:
    print(f"Read data: {data}")
```

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

--------------------------------

### Set Supernova configuration

Source: https://github.com/binhollc/supernovacontroller/blob/main/README.md

Configures the Supernova's operational parameters including memory layout, read/write lengths, IBI timing, and target behavior flags.

```APIDOC
## Set Supernova configuration

### Description
Sets the configuration of the Supernova such as its maximum write length, maximum read length, seconds waited to allow an In-Band Interrupt (IBI) to drive SDA low when the controller is not doing so and some flags regarding the target behaviour in the I3C bus.

### Method
```python
success, status = i3c_target.set_configuration(0x69, 0x300, 0x250, TARGET_CONF)
```

### Parameters
- **uSeconds to wait for IBI**: integer
- **Maximum Read Length (MRL)**: integer
- **Maximum Write Length (MWL)**: integer
- **Configuration flags**: `TARGET_CONF` (bitmask)
```