jessikitty
6c476afb08
Adds bench vs model power arrangements, the both-USB-plus-5V-jumper hazard, current budget, diode drop margin, and a deliberate test for the case the 400ms failsafe cannot cover.
214 lines
9.0 KiB
Markdown
214 lines
9.0 KiB
Markdown
# 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, 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. 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,<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
|
|
|
|
* **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.
|
|
* **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)
|