Developer Guide

Everything you need to build, run, test, and extend MaD.

• Repository layout — what lives where
• Building the firmware — PlatformIO targets
• Running the app — Vite + WASM dev loop
• SIL testing — the firmware emulator
• Protocol & codegen — regenerate C/TS/Rust
• Reusing embsim — the SIL framework elsewhere
• embsim improvements — time, hygiene, ISS backlog
• P2 ISS on QEMU — plan, spikes and kill criteria for a TCG target
• Lossless net transport — putting every pin's signal on the net
• One drive type — scope for folding the pulse channel into the resolver
• CI/CD & releases — pipelines and tags
• Contributing — conventions and constraints
• Bug-class coverage — regression checklist for recurring failure modes
• Bulletproof test plan — matrix roadmap (M1–M12) + sprint status
• Backend certification — what covers the servo motion backend
• Protocol messages — the wire message map
• G-code — the dialect the firmware plays back

Prerequisites

Tool	Version	For
Node.js	20+	The app and its E2E suite
Rust	stable + wasm32-unknown-unknown	The protocol core, WASM, the SIL emulator
wasm-pack	latest	Building the app's WASM core
Python	3.8+	The protocol generator and the docs site
PlatformIO	6.x+	Building the firmware
KiCad	8+	Hardware (optional)

Rust, wasm-pack, and Python are only needed if you're building the app or running SIL; PlatformIO only if you're building firmware.

Initialize the submodules first

Two components are git submodules: Protocol/ProtoEmb (protocol codegen + runtime) and SIL/embsim (the emulator framework). Every fast path below needs them:

git clone --recurse-submodules https://github.com/RileyMcCarthy/MaD.git
# or, in an existing checkout:
git submodule update --init --recursive

The fast paths

Run the app against real hardwareRun the full simulation (no hardware)Build firmware for the board

cd Software/Control
npm install
npm run build:wasm        # compile the Rust protocol core → src/wasm/
npm run generate:proto    # generate the TS codec from the YAML schema
npm run app               # opens your browser; use Web Serial to connect

cd SIL
make test                 # build firmware + emulator, run cargo test

cd Firmware/MaDCore
pio run -e MaD             # build
pio run -e MaD -t upload   # flash through J1, the programming port

Deep dives

Design records kept alongside the code rather than duplicated here.

Control app — TEST_PLAN.md (Rust unit, vitest, and live-SIL E2E layers) and HARDENING.md (safety model, failure recovery, data integrity, performance).

Protocol — ProtoEmb README (generator, framing, runtime) and wire-format.md (the canonical frame + payload contract).

SIL framework — embsim README (the reusable framework and the ~10-line emulator) and CONTRACT.md (the symbols and ABI a platform crate must export).