wirestudio

Hardware design tool for ESPHome devices. A single design.json (board + components + connections) drives every artifact: solved pin assignments, electrical validation, compile-clean ESPHome YAML, an ASCII wiring diagram, a KiCad schematic and placed PCB, a JLCPCB fab bundle (BOM / CPL / Gerber / drill), and a parametric OpenSCAD enclosure. Drive it from the web UI, the built-in agent, or any MCP client.

Stock ESPHome's Device Builder covers picking a board and adding components. wirestudio works below the YAML: the component library carries electrical metadata ESPHome doesn't model (voltage rails, current draw, pull-ups, per-pin capabilities), a CSP solver assigns legal pins from it, a validator catches boot-strap / ADC2-WiFi / voltage conflicts, and the same design fans out to the physical artifacts — wiring, schematic, PCB, enclosure. The bundled boards span the ESP32 family (original, C3, S3, C6) and ESP8266; nothing is ESP32-specific — any board ESPHome supports can be added with a library file (integration spec).

Below the module level the library also carries subcircuits: a component built from discrete parts (an H-bridge, a MOSFET low-side driver, an LED indicator, a voltage divider, a level shifter) expands into real symbols and footprints on the schematic and PCB, into the BOM and CPL, and into the inventory check. Blocks declare the electrical rule they are held to, and validate runs it with the instance's params and the rails it is wired to. Components can be authored in the studio (or by the agent) and pass the same gate the bundled ones do. An inventory of what is on hand -- library modules and a drawer of discrete parts, imported from a spreadsheet -- is cross-checked against a design's BOM: shortfalls come back with same-package substitutes and their caveats, an accepted substitute changes what every fab output prints, and the report ends in a pick list by drawer location and a buy list priced on JLCPCB.

Two LoRaWAN paths share the studio. The standalone target builds and flashes RadioLib + LoRaWAN_ESP32 firmware over WebSerial. The newer external-component path emits ESPHome YAML referencing lorawan-for-esphome, so the LoRaWAN device joins the same ESPHome / fleet-for-esphome build pipeline as every other device — provisioning, key handling, and join-status polling all from the web UI. Both paths target US915 radio boards (TTGO T-Beam / LoRa32, Heltec WiFi LoRa 32 V2 / V3 / V4) and provision against ChirpStack.

One flash dialog covers six firmware frameworks over the same WebSerial + esptool-js mechanism: ESPHome (built by fleet-for-esphome or by an ESPHome dashboard, then OTA), Tasmota (official release image + template push over serial), LoRaWAN (compiled RadioLib firmware), Meshtastic (official release factory image for the radio boards, then region, preset, owner and channel pushed over the same port), CircuitPython (official release image plus a generated code.py for the CIRCUITPY drive), and MicroPython (official release image for every board's chip, plus a main.py generated from the design and pushed over the same port through the raw REPL).

WebSerial needs the board on the end of a cable. A remote workbench removes that: point the studio at a SensorsIot Embedded AI Harness — a Raspberry Pi exposing every USB-attached board as a network resource — and flashing, LoRaWAN key provisioning and join verification all run against a slot on a bench somewhere else (workbench). The MCP server carries the same reach: alongside the design tools it exposes workbench, ChirpStack and fleet-build tools, so a headless client can take a design from design.json to a joined device without dropping to HTTP (MCP).

Not affiliated with the ESPHome project. Push to fleet talks to weirded/fleet-for-esphome, the OTA-deploy companion; Push to ESPHome dashboard talks to an ESPHome Device Builder (the dashboard of ESPHome 2026.6 and later: the Home Assistant add-on or a standalone one), which dispatches the compile to its own workers.

Documentation

Detailed docs live in docs/:

• Documentation index — architecture, repo layout, per-area status.
• Roadmap to 1.0 — what 1.0 promises and what has to land.
• User guide — Web UI, inspector, header actions, HTTP API, examples.
• Deployment — self-host with Docker or Kubernetes.
• Integrations — agent, fleet handoff, enclosure search, KiCad.
• MCP server — drive the studio from Claude Code / Desktop.
• Workbench — flash and provision boards on a remote bench.
• Library reference — every board and component.
• LoRaWAN target — build + flash LoRaWAN firmware, provision against ChirpStack.

Status

v0.40.0 — on PyPI (pip install wirestudio). The studio has wide surface area (YAML, schematic, PCB + fab outputs, enclosure, subcircuits with electrical rules, inventory matching, component authoring, agent, MCP server, two ESPHome build paths, remote workbench, web UI, two LoRaWAN flash/provision paths — standalone Arduino and an external-component path that emits ESPHome YAML referencing lorawan-for-esphome) and a set of things actually verified against upstream tools. The YAML, schematic, PCB, and enclosure paths are gated in CI, and every library component and board is exercised by a bundled example that passes those gates. The unit and golden tests a row cites run on every PR too (tests). This section is honest about which is which, ordered by how much it matters that it works.

Tiers, in priority order:

The Verified tier is the bar the project is asking to be judged on. Everything else is offered with the caveat that's spelled out in the table.

See CONTRIBUTING.md for the bar a change has to clear before merging, CHANGELOG.md for per-release deltas, and docs/architecture.md for the design decisions.

Tested against ESPHome ==2026.6.5 (pinned in .github/workflows/esphome-config.yml + bumped deliberately). When that pin moves, this line moves with it. The releases around the pin that every example also validates on, and the component behind any failure elsewhere, are in docs/esphome-support.md, built from the weekly esphome-matrix sweep.

Quickstart

Docker

docker run --rm -p 8765:8765 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -v wirestudio-data:/data \
  ghcr.io/moellere/wirestudio:0.35.0

Open http://localhost:8765. The image bundles the FastAPI server + the built web UI in one process. See Deployment for image tags, env vars, and the Kubernetes manifest.

CLI

pip install wirestudio                       # from PyPI
# ...or, for a dev checkout:  pip install -e .[dev]
python -m wirestudio.generate wirestudio/examples/garage-motion.json

Prints rendered YAML and the ASCII wiring block to stdout. A design.json from an older release is migrated on load everywhere the studio reads one; python -m wirestudio.migrate --write design.json rewrites the file itself, and --check makes a gate of it.

HTTP API

python -m wirestudio.api                    # localhost:8765
python -m wirestudio.api --reload           # dev mode (auto-reload on edits)

Browse the auto-generated OpenAPI docs at http://127.0.0.1:8765/docs. The agent, fleet handoff, and MCP surfaces are each gated by an env var — see Integrations.

Web UI (dev)

# In one terminal:
python -m wirestudio.api
# In another:
cd web && npm install && npm run dev

Open http://localhost:5173; Vite proxies /api/* to the studio API. The User guide walks the panes and header actions.

Tests

python -m pytest                          # ~1220 cases
python -m ruff check .                    # lint
cd web && npx vitest run                  # vitest + jsdom
pip install 'esphome==2026.6.5'
python scripts/check_examples.py          # the YAML gate -- every example through `esphome config`

The esphome config gate is the headline test: it renders every bundled example through the studio and runs upstream ESPHome's own validator against the output. The GitHub Actions workflow runs the YAML gate + the full suite + multi-arch image build on every PR and merge to main. A nightly compile-smoke runs esphome compile against a representative example. To run the gate before every push:

pip install pre-commit
pre-commit install --hook-type pre-push

Contributing

CONTRIBUTING.md is the substantive bar — what "working" means for the artifacts the studio produces, including the esphome config gate every PR has to clear. CLAUDE.md covers the prose / commit / comment conventions (concise, no emojis, default-to-no-comments, boundary-only validation, no premature abstraction).

License

MIT. See LICENSE. Third-party data in the tree, the libraries the generated firmware names, the web bundle's packages and what the images fetch are recorded with their licences in LICENSES.md.