ADR-0021: Wiring at pad level: every wire from a named pad to a named pad

# ADR-0021: Wiring at pad level: every wire from a named pad to a named pad

- **Status:** accepted (2026-10-14)
- **Date:** 2026-10-14
- **Requirements touched:** the kit's buildability
- **Builds on:** ADR-0018 (every board screwed down), ADR-0020 (chassis and lid, one connector)

## Context

Rafa's words, verbatim:

> "Can we increase the fidelity of the model so that we can see where the cables are connected / soldered? and have the pins more clearly visible?"

Until now a wire ended on the face of its part's bounding box, nearest the other end. The only exception was the Radxa header, whose pin positions came from a formula. Lengths were ±10 mm, and nothing checked that a pad existed where a wire ended, or that a builder could reach it.

## Decision

1. **Every wire runs from a named pad to a named pad.**
   - `cad/board_pads.py` lists each part's pads: the silkscreen name, the position in the board's own frame, the face it is soldered from, and the source.
   - **Where the positions come from:**
     - Eagle board files: Adafruit 4755, 4090, 3421, 5830, 5189 and 4314; SparkFun 21274; the LED sequin.
     - Pololu's STEP files and dimension PDFs: U3V40F5 and 2810.
     - Radxa's DXF: the 40-pin header.
     - Makers' datasheets: the C&K and Diptronics switches, the Harwin G125.
     - Product photos only, marked unverified: the NeoPixel Mini 1612 and the 2969 strip's cut-line pads.
   - **A board's frame is computed once** (`frame()`) and written to `wires.json`. The site draws each vendor model in it, and places the pads in the same frame.
   - **Turned boards:** where the packer turns a board, it records which way (`mount.turn`).
2. **A run is what a builder lays as one.** The router finds the run's path once, as a bundle. Each wire then leaves the bundle for its own pad.
   - The site draws each wire separately, with its pads, solder fillets and plugs.
   - **Pins** names every pad in use. Hovering over a wire names its two pads.
3. **The pad-level model changed the wiring.** Each change below was found by the model or its new checks:

   | Before | After | Why |
   |---|---|---|
   | STEMMA QT cable's GND pin in Radxa pin 6 | pin 9 | pin 6 also takes the 26 AWG ground from the ideal diode; one hole takes one pin |
   | mic switch fed from Radxa pin 1 | pin 17 (the other 3V3 pin) | pin 1 is the STEMMA QT cable's 3V3 pin |
   | no ground to the lid's parts drawn | Radxa pin 39 → contact 1 → a chain, pad to pad: tag → icon LED (its gnd and − pads are one net) → tail mic → head mic → eye light → eye switch | the mics, the icon LED, the sequin and the eye switch had no ground wire in the model |
   | I²S as one wire to pins 12 and 35 | BCLK, LRCL and DOUT each wired (DOUT to pin 38, 100 kΩ to pin 39) | DOUT was missing |
   | motor: one wire | pin 18 (470 Ω) to Q1's base, pin 20 to its emitter, M1 + from the 2810's second VOUT pin | the transistor's emitter and the motor's + had no wire |
   | charger "Load Out" socket → 2810 | the charger header's OUT and GND pads | the socket opens toward the head and the 2810 is at the tail: a 210 mm detour |
   | boost EN wired to VIN | EN left open | Pololu pulls EN up to VIN (30 kΩ) |
   | icon LED's 5 V from the boost's VOUT | from the strip's +V pad (after F1), through D4 | the U3V40F5 has one VOUT pin, and it already takes the diode and the ring |
   | clock → NFC tag: a 200 mm STEMMA QT cable, cut and spliced to the pigtails | the pigtails solder straight from the clock's header (VIN, SDA, SCL) to the tag's (3V3, SDA, SCL) | one joint per wire instead of two |
   | secure element → clock: 100 mm cable (4210) | 200 mm cable (4401), its spare folded | pad to pad it needs ≈ 115 mm |
   | the lid's shared lines spliced at the connector | pad to pad, one pigtail per contact | a contact has one pigtail; a three-way splice was the only alternative |

4. **The lid connector's pin map** is in `wiring.md`. Contacts 1–6 on one row, 7–12 on the other, 1 opposite 7 (Harwin C125 spec, Appendix 1). Harwin's pigtails are all white ("05 = WHITE"), so the builder flags each lead with its number before cutting.
5. **No strap on a solder joint.**
   - **The ideal diode:** its strap ran over the header (GND, Vout). It now crosses the board's other half (`STRAP_LINE`, board y 7.4 mm), and the packer may turn the board any way round to fit that.
   - **The tap-icon LED:** its pads are on the face its strap presses. Its wires are tacked flat across the back, and its strap stands 1.8 mm off on two foam pads (`STRAP_GAP_OF`).
6. **A STEMMA QT plug needs 4.5 mm clear in front of its socket.** The clock's cable takes whichever socket is clear: one faced a strap screw of the lid connector.

## Checks

New in `buildability.py`:
- **Boards drawn on their own holes:** the frame puts each vendor model's mounting holes on the packer's bosses, within 0.5 mm.
- **Every wire ends on a pad of its part.**
- **Every soldered pad can be reached:** nothing occupies the first 2–4.5 mm off a pad in use.
- **Wires fit their pad holes:** bare cores fill at most half of a Ø1.0 mm plated hole.

"Every bought cable is long enough" and "The lid opens like a book" now read the runs, pad to pad. The second also holds every pigtail to Harwin's 150 mm.

## Not verified

- The NeoPixel Mini's back pads (from photos: 2 columns 4.0 mm apart, rows 2.0 mm).
- Which of the 2969's three cut-line pads is +5V, DIN or GND.
- The depth of the C&K switch's pins in its body.
- Where the cell's lead and thermistor leave the cell.
- How the 5830's VIN 2 and On pins should be tied: wiring.md still says "as Adafruit's guide says".

The model labels each of these as unverified, and the builder checks them against the board in hand.

## Amended: the open lid routed, and slack to work with

Rafa's words, verbatim:

> "For the cables that branch over in the "open" state, can you make sure they don't go "through" any of the components? I think the blue wires for example are going through the real-time clock component"

> "And for the wires that go from component to component can you make them longer / looser so the user building the kit has more wiggle room to solder / connect them?"

- **The open lid is routed, not drawn.**
  - **Before:** the Open view drew each run to the lid as an arc from its chassis end to its turned lid end, through whatever was in the way. The cut came from that straight line + 15 %.
  - **Now:** the router builds the free space with the lid turned 180° about its +Y edge: both shells' walls, the chassis's parts where they are, and the lid's parts turned with it. It routes each run out of the chassis, over the hinge edge just above the rim, and into the lid.
  - **Same length:** each wire is drawn at the length it has closed. Its spare rises into an arch over the hinge, lifted only where it stays in free space.
  - **The check** "The lid opens like a book" now reads the routes. Every run reaches at its closed length, and passes no part other than its own end parts, whose boxes it starts inside.
- **The routes were longer than the estimate.** Two chassis runs need 160 mm: the mic rail, and the icon LED's power and data from the strip. Both start on the −Y side and cross to the hinge on +Y. The 150 mm pigtails don't reach, so the chassis half is now the socket with **450 mm** pigtails, G125-FC11205L0-0450L. On a DigiKey.de search (2026-10-14) it lists at €55.31 with 342 in stock, against €40.76 for the 150 mm. The lid half keeps its 150 mm pigtails; their longest cut is 130 mm.
- **30 mm to work with on every soldered wire.**
  - **The cut:** routed × 1.1 + 10 mm (ends and bends) + 30 mm. That is enough to hold a board about 25 mm up out of its place while soldering it.
  - **Closed:** the spare folds into a small loop where the model shows it. "Spare wire stows in the closed case" now covers every run (29 loops), not only those to the lid.
  - **Bought STEMMA QT cables** keep their own lengths.

## Amended: every wire, leg and joint inside the case; the switches turned; the case 85 mm wide

Rafa's words, verbatim:

> "Do the wires that go to the switches on the side fit alongside the battery?"

> "You'll need to test all wires and soldering to make sure they fit if this one fell through, there may be others. Potentially need to make the case slightly wider?"

> "Maybe we should spin the real-time clock 180 degrees so the cables flow easier"

When asked how to fix the switches, Rafa chose "Pins inward, case +6 mm (Recommended)".

- **A new check, "Every wire, leg and joint fits inside the case".**
  - **What it tests:** every wire, pad to pad with its loop, lies in the cavity (not in a wall) and passes through no part other than its own two. A switch's legs must fit too.
  - **What it found on its first run:** the slide switches' pins and four wires in the belly wall, and wires through three straps and the Radxa's board. The router had kept only each bundle's centre clear.
  - **The router since:**
    - a bundle keeps a clearance of its own radius;
    - a wire's way from its pad to its bundle, and a bundle's hops to its loop, go round parts;
    - straight pieces are tested against the parts' exact boxes;
    - the open-lid routes use the open pose for the same tests.
- **The slide switches.**
  - **The problem:** the right-angle C&K OS102011MA1QN1 stood on the belly flank with its 2.8 mm pins pointing down. Under the light strip the flank has 5.2–7 mm down to the floor, and switch + pins + joint needs about 9.5 mm. No position fit, at any width.
  - **The new part:** the vertical OS102011MS2QN1 from the same series. Datasheet p. I-37: 8.60 × 4.30, 4.00 high, actuator 3.5 proud, 2.0 travel, pins 2.80. It lies on its back: actuator out through the flank under the same printed cap, pins pointing in.
  - **Pins trimmed to 1.5 mm.** With 1.5 mm for the joint, the switch takes 7 mm from the wall, and the wires rise from the pin tips behind it.
  - **The width:** that needs the case 85 mm wide (was 79). The packer moved the power switch to x −23; the switches are now 35 mm apart (were 41).
  - **Mass:** about 266 g (was 259). The print bed must be at least 190 × 90 mm.
- **The clock turned 180°** on its symmetric holes, so its header faces the lid connector and the hinge. Its run to the lid went from 101 to 66 mm.
- **The NFC tag was not turned.** Turned, its antenna coil (one half of the board) would leave the tap icon by about 13 mm.
- **The tap-icon LED's strap stands 1.3 mm off** on a 1.5 mm foam pad (was 1.8 on two). At 1.8 mm its screw heads took the NFC tag's place.
- **Spare that has no room for folds** is laid as a hairpin, out and back beside its run: four runs.
- **Both halves of the lid connector have 450 mm pigtails.** With 30 mm of working slack, two lid wires need 160–170 mm. The plug is G125-MC11205L4-0450L (DigiKey.de search, 2026-10-14: €57.94, 52 in stock), and the pair is about €113.