Skip to content

Getting Started with ZapTrace

Installation

Prerequisites

  • Python 3.12 or 3.13
  • uv (recommended) or pip

Install from source

ZapTrace is pre-1.0 and not yet published to PyPI; install from source:

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

Once published, uv pip install zaptrace will install the zaptrace distribution; the import package and CLI commands are zaptrace.

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