Skip to content
gunkslab

Reference

Bench programs

Small one-job programs that test a robot’s hardware on the desk, before it goes into the robot or onto a custom PCB. Each checks one thing, such as whether a board answers or what a sensor reads. One PlatformIO environment each. None of them is the bot’s firmware (firmware/), and none stays on a board.

Each program goes with a bench test page on the soleil site, which has the wiring sheet, the picture and the readings to write down.

How to build, flash and add one is a guide.

The programs

Environment Robot What it does Test page
ps-pwm Pirate Stage Scans the I2C bus, sets up the PCA9685 (All Call off, totem-pole outputs, 1 kHz), then steps channel 0 off, half, full, two seconds each, printing every step pirate-stage/bench-pwm (test 5)
ps-imu Pirate Stage Checks the GY-521’s WHO_AM_I, wakes it, prints acceleration, rotation and temperature five times a second: flat reads about 0, 0, +1 g pirate-stage/bench-imu (test 9)
ps-vbat Pirate Stage Reads the battery divider (64 samples, the ESP32’s calibrated millivolts), prints the pack voltage. Type the meter’s reading for the correction ratio pirate-stage/bench-vbat (test 10)
ps-cliff Pirate Stage The two VL53L5CX on the mux’s channels 0 and 1: holds 10 s idle, 10 s with their firmware loaded, 10 s ranging, for the meter on their 5 V lead (VIN from the buck’s 5 V). Then each one’s nearest valid zone and its 4 x 4 grid pirate-stage/bench-cliff (test 11)
ps-drive Pirate Stage Reminds that R22 (10 kΩ, EEP to GND) should be on the board. Wakes both DRV8833s only after every PWM pin is low, then on Enter runs each motor forward and back at 30, 60 and 100%. s stops all and sleeps the drivers pirate-stage/bench-drive (test 12)
ps-enc Pirate Stage Counts the four encoders in hardware (PCNT, x4 quadrature) and prints totals and counts a second. One output-shaft turn by hand gives counts a wheel turn. Glitch filter on at start, f toggles it. a reads the battery ADC (GPIO 32) in a tight loop while counting, so a held-still shaft shows whether ADC reads glitch the rear counts (GPIO 36, 39) pirate-stage/bench-enc-count (test 13)
ps-dip Pirate Stage On the car’s own pack. With USB (which keeps the ESP32 up), for the readings: Enter starts all four motors at once to the firmware’s duty cap for 300 ms, r and Enter through its 150 ms ramp, reading the battery divider thousands of times a second: the pack at rest, its lowest and when, and the lowest of every 10 ms. Without USB, to see a restart: a (or ar) arms one start, run 5 s after the next boot on the pack alone. Its readings, and the reason for any restart that cut it short (brownout: the supply sagged; power_on: the power was cut, the protector), are kept in flash and printed at the next boot with USB pirate-stage/car-dip (test 15)
ps-payload Pirate Stage The payload connector: DETECT on GPIO 12 (internal pull-up after boot, every change printed, debounced). UART2 on GPIO 2 / 15: l runs a loopback through a TX-RX jumper at 115200, 460800 or 921600 (b steps it), and e prints what a module sends. s turns the PCA9685’s All Call off, then lists what answers only on the mux’s channel 2 none yet
gz-imu gl_zero As ps-imu, on gl_zero’s bus (SDA 21, SCL 22): WHO_AM_I (0x68 for an MPU-6050), then acceleration, rotation and temperature five times a second gl-zero/bench-imu (test 6)
gz-vbat gl_zero As ps-vbat, on GPIO 32 (100 kΩ / 33 kΩ, 100 nF across the 33 kΩ: 8.4 V reads about 2.08 V): pin and pack volts twice a second. Type the meter’s reading for the ratio gl-zero/bench-vbat (test 7)
gz-tof gl_zero The two TOF400C boards (VL53L1X), both at 0x29 at power-up. Holds the rear one off (XSHUT, GPIO 13 low) and scans the bus: one board at 0x29. Moves the front one to 0x30, lets the rear one up, scans again: the front at 0x30, the rear at 0x29. Then both distances a few times a second. Both answering is a pass gl-zero/bench-tof (test 8)
gz-drive gl_zero The one DRV8833 (both motors on a side in parallel). EEP held low until every PWM pin is low. On Enter, the left side (IN1 / IN2) forward and back at 30, 60 and 100%, a second each, then the right side (IN3 / IN4), printing ULT (GPIO 34, high is no fault) after each. s stops all and sleeps the driver gl-zero/bench-drive (test 9)
gz-dip gl_zero As ps-dip, on gl_zero’s driver: all four motors to full duty (gl_zero’s firmware has no duty cap) for 300 ms, or through the 150 ms ramp, with the same commands, readings and unattended start kept in flash. It prints the firmware’s cutout, warn at 7.0 V and stop at 6.8 V gl-zero/bench-dip (test 10)
gz-stall gl_zero What the stall cutoff hears: the firmware’s IMU set-up and its rules (lib/chassis), with the motors run by hand. Type left and right percentages (60 60, 60 -60): they run 2 s and stop by themselves. Four times a second, the power, the buzz (g), the turn rate and what the cutoff would make of it: heard, QUIET or PIVOT, and its heat. It doesn’t stop the motors. Its comment lists the readings to take: still, wheels in the air, on the desk, held, one side held none yet

Pin numbers

include/pirate_stage_pins.h is Pirate Stage’s pin map, and include/gl_zero_pins.h gl_zero’s, each from the repo its hardware is designed in, which isn’t public: GPIO nets as PS_PIN_* and GZ_PIN_*, I2C addresses as PS_I2C_* and GZ_I2C_*, and the battery divider’s resistors. Programs use those, never a bare number, so they can’t drift from the wiring sheets. The headers are committed. When a pin map changes:

python3 bench/pins.py                    # write them again (SOLEIL=path if the soleil repo isn't ../soleil)
python3 bench/pins.py gl_zero            # one robot's (pirate_stage, gl_zero)
python3 bench/pins.py --check            # are they current?