Fusible

The fuse for your firmware. An electronic linter and tscircuit project manager in Rust: it reads the Circuit JSON generated by tscircuit, checks the electrical and physical rules of the board, and when a rule fails, the fuse blows: the process exits with an error and firmware code generation never happens.

Fusible unifies hardware and firmware into a single monorepo contract using fusible.yml, wrapping development servers, dark-theme web previewers, artifact exports, and firmware codegen.

Project status

Phase	Scope	Status
1 (MVP)	CLI, Circuit JSON parser, rules engine, diagnostics	shipped
1.1	Project manifest (fusible.yml), toolchain detection, package manager	shipped
2	Silicon pin-muxing (src/silicon/) for STM32, RP2040, ESP32-S3	shipped
2	Firmware codegen (src/codegen/pins.rs) for Embassy / Cortex-M	shipped
2.1	Pure-Rust RS-274X Extended Gerber & Excellon drill generator	shipped
2.2	Pure-Rust vector documentation exporter (PCB & schematic SVGs)	shipped
2.3	Native Fusible Studio dev server with dark theme and live SSE reload	shipped
2.4	Deterministic autorouter and bidirectional KiCad syncer	shipped
2.5	Fuse-gated 3D enclosure generator on OpenCascade	shipped
2.6	Multi-board projects: named boards, firmware, and bodies	shipped

Prerequisites

For pure Circuit JSON projects, Gerber exports, SVG rendering, and linter checks, Fusible runs with zero external dependencies.

To compile React .tsx circuits or export 3D STEP models, install tscircuit globally or in your workspace:

# Using bun:
bun add -g tscircuit

# Or using npm:
npm install -g tscircuit

Inspect toolchain health anytime with fusible doctor (or run fusible doctor --install to provision it).

Installation

cargo install fusible

Quick start (monorepo)

Initialize a new hardware + firmware project:

fusible init --name sensor-node

This creates a minimal fusible.yml:

name: sensor-node

boards:
  main:
    entry: hardware/index.tsx
    out_dir: dist
    port: 3020
    mcu: stm32g431

firmware:
  app:
    board: main
    path: firmware
    framework: embassy
    pins_rs: firmware/src/pins.rs
    build_cmd: cargo build

One project, three worlds

A Fusible project links circuit boards, firmware, and physical bodies. Each section holds named entries, and names are unique across the three, so any command takes one as its target:

name: rover

boards:
  main:   { entry: boards/main/index.tsx, mcu: esp32-s3 }
  sensor: { entry: boards/sensor/index.tsx, mcu: rp2040 }

firmware:
  main-fw:   { board: main, path: firmware/main, pins_rs: firmware/main/src/pins.rs }
  sensor-fw: { board: sensor, path: firmware/sensor, pins_rs: firmware/sensor/src/pins.rs }

bodies:
  case:  { source: bodies/case.step }                        # drawn in FreeCAD, Fusion, Onshape...
  knob:  { source: bodies/knob.step, build: python bodies/knob.py }   # code-CAD
  lid:   { generate: enclosure, around: sensor }             # Fusible owns and regenerates it

• fusible check checks every board and reports all violations together. fusible check sensor checks one.
• fusible build sensor-fw checks the sensor board, writes its pin bindings, then builds that firmware.
• fusible export main --preset fab writes into dist/main/fab/. With several boards, export and dev need a board name.
• A firmware or generated body must name its board when the project has more than one.
• The single-board form (hardware:, mcu: { chip }, one firmware:, mechanical:) still loads. It becomes a board named main, a firmware named firmware, and a generated body named after the project, which keeps writing dist/mechanical/<project>.<format>.

Commands

1. Electrical linter (check)

fusible check                     # uses fusible.yml entry
fusible check hardware/index.tsx  # compiles .tsx on the fly and lints
fusible --input circuit.json      # direct Circuit JSON input
fusible check --mcu stm32g431     # validates alternate functions against silicon

Compiling .tsx through tscircuit stops after 120 seconds. Set FUSIBLE_BUILD_TIMEOUT_SECS to change the limit for boards that take longer to route.

Clean circuit (exit code 0):

Circuit validated (fuse intact)

Rule violated (exit code 1):

the fuse blew: 1 electrical violation(s)
[unconnected_net] net "I2C_SDA" has only 1 connection(s) (minimum 2): it is floating
help: every net must connect at least two pads/ports: complete the routing in tscircuit

2. Fusible Studio dev server (dev / view / webview)

Starts the native dark-theme web previewer powered by an embedded Rust HTTP server and live-reload event streamer:

fusible dev                       # launches native Fusible Studio on port 3020
fusible view --port 3030          # custom port
fusible dev --legacy              # fallback to legacy tsci dev server

Features:

• Instant startup with zero Node runtime required for Circuit JSON.
• Live-reload streaming via Server-Sent Events (SSE) with 150ms debounced filesystem watching.
• Vitrine brutalist dark UI palette (#000000, #131313, #353535, #86A881, #A8B365) and embedded Undefined monospace typography.
• Interactive pan and zoom vector canvas for multi-layer PCB layout (01 // PCB LAYOUT) and schematic diagrams (02 // SCHEMATIC).
• Interactive Three.js 3D board viewer (03 // 3D VIEW) rendering substrate, ENIG gold pads, copper vias, traces, and components with OrbitControls and view presets.
• BODIES tab showing the generated base and lid, with lid and explode toggles. The 3D view has an ENCLOSURE toggle that draws the shell translucent around the board. The studio builds the model on demand from the first generated body in fusible.yml and rebuilds it when the circuit changes. Needs bun.
• Real-time fuse status badge (glowing green when intact, pulsing red on blown fuse).
• Diagnostics inspector showing rule violations, severity, and remediation advice.
• PCB layer visibility toggles (top copper, bottom copper, ENIG pads, silkscreen).

3. Autorouter (route)

Multi-layer A* autorouter on pure Rust spatial R-trees (rstar). Nets route one at a time in a fixed order, and each finished trace becomes an obstacle for the next, so routed nets cannot short:

fusible route                             # routes entry circuit and writes dist/circuit.routed.json
fusible route --dry-run                   # verifies all nets can be routed without writing files
fusible route -o dist/routed.json         # custom destination
fusible route --clearance 0.2 --layers 2  # custom clearance and layer count

When routing congestion prevents a trace from completing, the fuse blows (exit code 1) and lists unrouted nets to protect physical fabrication.

4. Bidirectional KiCad syncer (diff and sync)

Bi-directional layout reconciliation between graphical CAD tools (KiCad PCB) and declarative code (tscircuit):

# Compare component placement and report layout drift:
fusible diff path/to/board.kicad_pcb

# Synchronize physical moves and rotations back into manual-edits.json:
fusible sync path/to/board.kicad_pcb --write

# Dry run sync without modifying disk:
fusible sync path/to/board.kicad_pcb --dry-run

5. Build (build)

Evaluates the boards, lints electrical rules, generates typed firmware pin bindings (pins.rs), and compiles firmware only if every board keeps the fuse intact:

fusible build             # every board, then every firmware
fusible build main-fw     # one firmware and the board it runs on

6. Fuse-gated deliverables (export)

Exports fabrication-ready Gerbers, KiCad projects, SVGs, 3D models (STEP/GLB), or documentation. All exports are fuse-gated: electrical rules are verified first. If a rule fails, the fuse blows and no artifacts are produced.

# Presets:
fusible export --preset fab       # RS-274X Gerbers (.zip) + Circuit JSON via native Rust
fusible export --preset cad       # KiCad project (.zip) + 3D STEP (.step)
fusible export --preset docs      # Native PCB SVG + Schematic SVG (<5ms)
fusible export --preset all       # Generates all export bundles

# Specific format exports:
fusible export -f gerbers -o dist/gerbers.zip
fusible export -f pcb-svg -o dist/pcb.svg
fusible export -f step
fusible export -f kicad_zip

# Bypass verification (for debugging/drafts):
fusible export --preset fab --skip-lint

7. Physical bodies (body)

Builds the bodies of the project. A body is either authored or generated:

• Authored (source:): a file you made in any CAD tool. Fusible checks that it exists and never overwrites it. With build:, Fusible first runs that command from the manifest directory, for code-CAD tools such as build123d, CadQuery, or OpenSCAD.
• Generated (generate: enclosure): a two-part enclosure (base + lid) around the board outline in Circuit JSON. Fusible owns the file and regenerates it on every run. Generation is fuse-gated like export.

fusible body                             # every body of the manifest
fusible body case                        # one body
fusible body sensor                      # the generated bodies around one board
fusible body -f all                      # step, stl, glb, and brep into dist/bodies/
fusible body --ventilation grid          # vent holes in the lid (grid | slots)
fusible body --wall-thickness 2.5 --height 25
fusible body --no-cutouts --no-mounting

A board without any body gets a default enclosure, so fusible body works without a bodies: section. mechanical, case, and housing remain aliases of body.

Enclosure details:

• The outline comes from pcb_board (outline points, or width x height).
• Each pcb_hole gets a screw boss with a pilot hole, and the board sits on the bosses.
• Components that reach the board edge get a wall notch from the board surface up.
• CLI flags override the body settings in fusible.yml, which override defaults.
• Requires bun. The first run installs occt-wasm into ~/.cache/fusible/. IGES is not supported.
• fusible dev previews the first generated body in its BODIES tab and as a 3D overlay, without the fuse gate.

8. Hardware package management (add, install, search)

Manage tscircuit packages, community footprints, and components without touching npm or tsci directly:

# Search footprints and components in the tscircuit registry:
fusible search esp32-s3

# Add a community component or registry footprint to hardware/:
fusible add @tsci/seveibar.smd-resistor

# Install all hardware dependencies:
fusible install

9. Toolchain diagnostics (doctor)

Inspects local toolchain health (bun, node, npm, npx, tsci) and verifies tscircuit runner availability:

fusible doctor
fusible doctor --install

Exit codes

The codes are part of the contract, so CI can tell failures apart:

Code	Meaning
0	Fuse intact: circuit validated / command succeeded
1	Electrical violations: the fuse blew, generation is blocked
2	Tool or usage error (unreadable/malformed input, bad arguments)

Architecture

src/
├── main.rs                 # CLI entry point, exit code mapping
├── cli.rs                  # Clap command definitions
├── assets/                 # Embedded dark-theme web dashboard & Undefined font
├── dev/                    # Native Fusible Studio dev server (tiny_http, SSE, notify)
├── router/                 # Deterministic multi-layer autorouter (rstar, A*)
├── kicad/                  # S-expression parser & bidirectional layout drift syncer
├── commands/               # Subcommand execution pipelines (check, dev, route, diff, sync, export, build)
├── config/                 # fusible.yml manifest loader and path resolution
├── gerber/                 # Pure-Rust RS-274X Gerber and Excellon drill generator
├── svg/                    # Pure-Rust vector renderers for PCB layout and schematics
├── silicon/                # Silicon database and alternate function pin multiplexer
├── codegen/                # Typed firmware pin bindings generator (pins.rs)
├── parser/                 # Serde Circuit JSON parser and source span tracking
├── linter/                 # Fail-closed rules engine and diagnostics
├── netlist/                # Bipartite graph IR of nets, components, ports, and traces
└── tscircuit/              # Runner discovery and external process control

Development

mise install        # installs lefthook
cargo test          # test suite (85+ unit and integration tests)
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check

License

MIT