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
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
I2CDevice
to 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
Note
On the nRF52840, only one I2C object may be created, except on the Circuit Playground Bluefruit, which allows two, one for the onboard accelerometer, and one for offboard use.
-
__enter__
(self) → I2C¶ No-op used in Context Managers.
-
__exit__
(self) → None¶ Automatically deinitializes the hardware on context exit. See Lifetime and ContextManagers for more info.
-
scan
(self) → 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
(self) → bool¶ Attempts to grab the I2C lock. Returns True on success.
- Returns
True when lock has been grabbed
- Return type
-
readfrom_into
(self, address: int, buffer: WriteableBuffer, *, start: int = 0, end: Optional[int] = None) → None¶ Read into
buffer
from the device selected byaddress
. The number of bytes read will be the length ofbuffer
. At least one byte must be read.If
start
orend
is provided, then the buffer will be sliced as ifbuffer[start:end]
. This will not cause an allocation likebuf[start:end]
will so it saves memory.- Parameters
address (int) – 7-bit device address
buffer (WriteableBuffer) – 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) → None¶ Write the bytes from
buffer
to the device selected byaddress
and then transmit a stop bit.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.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
(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) → None¶ Write the bytes from
out_buffer
to the device selected byaddress
, generate no stop bit, generate a repeated start and read intoin_buffer
.out_buffer
andin_buffer
can be the same buffer because they are used sequentially.if
start
orend
is provided, then the corresponding buffer will be sliced as ifbuffer[start:end]
. This will not cause an allocation likebuf[start:end]
will so it saves memory.- Parameters
address (int) – 7-bit device address
out_buffer (ReadbleBuffer) – buffer containing the bytes to write
in_buffer (WriteableBuffer) – 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
(formerly Dallas Semi) OneWire protocol.
Protocol definition is here: https://www.maximintegrated.com/en/app-notes/index.mvp/id/126
-
class
OneWire
(pin)¶ Create a OneWire object associated with the given pin. The object implements the lowest level timing-sensitive bits of the protocol.
- Parameters
pin (Pin) – Pin connected to the OneWire bus
Read a short series of pulses:
import busio import board onewire = busio.OneWire(board.D7) onewire.reset() onewire.write_bit(True) onewire.write_bit(False) print(onewire.read_bit())
-
__enter__
(self) → OneWire¶ No-op used by Context Managers.
-
__exit__
(self) → None¶ Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.
-
class
-
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 abbreviatedCS
orSS
. (This is common because multiple secondaries can share theclock
,MOSI
andMISO
lines 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
SPIDevice
to 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
-
frequency
:int¶ The actual SPI bus frequency. This may not match the frequency requested due to internal limitations.
-
__enter__
(self) → SPI¶ No-op used by Context Managers. Provided by context manager helper.
-
__exit__
(self) → None¶ 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) → 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
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) → bool¶ Attempts to grab the SPI lock. Returns True on success.
- Returns
True when lock has been grabbed
- Return type
-
write
(self, buffer: ReadableBuffer, *, start: int = 0, end: Optional[int] = None) → None¶ Write the data contained in
buffer
. The SPI object must be locked. If the buffer is empty, nothing happens.- Parameters
buffer (ReadableBuffer) – 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) → None¶ Read into
buffer
while writingwrite_value
for each byte read. The SPI object must be locked. If the number of bytes to read is 0, nothing happens.- Parameters
buffer (WriteableBuffer) – 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: WriteableBuffer, *, out_start: int = 0, out_end: Optional[int] = None, in_start: int = 0, in_end: Optional[int] = None) → None¶ Write out the data in
buffer_out
while simultaneously reading data intobuffer_in
. The SPI object must be locked. The lengths of the slices defined bybuffer_out[out_start:out_end]
andbuffer_in[in_start:in_end]
must be equal. If buffer slice lengths are both 0, nothing happens.- Parameters
buffer_out (ReadableBuffer) – Write out the data in this buffer
buffer_in (WriteableBuffer) – 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
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
None
if thisUART
is receive-only.rx (Pin) – the pin to receive on, or
None
if thisUART
is transmit-only.rts (Pin) – the pin for rts, or
None
if rts not in use.cts (Pin) – the pin for cts, or
None
if cts not in use.rs485_dir (Pin) – the output pin for rs485 direction setting, or
None
if 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, 7, 8 or 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
ValueError
if 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.)
New in CircuitPython 4.0:
timeout
has incompatibly changed units from milliseconds to seconds. The new upper limit ontimeout
is meant to catch mistaken use of milliseconds.-
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).
-
__enter__
(self) → UART¶ No-op used by Context Managers.
-
__exit__
(self) → None¶ Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.
-
read
(self, nbytes: Optional[int] = None) → Optional[bytes]¶ 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.
-
readinto
(self, buf: WriteableBuffer) → Optional[int]¶ Read bytes into the
buf
. Read at mostlen(buf)
bytes.New in CircuitPython 4.0: No length parameter is permitted.
-
readline
(self) → bytes¶ - 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