Build and deploy: docs/BUILD.md. This will not compile out of the box — the board package ships the BTstack headers but does not put them on the include path, and that has to be fixed first.

Controls and port map: docs/CONTROLS.md.

How it avoids the stack collision

The reason the obvious sketch fails is that Bluepad32 (BTstack) and Legoino (NimBLE) are two Bluetooth host stacks fighting over one radio. The fix here is to have only one stack: BTstack does the gamepad and the hubs.

Bluepad32 v4 already compiles BTstack with LE central and a GATT client, since it supports BLE gamepads like the Xbox v5 firmware pads. That machinery is sitting there unused for our purposes, so this sketch borrows it and speaks the LEGO Wireless Protocol directly. No Legoino, no NimBLE.

What you give up: everything Legoino did for you. Sensor callbacks, tacho positioning, hub name reads. What you get back is one board and about 450 lines. Port detection we got back cheaply — see below.

The two rules

1. Threading. BTstack is not thread-safe, and loop() does not run on the BTstack task. From the Bluepad32 docs, the only BTstack call that is safe from anywhere is btstack_run_loop_execute_on_main_thread().

So the LEGO side lives entirely inside a repeating BTstack timer, which is scheduled once at boot via that one safe call. loop() never touches BTstack — it reads the sticks and writes plain ints into gDesired, and the timer picks them up. Any BTstack call added to loop() will crash at random places, which is the worst kind of bug to chase.

2. Boot order. Gamepad discovery starts disabled. Both hubs connect first, then BP32.enableNewBluetoothConnections(true) opens up for the pad. Bluepad32's inquiry and LE scan otherwise run at the same time as our LE create-connection and the hub connects unreliably or not at all.

Layout

ps4_lego_onebrain/ps4_lego_onebrain.ino   the sketch
docs/BUILD.md                             install, include-path fix, first run
docs/CONTROLS.md                          port map, control layout, power caps
docs/platform.local.txt                   the include-path override, for restoring
                                          after a Bluepad32 package update

The protocol

Everything the motors need is one 8-byte write, no response, to characteristic 00001624-1212-EFDE-1623-785FEABCD123 inside service ...1623...:

08 00 81 <port> 11 51 00 <power>
│  │  │  │      │  │  │  └── int8, -100..100 (127 = brake)
│  │  │  │      │  │  └───── mode 0x00 = POWER
│  │  │  │      │  └──────── subcommand 0x51 = WriteDirectModeData
│  │  │  │      └─────────── 0x11 = execute immediately + command feedback
│  │  │  └────────────────── port: A=0x00 B=0x01 C=0x02 D=0x03, LED=0x32
│  │  └───────────────────── message type 0x81 = Port Output Command
│  └──────────────────────── hub ID, always 0x00
└─────────────────────────── message length

That same shape sets the hub LED — port 0x32, payload is a colour index (0x06 is green, which the sketch uses to show a hub came up).

Mode 0 is direct power, so it works on train motors and Technic motors alike. There is no tacho-vs-basic distinction to get wrong here. The trade-off is that you get no closed-loop speed control — power is power, and the motor slows under load. StartSpeed (subcommand 0x07) does regulate, if you want it later.

Going the other way, the sketch subscribes to notifications on the same characteristic and decodes two inbound messages:

0x04 Hub Attached I/O — the hub announces every populated port the instant notifications go live, so the serial log tells you what is actually plugged in rather than what you think is. Device type IDs come from pybricks/technical-info.
0x05 Generic Error — rejected commands used to vanish silently.

Full spec: https://lego.github.io/lego-ble-wireless-protocol-docs/

Known rough edges

No end-stop protection. Every axis except the tracks runs into a mechanical stop and there is no position feedback, so holding a direction at a stop stalls the motor. The power caps in docs/CONTROLS.md are the only thing standing between you and stripped gears. Control+ motors have absolute encoders, so this is fixable properly with Port Input Format Setup (0x41).
Write-without-response can fail silently when ACL buffers are full. The tick retries 25ms later, so a dropped command is invisible in practice, but do not treat a single write as a guarantee.
No failsafe timer on the gamepad side beyond isConnected(). If the pad goes out of range the stack can take 20 seconds to notice. The Bluepad32 FAQ has a hasData() plus timeout pattern worth adding.
Rate limits are tuned by feel, not measurement — see docs/CONTROLS.md.

If something misbehaves, turn on verbose BTstack logging first. Nearly every failure here shows up as a specific HCI event you can read.

Created by: Jess Rogerson (yelling commands at Claude.AI)