Schematics and PCB

Hardware in an Embedr project is text: .zen source files in a pcb/ folder next to your firmware. The Schematics tab draws that source, the Board tab shows the KiCad layout generated from it, and the agent edits both.

The hardware source layer

A new electronics workspace looks like this:

my-project/
  embedr.yaml
  src/
    main.cpp
  pcb/
    pcb.toml        # workspace settings and the selected board
    main.zen        # the board's schematic source
    .gitignore      # ignores the .pcb/ cache
    layout/         # KiCad board files, created when the layout is generated
      main.kicad_pcb
      main.kicad_pro

• .zen files are the source of truth. Edit, review and commit them like code.
• pcb/pcb.toml names the board the Schematics and Board tabs open ([board] with name and path).
• The board file declares the board itself, for example Board(name="main", layout_path="layout", layers=2).
• Files under layout/ are generated from the source, then edited by placement, routing and board tools. Commit them if you want others to open the exact board without regenerating it.

A small piece of .zen source:

Resistor = Module("@stdlib/generics/Resistor.zen")

VCC_3V3 = Power(voltage="3.3V")
GND = Ground()
LED_A = Net()

Resistor(name="R1", value="330ohm", P1=VCC_3V3, P2=LED_A)

Nets are variables, parts are module instances, and connections are the nets you pass to each pin.

Set up the workspace

Open the Schematics tab from the Add tab (+) menu under Workspaces. Without a workspace the tab shows one of these states:

State	What it says	What to do
No project open	Open a project to start schematics	Open or create a project first.
No pcb/ workspace	Initialize the PCB workspace	Click Ask agent to initialize schematics.
Workspace but no main .zen	Restore the main board file	Click Ask agent to initialize schematics.

The button sends a request to the agent, which creates pcb/pcb.toml, pcb/main.zen and pcb/.gitignore. Existing files are never overwritten; if a workspace has .zen files but no selected board, the agent adds a [board] entry to pcb.toml and keeps a backup of the old one.

From a terminal, embedr pcb init creates a workspace too, naming the board file after the project. See CLI reference.

Public projects opened by link are view only: the button is disabled and the footer reads "Public projects are view only".

The Schematics tab

The schematic refreshes on its own whenever you save a .zen file, pcb.toml or pcb.sum. While it evaluates, the header shows "Evaluating schematic...".

Readable blocks

Parts without a saved position are arranged automatically into functional blocks, each drawn inside a dashed frame with a bold title (for example a power block, or an IC with its supporting parts). The frames are for reading only: you cannot click them and they are not exported to KiCad.

When you add parts to a schematic you have already arranged, parts you placed stay where they are and the new parts are placed around them.

Navigate

Action	How
Zoom	Mouse wheel, or Zoom in / Zoom out in the bottom bar
Pan	Drag the canvas in View mode, or drag with the middle mouse button
Fit everything	Fit to Viewport
Reset to 100% or focus the selection	Click the zoom percentage
Jump to a part of the drawing	Jump to section… in the header: Whole schematic or any section frame
Re-evaluate	Refresh Schematic

The bottom bar also shows the Components and Nets counts.

Tools

The Tools panel on the left (collapsed at first; click Expand tools) has:

Tool	Shortcut	Use
View / pan	H	Default. Drag to pan, double-click a part to select it.
Select / move	V	Click to select, drag parts to move them.
Section frame	F	Draw a titled frame around a group of parts.
Text	T	Place a text label.
Note box	N	Place a boxed note.
Rectangle		Draw a rectangle.
Line	L	Draw a line.
Arrow	A	Draw an arrow.
Circle	O	Draw a circle.

Also in the panel: Copy screenshot, Undo (⌘Z / Ctrl+Z) and Redo (⇧⌘Z / Ctrl+Shift+Z) for annotations.

Other keys in the canvas:

• Esc returns to View mode.
• R rotates the selected part by 90° (also Rotate Selected (R) in the bottom bar).
• Hold ⌘ / Ctrl while dragging to move a part off the grid.
• Enter edits a selected annotation's text; ⌘Enter / Ctrl+Enter commits it.
• Delete / Backspace removes a selected annotation.

Where your edits are saved

• Part positions you drag are saved into the .zen file as a comment block at the end, with lines like # pcb:sch R1 x=… y=… rot=…. Save any unsaved edits in that file first, or you see "Save the edited board file before saving component positions."
• Section frames, notes, text and shapes are saved as # embedr:schematic-graphic comment lines at the top of the .zen file.

Both are ordinary text, so they show up in diffs and travel with the project.

Find, inspect and export

• The side panel (Toggle Right Panel) has Components, Properties, and, when relevant, Diagnostics and Inputs tabs.
• Components has a search box, "Find component or net...", that matches references, values, names and connected nets.
• Properties shows the selected part's name, position, rotation, footprint and connected nets (click a net to highlight it), plus Open Datasheet when one is known.
• Inputs lists the board's configurable parameters.
• The camera icon (Copy schematic screenshot) copies a PNG to the clipboard.
• Export schematic saves PNG, PDF or SVG, with a resolution of 1x to 100x for images.
• Export to KiCad writes a KiCad schematic and opens it in KiCad. It needs KiCad 10 installed locally.

Click a component to find it everywhere

Select a part (double-click in View mode, or click in Select mode) and a bar appears at the bottom:

• Ref · Value opens its properties.
• Add to chat attaches the part (source file, reference, value, footprint, connected nets, datasheet) to your next message.
• View on board switches to the Board tab and focuses the same part. If it is not on the board yet, the Board tab says so.
• Datasheet opens the datasheet when one is known.

The Board tab has the reverse action, View in schematic. See Board and KiCad.

Diagnostics

Problems in .zen source show up in two places:

• In the editor. .zen files get language support: errors and warnings as squiggles, hover documentation, completion, signature help and go to definition.
• In the Schematics tab. The bottom bar shows a count such as "2 Errors" or "1 Warning". Click it to open the Diagnostics tab, which lists each problem with its location; use the arrow keys to step through them.

If the schematic cannot be evaluated, an error card appears over the canvas with Copy and Retry.

The agent also lints and builds source as it works. Its timeline rows read, for example, "Lint PCB/Zener file" or "Build PCB project", with error and warning counts in the details.

Automatic source fixes

Ask the agent to fix common source problems ("Run pcb fix on the workspace and show me the diff first"). The Fix Zener source row shows one of:

• "Nothing to fix in …"
• "Previewed pcb fix for …" with the diff in its details
• "Applied pcb fix to …"

A fix can cover one .zen file or the whole pcb/ workspace. It only edits .zen source, never KiCad board files. In Plan Mode the agent does not run source fixes.

Inspect a KiCad symbol library

If you bring your own KiCad symbols, the agent can read a .kicad_sym file or .kicad_symdir folder inside the project ("Inspect pcb/libs/sensors.kicad_sym and tell me which symbols have footprints"). The Inspect symbol library row reports "Read N symbol(s) from …" and the agent gets each symbol's name, reference, value, footprint, datasheet, description and keywords. Paths outside the project are refused.

Ask for readability passes

The agent leaves the drawing alone unless you ask. When you want a cleaner schematic, say what you want:

• "Tidy up the schematic."
• "Rearrange the whole schematic from scratch." (This discards positions you saved.)
• "Add a section frame around the power supply and label it."
• "The I2C labels overlap near U1, fix that."

The agent moves parts or adds annotations, looks at the re-rendered schematic, and repeats until it reads well. The Schematics tab opens on its own when the agent saves positions or graphics. Rows you may see: Arrange schematic, Save schematic positions, Schematic graphics and Schematic screenshot.

From requirements to schematic

A typical sequence with the agent:

1. Describe the board: what it does, power input, connectors, the microcontroller, and who will fabricate it. In Plan Mode the agent interviews you and writes a spec.
2. "Initialize the PCB workspace."
3. "Find real parts for a 3.3 V regulator, a USB-C connector and a BME280 in the component library and install them." See Component library.
4. "Write the schematic in pcb/main.zen and build it."
5. "Inspect the netlist and confirm VCC_3V3, GND, SDA and SCL reach the right pins."
6. "Check that the pins match src/main.cpp." Keep firmware and schematic pin assignments in the same task.
7. "Generate the PCB layout." This creates the KiCad board under pcb/layout/ and records your board maker's limits. See Placement and routing.

To check circuit behaviour before layout, see Simulation.

CLI equivalents

embedr pcb init          # scaffold pcb/ (pcb.toml, README.md, board .zen)
embedr pcb status        # workspace, board file and pcb runtime version
embedr pcb build         # build the board .zen
embedr pcb test          # run pcb tests
embedr pcb layout        # generate the KiCad layout (--check, --no-open, --sync-footprints)
embedr pcb open          # open the layout in KiCad
embedr pcb fmt           # format .zen source

Source fixes and symbol library inspection are available through the agent only.