Skip to content

docs: refresh README with sensor controller example #113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eduardozf merged 1 commit into from
Sep 7, 2026
Merged

docs: refresh README with sensor controller example #113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 82 additions & 130 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,56 +18,111 @@
<img src="https://img.shields.io/node/v/wire-lang.svg" alt="Node version">
</p>

**Text-first electronic schematics.** Describe a circuit in a small declarative
language and render it as a clean, documentation-ready SVG.
Describe electronic schematics in text and render them as SVG.

## Why Wire Lang
## This is how you write

LLMs changed how we write software because code is text. Diagrams followed with tools like [Mermaid](https://github.com/mermaid-js/mermaid), giving AI a format it can easily generate, understand, and modify.
Name the components, declare their pins, and connect them with nets.
Here is an excerpt from a sensor controller with a button and status LED:

Electronic schematics are still stuck in GUI editors.

Wire Lang brings schematics into the AI era with a text-based representation that enables real-time collaboration between engineers and AI. Instead of screenshots and proprietary files, schematics become something AI can reason about, generate, review, and improve.

Wire Lang is the missing layer between AI and electronic schematics.
```wire
schematic
title "Sensor controller with status LED"

## Setup
// Declare a button and a green status LED.
component SW1 PushButton
component D1 LED color=green

```bash
npm install wire-lang
// Connect named pins to describe each electrical net.
net BTN: SW1.1, U2.BTN
net LED_OUT: U3.OUT, D1.A
// ... full circuit below
```

Write a `.wire` file:
<details>
<summary>View the complete Wire Lang source</summary>

```wire
schematic
title "LED current limiting circuit"
title "Sensor controller with status LED"
description "A controller reads an I2C sensor, accepts a button input, and controls a status LED through a driver."

// Declare each block and its named pins. @left and @right set pin sides.
// U1: I2C sensor with an interrupt output.
component U1 IC pins=[1:VCC@left, 2:GND@left, 3:SCL@right, 4:SDA@right, 5:INT@right]
// U2: microcontroller that reads the sensor and button.
component U2 IC pins=[1:3V3@left, 2:GND@right, 3:SCL@left, 4:SDA@left, 5:IRQ@left, 6:BTN@left, 7:DRIVE@right, 8:FAULT@right]
// U3: LED driver with a fault output back to the controller.
component U3 IC pins=[1:VIN@left, 2:GND@left, 3:IN@left, 4:FAULT@left, 5:OUT@right]
component SW1 PushButton
component D1 LED color=green

// All blocks share the supply and ground rails.
net VCC: U1.VCC, U2.3V3, U3.VIN
net GND: U1.GND, U2.GND, U3.GND, SW1.2, D1.C

// The sensor sends readings over I2C and signals an interrupt on INT.
net SCL: U1.SCL, U2.SCL
net SDA: U1.SDA, U2.SDA
net INT: U1.INT, U2.IRQ

// The controller commands the driver, which reports faults back.
net DRIVE: U2.DRIVE, U3.IN
net FAULT: U3.FAULT, U2.FAULT

// Pressing the button connects BTN to ground. The driver powers the LED.
net BTN: SW1.1, U2.BTN
net LED_OUT: U3.OUT, D1.A

// Draw supply rails above and below the blocks, and bundle related signals.
render layout=bus-rail
```

component BT1 Battery voltage=5V
component R1 Resistor value=220ohm
component D1 LED color=red
</details>

## This is what you get

The complete source renders as a schematic with shared power rails, a sensor
bus, and separate control signals.

<img src="./docs/assets/sensor-controller.svg" alt="Sensor controller with an I2C sensor, LED driver, status LED, and push button" width="100%">

net VCC: BT1.+, R1.1
connect R1.2, D1.A
net GND: D1.C, BT1.-
## Install and use

annotation "Current limiting resistor" near R1
```bash
npm install wire-lang
```

Render it from the CLI:
Save the [complete source](./examples/sensor-controller.wire) as
`sensor-controller.wire`, then render it:

```bash
npx wire render led.wire --out led.svg
npx wire render sensor-controller.wire --out sensor-controller.svg
```

…or from JavaScript/TypeScript:
Open `sensor-controller.svg` to view the schematic. To render from JavaScript or TypeScript:

```ts
import { renderSvg } from "wire-lang";

const svg = renderSvg(source);
```

## AI skill

Install the [Wire Lang authoring skill](./skills/wire-lang/SKILL.md) to teach your
AI assistant the syntax, component library, and validation workflow:

```bash
npx skills add eduardozf/wire-lang --skill wire-lang
```

Agents can validate source with `wire check sensor-controller.wire --json`. The parser returns
a partial AST for invalid input, with source locations and suggested fixes in
its diagnostics.

## Markdown and MDX

Write the same source inside a Markdown or MDX fence:

````markdown
Expand Down Expand Up @@ -100,72 +155,8 @@ For ahead-of-time rendering with no browser runtime, use `remarkWire` or
`rehypeWire` from `@wire-lang/markdown` with `{ mode: "static" }`. See the
[Markdown/MDX guide](./packages/markdown) for complete build configuration.

## How it compares

Think **[Mermaid Charts](https://github.com/mermaid-js/mermaid), but for electronic schematics**: text goes in, documentation-
friendly diagrams come out. The difference is that Wire Lang models real
electrical nets, terminals, and components instead of flowchart boxes and arrows.

## Use with AI

Wire Lang is built for AI-assisted authoring:

- `parse(source)` returns a partial AST even for invalid input, and every
diagnostic carries a source location and suggested fix — so agents can
self-correct.
- The CLI speaks JSON for scripts and agents: `wire check led.wire --json`.
- A bundled [Agent Skill](./skills/wire-lang/SKILL.md) teaches assistants the
syntax and component library so they generate valid `.wire` source.

Install the authoring skill with the open Agent Skills CLI:

```bash
npx skills add eduardozf/wire-lang --skill wire-lang
```

## Examples

| LED current limiter | Soil sensor (bus-rail) | Bus-rail block diagram |
| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| <img src="./docs/assets/led-current-limiter.svg" alt="LED current limiting circuit rendered by Wire Lang" width="260"> | <img src="./docs/assets/soil-sensor.svg" alt="Soil sensor module rendered by Wire Lang" width="260"> | <img src="./docs/assets/bus-rail.svg" alt="Bus-rail block diagram rendered by Wire Lang" width="260"> |

See the [full gallery](./docs/EXAMPLES.md) and source in [examples/](./examples).

---

## Reference

### The language

Wire Lang separates the electrical model from the rendered drawing. In the
source below, `R1`/`D1` are component instances, `Resistor`/`LED` are types,
`VCC`/`GND` are nets, and `connect` makes an anonymous net. Visual wires are
renderer output, not the source of truth.

```wire
schematic
component R1 Resistor value=10k
component D1 LED color=red

net VCC: R1.1
connect R1.2, D1.A
net GND: D1.C
```

Components can also be defined locally, including overriding a built-in symbol:

```wire
define component SoilSensor
terminal VCC
terminal GND
terminal AOUT
terminal DOUT
symbol module
end

component S1 SoilSensor
```

### API

```ts
Expand All @@ -182,54 +173,15 @@ stage's output. Packages are ESM-only and target Node.js 20+.
### CLI

```bash
wire check examples/led.wire # validate
wire render examples/led.wire --out led.svg
wire watch examples/led.wire --out led.svg
wire check examples/sensor-controller.wire # validate
wire render examples/sensor-controller.wire --out sensor-controller.svg
wire watch examples/sensor-controller.wire --out sensor-controller.svg
```

Add `--json` to `check`/`render` for machine-readable output. Exit codes: `0`
success (incl. warnings), `1` source/render errors, `2` usage or I/O problems.
There is no preview server; open the generated SVG directly.

### Standard components

`Resistor`, `Capacitor`, `PolarizedCapacitor`, `Inductor`, `Diode`, `LED`,
`NPNTransistor`, `PNPTransistor`, `Battery`, `GroundReference`, `SPSTSwitch`,
`PushButton`, `Header`.

Wire Lang uses IEC-style conventions where practical with original, open-source
symbol art; it does not claim formal IEC/IEEE compliance. See
[CONTRIBUTING.md](./.github/CONTRIBUTING.md) for the artwork policy.

### Packages & development

| Package | Role |
| -------------------------------------------- | ----------------------------------------------------------- |
| [`wire-lang`](./packages/wire-lang) | User-facing aggregate package and the `wire` binary |
| [`@wire-lang/core`](./packages/core) | Parser, compiler, schematic model, layout engine, renderer |
| [`@wire-lang/cli`](./packages/cli) | `wire check`, `wire render`, `wire watch` |
| [`@wire-lang/browser`](./packages/browser) | Asynchronous rendering after HTML loads |
| [`@wire-lang/markdown`](./packages/markdown) | Markdown and MDX integration with optional static rendering |

```bash
pnpm install
pnpm build # tsup build + tsc typecheck
pnpm test # vitest
```

### Scope

The MVP is implemented: a working `parse → compile → layout → renderSvg`
pipeline plus the CLI. Scope is intentionally narrow — schematic documentation,
not simulation, PCB/breadboard layout, BOMs, or editor integrations. See
[docs/MVP.md](./docs/MVP.md) for the full specification.

## Documentation

- [MVP specification](./docs/MVP.md) · [Example gallery](./docs/EXAMPLES.md) · [Domain vocabulary](./docs/CONTEXT.md)
- [Architecture decisions](./docs/adr/) · [Brand assets](./docs/brand/)
- [Contributing](./.github/CONTRIBUTING.md) · [Code of conduct](./.github/CODE_OF_CONDUCT.md) · [Support](./.github/SUPPORT.md) · [Security](./.github/SECURITY.md) · [Changelog](./CHANGELOG.md)

## Contributing

Wire Lang is early and design-heavy. The most useful contributions right now are
Expand Down
Loading