README.md
# FACET Four
A small desktop USB macro controller for shortcuts, media controls, video-editing commands, and volume adjustment. Four angled tactile keys, four blue indicators, a push encoder, and a 128 × 32 OLED fit in an 85 × 69 mm enclosure.
This is a hardware prototype. USB HID behavior, switch debouncing, encoder decoding, LED control, and the illustrated OLED display require firmware; firmware is not included.
## Open and run
```sh
bun install
bun run typecheck
bun run build
bun run validate
bun run preview
bun run assembly:render
bun run dev
```
- `assembly.circuit.tsx`: assembled product (default view).
- `exploded.circuit.tsx`: separated case, controls, display, and PCB.
- `index.circuit.tsx`: routed 80 × 64 × 1.6 mm four-layer carrier and three schematic sheets.
- `imports/`: local tscircuit components; no registry imports needed at runtime.
- `mechanics.tsx`: native tscircuit/JSCAD enclosure and assembly geometry.
- `BOM.csv`: PCB and mechanical parts.
Local installs pin tscircuit 0.0.3012. Hosted builds use the supported `alwaysUseLatestTscircuitOnCloud` setting to reuse the cloud runtime instead of reinstalling tscircuit. The project uses tscircuit-compatible source, footprints, routing, Circuit JSON, SVG, and GLB throughout. Supplier OBJ models are downloaded for the switches, encoder, and LEDs when rendering 3D.
## Power and connections
Plug a USB-C data cable into the RP2040-Zero module through the front opening. Its onboard USB controller connects directly to the host; its onboard regulator supplies the carrier's 3.3 V rail. There is no battery and no charging circuit. The exposed module 5 V pad is intentionally unused; do not connect a second supply to it while USB is attached.
The carrier uses the module's castellated mounting footprint, including the supplier footprint's clearance cutout. U1 is on the underside, rotated 180 degrees. The base has a service opening for the module's BOOT/RESET controls. Native USB boot loading uses those onboard controls; follow the Waveshare documentation.
OLED solder pads, left to right on the top PCB view:
| Pad | Signal | Connection |
|---|---|---|
| TP1 | V3V3 | OLED VCC, 3.3 V |
| TP2 | GND | OLED GND |
| TP3 | SDA | OLED DIN/SDA |
| TP4 | SCL | OLED CLK/SCL |
Use a Waveshare **0.91inch OLED Module**, SSD1306, 128 × 32, configured for I²C. Match signal names on the module; the harness is not specified as a straight-through connector. The display is an off-board assembly part with a four-wire solder harness, not an unrouted IC on the PCB. Display supports need adhesive retention and a physical fit check.
## Pin map
| Function | RP2040 GPIO | U1 footprint pin | Notes |
|---|---|---|---|
| OLED SDA | GP0 | 1 | I²C0; 4.7 kΩ pull-up |
| OLED SCL | GP1 | 2 | I²C0; 4.7 kΩ pull-up |
| Key 1–4 | GP2–GP5 | 3–6 | Active low; 10 kΩ pull-ups |
| Encoder A/B | GP6/GP7 | 7/8 | Common to ground; 10 kΩ pull-ups |
| Encoder push | GP8 | 9 | Active low; 10 kΩ pull-up |
| Blue LED 1–4 | GP9–GP12 | 10–13 | Active high through individual 1 kΩ resistors |
| Peripheral supply | 3V3 | 21 | Module regulator output |
| Ground | GND | 22 | Common return |
Unused module lands are intentionally unconnected. The imported footprint leaves auxiliary lands 24–33 unnamed, so the design uses only documented GPIO/power lands 1–23. The module already includes its MCU, flash, regulator, clock, USB connector, and boot/reset circuitry.
## Mechanical construction
The base and lid use four M2 mounting locations. Keycaps match the PCB's 15°, −15°, 45°, and −45° switch rotations. The Bourns encoder is rotated 45° and takes a printed 6 mm shaft knob. The four light pipes align with the actual LED locations. A small blue tscircuit wordmark is included on the faceplate.
The RP2040-Zero import has no supplier 3D model. The assembly explicitly uses a dimensional module-board and USB-shell representation, not a detailed manufacturer model. The OLED likewise uses a documented dimensional representation. Display graphics are illustrative. Physical connector reach, key travel, knob fit, display retention, print clearances, and screw engagement must be checked on a prototype before manufacturing. The module pin geometry, imported cutout, and pick-and-place rotations also require manufacturing review.
## References
- [Waveshare RP2040-Zero documentation](https://www.waveshare.com/wiki/RP2040-Zero)
- [Waveshare 0.91inch OLED documentation](https://www.waveshare.com/wiki/0.91inch_OLED_Module)
- [RP2040-Zero, C5350143](https://jlcpcb.com/partdetail/C5350143)
- [KH-6X6X5H-STM, C2837531](https://jlcpcb.com/partdetail/C2837531)
- [Bourns PEC11R-4020F-S0024, C143788](https://jlcpcb.com/partdetail/C143788)
- [XL-1608UBC-04, C965807](https://jlcpcb.com/partdetail/C965807)
