Implement I2CDevice class on EV3 #379

laurensvalk · 2025-08-18T18:00:03Z

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.

Testing to allow a range of devices like any I2C devices is more natural this way.

So far we assumed that if a device made it out of the passive device manager, it must be a LUMP device. There may be other categories of active sensors that need a background process, so prepare for it now.

Reset isn't implemented here, so we don't need this argument.

Start off with a basic implementation. This is not async-compatible yet.

We used to turn power off only at the end of active sensor processes as well as at the end of a program. In general, we want to turn power off whenever something is disconnected, which is what we do here. The goal here is to be able to turn off 9V to a sensor if a user has switched it on and then unplugs the device.

This is only an indentation change with continue replaced by returning success. This thread should wait for a connection and then wait until disconnected. The outer sensor port loop will run this again instead. This allows us to handle things like port reset in the outer sensor loop. This ensures 9V power is turned off once a device is unplugged, for example.

This will automatically turn off when unplugged.

Also supports async API. This replaces the smbus version for ev3dev. Some missing methods will be reinstated in future commits.

This way we don't need to add the `max_read_size` parameter and only allocate as much as we need.

These are wrappers around write_then_read for backwards compatibility.

It appears that this was left on by accident.

A user could inadvertently make another async I2C request, but we don't allow this if another operation is ongoing. So we shouldn't override the state in this case.

Since this already deals with nxt quirks, include the required delay between operations too. This simplifies higher level code common to all I2C Sensors.

Creating duplicate async functions in Python for every method is not very nice. We can instead define callbacks to map bytes to relevant data when the operation completes.

Instead of having the driver memcpy it, let the caller handle it so it can do it after allocation. This also means we don't have to allocate bytes objects at all for most sensor methods in the nect commits.

We no longer need a double allocation just to shift the write data.

We've been gradually introducing this pattern for newer classes, so be consistent about it.

Allows sensor definitions to have an I2DDevice instance with awaitable operations with a result mapped to objects.

Given the firmware size limitations on NXT, using Python wasn't going to be scalable. With the recent changes to the I2CDevice implementation, we can use instances of it for sensor classes written in C. This reverts commit a37f46f756cd8453ff8f99193263ac68f9b5a057. This is reverted instead of dropped so we maintain the logic to import Python classes into the C module in git history for future reference.

This is commonly used for LEGO-style I2C device classes. Also simplify passing in address to I2CDevice object creator.

coveralls · 2025-08-18T18:06:59Z

coverage: 58.691% (-0.05%) from 58.741%
when pulling 5fba49d on work
into 5c37864 on master.

github-actions · 2025-08-18T18:18:23Z

Download the artifacts for this pull request:

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:

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.
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 · 2025-08-21T21:53:07Z

lib/pbio/drv/ioport/ioport.c

@@ -46,6 +46,17 @@ pbio_error_t pbdrv_ioport_p5p6_set_mode(const pbdrv_ioport_pins_t *pins, pbdrv_i
        pbdrv_gpio_alt(&pins->uart_tx, pins->uart_tx_alt_uart);
        pbdrv_gpio_out_low(&pins->uart_buf);
        return PBIO_SUCCESS;
+    } else if (mode == PBDRV_IOPORT_P5P6_MODE_I2C) {
+        // First reset all pins to inputs by going to GPIO mode recursively.


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

dlech · 2025-08-21T22:09:24Z

lib/pbio/drv/i2c/i2c_ev3.c

+        PBIO_OS_AWAIT_UNTIL(state, pbio_os_timer_is_expired(&i2c_dev->timer));
+        pbio_os_timer_set(&i2c_dev->timer, 100);


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.

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

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.

dlech · 2025-08-21T22:11:25Z

bricks/ev3/modules/_i2c_sensors.py

+        try:
+            assert self._i2c.read(0x08, 4) == b"LEGO"
+            assert self._i2c.read(0x10, 5) == b"Sonar"
+        except:


This should only catch Exception, otherwise it could swallow SystemExit or KeyboardInterrupt.

dlech · 2025-08-21T22:13:21Z

bricks/ev3/modules/_i2c_sensors.py

+            assert self._i2c.read(0x08, 4) == b"LEGO"
+            assert self._i2c.read(0x10, 5) == b"Sonar"
+        except:
+            raise OSError("Ultrasonic Sensor not found.")


Proper use of OSError should include an error code as the first argument. I wouldn't call this OSError though since it didn't come from a pbio error.

dlech · 2025-08-21T22:15:26Z

bricks/ev3/modules/_i2c_sensors.py

+        wait(100)
+
+        try:
+            assert self._i2c.read(0x08, 4) == b"LEGO"


Technically assert statements can be optimized out when compiling.

dlech · 2025-08-21T22:16:02Z

pybricks/iodevices/pb_type_iodevices_i2cdevice.c

@@ -17,10 +17,22 @@

 #include <pybricks/util_mp/pb_kwarg_helper.h>
 #include <pybricks/util_mp/pb_obj_helper.h>
+


Unintentional blank line?

dlech · 2025-08-21T22:34:52Z

lib/pbio/drv/i2c/i2c_ev3.c

@@ -106,7 +106,7 @@ pbio_error_t pbdrv_i2c_write_then_read(
    uint8_t dev_addr,
    const uint8_t *wdata,
    size_t wlen,
-    uint8_t *rdata,
+    uint8_t **rdata,


This scares me. I'm guessing it was done to avoid copying the same data twice. I would just pass in an array allocated from the MicroPython heap and leave the copy here. Then call mp_obj_str_set_data() to attach that array to a bytes object if calling this method is successful.

I would just pass in an array allocated from the MicroPython heap

As we have seen several times with Bluetooth code, this tends to lead to issues. When pbio does the copying, problems arise when the allocated buffer no longer exists or the user program has ended.

When MicroPython drives the final copy step, we know that MicroPython is still running, and it is reading from a static pbio buffer, so this is always safe. If the async code never completes, there are no issues.

Alternatively, we could make a separate get_data call that does the copying. The end result is the same though.

Fair point.

dlech · 2025-08-21T22:37:42Z

pybricks/iodevices/pb_type_iodevices_i2cdevice.c

+    }
+
+    // Otherwise need to prefix write data with given register.
+    uint8_t write_data[256];


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 added 23 commits August 18, 2025 13:44

pbio/port_dcm_ev3: Invert category type assertion.

be53215

Testing to allow a range of devices like any I2C devices is more natural this way.

pbio/port: Generalize active sensor process.

72576cb

So far we assumed that if a device made it out of the passive device manager, it must be a LUMP device. There may be other categories of active sensors that need a background process, so prepare for it now.

pbio/drv/ioport: Don't pass uart to mode setter.

11606ba

Reset isn't implemented here, so we don't need this argument.

pbio/port: Implement mode setter for I2C.

948ffea

pybricks.nxtdevices: Enable UltrasonicSensor.

2477504

Start off with a basic implementation. This is not async-compatible yet.

pybricks.nxtdevices.UltrasonicSensor: Enable battery power.

162665c

This will automatically turn off when unplugged.

pybricks.iodevices.I2CDevice: Implement for embedded Pybricks.

5d828f9

Also supports async API. This replaces the smbus version for ev3dev. Some missing methods will be reinstated in future commits.

pybricks.iodevices.I2CDevice: Use bytes obj as buffer.

e5be629

This way we don't need to add the `max_read_size` parameter and only allocate as much as we need.

pybricks.iodevices.I2CDevice: Implement legacy read and write.

7fc503d

These are wrappers around write_then_read for backwards compatibility.

pbio/drv/i2c_ev3: Turn off debug output.

cb4e7cc

It appears that this was left on by accident.

pybricks.iodevices.I2CDevice: Save state only after success.

d061c3c

A user could inadvertently make another async I2C request, but we don't allow this if another operation is ongoing. So we shouldn't override the state in this case.

pbio/drv/i2c_ev3: Absorb quirk delay time.

226313f

Since this already deals with nxt quirks, include the required delay between operations too. This simplifies higher level code common to all I2C Sensors.

pybricks.nxtdevices.UltrasonicSensor: Implement in Python.

6e494fb

pybricks.iodevices.I2CDevice: Use return map callback.

d0e19aa

Creating duplicate async functions in Python for every method is not very nice. We can instead define callbacks to map bytes to relevant data when the operation completes.

pybricks.iodevices.I2CDevice: Don't allocate until success.

3f4584d

Instead of having the driver memcpy it, let the caller handle it so it can do it after allocation. This also means we don't have to allocate bytes objects at all for most sensor methods in the nect commits.

pybricks.iodevices.I2CDevice: Use common operation for read/write.

2dcc6af

We no longer need a double allocation just to shift the write data.

pybricks.iodevices.I2CDevice: Update type name.

4e4ca6c

We've been gradually introducing this pattern for newer classes, so be consistent about it.

pybricks.iodevices.I2CDevice: Generalize object interface.

505f3ab

Allows sensor definitions to have an I2DDevice instance with awaitable operations with a result mapped to objects.

pybricks.iodevices.I2CDevice: Add helper for asserting id string.

1f3032e

This is commonly used for LEGO-style I2C device classes. Also simplify passing in address to I2CDevice object creator.

pybricks.nxtdevices: Add TemperatureSensor.

5fba49d

laurensvalk mentioned this pull request Aug 19, 2025

[Bug] Subsequent I2C operations raise PBIO_ERROR_IO pybricks/support#2314

Open

dlech reviewed Aug 21, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Implement I2CDevice class on EV3 #379

Implement I2CDevice class on EV3 #379

laurensvalk commented Aug 18, 2025 •

edited

Loading

Uh oh!

coveralls commented Aug 18, 2025

Uh oh!

github-actions bot commented Aug 18, 2025

Uh oh!

dlech left a comment

Uh oh!

dlech Aug 21, 2025

Uh oh!

dlech Aug 21, 2025

Uh oh!

laurensvalk Aug 22, 2025

Uh oh!

dlech Aug 22, 2025

Uh oh!

dlech Aug 21, 2025

Uh oh!

dlech Aug 21, 2025

Uh oh!

dlech Aug 21, 2025

Uh oh!

dlech Aug 21, 2025

Uh oh!

dlech Aug 21, 2025

Uh oh!

laurensvalk Aug 22, 2025

Uh oh!

dlech Aug 22, 2025

Uh oh!

dlech Aug 21, 2025

Uh oh!

Uh oh!

		PBIO_OS_AWAIT_UNTIL(state, pbio_os_timer_is_expired(&i2c_dev->timer));
		pbio_os_timer_set(&i2c_dev->timer, 100);

		@@ -17,10 +17,22 @@

		#include <pybricks/util_mp/pb_kwarg_helper.h>
		#include <pybricks/util_mp/pb_obj_helper.h>

Uh oh!

Implement I2CDevice class on EV3 #379

Are you sure you want to change the base?

Implement I2CDevice class on EV3 #379

Conversation

laurensvalk commented Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Other sensors

Async support

Multiple devices

Thanks

Uh oh!

coveralls commented Aug 18, 2025

Uh oh!

github-actions bot commented Aug 18, 2025

Uh oh!

dlech left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

laurensvalk commented Aug 18, 2025 •

edited

Loading