Pinout
Interactive, step-by-step 3D wiring guides for ESP32 hardware builds. You type an idea. Pinout asks which catalog parts you already have (five questions or fewer). Deterministic code then picks safe GPIOs, seats parts on a full-size breadboard, routes the wires, and plays an IKEA-style assembly guide.
Owner: Focus (mtliendo).
Safety rule
Pin data is never generated by an LLM.
The model may only choose catalog part ids (esp32-s3-devkitc-1-n16r8, hc-sr501-pir, …) and a title. Every signal pin is assigned in src/lib/compose.ts from that board’s safe_gpio list, scored by capability (I2C, PWM, input, output). JTAG GPIOs 39–42 are used last. Strapping, USB, PSRAM, and input-only pins never appear in safe_gpio.
A validator (ported from specs/tools/validate.py) then checks the build before anything is rendered:
- every pin and hole exists in the spec
- no hole is used twice
- every step names a real connection
- every board GPIO on a net is in
safe_gpio
- no GPIO shares a net with 5V (
label === "5V", PIR/servo VCC, or the L+ / R+ rails)
If validation fails, the compose route repairs or rejects the build. An invalid pin is never sent to the 3D viewer.
Spec schema
Verified JSON lives in specs/ and is read-only. Swap a file in; do not reshape it to match the app.
| Path | What it is |
|---|
specs/components/<id>.json | Boards, breadboard, sensors, actuators, passives |
specs/builds/pir-servo-s3.json | Reference build (PIR + SG90 + LED) |
specs/wire-colors.json | Power and signal colours |
specs/schema.md | Field-level format |
specs/notes.md | Pin cautions and power notes |
specs/tools/validate.py | Original checker (also run from specs/) |
specs/tools/gen.py, genbuild.py | How the catalog and reference build were produced |
Coordinates are millimetres. Origin is pin 1. +X along the header, +Z up in the spec; the renderer maps spec y onto Three.js z and uses +Y up. Values written { "value": n, "approx": true } may be drawn, but they are never shown as exact dimensions.
ESP32-S3 DevKitC-1 (N16R8): never use GPIO 35/36/37 (octal PSRAM). Caution: 0, 3, 45, 46 (strapping), 19/20 (USB), 43/44 (UART0), 38 (RGB). safe_gpio is 1, 2, 4–18, 21, 39–42, 47.
The DevKit straddles the breadboard gap: J1 in column b, J3 in column i, rows 1–22. Wires leave from the one free hole per pin (a and j). Rail refs such as L+@21 snap to the nearest of 50 rail holes (groups of five).
HC-SR501 is powered from 5V; its OUT is 3.3 V and is safe on a GPIO. One SG90 may share USB 5V with a 100–470 µF capacitor across the rails. More than one servo needs its own supply.
Architecture
idea ──► /api/ask (LLM, ≤5 chip questions)
──► /api/compose (LLM picks catalog ids only)
──► composeBuild() assigns GPIOs, placements, wires, steps, sketch
──► validateBuild()
──► /guide 3D viewer
- Next.js App Router, TypeScript, Tailwind v4, pnpm. No database, no auth.
- AI SDK
generateText + Output.object (Zod) through Vercel AI Gateway. Deployments use OIDC (VERCEL_OIDC_TOKEN). Locally: vercel link and vercel env pull, or AI_GATEWAY_API_KEY.
- three.js / React Three Fiber / drei: procedural models from spec millimetres, toon materials, outlines, growing wires, easing camera, circular magnifier.
- Build-time check:
pnpm check:specs (also prebuild). A bad spec fails the Vercel build.
Key modules:
src/lib/specs/schema.ts — Zod for the real filessrc/lib/specs/validate.ts — validate.py rulessrc/lib/compose.ts — pin assignment, placement, routing, PlatformIO sketchsrc/lib/geometry.ts — holes, rail snap, camerassrc/app/api/ask/route.ts, src/app/api/compose/route.ts
The home-screen preview is the reference build pir-servo-s3. A motion-triggered servo idea composes an equivalent guide.
Local development
Requires Node 22+ and pnpm.
pnpm install
python3 specs/tools/validate.py
pnpm check:specs
pnpm dev
Open http://localhost:3000.
Optional AI locally:
vercel link --yes --scope focus-otters-projects --project pinout
vercel env pull .env.local --yes
# or copy .env.example and set AI_GATEWAY_API_KEY
Design
Workbench layout from Hassan’s IKEA-instructions demo: huge step number, frameless 3D canvas, instruction card, progress Build n/N, voice (browser speechSynthesis), circular magnifier, completion check plus copyable sketch.
Visual system follows Hallmark v2 (npx skills add nutlope/hallmark) and Gloss: cream paper, Newsreader headlines, IBM Plex Sans utility, IBM Plex Mono for pin ids and code, 1px rules. Desktop (~1280) is three panes; tablet (~820) stacks the card under the canvas.
Preview deploys
The Vercel project pinout on team focus-otters-projects is Git-linked to mtliendo/pinout. Pushes to this branch build Preview deployments only. Do not merge to main or promote to production from this MVP.
End-to-end tests
Playwright hits the Preview URL (or pnpm dev) and walks both required ideas: a motion-triggered servo, and a button + LED + OLED. It asserts ≤5 questions, a valid guide, step forward/back through completion, no page errors, and that every used ESP32-S3 GPIO is in safe_gpio.
PLAYWRIGHT_BASE_URL=https://<preview>.vercel.app \
PLAYWRIGHT_SHARE=<optional-sso-share-token> \
pnpm test:e2e
