JT Business Card

S.I.M. (Simple Implementation Machine)

A 3D hardware-in-the-loop simulator for an RP2350 business card that was never fabricated.

S.I.M. runs the card's real Pico SDK C firmware, unmodified, against an electrical model of the circuit built straight from its KiCad files, and shows the result on a 3D card you can tilt. It answers the question a first prototype would have answered: does this firmware drive this hardware correctly?

The board: an RP2350A, a 21×21 charlieplexed matrix of 441 green 0603 LEDs on 22 GPIOs, a LIS2DH12 accelerometer, an ST25DV04K NFC tag and a coin cell. The reference firmware is a particle fluid that flows as you tilt the card.

Try it

• In a browser, nothing to install: open docs/index.html, or this repository's GitHub Pages site if it is enabled (Settings → Pages → branch main, folder /docs). Drag the card to tilt it; right-drag to orbit.
• With your own firmware: follow the quick start below.

Quick start

Requirements: Node.js 18+, Python 3, and clang + wasm-ld (LLVM 15 or newer).

npm install                       # Binaryen, three.js, esbuild

# macOS: Apple's clang has no WebAssembly target, so use Homebrew's LLVM
brew install llvm lld
export PATH="$(brew --prefix llvm)/bin:$(brew --prefix lld)/bin:$PATH"
# Ubuntu / Debian:  sudo apt install clang lld

npm run build                     # compile the reference firmware to .wasm
npm test                          # run it headless and print a report
node tools/sim.mjs firmware/fluid-demo   # compile and open the 3D view

The same firmware also builds for the real chip with the Pico SDK; see firmware/fluid-demo/CMakeLists.txt.

How it works

 .kicad_pcb ──┬─ kicad_pcb_extract.py ─▶ board.json ───────┐
              │                         led_map.h ─▶ firmware
              └─ kicad_artwork.py ────▶ artwork.json ─┐    │
                                                      │    ▼
 firmware C ──── build-firmware.mjs ──▶ firmware.wasm ─▶ engine.js ── board.js ── devices.js
                 clang → cycle counter → asyncify     │   (2 cores,    (pins,      (LIS2DH12,
                                                      │    virtual      LED solve,   ST25DV)
                                                      ▼    time, IRQs)  I2C checks)
                                          3D page (three.js)   or   run-headless.mjs

Reading the design files. A dependency-free Python S-expression parser reads the .kicad_pcb. It finds the 22 GPIO lines through the series resistors between Net-(U1-GPIOn) and /LED_ARRAY/Dk nets, finds every LED with both pads on LED nets, uses the pads' A/K pin functions to tell anode from cathode, and clusters positions into the 21×21 grid. A second script extracts the visual layers: Edge.Cuts chained into the outline and cutouts, copper, mask openings, and silkscreen. Silkscreen text comes from the polygons KiCad caches for outline fonts, so it renders exactly.

Running the firmware. The firmware is compiled with clang to WebAssembly against a simulated Pico SDK: 22 headers with the real SDK's names and signatures, implemented on about 30 JavaScript imports. Calling an unsupported SDK function fails at link time with its name. A Binaryen pass adds a Cortex-M33 instruction-cost counter, so compute time is deterministic. Binaryen's asyncify pass lets the engine suspend and resume each core at any SDK call, which gives two cores with their own stacks and virtual clocks, kept within 5 µs of each other, plus timers, alarms and GPIO interrupts on core 0.

The electrical model. Every pin change re-solves the charlieplex matrix. Each driven line is a source behind the pad resistance plus the 22 Ω resistor, and each conducting LED is a 2.55 V knee plus 32 Ω. Kirchhoff's current law gives a small linear system, solved directly. Current is added over time per LED, which becomes brightness and refresh rate. The model also flags pins over their drive rating, leakage glow through pull resistors, shorts, and outputs fighting other chips.

Peripherals. I2C transactions succeed only if the bus would really work: the pins are routed, and the pull-ups (powered from GPIO29 on this board) are on. A register-level LIS2DH12 model samples gravity from the 3D card's orientation, rotated into the sensor's axes using its footprint pose in the PCB.

A longer write-up of each part is in docs/HOW-IT-WORKS.md.

What it found on rev E1

Build a simulator for your own board

Most of the code knows nothing about this card. The parts to adapt:

Keep a deliberately broken firmware next to the real one, like firmware/examples/common-mistakes. If the simulator does not catch the bugs you planted, it will not catch the ones you did not plan.

After a PCB change:

python3 tools/kicad_pcb_extract.py board/JT-Business-Card.kicad_pcb \
    -o board/board.json --header firmware/fluid-demo/led_map.h
python3 tools/kicad_artwork.py board/JT-Business-Card.kicad_pcb -o board/artwork.json
npm run build && npm run pages

Limitations

• Not an ARM emulator: firmware is recompiled, so direct register access (sio_hw->…), PIO, DMA, PWM, ADC, USB and flash writes are not simulated.
• Interrupts and core switches happen at SDK calls, so races shorter than ~5 µs are not reproduced. A busy-wait on the other core must call an SDK function such as tight_loop_contents().
• LED I-V fit, pad resistances and instruction costs are estimates; absolute currents and CPU load should be confirmed on hardware.
• The LIS2DH12 axis directions follow the datasheet's top-view figure; confirm them by holding the first board upright.
• Solder-mask colour and finish are not stored in KiCad files, so they are a viewer setting.

Project layout

License

MIT.