I2CTarget: Add number of bytes read/written
Description
Love the new I2CTarget class, thanks for adding it!
I2CTarget.memaddr specifies the first memory address read/written by the controller, but there is no way to know how many bytes were read/written. This would be a very useful feature for some I2CTarget implementations.
As a slightly contrived example for motivation, suppose I'm creating an I2CTarget that controls multiple stepper motors, and is implemented as a "memory device". Whenever the I2C controller writes a byte to a memory address (or multiple bytes in a single transaction), the corresponding stepper motor(s) moves that many steps. The IRQ implementation would need to wait for a IRQ_END_WRITE event, then look at i2c_target.memaddr and a currently non-existent i2c_target.numbytes (or similar) to know which stepper motors to move.
I suppose this hypothetical device could be implemented as an arbitrary I2C device by handling all the events in the IRQ, instead of as a memory device, so you could count each time the IRQ_WRITE_REQ event occurs until IRQ_END_WRITE occurs. However this would be a lot more Python code, and I have yet to evaluate performance and whether this would result in unnecessary clock stretching (particularly at clock frequencies higher than 100kHz). Clock stretching should really be avoided if possible, it can cause a lot of obscure problems (example, example).
Code Size
IMO this should be required as part of I2CTarget. Can't imagine it would be a huge increase to the code size.
Implementation
I hope the MicroPython maintainers or community will implement this feature
Code of Conduct
Yes, I agree
Add `machine.I2CTarget` implementing a generic I2C device
Summary
(Edit: this summary was updated to reflect the most recent state of this PR.)
This PR implements a generic I2C target/peripheral/"slave" device. It can work in two separate modes:
- a general device with interrupts/events/callbacks for low-level I2C operations like address match, read request and stop
- a memory device that allows reading/writing a specific region of memory (or "registers") on the target I2C device
The class is called machine.I2CTarget. To make a memory device is very simple:
from machine import I2CTarget
mem = bytearray(8)
i2c = I2CTarget(addr=67, mem=mem)
That's all that's needed to start the I2C target. From then on it will respond to any I2C controller on the bus, allowing reads and writes to the mem bytearray.
You can also register to receive events. For example to be notified when the memory is read/written:
from machine import I2CTarget
def irq_handler(i2c_target):
flags = i2c_target.irq().flags()
if flags & I2CTarget.IRQ_END_READ:
print("controller read from target starting at", i2c_target_memaddr)
if flags & I2CTarget.IRQ_END_WRITE:
print("controller wrote to target starting at", i2c_target_memaddr)
mem = bytearray(8)
i2c = I2CTarget(addr=67, mem=mem)
i2c.irq(irq_handler)
Instead of a memory device, an arbitrary I2C device can be implemented using all the events (see docs).
This is based on the discussion in #3935.
An implementation is provided for:
- rp2 (direct register access)
- alif (direct register access, same I2C hardware as rp2)
- stm32 (direct register access)
- esp32s2/esp32s3 (using the IDF, does not support all events)
- zephyr (using zephyr i2c_target API, all events supported)
- mimxrt
- samd
Testing
An extmod test is added, and also a multitest.
The tests pass RPI_PICO, RPI_PICO2_W, PYBV10, PYBD_SF6, ALIF_ENSEMBLE.
Trade-offs and Alternatives
This is a very simple implementation, but it works and is probably enough for most use cases. There are lots of things that could be enhanced:
- add Python callbacks to notify when the I2C controller reads/writes memory
- implement 16-bit wide memory addressing (currently restricted to 8-bit addresses)
- implement other I2C targets, eg FIFO, or generic
- add support for
asyncio, eg polling the device for events