.. currentmodule:: machine
.. _machine.I2CTarget:

class I2CTarget -- an I2C target device
=======================================

An I2C target is a device which connects to an I2C bus and is controlled by an
I2C controller.  I2C targets can take many forms.  The :class:`machine.I2CTarget`
class implements an I2C target that can be configured as a memory/register device,
or as an arbitrary I2C device by using callbacks (if supported by the port).

Example usage for the case of a memory device::

    from machine import I2CTarget

    # Create the backing memory for the I2C target.
    mem = bytearray(8)

    # Create an I2C target.  Depending on the port, extra parameters
    # may be required to select the peripheral and/or pins to use.
    i2c = I2CTarget(addr=67, mem=mem)

    # At this point an I2C controller can read and write `mem`.
    ...

    # Deinitialise the I2C target.
    i2c.deinit()

Note that some ports require an ``id``, and maybe ``scl`` and ``sda`` pins, to be
passed to the `I2CTarget` constructor, to select the hardware I2C instance and
pins that it connects to.

When configured as a memory device, it's also possible to register to receive events.
For example to be notified when the memory is read/written::

    from machine import I2CTarget

    # Define an IRQ handler, for I2C events.
    def irq_handler(i2c_target):
        flags = i2c_target.irq().flags()
        if flags & I2CTarget.IRQ_END_READ:
            print("controller read target at addr", i2c_target.memaddr)
        if flags & I2CTarget.IRQ_END_WRITE:
            print("controller wrote target at addr", i2c_target.memaddr)

    # Create the I2C target and register to receive default events.
    mem = bytearray(8)
    i2c = I2CTarget(addr=67, mem=mem)
    i2c.irq(irq_handler)

More complicated I2C devices can be implemented using the full set of events.  For
example, to see the raw events as they are triggered::

    from machine import I2CTarget

    # Define an IRQ handler that prints the event id and responds to reads/writes.
    def irq_handler(i2c_target, buf=bytearray(1)):
        flags = i2c_target.irq().flags()
        print(flags)
        if flags & I2CTarget.IRQ_READ_REQ:
            i2c_target.write(buf)
        if flags & I2CTarget.IRQ_WRITE_REQ:
            i2c_target.readinto(buf)

    # Create the I2C target and register to receive all events.
    i2c = I2CTarget(addr=67)
    all_triggers = (
        I2CTarget.IRQ_ADDR_MATCH_READ
        | I2CTarget.IRQ_ADDR_MATCH_WRITE
        | I2CTarget.IRQ_READ_REQ
        | I2CTarget.IRQ_WRITE_REQ
        | I2CTarget.IRQ_END_READ
        | I2CTarget.IRQ_END_WRITE
    )
    i2c.irq(irq_handler, trigger=all_triggers, hard=True)

Constructors
------------

.. class:: I2CTarget(id, addr, *, addrsize=7, mem=None, mem_addrsize=8, scl=None, sda=None)

   Construct and return a new I2CTarget object using the following parameters:

      - *id* identifies a particular I2C peripheral.  Allowed values depend on the
        particular port/board.  Some ports have a default in which case this parameter
        can be omitted.
      - *addr* is the I2C address of the target.
      - *addrsize* is the number of bits in the I2C target address.  Valid values
        are 7 and 10.
      - *mem* is an object with the buffer protocol that is writable.  If not
        specified then there is no backing memory and data must be read/written
        using the :meth:`I2CTarget.readinto` and :meth:`I2CTarget.write` methods.
      - *mem_addrsize* is the number of bits in the memory address.  Valid values
        are 0, 8, 16, 24 and 32.
      - *scl* is a pin object specifying the pin to use for SCL.
      - *sda* is a pin object specifying the pin to use for SDA.

   Note that some ports/boards will have default values of *scl* and *sda*
   that can be changed in this constructor.  Others will have fixed values
   of *scl* and *sda* that cannot be changed.

General Methods
---------------

.. method:: I2CTarget.deinit()

   Deinitialise the I2C target.  After this method is called the hardware will no
   longer respond to requests on the I2C bus, and no other methods can be called.

.. method:: I2CTarget.readinto(buf)

   Read into the given buffer any pending bytes written by the I2C controller.
   Returns the number of bytes read.

.. method:: I2CTarget.write(buf)

   Write out the bytes from the given buffer, to be passed to the I2C controller
   after it sends a read request.  Returns the number of bytes written.  Most ports
   only accept one byte at a time to this method.

.. method:: I2CTarget.irq(handler=None, trigger=IRQ_END_READ|IRQ_END_WRITE, hard=False)

   Configure an IRQ *handler* to be called when an event occurs.  The possible events are
   given by the following constants, which can be or'd together and passed to the *trigger*
   argument:

      - ``IRQ_ADDR_MATCH_READ`` indicates that the target was addressed by a
        controller for a read transaction.
      - ``IRQ_ADDR_MATCH_WRITE`` indicates that the target was addressed by a
        controller for a write transaction.
      - ``IRQ_READ_REQ`` indicates that the controller is requesting data, and this
        request must be satisfied by calling `I2CTarget.write` with the data to be
        passed back to the controller.
      - ``IRQ_WRITE_REQ`` indicates that the controller has written data, and the
        data must be read by calling `I2CTarget.readinto`.
      - ``IRQ_END_READ`` indicates that the controller has finished a read transaction.
      - ``IRQ_END_WRITE`` indicates that the controller has finished a write transaction.

   Not all triggers are available on all ports.  If a port has the constant then that
   event is available.

   Note the following restrictions:

      - ``IRQ_ADDR_MATCH_READ``, ``IRQ_ADDR_MATCH_WRITE``, ``IRQ_READ_REQ`` and
        ``IRQ_WRITE_REQ`` must be handled by a hard IRQ callback (with the *hard* argument
        set to ``True``).  This is because these events have very strict timing requirements
        and must usually be satisfied synchronously with the hardware event.

      - ``IRQ_END_READ`` and ``IRQ_END_WRITE`` may be handled by either a soft or hard
        IRQ callback (although note that all events must be registered with the same handler,
        so if any events need a hard callback then all events must be hard).

      - If a memory buffer has been supplied in the constructor then ``IRQ_END_WRITE``
        is not emitted for the transaction that writes the memory address.  This is to
        allow ``IRQ_END_READ`` and ``IRQ_END_WRITE`` to function correctly as soft IRQ
        callbacks, where the IRQ handler may be called quite some time after the actual
        hardware event.

.. attribute:: I2CTarget.memaddr

   The integer value of the most recent memory address that was selected by the I2C
   controller (only valid if ``mem`` was specified in the constructor).

Constants
---------

.. data:: I2CTarget.IRQ_ADDR_MATCH_READ
          I2CTarget.IRQ_ADDR_MATCH_WRITE
          I2CTarget.IRQ_READ_REQ
          I2CTarget.IRQ_WRITE_REQ
          I2CTarget.IRQ_END_READ
          I2CTarget.IRQ_END_WRITE

    IRQ trigger sources.
