.. 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_READ`` 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_READ``, ``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.