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
  • AITHinker ESP32-C3S_Kit
  • ARAMCON Badge 2019
  • ARAMCON2 Badge
  • ATMegaZero ESP32-S2
  • Adafruit CLUE nRF52840 Express
  • Adafruit Circuit Playground Bluefruit
  • Adafruit Circuit Playground Express 4-H
  • Adafruit CircuitPlayground Express
  • Adafruit EdgeBadge
  • Adafruit Feather Bluefruit Sense
  • Adafruit Feather M4 CAN
  • Adafruit Feather M4 Express
  • Adafruit Feather MIMXRT1011
  • Adafruit Feather RP2040
  • Adafruit Feather STM32F405 Express
  • Adafruit Feather nRF52840 Express
  • Adafruit FunHouse
  • Adafruit Grand Central M4 Express
  • Adafruit Hallowing M4 Express
  • Adafruit ItsyBitsy M4 Express
  • Adafruit ItsyBitsy RP2040
  • Adafruit ItsyBitsy nRF52840 Express
  • Adafruit LED Glasses Driver nRF52840
  • Adafruit Macropad RP2040
  • Adafruit MagTag
  • Adafruit Matrix Portal M4
  • Adafruit Metro ESP32S2
  • Adafruit Metro M4 Airlift Lite
  • Adafruit Metro M4 Express
  • Adafruit Metro nRF52840 Express
  • Adafruit Monster M4SK
  • Adafruit PyGamer
  • Adafruit PyPortal
  • Adafruit PyPortal Pynt
  • Adafruit PyPortal Titano
  • Adafruit Pybadge
  • Adafruit QT Py RP2040
  • Adafruit QT2040 Trinkey
  • Adafruit Trellis M4 Express
  • AloriumTech Evo M51
  • Arduino Nano 33 BLE
  • Arduino Nano RP2040 Connect
  • Artisense Reference Design RD00
  • AtelierDuMaker nRF52840 Breakout
  • BDMICRO VINA-D51
  • BLE-SS dev board Multi Sensor
  • BastBLE
  • BastWiFi
  • BlueMicro840
  • CP32-M4
  • Capable Robot Programmable USB Hub
  • Challenger NB RP2040 WiFi
  • Challenger RP2040 LTE
  • Challenger RP2040 WiFi
  • Circuit Playground Express Digi-Key PyCon 2019
  • CircuitBrains Deluxe
  • CrumpS2
  • Cytron Maker Pi RP2040
  • DynOSSAT-EDU-OBC
  • ESP 12k NodeMCU
  • Electronut Labs Blip
  • Electronut Labs Papyr
  • EncoderPad RP2040
  • Espruino Pico
  • Espruino Wifi
  • Feather ESP32S2 without PSRAM
  • Feather MIMXRT1011
  • Feather MIMXRT1062
  • FeatherS2
  • FeatherS2 Neo
  • FeatherS2 PreRelease
  • Franzininho WIFI w/Wroom
  • Franzininho WIFI w/Wrover
  • Gravitech Cucumber M
  • Gravitech Cucumber MS
  • Gravitech Cucumber R
  • Gravitech Cucumber RS
  • HMI-DevKit-1.1
  • HiiBot BlueFi
  • IMXRT1010-EVK
  • IkigaiSense Vita nRF52840
  • Kaluga 1
  • LILYGO TTGO T8 ESP32-S2 w/Display
  • MDBT50Q-DB-40
  • MDBT50Q-RX Dongle
  • MEOWBIT
  • MORPHEANS MorphESP-240
  • MakerDiary nRF52840 MDK
  • MakerDiary nRF52840 MDK USB Dongle
  • Makerdiary M60 Keyboard
  • Makerdiary Pitaya Go
  • Makerdiary nRF52840 M.2 Developer Kit
  • Melopero Shake RP2040
  • Metro MIMXRT1011
  • MicroDev microC3
  • MicroDev microS2
  • Mini SAM M4
  • NUCLEO STM32F746
  • NUCLEO STM32F767
  • NUCLEO STM32H743
  • OPENMV-H7 R1
  • Oak Dev Tech BREAD2040
  • Oak Dev Tech PixelWing ESP32S2
  • Open Hardware Summit 2020 Badge
  • PCA10056 nRF52840-DK
  • PCA10059 nRF52840 Dongle
  • PYB LR Nano V2
  • Particle Argon
  • Particle Boron
  • Particle Xenon
  • Pimoroni Interstate 75
  • Pimoroni Keybow 2040
  • Pimoroni PGA2040
  • Pimoroni Pico LiPo (16MB)
  • Pimoroni Pico LiPo (4MB)
  • Pimoroni PicoSystem
  • Pimoroni Plasma 2040
  • Pimoroni Tiny 2040
  • PyCubedv04
  • PyCubedv04-MRAM
  • PyCubedv05
  • PyCubedv05-MRAM
  • PyKey60
  • PyboardV1_1
  • Raspberry Pi Pico
  • Robo HAT MM1 M4
  • S2Mini
  • S2Pico
  • SAM E54 Xplained Pro
  • SAM32v26
  • SPRESENSE
  • ST STM32F746G Discovery
  • STM32F411E_DISCO
  • STM32F412G_DISCO
  • STM32F4_DISCO
  • Saola 1 w/Wroom
  • Saola 1 w/Wrover
  • Seeeduino Wio Terminal
  • Silicognition LLC M4-Shim
  • Simmel
  • SparkFun MicroMod RP2040 Processor
  • SparkFun MicroMod SAMD51 Processor
  • SparkFun MicroMod nRF52840 Processor
  • SparkFun Pro Micro RP2040
  • SparkFun Pro nRF52840 Mini
  • SparkFun STM32 MicroMod Processor
  • SparkFun Thing Plus - RP2040
  • SparkFun Thing Plus - SAMD51
  • Sprite_v2b
  • Swan R5
  • TG-Boards' Datalore IP M4
  • TG-Watch
  • THUNDERPACK_v11
  • THUNDERPACK_v12
  • Targett Module Clip w/Wroom
  • Targett Module Clip w/Wrover
  • Teensy 4.0
  • Teensy 4.1
  • Teknikio Bluebird
  • The Open Book Feather
  • TinkeringTech ScoutMakes Azul
  • TinyS2
  • UARTLogger II
  • WarmBit BluePixel nRF52840
  • Winterbloom Sol
  • iMX RT 1020 EVK
  • iMX RT 1060 EVK
  • nanoESP32-S2 w/Wrover
  • nanoESP32-S2 w/Wroom
  • nice!nano
  • stm32f411ce-blackpill
  • stm32f411ce-blackpill-with-flash

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 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
  • scl (Pin) – The clock pin

  • sda (Pin) – The data pin

  • frequency (int) – The clock frequency of the bus

  • timeout (int) – The maximum clock stretching timeout in microseconds

deinit(self)None

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

__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. A device responds if it pulls the SDA line low after its address (including a read bit) is sent on the bus.

try_lock(self)bool

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

unlock(self)None

Releases the I2C lock.

readfrom_into(self, address: int, buffer: _typing.WriteableBuffer, *, start: int = 0, end: int = sys.maxsize)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 (WriteableBuffer) – buffer to write into

  • start (int) – Index to start writing at

  • end (int) – Index to write up to but not include

writeto(self, address: int, buffer: _typing.ReadableBuffer, *, start: int = 0, end: int = sys.maxsize)None

Write the bytes from buffer to the device selected by address and then transmits a stop bit. Use writeto_then_readfrom when needing a write, no stop and repeated start before a read.

If start or end is provided, then the buffer will be sliced as if buffer[start:end] were passed, but without copying the data. The number of bytes written will be the length of buffer[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.

Parameters
  • address (int) – 7-bit device address

  • buffer (ReadableBuffer) – buffer containing the bytes to write

  • start (int) – beginning of buffer slice

  • end (int) – end of buffer slice; if not specified, use len(buffer)

writeto_then_readfrom(self, address: int, out_buffer: _typing.ReadableBuffer, in_buffer: _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_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 out_start or out_end is provided, then the buffer will be sliced as if out_buffer[out_start:out_end] were passed, but without copying the data. The number of bytes written will be the length of out_buffer[start:end].

If in_start or in_end is provided, then the input buffer will be sliced as if in_buffer[in_start:in_end] were passed, The number of bytes read will be the length of out_buffer[in_start:in_end]. :param int address: 7-bit device address :param ~_typing.ReadableBuffer out_buffer: buffer containing the bytes to write :param ~_typing.WriteableBuffer in_buffer: buffer to write into :param int out_start: beginning of out_buffer slice :param int out_end: end of out_buffer slice; if not specified, use len(out_buffer) :param int in_start: beginning of in_buffer slice :param int in_end: end of in_buffer slice; if not specified, use len(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 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.)

Construct an SPI object on the given pins.

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
  • clock (Pin) – the pin to use for the clock.

  • MOSI (Pin) – the Main Out Selected In pin.

  • MISO (Pin) – the Main In Selected Out pin.

deinit(self)None

Turn off the SPI bus.

__enter__(self)SPI

No-op used by Context Managers.

__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. Only valid when locked.

Parameters
  • baudrate (int) – the clock rate in Hertz

  • 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

try_lock(self)bool

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

Returns

True when lock has been grabbed

Return type

bool

unlock(self)None

Releases the SPI lock.

write(self, buf: _typing.ReadableBuffer)None

Write the data contained in buf. Requires the SPI being locked. If the buffer is empty, nothing happens.

readinto(self, buffer: _typing.WriteableBuffer, *, start: int = 0, end: int = sys.maxsize, write_value: int = 0)None

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.

If start or end is provided, then the buffer will be sliced as if buffer[start:end] were passed. The number of bytes read will be the length of buffer[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, use len(buffer)

  • write_value (int) – value to write while reading

write_readinto(self, out_buffer: _typing.ReadableBuffer, in_buffer: _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_buffer while simultaneously reading data into in_buffer. The SPI object must be locked.

If out_start or out_end is provided, then the buffer will be sliced as if out_buffer[out_start:out_end] were passed, but without copying the data. The number of bytes written will be the length of out_buffer[out_start:out_end].

If in_start or in_end is provided, then the input buffer will be sliced as if in_buffer[in_start:in_end] were passed, The number of bytes read will be the length of out_buffer[in_start:in_end].

The lengths of the slices defined by out_buffer[out_start:out_end] and in_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_buffer slice

  • out_end (int) – end of out_buffer slice; if not specified, use len(out_buffer)

  • in_start (int) – beginning of in_buffer slice

  • in_end (int) – end of in_buffer slice; if not specified, use len(in_buffer)