Skip to content

Getting Started with ZapTrace

Installation

Prerequisites

Install from source

ZapTrace is pre-1.0. GitHub Releases is the current artifact channel; PyPI and GHCR publication are not enabled. For contributor use, install from source:

git clone https://github.com/oaslananka/zaptrace.git
cd zaptrace
uv sync --all-extras

Do not assume uv pip install zaptrace resolves to an official package. Download a supported wheel or source distribution from the matching GitHub Release and verify its evidence as described in the distribution support matrix.

Optional: Rust Extension

For faster core algorithms, build the Rust extension:

uv pip install maturin
uv run maturin develop --manifest-path zaptrace_core/Cargo.toml

Verify Installation

zaptrace --version
zaptrace --help

If the MCP server is working:

zaptrace-mcp --help

Your First Design

1. Create a design file

Create my-board.yaml:

meta:
  name: my_board
  description: A simple LED blinker

board:
  width_mm: 50
  height_mm: 40
  layers: 2

components:
  u1:
    ref: U1
    type: mcu
    value: ESP32-C3
    footprint: QFN-32
    pins:
      VCC: power
      GND: ground
      IO2: output
  r1:
    ref: R1
    type: resistor
    value: 10k
    footprint: 0805
    pins:
      p1: passive
      p2: passive
  led1:
    ref: LED1
    type: led
    value: Red
    footprint: 0805
    pins:
      anode: passive
      cathode: passive

nets:
  VCC:
    nodes:
      - U1.VCC
      - R1.p1
  GND:
    nodes:
      - U1.GND
      - LED1.cathode
  LED_OUT:
    nodes:
      - U1.IO2
      - R1.p2
      - LED1.anode

2. Parse and inspect

zaptrace parse my-board.yaml
zaptrace inspect my_board
zaptrace nets my_board

3. Validate

zaptrace erc my_board
zaptrace erc-rules

4. Place and route

zaptrace place my_board
zaptrace route my_board

5. Generate outputs

# Schematic
zaptrace svg my_board --output schematic.svg

# Report
zaptrace report my_board --output report.md

# BOM
zaptrace bom my_board

# Manufacturing package
zaptrace export manufacturing my_board --output build/

6. Full pipeline

zaptrace pipeline --source my-board.yaml --output build/

Next Steps