:mod:`busio` ============ .. py:module:: busio .. autoapi-nested-parse:: 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 :py:meth:`!deinit` or use a context manager. See :ref:`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 :py:meth:`~busio.I2C.scan` and then :py:meth:`~busio.I2C.deinit` the hardware. The last step is optional because CircuitPython automatically resets hardware after a program finishes. .. py:class:: I2C(scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int = 255) Two wire serial protocol .. method:: deinit(self) Releases control of the underlying hardware so other classes can use it. .. method:: __enter__(self) No-op used in Context Managers. .. method:: __exit__(self) Automatically deinitializes the hardware on context exit. See :ref:`lifetime-and-contextmanagers` for more info. .. method:: scan(self) Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of those that respond. :return: List of device ids on the I2C bus :rtype: list .. method:: try_lock(self) Attempts to grab the I2C lock. Returns True on success. :return: True when lock has been grabbed :rtype: bool .. method:: unlock(self) Releases the I2C lock. .. method:: readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: 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. :param int address: 7-bit device address :param bytearray buffer: buffer to write into :param int start: Index to start writing at :param int end: Index to write up to but not include. Defaults to ``len(buffer)`` .. method:: writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) Write the bytes from ``buffer`` to the device selected by ``address``. Transmits a stop bit when stop is True. Setting stop=False is deprecated and stop will be removed in CircuitPython 6.x. 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]``. 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. :param int address: 7-bit device address :param bytearray buffer: buffer containing the bytes to write :param int start: Index to start writing from :param int end: Index to read up to but not include. Defaults to ``len(buffer)`` :param bool stop: If true, output an I2C stop condition after the buffer is written. Deprecated. Will be removed in 6.x and act as stop=True. .. method:: writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: 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. :param int address: 7-bit device address :param bytearray out_buffer: buffer containing the bytes to write :param bytearray in_buffer: buffer to write into :param int out_start: Index to start writing from :param int out_end: Index to read up to but not include. Defaults to ``len(buffer)`` :param int in_start: Index to start writing at :param int in_end: Index to write up to but not include. Defaults to ``len(buffer)`` .. py:class:: OneWire(pin: microcontroller.Pin) Lowest-level of the Maxim OneWire protocol .. method:: deinit(self) Deinitialize the OneWire bus and release any hardware resources for reuse. .. method:: __enter__(self) No-op used by Context Managers. .. method:: __exit__(self) Automatically deinitializes the hardware when exiting a context. See :ref:`lifetime-and-contextmanagers` for more info. .. method:: reset(self) Reset the OneWire bus and read presence :returns: False when at least one device is present :rtype: bool .. method:: read_bit(self) Read in a bit :returns: bit state read :rtype: bool .. method:: write_bit(self, value: Any) Write out a bit based on value. .. py:class:: SPI(clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: 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 :py:class:`~bitbangio.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.) .. attribute:: frequency :annotation: :Any The actual SPI bus frequency. This may not match the frequency requested due to internal limitations. .. method:: deinit(self) Turn off the SPI bus. .. method:: __enter__(self) No-op used by Context Managers. Provided by context manager helper. .. method:: __exit__(self) Automatically deinitializes the hardware when exiting a context. See :ref:`lifetime-and-contextmanagers` for more info. .. method:: configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) Configures the SPI bus. The SPI object must be locked. :param int baudrate: 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. :param int polarity: the base state of the clock line (0 or 1) :param int phase: the edge of the clock that data is captured. First (0) or second (1). Rising or falling depends on clock polarity. :param int bits: 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). .. method:: try_lock(self) Attempts to grab the SPI lock. Returns True on success. :return: True when lock has been grabbed :rtype: bool .. method:: unlock(self) Releases the SPI lock. .. method:: write(self, buffer: bytearray, *, start: Any = 0, end: int = None) Write the data contained in ``buffer``. The SPI object must be locked. If the buffer is empty, nothing happens. :param bytearray buffer: Write out the data in this buffer :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` .. method:: readinto(self, buffer: bytearray, *, start: Any = 0, end: 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. :param bytearray buffer: Read data into this buffer :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` :param int write_value: Value to write while reading. (Usually ignored.) .. method:: write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: 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. :param bytearray buffer_out: Write out the data in this buffer :param bytearray buffer_in: Read data into this buffer :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)`` .. py:class:: UART(tx: microcontroller.Pin, rx: microcontroller.Pin, *, baudrate: int = 9600, bits: int = 8, parity: Parity = None, stop: int = 1, timeout: float = 1, receiver_buffer_size: int = 64) A bidirectional serial protocol .. attribute:: baudrate :annotation: :Any The current baudrate. .. attribute:: in_waiting :annotation: :Any The number of bytes in the input buffer, available to be read .. attribute:: timeout :annotation: :Any The current timeout, in seconds (float). .. method:: deinit(self) Deinitialises the UART and releases any hardware resources for reuse. .. method:: __enter__(self) No-op used by Context Managers. .. method:: __exit__(self) Automatically deinitializes the hardware when exiting a context. See :ref:`lifetime-and-contextmanagers` for more info. .. method:: read(self, nbytes: Any = 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. :return: Data read :rtype: bytes or None .. method:: readinto(self, buf: Any) Read bytes into the ``buf``. Read at most ``len(buf)`` bytes. :return: number of bytes read and stored into ``buf`` :rtype: int or None (on a non-blocking error) *New in CircuitPython 4.0:* No length parameter is permitted. .. method:: 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 :return: the line read :rtype: bytes or None .. method:: write(self, buf: Any) 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 .. method:: reset_input_buffer(self) .. py:class:: Parity Enum-like class to define the parity used to verify correct data transfer. .. attribute:: ODD :annotation: :Any Total number of ones should be odd. .. attribute:: EVEN :annotation: :Any Total number of ones should be even.