Document tank drive layout and NVS pairing reset

docs/CONTROLS.md

@@ -2,6 +2,9 @@
 
 Model: Johnny 5 (Short Circuit) MOC. Seven motors across two Technic hubs.
 
+Control scheme is **tank drive**: every input drives exactly one motor. Nothing
+is mixed, so a single stick can never command two motors at once.
+
 ## Port map
 
 | Hub | Address | Port | Function | Desired field |
@@ -33,28 +36,35 @@ attached too. Anything not on A–D can be ignored.
 
 | Input | Function |
 | --- | --- |
-| Left stick Y | Drive forward / back |
-| Left stick X | Turn |
-| Right stick X | Head turn |
-| Right stick Y | Head tilt |
+| Left stick Y | Left track |
+| Right stick Y | Right track |
+| D-pad up / down | Head tilt |
+| D-pad left / right | Head turn |
 | R2 | Body lift up (proportional) |
 | L2 | Body lift down (proportional) |
-| D-pad up / down | Left arm up / down |
+| Square / Circle | Left arm up / down |
 | Triangle / Cross | Right arm up / down |
-| L1 (held) | Precision mode, 40% drive |
-| R1 (held) | Full speed, 100% drive |
-| Circle | All stop |
+| L1 (held) | Precision mode, 40% track speed |
+| R1 (held) | Full speed, 100% track speed |
+| L1 + R1 together | All stop |
 
-Default drive scale is 75%.
+Default track scale is 75%. The stick X axes are unused.
 
-Bluepad32 names buttons Xbox-style, so in the code `y()` is Triangle, `a()` is
-Cross and `b()` is Circle. `throttle()` is R2 and `brake()` is L2, both analog
-0–1023.
+Bluepad32 names buttons Xbox-style, so in the code `x()` is Square, `b()` is
+Circle, `y()` is Triangle and `a()` is Cross. `throttle()` is R2 and `brake()`
+is L2, both analog 0–1023.
 
-Why this layout: arcade drive on one stick keeps the other free for the head,
-which is the expressive part of this model. The analog triggers go to body lift
-because it is the heavy slow axis that benefits most from proportional feel.
-Arms are digital because they are pose-and-hold, not modulate.
+Trade-offs in this layout:
+
+* **Tracks are independent.** Turning means pushing one stick further than the
+  other, like a skid-steer. Takes a minute to get used to, but you always know
+  which motor you are commanding.
+* **The head is digital now**, not proportional — d-pad has no analog travel, so
+  it runs at a fixed `HEAD_MAX`. Drop that constant if it moves too fast to aim.
+* **Body lift kept the triggers** because they are the only remaining analog
+  inputs, and it is the axis that benefits most from proportional control.
+* **D-pad diagonals** will tilt and turn the head simultaneously. That is two
+  motors from one thumb, but only when you deliberately press a diagonal.
 
 To remap, set `DEBUG_BUTTONS` to 1 at the top of the sketch and press each
 button — it prints the mask so you can match your pad's firmware exactly.
@@ -63,7 +73,7 @@ button — it prints the mask so you can match your pad's firmware exactly.
 
 ```cpp
 static const int TRACK_MAX = 100;
-static const int HEAD_MAX  = 50;
+static const int HEAD_MAX  = 45;
 static const int LIFT_MAX  = 60;
 static const int ARM_MAX   = 45;
 ```
@@ -95,6 +105,20 @@ from both and always go out immediately.
 If motors feel laggy, lower `MOTOR_MIN_GAP_MS` before touching the hub limit.
 If a hub drops out under heavy stick movement, raise `HUB_MIN_GAP_MS`.
 
+## Clearing stale pairings
+
+Bluepad32 stores Bluetooth pairing keys in NVS, and **reflashing the sketch does
+not clear them**. If you end up with a pad paired into more than one slot, or an
+old device from a previous build still remembered, uncomment this in `setup()`:
+
+```cpp
+BP32.forgetBluetoothKeys();
+```
+
+Flash once, re-pair, then comment it out again — leaving it in means re-pairing
+on every boot. For a full wipe, Tools → Erase All Flash Before Sketch Upload →
+Enabled, upload once, then set it back to Disabled.
+
 ---
 
 Created by: Jess Rogerson (yelling commands at Claude.AI)