bitbangio – Digital protocols implemented by the CPU¶
The bitbangio module contains classes to provide digital bus protocol
support regardless of whether the underlying hardware exists to use the
protocol.
First try to use busio module instead which may utilize peripheral
hardware to implement the protocols. Native implementations will be faster
than bitbanged versions and have more capabilities.
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 bitbangio
from board import *
i2c = bitbangio.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.
Available on these boards
- class bitbangio.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
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. A device responds if it pulls the SDA line low after its address (including a read bit) is sent on the bus.
- readfrom_into(address: int, buffer: circuitpython_typing.WriteableBuffer, *, start: int = 0, end: int = sys.maxsize) None¶
Read into
bufferfrom the device selected byaddress. The number of bytes read will be the length ofbuffer. At least one byte must be read.If
startorendis 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.
- 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 transmits a stop bit. Usewriteto_then_readfromwhen needing a write, no stop and repeated start before a 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 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.ReadableBuffer, *, 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]. :param int address: 7-bit device address :param ~circuitpython_typing.ReadableBuffer out_buffer: buffer containing the bytes to write :param ~circuitpython_typing.WriteableBuffer in_buffer: buffer to write into :param int out_start: beginning ofout_bufferslice :param int out_end: end ofout_bufferslice; if not specified, uselen(out_buffer):param int in_start: beginning ofin_bufferslice :param int in_end: end ofin_buffer slice; if not specified, uselen(in_buffer)
- class bitbangio.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
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.
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
- __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. Only valid when locked.
- try_lock() bool¶
Attempts to grab the SPI lock. Returns True on success.
- Returns
True when lock has been grabbed
- Return type
- write(buf: circuitpython_typing.ReadableBuffer) None¶
Write the data contained in
buf. Requires the SPI being locked. If the buffer is empty, nothing happens.
- 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].
- 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)