Registry /
database / adafruit-circuitpython-busdevice
Install & Compatibility
Where this runs
tested against v5.2.17 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.059s · 27.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.7s · import 0.052s · 28MB
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
I2CDevice
✓ from adafruit_bus_device.i2c_device import I2CDevice
✗ from adafruit_bus_device import I2CDevice
The `I2CDevice` class is within the `i2c_device` submodule, not directly under `adafruit_bus_device`.
SPIDevice
✓ from adafruit_bus_device.spi_device import SPIDevice
✗ from adafruit_bus_device import SPIDevice
The `SPIDevice` class is within the `spi_device` submodule, not directly under `adafruit_bus_device`.
This quickstart demonstrates how to use `I2CDevice` and `SPIDevice` to perform basic read operations. It initializes the respective bus, creates a device object, and uses a `with` statement to manage bus locking and chip select automatically during transactions. Replace placeholder addresses and pins with your specific hardware configuration. For CPython, ensure `adafruit-blinka` is installed and GPIO/bus access is configured.
import board
import busio
import digitalio
from adafruit_bus_device.i2c_device import I2CDevice
from adafruit_bus_device.spi_device import SPIDevice
# --- I2C Example ---
# Replace with your actual I2C device address (e.g., 0x68 for DS3231)
I2C_DEVICE_ADDRESS = 0x68
I2C_REGISTER_ADDRESS = 0x0E # Example register
print("--- I2C Device Example ---")
try:
# Initialize I2C bus
i2c = busio.I2C(board.SCL, board.SDA)
# Create an I2CDevice object
i2c_device = I2CDevice(i2c, I2C_DEVICE_ADDRESS)
# Perform an I2C transaction
with i2c_device:
i2c_device.write(bytes([I2C_REGISTER_ADDRESS]))
result = bytearray(1)
i2c_device.readinto(result)
print(f"I2C read from 0x{I2C_DEVICE_ADDRESS:02X}, register 0x{I2C_REGISTER_ADDRESS:02X}: {result[0]:02X}")
except Exception as e:
print(f"I2C Example Error: {e}")
finally:
if 'i2c' in locals() and i2c.locked: i2c.unlock() # Ensure bus is unlocked
# --- SPI Example ---
# Replace with your actual SPI settings and CS pin
SPI_REGISTER_ADDRESS = 0xD0 # Example register for BMP280
print("\n--- SPI Device Example ---")
try:
# Initialize SPI bus and Chip Select pin
spi_bus = busio.SPI(board.SCK, MOSI=board.MOSI, MISO=board.MISO)
cs_pin = digitalio.DigitalInOut(board.D5) # Use an appropriate digital pin
# Create an SPIDevice object
spi_device = SPIDevice(spi_bus, cs_pin)
# Perform an SPI transaction
with spi_device as spi:
spi.write(bytes([SPI_REGISTER_ADDRESS]))
result = bytearray(1)
spi.readinto(result)
print(f"SPI read from register 0x{SPI_REGISTER_ADDRESS:02X}: {result[0]:02X}")
except Exception as e:
print(f"SPI Example Error: {e}")
finally:
if 'spi_bus' in locals() and spi_bus.locked: spi_bus.unlock() # Ensure bus is unlocked
print("Examples complete.")
Debug
Known issues
gotchaOn CircuitPython boards running v6.3.0 or newer firmware, `adafruit_bus_device` may be built-in. Installing an additional copy into the 'lib' directory can cause import conflicts and lead to unexpected errors in libraries that depend on it.fixCheck the CircuitPython 'module support matrix' for your board. If `adafruit_bus_device` is built-in, do not copy the library to your CIRCUITPY drive. If you encounter issues, try removing the `adafruit_bus_device` folder from 'lib'.
affects: CircuitPython >= 6.3.0
gotcha`ImportError: No module named 'adafruit_bus_device'` in CPython (e.g., Raspberry Pi) often indicates the library or a core dependency like `adafruit-blinka` is missing.fixEnsure `adafruit-circuitpython-busdevice` and `adafruit-blinka` are installed via `pip` (e.g., `pip3 install adafruit-circuitpython-busdevice adafruit-blinka --upgrade`).
affects: All CPython versions
gotchaEncountering `AttributeError: 'DebugI2C' object has no attribute 'probe'` when using `DebugI2C` with `adafruit_bus_device` can occur due to an incompatibility between `DebugI2C` and the core CPython implementation of `adafruit_bus_device`.fixThis is an active issue (as of March 2026). A known workaround for specific debugging scenarios is to force the use of the pure Python `adafruit_bus_device` implementation, if available, by renaming library directories or adjusting import paths, though this is generally not recommended for production. Refer to GitHub issue `adafruit/circuitpython#10890` for the latest status and solutions.
affects: Recent CircuitPython versions (e.g., CircuitPython 10.x with core busio)
gotchaCircuitPython `.mpy` files (pre-compiled modules) are version-specific. An `ValueError: Incompatible .mpy file` will occur if `adafruit_bus_device` (or a library depending on it) was compiled for a different major CircuitPython version than currently running on your board (e.g., 6.x vs 7.x).fixAlways use the latest Adafruit CircuitPython Library Bundle corresponding to your CircuitPython firmware version. Replace all `.mpy` libraries on your `CIRCUITPY/lib` drive with the updated versions from the bundle.
affects: CircuitPython versions with `.mpy` format changes (e.g., 1.x->2.x, 2.x->3.x, 6.x->7.x)
gotchaThe `SPIDevice` class might fail to initialize if `libgpiod` bindings are absent on certain Linux systems when using direct hardware SPI, as noted in release 5.2.15.fixEnsure `libgpiod` development libraries and Python bindings are installed on your system if you encounter issues with `SPIDevice` on Linux (e.g., `sudo apt-get install libgpiod-dev python3-libgpiod`).
affects: 5.2.15 and later on specific CPython platforms (e.g., some Linux SBCs)
Errors
Common errors & fixes
ImportError: No module named 'adafruit_bus_device.i2c_device'
The `adafruit_bus_device` library is not installed, or the `adafruit_bus_device` folder is missing from the `lib` directory on a CircuitPython board, or there's a conflict with a built-in version.
fixFor CPython, run `pip install adafruit-circuitpython-busdevice`. For CircuitPython, ensure the `adafruit_bus_device` folder from the latest library bundle is copied to `CIRCUITPY/lib`, and check if your firmware has it built-in (see warnings).
AttributeError: 'I2C' object has no attribute 'readinto' (or 'write', 'writeto_then_readfrom')
You are attempting to use `I2CDevice` methods directly on a `busio.I2C` object, or outside of its context manager (`with i2c_device:` block). `I2CDevice` provides these methods and manages bus locking.
fixAlways interact with I2C devices through an `I2CDevice` instance and preferably within a `with` statement. Example: `with i2c_device: i2c_device.readinto(buf)`.
TypeError: function takes 1 positional arguments but 2 were given
This specific `TypeError` has been observed when using `DebugI2C` from `adafruit_debug_i2c` with the core `adafruit_bus_device` implementation, indicating a mismatch in expected arguments for certain internal methods, possibly related to `probe` or initialization.
fixThis points to a known compatibility issue. Consult the Adafruit CircuitPython GitHub issues (specifically `adafruit/circuitpython#10890`) for the most up-to-date workarounds or fixes. Temporarily, some users have resorted to using the pure Python `adafruit_bus_device` implementation if debugging is critical.
ValueError: Incompatible .mpy file
The pre-compiled Python module (`.mpy` file) for `adafruit_bus_device` (or a library that depends on it) was created with a different major version of CircuitPython than what is currently running on the board.
fixUpdate all CircuitPython libraries on your board using the latest Adafruit CircuitPython Library Bundle that matches your board's firmware version. This ensures all `.mpy` files are compatible.
Upgrade
Version history
5.2.17latest on PyPI · released Apr 23, 2026
Audit
Dependencies
adafruit-blinkarequiredRequired for running CircuitPython libraries on single-board computers like Raspberry Pi (CPython).
busiorequiredProvides low-level I2C and SPI bus access, used by `adafruit_bus_device` classes. Part of CircuitPython core or provided by `adafruit-blinka`.
digitaliorequiredUsed for managing chip select (CS) pins in SPIDevice. Part of CircuitPython core or provided by `adafruit-blinka`.
libgpiod bindingsoptionalMay be required for SPIDevice initialization on certain Linux systems when hardware SPI is used directly (CPython).