README.md
# Single-PCB robot vacuum — tscircuit R0
An executable native tscircuit PCB + mechanical assembly study. All PCB pads, nets and printed solids are authored in TSX using tscircuit; no external CAD application, imported enclosure mesh or image-based model was used.
**Status: engineering draft. It is not a complete working robot or a fabrication release.** The charger and regulators are reserved areas, copper routing is disabled, firmware is absent and several purchased parts are dimensional envelopes. A protected battery alone cannot run the logic rails in this revision.
## Included design
- One 160 × 130 × 1.6 mm PCB with four declared copper layers and four matching chassis mounting holes.
- ESP32-S3-WROOM-1-N16R8; four DRV8876 channels for the two wheels, roller and side brush; ICM-42688-P; LiDAR, encoder, cliff, bumper, blower and UART interfaces.
- Eight schematic sheets sharing one board and one electrical netlist.
- Fifteen separately named printed parts, approximate purchased assemblies, native board-to-chassis face mounting and three native explosion stages.
- Native Circuit JSON, PCB/schematic SVG, assembled/exploded/internal GLB scenes, PNG views and separate prototype STL files.
- Evidence-linked capability audits and small runnable reproduction cases for the platform behavior observed during this build.
The nominal cover is Ø320 mm. The bumper reaches Ø328 mm; bristles extend beyond it. The model is 110.5 mm high including the LiDAR envelope. Motors, LiDAR, battery, tyres, filter and bristles are purchased parts. “Single PCB” means one custom main PCB; purchased assemblies can contain electronics.
## Open locally
Use Node.js 22 or newer and npm. Dependencies are pinned by `package-lock.json`.
```sh
npm ci
npm run typecheck
npm run build
npm run views
npm run stl
npm run dev
```
`dev` opens tscircuit's native local viewer; use the URL printed by the command. The scripts call the CLI through Node, so Bun is not needed for these tested commands. `npm run build` saves diagnostics rather than disguising warnings as a clean production check.
For one-file use, open `robot-vacuum.circuit.tsx` in the tscircuit editor. It contains the same complete design as the three modular source files. Regenerate it after edits with `node --import tsx scripts/standalone.ts`.
## Files to inspect
| File | Purpose |
| --- | --- |
| `index.tsx` | Native assembly entry point |
| `robot-electronics.tsx` | Footprints, circuit, connector pin allocation, PCB placement and reserved areas |
| `robot-mechanical.tsx` | Printed solids, approximate purchased bodies, mounting face and explosion instructions |
| `robot-vacuum.circuit.tsx` | Self-contained TSX for the native interactive viewer |
| `docs/tscircuit-gap-register.md` | Requirement-by-requirement platform capabilities, limitations, reproduced bugs and proposed improvements |
| `docs/electrical-review.md` | Exact pin mapping, service power, component sources and unfinished electrical work |
| `docs/mechanical-capability-audit.md` | Geometry, measured model envelope, native support and unresolved fit/airflow work |
| `docs/requirements.md` | Product requirements and staged acceptance criteria |
| `docs/build-report.md` | Actual final build/export results and warnings |
| `dist/diagnostics.json` | Unfiltered native build diagnostics |
| `dist/printed-parts/manifest.json` | Per-part units, bounds, triangles, topology checks and STL coordinate transforms |
| `capability-audit/` | Minimal platform probes and their observed results |
## Native exports
The GLB files are scenes for inspection, not printing instructions. STL files are the original native tscircuit meshes with only a file-format conversion, XY centring and a shift to Z=0. They retain assembly orientation; the script does not choose optimal print orientation or add supports. Use millimetres when importing. A 320 mm shell needs a suitable printer or an engineered split; splitting and joining are not implemented.
For native STEP export:
```sh
node node_modules/tscircuit/cli.mjs export dist/circuit.json --format assembly-step --output "$PWD/dist/assembly-step.zip"
```
`assembly-step` is the assembly mode; ordinary `step` is the PCB mode. Read the build report for whether the full robot export succeeded. The CLI has no first-class per-part STL selector in the pinned version, so `scripts/export-printed-parts.ts` serializes native meshes instead. No substitute CAD geometry is generated.
## What must be completed before hardware
Complete and review the 3S charger, protection interfaces and 5 V/3.3 V regulation. Select actual motor/blower/pack/connector SKUs, then calculate fuse, wire, connector, copper and thermal requirements from measured continuous and stall currents. Route the board and review power return paths and thermal vias. Replace purchased envelopes with verified dimensions, finish suspension/retention/fasteners/filters/seals and check initial static clearances. Implement and validate the motor, cliff, bumper, watchdog and navigation firmware.
Native explosion checks cover continuous straight translations. They intentionally exclude initial overlap; the current PCB-hole reproduction also demonstrates an unsupported-geometry coverage warning. Passing the isolated mechanical probe is not proof that the assembled robot has no interference. See the gap register for the precise evidence and boundaries.
No orderable Gerbers are supplied. The present layout contains no copper traces. That is an explicit project state, not evidence that tscircuit lacks routing, planes or fabrication export support.
