From 069e7ebdd5e639ea4007d5ef44daca97b6b6bd47 Mon Sep 17 00:00:00 2001 From: jessikitty Date: Fri, 25 Sep 2026 01:24:39 +1000 Subject: [PATCH] Add wiring doc with the series-LED failure mode Records the diagnosis: green only lights when red is on, because the green return reaches the red LED's anode instead of the ground rail. --- docs/WIRING.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/WIRING.md diff --git a/docs/WIRING.md b/docs/WIRING.md new file mode 100644 index 0000000..5b40c6a --- /dev/null +++ b/docs/WIRING.md @@ -0,0 +1,69 @@ +# Wiring + +![Wiring pinout](wiring.svg) + +## Board to board + +| Board A (esp32_bluepad32) | | Board B (esp32 2.0.17) | +| --- | --- | --- | +| GPIO17 TX | → | GPIO16 RX | +| GPIO16 RX | ← | GPIO17 TX | +| GND | — | GND | +| 5V | — | 5V (model setup only, see README) | + +TX goes to RX, not TX to TX. The ground is a shared voltage reference so the +two boards agree on what a logic 1 is — without it you get garbage or silence. +It is not a return path for anything else, so do not hang LED current off it. + +## LED circuits + +Both live entirely on **board B**. Each is its own complete loop: + +``` +GPIO25 ──[220Ω]──▶|── RED pair ────┐ + ├── ground rail ── board B GND +GPIO26 ──[100Ω]──▶|── GREEN pair ──┘ +``` + +The two returns meet **only at the ground rail**, and the rail goes straight to +a GND pin on board B. LED long leg (anode) faces the resistor and GPIO side. + +Resistor values are a starting point: roughly 220Ω for red, 100Ω for blue or +white. A pin is comfortable at about 12mA and hard-limited near 40mA. If a pair +draws more than ~20mA — which pre-wired "3V" LEDs sized for a coin cell often +do — drive it through a small NPN transistor or MOSFET instead of off the pin. + +## Known failure mode: LEDs wired in series + +Symptom seen on this build — green only lights when red is already on, and +green never lights alone: + +| Software state | Observed | +| --- | --- | +| red on, green off | red on ✓ | +| red off, green on | **both off** ✗ | +| red on, green on | both on ✓ | +| red off, green off | both off ✓ | + +Cause: the green return lands on the *anode* side of the red LED rather than on +the ground rail, putting the two LEDs in series. Green alone then has to push +through both — roughly 2.1V plus 1.9V — and a 3.3V pin cannot do it, so neither +lights. With GPIO25 also high, the junction is lifted and both conduct. + +Two rows of that table are impossible from a software fault, which is what +identifies it as wiring. + +**Test:** with both LEDs off, meter from the shared return wire to a GND pin. +It must read 0V. Press Circle and measure again — if it rises above 0V, that +wire is not ground. + +**Simplest fix:** give each LED its own separate wire back to its own GND pin +on board B, with no shared return at all. Board B has several grounds, all +common internally. Slightly less tidy, and it removes the junction entirely. + +Worth checking polarity at the same time. A reversed LED simply stays dark, so +it looks like a dead circuit rather than a wiring error. + +--- + +Created by: Jess Rogerson (yelling commands at Claude.AI)