# ps4-lego-bridge PS4 controller -> two LEGO Technic hubs, using two ESP32 boards. Driving a Johnny 5 (Short Circuit) MOC — seven motors across two hubs. ## Why two boards The obvious sketch — Bluepad32 for the gamepad, Legoino for the hubs, one ESP32 — does not work, and it is not a library-version problem. * **Bluepad32** needs Bluetooth Classic (BR/EDR), because a DualShock 4 is a BR/EDR device. It gets that from **BTstack**, and it ships as a whole replacement ESP32 board package rather than a normal library. * **Legoino** talks to the hubs over BLE using **NimBLE-Arduino**. BTstack and NimBLE are both Bluetooth *host* stacks. There is one radio and one VHCI interface on the chip, and whichever stack registers second wins. You cannot run both in one firmware image. So: board A runs Bluepad32 and nothing else. Board B runs Legoino and nothing else. Three jumper wires between them. (The single-board version, which speaks the LEGO protocol directly against BTstack, lives in `ps4-lego-onebrain`. It works, but it is a lot more code and a lot more ways to be wrong.) ## Hardware * 2x ESP32 dev boards. Both must be the **original ESP32** (WROOM/WROVER). S3, C3, C6 and H2 have no Bluetooth Classic, so a PS4 pad will not pair. * 3 jumper wires. ``` Board A (Bluepad32) Board B (Legoino) GPIO17 TX -------------> GPIO16 RX GPIO16 RX <------------- GPIO17 TX GND -------------- GND <- do not skip this one ``` TX goes to RX, not TX to TX. If nothing arrives, that swap is the first thing to check. Power both from the same supply if you can. Separate USB bricks are fine as long as the grounds are tied together — without a common ground the UART has no shared voltage reference and you get garbage or silence. ## Step by step **1. Board A — the gamepad board.** Preferences -> Additional board manager URLs, add: ``` https://raw.githubusercontent.com/ricardoquesada/esp32-arduino-lib-builder/master/bluepad32_files/package_esp32_bluepad32_index.json ``` Boards Manager -> install **esp32_bluepad32**. Tools -> Board -> pick ESP32 Dev Module from under **esp32_bluepad32**, not the plain `esp32` group. Getting that wrong is what produces `fatal error: Bluepad32.h: No such file or directory`. Flash `transmitter/transmitter.ino`. Nothing else needs installing — Bluepad32 lives inside the board package. Do not install Legoino or NimBLE on this board. **2. Pair the pad, before wiring anything.** Open Serial Monitor at 115200. Hold SHARE + PS on the controller until the light bar flashes. You want `Controller connected in slot 0`. Once it pairs reliably, comment out `BP32.forgetBluetoothKeys()` in `setup()` — it is in there to clear stale pairings, and leaving it means re-pairing on every boot. Set `DEBUG_FRAMES` to 1 temporarily and confirm frames stream past as you move the sticks. If they do, board A is finished. **3. Board B — the hub board.** Boards Manager -> the standard **esp32** package by Espressif. Library Manager -> **NimBLE-Arduino**, pinned to **1.4.x** (Legoino has not moved to the 2.x API, and 2.x gives a wall of compile errors), then **Legoino**. Flash `tools/hub_scanner/hub_scanner.ino` first. Press each hub's green button and note the addresses it reports, then paste them into `receiver.ino` as `HUB0_ADDR` and `HUB1_ADDR`. **4. Verify the port map before you trust it.** Flash `receiver/receiver.ino` with `DEBUG_MOTORS` set to 1. Every motor command logs which hub and port it lands on. Move one control at a time and check the log matches what physically moves. This is worth doing properly — a swapped hub address or a motor in the wrong port looks exactly like a software bug and will waste an afternoon. Set `DEBUG_MOTORS` back to 0 once it checks out. **5. Wire the boards together** per the diagram above, power both, and drive it. Onboard LED on board A is solid when the pad is connected. On board B it is solid when both hubs are connected. ## Controls Tank drive — every input drives exactly one motor. | Input | Function | | --- | --- | | Left stick Y | Left track (hub 0 port B) | | Right stick Y | Right track (hub 0 port A) | | D-pad up / down | Head tilt (hub 1 port A) | | D-pad left / right | Head turn (hub 1 port B) | | R2 / L2 | Body lift up / down, proportional (hub 0 port D) | | Square / Circle | Left arm up / down (hub 1 port C) | | Triangle / Cross | Right arm up / down (hub 1 port D) | | L1 held | Precision, 40% track speed | | R1 held | Full, 100% track speed | | L1 + R1 | All stop | Default track scale is 75%. Stick X axes are unused. **Everything except the tracks runs into a mechanical end stop**, and there is no position feedback, so holding a direction at a stop stalls the motor. That is what `HEAD_MAX`, `LIFT_MAX` and `ARM_MAX` are for. Lower them if an axis feels forceful, and do not hold a direction once an axis has stopped moving. ## Link protocol ASCII, newline terminated, 115200 8N1: ``` G,,,,,,,,*\n ``` * axes are Bluepad32 raw values, -512..511 * `buttons` is the 16-bit mask, `dpad` the 8-bit mask, both decimal * `l2`/`r2` are the analog triggers, 0..1023 * `XX` is a two-digit hex XOR checksum of everything before the `*` Plain text means you can watch the link with any USB-serial adapter when something misbehaves. The receiver drops any frame that fails the checksum, and stops all motors if nothing valid arrives for 400ms. ## Things that bite * **Nothing arrives at board B.** TX/RX swapped, or no common ground. Both are silent failures. * **One hub connects, the other does not.** Legoino shares a single NimBLE scanner. `receiver.ino` connects them strictly one at a time for this reason — do not "optimise" that into two parallel `init()` calls. * **Motors stutter or a hub drops out.** Commands are outrunning the hub. Raise `MOTOR_MIN_GAP_MS` (per port) or `HUB_MIN_GAP_MS` (per hub). Hub 1 carries four motors, which is why the per-hub limit exists at all. * **Wrong motor command.** Technic/Control+ motors want `setTachoMotorSpeed`; train and simple PU motors want `setBasicMotorSpeed`. Toggle `USE_TACHO_MOTORS`. * **Button masks.** The values in `receiver.ino` are Bluepad32's standard layout. If a face button does the wrong thing, set `DEBUG_BUTTONS` in the transmitter, press each one, and correct the constants. * **More than 3 hubs later on.** Edit `CONFIG_BT_NIMBLE_MAX_CONNECTIONS` in `NimBLE-Arduino/src/nimconfig.h`, then restart the IDE to force a rebuild. --- Created by: Jess Rogerson (yelling commands at Claude.AI)