AnasSarkiz/muse-voice-remote

docs/3d-assembly.md

# Muse Voice Remote 3D assembly

Run `npm ci`, `npm run build`, then `npm run dev`. Open
`http://localhost:8080/assembly/` for orbit, part inspection, assembled/exploded
views, a populated-PCB view and visibility controls. All viewer code and geometry
are local; opening the HTML requires an HTTP server for ES modules and model loads.
Downloadable native exports are in `dist/assembly/`:

- `MuseVoiceRemote-assembly.glb`: populated board and labelled mechanical envelopes.
- `MuseVoiceRemote-populated-pcb.glb`: the populated board alone.
- `assembly.circuit.json`: native tscircuit interchange, retaining original supplier URLs.
- `manifest.json`: model hashes, actual supplier bounds, placement and qualification limits.

## Native tscircuit workflow

`MuseVoiceRemoteAssembly.circuit.tsx` uses `assembly.device`,
`assembly.subassembly` and `assembly.part` from `@tscircuit/core`.
The board contains the existing imported JLCPCB components. Mechanical parts have
no electronic footprints or electrical ports. Native JSCAD geometry describes only
the clearly named `ENV_` allocations; none replaces supplier component CAD.

`scripts/build-assembly.tsx` appends separately rendered, namespaced mechanical
records to the checked board JSON, preserving all its records. It uses tscircuit's
`circuit-json-to-gltf` converter and refuses missing-model box fallbacks. Both OBJ
and STEP downloads are verified against recorded SHA-256 hashes. The native
converter receives a temporary copy with embedded downloaded OBJ bytes; published
Circuit JSON retains every original OBJ/STEP URL. All 56 selected part types /155
populated instances have loaded meshes. The 112 original model files are retained
under `models/jlcpcb`; refresh them with `npm run download:assembly-models`.

The official CLI also supports the interchange workflow:

```sh
tsci export dist/assembly/assembly.circuit.json -f glb -o assembly.glb
```

Use a filename ending in `.circuit.json` for CLI JSON input. A plain `circuit.json`
can be interpreted as a source entry by this pinned CLI version. The offline npm
build uses the SHA-verified local models and does not depend on CDN availability.

## Coordinates and mechanical revision

The reference PDF is dimensional evidence, not assembly approval. Its height is
measured from the front case surface. PCB front/rear are 4.20/5.20 mm, so the PCB
centre is 4.70 mm. tscircuit uses that centre as Z=0 and the populated TOP surface
as Z=+0.50 mm. The LCD faces −Z. XY coordinates follow the PDF without mirroring.

The original PDF's ESP32 module envelope is obsolete: the board uses the actual
bare ESP32-S3R8 QFN56 CAD. With current supplier geometry, the previous battery
allocation intersected the privacy, TALK and RESET switch bounds. The revised
proposal moves the 52.5×35×5.7 mm pack from X=−2 to X=−1 mm and raises its bottom
from front-Z=8.75 to 9.25 mm. The proposed case depth increases from 16 to 17 mm.
With a 0.80 mm rear cover and the PDF's 0.57 mm swelling allocation, nominal rear
clearance is 0.68 mm. Speaker and motor allocations also rise 0.5 mm; this clears
the BOOT switch under the speaker. These are design proposals, not a qualified
battery pack, selected transducers or an engineered enclosure.

Conservative transformed supplier OBJ bounds screen all populated component
pairs, the battery, and transducer allocations. The revised scene has zero such
overlaps. This does not prove wiring access, tolerance accumulation, flex fold,
acoustic ducts, switch travel, antenna placement, or enclosure apertures/posts.
The case is shown as an outside wireframe envelope only. Exploded-view offsets
are illustrative; they never change the native assembled coordinates.

The PCB copper, imported footprints, component placement, manufacturing ZIP and
0.30 mm via drill /0.45 mm pad minima are retained. MUSE service integration and
physical prototype qualification remain outstanding.

## Official references

- [Device assembly](https://docs.tscircuit.com/elements/assembly-device)
- [Mechanical parts](https://docs.tscircuit.com/elements/assembly-part)
- [CAD models and transforms](https://docs.tscircuit.com/elements/cadmodel)
- [Subassemblies and Z datum](https://docs.tscircuit.com/elements/assembly-subassembly)
- [CLI 3D export](https://docs.tscircuit.com/command-line/tsci-export)

API behavior was checked against the official documentation and installed
`@tscircuit/core` 0.0.2130 /`circuit-json-to-gltf` 0.0.151 source.