:mod:`i2cperipheral`
====================

.. py:module:: i2cperipheral

.. autoapi-nested-parse::

   Two wire serial protocol peripheral

   The `i2cperipheral` module contains classes to support an I2C peripheral.

   Example emulating a peripheral with 2 addresses (read and write)::

     import board
     from i2cperipheral import I2CPeripheral

     regs = [0] * 16
     index = 0

     with I2CPeripheral(board.SCL, board.SDA, (0x40, 0x41)) as device:
         while True:
             r = device.request()
             if not r:
                 # Maybe do some housekeeping
                 continue
             with r:  # Closes the transfer if necessary by sending a NACK or feeding dummy bytes
                 if r.address == 0x40:
                     if not r.is_read:  # Main write which is Selected read
                         b = r.read(1)
                         if not b or b[0] > 15:
                             break
                         index = b[0]
                         b = r.read(1)
                         if b:
                             regs[index] = b[0]
                     elif r.is_restart:  # Combined transfer: This is the Main read message
                         n = r.write(bytes([regs[index]]))
                     #else:
                         # A read transfer is not supported in this example
                         # If the microcontroller tries, it will get 0xff byte(s) by the ctx manager (r.close())
                 elif r.address == 0x41:
                     if not r.is_read:
                         b = r.read(1)
                         if b and b[0] == 0xde:
                             # do something
                             pass

   This example sets up an I2C device that can be accessed from Linux like this::

     $ i2cget -y 1 0x40 0x01
     0x00
     $ i2cset -y 1 0x40 0x01 0xaa
     $ i2cget -y 1 0x40 0x01
     0xaa

   .. warning::
      I2CPeripheral makes use of clock stretching in order to slow down
      the host.
      Make sure the I2C host supports this.

      Raspberry Pi in particular does not support this with its I2C hw block.
      This can be worked around by using the ``i2c-gpio`` bit banging driver.
      Since the RPi firmware uses the hw i2c, it's not possible to emulate a HAT eeprom.





.. py:class:: I2CPeripheral(scl: microcontroller.Pin, sda: microcontroller.Pin, addresses: tuple, smbus: bool = False)

   Two wire serial protocol peripheral

   .. 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:: request(self, timeout: float = -1)


      Wait for an I2C request.

      :param float timeout: Timeout in seconds. Zero means wait forever, a negative value means check once
      :return: I2C Slave Request or None if timeout=-1 and there's no request
      :rtype: ~i2cperipheral.I2CPeripheralRequest



.. py:class:: I2CPeripheralRequest(peripheral: i2cperipheral.I2CPeripheral, address: int, is_read: bool, is_restart: bool)

   .. attribute:: address
      :annotation: :int

      The I2C address of the request.


   .. attribute:: is_read
      :annotation: :bool

      The I2C main controller is reading from this peripheral.


   .. attribute:: is_restart
      :annotation: :bool

      Is Repeated Start Condition.


   .. method:: __enter__(self)


      No-op used in Context Managers.


   .. method:: __exit__(self)


      Close the request.


   .. method:: read(self, n: int = -1, ack: bool = True)


      Read data.
      If ack=False, the caller is responsible for calling :py:meth:`I2CPeripheralRequest.ack`.

      :param n: Number of bytes to read (negative means all)
      :param ack: Whether or not to send an ACK after the n'th byte
      :return: Bytes read


   .. method:: write(self, buffer: bytearray)


      Write the data contained in buffer.

      :param buffer: Write out the data in this buffer
      :return: Number of bytes written


   .. method:: ack(self, ack: bool = True)


      Acknowledge or Not Acknowledge last byte received.
      Use together with :py:meth:`I2CPeripheralRequest.read` ack=False.

      :param ack: Whether to send an ACK or NACK