register_accessor.py

# SPDX-FileCopyrightText: Copyright (c) 2022 Max Holliday
# SPDX-FileCopyrightText: Copyright (c) 2025 Tim Cocks for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
`adafruit_register.register_accessor`
====================================================

SPI and I2C Register Accessor classes.

* Author(s): Max Holliday
* Adaptation by Tim Cocks
"""

__version__ = "0.0.0+auto.0"
__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Register.git"

try:
    from typing import Union

    from adafruit_bus_device.i2c_device import I2CDevice
    from adafruit_bus_device.spi_device import SPIDevice
except ImportError:
    pass


class RegisterAccessor:
    """
    Subclasses of this class will be used to provide read/write interface to registers
    over different bus types.

    :param int address_width: The width of the register addresses in bytes. Defaults to 1.
    :param bool lsb_first: Is the first byte we read from the bus the LSB? Defaults to true
    """

    address_width = None

    def __init__(self, address_width=1, lsb_first=True):
        self.address_width = address_width
        self.address_buffer = bytearray(address_width)
        self.lsb_first = lsb_first

    def _pack_address_into_buffer(self, address):
        if self.lsb_first:
            # Little-endian: least significant byte first
            for address_byte_i in range(self.address_width):
                self.address_buffer[address_byte_i] = (address >> (address_byte_i * 8)) & 0xFF
        else:
            # Big-endian: most significant byte first
            big_endian_address = address.to_bytes(self.address_width, byteorder="big")
            for address_byte_i in range(self.address_width):
                self.address_buffer[address_byte_i] = big_endian_address[address_byte_i]


class SPIRegisterAccessor(RegisterAccessor):
    """
    RegisterAccessor class for SPI bus transport. Provides interface to read/write
    registers over SPI.

    :param SPIDevice spi_device: The SPI bus device to communicate over.
    :param int address_width: The number of bytes in the address
    """

    def __init__(self, spi_device: SPIDevice, address_width: int = 1, lsb_first=True):
        super().__init__(address_width, lsb_first)
        self.spi_device = spi_device

    def _shift_rw_cmd_bit_into_first_byte(self, bit_value):
        if bit_value not in {0, 1}:
            raise ValueError("bit_value must be 0 or 1")

        # Clear the MSB (set bit 7 to 0)
        cleared_byte = self.address_buffer[0] & 0x7F
        # Set the MSB to the desired bit value
        self.address_buffer[0] = cleared_byte | (bit_value << 7)

    def read_register(self, address: int, buffer: bytearray):
        """
        Read register value over SPIDevice.

        :param int address: The register address to read.
        :param bytearray buffer: Buffer that will be used to read register data into.
          Buffer must be long enough to be read all data sent by the device.
        :return: None
        """

        self._pack_address_into_buffer(address)
        self._shift_rw_cmd_bit_into_first_byte(1)
        with self.spi_device as spi:
            spi.write(self.address_buffer)
            spi.readinto(buffer)

    def write_register(
        self,
        address: int,
        buffer: bytearray,
    ):
        """
        Write register value over SPIDevice.

        :param int address: The register address to read.
        :param bytearray buffer: Buffer that will be written to the register.
        :return: None
        """
        self._pack_address_into_buffer(address)
        self._shift_rw_cmd_bit_into_first_byte(0)
        with self.spi_device as spi:
            spi.write(self.address_buffer)
            spi.write(buffer)


class I2CRegisterAccessor(RegisterAccessor):
    """
    RegisterAccessor class for I2C bus transport. Provides interface to read/write
    registers over I2C

    :param I2CDevice i2c_device: I2C device to communicate over
    :param int address_width: The number of bytes in the address
    """

    def __init__(self, i2c_device: I2CDevice, address_width: int = 1, lsb_first=True):
        super().__init__(address_width, lsb_first)
        self.i2c_device = i2c_device

        # buffer that will hold address + data for write operations, will grow as needed
        self._full_buffer = bytearray(address_width + 1)

    def read_register(self, address: int, buffer: bytearray):
        """
        Read register value over I2CDevice.

        :param int address: The register address to read.
        :param bytearray buffer: Buffer that will be used to read register data into.
          Buffer must be long enough to be read all data sent by the device.
        :return: None
        """

        self._pack_address_into_buffer(address)
        with self.i2c_device as i2c:
            i2c.write_then_readinto(self.address_buffer, buffer)

    def write_register(self, address: int, buffer: bytearray):
        """
        Write register value over I2CDevice.

        :param int address: The register address to read.
        :param bytearray buffer: Buffer of data that will be written to the register.

        :return: None
        """
        # grow full buffer if needed
        if self.address_width + len(buffer) > len(self._full_buffer):
            self._full_buffer = bytearray(self.address_width + len(buffer))

        # put address into full buffer
        self._pack_address_into_buffer(address)
        for i in range(self.address_width):
            self._full_buffer[i] = self.address_buffer[i]

        # put data into full buffer
        for i, b in enumerate(buffer):
            self._full_buffer[i + self.address_width] = b

        with self.i2c_device as i2c:
            i2c.write(self._full_buffer)