diff --git a/docs/wiring.svg b/docs/wiring.svg
new file mode 100644
index 0000000..f1a3f0b
--- /dev/null
+++ b/docs/wiring.svg
@@ -0,0 +1,90 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 740" width="760" height="740" role="img" aria-labelledby="t d">
+<title id="t">Johnny 5 wiring pinout - both ESP32 boards and both LED circuits</title>
+<desc id="d">Board A runs Bluepad32 and pairs with the PS4 controller. Board A GPIO17 goes to Board B GPIO16; Board A GPIO16 goes to Board B GPIO17; the grounds are joined as a shared reference. Board B runs Legoino, connects to two LEGO hubs over BLE, and drives two independent LED circuits: GPIO25 through a 220 ohm resistor to the red LED pair and back to a ground rail, and GPIO26 through a 100 ohm resistor to the green LED pair and back to the same ground rail. Each LED has its own complete path; they are never in series.</desc>
+<style>
+  .bg{fill:#fbfaf8}
+  .box{fill:#fff;stroke-width:1.2}
+  .p{stroke:#7F77DD;fill:#f3f2fd}
+  .t{stroke:#2E8B8B;fill:#eef7f7}
+  .r{stroke:#D85A30;fill:#fdf1ec}
+  .g{stroke:#3D9A50;fill:#eef8f0}
+  .b{stroke:#3B6FB5;fill:#eef3fb}
+  .n{stroke:#888780;fill:#f4f4f2}
+  text{font-family:ui-sans-serif,system-ui,'Segoe UI',Helvetica,Arial,sans-serif;fill:#20201d}
+  .h{font-size:15px;font-weight:600}
+  .s{font-size:12px}
+  .xs{font-size:11px;fill:#5a5a54}
+  .w{stroke-width:2;fill:none}
+</style>
+<rect class="bg" x="0" y="0" width="760" height="740"/>
+<defs><marker id="ar" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></marker></defs>
+
+<rect class="box r" x="30" y="20" width="150" height="40" rx="8"/>
+<text class="s" x="105" y="39" text-anchor="middle">PS4 controller</text>
+<text class="xs" x="105" y="54" text-anchor="middle">Bluetooth Classic</text>
+<line class="w" x1="105" y1="60" x2="105" y2="94" stroke="#888780" marker-end="url(#ar)"/>
+
+<rect class="box p" x="30" y="98" width="230" height="182" rx="12"/>
+<text class="h" x="145" y="124" text-anchor="middle">BOARD A</text>
+<text class="xs" x="145" y="141" text-anchor="middle">esp32_bluepad32 4.1.0</text>
+<text class="xs" x="145" y="156" text-anchor="middle">transmitter.ino</text>
+<rect class="box p" x="170" y="170" width="84" height="24" rx="4"/><text class="s" x="212" y="187" text-anchor="middle">TX 17</text>
+<rect class="box p" x="170" y="200" width="84" height="24" rx="4"/><text class="s" x="212" y="217" text-anchor="middle">RX 16</text>
+<rect class="box n" x="170" y="230" width="84" height="24" rx="4"/><text class="s" x="212" y="247" text-anchor="middle">GND</text>
+
+<rect class="box t" x="440" y="98" width="230" height="182" rx="12"/>
+<text class="h" x="555" y="124" text-anchor="middle">BOARD B</text>
+<text class="xs" x="555" y="141" text-anchor="middle">esp32 core 2.0.17</text>
+<text class="xs" x="555" y="156" text-anchor="middle">receiver.ino</text>
+<rect class="box t" x="446" y="170" width="84" height="24" rx="4"/><text class="s" x="488" y="187" text-anchor="middle">RX 16</text>
+<rect class="box t" x="446" y="200" width="84" height="24" rx="4"/><text class="s" x="488" y="217" text-anchor="middle">TX 17</text>
+<rect class="box n" x="446" y="230" width="84" height="24" rx="4"/><text class="s" x="488" y="247" text-anchor="middle">GND</text>
+<rect class="box r" x="576" y="170" width="88" height="24" rx="4"/><text class="s" x="620" y="187" text-anchor="middle">GPIO 25</text>
+<rect class="box g" x="576" y="200" width="88" height="24" rx="4"/><text class="s" x="620" y="217" text-anchor="middle">GPIO 26</text>
+<rect class="box n" x="576" y="230" width="88" height="24" rx="4"/><text class="s" x="620" y="247" text-anchor="middle">GND 2</text>
+
+<line class="w" x1="256" y1="182" x2="442" y2="182" stroke="#D85A30" marker-end="url(#ar)"/>
+<line class="w" x1="444" y1="212" x2="258" y2="212" stroke="#7F77DD" marker-end="url(#ar)"/>
+<line class="w" x1="256" y1="242" x2="444" y2="242" stroke="#888780"/>
+<text class="xs" x="350" y="166" text-anchor="middle">UART link 115200 8N1</text>
+<text class="xs" x="350" y="262" text-anchor="middle">shared voltage reference only - do NOT hang LED current off this</text>
+
+<rect class="box b" x="440" y="300" width="108" height="40" rx="8"/>
+<text class="s" x="494" y="318" text-anchor="middle">Hub 0 (BLE)</text><text class="xs" x="494" y="333" text-anchor="middle">A B D</text>
+<rect class="box b" x="558" y="300" width="108" height="40" rx="8"/>
+<text class="s" x="612" y="318" text-anchor="middle">Hub 1 (BLE)</text><text class="xs" x="612" y="333" text-anchor="middle">A B C D</text>
+<line class="w" x1="555" y1="282" x2="555" y2="296" stroke="#888780" marker-end="url(#ar)"/>
+
+<line x1="30" y1="380" x2="730" y2="380" stroke="#c9c8c3" stroke-width="1" stroke-dasharray="4 4"/>
+<text class="h" x="30" y="408">LED circuits - two separate loops, board B only</text>
+
+<rect class="box r" x="30" y="430" width="88" height="26" rx="4"/><text class="s" x="74" y="448" text-anchor="middle">GPIO 25</text>
+<line class="w" x1="120" y1="443" x2="164" y2="443" stroke="#D85A30"/>
+<rect class="box r" x="166" y="430" width="96" height="26" rx="4"/><text class="s" x="214" y="448" text-anchor="middle">220&#937;</text>
+<line class="w" x1="264" y1="443" x2="308" y2="443" stroke="#D85A30"/>
+<rect class="box r" x="310" y="424" width="150" height="38" rx="6"/>
+<text class="s" x="385" y="441" text-anchor="middle">RED pair</text>
+<text class="xs" x="385" y="456" text-anchor="middle">long leg faces this side</text>
+<line class="w" x1="462" y1="443" x2="596" y2="443" stroke="#D85A30"/>
+
+<rect class="box g" x="30" y="510" width="88" height="26" rx="4"/><text class="s" x="74" y="528" text-anchor="middle">GPIO 26</text>
+<line class="w" x1="120" y1="523" x2="164" y2="523" stroke="#3D9A50"/>
+<rect class="box g" x="166" y="510" width="96" height="26" rx="4"/><text class="s" x="214" y="528" text-anchor="middle">100&#937;</text>
+<line class="w" x1="264" y1="523" x2="308" y2="523" stroke="#3D9A50"/>
+<rect class="box g" x="310" y="504" width="150" height="38" rx="6"/>
+<text class="s" x="385" y="521" text-anchor="middle">GREEN pair</text>
+<text class="xs" x="385" y="536" text-anchor="middle">long leg faces this side</text>
+<line class="w" x1="462" y1="523" x2="596" y2="523" stroke="#3D9A50"/>
+
+<line class="w" x1="598" y1="443" x2="598" y2="523" stroke="#888780"/>
+<line class="w" x1="598" y1="483" x2="658" y2="483" stroke="#888780" marker-end="url(#ar)"/>
+<rect class="box n" x="662" y="470" width="68" height="26" rx="4"/><text class="s" x="696" y="488" text-anchor="middle">GND 2</text>
+<text class="xs" x="598" y="562" text-anchor="middle">ground rail - the two returns join ONLY here</text>
+
+<rect class="box r" x="30" y="596" width="700" height="112" rx="8"/>
+<text class="h" x="48" y="622">The fault to look for</text>
+<text class="s" x="48" y="645">The green return is reaching the RED side of the red LED instead of the ground rail, putting</text>
+<text class="s" x="48" y="663">the two LEDs in series. Green alone then needs about 4V through both, and 3.3V cannot supply it.</text>
+<text class="s" x="48" y="686">TEST: with both LEDs off, meter from the shared return wire to GND. It must read 0V. Press</text>
+<text class="s" x="48" y="704">Circle and measure again - if it rises above 0V that wire is not ground, and that is the fault.</text>
+</svg>