uniwire

Electrical diagrams, as code.

An open standard to describe electrical installations, and the reference Python library that validates
them, checks them against rules and draws their single-line and multi-line diagrams.

You describe the installation (sources, protective devices, cables, loads, PLCs) in a *.uniwire.json
file or in Python, and uniwire computes the drawings. No coordinates, no CAD file: a text file you can
review and diff.

Format: *.uniwire.json, format 1.0, defined by the specification
and validated by a published JSON Schema: https://uniwire.sh/schema/v1/uniwire.schema.json.
Library: pip install uniwire: Python API, code-first builder and the uniwire command line.
Documentation: https://uniwire.sh/docs/
Web viewer: https://uniwire.sh/viewer/, paste a document to validate, check and draw it in the browser.

Features

Single-line and multi-line diagrams from the same document: the multi-line view derives every
conductor (L1, L2, L3, N, PE, PEN) from the single-line data, with no extra input.
53 node types: utility grid, transformers, generators, UPS, PV, batteries, inverters; breakers,
RCDs, RCBOs, fuses, switch-disconnectors, contactors, motor starters, transfer switches, SPDs,
protection relays, instrument transformers, insulation monitors; busbars, boards, terminal blocks;
lighting, sockets, heating, motors, EV chargers, modular PLCs and more.
Tree + links: the power tree is the backbone; transfers, bus ties, infeeds, earthing, control,
interlocks, trips, measurements and data buses are links. A terminal / connectivity-node graph is
derived automatically, with CIM, IFC and IEC 61850 SCL mappings.
Closed typing and unit-suffixed fields: in_A, idn_mA, section_mm2, p_kW; unknown fields are
errors (calibre instead of in_A is caught), extensions live in ext. Templates declare a device once.
Rule profiles: core (always), nfc15100 (French dwellings), vde0100 (German installations),
iec60364 (cable current-carrying capacity), enedis (connection to the French public network), plus PLC
consistency checks.
Bill of materials: structured product references (manufacturer, part number, range, accessories)
on any node or PLC module, aggregated to CSV (uniwire bom).
Wire and cable marking: marking rules per view (manual, sequential, per potential, pattern), marks
drawn on the multi-line diagram, and CSV exports: wire list (uniwire wires), wire marker list
(uniwire markers), cable schedule (uniwire cables); uniwire marks --write freezes the marks.
Colour modes: conductors in their IEC 60445 or North-American colours, or colouring by phase,
source, status or voltage level.
Sheets: paper size, sub-tree views, automatic sheet splitting with cross-references, circuit schedule,
enclosure frames, title block, revisions and notes. SVG output is deterministic and diff-friendly;
the multi-sheet PDF has clickable links between sheets.
Drawings in English, French, German, Spanish, Portuguese, Italian, Polish, Turkish, Russian and Simplified
Chinese, selected per document with meta.lang.
LLM tooling: a reference card generated from the model (uniwire card), a text outline with
stable ids (uniwire describe), id-based edits (uniwire patch), an MCP server (uniwire-mcp, stdio)
and a hosted MCP endpoint at https://mcp.uniwire.sh/mcp, plus
llms.txt for assistants (full reference card
included). Setup for ChatGPT, Claude, Cursor and VS Code:
uniwire in your assistant; details in
LLM tools.

Gallery

_{French house, TT (NF C 15-100), single-line}	_{German house, TN-C-S, multi-line in conductor colours}
_{Office building, main LV switchboard}	_{MV/LV substation, 1000 kVA}
_{Standby generator, ATS, load shedding}	_{Motor control centre, multi-line with wire marks}

All 53 examples are in examples/ and listed in the
documentation; open any of them in the web viewer.

Install

pip install uniwire                 # validation, rules, SVG rendering, bill of materials, exports
pip install "uniwire[pdf]"          # + PDF output (reportlab)
pip install "uniwire[mcp]"          # + MCP server (uniwire-mcp)
pip install "uniwire[iec81346]"     # + optional IEC 81346-2 class table (separate CC BY-SA 4.0 data package)

Python 3.10 or later. The only required dependency is pydantic.

Quickstart

A document in JSON:

{
  "$schema": "https://uniwire.sh/schema/v1/uniwire.schema.json",
  "uniwire": "1.0.0",
  "profiles": ["nfc15100"],
  "meta": { "title": "Small house", "lang": "en" },
  "installation": { "earthing": "TT", "system": "1P+N", "un_V": 230 },
  "templates": { "C16": { "type": "breaker", "in_A": 16, "curve": "C" } },
  "sources": [
    { "type": "grid", "label": "Utility", "children": [
      { "type": "main_breaker", "ref": "-Q0", "range_A": "15-45", "in_A": 45, "idn_mA": 500, "selective": true,
        "children": [
          { "type": "rcd", "ref": "-Q1", "in_A": 40, "idn_mA": 30, "rcd_type": "AC", "children": [
            { "type": "breaker", "ref": "-Q11", "use": "C16", "cable": { "cores": "3G", "section_mm2": 1.5 },
              "children": [ { "type": "lighting", "label": "Lighting", "points": 6 } ] }
          ] },
          { "type": "rcd", "ref": "-Q2", "in_A": 40, "idn_mA": 30, "rcd_type": "A", "children": [
            { "type": "breaker", "ref": "-Q21", "in_A": 20, "curve": "C", "cable": { "cores": "3G", "section_mm2": 2.5 },
              "children": [ { "type": "socket", "label": "Sockets", "points": 8 } ] }
          ] }
      ] }
    ] }
  ]
}

The tree is the power flow (source, protective devices, loads); whatever falls outside the tree
(transfer switches, bus ties, control and data connections) goes in links.

uniwire validate house.uniwire.json                 # schema + integrity
uniwire check house.uniwire.json                    # rule profiles (exit code 1 on errors)
uniwire render house.uniwire.json                   # SVG sheets in out/house/
uniwire render house.uniwire.json -f pdf -o house.pdf
uniwire render house.uniwire.json --kind multi-line # multi-line power diagram
uniwire bom house.uniwire.json -o house.bom.csv     # bill of materials
uniwire wires house.uniwire.json                    # wire list (also: markers, cables, marks)
uniwire card                                        # reference card for assistants

The same installation in Python:

from uniwire.build import *

with Installation("Small house", earthing="TT", system="1P+N", un="230 V", profiles=["nfc15100"]) as inst:
    with Grid("Utility"), MainBreaker("-Q0", "15-45 A", idn="500 mA", selective=True):
        with RCD("-Q1", "40 A", "30 mA", type="AC"):
            Breaker("-Q11", "C16", cable="3G1,5") >> Lighting("Lighting", points=6)
        with RCD("-Q2", "40 A", "30 mA", type="A"):
            Breaker("-Q21", "C20", cable="3G2,5 18 m") >> Socket("Sockets", points=8)

for finding in inst.check():
    print(finding)
inst.save("house.uniwire.json")
inst.render("house.pdf")

with makes an element the parent of everything created inside it, >> chains elements, ratings and
cables are written the way they appear on drawings ("C16", "3G2,5 18 m"). See the
code-first API and the Python API and CLI.

Roadmap

Terminals, terminal strips and wires: UEP-0001,
a draft for format 2.0 (named ports, terminal strips, wires and cables as objects, potentials).
Control schematics: coils, auxiliary contacts with cross-references, terminal plans and wire numbers,
built on named ports.
Exports: DXF drawings, pandapower networks for load-flow and short-circuit studies.

Ideas and format proposals are welcome: see
CONTRIBUTING.md.

Contributing

Bug reports, examples, rules, symbols and translations are welcome. Read
CONTRIBUTING.md (development setup, tests,
uniwire Enhancement Proposals) and the
Code of Conduct. Report security issues
privately, see SECURITY.md.

Licences

Code, CLI and JSON Schema: Apache License 2.0.
Specification text: CC BY 4.0:
implement it freely, in any software.
Optional data package uniwire-data-iec81346 (IEC 81346-2 class table): CC BY-SA 4.0, distributed
separately (pip install "uniwire[iec81346]").

See NOTICE for third-party notices.