boardsmith: Text Prompt to KiCad Schematic and ESP32 Firmware

Oct 13, 2026 · 5 min read

\2

What You Will Build

boardsmith lets you skip the blank-canvas phase of circuit design entirely. You type a sentence — something like "ESP32 with BME280 temperature sensor" — and the tool produces four ready-to-use files: a wired KiCad schematic with correct nets, a bill of materials with manufacturer part numbers, Arduino or ESP-IDF firmware with pin definitions and init sequences, and JLCPCB-compatible Gerber files you can upload directly to order PCBs.

The key distinction from AI-assisted copy-paste tools is that boardsmith computes values. Pull-up resistors are sized from datasheet specs. Decoupling capacitors are placed where the pipeline determines they are needed. I2C addresses are resolved from the verified knowledge base. The output is not a starting point you patch — it is a schematic you open in KiCad and review before sending to fab.

This is useful for makers who know what circuit they want but do not want to spend two hours on the mechanical work of placing and wiring standard peripheral circuits from scratch.

What You Need

Software prerequisites

• Python 3.10 or later (Mac, Windows, or Linux)
• KiCad — to open and inspect the generated schematic
• An Anthropic or OpenAI API key if you want the LLM-guided flow; not required for offline use

Hardware

boardsmith targets three microcontroller families. ESP32 support is marked stable with ESP-IDF and Arduino and more than 50 compatible components. RP2040 (Raspberry Pi Pico) is also stable with Pico SDK and I2C/SPI peripherals. STM32 support is in beta with STM32 HAL and a subset of peripherals.

The component knowledge base covers 212 verified parts including sensors, displays, communications modules, MCUs, memory, and power components. Each entry carries electrical ratings, timing constraints, I2C addresses, and init sequences drawn from datasheets. You can browse the full list with boardsmith list-components or look up a specific part with boardsmith research BME280.

Install

For the full LLM-assisted flow:

pip install boardsmith[llm]
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY

For offline use with no API key:

pip install boardsmith

Typical use cases

How It Works

boardsmith treats circuit design like a compiler treats source code. Your text prompt is the source; the schematic is the compiled artifact. Between them sits a 9-stage synthesis pipeline that runs 11 constraint checks: voltage compatibility, I2C address conflicts, pin assignment, power budget, timing, decoupling, pull-up values, bus width, clock domains, current limits, and ERC (Electrical Rules Check) validation.

The internal data structure is called HIR — Hardware Intermediate Representation. It is a typed schema that flows through every stage of the pipeline and acts as the contract between the synthesis logic and the firmware generator. Every component, net, and constraint is expressed in HIR before anything is written to disk.

When you run with an API key, the agent asks one clarifying question (typically about the power source), then iterates, improving the design until it passes all constraint checks or until the confidence threshold is met. With --no-llm, the full pipeline runs deterministically — same input, same output, every time, no network required.

Version 0.2 adds three agentic features on top of the base pipeline. ERCAgent reads real KiCad ERC output and applies surgical patches — up to five iterations with stall detection — to automatically repair rule violations after generation. boardsmith modify lets you patch an existing schematic in plain English without rerunning the full pipeline, and creates a timestamped backup before writing. boardsmith verify runs six rule-based tools plus an LLM fix loop to check that a schematic matches the design intent recorded in the HIR.

Build and Run

Offline quick start (no API key)

pip install boardsmith
boardsmith build -p "ESP32 with BME280 temperature sensor" --no-llm

Output lands in ./boardsmith-output/. Open schematic.kicad_sch in KiCad, review bom.json for parts, and find generated firmware in firmware/main.cpp and hardware.h.

With LLM guidance

pip install boardsmith[llm]
export ANTHROPIC_API_KEY=sk-ant-...
boardsmith build -p "ESP32 with BME280 temperature sensor"

The agent asks about your power source, then iterates until the design passes constraint checks.

More example builds

# Weather station with OLED
boardsmith build -p "ESP32 with BME280 and SSD1306 OLED display" --no-llm

# CO2 monitor with TFT display targeting RP2040
boardsmith build -p "RP2040 CO2 monitor with SCD41 sensor and ST7789 TFT" \
  --target rp2040 --quality high

# LoRa remote sensor node
boardsmith build -p "ESP32 with SX1276 LoRa and BME280 for remote weather" --no-llm

Patching an existing schematic

boardsmith modify existing.kicad_sch "add battery management with TP4056"

boardsmith displays the modification plan and asks for confirmation before writing. Pass --yes to skip the prompt. A .bak backup is created automatically.

Verifying design intent

boardsmith verify path/to/design.kicad_sch --hir path/to/design.hir.json

This requires pip install boardsmith[llm] and an API key; the six rule-based checks are free but the LLM fix loop requires a key.

Controlling ERC iterations

boardsmith build -p "ESP32 with BME280" --max-erc-iterations 3

Extending boardsmith and Known Limits

Adding components

The fastest way to make boardsmith more useful is to add a part to the knowledge base. Each component is a Python TypedDict with electrical specs sourced from the datasheet. The README estimates this takes about 20 minutes per part. After adding your component to the appropriate file in shared/knowledge/seed/, smoke-test it:

boardsmith build -p "ESP32 with <your-component>" --no-llm --no-pcb
pytest

Then open a pull request. Every new part is immediately available to all users.

Project ideas to try

• Swap BME280 for SCD41 to build a CO2 monitor without writing any schematic by hand
• Use boardsmith modify to bolt battery management onto a USB-only design after the fact
• Generate the schematic offline, then enable LLM mode to let ERCAgent tighten up any rule violations before sending to fab
• Use boardsmith verify as a sanity check before ordering — it catches missing decoupling, unconnected boot pins, and BOM mismatches

Limitations to know

• STM32 support is beta; expect a narrower peripheral selection than ESP32 or RP2040
• boardsmith modify does not update the HIR; run boardsmith build --from-schematic to re-sync if you plan to use boardsmith verify afterward
• The boardsmith verify command has no --no-llm fallback; the rule-based checks run free, but LLM-guided fixes require an API key
• The ERCAgent caps at five repair iterations; remaining violations are reported in plain English rather than silently ignored, so you know exactly what needs manual attention
• The project has no stable release yet — the latest push and creation date are both March 2026, so treat this as early-access software and pin your install if reproducibility matters

Facts in this article come from the project's public README and GitHub metadata at the time of writing. Images belong to their respective owners and link back to the original source.