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.

class busio.I2C(scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int = 255)

Two wire serial protocol

deinit(self)

Releases control of the underlying hardware so other classes can use it.

__enter__(self)

No-op used in Context Managers.

__exit__(self)

Automatically deinitializes the hardware on context exit. See Lifetime and ContextManagers for more info.

scan(self)

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:list
try_lock(self)

Attempts to grab the I2C lock. Returns True on success.

Returns:True when lock has been grabbed
Return type:bool
unlock(self)

Releases the I2C lock.

readfrom_into(self, address: int, buffer: WriteableBuffer, *, start: int = 0, end: Optional[int] = None)

Read into buffer from the device selected by address. The number of bytes read will be the length of buffer. At least one byte must be read.

If start or end is provided, then the buffer will be sliced as if buffer[start:end]. This will not cause an allocation like buf[start:end] will so it saves memory.

Parameters:
  • address (int) – 7-bit device address
  • buffer (bytearray) – buffer to write into
  • start (int) – Index to start writing at
  • end (int) – Index to write up to but not include. Defaults to len(buffer)
writeto(self, address: int, buffer: ReadableBuffer, *, start: int = 0, end: Optional[int] = None, stop: bool = True)

Write the bytes from buffer to the device selected by address and then transmit a stop bit.

If start or end is provided, then the buffer will be sliced as if buffer[start:end]. This will not cause an allocation like buffer[start:end] will so it saves memory.

Writing a buffer or slice of length zero is permitted, as it can be used to poll for the existence of a device.

Parameters:
  • address (int) – 7-bit device address
  • buffer (bytearray) – buffer containing the bytes to write
  • start (int) – Index to start writing from
  • end (int) – Index to read up to but not include. Defaults to len(buffer)
writeto_then_readfrom(self, address: int, out_buffer: ReadableBuffer, in_buffer: WriteableBuffer, *, out_start: int = 0, out_end: Optional[int] = None, in_start: int = 0, in_end: Optional[int] = None)

Write the bytes from out_buffer to the device selected by address, generate no stop bit, generate a repeated start and read into in_buffer. out_buffer and in_buffer can be the same buffer because they are used sequentially.

if start or end is provided, then the corresponding buffer will be sliced as if buffer[start:end]. This will not cause an allocation like buf[start:end] will so it saves memory.

Parameters:
  • address (int) – 7-bit device address
  • out_buffer (bytearray) – buffer containing the bytes to write
  • in_buffer (bytearray) – buffer to write into
  • out_start (int) – Index to start writing from
  • out_end (int) – Index to read up to but not include. Defaults to len(buffer)
  • in_start (int) – Index to start writing at
  • in_end (int) – Index to write up to but not include. Defaults to len(buffer)
class busio.OneWire(pin: microcontroller.Pin)

Lowest-level of the Maxim OneWire protocol

deinit(self)

Deinitialize the OneWire bus and release any hardware resources for reuse.

__enter__(self)

No-op used by Context Managers.

__exit__(self)

Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.

reset(self)

Reset the OneWire bus and read presence

Returns:False when at least one device is present
Return type:bool
read_bit(self)

Read in a bit

Returns:bit state read
Return type:bool
write_bit(self, value: bool)

Write out a bit based on value.

class busio.SPI(clock: microcontroller.Pin, MOSI: Optional[microcontroller.Pin] = None, MISO: Optional[microcontroller.Pin] = None)

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 I2C because 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 abbreviated CS or SS. (This is common because multiple secondaries can share the clock, MOSI and MISO lines and therefore the hardware.)

frequency :int

The actual SPI bus frequency. This may not match the frequency requested due to internal limitations.

deinit(self)

Turn off the SPI bus.

__enter__(self)

No-op used by Context Managers. Provided by context manager helper.

__exit__(self)

Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.

configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8)

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 frequency attribute 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(self)

Attempts to grab the SPI lock. Returns True on success.

Returns:True when lock has been grabbed
Return type:bool
unlock(self)

Releases the SPI lock.

write(self, buffer: ReadableBuffer, *, start: int = 0, end: Optional[int] = None)

Write the data contained in buffer. The SPI object must be locked. If the buffer is empty, nothing happens.

Parameters:
  • buffer (bytearray) – Write out the data in this buffer
  • start (int) – Start of the slice of buffer to write out: buffer[start:end]
  • end (int) – End of the slice; this index is not included. Defaults to len(buffer)
readinto(self, buffer: WriteableBuffer, *, start: int = 0, end: Optional[int] = None, write_value: int = 0)

Read into buffer while writing write_value for each byte read. The SPI object must be locked. If the number of bytes to read is 0, nothing happens.

Parameters:
  • buffer (bytearray) – Read data into this buffer
  • start (int) – Start of the slice of buffer to read into: buffer[start:end]
  • end (int) – End of the slice; this index is not included. Defaults to len(buffer)
  • write_value (int) – Value to write while reading. (Usually ignored.)
write_readinto(self, buffer_out: ReadableBuffer, buffer_in: ReadableBuffer, *, out_start: int = 0, out_end: Optional[int] = None, in_start: int = 0, in_end: Optional[int] = None)

Write out the data in buffer_out while simultaneously reading data into buffer_in. The SPI object must be locked. The lengths of the slices defined by buffer_out[out_start:out_end] and buffer_in[in_start:in_end] must be equal. If buffer slice lengths are both 0, nothing happens.

Parameters:
  • buffer_out (bytearray) – Write out the data in this buffer
  • buffer_in (bytearray) – Read data into this buffer
  • out_start (int) – Start of the slice of buffer_out to write out: buffer_out[out_start:out_end]
  • out_end (int) – End of the slice; this index is not included. Defaults to len(buffer_out)
  • in_start (int) – Start of the slice of buffer_in to read into: buffer_in[in_start:in_end]
  • in_end (int) – End of the slice; this index is not included. Defaults to len(buffer_in)
class busio.UART(tx: microcontroller.Pin, rx: microcontroller.Pin, *, baudrate: int = 9600, bits: int = 8, parity: Optional[Parity] = None, stop: int = 1, timeout: float = 1, receiver_buffer_size: int = 64)

A bidirectional serial protocol

baudrate :int

The current baudrate.

in_waiting :int

The number of bytes in the input buffer, available to be read

timeout :float

The current timeout, in seconds (float).

deinit(self)

Deinitialises the UART and releases any hardware resources for reuse.

__enter__(self)

No-op used by Context Managers.

__exit__(self)

Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.

read(self, nbytes: Optional[int] = None)

Read characters. If nbytes is 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.

Returns:Data read
Return type:bytes or None
readinto(self, buf: WriteableBuffer)

Read bytes into the buf. Read at most len(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(self)
Read a line, ending in a newline character, or
return None if a timeout occurs sooner, or return everything readable if no newline is found and timeout=0
Returns:the line read
Return type:bytes or None
write(self, buf: WriteableBuffer)

Write the buffer of bytes to the bus.

New in CircuitPython 4.0: buf must be bytes, not a string.

return:the number of bytes written
rtype:int or None
reset_input_buffer(self)

Discard any unread characters in the input buffer.

class busio.Parity

Enum-like class to define the parity used to verify correct data transfer.

ODD :int

Total number of ones should be odd.

EVEN :int

Total number of ones should be even.