Adafruit CircuitPython BusDevice¶
The I2CDevice
and SPIDevice
helper classes make managing transaction state
on a bus easy. For example, they manage locking the bus to prevent other
concurrent access. For SPI devices, it manages the chip select and protocol
changes such as mode. For I2C, it manages the device address.
On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:
pip3 install adafruit-circuitpython-busdevice
To install system-wide (this may be required in some cases):
sudo pip3 install adafruit-circuitpython-busdevice
To install in a virtual environment in your current project:
mkdir project-name && cd project-name
python3 -m venv .env
source .env/bin/activate
pip3 install adafruit-circuitpython-busdevice
Usage Example¶
See examples/read_register_i2c.py and examples/read_register_spi.py for examples of the module’s usage.
Contributing¶
Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.
Documentation¶
For information on building library documentation, please check out this guide.
Table of Contents¶
Simple test¶
Ensure your device works with this simple test.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | import busio
import board
from adafruit_bus_device.i2c_device import I2CDevice
DEVICE_ADDRESS = 0x68 # device address of DS3231 board
A_DEVICE_REGISTER = 0x0E # device id register on the DS3231 board
# The follow is for I2C communications
comm_port = busio.I2C(board.SCL, board.SDA)
device = I2CDevice(comm_port, DEVICE_ADDRESS)
with device as bus_device:
bus_device.write(bytes([A_DEVICE_REGISTER]))
result = bytearray(1)
bus_device.readinto(result)
print("".join("{:02x}".format(x) for x in result))
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | import busio
import board
import digitalio
from adafruit_bus_device.spi_device import SPIDevice
DEVICE_ADDRESS = 0x68 # device address of BMP280 board
A_DEVICE_REGISTER = 0xD0 # device id register on the BMP280 board
# The follow is for SPI communications
cs = digitalio.DigitalInOut(board.A2)
comm_port = busio.SPI(board.SCK, MOSI=board.MOSI, MISO=board.MISO)
device = SPIDevice(comm_port, cs)
# pylint: disable-msg=no-member
with device as bus_device:
bus_device.write(bytes([A_DEVICE_REGISTER]))
result = bytearray(1)
bus_device.readinto(result)
print("".join("{:02x}".format(x) for x in result))
|
adafruit_bus_device.i2c_device
- I2C Bus Device¶
-
class
adafruit_bus_device.i2c_device.
I2CDevice
(i2c, device_address, probe=True)[source]¶ Represents a single I2C device and manages locking the bus and the device address.
Parameters: Note
This class is NOT built into CircuitPython. See here for install instructions.
Example:
import busio from board import * from adafruit_bus_device.i2c_device import I2CDevice with busio.I2C(SCL, SDA) as i2c: device = I2CDevice(i2c, 0x70) bytes_read = bytearray(4) with device: device.readinto(bytes_read) # A second transaction with device: device.write(bytes_read)
-
readinto
(buf, *, start=0, end=None)[source]¶ Read into
buf
from the device. The number of bytes read will be the length ofbuf
.If
start
orend
is provided, then the buffer will be sliced as ifbuf[start:end]
. This will not cause an allocation likebuf[start:end]
will so it saves memory.Parameters:
-
write
(buf, *, start=0, end=None, stop=True)[source]¶ Write the bytes from
buffer
to the device. Transmits a stop bit ifstop
is set.If
start
orend
is provided, then the buffer will be sliced as ifbuffer[start:end]
. This will not cause an allocation likebuffer[start:end]
will so it saves memory.Parameters:
-
write_then_readinto
(out_buffer, in_buffer, *, out_start=0, out_end=None, in_start=0, in_end=None, stop=False)[source]¶ Write the bytes from
out_buffer
to the device, then immediately reads intoin_buffer
from the device. The number of bytes read will be the length ofin_buffer
.If
out_start
orout_end
is provided, then the output buffer will be sliced as ifout_buffer[out_start:out_end]
. This will not cause an allocation likebuffer[out_start:out_end]
will so it saves memory.If
in_start
orin_end
is provided, then the input buffer will be sliced as ifin_buffer[in_start:in_end]
. This will not cause an allocation likein_buffer[in_start:in_end]
will so it saves memory.Parameters: - out_buffer (bytearray) – buffer containing the bytes to write
- in_buffer (bytearray) – buffer containing the bytes to read into
- out_start (int) – Index to start writing from
- out_end (int) – Index to read up to but not include; if None, use
len(out_buffer)
- in_start (int) – Index to start writing at
- in_end (int) – Index to write up to but not include; if None, use
len(in_buffer)
- stop (bool) – Deprecated
-
adafruit_bus_device.spi_device
- SPI Bus Device¶
-
class
adafruit_bus_device.spi_device.
SPIDevice
(spi, chip_select=None, *, baudrate=100000, polarity=0, phase=0, extra_clocks=0)[source]¶ Represents a single SPI device and manages locking the bus and the device address.
Parameters: - spi (SPI) – The SPI bus the device is on
- chip_select (DigitalInOut) – The chip select pin object that implements the DigitalInOut API.
- extra_clocks (int) – The minimum number of clock cycles to cycle the bus after CS is high. (Used for SD cards.)
Note
This class is NOT built into CircuitPython. See here for install instructions.
Example:
import busio import digitalio from board import * from adafruit_bus_device.spi_device import SPIDevice with busio.SPI(SCK, MOSI, MISO) as spi_bus: cs = digitalio.DigitalInOut(D10) device = SPIDevice(spi_bus, cs) bytes_read = bytearray(4) # The object assigned to spi in the with statements below # is the original spi_bus object. We are using the busio.SPI # operations busio.SPI.readinto() and busio.SPI.write(). with device as spi: spi.readinto(bytes_read) # A second transaction with device as spi: spi.write(bytes_read)