README.md
# Muse e-paper gadget — rev D
USB-powered Muse gadget for the **Good Display GDEY075T7, 7.5-inch 800 × 480 UC8179 e-paper panel**. The editable tscircuit design is a 55 × 46 mm, two-layer board with a directly soldered **ESP32-S3-WROOM-1-N8R8 / U1 / LCSC C2913201**, onboard USB-C power and native USB programming, the panel's 24-pin FPC and external boost/charge-pump circuitry, pairing/BOOT/RESET buttons, two M2.5 mounting holes, 0.3 mm via drills with 0.5 mm copper lands and an overhanging antenna. U1 integrates Wi-Fi, BLE, 8 MB flash, 8 MB octal PSRAM, a crystal and the RF matching circuit; there is no separate DevKit to buy or socket.
Rev D compacts the same 44 imported components without scaling their footprints or changing the electrical circuit. Its 55 × 46 mm rectangular PCB has **59% less board area** than rev C's 90 × 76 mm outline with its 45 × 14 mm antenna notch (2,530 versus 6,210 mm²). Its bounding rectangle is 63% smaller. The FPC now exits the bottom edge, USB-C exits the left edge, and RESET/BOOT/PAIR sit along the bottom. The two mounting holes are 2.7 mm diameter for M2.5 hardware. Allow additional space beyond the PCB outline for the module antenna, connector bodies and attached cables. The 7.5-inch panel remains separately mounted at its original dimensions.
## Source the panel and connector
Order the **raw GDEY075T7 panel** from [Good Display's store](https://buy-lcd.com/products/gdey075t7). The [manufacturer product page](https://www.good-display.com/product/396.html) specifies 800 × 480 pixels, UC8179, SPI and a 170.2 × 111.2 × 1.25 mm outline. Stock and delivery for the raw-panel variant remain unconfirmed; no order has been placed.
J3 is **JUSHUO AFC07-S24ECA-00 / LCSC C262643**, a [24-position, 0.5 mm pitch, top-contact slide-lock connector for 0.3 mm flex](https://www.lcsc.com/product-detail/C262643.html). The imported footprint has 24 signal pads plus two isolated mounting tabs. It faces the board's bottom edge; PCB pin 1 is on the left in the top view. Insert the panel tail with exposed contacts facing the connector's upper contacts, checking its pin-1 marking. Support the glass separately and leave clearance for the latch and flex bend.
The board implements the circuit on page 40 of [Good Display's GDEY075T7 specification, manufacturer-authored copy hosted by LaskaKit](https://www.laskakit.cz/user/related_files/gdey075t7.pdf). It uses a 10 µH inductor, AO3400A N-channel MOSFET, three MBR0530 diodes, a 0.47 Ω sense resistor, a 1 MΩ gate pull-down and the reference rail capacitors. The AO3400A is an AO3400-family substitute for the reference Si1308EDL; the manufacturer's [driver-design guidance, page 10](https://p.globalsources.com/IMAGES/PDT/SPEC/358/K1186229358.pdf) permits AO3400. All display and boost capacitors are 50 V rated. BS1 is grounded for four-wire SPI, and TSCL/TSDA are unused for internal temperature sensing. A separate DESPI-C02 adapter is unnecessary for this revision.
## Real footprints and ordering
Every populated PCB component uses an exact JLCPCB/EasyEDA footprint imported with:
```sh
npx --no-install tsci import --jlcpcb --use-exact-footprint C262643
```
The same command was run for all 20 package types listed in `imports/manifest.json`. The generated pad, drill and courtyard geometry is retained. Connector primitive/insertion metadata and the MOSFET primitive/reference text were corrected locally. The FPC has explicit saved top-layer fanout geometry in `fpc-fanout.ts` to keep vias away from its fine-pitch pads.
`bom.csv` includes the purchase link and supplier ID for each of the 44 PCB components, plus the separately mounted raw display. All PCB parts are populated on the top side. The USB connector's shield tabs are through-hole; its signal contacts are SMT. Review the imported centroid rotations and connector/module placement with the assembler before ordering.
U1 is the [Espressif ESP32-S3-WROOM-1-N8R8](https://www.lcsc.com/product-detail/C2913201.html). Its [official datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3-wroom-1_wroom-1u_datasheet_en.pdf) defines the castellated 40-pin land pattern and exposed ground pad. GPIO35/36/37, used by octal PSRAM, remain unconnected externally. GPIO3/45/46 strapping pins remain open. The antenna projects past the top PCB edge; keep the display, wiring and enclosure metal away from it, with at least 15 mm clearance around the antenna inside the enclosure.
J1 is an imported **HRO TYPE-C-31-M-12 / C165948** USB-C receptacle. CC1 and CC2 each have their own 5.1 kΩ sink resistor. Both orientations' D−/D+ contacts connect to native ESP32 GPIO19/GPIO20 through 22 Ω series resistors; **ST USBLC6-2SC6 / C7519** protects the data lines and VBUS. J1 is a device/power-sink connection, with no USB PD or host support. Use a regulated 5 V USB source with enough current for RF and display refresh; a 1 A rated supply is recommended.
**AP63203WU-7 / U2 / C780769** supplies 3.3 V. Its [manufacturer reference](https://www.diodes.com/assets/Datasheets/AP63200-AP63201-AP63203-AP63205.pdf), table 2, specifies a 3.9 µH inductor, 10 µF input, two 22 µF output capacitors and a 100 nF bootstrap capacitor. L2 is **Bourns SRN6028C-3R9M / C19947652**, rated 3.3 A with 3.9 A saturation current per [Bourns](https://www.bourns.com/data/global/pdfs/SRN6028C.pdf). Feedback connects directly to 3.3 V; EN connects to 5 V. C14/C15 bypass the ESP32 supply. ESP_EN uses the recommended 10 kΩ/1 µF delay; SW2 resets EN, SW3 pulls GPIO0 low for recovery flashing, and R5 holds GPIO0 high normally.
Native USB Serial/JTAG provides flashing and logs. For first programming, hold **BOOT**, press and release **RESET**, then release **BOOT** and run the SDK flash command. Later USB Serial/JTAG downloads can enter the bootloader automatically. This design is a prototype: USB impedance and signal integrity have not been measured; the final fabricator stackup and USB routing require review before production.
## Direct FPC wiring
| Panel J3 pin | Signal | ESP32-S3 / connection |
|---:|---|---|
| 1, 4 | NC | Open |
| 2 | GDR | Q1 gate, R1 1 MΩ to ground |
| 3 | RESE | Q1 source, R2 0.47 Ω to ground |
| 5 | VSHR | C2 1 µF to ground |
| 6, 7 | TSCL, TSDA | Open; internal temperature sensor |
| 8 | BS1 | Ground; four-wire SPI |
| 9 | BUSY | GPIO13 / U1.21 |
| 10 | RES | GPIO12 / U1.20 |
| 11 | D/C | GPIO11 / U1.19 |
| 12 | CS | GPIO10 / U1.18 |
| 13 | SCL | GPIO7 / U1.7 |
| 14 | SDA | GPIO9 / U1.17 |
| 15, 16 | VDDIO, VCI | 3.3 V |
| 17 | VSS | Ground |
| 18, 19 | VDD, VPP | C6, C7, each 1 µF to ground |
| 20 | VSH1 | C9 10 µF to ground |
| 21 | VGH / PREVGH | D3 cathode, C5 10 µF to ground |
| 22 | VSL | C10 10 µF to ground |
| 23 | VGL / PREVGL | D1 anode, C11 10 µF to ground |
| 24 | VCOM | C12 1 µF to ground |
The SPI pins match `muse-gadget-sdk/esp32/main/epaper_status.c`. SW1 is a two-terminal normally-open TS-1088-AR02016: GPIO6 to ground, with a 10 kΩ pull-up and 100 nF filter. Pin 1 is the left pad and pin 2 the right pad in the imported unrotated footprint.
## Muse firmware
Reference SDK: [facebookincubator/muse-gadget-sdk](https://github.com/facebookincubator/muse-gadget-sdk), inspected commit `7e7123e2815d3e7e3c0f2ca330f576290ae6a6a9`.
`firmware/sdkconfig.muse-eink` adapts the existing reTerminal UC8179 backend to the N8R8 module and GPIO6 pairing button, with the native USB Serial/JTAG console. That backend supports the still status screen, `display.draw_url`, JPEG/RGB565 input with black-and-white dithering, and `display.show_animation` to restore the status screen. E-paper keeps its last picture when unplugged; the controller needs USB power to stay connected to Muse.
1. Install and activate **ESP-IDF v6.0.1**, as required by the SDK.
2. Clone the reference SDK and copy `firmware/sdkconfig.muse-eink` to `esp32/devices/sdkconfig.muse-eink`.
3. From its `esp32/` directory, configure the new build:
```sh
idf.py -B build-muse-eink -DIDF_TARGET=esp32s3 \
-DSDKCONFIG=build-muse-eink/sdkconfig \
-DSDKCONFIG_DEFAULTS="sdkconfig.defaults;devices/sdkconfig.muse-eink" menuconfig
```
4. Enter your own SDK token from [gadgets.muse.ai](https://gadgets.muse.ai/) into the Gadget SDK token setting. Keep it out of source control.
5. Run the same command with `build` in place of `menuconfig`. Inspect generated config for 8 MB flash, octal PSRAM, the UC8179 backend and GPIO6. Check the app fits its partition.
6. Flash using the same arguments with `-p YOUR_SERIAL_PORT flash monitor` in place of `menuconfig`.
7. In the Muse app enable Developer mode under Settings → Devices, then pair the `MuseGadget-Eink-…` device. Tap SW1 when confirmation is requested; holding it for five seconds clears setup. Upstream e-paper prompts call this the "green button"; SW1 is that button on this carrier.
This project contains the board and firmware configuration, not a prebuilt firmware binary. ESP-IDF is not installed in this workspace, so the overlay has **not been firmware-build or hardware tested**.
Published package: [muse/esp32-eink-display](https://tscircuit.com/muse/esp32-eink-display).
## Build and inspect
```sh
npm ci
npm run check
npm run dev
```
Updated to the npm `latest` releases checked on October 2, 2026: tscircuit **0.0.2742**, CLI **0.1.2235**, core **0.0.2056**, capacity autorouter **0.0.953** and runframe **0.0.2887**. The top-level tscircuit and router versions and complete dependency tree are pinned in `package-lock.json`. `index.circuit.tsx` is the main editable source; `imports/` contains the actual imported parts. `dist/index/` contains circuit JSON, PCB/schematic SVG and PNG, and the GLB model. Gerber and KiCad ZIP exports are in `dist/`. `dist/validation.json` records the automated checks, including reference boost topology, FPC mapping, independent nets, footprint provenance, ESP32 module geometry, USB-C/ESD/CC mapping, buck supply, EN/BOOT controls, compact outline, antenna overhang and zero DRC errors/warnings. No checks are disabled. `routing.ts` runs the installed built-in capacity autorouter pipeline through an explicit main phase. A final via-spacing cleanup moves a distinct-net via and its attached wire vertices when their copper clearance is too small. The resulting geometry passes the unchanged normal board DRC. All physical vias have **0.3 mm drills and 0.5 mm copper lands** (0.1 mm radial annular ring); these are checked in the generated circuit JSON and retained in fabrication exports. `scripts/render-assembly-preview.mjs` frames both the PCB and the full-size panel in the 3D thumbnail; the default CLI camera only frames PCB bounds, leaving some panel triangles behind the camera. PoppyGL 0.0.29 does not correctly clip these triangles and incorrectly draws them over the PCB. A diagnostic render with the same camera and GLB, rejecting triangles with vertices behind the camera, restores the PCB; the wider assembly camera avoids the issue. `dist/muse-eink-pnp.csv` supplies the PCB placements; assembler rotation review is still required.
These are prototype fabrication/review outputs. Firmware compilation, physical fit and hardware operation remain unverified. Before ordering, confirm panel/FPC polarity and thickness against the actual purchased parts, module seating and enclosure clearance. Bring up with a current-limited supply, inspect display rails against the panel datasheet and test refresh/BUSY operation. There is no battery, audio or touch circuitry in this revision.
## WebGPU preview compatibility fix
The guarded WebGPU compatibility patch from rev B was reviewed for runframe 0.0.2887: the shape compiler has the identical SHA-256 hash, so the same narrowly scoped patch remains in the toolchain; its rotated-slot regression fixtures are retained even though this revision replaces the sockets. Run `npm run build:site` to reapply the guarded local renderer fix, rebuild the HTML and validate its embedded geometry compiler. See [renderer-fix/notes.md](renderer-fix/notes.md) for the upstream source patch, regression tests and validation details.
The cloud build now runs `npm run build:site` through the documented `buildCommand` setting. A PoppyGL 0.0.30 override supplies the upstream near-plane clipping fix; the final assembly-preview step frames both the PCB and the full-size display and replaces the generated thumbnail before upload. This avoids relying on the cloud CLI release cadence.
