I3CBlaster

https://github.com/xyphro/i3cblaster
Admin
I3CBlaster is a firmware for Raspberry Pi Pico and Seeed Xiao RP2040 boards, transforming them into...
Tokens:17,817
Snippets:54
Trust Score:7.3
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### CMake Project Setup

Source: https://github.com/xyphro/i3cblaster/blob/main/src/CMakeLists.txt

Initializes the CMake build system for the project. Sets the minimum required CMake version and the build type to 'Release'.

```cmake
cmake_minimum_required(VERSION 3.13)

set(CMAKE_BUILD_TYPE "Release")

include(pico_sdk_import.cmake)

project(myproject_test C CXX ASM)
set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)
```

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

### Complete Python Example for I3C Operations

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Demonstrates a full workflow for I3C operations using the i3cblaster Python library. This includes discovering devices, configuring the bus, scanning and assigning addresses, and performing SDR and HDR-DDR data transfers. It requires the 'i3cblaster' library to be installed.

```python
import i3cblaster

def main():
    # Discover devices
    devices = i3cblaster.listdevices()
    print(f"Found {len(devices)} I3CBlaster device(s)")

    if len(devices) == 0:
        print("No devices found. Connect I3CBlaster and try again.")
        return

    # Connect to device
    i3c = i3cblaster.i3cblaster()

    # Configure bus
    i3c.i3c_clk(12500)  # 12.5 MHz
    i3c.i3c_drivestrength(4)  # 4mA drive strength

    # Reset previous address assignments
    i3c.i3c_rstdaa()

    # Scan for devices
    print("Scanning I3C bus...")
    addresses = i3c.i3c_scan()
    print(f"Found devices: {[hex(addr) for addr in addresses]}")

    # Assign dynamic address
    print("Assigning dynamic address 0x30...")
    device_info = i3c.i3c_entdaa(0x30)
    if device_info:
        print(f"Device info: {[hex(x) for x in device_info]}")

    # Verify assignment
    addresses = i3c.i3c_scan()
    print(f"Active addresses: {[hex(addr) for addr in addresses]}")

    # Perform SDR transfers
    print("\nSDR Operations:")
    target = 0x30

    # Write operation
    i3c.i3c_sdr_write(target, [0x10, 0x20, 0x30])
    print("Write completed")

    # Read operation
    data = i3c.i3c_sdr_read(target, 8)
    print(f"Read data: {[hex(x) for x in data]}")

    # Write-read operation (register access)
    reg_data = i3c.i3c_sdr_writeread(target, [0x00], 10)
    print(f"Register data: {[hex(x) for x in reg_data]}")

    # HDR-DDR operations
    print("\nHDR-DDR Operations:")
    i3c.i3c_ddr_config(True, False, False)  # V1.0 target config

    # DDR write
    i3c.i3c_ddr_write(target, 0x00, [0x1234, 0x5678])
    print("DDR write completed")

    # DDR read
    ddr_data = i3c.i3c_ddr_read(target, 0x00, 10)
    print(f"DDR read: {[hex(x) for x in ddr_data]}")

    # DDR write-read
    result = i3c.i3c_ddr_writeread(target, 0x00, 0x01, [0xABCD], 5)
    print(f"DDR write-read: {result[0]} words written, {len(result[1])} words read")

    print("\nAll operations completed successfully")

if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        print(f"Error: {e}")

```

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

### Python I3CBlaster API Example

Source: https://github.com/xyphro/i3cblaster/blob/main/README.md

This Python code demonstrates the usage of the i3cblaster module for interacting with I3C devices. It covers listing devices, scanning the bus, assigning dynamic addresses, performing SDR and DDR read/write operations, and setting drive strength. The module handles COM port identification automatically.

```python
import i3cblaster

# list available and connected i3c blaster devices:
devices = i3cblaster.listdevices() # this returns an array with serial numbers of connected i3cblaster devices
print(len(devices), ' i3cblaster devices connected:', devices)

if len(devices) > 0:
    i3c = i3cblaster.i3cblaster() # in case multiple devices are connected you can provide the serial number here as a parameter
    
    print('resetting dynamic addresses previously assigned')
    i3c.i3c_rstdaa()

    print('scanning for available i3c devices')
    targets = i3c.i3c_scan()
    print('found target devices on bus:', targets)
    
    print('assign a dynamic address - this only works for i3c devices supporting it, but will not cause issues')
    i3c.i3c_entdaa(0x30)
    
    print('scanning for available i3c devices')
    targets = i3c.i3c_scan()
    print('found target devices on bus:', targets)
    
    print('reading up to 10 bytes from subregister 0x00:')
    data = i3c.i3c_sdr_writeread(0x30, [0x00], 10)
    print('result: ', data)

    print('Setting controllers SDA/SCL drivestrength to 4mA')
    data = i3c.i3c_drivestrength(4)
    print('result: ', data)
    
    print('Executing a HDR-DDR Write')
    i3c.i3c_ddr_write(0x30, 0x00, [0x1234, 0x5678])

    print('Executing a HDR-DDR Read')
    data = i3c.i3c_ddr_read(0x30, 0x00, 10)
    print('result: ', data)

    print('Executing a HDR-DDR Write followed by read')
    data = i3c.i3c_ddr_writeread(0x30, 0x00, 0x00, [0x1234, 0x5678], 10)
    print('result: ', data)

```

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

### Pico SDK Initialization and Executable Definition

Source: https://github.com/xyphro/i3cblaster/blob/main/src/CMakeLists.txt

Configures the Pico SDK and defines the main executable for the i3cblaster project. It specifies source files and PIO headers required for the build.

```cmake
set(PICO_SDK_FETCH_FROM_GIT)

pico_sdk_init()

add_executable(i3cblaster
	main.c
	i3c_hl.c
	ucli.c
	XiaoNeoPixel.c
	)

pico_generate_pio_header(i3cblaster ${CMAKE_CURRENT_LIST_DIR}/i3c.pio)
```

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

### Initialize I3CBlaster Connection (Python)

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Creates an I3CBlaster instance and establishes a connection to the hardware. It supports connecting to the first available device or a specific device via its serial number, with automatic COM port detection.

```python
import i3cblaster

# Connect to the first available device
i3c = i3cblaster.i3cblaster()

# Or connect to a specific device by serial number
devices = i3cblaster.listdevices()
if len(devices) > 0:
    i3c = i3cblaster.i3cblaster(serialnumber=devices[0])
    print("Connected to I3CBlaster")
else:
    print("No I3CBlaster devices found")

# The connection is established automatically with COM port auto-detection
# No need to manually specify port numbers
```

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

### Library Linking and Extra Outputs

Source: https://github.com/xyphro/i3cblaster/blob/main/src/CMakeLists.txt

Links the necessary libraries for the i3cblaster executable and configures extra build outputs. This ensures all required hardware and SDK components are included.

```cmake
target_link_libraries(i3cblaster pico_stdlib hardware_pio  hardware_adc hardware_i2c)

pico_add_extra_outputs(i3cblaster)
```

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

### Standard I/O Configuration

Source: https://github.com/xyphro/i3cblaster/blob/main/src/CMakeLists.txt

Enables standard input/output for the i3cblaster executable. Specifically, it enables USB stdio and disables UART stdio.

```cmake
pico_enable_stdio_usb(i3cblaster 1)
pico_enable_stdio_uart(i3cblaster 0)
```

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

### I3Cblaster Commands API

Source: https://github.com/xyphro/i3cblaster/blob/main/README.md

This section provides documentation for each I3Cblaster command. Each command has a specific function related to I3C bus operations or general system information.

```APIDOC
## HELP

### Description
Lists all available commands or provides detailed information about a specific command. Usage: `help` or `help [command_name]`.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
help i3c_clk
```

### Response
#### Success Response (200)
- **Output** (string) - Help information for the specified command or a list of all commands.

#### Response Example
```plaintext
Set I3C clock frequency
```
```

```APIDOC
## GPIO_WRITE

### Description
Sets the state and direction of a GPIO pin.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
gpio_write <pin_number> <state> <direction>
```

### Response
#### Success Response (200)
- **Status** (string) - "OK(0)" indicating success.

#### Response Example
```plaintext
OK(0)
```
```

```APIDOC
## GPIO_READ

### Description
Gets the current state of GPIO pins. If no parameter is given, a 32-bit number containing all GPIO states is returned.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
gpio_read
```

### Response
#### Success Response (200)
- **State** (string) - "OK(0)" followed by the GPIO state(s).

#### Response Example
```plaintext
OK(0),0x1
```
```

```APIDOC
## INFO

### Description
Displays information about the current version of the I3Cblaster.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
info
```

### Response
#### Success Response (200)
- **Info** (string) - Version and other relevant information about the I3Cblaster.

#### Response Example
```plaintext
I3Cblaster v1.0
```
```

```APIDOC
## I3C_TARGETRESET

### Description
Executes a target reset sequence on the I3C bus.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_targetreset
```

### Response
#### Success Response (200)
- **Status** (string) - "OK(0)" indicating success.

#### Response Example
```plaintext
OK(0)
```
```

```APIDOC
## I3C_DRIVESTRENGTH

### Description
Sets the drive strength of the controller's SDA and SCL pads. Valid values are 2, 4, 8, 12 (representing 2mA, 4mA, 8mA, or 12mA).

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_drivestrength 8
```

### Response
#### Success Response (200)
- **Status** (string) - "OK(0)" indicating success.

#### Response Example
```plaintext
OK(0)
```
```

```APIDOC
## I3C_CLK

### Description
Sets the I3C clock frequency.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_clk 1000000
```

### Response
#### Success Response (200)
- **Status** (string) - "OK(0)" indicating success.

#### Response Example
```plaintext
OK(0)
```
```

```APIDOC
## I3C_SCAN

### Description
Scans for available I3C devices on the bus.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_scan
```

### Response
#### Success Response (200)
- **Devices** (string) - "OK(0)" followed by a comma-separated list of detected I3C addresses.

#### Response Example
```plaintext
OK(0),0x30,0x7e
```
```

```APIDOC
## I3C_ENTDAA

### Description
Executes the I3C ENTDAA (Assign Dynamic Address) procedure. The I3C address to assign can be provided as a parameter.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_entdaa 0x30
```

### Response
#### Success Response (200)
- **Status** (string) - "OK(0)" followed by device information (e.g., BCR).

#### Response Example
```plaintext
OK(0),0x04,0x6a,0x00,0x00,0x00,0x00,0x27,0xa0
```
```

```APIDOC
## I3C_RSTDAA

### Description
Executes an I3C RSTDAA (Reset Dynamic Address Assignment) CCC broadcast transfer. This un-assigns all target dynamic addresses.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_rstdaa
```

### Response
#### Success Response (200)
- **Status** (string) - "OK(0)" indicating success.

#### Response Example
```plaintext
OK(0)
```
```

```APIDOC
## I3C_SDR_WRITE

### Description
Executes a private SDR (Standard Data Rate) write transfer to a target device.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_sdr_write <target_address> <data_bytes>
```

### Response
#### Success Response (200)
- **Status** (string) - "OK(0)" indicating success.

#### Response Example
```plaintext
OK(0)
```
```

```APIDOC
## I3C_SDR_READ

### Description
Executes a private SDR (Standard Data Rate) read transfer from a target device.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_sdr_read <target_address> <byte_count>
```

### Response
#### Success Response (200)
- **Data** (string) - "OK(0)" followed by the read data bytes.

#### Response Example
```plaintext
OK(0),0x00,0x01
```
```

```APIDOC
## I3C_SDR_WRITEREAD

### Description
Executes a private SDR (Standard Data Rate) combined write-read transfer to a target device. Useful for reading register values after writing.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_sdr_writeread <target_address> <data_to_write> <bytes_to_read>
```

### Response
#### Success Response (200)
- **Result** (string) - "OK(0)" followed by bytes written and bytes read.

#### Response Example
```plaintext
OK(0),0x00,0x01
```
```

```APIDOC
## I3C_SDR_CCC_BC_WRITE

### Description
Executes a CCC (Command Control Code) broadcast write transfer over SDR.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_sdr_ccc_bc_write <ccc_command> <data_bytes>
```

### Response
#### Success Response (200)
- **Status** (string) - "OK(0)" indicating success.

#### Response Example
```plaintext
OK(0)
```
```

```APIDOC
## I3C_SDR_CCC_DIRECT_WRITE

### Description
Executes a CCC (Command Control Code) direct write transfer over SDR to a specific target.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_sdr_ccc_direct_write <target_address> <ccc_command> <data_bytes>
```

### Response
#### Success Response (200)
- **Status** (string) - "OK(0)" indicating success.

#### Response Example
```plaintext
OK(0)
```
```

```APIDOC
## I3C_SDR_CCC_DIRECT_READ

### Description
Executes a CCC (Command Control Code) direct read transfer over SDR from a specific target.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_sdr_ccc_direct_read <target_address> <ccc_command> <byte_count>
```

### Response
#### Success Response (200)
- **Data** (string) - "OK(0)" followed by the read data bytes.

#### Response Example
```plaintext
OK(0),0x00,0x01
```
```

```APIDOC
## I3C_POLL

### Description
Allows reading IBI (In-Band Interrupt) or HJ (Hot Join) information from the bus. Call this function if an IBI was signaled or at regular intervals to ensure IBI detection.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_poll
```

### Response
#### Success Response (200)
- **Info** (string) - "OK(0)" followed by IBI or HJ information if available.

#### Response Example
```plaintext
OK(0),IBI_DETECTED
```
```

```APIDOC
## I3C_DDR_CONFIG

### Description
Configures I3C behavior and I3C target capabilities. Refer to the ENDXFER CCC for a complete explanation.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_ddr_config <configuration_options>
```

### Response
#### Success Response (200)
- **Status** (string) - "OK(0)" indicating success.

#### Response Example
```plaintext
OK(0)
```
```

```APIDOC
## I3C_DDR_WRITE

### Description
Executes a private HDR-DDR (High Data Rate - Double Data Rate) mode write transfer to a target. Returns an error code and the number of words actually written.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_ddr_write <target_address> <data_words>
```

### Response
#### Success Response (200)
- **Result** (string) - "OK(0)" followed by the number of words written.

#### Response Example
```plaintext
OK(0),4
```
```

```APIDOC
## I3C_DDR_READ

### Description
Executes a HDR-DDR (High Data Rate - Double Data Rate) mode read transfer from a target. Returns an error code and the read data words.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_ddr_read <target_address> <word_count>
```

### Response
#### Success Response (200)
- **Data** (string) - "OK(0)" followed by the read data words.

#### Response Example
```plaintext
OK(0),0x00,0x01,0x02,0x03
```
```

```APIDOC
## I3C_DDR_WRITEREAD

### Description
Executes a HDR-DDR (High Data Rate - Double Data Rate) mode write transfer followed by a read transfer to a target. Returns an error code, the number of words written, and the read data words.

### Method
N/A (Command-line tool)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```plaintext
i3c_ddr_writeread <target_address> <data_to_write> <words_to_read>
```

### Response
#### Success Response (200)
- **Result** (string) - "OK(0)" followed by words written and read data words.

#### Response Example
```plaintext
OK(0),2,0x00,0x01
```
```

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

### C: Initialize I3C Controller

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Initializes the I3C controller hardware on the RP2040. This function requires the I2C pin as an argument. It returns a status code indicating success or failure.

```c
#include "i3c_hl.h"

int main() {
    // Initialize I3C controller
    // For Raspberry Pi Pico: GPIO16=SDA, GPIO17=SCL
    i3c_hl_status_t status = i3c_init(16);

    // For Seeed Xiao RP2040: GPIO6=SDA, GPIO7=SCL
    // status = i3c_init(6);

    if (status == i3c_hl_status_ok) {
        printf("I3C initialized successfully\n");
    } else {
        printf("I3C initialization failed: %s\n",
               i3c_hl_get_errorstring(status));
    }

    return 0;
}
```

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

### Discover I3CBlaster Devices (Python)

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Lists all connected I3CBlaster devices on the system by discovering their serial numbers. This function is crucial for identifying available hardware before establishing a connection.

```python
import i3cblaster

# Discover all connected I3CBlaster devices
devices = i3cblaster.listdevices()
print(f"Found {len(devices)} devices: {devices}")

# Example output: ['E6616407E34E5D28', 'A7834B02C45F6A39']
# Returns array of serial numbers for connected devices
```

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

### C: I3C Dynamic Address Assignment (ENTDAA)

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Executes the I3C ENTDAA (Enter Dynamic Address Assignment) command to assign a unique dynamic address to a target device. It first resets any previous assignments using `i3c_hl_rstdaa()` and then attempts to assign an address, returning the device's PID (Provisioned ID).

```c
#include "i3c_hl.h"

void assign_dynamic_address(void) {
    uint8_t target_addr = 0x30;
    uint8_t pid[8];  // Provisioned ID: BCR, DCR, PID[6]

    // Reset all previous assignments
    i3c_hl_rstdaa();

    // Assign dynamic address
    i3c_hl_status_t status = i3c_hl_entdaa(target_addr, pid);

    if (status == i3c_hl_status_ok) {
        printf("Device assigned to 0x%02x\n", target_addr);
        printf("BCR: 0x%02x, DCR: 0x%02x\n", pid[0], pid[1]);
        printf("PID: ");
        for (int i = 2; i < 8; i++) {
            printf("%02x", pid[i]);
        }
        printf("\n");
    } else if (status == i3c_hl_status_nak_during_arbhdr) {
        printf("No devices available for ENTDAA\n");
    } else {
        printf("ENTDAA failed: %s\n", i3c_hl_get_errorstring(status));
    }
}
```

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

### I3C Drive Strength Configuration

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Sets the I3C bus drive strength for SDA and SCL signals using the i3cblaster library. Valid values typically range from 2 to 12 mA. Proper drive strength configuration optimizes signal integrity, crucial for reliable communication, especially with longer traces or higher capacitance.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

# Valid values: 2, 4, 8, 12 (in mA)
try:
    i3c.i3c_drivestrength(4)  # Set to 4mA
    print("Drive strength set to 4mA")
except Exception as e:
    print(f"Drive strength configuration failed: {e}")

# Use higher drive strength for longer wires or higher capacitance
# Use lower drive strength to reduce EMI and power consumption
```

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

### Scan I3C Bus for Devices (Python)

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Scans the I3C bus to detect all responding device addresses. It handles potential exceptions during the scan process and prints the found addresses, including the broadcast address.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

# Scan for I3C devices on the bus
try:
    addresses = i3c.i3c_scan()
    print(f"Found devices at addresses: {[hex(addr) for addr in addresses]}")
    # Example output: ['0x30', '0x7e']
    # 0x7e is the I3C broadcast address, always present
except Exception as e:
    print(f"Scan failed: {e}")
```

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

### C Flags Configuration

Source: https://github.com/xyphro/i3cblaster/blob/main/src/CMakeLists.txt

Sets the C compiler flags for the project. In this case, it adds the '-g' flag to enable debugging information.

```cmake
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -g")
```

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

### C API: Execute HDR-DDR Write Transfer

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Executes a DDR mode write transfer using the i3c_hl_ddr_write function. It configures parameters like target address, command, data, and termination options. The function returns the status of the operation and updates the word count. Dependencies include the 'i3c_hl.h' header.

```c
#include "i3c_hl.h"

void ddr_write_example(void) {
    uint8_t target_addr = 0x30;
    uint8_t command = 0x00;
    uint16_t write_data[] = {0x1234, 0x5678, 0xABCD, 0xEF01};
    uint32_t word_count = sizeof(write_data) / sizeof(uint16_t);
    bool finalize_with_restart = false;

    // Configuration for V1.0 targets (most common)
    bool ack_nack_enable = false;
    bool early_write_term = false;
    bool send_crc_on_early_term = false;

    i3c_hl_status_t status = i3c_hl_ddr_write(
        target_addr,
        command,
        write_data,
        &word_count,  // Updated with actual words written
        finalize_with_restart,
        ack_nack_enable,
        early_write_term,
        send_crc_on_early_term
    );

    if (status == i3c_hl_status_ok) {
        printf("DDR write: %d words written\n", word_count);
    } else if (status == i3c_hl_status_ddr_early_termination) {
        printf("Target requested early termination at word %d\n", word_count);
    } else if (status == i3c_hl_status_ddr_crc_wrong) {
        printf("CRC error during DDR write\n");
    } else {
        printf("DDR write failed: %s\n", i3c_hl_get_errorstring(status));
    }
}
```

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

### I3C SDR Combined Write-Read (Python)

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Executes a combined SDR write followed by a read transfer, useful for accessing device registers. The function takes the target address, data to write (e.g., register address), and the number of bytes to read. It returns the read data or raises an exception.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

target_addr = 0x30
register_addr = [0x00, 0x01]  # Register address to read from
bytes_to_read = 8

try:
    # Write register address, then read data
    data = i3c.i3c_sdr_writeread(target_addr, register_addr, bytes_to_read)
    print(f"Read {len(data)} bytes from register: {[hex(x) for x in data]}")
    # Example output: [0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07]
except Exception as e:
    print(f"Write-Read failed: {e}")
```

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

### C API: Execute HDR-DDR Read Transfer

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Executes a DDR mode read transfer using the i3c_hl_ddr_read function. It specifies the target address, command, and a buffer for received data. The function returns the status and the number of words read. Dependencies include the 'i3c_hl.h' header.

```c
#include "i3c_hl.h"

void ddr_read_example(void) {
    uint8_t target_addr = 0x30;
    uint8_t command = 0x00;
    uint16_t read_buffer[32];
    uint32_t word_count = sizeof(read_buffer) / sizeof(uint16_t);
    bool finalize_with_restart = false;
    bool read_crc_on_early_term = false;  // For V1.0 targets

    i3c_hl_status_t status = i3c_hl_ddr_read(
        target_addr,
        command,
        read_buffer,
        &word_count,  // Updated with actual words read
        finalize_with_restart,
        read_crc_on_early_term
    );

    if (status == i3c_hl_status_ok) {
        printf("DDR read: %d words\n", word_count);
        for (uint32_t i = 0; i < word_count; i++) {
            printf("  [%02d] = 0x%04x\n", i, read_buffer[i]);
        }
    } else if (status == i3c_hl_status_ddr_parity_wrong) {
        printf("Parity error during DDR read\n");
    } else if (status == i3c_hl_status_ddr_crc_wrong) {
        printf("CRC error during DDR read\n");
    } else {
        printf("DDR read failed: %s\n", i3c_hl_get_errorstring(status));
    }
}
```

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

### Assign Dynamic I3C Addresses (ENTDAA) (Python)

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Assigns dynamic addresses to I3C devices supporting DAA. This function first resets previous assignments and then assigns a specific address, returning device information if successful. It also includes verification by scanning the bus afterwards.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

# Reset all previously assigned dynamic addresses
i3c.i3c_rstdaa()

# Assign address 0x30 to an I3C device
device_info = i3c.i3c_entdaa(0x30)

if device_info is not None:
    print(f"Device assigned to 0x30")
    print(f"Device PID (Provisioned ID): {[hex(x) for x in device_info]}")
    # device_info contains [BCR, DCR, PID[6 bytes]]
else:
    print("No devices available for ENTDAA (0x7E NAKed)")

# Verify the assignment
addresses = i3c.i3c_scan()
print(f"Active addresses: {[hex(addr) for addr in addresses]}")
```

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

### I3C HDR-DDR Configuration

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Configures parameters for High Data Rate Double Data Rate (HDR-DDR) mode using the i3cblaster library. This function allows setting options like CRC word indicators and early termination, crucial for compatibility with specific I3C target specifications (e.g., V1.0 or V1.1).

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

# Configure for V1.0 spec targets (most common as of 2024)
crc_word_indicator = True  # No CRC word follows early termination
enable_early_write_term = False  # Disable early write termination
write_ack_enable = False  # V1.0 targets don't support write ACK

try:
    i3c.i3c_ddr_config(crc_word_indicator, enable_early_write_term, write_ack_enable)
    print("DDR configuration set for V1.0 targets")
except Exception as e:
    print(f"DDR configuration failed: {e}")

# For V1.1 spec targets with flow control, adjust parameters accordingly
# based on ENDXFER CCC settings
```

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

### I3C CCC Direct Write

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Performs a CCC direct write transfer to a specific target device on the I3C bus. It requires the i3cblaster library, a target address, the CCC command, and optional payload data. This enables targeted control of individual I3C devices.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

target_addr = 0x30
bc_payload = [0x81]  # Direct CCC command (SETDASA + 1)
direct_payload = [0x50, 0x00]  # Payload data

try:
    i3c.i3c_sdr_ccc_direct_write(target_addr, bc_payload, direct_payload)
    print("Direct CCC write completed")
except Exception as e:
    print(f"Direct CCC write failed: {e}")
```

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

### I3C HDR-DDR Read Transfer

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Initiates a High Data Rate DDR mode read transfer from an I3C target using the i3cblaster library. This function takes the target address, a command (with bit 7 set for read), and the number of 16-bit words to read. It's essential to configure DDR mode before use.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

target_addr = 0x30
command = 0x00  # 7-bit command (bit 7 will be forced high for read)
words_to_read = 10

# DDR configuration would typically precede this call
# e.g., i3c.i3c_ddr_config(True, False, False)

# try:
#     data = i3c.i3c_ddr_read(target_addr, command, words_to_read)
#     print(f"DDR read completed: {[hex(x) for x in data]}")
# except Exception as e:
#     print(f"DDR read failed: {e}")
```

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

### I3C Target Reset

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Initiates an I3C target reset sequence on the bus. This function, provided by the i3cblaster library, causes all I3C targets connected to the bus to reset their internal states. It's a useful utility for bringing devices back to a known state.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

try:
    i3c.i3c_targetreset()
    print("Target reset sequence completed")
    # All I3C targets on the bus will reset
except Exception as e:
    print(f"Target reset failed: {e}")
```

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

### I3C HDR-DDR Write Transfer

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Executes a High Data Rate DDR mode write transfer using the i3cblaster library. This function requires the target address, a command value, and the data to be written (as 16-bit words). Proper DDR configuration must be set prior to initiating the transfer.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

target_addr = 0x30
command = 0x00  # 7-bit command value
write_data = [0x1234, 0x5678, 0xABCD]  # 16-bit word values

# Configure for V1.0 targets first
i3c.i3c_ddr_config(True, False, False)

try:
    i3c.i3c_ddr_write(target_addr, command, write_data)
    print(f"DDR write completed: {len(write_data)} words written")
except Exception as e:
    print(f"DDR write failed: {e}")
    # Possible errors: NAK, CRC error, parity error, early termination
```

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

### I3C Clock Frequency Configuration

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Configures the I3C bus clock frequency using the i3cblaster library. The function accepts frequency in kHz and allows setting various speeds suitable for different device requirements or bus lengths. It's important to use compatible frequencies for stable communication.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

# Set clock to 12.5 MHz (maximum supported)
try:
    i3c.i3c_clk(12500)  # Frequency in kHz
    print("Clock set to 12.5 MHz")
except Exception as e:
    print(f"Clock configuration failed: {e}")

# Set to 1 MHz for slower devices or longer wires
i3c.i3c_clk(1000)
```

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

### I3C DDR Write-Read Transfer

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Executes a combined HDR-DDR write followed by a read transfer to an I3C target. This function first writes data and then reads a specified number of words. It returns the number of words written and the data read. DDR configuration must be set beforehand.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

target_addr = 0x30
write_command = 0x00
read_command = 0x01
write_data = [0x1234, 0x5678]  # 16-bit words
words_to_read = 8

# Configure for V1.0 targets
i3c.i3c_ddr_config(True, False, False)

try:
    result = i3c.i3c_ddr_writeread(target_addr, write_command, read_command,
                                    write_data, words_to_read)
    words_written = result[0]
    read_data = result[1]

    print(f"DDR write-read completed")
    print(f"Words written: {words_written}")
    print(f"Words read: {len(read_data)}")
    print(f"Read data: {[hex(x) for x in read_data]}")
except Exception as e:
    print(f"DDR write-read failed: {e}")
```

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

### I3C CCC Direct Read

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Executes a CCC direct read transfer from a specific target device. This function from the i3cblaster library needs the target address, the CCC command, and the number of bytes to read. It returns the data read from the target.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

target_addr = 0x30
ccc_command = [0x8F]  # GETMWL (Get Max Write Length) - direct read CCC
bytes_to_read = 2

try:
    data = i3c.i3c_sdr_ccc_direct_read(target_addr, ccc_command, bytes_to_read)
    print(f"CCC direct read result: {[hex(x) for x in data]}")
except Exception as e:
    print(f"CCC direct read failed: {e}")
```

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

### I3C CCC Broadcast Write

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Executes a Common Command Code (CCC) broadcast write transfer to all devices on the I3C bus. It requires the i3cblaster library and takes a list of CCC command bytes as input. This is useful for commands affecting all targets, like enabling interrupts.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

# Send ENEC (Enable Events Command) - CCC 0x00
# Enable In-Band Interrupts for all devices
ccc_command = [0x00]  # CCC command code

try:
    i3c.i3c_sdr_ccc_bc_write(ccc_command)
    print("Broadcast CCC command sent successfully")
except Exception as e:
    print(f"CCC broadcast failed: {e}")
```

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

### I3C SDR Private Write Operation (Python)

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Executes a private write transfer to an I3C target device using SDR mode. This function takes the target address and a list of bytes to write, reporting success or failure with specific exception details.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

target_addr = 0x30
write_data = [0x00, 0x12, 0x34, 0x56]

try:
    i3c.i3c_sdr_write(target_addr, write_data)
    print(f"Successfully wrote {len(write_data)} bytes to device 0x{target_addr:02x}")
except Exception as e:
    print(f"Write failed: {e}")
    # Exceptions include: NAK, IBI detected, parameter out of range
```

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

### GPIO Read

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Reads the state of GPIO pins on the I3CBlaster device. It can read a single pin's state or all GPIO pins simultaneously, returning a 32-bit integer representing the state of all pins.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

try:
    # Read single GPIO pin
    gpio_pin = 5
    state = i3c.gpio_read(gpio_pin)[0]
    print(f"GPIO {gpio_pin} state: {state}")

    # Read all GPIO pins (returns 32-bit value)
    all_gpios = i3c.gpio_read()[0]
    print(f"All GPIO states: 0x{all_gpios:08x}")

    # Check individual bits
    if all_gpios & (1 << 5):
        print("GPIO 5 is HIGH")
    else:
        print("GPIO 5 is LOW")
except Exception as e:
    print(f"GPIO read failed: {e}")
```

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

### GPIO Write Control

Source: https://context7.com/xyphro/i3cblaster/llms.txt

Controls the state of GPIO pins on the I3CBlaster device. Pins can be set to HIGH (1), LOW (0), or tristate/input ('Z'). On Xiao modules, GPIO0 controls the edge accelerator.

```python
import i3cblaster

i3c = i3cblaster.i3cblaster()

gpio_pin = 0

try:
    # Set pin to HIGH (output)
    i3c.gpio_write(gpio_pin, 1)

    # Set pin to LOW (output)
    i3c.gpio_write(gpio_pin, 0)

    # Set pin to tristate/input
    i3c.gpio_write(gpio_pin, 'Z')

    print(f"GPIO {gpio_pin} configured")
except Exception as e:
    print(f"GPIO write failed: {e}")

# On Xiao module, GPIO0 controls edge accelerator
# gpio_write(0, 1) = edge accelerator ON (default)
# gpio_write(0, 0) = edge accelerator OFF
```
Tokens:
Raw