Registry / database / adafruit-circuitpython-busdevice

adafruit-circuitpython-busdevice

JSON →
library5.2.17pypypi✓ verified 85d ago

Adafruit CircuitPython Bus Device provides helper classes, `I2CDevice` and `SPIDevice`, to simplify managing transaction state on I2C and SPI buses. It handles bus locking, device addressing for I2C, and chip select and protocol changes for SPI. The library is actively maintained by Adafruit, with frequent releases to address bug fixes and add minor enhancements. The current version is 5.2.16.

pip install adafruit-circuitpython-busdevice
INSTALL
IMPORT
SIG · ADAFRUIT-CIRCUITPY
A
adafruit-circuitpython-busdevice
databasepythonv5.2.17
Install
2.7s avg
Import
56ms
Disk
26MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.059s · 27.4MB
glibc
py 3.103.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.
fix
Check 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.
fix
Ensure `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`.
fix
This 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).
fix
Always 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.
fix
Ensure `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.
fix
For 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.
fix
Always 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.
fix
This 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.
fix
Update 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).
Agent activity
67 hits · last 30 days
node
56
OpenAI (training)
1
Resources
adafruit-circuitpython-busdevice — pip install adafruit-circuitpython-busdevice · libregistry