{"id":7367,"library":"libusbsio","title":"libusbsio Python Wrapper","description":"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.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/vsl-lab/libusbsio-python","tags":["usb","hardware","i2c","spi","gpio","nxp","embedded"],"install":[{"cmd":"pip install libusbsio","lang":"bash","label":"Install libusbsio"}],"dependencies":[{"reason":"This Python package is a wrapper around the NXP LIBUSBSIO C library, which must be installed separately on the operating system for libusbsio to function. It is not a Python dependency installable via pip.","package":"NXP LIBUSBSIO C library","optional":false}],"imports":[{"note":"All core classes and functions (e.g., SiODevice, SiOBus, SiOError) are typically accessed as attributes of the libusbsio module.","symbol":"libusbsio","correct":"import libusbsio"},{"note":"Classes like SiODevice are part of the libusbsio module; they cannot be imported directly without specifying the parent module.","wrong":"import SiODevice","symbol":"SiODevice","correct":"from libusbsio import SiODevice"}],"quickstart":{"code":"import libusbsio\n\ntry:\n    # Enumerate available SiO devices\n    devices = libusbsio.SiOBus.enumerate()\n\n    if not devices:\n        print(\"No SiO devices found. Ensure device is connected and C library is installed.\")\n    else:\n        print(f\"Found {len(devices)} SiO devices:\")\n        for i, dev_info in enumerate(devices):\n            print(f\"  [{i}] Path: {dev_info.path}, Serial: {dev_info.serial_number}\")\n\n        # Example: Open the first detected device\n        first_device_path = devices[0].path\n        print(f\"\\nAttempting to open device at path: {first_device_path}\")\n        \n        with libusbsio.SiODevice(first_device_path) as device:\n            print(f\"Successfully opened device: {first_device_path}\")\n            # Now you can interact with the device, e.g., read/write I2C/SPI\n            # For example, to set an I2C speed (check your device capabilities):\n            # device.set_i2c_speed(100000) # 100 kHz\n            print(\"Device interaction complete. Device will close automatically.\")\n\nexcept libusbsio.SiOError as e:\n    print(f\"A libusbsio error occurred: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The underlying NXP LIBUSBSIO C library (DLLs on Windows) is not installed or not discoverable in the system's PATH.","error":"ImportError: DLL load failed while importing _libusbsio_bindings: The specified module could not be found."},{"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.","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.","error":"libusbsio.SiOError: LIBUSBSIO_STATUS_DEVICE_NOT_FOUND"},{"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.","cause":"The current user does not have sufficient permissions to open or interact with the USB device. This is common on Linux systems.","error":"libusbsio.SiOError: LIBUSBSIO_STATUS_ACCESS_DENIED"}]}