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 files
• src/lib/specs/validate.ts — validate.py rules
• src/lib/compose.ts — pin assignment, placement, routing, PlatformIO sketch
• src/lib/geometry.ts — holes, rail snap, cameras
• src/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