Implement I2CDevice class on EV3

[laurensvalk]

This implements the pybricks.iodevices.I2CDevice class. It is compatible with the class we had in Pybricks 2.0, but adds new features. You can use use either LEGO-style (autodetected) devices to raise ERROR_NO_DEV if it isn't found, or disable auto-detection to allow custom devices.

You can gracefully switch between them. If you run a new program with an auto-detectable sensor after using a custom sensor last time, you can do so without rebooting the hub. This takes a little bit of time (less than a second), but should be more stable than in 2.0, where it would take much longer and sometimes not revert modes.

from pybricks.iodevices import I2CDevice
from pybricks.parameters import Port
from ustruct import unpack

# Using custom=True will disable auto-detection, allowing for non-LEGO I2C devices too.
# Using powered=True turns on battery voltage which is needed for some devices.
# Using nxt_quirk=True applies I2C workarounds for certain LEGO sensors, off by default.
therm = I2CDevice(Port.S4, 0x4C, custom=True, powered=False, nxt_quirk=False)

# There is a new write-then-read command to efficiently combine certain operations.
# This sets the temperature resolution to 0.125 degrees, which could also be done
# with the old-style write.
therm.write_then_read(bytes([0x01, (1 << 6) | (0 << 5)]), 0)

old_data = 0

while True:

    # Original read and write API remain available.
    data = therm.read(reg=0x00, length=2)
    if data == old_data:
        continue

    old_data = data

    temperature_raw = unpack(">h", data)[0]

    print(temperature_raw // 16 / 16)

A new method called write_then_read is added to complement the existing read and write for advanced users.

Other sensors

Support for the NXT Ultrasonic Sensor and the Temperature Sensor has been added. The Energy Meter should follow shortly. Support for powered devices is added, which is needed for the Ultrasonic Sensor and selected other devices.

Async support

Unlike in 2.0 where everything was blocking, the new API is also async-compatible. You can make background loops that poll your devices without blocking the rest of your code. The internal implementation of the I2CDevice class is such that we can easily add builtin support for more sensors without a big penalty on build size. Of course new sensors can just be implemented in Python too.

from pybricks.nxtdevices import TemperatureSensor, UltrasonicSensor
from pybricks.parameters import Port
from pybricks.tools import multitask, run_task

therm = TemperatureSensor(Port.S4)
sonar = UltrasonicSensor(Port.S3)


async def therm_thread():

    old = 0

    while True:
        new = await therm.temperature()
        if new == old:
            continue
        old = new
        print(f"Temperature: {new}°C")


async def sonar_thread():

    old = 0

    while True:
        new = await sonar.distance()
        if new == old:
            continue
        old = new
        print(f"Distance: {new} mm")


run_task(multitask(therm_thread(), sonar_thread()))

Multiple devices

Using multiple sensors with different addresses on one port also works by initializing two I2CDevice instances (or two regular sensor instances). It is then up to the user to poll them one at a time.

from pybricks.nxtdevices import TemperatureSensor, UltrasonicSensor
from pybricks.parameters import Port
from pybricks.tools import wait

sonar = UltrasonicSensor(Port.S4)
wait(100)
therm = TemperatureSensor(Port.S4)
wait(100)

while True:

    dist = sonar.distance()
    temp = therm.temperature()

    print(f"Dist: {dist} mm  Temp: {temp} °C")
    wait(200)

Thanks

Big thanks to @ArcaneNibble for implementing a low-level I2C driver using the PRU.

[coveralls]

coverage: 58.75% (+0.009%) from 58.741%
when pulling 7cd3f2f on work
into 1b5b06f on master.

[github-actions]

Download the artifacts for this pull request:

• pr_number.zip
• mpy-cross.zip
• nxt-firmware-build-4149-git576cc86e.zip
• movehub-firmware-build-4149-git576cc86e.zip
• ev3-firmware-build-4149-git576cc86e.zip
• cityhub-firmware-build-4149-git576cc86e.zip
• technichub-firmware-build-4149-git576cc86e.zip
• primehub-firmware-build-4149-git576cc86e.zip
• essentialhub-firmware-build-4149-git576cc86e.zip

[dlech]

So many commits! I think half of my comments were on code that got added and then promptly removed.

Just a few high-level comments:

1. I'm not sure that write_then_read() as a user API is particularly useful. Pretty much the only time you actually write then read is on devices that use register addressing, so this is already covered by the read() method.

   For the less common cases when a device doesn't use register addressing, I think allowing None as the reg arg for the read() and write() methods would be simpler than adding a new method.

2. For the case of multiple devices on a single port, why do we need the extra wait() calls? It seems like this is something that should be baked in if it is actually required.

[dlech]

What is the advantage of doing this recursively vs. just setting each gpio once here?

[dlech]

This looks reversed. Timer is set after awaiting. If something funny is going on that makes this correct, we should have a comment explaining it.

[laurensvalk]

    // This ensures a minimum delay without slowing down code that polls
    // less frequently.

[dlech]

That doesn't explain why we wait for the timer to expire first and then set the duration of the timer after that. I would expect to set the timer first, then wait for it.

[laurensvalk]

Then you would wait every time. If a user already has a wait in their loop, then we don't need to wait again here.

So we only wait if it isn't already expired. I'll rephrase.

[dlech]

This amount of stack is fine on EV3, but not so sure about NXT. Most I2C operations are going to be 32 bytes or less so that could be a sensible number to use.

[laurensvalk]

This was here to avoid always allocating, but I suppose we could still do that instead.