
Driver PCB
lnpanini/Falali
An AMR-style under-ride platform that drives beneath a textile trolley, uses upward-facing time-of-flight sensors to confirm it is under the trolley and centred, clamps onto the underside, and then moves the trolley.

An AMR-style under-ride platform that drives beneath a textile trolley, uses upward-facing time-of-flight sensors to confirm it is under the trolley and centred, clamps onto the underside, and then moves the trolley.
Arm Subsystem PCB is an open-source printed circuit board by lnpanini, from the lnpanini/Falali repository on GitHub. It is a 2-layer board of 110 × 110 mm with 24 parts on 45 nets, routed with 210 tracks and 9 vias.
It is built around the ESP32-S3-DEVKITC-1-N8. Its parts include 12 switches, 3 connectors and 1 IC. It belongs with the ESP32 boards of this library.
An AMR-style under-ride platform that drives beneath a textile trolley, uses upward-facing time-of-flight sensors to confirm it is under the trolley and centred, clamps onto the underside, and then moves the trolley. ESP32-S3 firmware, hardware and documentation.
This is also the whole-project home for Falali — One AMR Fits All (SUTD 30.007 Engineering Design Innovation, Group 10): a low-profile autonomous mobile robot that moves existing fabric trolleys in a textile factory by driving underneath them, clamping on, and transporting them — no changes to the trolleys or the factory floor.
Hardware documentation lives in
docs/hardware/— power-up runbook, component list, per-connector pinouts for all three PCBs (extracted from the KiCad netlists, not inferred), and a fabrication/repair guide.docs/hardware-architecture.mdis the older companion and is partly superseded by it. The pin table further down this README is the pre-PCB design intent and does not match the fabricated board.
Full design: docs/superpowers/specs/2026-07-06-falali-esp32-docking-design.md.
| Requirement | Target | Result |
|---|---|---|
| Fit under trolley clearance | ≤ 200 mm | 167 mm, validated on the physical chassis |
| Move loaded trolley | ≥ 100 kg | Passed — load moved with two people standing on top |
| Clamp holding force | ≥ 300 N | Weakest-link analysis: clamp capacity 403 N (SF 1.34×) |
| Clamp vertical reach | ≥ 200 mm | Met |
| Docking time | ≤ 1 min | Under 60 s in testing |
| Worst-case castor misalignment | All 4 orientations | Moves under all |
Derivations, test protocols and data: docs/pdr-falali-amr.pdf
(Preliminary Design Review deck, 11 Aug 2026).
ESP-BASE (Wheel Drive PCB) ESP-ARM (Arm Subsystem PCB)
docking state machine arm axes X/Y, flipper servos, clamp
mecanum mixing, 4× corner ToF centring ⇄ limit switches, homing
clamp handoff ESP-NOW over Wi-Fi (channel 1)
operator: BLE gamepad ([bench_ble/](bench_ble/))Commercial AMRs don't fit this job: platform AMRs are too tall to get under the trolleys, tow tractors need turning space, side-docking systems need the trolley modified. The answer is under-entry capture: fit under the ≤200 mm clearance, strafe beneath an existing trolley with mecanum drive, confirm centring sensor-only, clamp and carry.

The clamp must not engage unless the alignment logic CONFIRMS the platform is centred. Limit
switches only confirm clamp travel; they never authorise clamping. SafetyMonitor is the single
gate (confirmed && no faults && !E-stop), and the docking state machine reaches the clamp handoff
only after a sustained CONFIRM. The clamp/arm mechanism itself is an external subsystem that
plugs in at the IClamp port.
lib/ports pure C++ interfaces + shared types (no Arduino)
lib/domain the hand-written core: CornerEdgeDetector · DeadReckonOdometry · SafetyMonitor · DockingStateMachine
lib/drive MecanumDrive (mixes body-frame vx/vy/omega -> 4 wheels)
lib/fakes desktop test doubles for every port
lib/hal_esp32 Arduino adapters over popular libraries
include/ config.h (tunables) · pins.h (GPIO map)
src/main.cpp composition root: builds adapters, wires domain, runs the loop
test/ host unit tests (Unity)Dependency rule: domain → ports only; adapters → ports; main → everything. The domain
never includes Arduino, so it compiles and tests on a laptop. Commodity work uses popular libraries
(pololu/VL53L0X, Bounce2, ArduinoJson, SerialCommands, ESP32 LEDC); only the docking
sequence, corner edge detection, odometry, and safety logic are hand-written — and that is the part
under test.
Alignment method: with a solid trolley board and 4 corner ToF sensors, docking is a deterministic
geometric sequence — APPROACH → ORIENT (rotate until both front corners see the edge) → CENTER_X
(odometry-centre between near/far edges) → CENTER_Y (same, strafing) → CONFIRM → clamp handoff.
Centring uses dead-reckoning odometry; driving to the midpoint between two edge events makes it robust
to calibration error.
ToF wiring, both ESPs: all four corner sensors keep their factory address 0x29 and are brought
up one at a time via XSHUT re-addressing — Vl53l0xArray on the base, TofSensorArray in
arm/. An earlier design multiplexed them through the PCA9548A breakout in
KiCad/PCA9548A Breakout/; final firmware uses no mux, and the
breakout is kept as history of that era.
# Host unit tests of the pure core — no hardware needed:
pio test -e native
# Compile / upload the firmware (fetches lib_deps):
pio run -e esp32s3
pio run -e esp32s3 -t upload
pio device monitor -b 115200Arm subsystem firmware has its own project: arm/.
The robot is driven from a gamepad, not a serial console. bench_ble/ runs
Bluepad32, which owns stdin: Console is output-only and Serial is never
begin()-ed, so typed commands cannot reach the firmware. Every operator
control is a gamepad button. See docs/gotchas.md §6.
The base prints status to the console as it runs; that is one-way.
A
DOCK/ABORT/UNCLAMP/STATUSserial protocol was designed and the parser written, but it never ran on hardware — see Project history below.
🛑 The table below is WRONG. Do not wire or flash from it.
It is the pre-PCB design intent and does not match the fabricated board. On the real board GPIO4–7 are the ToF XSHUT lines, not wheel SV, and GPIO38/39 are motor brake lines, not I²C. Using this map would drive the I²C bus as motor enables.
The real map is
include/pins.h, extracted from the KiCad netlist, with per-connector pinouts indocs/hardware/boards.md.Kept here only because it is referenced by older notes. It should be deleted.
Reserved on the N16R8: GPIO26–37 (flash + octal PSRAM) and GPIO19/20 (USB-CDC).
| Group | Signals | GPIO |
|---|---|---|
| Wheel speed (SV, PWM) | FL/FR/RL/RR | 4, 5, 6, 7 |
| Wheel direction (F/R) | FL/FR/RL/RR | 15, 16, 17, 18 |
| Wheel enable / brake (ganged) | EN / BRK | 8 / 9 |
| Clamp (BTS7960) | RPWM / LPWM / EN | 11 / 12 / 13 |
| Clamp current sense (ADC1) | IS close / open | 1 / 2 |
| Limit switches | open / closed | 14 / 21 |
| ToF I²C | SDA / SCL | 38 / 39 |
These adapters were validated on the assembled robot over the 2026 term. Kept as a bring-up order for a rebuild, or after a board respin:
PwmPin shim supports Arduino-ESP32 core 2.x and 3.x automatically.F/R forward sense, and active-low EN/BRK (Bld120aMotor.h). There
is no ALARM: the driver has no such terminal, only a front-panel LED.MecanumDrive.cpp) and the
ORIENT rotate-direction sign in DockingStateMachine.cpp (rotate toward the lagging corner).pins::kTofXSHUT; Vl53l0xArray is the
default backend since the mux approach was retired); set the board
height band (makeCornerConfig).max_lin_mm_s / max_ang_rad_s (makeOdometryCal); tune the
centring tolerance/offsets in makeDockConfig.cfg::kWheelStallAmps under a loaded trolley. Note the
ACS758 outputs are not currently wired to J9/J12/J14/J17, so this reads nothing until they are
(docs/hardware/components.md §4). The clamp is on the arm board,
not this one.corners, x_mm, y_mm, confirmed). The
clamp/arm subsystem is external and validated separately at the IClamp handoff.Connector-level references for all boards (every pin extracted from the KiCad netlists):
docs/hardware/boards.md.
| Board | Size | KiCad project | Job |
|---|---|---|---|
| Wheel Drive PCB | 130 × 105 mm | KiCad/Wheel Drive PCB/ | base ESP + 4 motor-driver adapters + all base sensors |
| Driver PCB ×4 | 42.8 × 33.8 mm | KiCad/Driver PCB/ | 3.3 V → open-collector adapter, one per motor |
| Arm Subsystem PCB | 110 × 110 mm | KiCad/Arm Subsystem PCB/ | arm ESP + 2 H-bridges + servos + 8 limit switches |
| PCA9548A breakout | — | KiCad/PCA9548A Breakout/ | I²C mux — historical, see ToF note above |
JLCPCB fab outputs ship with each project (fab-output/ folders; the Arm board's zip is in its
folder). Board designs by Kai Xiang & Heng Li (arm/wheel sensor side) and Bryan Lim (base).
| Load test — ≥100 kg requirement load, two people on top | |
| Mecanum base driving and strafing | |
| Arm extension / flipper / release sequence | |
| Clamped onto a trolley |
(GitHub renders <video> tags in markdown; if your viewer doesn't, open the files under
docs/media/videos/.)
| File | What it shows |
|---|---|
trolley-carry-demo.mp4 | full trolley-carry run (1:49) |
clamping-on-sequence.mp4 | clamp engaging under the trolley (0:56) |
rail-strength-test.mp4 | rail strength durability test (0:29) |
img-3340.mp4 | bench footage (0:51) |
img-3350.mp4 | bench footage (0:43) |
video-2026-07-13.mp4 | mid-build progress clip (0:16) |
video-2026-07-17.mp4 | mid-build progress clip (0:10) |
clip-20260707.mp4 | early drive test (0:05) |
(SVGs render inline above; click through for the higher-resolution PNGs.)
| Member | Focus areas |
|---|---|
| Chan Long Nam | mechanical structure & clamping system |
| Chong Shao Yih | chassis & integration |
| Chua Heng Li | electronics: arm-subsystem & wheel-drive PCBs, power wiring, arm firmware |
| Jacelyn Tan | systems analysis & testing |
| Lim Nguyen Ping, Bryan | drive firmware, sensing & base architecture (this repo) |
| Lucas Lim Kong Keong | clamping mechanism & materials |
| Soh Kai Siang | power distribution & wiring; co-author of arm firmware |
Rows are initial attributions — each member, feel free to refine your own.
| Path | What it is |
|---|---|
src/ | firmware entry + bench bring-up sketches |
lib/ | hexagonal core: ports, domain, drive, fakes, ESP32 adapters |
include/ | tunables (config.h) and GPIO map (pins.h) |
test/ | host unit tests (Unity, pio test -e native) |
arm/ | vendored arm-subsystem firmware (ESP-NOW slave) |
KiCad/ | four custom board projects + fab outputs |
bench_ble/ | BLE-gamepad bench firmware |
tools/ | PCB production test |
docs/ | specs, gotchas, hardware references, runbooks, session history, media |
Kept because knowing what was attempted saves repeating it. None of the below is part of the delivered machine.
| Abandoned | What it was | Why it went |
|---|---|---|
| AS5600 wheel encoders | four magnetic encoders, one per wheel, for closed-loop speed | Never worked on the fabricated board: pin 1 of every 1×04 encoder header is unconnected, and all four parts share address 0x36 on a commoned bus. The sensors and shaft magnets are still physically mounted on the motors, unwired and undriven. docs/gotchas.md §13 |
| TCA9548A / PCA9548A I²C mux | fitted to give the four encoders separate addresses | Went with the encoders. An external PCA9548-type mux overheated and failed with more than two AS5600 attached. The ToF sensors never needed it — they use XSHUT re-addressing. Board files kept at KiCad/PCA9548A Breakout/ |
| Raspberry Pi 5 as main controller | Pi 5 driving two ESP32s over USB serial, with a link watchdog | Never used. The delivered prototype runs on the two ESP32s alone, base ↔ arm over ESP-NOW. Design retained at docs/superpowers/specs/2026-08-04-rpi5-main-controller-design.md |
DOCK/ABORT/UNCLAMP/STATUS serial protocol | text commands in, JSON telemetry out | The parser was written but Bluepad32 owns stdin, so it never ran. Operator control is the gamepad. docs/gotchas.md §6 |
| Hardware E-stop input | a GPIO for an emergency-stop button | Discussed, never implemented. The red mushroom button on the robot is wired as an enable for the 12 V arm rail — docs/hardware/startup.md §1 |
| Base-board clamp driver | BTS7960 clamp driven from the base ESP | Moved to the arm subsystem. The base pins remain kNoPin so the one-ESP firmware still compiles |
Code for the encoders, the mux and the Pi was deleted on 2026-08-31 rather
than left to rot — git log --diff-filter=D recovers any of it. What was worth
keeping is the analysis of why each failed, which lives in
docs/gotchas.md and docs/hardware/.
| Qty | Value | Footprint | References |
|---|---|---|---|
| 4 | MountingHole | MountingHole:MountingHole_3.2mm_M3 | H1, H2, H3, H4 |
| 1 | Arm Motor X | Connector_PinHeader_2.54mm:PinHeader_1x06_P2.54mm_Vertical | J1 |
| 1 | Arm Motor Y | Connector_PinHeader_2.54mm:PinHeader_1x06_P2.54mm_Vertical | J2 |
| 1 | ESP32-S3-DevKitC | HengLi's Footprint Library:ESP32-S3-DevKitC-N16R8 | U1 |
| 1 | External Buck 5V and GND | TerminalBlock_Phoenix:TerminalBlock_Phoenix_MKDS-1,5-2-5.08_1x02_P5.08mm_Horizontal | J3 |
| 1 | Limit Switch X1 | Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical | SW1 |
| 1 | Limit Switch X2 | Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical | SW4 |
| 1 | Limit Switch Y1 | Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical | SW2 |
| 1 | Limit Switch Y2 | Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical | SW5 |
| 1 | Servo X1 | Connector_PinHeader_2.54mm:PinHeader_1x03_P2.54mm_Vertical | S1 |
| 1 | Servo X2 | Connector_PinHeader_2.54mm:PinHeader_1x03_P2.54mm_Vertical | S2 |
| 1 | Servo Y1 | Connector_PinHeader_2.54mm:PinHeader_1x03_P2.54mm_Vertical | S3 |
| 1 | Servo Y2 | Connector_PinHeader_2.54mm:PinHeader_1x03_P2.54mm_Vertical | S4 |
| 1 | ToF X1 | Connector_PinHeader_2.54mm:PinHeader_1x06_P2.54mm_Vertical | TOF1 |
| 1 | ToF X2 | Connector_PinHeader_2.54mm:PinHeader_1x06_P2.54mm_Vertical | TOF3 |
| 1 | ToF Y1 | Connector_PinHeader_2.54mm:PinHeader_1x06_P2.54mm_Vertical | TOF2 |
| 1 | ToF Y2 | Connector_PinHeader_2.54mm:PinHeader_1x06_P2.54mm_Vertical | TOF4 |
| 1 | X Limit Max | Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical | SW3 |
| 1 | X Limit Min | Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical | SW7 |
| 1 | Y Limit Max | Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical | SW8 |
| 1 | Y Limit Min | Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical | SW6 |

lnpanini/Falali
An AMR-style under-ride platform that drives beneath a textile trolley, uses upward-facing time-of-flight sensors to confirm it is under the trolley and centred, clamps onto the underside, and then moves the trolley.

lnpanini/Falali
An AMR-style under-ride platform that drives beneath a textile trolley, uses upward-facing time-of-flight sensors to confirm it is under the trolley and centred, clamps onto the underside, and then moves the trolley.

willem-pennings/balancing-cube
A cube that balances itself in a corner or edge using reaction wheels

jazzmonger/Traeger-PID-Controller
Traeger Smoker/Grill Controller based on an

ohasanov-hbrw/tribit32-advanced
A tri-microcontroller, overengineered GameBoy Advance clone. More value was given to the controls and the exterior look, which is cool!



FIPATECH/CDFR26_PAMI
Open source firmware and PCB for a differential mobile robot (PAMI) based on ESP32-S3 - Coupe de France de Robotique

dnhutchins/ETC_Express_Reverse_Eng
The ultimate goal of this work is to develop an interface to use the control surface from a legacy ETC Express 24/48 lighting controller as a modern EOSNomad compatible programming and fader wing.

heckler/esphome-device-configs
Configuration definitions for local ESPHome files
It measures 110 × 110 mm and has 2 copper layers, 1.6 mm thick.
24 parts, built around the ESP32-S3-DEVKITC-1-N8. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.
From the lnpanini/Falali repository on GitHub, at the commit this page was made from: the board is KiCad/Arm Subsystem PCB/Arm Subsystem PCB.kicad_pcb and its schematic KiCad/Arm Subsystem PCB/Arm Subsystem PCB.kicad_sch. PCBKit opens the board in the browser, with nothing to install.
Its repository states no licence, so its author keeps all rights: ask lnpanini before reusing the design.