busio – Hardware accelerated external bus access
The busio module contains classes to support a variety of serial
protocols.
When the microcontroller does not support the behavior in a hardware
accelerated fashion it may internally use a bitbang routine. However, if
hardware support is available on a subset of pins but not those provided,
then a RuntimeError will be raised. Use the bitbangio module to explicitly
bitbang a serial protocol on any general purpose pins.
All classes change hardware state and should be deinitialized when they
are no longer needed if the program continues after use. To do so, either
call deinit() or use a context manager. See
Lifetime and ContextManagers for more info.
For example:
import busio
from board import *
i2c = busio.I2C(SCL, SDA)
print(i2c.scan())
i2c.deinit()
This example will initialize the the device, run
scan() and then deinit() the
hardware. The last step is optional because CircuitPython automatically
resets hardware after a program finishes.
Note that drivers will typically handle communication if provided the bus
instance (such as busio.I2C(board.SCL, board.SDA)), and that many of
the methods listed here are lower level functionalities that are needed
for working with custom drivers.
Tutorial for I2C and SPI: https://learn.adafruit.com/circuitpython-basics-i2c-and-spi
Tutorial for UART: https://learn.adafruit.com/circuitpython-essentials/circuitpython-uart-serial
Available on these boards
- class busio.I2C(scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 100000, timeout: int = 255)
Two wire serial protocol
I2C is a two-wire protocol for communicating between devices. At the physical level it consists of 2 wires: SCL and SDA, the clock and data lines respectively.
See also
Using this class directly requires careful lock management. Instead, use
I2CDeviceto manage locks.See also
Using this class to directly read registers requires manual bit unpacking. Instead, use an existing driver or make one with Register data descriptors.
- Parameters:
- __exit__() None
Automatically deinitializes the hardware on context exit. See Lifetime and ContextManagers for more info.
- scan() List[int]
Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of those that respond.
- Returns:
List of device ids on the I2C bus
- Return type:
- try_lock() bool
Attempts to grab the I2C lock. Returns True on success.
- Returns:
True when lock has been grabbed
- Return type:
- readfrom_into(address: int, buffer: circuitpython_typing.WriteableBuffer, *, start: int = 0, end: int = sys.maxsize) None
Read into
bufferfrom the device selected byaddress. At least one byte must be read.If
startorendis provided, then the buffer will be sliced as ifbuffer[start:end]were passed, but without copying the data. The number of bytes read will be the length ofbuffer[start:end].
- writeto(address: int, buffer: circuitpython_typing.ReadableBuffer, *, start: int = 0, end: int = sys.maxsize) None
Write the bytes from
bufferto the device selected byaddressand then transmit a stop bit.If
startorendis provided, then the buffer will be sliced as ifbuffer[start:end]were passed, but without copying the data. The number of bytes written will be the length ofbuffer[start:end].Writing a buffer or slice of length zero is permitted, as it can be used to poll for the existence of a device.
- writeto_then_readfrom(address: int, out_buffer: circuitpython_typing.ReadableBuffer, in_buffer: circuitpython_typing.WriteableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) None
Write the bytes from
out_bufferto the device selected byaddress, generate no stop bit, generate a repeated start and read intoin_buffer.out_bufferandin_buffercan be the same buffer because they are used sequentially.If
out_startorout_endis provided, then the buffer will be sliced as ifout_buffer[out_start:out_end]were passed, but without copying the data. The number of bytes written will be the length ofout_buffer[start:end].If
in_startorin_endis provided, then the input buffer will be sliced as ifin_buffer[in_start:in_end]were passed, The number of bytes read will be the length ofout_buffer[in_start:in_end].- Parameters:
address (int) – 7-bit device address
out_buffer (ReadableBuffer) – buffer containing the bytes to write
in_buffer (WriteableBuffer) – buffer to write into
out_start (int) – beginning of
out_buffersliceout_end (int) – end of
out_bufferslice; if not specified, uselen(out_buffer)in_start (int) – beginning of
in_bufferslicein_end (int) – end of
in_buffer slice; if not specified, uselen(in_buffer)
- class busio.SPI(clock: microcontroller.Pin, MOSI: microcontroller.Pin | None = None, MISO: microcontroller.Pin | None = None, half_duplex: bool = False)
A 3-4 wire serial protocol
SPI is a serial protocol that has exclusive pins for data in and out of the main device. It is typically faster than
I2Cbecause a separate pin is used to select a device rather than a transmitted address. This class only manages three of the four SPI lines:clock,MOSI,MISO. Its up to the client to manage the appropriate select line, often abbreviatedCSorSS. (This is common because multiple secondaries can share theclock,MOSIandMISOlines and therefore the hardware.)Construct an SPI object on the given pins.
Note
The SPI peripherals allocated in order of desirability, if possible, such as highest speed and not shared use first. For instance, on the nRF52840, there is a single 32MHz SPI peripheral, and multiple 8MHz peripherals, some of which may also be used for I2C. The 32MHz SPI peripheral is returned first, then the exclusive 8MHz SPI peripheral, and finally the shared 8MHz peripherals.
See also
Using this class directly requires careful lock management. Instead, use
SPIDeviceto manage locks.See also
Using this class to directly read registers requires manual bit unpacking. Instead, use an existing driver or make one with Register data descriptors.
- Parameters:
Limitations:
half_duplexis available only on STM; other chips do not have the hardware support.- frequency: int
The actual SPI bus frequency. This may not match the frequency requested due to internal limitations.
- __exit__() None
Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.
- configure(*, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) None
Configures the SPI bus. The SPI object must be locked.
- Parameters:
baudrate (int) – the desired clock rate in Hertz. The actual clock rate may be higher or lower due to the granularity of available clock settings. Check the
frequencyattribute for the actual clock rate.polarity (int) – the base state of the clock line (0 or 1)
phase (int) – the edge of the clock that data is captured. First (0) or second (1). Rising or falling depends on clock polarity.
bits (int) – the number of bits per word
Note
On the SAMD21, it is possible to set the baudrate to 24 MHz, but that speed is not guaranteed to work. 12 MHz is the next available lower speed, and is within spec for the SAMD21.
Note
On the nRF52840, these baudrates are available: 125kHz, 250kHz, 1MHz, 2MHz, 4MHz, and 8MHz. If you pick a a baudrate other than one of these, the nearest lower baudrate will be chosen, with a minimum of 125kHz. Two SPI objects may be created, except on the Circuit Playground Bluefruit, which allows only one (to allow for an additional I2C object).
- try_lock() bool
Attempts to grab the SPI lock. Returns True on success.
- Returns:
True when lock has been grabbed
- Return type:
- write(buffer: circuitpython_typing.ReadableBuffer, *, start: int = 0, end: int = sys.maxsize) None
Write the data contained in
buffer. The SPI object must be locked. If the buffer is empty, nothing happens.If
startorendis provided, then the buffer will be sliced as ifbuffer[start:end]were passed, but without copying the data. The number of bytes written will be the length ofbuffer[start:end].
- readinto(buffer: circuitpython_typing.WriteableBuffer, *, start: int = 0, end: int = sys.maxsize, write_value: int = 0) None
Read into
bufferwhile writingwrite_valuefor each byte read. The SPI object must be locked. If the number of bytes to read is 0, nothing happens.If
startorendis provided, then the buffer will be sliced as ifbuffer[start:end]were passed. The number of bytes read will be the length ofbuffer[start:end].- Parameters:
buffer (WriteableBuffer) – read bytes into this buffer
start (int) – beginning of buffer slice
end (int) – end of buffer slice; if not specified, it will be the equivalent value of
len(buffer)and for any value provided it will take the value ofmin(end, len(buffer))write_value (int) – value to write while reading
- write_readinto(out_buffer: circuitpython_typing.ReadableBuffer, in_buffer: circuitpython_typing.WriteableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) None
Write out the data in
out_bufferwhile simultaneously reading data intoin_buffer. The SPI object must be locked.If
out_startorout_endis provided, then the buffer will be sliced as ifout_buffer[out_start:out_end]were passed, but without copying the data. The number of bytes written will be the length ofout_buffer[out_start:out_end].If
in_startorin_endis provided, then the input buffer will be sliced as ifin_buffer[in_start:in_end]were passed, The number of bytes read will be the length ofout_buffer[in_start:in_end].The lengths of the slices defined by
out_buffer[out_start:out_end]andin_buffer[in_start:in_end]must be equal. If buffer slice lengths are both 0, nothing happens.- Parameters:
out_buffer (ReadableBuffer) – write out bytes from this buffer
in_buffer (WriteableBuffer) – read bytes into this buffer
out_start (int) – beginning of
out_buffersliceout_end (int) – end of
out_bufferslice; if not specified, uselen(out_buffer)in_start (int) – beginning of
in_bufferslicein_end (int) – end of
in_buffer slice; if not specified, uselen(in_buffer)
- class busio.UART(tx: microcontroller.Pin | None = None, rx: microcontroller.Pin | None = None, *, rts: microcontroller.Pin | None = None, cts: microcontroller.Pin | None = None, rs485_dir: microcontroller.Pin | None = None, rs485_invert: bool = False, baudrate: int = 9600, bits: int = 8, parity: Parity | None = None, stop: int = 1, timeout: float = 1, receiver_buffer_size: int = 64)
A bidirectional serial protocol
A common bidirectional serial protocol that uses an an agreed upon speed rather than a shared clock line.
- Parameters:
tx (Pin) – the pin to transmit with, or
Noneif thisUARTis receive-only.rx (Pin) – the pin to receive on, or
Noneif thisUARTis transmit-only.rts (Pin) – the pin for rts, or
Noneif rts not in use.cts (Pin) – the pin for cts, or
Noneif cts not in use.rs485_dir (Pin) – the output pin for rs485 direction setting, or
Noneif rs485 not in use.rs485_invert (bool) – rs485_dir pin active high when set. Active low otherwise.
baudrate (int) – the transmit and receive speed.
bits (int) – the number of bits per byte, 5 to 9.
parity (Parity) – the parity used for error checking.
stop (int) – the number of stop bits, 1 or 2.
timeout (float) – the timeout in seconds to wait for the first character and between subsequent characters when reading. Raises
ValueErrorif timeout >100 seconds.receiver_buffer_size (int) – the character length of the read buffer (0 to disable). (When a character is 9 bits the buffer will be 2 * receiver_buffer_size bytes.)
txandrxcannot both beNone.New in CircuitPython 4.0:
timeouthas incompatibly changed units from milliseconds to seconds. The new upper limit ontimeoutis meant to catch mistaken use of milliseconds.Limitations: RS485 is not supported on SAMD, nRF, Broadcom, Spresense, or STM. On i.MX and Raspberry Pi RP2040, RS485 support is implemented in software: The timing for the
rs485_dirpin signal is done on a best-effort basis, and may not meet RS485 specifications intermittently.- __exit__() None
Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.
- read(nbytes: int | None = None) bytes | None
Read bytes. If
nbytesis specified then read at most that many bytes. Otherwise, read everything that arrives until the connection times out. Providing the number of bytes expected is highly recommended because it will be faster. If no bytes are read, returnNone.Note
When no bytes are read due to a timeout, this function returns
None. This matches the behavior ofio.RawIOBase.readin Python 3, but differs from pyserial which returnsb''in that situation.- Returns:
Data read
- Return type:
bytes or None
- readinto(buf: circuitpython_typing.WriteableBuffer) int | None
Read bytes into the
buf. Read at mostlen(buf)bytes.- Returns:
number of bytes read and stored into
buf- Return type:
int or None (on a non-blocking error)
New in CircuitPython 4.0: No length parameter is permitted.
- readline() bytes
Read a line, ending in a newline character, or return
Noneif a timeout occurs sooner, or return everything readable if no newline is found andtimeout=0- Returns:
the line read
- Return type:
bytes or None