Breadkit / Reference

DSL reference

A .bk.rb file describes the board, parts, wires, and expected connections. Breadkit resolves it into nets and JSON IR. The file runs as Ruby, so only load files you trust.

A small circuit

This is the button and LED example used in the guide.

title "Button-controlled LED"
board :half
supply :USB, voltage: 5.0, plus: "B+1", minus: "B-1"
net :VCC, at: "B+1"
net :GND, at: "B-1"

button :SW1, at: "e10"
resistor :R1, "330", pins: %w[a12 a16]
led :D1, color: :red, anode: "b16", cathode: "b17"
wire "a10", "B+", color: :red
wire "a17", "B-", color: :black

expect do
  connected "SW1.1", :VCC
  isolated :VCC, :GND
end

Declarations

Method	Purpose
title(text)	Set the diagram title.
board(id, split_rails: false, as: nil)	Select `:double_full` (1660 holes), `:full`, `:half`, `:mini`, or a custom board. Use `as:` to name each board in a multi-board circuit.
use_parts(path) / use_boards(path)	Load YAML definitions relative to the DSL file. Globs are supported.
include(path)	Load another trusted Ruby circuit file relative to this file.
block(name) { ... } / use_block(name, ...)	Define and expand reusable circuit declarations with explicit arguments.
bus(name, **lines)	Label related nets at explicit holes or pin references. Add wires separately.
step(number, title:) { ... }	Tag declarations with a numbered assembly stage. Start at 1 and continue in order.
supply(name, voltage:, plus:, minus:)	Add a DC source. Both terminals occupy board holes.
supply(from:, plus:, minus:)	Wire a modeled offboard power output to the positive and negative rails without adding a second voltage source.
net(name, at:)	Label a hole or component pin.
part(ref, type, value = nil, pins: ..., at: ..., **attrs)	Place a defined part. `pins:` accepts an ordered array or a pin-name hash.
wire(from, to, color: nil, route: :straight, layer: nil)	Connect holes or pins. Use `route: :arc` for a curve or `route: :edge` around the board edge. Options also include `id:`, `electrical:`, and `dashed:`.
connect(ref_a, ref_b, when: nil)	Declare a connection you intend without placing a wire. Lint checks the resolved circuit; `breadkit suggest` can propose free holes for two placed pins.
offboard(name, type, side: :left, at: nil, unused: [])	Place a module beside the board. `at:` aligns its first pin; extra attributes such as `address:` appear on the module.
expect(strict: false, when: nil) { ... }	Declare `connected`, `isolated`, or named `net` expectations. Use `when:` for a switch state; strict mode rejects unlisted pins.
expect_voltage(ref, range) / expect_current(ref, range)	Check an inclusive DC voltage or current range when the operating point is known.
lint_disable(rule, on: nil, reason: nil)	Suppress a lint rule, optionally for one target.

Short forms are available for resistor, capacitor, electrolytic, diode, led, transistor, pot, button, and ic. See the component examples.

Hole and pin references

Terminal holes use rows a through j and 1-based numbers, such as a10 or J30.
Rail holes use T+, T-, B+, and B-, with an optional 1-based index. A rail without an index selects a free hole.
Custom board YAML may define other row and rail IDs. Rows u and v use u1 and v1; a rail with id: PWR uses PWR1 or PWR. Set rail polarity: to + or - for polarity-aware rendering. Rail side: accepts top, bottom, left, right, or center; center requires a declared ravine.
Component pins use names such as R1.1, D1.anode, or U1.VCC. A wire endpoint referencing a placed pin selects a free hole on its conductive strip.
ne555 and generic dip parts must straddle the center gap. For a generic DIP, set pin_count, such as part :U2, :dip, pin_count: 14, at: "e20".
A generic header can be sized with part :J1, :pin_header, pin_count: 4, pins: %w[a1 a2 a3 a4].

Values accept SI suffixes and RKM notation, including 4.7k, 4k7, 1M, 100n, and 10uF.

Layers and module pins

Give wires and components the same layer: to show them together in an interactive SVG. A layer can be one name or a list of names. Components without a layer remain visible in every view. Use electrical: false, dashed: true for an alternate visual connection that does not affect connectivity.

Custom YAML definitions can mark module pins with type: values such as power, ground, clock, data, address, or interrupt. The renderer colors those markers and dims unwired pins.

Connect two breadboards

Name each board, then prefix every physical hole and rail with that name. The two boards have separate conductive strips until a wire joins them.

board :half, as: :B1
board :half, as: :B2
supply :BAT, voltage: 5, plus: "B1.T+1", minus: "B2.B-1"
resistor :R1, "330", pins: %w[B1.a1 B1.a3]
led :D1, color: :red, anode: "B2.a1", cathode: "B2.a2"
wire "B1.b1", "B1.T+2", color: :red
wire "B1.b3", "B2.b1", color: :red
wire "B2.b2", "B2.B-2", color: :black

This path runs from the battery through the resistor and LED, then back to the battery. breadkit nets reports three nets: BAT+, N1, and BAT-. Named-board circuits use JSON IR v2; unnamed single-board circuits use JSON IR v1. See a complete JSON circuit example.

Switch states, IR, and CLI

circuit.states("none"), circuit.states("single"), and circuit.states("all") control switch contact simulation. Breadkit.load(path) reads Ruby DSL, declarative YAML or TOML, or JSON IR. circuit.to_ir returns the resolved circuit data, including selected hole positions and assembly steps.

A part with independent SPST contacts declares switch: [[P1A, P1B], [P2A, P2B]] and independent_switches: true. The built-in C&K BD04 has four such positions. For an instance named SW1, use SW1.1 through SW1.4, or select several with circuit.state("SW1.1,SW1.4"). See the component guide for its footprint and source.

breadkit nets circuit.bk.rb
breadkit parts
breadkit ir circuit.bk.rb
breadkit suggest circuit.bk.rb
breadkit patterns circuit.bk.rb
breadkit fmt circuit.bk.yml > formatted.bk.yml

Use breadkit nets to inspect connections, breadkit parts to list built-in definitions, and breadkit ir to print JSON IR. breadkit suggest prints JSON wire candidates for unmet, state-independent connect intent when both pins are placed and safe holes are free. It does not alter the circuit. breadkit fmt prints normalized declarative YAML or TOML and discards comments. See the YAML and TOML example.

breadkit patterns prints JSON for an unloaded resistor divider or the exact NE555 astable LED wiring shown in the official example. It reports the divider midpoint voltage, but does not estimate 555 frequency or prove oscillation. An empty array means no supported pattern matched. See the CLI pattern reference for the required connections.

For editor validation, use the published part and board JSON Schemas. Add a YAML language server modeline to a part or board file, or associate optional *.bkpart.yml and *.bkboard.yml filenames in editor settings:

# yaml-language-server: $schema=https://breadkit.github.io/breadkit/schema/part-v1.json
id: custom_part
pins:
  - {num: 1, name: SIGNAL}

See the editor settings example for workspace-wide YAML and JSON IR associations.