README.md
# nRF9151 GPS tracker — LTE-M/NB-IoT + GNSS + Wi-Fi locating (Rev A)
A small rechargeable tracker for children (bag or pocket) or pets (collar), designed in tscircuit for JLCPCB fabrication and assembly.
| | |
| --- | --- |
| Board | 44 × 32 mm, 4 layers, 1.6 mm, double-sided assembly |
| Cellular / GNSS | Nordic nRF9151 SiP (LTE-M, NB-IoT, GPS; Cortex-M33 runs the application) |
| Indoor location | Nordic nRF7002 Wi-Fi 6 companion, SSID scanning only (nRF7000 is a drop-in alternative) |
| SIM | nano-SIM push-pull socket **and** MFF2 eSIM, selected in firmware through an NX3DV2567 switch |
| Power | 1-cell LiPo on a JST-PH 2.0 connector (pin 1 = +), USB-C charging via the nPM1300 PMIC, on-board NTC, ship mode |
| Antennas | three U.FL receptacles: LTE, GNSS (passive, or active via the DNP bias-T), Wi-Fi 2.4/5 GHz |
| UI | SOS/power button, charge + status LEDs, 5 mm find-me buzzer, LIS2DW12 motion wake |
| Debug | Tag-Connect TC2030-NL SWD pads, logs over RTT |
Read [docs/design.md](docs/design.md) first. Then:
- [docs/decisions.md](docs/decisions.md): what was agreed before layout, and why
- [docs/firmware.md](docs/firmware.md): pin map, nPM1300 and nRF7002 bring-up, SIM switching
- [research/](research/): datasheet facts behind the nRF7002 and SIM/eSIM parts
## Layout of the code
- `index.circuit.tsx` — the board: parts, nets, placement, hand-routed RF/crystal copper, pours.
- `parts/` — one typed component per IC or connector, with its verified pin table and land pattern:
- `Nrf9151`, `Npm1300`, `RfFrontEnd`, `NanoSimSocket`, `Lis2dw12`, `Connectors`: reused from the pixal-gps project.
- `Wifi`, `Sim`, `Power`, `Ui`: new for this board.
- `lib/` — footprint generators, the passives/JLC part table, geometry helpers, the layout constants (`layout.ts`) and the renderers for generated copper.
- `routing/` — generated copper:
- `index-gnd.json`: a ground stub via per ground land.
- `index-routes.json`: signal/power legs from the router.
Both are geometry only; every connection is declared in `index.circuit.tsx`.
- `scripts/`:
- `validate.ts`: netlist and datasheet assertions.
- `render.ts`, `render-sch.ts`: PNG views.
- `errors.py`, `pads.py`: readable error and pad listings.
- The routing flow: `route-all.sh` (`prepare-routing.sh`, `gen-gnd-mesh.py`, `export-router-dsn.py`, Freerouting, `import-router-session.py`, `fix-anchors.py`), `widen-power-legs.py`, and `hand-route-net.py` (`--maze` for leftovers).
- The physical checks: `check-connectivity.py`, `check-clearance.py`, `check-holes.py`, `supply-resistance.py`.
- `solve-sch-boxes.py`: sizes chip schematic boxes to pass `tsci check schematic-placement` (it re-implements the pin-padding, label-collision and box-width rules).
## Run
```sh
bun install
npx tsci build index.circuit.tsx # -> dist/index/circuit.json (no autorouter runs at build time)
bun scripts/validate.ts --routed # design assertions + copper coverage
bun scripts/render.ts # dist/index/pcb-top.png, pcb-bottom.png
npx tsci dev --port 3905 # interactive viewer
```
Re-routing after a placement change (see "Routing" in docs/design.md):
```sh
bun run route:all # ground mesh, DSN, Freerouting, import, anchor fix, build, physical checks
bun run route:widen # widen the rails where clearance allows
bun run check:routed # 94 checks incl. connectivity through copper, clearance, pour shorts, drills
bun run check:sch # tsci check schematic-placement (clean)
bun run check:shorts # tsci check shorts (clean)
```
Fabrication package for JLCPCB (build, all routed checks, JLC footprint/rotation check, then `fab/`):
```sh
bun run fab # fab/*-gerbers.zip, *-bom.csv, *-cpl.csv; order settings in fab/FAB-NOTES.md
```
If the router leaves a connection open, close it against the routed board and paste the printed `<trace>` into `index.circuit.tsx`:
```sh
python3 scripts/hand-route-net.py index U3.LED1 D1.cathode --maze --width 0.1
```