runpatrick/sa-sim-pcb

CLAUDE.md

# SA-SIM PCB — Project Rules

You are designing **SA-SIM**: a 40mm IP68 cellular puck tracker.

Hardware stack: nRF52840 + BG95 cellular + BNO086 IMU + BQ25180 charger + BQ51013 wireless Qi RX + BQ27220 fuel gauge + TPS62840 buck + TPS7A02 LDO + USB-C + JST + eSIM + 32MHz/32kHz crystals.

**Goal: Tesla-grade, fab-ready boards.** No half-implementations, no placeholders.

---

## Workflow

1. Read `index.circuit.tsx` (or other `*.circuit.tsx` files) to understand current state.
2. When the user describes a change, edit the JSX directly. Add components, wire `<trace>`s, set positions.
3. After every meaningful edit, run `tsci dev` (already available — don't restart it if running) and tell the user to refresh `localhost:3020`.
4. Use the tscircuit skill at `.claude/skills/tscircuit/` for syntax reference. Component element docs live at `.claude/skills/tscircuit/elements/*.md`.
5. Before declaring "done": run `bun typecheck` (tsc --noEmit) and ensure no errors.

---

## Placement (40mm puck, top side)

| Designator | Part         | x (mm) | y (mm) | rot | Note                            |
|------------|--------------|--------|--------|-----|---------------------------------|
| U2         | BG95 modem   | 20.0   | 30.0   | 0   | North; antenna routing zone     |
| U8         | eSIM         | 32.0   | 28.0   | 0   | Adjacent to modem               |
| IC1        | nRF52840 MCU | 20.0   | 18.0   | 0   | Digital core                    |
| X1         | 32MHz HFXO   | 16.0   | 19.5   | 0   | West of MCU                     |
| Y1         | 32kHz LFXO   | 24.0   | 19.5   | 0   | East of MCU                     |
| U1         | BNO086 IMU   | 20.0   | 14.5   | 0   | South of MCU                    |
| IC3        | TPS62840 buck| 15.0   | 8.0    | 0   | Buck converter                  |
| L1         | 2.2uH (NR3015)| 18.5  | 8.0    | 0   | Buck inductor                   |
| U4         | TPS7A02 LDO  | 24.0   | 8.0    | 0   | LDO for analog rail             |
| U3         | BQ25180 chrg | 10.0   | 11.0   | 0   | Linear charger                  |
| U5         | BQ27220 fuel | 28.0   | 11.0   | 0   | Fuel gauge                      |
| IC2        | BQ51013 Qi   | 30.0   | 8.0    | 0   | Wireless RX                     |
| C21        | tantalum bulk| 22.0   | 10.5   | 0   | 10uF tant on VSYS               |
| J1         | USB-C        | 2.0    | 20.0   | 90  | West edge                       |
| D1         | USB ESD      | 6.0    | 20.0   | 0   |                                 |
| U6         | USB TVS      | 6.0    | 22.0   | 0   |                                 |
| J2         | JST batt     | 38.0   | 20.0   | 270 | East edge                       |
| U7         | batt TVS     | 34.0   | 20.0   | 0   |                                 |
| R8         | batt NTC     | 34.0   | 22.0   | 0   | 10k NTC, 0402                   |

Outer ground ring: 1.5mm keepout from board edge for IP68 potting.

---

## I2C addresses (per real datasheets — DO NOT GUESS)

| Part    | I2C addr | Datasheet |
|---------|----------|-----------|
| BQ25180 | 0x6A     | SLUSDP3   |
| BQ27220 | 0x55     | SLUSCY9   |
| BQ51013 | 0x6E     | SLUSC11   |
| BNO086  | 0x4A     | (ADR=GND) |

If a part is on the wrong bus or address, fail loudly. Don't paper over.

---

## Default component values

**Capacitors (by net):**
- VBAT / BAT_P: 4.7µF 0402 (Samsung CL05A475MP5NRNC, LCSC C19666)
- VSYS: 10µF 0603 (CL10A106KP8NNNC, C19702)
- 3V3: 100nF 0402 (CL05A104KO5NNNC, C1525)
- 1V8: 100nF 0402 (same)
- VBUS: 4.7µF 0402 (C19666)
- QI_VOUT/AC: 22µF 0805 (CL21A226MAQNNNE, C45783)
- BSTRP / SW_BUCK: 470nF 0402 (CL05A474KP5NNNC, C57112)
- XTAL/OSC load caps: 12pF 0402 (CL05C120JB5NNNC, C1635)
- Default decoupler: 100nF 0402

**Resistors:**
- USB-C CC1/CC2 pulldowns: 5.1k 0402 (RC0402FR-075K1L, C25771)
- I2C pullups (SDA/SCL): 4.7k 0402 (RC0402FR-074K7L, C25900)
- Default: 10k 0402 (RC0402FR-0710KL, C25804)

**Inductor (buck):** 2.2µH (Taiyo Yuden NR3015T2R2M, C97127)

Always include LCSC part numbers in component definitions (the user fabs at JLCPCB).

---

## Free GPIO candidates (nRF52840)

In priority order — pick lowest-numbered free pin first:

`P0.31, P0.30, P0.29, P0.28, P0.04, P0.03, P0.02, P0.13, P0.14, P0.15, P0.16, P0.17, P0.22, P0.23, P0.24, P0.25, P1.10, P1.11, P1.12, P1.13, P1.14, P1.15`

Reserved (do NOT auto-assign):
- P0.00 / P0.01: 32kHz LFXO
- P0.32 (XL1) / P0.33 (XL2): 32MHz HFXO (some pkgs)
- SWD pins: P0.05/P0.06 (some pkgs use dedicated SWDIO/SWDCLK)

Verify `IMU_CS`, `MODEM_TX`, etc. don't share a pin (the v1 board had IMU_CS↔MODEM_TX shorted — this is the canonical bug to never repeat).

---

## Net naming

Use ALL-CAPS underscored names: `VBAT`, `VSYS`, `_3V3`, `_1V8`, `IMU_INT`, `MODEM_PWRKEY`, `MODEM_TX`, `MODEM_RX`, `USB_DP`, `USB_DM`, `USB_CC1`, `USB_CC2`, `BAT_P`, `QI_VOUT`, `QI_AC1`, `QI_AC2`, `I2C_SDA`, `I2C_SCL`, `SWDIO`, `SWDCLK`.

---

## Hard rules

- **Power budget**: Buck must source ≥500mA into VSYS. LDO TPS7A02 → 1.8V analog only (low noise).
- **Antenna**: Keep 5mm clearance around BG95 antenna pin. No copper pour. No traces under U2's antenna footprint.
- **Crystal**: HFXO load caps within 2mm of X1; trace length <5mm; no high-speed signals crossing.
- **USB-C**: Both CC1 and CC2 need 5.1k pulldowns to GND for sink role. ESD diode on D+/D- pair.
- **JST battery**: Polarity check — if reversed, body diode of charger conducts. Add reverse-polarity FET if unsure.
- **NTC**: Battery thermistor is 10k 0402, B-constant 3380, on a dedicated pad next to JST.

---

## When you're unsure

- Ask the user before placing parts in regions that aren't in the placement table.
- Ask before changing pin assignments on the MCU.
- Don't invent LCSC part numbers — if a part isn't in this doc, search tscircuit registry first or flag it.