libusbsio Python Wrapper

2.2.0 · active · verified Thu Apr 16

libusbsio is a Python wrapper for the NXP LIBUSBSIO C library, designed to facilitate interaction with NXP's USB-to-I2C/SPI/GPIO bridge devices. It provides a high-level API for enumerating, opening, and communicating with supported hardware from Python applications. The current version is 2.2.0, with updates typically tied to enhancements or bug fixes in the underlying C library or the Python binding itself.

Common errors

```
ImportError: DLL load failed while importing _libusbsio_bindings: The specified module could not be found.
```
cause The underlying NXP LIBUSBSIO C library (DLLs on Windows) is not installed or not discoverable in the system's PATH.

fix Install the NXP LIBUSBSIO C library and its necessary drivers/DLLs according to NXP's official instructions. On Windows, ensure the DLLs are in a directory included in your system's PATH environment variable or in the Python script's directory.
```
libusbsio.SiOError: LIBUSBSIO_STATUS_DEVICE_NOT_FOUND
```
cause The NXP SiO device is either not connected, not powered on, or its system-level drivers are not correctly installed or recognized by the operating system.

fix Verify that your NXP device is securely connected and powered. Check your OS device manager (Windows) or use `lsusb` (Linux) to confirm the device is visible at the OS level. Ensure the correct NXP drivers are installed.
```
libusbsio.SiOError: LIBUSBSIO_STATUS_ACCESS_DENIED
```
cause The current user does not have sufficient permissions to open or interact with the USB device. This is common on Linux systems.

fix On Linux, you likely need to set up `udev` rules for the NXP device's Vendor ID (VID) and Product ID (PID) to grant access to a specific user group (e.g., `plugdev`) and add your user to that group. Restart your system or log out/in after changing udev rules/group memberships.

Warnings

breaking The `libusbsio` Python wrapper requires the NXP LIBUSBSIO C library to be separately installed on your operating system. Without the C library, the Python package will not function and will raise import errors.
Fix: Refer to NXP's documentation or the `libusbsio` Python wrapper's GitHub README for instructions on installing the appropriate C library and drivers for your specific OS (Windows, Linux, macOS).
gotcha On Linux, accessing USB devices often requires specific user permissions. If you encounter 'Access Denied' errors, it's likely a permission issue, not a problem with the Python library itself.
Fix: Configure `udev` rules to grant your user account access to the NXP SiO devices. Typically, this involves creating a rule in `/etc/udev/rules.d/` with the device's Vendor ID (VID) and Product ID (PID), and adding your user to a group like `plugdev` or `dialout`.
gotcha The library is specifically designed for NXP's USB-to-I2C/SPI/GPIO bridge devices. It will not work with generic USB devices or other manufacturers' bridge chips.
Fix: Ensure you are using a supported NXP USB-to-I2C/SPI/GPIO bridge device. If you're working with other hardware, a different library will be required.

Install

pip install libusbsio Install libusbsio

Imports

libusbsio
```
import libusbsio
```
All core classes and functions (e.g., SiODevice, SiOBus, SiOError) are typically accessed as attributes of the libusbsio module.
SiODevice
wrong:
```
import SiODevice
```
correct:
```
from libusbsio import SiODevice
```
Classes like SiODevice are part of the libusbsio module; they cannot be imported directly without specifying the parent module.

Quickstart

This quickstart demonstrates how to enumerate available NXP SiO devices and open the first one found. It uses a context manager (`with ... as`) to ensure the device is properly closed after use. Note that the underlying NXP LIBUSBSIO C library must be installed on your system for this code to run successfully.

import libusbsio

try:
    # Enumerate available SiO devices
    devices = libusbsio.SiOBus.enumerate()

    if not devices:
        print("No SiO devices found. Ensure device is connected and C library is installed.")
    else:
        print(f"Found {len(devices)} SiO devices:")
        for i, dev_info in enumerate(devices):
            print(f"  [{i}] Path: {dev_info.path}, Serial: {dev_info.serial_number}")

        # Example: Open the first detected device
        first_device_path = devices[0].path
        print(f"\nAttempting to open device at path: {first_device_path}")
        
        with libusbsio.SiODevice(first_device_path) as device:
            print(f"Successfully opened device: {first_device_path}")
            # Now you can interact with the device, e.g., read/write I2C/SPI
            # For example, to set an I2C speed (check your device capabilities):
            # device.set_i2c_speed(100000) # 100 kHz
            print("Device interaction complete. Device will close automatically.")

except libusbsio.SiOError as e:
    print(f"A libusbsio error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →