Python API summary#

The everyday tier, which is what most projects need. Every method validates its arguments and, on failure, raises an exception naming the problem rather than returning a plausible-looking wrong number.

Getting the device#

from bbr_digital_expander import BBRDigitalExpander

expander = BBRDigitalExpander()                    # 0x38 on /dev/i2c-1
expander = BBRDigitalExpander(0x39)                # jumpered address
expander = BBRDigitalExpander(bus="/dev/i2c-3")    # another adapter

with BBRDigitalExpander(bus=1) as expander:        # begin() on entry, close() on exit
    ...

Errors#

Every one carries .message and .status, a Status value you can branch on.

Failed reads serve the last known good value. When a snapshot read cannot reach the device — or, for the localizer, when three reads in a row fail their checksum — the driver returns the previous snapshot and is_data_fresh() goes false, rather than raising. A bus being torn down, or a burst of noise, should not kill a running program. Fail-loud survives where it matters: a device that has never answered raises TransportError, and a streak still failing after half a second (5+ reads) raises BBRError. The FTC driver differs here: by default it logs that streak and keeps running, because ending an OpMode mid-match costs more than stale data that isDataFresh() already flags.

Encoders#

Sensors#

Teaching and triggers#

All of these save to flash automatically, which is why they are setup calls: run them once, never in a loop. See Set up once.

Heading and pose#

These raise rather than return a heading or pose the board cannot stand behind.

Mounting and direction#

Set once when the board is bolted on. Unlike set_encoder_direction() above, nothing here auto-saves — follow with save_config_to_flash().

Board identity#

Blocks and raw access#

Advanced tier#

The full register map is available underneath: configure_output(), write_color_class(), write_distance_class(), set_channel_mode(), set_pwm_channel_params(), set_pwm_wrap_enabled(), set_localizer_params(), read_telemetry(), run_command().

Behaviour worth knowing#

begin() refuses loudly. A wrong device ID, an unsupported protocol version or an unrecognised hardware variant raises rather than producing corrupt data later.

One transaction per snapshot. The everyday getters share a snapshot refreshed roughly every 10 ms, so four questions in one loop iteration cost one transaction and the answers are mutually consistent.

Block reads are raw I2C, not SMBus. The 96-byte telemetry block does not fit an SMBus block transfer’s 32-byte cap, so the driver uses i2c_rdwr messages instead. Pass chunk_size= if some adapter you are using cannot manage a long transfer; the register pointer is still written only once, so the whole block stays inside a single firmware snapshot either way.

Commands are idempotent. Every command carries a token, so a bus retry cannot execute it twice.

Config writes are verified by readback. The board never NAKs for addressing reasons — an out-of-range write is silently discarded — so the driver writes, reads back and compares.

IMU access raises when the gyro cannot be trusted rather than returning zeros, because a heading of 0.00 that never changes is indistinguishable from working software.

The localizer block is checked with CRC16. I2C acknowledges bytes without verifying them, so a noise-flipped bit would otherwise arrive looking like a valid pose. A mismatch is re-read, then raised.

A uniform block is treated as a failed transfer. A read that comes back all 0x00 or all 0xFF never came from a live board — every block the driver guards this way contains a timestamp, a CRC or a status byte with reserved bits. It is the reason a bus-level fault surfaces as an exception rather than as wrong numbers.