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.

Status: working on hardware. The configuration in this repo is the one that runs, not the one that ought to.

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.)

Toolchain versions — pin these

Board	Package / library	Version
A	esp32_bluepad32	4.1.0
B	esp32 (Espressif)	2.0.17
B	NimBLE-Arduino	1.4.x
B	Legoino	latest

Board B is the fussy one. Core 3.x will not build Legoino. ESP-IDF 5 changed uint32_t from unsigned int to unsigned long, so Legoino's own header and .cpp no longer agree, and it never included <string> itself. The symptoms are:

'string' in namespace 'std' does not name a type
no declaration matches 'uint32_t LegoinoCommon::ReadUInt32LE(uint8_t*, int)'

Downgrade the core rather than patching the library — patching works, but it is the first of several layers and any Library Manager update silently reverts it. Board A is unaffected; it uses a separate package.

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, or 4 if you daisy-chain power.

  Board A (Bluepad32)          Board B (Legoino)
  GPIO17 TX  ------------->    GPIO16 RX
  GPIO16 RX  <-------------    GPIO17 TX
  GND        --------------    GND          <- do not skip this one
  5V         --------------    5V           <- only in the model setup, see below

TX goes to RX, not TX to TX. If nothing arrives, that swap is the first thing to check.

Without a common ground the UART has no shared voltage reference and you get garbage or silence, so that wire is not optional even when both boards have their own USB.

Power

Two arrangements, and the choice matters more than it looks.

Bench setup — separate USB, no 5V wire. Both boards on their own USB cables. You get both serial monitors and can reflash either board without unplugging anything. Use this for everything up to step 5.

Model setup — one supply, 5V jumper. USB into board A, then a fourth wire from A's 5V pin to B's 5V pin (labelled VIN on some boards). Ground is already joined by the wire you have.

Use 5V to 5V, never 3.3V to 3.3V. Each board's onboard AMS1117 regulator makes its own 3.3V, and tying the outputs together back-feeds one regulator from the other.

Never have both USB cables plugged in while the 5V wire is connected. That ties two host supplies together through your jumper. Some devkits have a Schottky diode on VBUS that prevents it, plenty do not, and you cannot tell by looking. Pull the 5V jumper before plugging in a USB cable to reflash.

Current budget. An ESP32 idles around 80-120mA and peaks at a few hundred mA on Bluetooth transmit. Two of them off one USB 2.0 port sits right at the 500mA that port promises. It usually works, but a marginal supply shows up as random reboots that look exactly like a software fault. A 1A+ charger or power bank removes the doubt.

Diode drops. Many boards put a diode between VBUS and the 5V pin, so board A's 5V pin sits nearer 4.7V. Through board B's own diode you are at maybe 4.4V into a regulator wanting roughly 1.1V of headroom. It works, but the margin is thin. If you are running off a power bank anyway, prefer separate leads to each board's 5V pin over chaining B off A — same wire count, no stacked drops.

Test the power-loss case deliberately

The 400ms failsafe in receiver.ino only fires if the receiver is running. If board B loses power mid-command — and on a shared supply that now happens whenever board A does — the failsafe cannot fire, and whether the motors stop is left to the hub's own behaviour on BLE disconnect.

Find that out on purpose rather than by accident. Set a track running slowly, pull power from board B, and watch what the motor does. If it keeps running you want a physical switch on the hubs within arm's reach before driving this anywhere interesting.

Worth doing the same test by pulling the UART wire instead — that path does hit the failsafe, and confirming it works takes ten seconds.

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, version 2.0.17. Library Manager -> NimBLE-Arduino pinned to 1.4.x, then Legoino. See the toolchain table above for why the versions matter.

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.

Nothing else may be holding the hubs. A hub accepts one connection at a time and stops advertising once taken, so power down any other ESP32 and close the LEGO Powered Up app before scanning.

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 step is not optional busywork. On this build the two hub addresses were the wrong way round, and the symptom — an arm moving when the track stick moved — looks exactly like a software bug. It is not one, and no amount of reading the code will find it.

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)
Cross / Triangle	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.

Motor directions are the DIR_* constants at the top of receiver.ino. Flip one to -1 if an axis runs backwards — mirrored mountings are normal on a symmetric model. DIR_RIGHT_TRACK is -1 on this build.

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,<lx>,<ly>,<rx>,<ry>,<buttons>,<dpad>,<l2>,<r2>*<XX>\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

• 'Frame' has not been declared, or any type "not declared" at its own definition. The Arduino IDE injects generated prototypes immediately before the first function definition in the file. Any type used in a signature must be declared above that point — which is why HubLink, PortState and Frame all sit in one block near the top. Do not move a function above them.
• Legoino will not compile. Core 3.x. See the toolchain table.
• Nothing arrives at board B. TX/RX swapped, or no common ground. Both are silent failures.
• Random reboots under load. Supply, not software. See the current budget above.
• Hubs never connect. Something else is holding them, or they went to sleep. Power down other controllers, close the LEGO app, press the green buttons.
• 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)