mohan-bee/tscircuit-robot-vacuum

docs/requirements.md

# Robot vacuum R0 — requirements and design boundary

This is an executable tscircuit engineering study, not a released appliance. The design intent is a single custom main PCB with purchased motors, a protected battery pack, a LiDAR assembly and sensors connected by harnesses. Those purchased assemblies may contain their own electronics. “Single PCB” means one custom PCB, not a robot containing only one physical circuit board.

## Requested baseline

| Item | R0 target |
| --- | --- |
| Architecture | One 160 × 130 × 1.6 mm, four-layer custom main board |
| Control | ESP32-S3-WROOM-1-N16R8 (16 MB flash, 8 MB PSRAM) |
| Brushed drives | Left wheel, right wheel, main roller, side brush; four DRV8876 channels |
| Suction | Purchased balanced 3S-compatible BLDC blower with integrated driver |
| Navigation | Purchased RPLIDAR C1, ICM-42688-P IMU, wheel encoders |
| Safety inputs | Four downward cliff sensors and two bumper switches |
| Power | Protected 3S Li-ion pack, pack fuse and disconnect; onboard regulation and charge circuit required for release |
| Housing | Native tscircuit JSCAD geometry for tray, cover, brackets, wheels/hubs, bin, duct and bumper |
| Envelope | Nominal 320 mm diameter; exact height and envelope depend on chosen purchased parts |
| Later revision | Automatic docking, dock power electronics, mopping, production app, autonomous room mapping |

## Coordinate convention

All dimensions are millimetres. World +X is robot right, +Y is front, +Z is above the board. The PCB centre plane is Z=0, with surfaces at ±0.8. The floor is around Z=-52.5 for the nominal 65 mm wheel envelope. Components, mounting holes and mechanical solids share this frame. JSCAD rotations use radians; PCB/cad-model offsets use degrees where their prop specifies degrees.

## Hardware still needs measured requirements

Before release select actual motor and blower SKUs and record winding voltage, no-load current, continuous load current, locked-rotor current, torque/speed curve and dimensional drawing. Select the exact pack (capacity, discharge limit, charge current, NTC characteristic and cell protection/balance functions), filter and wheel tyres. The proposed current limit, fuse, wire gauge, connector and copper widths cannot be signed off from nominal motor voltage alone.

The blower must draw air from the bin's clean side after the replaceable filter. A removable bin needs seals and a latch; the robot must not bypass the filter or suck dust across the main board. The CAD study describes space allocation, not a verified airflow path, fan curve, acoustics model, dust ingress rating or cleaning performance claim.

## Acceptance sequence

1. Native TSX compiles, one board is emitted, native mechanical parts and explosion records are present.
2. Review PCB netlist, exact footprints and component sources; complete all reserved power circuits.
3. Route and review all four layers, ground return paths, high-current necks and thermal paths; run electrical and manufacturing checks. A layout render is not this sign-off.
4. Select mechanical SKUs; align their mounting faces and real geometry, then verify all initial clearances and removal paths. An exploded motion check is not a static interference audit.
5. Print low-cost fit coupons for screws, posts, bearing seats, bin latch and duct seals; adjust allowances for the chosen printer and material.
6. Bring up the board with a current-limited supply and motor loads disconnected. Then validate each motor and each protective stop separately.
7. Verify cliff stop behavior on representative floor colours and lighting, encoder polarity, bumper stops, watchdog, fault latching and reset state.
8. Add odometry and low-speed obstacle avoidance before attempting LiDAR mapping. Test coverage and failure recovery in a controlled area.
9. Validate pack charging/protection and enclosure temperature with the exact hardware. Do not use an unreviewed charge stage or energize an unfinished power layout.

## Functional firmware is outside this build

tscircuit describes electronics and assembly geometry. This project does not contain working ESP-IDF firmware, SLAM, motor control tuning, a Wi-Fi app or robot mission simulation. These remain product work. The capability audit distinguishes that unfinished work from reproducible platform limitations rather than calling every unimplemented feature a tscircuit defect.