metronome/hardware/pcb_layout_tutorial.md

# PCB Layout — what software, and how it actually works

A plain-English orientation for turning our finished schematic into a manufacturable board.
You don't need prior PCB experience to follow this. (Reminder: this is **board design** —
arranging finished chips and copper wires — *not* "chip design," which is the silicon inside
the chips. Totally different, far more approachable.)

## The software: KiCad

**Use KiCad** (free, open-source, professional-grade). It's what we've been using to verify
the design, and it's already installed in the project container (`hardware/eda/run.sh`).
There are paid alternatives (Altium ~$$$, Autodesk Fusion/EAGLE), but KiCad is free, capable,
and has the best free learning material — no reason to use anything else here.

KiCad is actually several tools in one:
- **Eeschema** — draws the *schematic* (what connects to what). *We did this in code (SKiDL),
  which generated the same thing.*
- **Pcbnew** — the *PCB layout* editor. **This is the part you'll learn next.**
- helpers for 3D view, Gerber export, etc.

## The core paradigm (read this part twice)

A circuit board is described at **two levels**, and keeping them separate is the whole idea:

1. **The schematic / netlist = the *contract*.** It says *what must be electrically
   connected* — "pin 6 of the DAC connects to the resistor R12, which connects to the op-amp."
   It says nothing about physical position. **Ours is done:** `hardware/kicad/board.net`.

2. **The PCB layout = the *physical realization*.** You decide *where* each component sits and
   *how* the copper wires (called **traces**) run to satisfy every connection the netlist
   demands — while obeying physical rules (wires can't be too thin, too close, etc.).

So the mental model is: **constraint-satisfying connect-the-dots.** The netlist hands you a
list of dots that *must* be joined; you place the parts on a rectangle and draw copper to join
exactly those dots, in the cleanest way, without breaking the rules. Nothing more, nothing less.

Why two levels? Because *what* connects (the design) and *where things go* (the craft) are
genuinely different problems. We nailed the first — rigorously, with simulations. The second
is a spatial puzzle.

## The workflow, step by step

1. **Import the netlist.** Open Pcbnew, import `board.net`. All 167 components appear as
   **footprints** (the real-world copper pads + outline for each part), piled up, joined by a
   tangle of thin lines called the **ratsnest** — each line is one connection the netlist
   requires but that isn't routed yet.

2. **Place the footprints.** Drag parts into a sensible arrangement. *This is where our
   `LAYOUT.md` rules apply* — switcher in one corner, quiet analog in another, USB by its
   connector, etc. Good placement makes routing easy; bad placement makes it impossible.

3. **Route the traces.** Draw copper to replace each ratsnest line. You work on **layers**
   (top copper, bottom copper, and inner layers on a 4-layer board); you hop between layers
   through plated holes called **vias**. As you connect dots, the ratsnest lines disappear.

4. **Pour the planes.** Fill empty areas with copper connected to **GND** (and power) — the
   "ground plane" that keeps everything quiet. (Big topic in `LAYOUT.md`.)

5. **Run DRC** (**Design Rule Check**) — the layout equivalent of the ERC we ran on the
   schematic. It flags traces too close together, too thin, unrouted connections, etc. Fix
   until clean.

6. **Export and order.** Generate **Gerber** files (the standard format every fab understands —
   one file per layer), plus a drill file, a pick-and-place file, and the BOM
   (`BOM_board.csv`). Upload to a fab like **JLCPCB** or **PCBWay**; they make and (optionally)
   assemble it.

## The vocabulary you'll meet

| Term | Plain meaning |
|---|---|
| **Footprint** | the copper pads + outline a real part solders onto |
| **Net** | one electrical connection (a wire), e.g. `+3V3`, `MIX_OUT` |
| **Ratsnest** | the thin "still-to-route" lines showing required connections |
| **Trace** | a copper wire you draw |
| **Via** | a plated hole that carries a trace between layers |
| **Plane / pour** | a large copper fill, usually ground or power |
| **Layer** | one copper sheet; our board uses 4, stacked |
| **Clearance** | the minimum gap rules between copper |
| **DRC** | Design Rule Check — automated "is this manufacturable?" |
| **Gerber** | the file format you send to the factory |

## How our files fit together
- **`board.net`** → the contract you import into Pcbnew (the dots to connect).
- **`LAYOUT.md`** → the rulebook for *how* to place and route this specific board (grounding,
  the switcher, USB pair, analog isolation).
- **`BOM_board.csv`** → the parts list for ordering/assembly.
- **`DESIGN.md`** → why the circuit is the way it is, if you want the background.

## Learning resources (do these in order)
1. **Digi-Key "Intro to KiCad" by Shawn Hymel** (YouTube) — start-to-finish, free; the layout
   parts are exactly steps 1–6 above.
2. **Phil's Lab** (YouTube) — especially relevant: he does **audio and mixed-signal** PCBs,
   grounding, and USB — our exact problem domain.
3. KiCad's official "Getting Started" docs.

## Honest expectations
The *digital* parts of this board (RP2350, flash, the ribbons) are beginner-friendly to route.
The **switching supply, the ±15 V analog section, and the USB pair are not** — they reward
experience, and mistakes there show up as noise or instability. Three realistic paths:
- **Learn on it:** route the easy parts yourself, and follow `LAYOUT.md` carefully (with me) for
  the tricky three. Best for understanding your own device.
- **Hybrid:** you place + route the digital/connectors; hand the switcher/analog/USB to a
  freelance layout person (or me, iterating).
- **Hire the layout:** `board.net` + `BOM_board.csv` + `LAYOUT.md` is a complete brief a
  contract PCB designer can execute (~$300–1500 for a board this size).

The hard intellectual work — the design — is already done and verified. Layout is craft and
care, and it's learnable.