Troubleshooting#

“Not a BBR Digital Expander: DEVICE_ID …” — something answered at the address, but it wasn’t an Expander. Check you picked the right I2C bus in the robot configuration, and that nothing else on the bus is at address 0x38.

Device not found in hardwareMap — the name in your code doesn’t match the name in the robot configuration. The examples use expander.

Configuration doesn’t list “BBR Digital Expander” — the driver folder isn’t in your project, or the project didn’t rebuild. Confirm com/buildingblockrobotics/expander/ is under TeamCode/src/main/java/ and rebuild.

begin() returning false prints a reason through lastErrorText(). The three you will actually see:

“the expander did not acknowledge” — nothing answered at that address. In order of likelihood:

1. No bus pull-ups. The board has none, and neither does your Arduino unless you fitted them. See Wiring it up. This is the single most common cause on a non-Hub host.
2. Wrong address. The jumpers select 0x38–0x3B; the constructor defaults to 0x38.
3. No power, or not enough of it. The board needs 3.3 V at about 55 mA.
4. SDA and SCL swapped.

“not a BBR Digital Expander” — something answered, but it isn’t this board. Check for an address clash with another device on the same bus.

“firmware speaks a protocol major this driver does not” — update whichever of the two is older. See Updating the firmware.

begin() raises, and the exception says which of these it is.

TransportError: “could not open I2C bus” — the bus device is not there, or you cannot reach it:

1. I2C is not enabled. sudo raspi-config nonint do_i2c 0, then reboot.
2. Permissions. sudo usermod -aG i2c "$USER", then log out and back in. Running as root works too, but do not build a habit of it.
3. Wrong adapter number. bus=1 is the header on every current Pi; a Pi Zero or a software-I2C overlay may be a different number. ls /dev/i2c-* lists what you have.

TransportError: “the expander did not acknowledge” — the bus opened, nothing answered at that address:

1. Wrong address. The jumpers select 0x38–0x3B; the driver defaults to 0x38.
2. No power, or not enough of it. 3.3 V at about 55 mA, from header pin 1.
3. SDA and SCL swapped, or no shared ground.

WrongDeviceError — something answered, but it isn’t this board. Check for an address clash with another device on the same bus.

ProtocolMismatchError — update whichever of the driver and the firmware is older. See Updating the firmware.

Readings freeze mid-match#

Check isDataFresh(). When a read can’t reach the device the driver serves the last known good value rather than throwing, so a stale reading looks like a working one that stopped changing.

A sustained streak of failures logs a warning to the Robot Controller log and keeps serving the old value, so the OpMode keeps running. Check isDataFresh() before acting on a reading. To make that streak throw instead while you track the fault down, call exp.setReadFailurePolicy(BBRDigitalExpander.ReadFailurePolicy.STOP_OPMODE).

Did the board reset, or did the bus drop out?#

On firmware 1.1.0 and later, readDiagnostics() answers it in one call. Read it when the OpMode starts and again after a dropout:

BBRDigitalExpander.Diagnostics d = exp.readDiagnostics();
telemetry.addData("last reset", d.resetCause);
telemetry.addData("resets since power-on", d.resetsSincePowerOn);
telemetry.addData("bus recoveries", d.i2cRecoveryCount);
telemetry.addData("bus arbitration lost", d.i2cArbitrationLostCount);

• resetsSincePowerOn above 0 with WATCHDOG: the firmware hung and restarted. The driver also logs expander REBOOTED. On 1.1.0 bus noise could trigger this; update to 1.1.1, which fixes it.
• POWER_ON mid-match, with the Hub still running: the board lost power briefly. Check the I2C cable’s power pins and connectors.
• No reset, but the bus counters climb: the board kept running and the I2C link itself was disturbed. i2cArbitrationLostCount going up usually means electrical noise on the cable. Route the I2C cable away from motor and motor-controller wiring, and check whether the errors follow particular encoder cables (unplug them one at a time).

The Hub stops talking to the board until it is power-cycled#

If readings stop and only a robot power cycle brings them back, the Hub’s I2C port has given up after too many corrupted transfers. First update to 1.1.1, so the board itself never holds the bus. Then reduce what corrupts the transfers:

• Route the I2C cable away from motor and motor-controller wiring, and away from the encoder cables of the noisiest motors.
• Read less often. Every transaction is another chance to be hit by noise. Read once per loop, and only what you use.
• Watch the counters. i2cArbitrationLostCount and i2cRecoveryCount from readDiagnostics() climbing while a mechanism runs points at that mechanism’s wiring.

Everything breaks when the OpMode stops#

Expected, and already handled. The SDK tears the I2C device down at stop, so a read already in flight comes back empty. The driver raises BBRTransportException for that case.

If you have a polling loop, catch it and break — the IMU and localizer examples show the pattern. It means “the read never reached the device”, not “something is broken”.

Every call returns false after one failure#

The library does not latch a failure — each call sets its own status. But if begin() failed, calls that need the device to have been identified fail with BBRStatus::NotInitialized until begin() succeeds. Check begin()’s return value and stop there rather than looping on it.

The sketch compiles but does nothing#

begin() needs Wire.begin() to have run first. Nothing enforces the order, and the symptom is a clean compile followed by a failed identity read.

Not enough RAM on an Uno#

BBRTelemetry is about 100 bytes and the block read uses a 96-byte buffer while it decodes, so a readTelemetry() call needs roughly 200 bytes of stack. On a 2 KB part that is affordable but not free — if you are already close to the limit, use the everyday getters, which keep one cached block rather than one per call site, and avoid keeping several BBRTelemetry copies alive at once.

Error text prints as garbage#

lastErrorText() returns a const __FlashStringHelper *, which Serial.println() handles correctly. Passing it somewhere expecting a char * prints the flash address instead of the string.

Occasional corrupt reads on a Pi, but the board is fine on a Hub#

Not something you should meet — a Pi 4 and a Pi 5 both run the whole driver at the stock bus rate with nothing added to config.txt — but here is the cause and the fix if you do.

The expander is an RP2040 in I2C target mode, so it stretches the clock while its firmware services a transfer, and the Pi’s hardware I2C controller has a long-standing bug handling clock stretching.

The driver catches the damage rather than passing it on — a uniform block raises TransportError and a corrupted localizer block raises CrcMismatchError after three tries — so the symptom is intermittent exceptions rather than silently wrong numbers.

Fix it at the bus, in /boot/firmware/config.txt:

• dtparam=i2c_arm_baudrate=50000, then reboot. This is usually enough.
• Or switch to software I2C, which has no such bug: dtoverlay=i2c-gpio,i2c_gpio_sda=23,i2c_gpio_scl=24, then pass that adapter’s number as bus=.

Every call raises NotInitializedError#

begin() has not succeeded. The with form runs it for you and raises on the way in, which is why the examples use it — a bare constructor does not talk to the board at all.

A loop that reads several values is slower than expected#

Each everyday getter serves from one cached telemetry block, refreshed when it is older than telemetry_max_age_ms (10 ms by default). If your loop runs faster than that and you want a fresh block each pass, call invalidate_telemetry() — or read read_telemetry() once and use the snapshot, which is what sensor_dump.py does.

smbus2 is not installed#

pip install smbus2. On a system-managed Python (Bookworm and later) either use a virtual environment or sudo apt install python3-smbus2.