Example scripts#
Every example below ships with the package, in its examples/ folder. Each one runs as-is:
python3 examples/device_info.py
They all assume the board is at the default address 0x38 on /dev/i2c-1. If you jumpered a different address or are using another adapter, change the constructor at the top of the file.
Start here#
| Script | What it shows |
|---|---|
device_info.py |
Identity, firmware version, variant, capabilities, and what is on each port |
sensor_dump.py |
Every live value in one transaction — the fastest way to check your wiring |
encoder_read.py |
Counts, firmware velocities, and the pin-state diagnostic |
Run device_info.py before anything else. If it prints a device report, your wiring, pull-ups, logic levels and address jumpers are all correct, and everything else will work.
Colour#
| Script | What it shows |
|---|---|
color_teach.py |
Teach-by-example from the terminal, saved to flash |
color_read.py |
Reading colour classes, and asking about one colour directly |
latched_output.py |
Latched outputs — catching an event too brief for your loop |
latched_output.py is worth reading even if you never use latching, because the problem it solves is worse on a Pi than anywhere else: a 3 ms event and a loop the scheduler can pause for 20 ms do not mix, and no amount of tightening your Python will fix that. The board latches; you read the latch whenever you get round to it.
Distance#
| Script | What it shows |
|---|---|
distance_read.py |
Millimetres, and what “nothing in range” looks like |
Triggers#
| Script | What it shows |
|---|---|
trigger_setup.py |
The canonical setup-once configuration: colour, distance, encoder and heading |
trigger_runtime.py |
The runtime half: one GPIO read, zero I2C, no driver at all |
Read these two together. They are the clearest demonstration of what the board is for — the setup script runs once and is then never needed again, and the runtime script does not even import the driver.
Encoders#
| Script | What it shows |
|---|---|
pwm_encoder.py |
Absolute pulse-width encoders, calibration, wrap tracking |
Heading and odometry#
| Script | What it shows |
|---|---|
heading_imu.py |
Heading, gyro calibration, failing loudly on an untrustworthy gyro |
localizer.py |
Full pose tracking: parameters, calibration, waiting for ready, live pose |
Both need the odometry variant of the board. On a base board they say so and stop, rather than reporting a heading of 0.00 forever.
A note on the examples#
They are written to be read as much as run. Where an example catches a specific exception rather than BBRError, that is showing you something worth copying — particularly heading_imu.py, where the difference between NoImuError and ImuFaultError is the difference between “you bought the base board” and “the IMU has come loose”.
trigger_runtime.py needs gpiozero, which Raspberry Pi OS ships with. The rest need only the driver itself.
Stop any of them with Ctrl-C; they all exit cleanly rather than dumping a traceback.