Skip to content

About

Render Fritzing breadboard diagrams to SVG/PNG without the app, via Fritzing's own SVG code; CLI and MCP server

Resources

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

fritzing-render

Renders Fritzing breadboard diagrams and schematics to SVG and PNG without the Fritzing app, using Fritzing's own SVG code and its parts libraries: sketches saved by the Fritzing app (.fzz, breadboard or schematic view), or breadboard diagrams described in JSON. Comes with a CLI and an MCP server, so an agent can search parts, read their pins, render a diagram and look at the image. A Docker image has it all, parts included, and the live demo runs it in your browser.

ESP32 air station

More in examples/: an ODROID-SHOW2 on a LiPo with a BLE Nano relay, a FeatherS2 air station with three Adafruit sensors and a BLE Nano bridge, and a smoke test. Their sketches are the .json files beside them.

Docker

docker pull ghcr.io/leonfedotov/fritzing-render

For linux/amd64 and linux/arm64, with Fritzing's core parts (obsolete ones too, for old sketches), the libraries under libraries/ (Adafruit, SparkFun, mgesteiro, DIP ICs, Elegoo, mkjanke) and the community parts listed under Licence. (Seeed's library is used by local builds but left out of the image: it states no licence.) With no arguments it runs the MCP server on stdio; render, search and part run the CLI, in /work:

docker run --rm -v "$PWD:/work" ghcr.io/leonfedotov/fritzing-render render sketch.fzz -o sketch.svg --png sketch.png
docker run --rm ghcr.io/leonfedotov/fritzing-render search arduino nano

As an MCP server for Claude Code (.mcp.json), with the project folder mounted at its own path so the tools can take the paths you use:

{
  "mcpServers": {
    "fritzing-render": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "${PWD}:${PWD}", "-w", "${PWD}", "ghcr.io/leonfedotov/fritzing-render"]
    }
  }
}

or claude mcp add fritzing-render -- docker run -i --rm -v "$PWD:$PWD" -w "$PWD" ghcr.io/leonfedotov/fritzing-render. The container runs as root; on Linux, add --user "$(id -u):$(id -g)" to keep files it saves yours.

Example

examples/blink.fzz is the classic blink circuit: an Arduino Uno driving a red LED through a 220 Ω resistor on a half breadboard. An .fzz is a zip holding the sketch's .fz XML (plus any custom parts); this one holds just blink.fz, small enough to read whole:

<?xml version="1.0" encoding="UTF-8"?>
<module fritzingVersion="1.0.8">
  <instances>
    <instance moduleIdRef="arduino_Uno_Rev3(fix)" modelIndex="1" path="arduino_Uno_Rev3(fix).fzp">
      <title>Arduino</title>
      <views><breadboardView layer="breadboardbreadboard"><geometry z="1.5" x="0" y="60"/></breadboardView></views>
    </instance>
    <instance moduleIdRef="0152b316-ca6e-11ee-a6fa-8be78db221f8BreadboardModuleID" modelIndex="2" path="Half_breadboard_v2.fzp">
      <title>Breadboard</title>
      <views><breadboardView layer="breadboardbreadboard"><geometry z="1.6" x="300" y="0"/></breadboardView></views>
    </instance>
    <instance moduleIdRef="LED-genedb611bf8177f41ac9c325217070f0c62ColorLEDModuleID" modelIndex="3" path="LED-generic-5mm_6852162_005.fzp">
      <property name="color" value="Red (633nm)"/>
      <title>LED1</title>
      <views><breadboardView layer="breadboard"><geometry z="2.5" x="424.99" y="-22.28"/></breadboardView></views>
    </instance>
    <instance moduleIdRef="ResistorModuleID" modelIndex="4" path="resistor.fzp">
      <property name="resistance" value="220Ω"/>
      <title>R1</title>
      <views><breadboardView layer="breadboard"><geometry z="2.6" x="438.34" y="58.46"/></breadboardView></views>
    </instance>
    <instance moduleIdRef="WireModuleID" modelIndex="5" path="wire.fzp">
      <title>D13</title>
      <views>
        <breadboardView layer="breadboardWire">
          <geometry z="3.5" x="125.06" y="69" x1="0" y1="0" x2="350.59" y2="3" wireFlags="64"/>
          <wireExtras mils="22.2222" color="#ffe24d" opacity="1" banded="0">
            <bezier><cp0 x="40" y="-45"/><cp1 x="300" y="-15"/></bezier>
          </wireExtras>
        </breadboardView>
      </views>
    </instance>
    <instance moduleIdRef="WireModuleID" modelIndex="6" path="wire.fzp">
      <title>GND</title>
      <views>
        <breadboardView layer="breadboardWire">
          <geometry z="3.5" x="116.06" y="69" x1="0" y1="0" x2="314.59" y2="-15" wireFlags="64"/>
          <wireExtras mils="22.2222" color="#404040" opacity="1" banded="0">
            <bezier><cp0 x="30" y="-45"/><cp1 x="260" y="-30"/></bezier>
          </wireExtras>
        </breadboardView>
      </views>
    </instance>
  </instances>
</module>

Parts are named by their Fritzing module id, placed in scene units (90 per inch), and wires run between end points, curved by Bézier control points. Render it with nothing installed but Docker:

cd examples
docker run --rm -v "$PWD:/work" ghcr.io/leonfedotov/fritzing-render render blink.fzz --png blink.png

blink.png:

The blink sketch rendered: an Arduino Uno wired to an LED and resistor on a half breadboard

In the browser

leonfedotov.github.io/fritzing-render has three pages:

  • Sketches: the examples, rendered live, and any .fzz, .fz or JSON sketch you drop on it, in both views and both themes, with SVG and PNG downloads. A JSON sketch, or an .fz saved without schematic positions, gets the laid-out schematic described below.
  • Parts: a catalogue that searches every part of every library (title, module id, family, tags, file name) and draws previews only for the results on screen. Each part has its own page with its breadboard and schematic views, its files (part file, breadboard, schematic, PCB and icon drawings) to view and download, or all of them as a .fzpz, its connectors, and its properties. Parts you drop (.fzpz, or a .fzp with its .svg drawings) are kept in your browser, and any sketch can use them.
  • Editor: a new JSON sketch, or an example opened from its card. Find parts on the left and click to add them; drag parts to move them, and drag from one pin to another to wire them. Drag a wire to bend it: each bend is a joint (its via points) that stays put when you move the parts, so only the segments to their pins follow. Double-click a wire to add a joint, a joint to remove it. You can choose wire colours, rotate, rename, label, undo, download the JSON, and render the result in either view. The sketch is kept in your browser between visits.

The renderer is compiled to WebAssembly with Qt for WebAssembly (src/wasm.cpp); the page (web/) loads a parts index of every library here (fritzing-render index, mapped to each library's GitHub repository at the commit this checkout pins) and fetches the parts a sketch names from GitHub before rendering it, so a sketch needn't bundle library parts, ours included.

Building it locally (Qt 6.11.2 for WebAssembly needs Emscripten 4.0.7):

aqt install-qt all_os wasm 6.11.2 wasm_singlethread -O ~/qt     # pip install aqtinstall
source ~/emsdk/emsdk_env.sh                                      # emsdk install/activate 4.0.7
mkdir -p build-wasm/boost-include && ln -s "$(brew --prefix)/include/boost" build-wasm/boost-include/
~/qt/6.11.2/wasm_singlethread/bin/qt-cmake -S . -B build-wasm -DQT_HOST_PATH=$(brew --prefix qt) \
  -DFR_BOOST_INCLUDE=$PWD/build-wasm/boost-include
cmake --build build-wasm
scripts/build-site.py && (cd site && python3 -m http.server)

.github/workflows/pages.yml builds and publishes it on every push to main.

How it works

Fritzing exports a view in SketchWidget::renderToSVG: each part's SVG for that view is split out of its file and scaled to the export DPI, placed, and the wires are appended. This project compiles the self-contained part of that pipeline straight from a fritzing-app checkout, 14 source files:

Fritzing code Used for
SvgFileSplitter pulling a part's breadboard layer out of its SVG and normalizing it to 1000 dpi
FSvgRenderer, SvgIdLayer connector geometry: pin rectangles, terminal points, bendable legs
TextUtils, GraphicsUtils SVG cleanup (fixMuch), the document header, wire lines
the SVG path parser, ViewLayer, helpers what those include

The rest of Fritzing's rendering path lives in classes that pull in the whole application (ModelPartShared, Wire, ConnectorItem, SketchWidget), so those pieces are reimplemented in src/, following the originals:

  • fzp.cpp: reading .fzp part files
  • partlib.cpp: finding parts and their SVGs in the libraries
  • render.cpp: the compose loop, wires (Wire::makeWireSVG: a 2-unit line over a 4-unit shadow, colors from Fritzing's ratsnestcolors.xml) and unbent legs (ConnectorItem::makeLegSvg)
--view schematic --view schematic --theme modern
The schematic of Fritzing's AnalogInputPot example, in Fritzing's look The same schematic in the modern theme

The schematic view of Fritzing's own AnalogInputPot example sketch, in Fritzing's look and in the modern theme.

Fritzing sketches (.fzz, a zip of the .fz XML and any parts it bundles) are read in fzz.cpp, one view at a time: each breadboard-view part with its saved transform, LED color and bent legs; each breadboard wire, curves included, leaving out PCB and schematic traces and wires to items the view hides, as Fritzing does. The schematic view reads the parts' schematic positions, the traces (one line each, no shadow) and the part labels Fritzing shows (title and chosen properties, where it put them), and adds the dots Fritzing draws where three traces meet or two leave one pin. Net labels and power labels are drawn as Fritzing's NetLabel and SymbolPaletteItem draw them, with their text, and ground and power symbols come from Fritzing's own resources.

A JSON sketch has breadboard positions only, so its schematic is laid out for it (schematic.cpp): each part's schematic symbol in rows, in the sketch's order, on the 0.1 in grid, and every wired pin given a net label, so pins on one net carry one name. Nothing is routed. Nets follow the wires and the buses inside parts (a breadboard's strips, a board's GND pins), through parts with no schematic symbol, such as breadboards, which aren't drawn. A net is named GND if any of its pins is a ground, else by the name most of its pins share (SDA), a power pin's name (3V3, VIN), or the microcontroller's pin name (D14); an LED and its resistor's net is named after the part (led_red_anode). Labels on pins closer than 0.1 in shrink to fit.

build/fritzing-render render examples/esp32-air-station.json --view schematic --theme modern --png station-schematic.png

The ESP32 air station's schematic, laid out from its JSON sketch

--theme modern restyles a schematic while keeping Fritzing's symbols: component bodies filled and outlined heavier with rounded corners, every line at a readable weight, slate pins, Noto Sans at a larger size, traces in one blue with large junction dots, net labels as filled tags, power symbols in red, reference designators as badges, and a 0.1 in dot grid. Fritzing's own look (--theme fritzing) is the default; the breadboard view has no theme.

Parts are found by module id, in the bundled copies first, then the libraries, obsolete parts included. Generic pin headers, which Fritzing generates rather than ships, are made from its templates (generated.cpp). Notes, and parts no library has (DIP and mystery chips, stripboards), are left out with a warning.

Two deliberate differences from Fritzing's export:

  • A part whose breadboard view has a single layer is drawn whole, as the Fritzing app loads it (ItemBase::setUpImage), and so is one whose drawing has no element for its layer; Fritzing's own SVG export splits the layer out regardless, dropping whatever lies outside it (common in community parts) or the whole part.
  • Unbent legs are drawn straight; there is no way to describe bent legs yet.

The breadboard and schematic views are rendered; the PCB view is not, yet.

Build

Clone with --recurse-submodules: the parts libraries (Adafruit, SparkFun, Seeed, mgesteiro, DIP ICs, Elegoo, mkjanke, fritzing-parts-extra) are submodules under libraries/ (fetch-vendor.sh initializes them if you didn't). Needs Qt 6 (6.8 and 6.11 tested) with its private headers (for the zip reader), Boost headers, CMake, and a fritzing-app checkout next to this repo (or -DFRITZING_APP=...). Or build the image: docker build -t fritzing-render .

brew install qt boost cmake
git clone https://github.com/fritzing/fritzing-app ../fritzing-app
scripts/fetch-vendor.sh                 # svgpp, fritzing-parts, the unpacked libraries/ parts, community parts
cmake -S . -B build -DCMAKE_PREFIX_PATH=/opt/homebrew/opt/qt
cmake --build build -j
(cd build && ctest)
node --test web/test/                   # the web editor's wire geometry

CLI

build/fritzing-render search arduino nano                   # titles and the "part" ref to use
build/fritzing-render part "core/Arduino Nano3(fix).fzp"    # size and connectors
build/fritzing-render render examples/smoke.json -o out.svg --png out.png --ppi 600
build/fritzing-render render ../fritzing-app/sketches/core/Button.fzz --png button.png
build/fritzing-render render ../fritzing-app/sketches/core/Button.fzz --view schematic --png button-schematic.png

render takes a JSON sketch, an .fzz or an .fz, told apart by their contents (- reads stdin). PNGs are 300 ppi unless --ppi says otherwise.

Add --json to search and part for machine-readable output. Parts are looked up in FRITZING_PARTS (colon-separated library roots) if set, else in vendor/.

Sketch format

{
  "parts": [
    { "id": "mcu", "part": "core/Arduino Nano3(fix).fzp", "x": 0, "y": 0, "label": "Arduino Nano" },
    { "id": "r1", "part": "core/resistor.fzp", "x": 120, "y": 40, "rotate": 90 },
    { "id": "led", "part": "core/LED-generic-5mm_6852162_005.fzp", "x": 200, "y": 0, "color": "green" },
    { "id": "relay", "generic": { "title": "BLE Nano", "pins": ["TX", "GND"] }, "x": 260, "y": 0 }
  ],
  "wires": [
    { "from": "mcu.D2", "to": "r1.connector0", "color": "green", "via": [[90, 49.5]] }
  ],
  "margin": 18
}
  • Coordinates are Fritzing scene units: 90 per inch (header pins are 9 apart), y down.
  • x/y place a part's top-left corner; rotate (0, 90, 180, 270, clockwise) turns it about its centre.
  • part is a ref from search, an .fzp path, a moduleId or an exact title.
  • generic instead of part draws a labelled block with 0.1 in header pins along its bottom, for parts no library has.
  • label draws text above the part (labelBelow: true puts it under).
  • color recolors a part's color_* elements, as Fritzing does for LEDs: a Fritzing LED color ("Green (555nm)"), a word (green: Fritzing's default shade) or #rrggbb.
  • Wire ends are <part id>.<connector name or id>; via adds bend points. An end can also be a spot on a part, { "part": "show2", "at": [47.5, 72.3] } in the part's own coordinates (it moves and turns with the part, e.g. a bodge wire to a chip's pin), or a scene point [x, y].
  • A wire's color is a Fritzing wire color (blue, red, black, yellow, green, grey, white, orange, ochre, cyan, brown, purple, pink) or #rrggbb.

MCP server

mcp/ wraps the CLI as an MCP server with four tools: search_parts, describe_part, render_diagram, which renders a diagram given as parts and wires, and render_fritzing_sketch, which renders a sketch file (.fzz, .fz or JSON) by path. Both take a view (breadboard or schematic; a JSON sketch's schematic is laid out from its wiring) and, for schematics, Fritzing's look or the modern theme. Images are 300 ppi unless ppi is given. The two render tools return the PNG as an image, with any warnings, and can save the SVG and PNG.

cd mcp && pnpm install
pnpm test && pnpm typecheck

Register it with Claude Code (or use the Docker image), e.g. in a project's .mcp.json:

{
  "mcpServers": {
    "fritzing-render": {
      "type": "stdio",
      "command": "/path/to/fritzing-render/mcp/node_modules/.bin/tsx",
      "args": ["/path/to/fritzing-render/mcp/src/server.ts"]
    }
  }
}

FRITZING_RENDER_BIN overrides the CLI's location (default build/fritzing-render).

Licence

GPL-3.0-or-later, as it compiles Fritzing's GPL sources. The parts libraries are not part of this code (the Docker image does include them, with Fritzing's fonts), and they and the part drawings in rendered images, including the examples here, are under their own terms:

Parts made here

libraries/fritzing-parts-extra is the submodule fritzing-parts-extra: parts for boards no library has, drawn from their makers' published design files, with their pinouts, sources and generators. It is searched with the other libraries. So far:

  • RedBear BLE Nano v1.5 (RedBearBLENanoV1_5ModuleID), from RedBear's v1.5 gerbers and DXF

RedBear BLE Nano v1.5

  • Hardkernel ODROID-SHOW2 (HardkernelOdroidShow2ModuleID), from Hardkernel's dimensioned board render and schematic and the LCD's datasheet

ODROID-SHOW2

About

Render Fritzing breadboard diagrams to SVG/PNG without the app, via Fritzing's own SVG code; CLI and MCP server

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages