mohan-bee/tscircuit-robot-vacuum

docs/electrical-review.md

# Electrical implementation and limits

Revision R0, checked 3 November 2026. This is an unrouted engineering draft, not fabrication-ready hardware. The PCB is one 160 × 130 × 1.6 mm, four-layer board with four Ø3.2 mm mounting holes at (±72, ±52) mm. Dimensions refer to tscircuit's PCB coordinates.

## What the circuit actually contains

`robot-electronics.tsx` implements an ESP32-S3-WROOM-1-N16R8, four DRV8876PWPR brushed-motor channels, an ICM-42688-P I²C IMU, local bypass capacitors, I²C and bumper pullups, four analog cliff inputs, two quadrature encoder interfaces, LiDAR UART, blower PWM/tach, UART programming/reset/boot, protected battery input, and separately supplied 3.3 V/5 V service rails.

The schematic is divided into eight native `<schematicsheet>` pages (control, four motor channels, encoders, IMU, and sensor/power interfaces). Sheets do not create new subcircuits: all named nets remain shared on the one physical PCB. The board accepts an optional native `mountedTo` reference for assembly placement.

The custom native tscircuit `<smtpad>` ESP footprint follows Espressif's official 40 perimeter-pad plus exposed-ground pattern. Nine ground islands share pin41; duplicate islands in the upstream footprint were intentionally omitted. Coordinates were transformed from KiCad's downward-positive Y to tscircuit's upward-positive Y. The project does not invoke KiCad or consume a generated KiCad board.

The native PWP0016A footprint uses 0.65 mm pitch, 1.5 × 0.45 mm lead pads at X=±2.9 mm, and a 3.3 × 3.3 mm thermal pad. The ICM land pattern is a nominal native 14-pad LGA draft and still needs a complete land/stencil review. No header is being used to impersonate an IC footprint. Each IC footprint has a native courtyard. IC 3D models are explicitly approximate native JSCAD cuboid package envelopes: ESP32 18 × 25.5 × 3.1 mm, DRV8876 4.4 × 5 × 1.2 mm, and IMU 2.5 × 3 × 0.9 mm. They are not vendor models or detailed lead/shield geometry. The ESP body offset compensates the footprint pad centroid. Test points are bare copper pads, marked do-not-place with no physical CAD model. Power, ground, and signal pin attributes are supplied for the six ICs; charge-pump nodes use named nets.

## Motor channels

| Driver | Motor | PWM GPIO | Direction GPIO |
|---|---|---:|---:|
| U2 / M1 | Left drive wheel | 6 | 7 |
| U3 / M2 | Right drive wheel | 8 | 9 |
| U4 / M3 | Main roller | 10 | 11 |
| U5 / M4 | Side brush | 14 | 15 |

Each PWP driver has its actual package pin mapping: 1 EN, 2 PH, 3 nSLEEP, 4 nFAULT, 5 VREF, 6 IPROPI, 7 IMODE, 8 OUT1, 9 PGND, 10 OUT2, 11 VM, 12 VCP, 13 CPH, 14 CPL, 15 GND, 16 PMODE, 17 exposed ground. This numbering must not be used for the different VQFN option. PMODE and IMODE are grounded. Each channel has a 22 nF charge-pump capacitor, 100 nF pump reservoir, VM bypass and bulk capacitance, and current-reference divider. The nominal design current limit is approximately 1 A, calculated from the chosen 2.49 kΩ IPROPI resistor and 10 kΩ/30.1 kΩ VREF divider. This is provisional, pending selected motor stall currents. IPROPI appears at a test pad rather than a falsely connected MCU ADC.

## Remaining GPIO assignment

| Signal | ESP GPIO | Connector / handling |
|---|---|---|
| Cliff analog 1–4 | 1, 2, 4, 5 | J_CLIFF_1–4, ADC1 inputs, 0–3.3 V only |
| I²C SDA/SCL | 12, 13 | IMU, pullups fitted |
| Left encoder A/B | 16, 17 | J_ENCODER_L, 3.3 V signalling |
| Right encoder A/B | 18, 21 | J_ENCODER_R, 3.3 V signalling |
| Left/right bumper | 19, 20 | J_BUMPER_L/R, switch to GND |
| MCU LiDAR TX/RX | 38, 39 | J_LIDAR; MCU RX receives LiDAR TX |
| Blower PWM/tach | 40, 41 | J_BLOWER; electrical interface depends on chosen blower |
| Shared motor enable | 42 | nSLEEP of four drivers, 100 kΩ pulldown |
| Combined driver fault | 47 | Wired open-drain nFAULT, 10 kΩ pullup |
| IMU interrupt | 48 | U6 INT1 |
| Programming UART TX/RX | 43, 44 | J_UART with EN/BOOT/GND/3V3 |
| Boot | 0 | Pullup, service header; ground deliberately to enter bootloader |

GPIO35/36/37 are intentionally unavailable because this module variant uses octal PSRAM. GPIO3/45/46 remain unconnected to avoid unnecessary strapping conflicts. GPIO19/20 are assigned to bumpers, so native USB is unavailable in this revision. Use UART0 programming. The IMU is set to I²C address 0x68 (AD0 grounded, CS high). Reserved pins follow the datasheet ground/no-connect allowances.

## Known electrical work still required

| Item | Status and why it remains open |
|---|---|
| BQ25798 charging | Reserved physical area only. No fake charger netlist. Requires inductor/caps, PROG selection, pack NTC network, charge-enable policy, input protection and switching-loop layout. |
| 5 V and 3.3 V generation | Not implemented. J_LOGIC_SERVICE supplies separate regulated rails for interface evaluation. A complete robot cannot run from the battery input alone. |
| Pack protection and balancing | Purchased protected/balanced 3S pack required. Charger is not a substitute for per-cell protection. Battery current rating, fuse and connector rating are unspecified. |
| Motor selection | Gear ratio, stall current, loaded RMS current, interference and braking transients unknown. Ratings and current-limit network must be recalculated. |
| Blower | Connector only, for a purchased balanced 3S blower with its own driver. DRV8876 cannot commutate a three-phase BLDC motor. PWM polarity/frequency, tach levels and surge current need a selected part. |
| Cliff sensing | Interfaces only; sensor devices, emitter drive, optical geometry and calibration are not designed. Inputs must stay within the ESP voltage range. |
| Encoder electrical levels | Assumed 3.3 V compatible. Add conditioning/level translation for different encoders. |
| LiDAR | Interface only; purchased module. Verify its supplied connector order against the exact unit before wiring. |
| RF | Antenna is placed near board edge with an explicit keepout. Vendor-recommended clearance around the antenna and nearby assembled metal still requires whole-product review. |
| Copper routing / stackup | Disabled deliberately by default. No approved high-current widths, ground planes, thermal vias, EMI routing, impedance stackup or final ERC/DRC. |
| Firmware | Not included. Motor-control timing, stuck-motor handling, fail-safe cliff response, mapping, odometry, Wi-Fi and application control are separate development. |

These are engineering tasks or unknown purchased-part specifications; they must not be reported as proof that tscircuit cannot implement them. Platform gaps should be based on actual failing probes, unavailable APIs or unsupported exports in the separate capability audit.

## Measured autorouting experiment

The final default remains `routingDisabled={true}`. A separate executable probe in `capability-audit/routing-probe.tsx` tested this exact board, with schematic rendering disabled only for the probe.

| Mode | Measured result |
|---|---|
| Routing enabled, default preflight | Render completed in 1.488 s, but routing was blocked because more than 50 traces remained. No routing solver ran. The diagnostic recommended explicit `routeRemaining={true}` or incremental routing phases. |
| Routing enabled, `routeRemaining={true}` on a React clone of the board | Native `AutoroutingPipelineSolver9_PreloadedTraceGraph` accepted 63 connections and 296 obstacles, used four layers, and ended after 19.199 s. Rendering settled after 20.335 s. Generated 213 PCB traces and 173 vias, with zero autorouting errors and zero unconnected-port errors. |

The routed probe has 1,705 wire segments: 1,150 top, 150 bottom, 260 inner1, and 145 inner2. **Every segment is 0.15 mm wide. These routes are not qualified for motor/battery current.** Output has 17 missing-manufacturer-part-number warnings for unspecified connectors/test interfaces and one long odd-angle trace styling warning. This successful run establishes four-layer routing capability for the supplied netlist; it does not validate current capacity, copper planes, thermal performance, charging, regulators, EMC, or hardware operation.

Reproduce from project root using `node --import tsx capability-audit/routing-probe.tsx` for the default policy, or `ROUTE_REMAINING=1 node --import tsx capability-audit/routing-probe.tsx` for the forced probe. The experiment was run under an external 60 s timeout. The final board source is unchanged by either experiment. Raw inputs, event logs, summaries and circuit JSON are retained alongside the probe as `routing-basic.*` and `routing-forced.*`. The native `circuit-to-svg` PCB view of this separate result is `dist/routing-experiment.svg` with a PNG preview; it does not replace the default unrouted draft. The successful run took 20.335 s and reported zero unconnected-port errors, but its uniform 0.15 mm signal routes remain unqualified for motor power.

## Primary evidence

- [Espressif module datasheet v1.8](https://www.espressif.com/sites/default/files/documentation/esp32-s3-wroom-1_wroom-1u_datasheet_en.pdf), pin table, N16R8 memory reservations and recommended PCB land.
- [Espressif maintained land-pattern source](https://github.com/espressif/kicad-libraries/blob/main/footprints/Espressif.pretty/ESP32-S3-WROOM-1.kicad_mod), used only to transcribe vendor pad coordinates into native tscircuit primitives.
- [Espressif PCB hardware guidelines](https://docs.espressif.com/projects/esp-hardware-design-guidelines/en/latest/esp32s3/pcb-layout-design.html), module antenna clearance and placement.
- [TI DRV8876 datasheet](https://www.ti.com/lit/ds/symlink/drv8876.pdf), PWP pinout, charge-pump components, PH/EN mode, current reference and PWP0016A package land pattern. Its 3.5 A figure is a peak rating; thermal capability depends on PCB copper and load.
- [TI BQ25798 datasheet, Rev. C](https://www.ti.com/lit/ds/symlink/bq25798.pdf), 1–4S charging and application network. For a future 3S implementation, 13.7 kΩ PROG chooses the 750 kHz 3S default; this resistor is not populated in this revision.
- [TDK ICM-42688-P datasheet](https://product.tdk.com/system/files/dam/doc/product/sensor/mortion-inertial/imu/data_sheet/ds-000347-icm-42688-p-v1.6.pdf), actual pin names and I²C supply/bypass network.
- [SLAMTEC C1 specifications](https://www.slamtec.com/en/c1/spec) and [official support](https://www.slamtec.com/en/support), purchased UART LiDAR.