Usage

[blocked]

The AI Pair Designer for Professional PCB Layout

atoplace is an intelligent orchestration layer for PCB design that bridges the gap between schematic and physical layout. It automates the tedious 80% of design—placement optimization and DFM validation—while strictly adhering to "Manhattan" aesthetics and Signal Integrity (SI) best practices.

Designed to work seamlessly with atopile and KiCad.

🚀 Why atoplace?

PCB layout automation has historically been "black box" and "messy"—producing organic, unreadable layouts that professional engineers reject. atoplace takes a different approach:

• Human-Grade Aesthetics: We don't just minimize wirelength. We enforce grids, alignment, and orthogonal routing so the result looks like you designed it.
• Physics-First: We model high-degree nets (GND/VCC) correctly to prevent component collapse, and prioritize critical signals (USB, RF) before general routing.
• Transparent & Interactive: No lock-in. The source of truth is always your .kicad_pcb file. You can take over manually at any second.

✨ Key Features

• 🧩 Manhattan Legalizer: Transforms "organic" force-directed placements into professional, grid-snapped, and row-aligned layouts using PCA axis detection and Abacus-style overlap resolution.
• 🧠 Intelligent Placement: Force-directed annealing engine with a Star Model for stable high-degree net (GND/VCC) handling and adaptive damping for oscillation control.
• 🚀 A Routing*: High-performance, deterministic geometric router using a Greedy Multiplier ($w=2-3$) and Spatial Hash Indexing for O(~1) collision detection.
• 🔍 Confidence Scoring: Automated assessment of your board's routability, signal integrity risks, and DFM compliance.
• 💬 Natural Language Control: "Move the USB connector to the left edge", "Align these capacitors", "Keep the crystal near the MCU".
• 🔌 Atopile Native: First-class support for atopile projects with ato-lock.yaml parsing, module-aware grouping, and atoplace.lock sidecar persistence to preserve placements across rebuilds.
• 📊 Interactive Visualization: Unified SVG delta viewer with real-time playback, layer toggles, grid customization, force vector display, routing trace visualization, and A* debug mode for step-by-step algorithm analysis.

🛠️ Installation

pip install atoplace

Requirements

• Python 3.10+
• KiCad 8.0+ (atoplace uses the pcbnew Python API)

Pro Tip: atoplace works best when run using the Python interpreter bundled with KiCad:

macOS:

/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 -m pip install atoplace

Windows:

"C:\Program Files\KiCad\8.0\bin\python.exe" -m pip install atoplace

⚡ Quick Start

1. Optimize Placement

Automatically place components with "Manhattan" legalization:

atoplace place board.kicad_pcb --grid 0.5 --constraints "USB on left edge"

2. Route the Board

Route all nets using the internal A* geometric planner:

atoplace route board.kicad_pcb --visualize

3. Validate Layout

Check your board against DFM rules (JLCPCB, OSH Park, etc.):

atoplace validate board.kicad_pcb --dfm jlcpcb_standard

4. Interactive Mode

Refine your design using natural language:

atoplace interactive board.kicad_pcb
# > "Rotate U1 45 degrees"
# > "Move C1 closer to U1"
# > "Save"

5. MCP Server (LLM Integration)

Expose atoplace tools to AI agents via the Model Context Protocol:

atoplace mcp --launch

See MCP Server section below for details.

🗺️ Roadmap

• Milestone A (Q1 2026): Solid Foundation ✅
  • Manhattan Legalizer (Grid snapping & PCA Alignment).
  • Physics Engine scaling (Star Model & Adaptive Damping).
  • Atopile ato-lock.yaml and module hierarchy integration.
• Milestone B (Q1-Q2 2026): Routing & Persistence ✅
  • A Geometric Planner* (Greedy Multiplier & Spatial Indexing).
  • MCP Server with 40+ tools for LLM agent integration.
  • Live KiCad IPC via kipy for real-time component manipulation (KiCad 9+).
  • atoplace.lock Sidecar Persistence for atopile projects.
  • Unified Visualization (SVG delta viewer with routing support).
  • BGA/QFN Fanout Generator (dogbone & via-in-pad strategies).
  • Pin Swap Optimization (bipartite matching for crossing reduction).
• Milestone C (Q2 2026): Professional Agent 🚧
  • Differential Pair Detection (auto-detect from net names).
  • Differential Pair Coupled Routing.
  • Deep Signal Integrity Analysis (Crosstalk/Impedance).
  • Automated Manufacturing Outputs (Gerbers/BOM/PNP).
  • Multi-board design support.

📂 Architecture

atoplace/
├── board/          # Board abstraction & KiCad/Atopile adapters
│   ├── abstraction.py      # Board, Component, Net, Pad data models
│   ├── kicad_adapter.py    # KiCad pcbnew integration
│   ├── lock_file.py        # atoplace.lock sidecar persistence
│   └── atopile_adapter.py  # Atopile project loader
├── placement/      # Force-directed physics & Manhattan Legalizer
│   ├── force_directed.py   # Physics Engine (Star Model, adaptive damping)
│   ├── legalizer.py        # Manhattan Pipeline with PCA alignment
│   ├── module_detector.py  # Functional module hierarchy analysis
│   ├── constraints.py      # Placement constraints (Proximity, Edge, Zone, etc.)
│   └── visualizer.py       # SVG delta visualization with frame capture
├── routing/        # A* Geometric Router
│   ├── astar_router.py     # Core A* with Greedy Multiplier (w=2-3)
│   ├── manager.py          # Multi-phase routing pipeline
│   ├── spatial_index.py    # O(~1) collision detection via spatial hashing
│   ├── obstacle_map.py     # Obstacle generation from board
│   ├── diff_pairs.py       # Differential pair detection
│   ├── visualizer.py       # Routing visualization with A* debug
│   └── fanout/             # BGA/QFN escape routing
├── visualization/  # Unified visualization system
│   └── assets/             # External JS/CSS for HTML viewer
│       ├── svg-delta-viewer.js  # Interactive SVG playback engine
│       └── styles.css      # KiCad-inspired dark theme

🤖 MCP Server

atoplace includes a Model Context Protocol (MCP) server that exposes 40+ PCB design tools to LLM agents like Claude. This enables conversational PCB layout design with support for placement, routing, fanout generation, and design validation.

Quick Start

Just run:

python -m atoplace.mcp.launcher

That's it! The launcher:

• Auto-detects KiCad Python on macOS, Linux, and Windows
• Starts the KiCad bridge (for pcbnew access)
• Starts the MCP server (exposes tools to LLM)
• Manages lifecycle and clean shutdown

Claude Code / Claude Desktop Configuration

Add to your MCP config:

{
  "mcpServers": {
    "atoplace": {
      "command": "python",
      "args": ["-m", "atoplace.mcp.launcher"]
    }
  }
}

Note: Replace python with the path to your atoplace virtualenv Python if needed.

🔴 Live KiCad IPC Mode (KiCad 9+)

New! With KiCad 9+, atoplace can manipulate components in real-time without save/reload cycles. Changes appear instantly in your KiCad viewport!

Requirements:

• KiCad 9.0 or later (with IPC API enabled)
• kicad-python package: pip install kicad-python

Setup:

# Install the kipy optional dependency
pip install atoplace[kipy]

# Or install directly
pip install kicad-python

Usage:

1. Open your .kicad_pcb in KiCad 9+ PCB Editor
2. Start the MCP server with the kipy backend:

   ATOPLACE_BACKEND=kipy python -m atoplace.mcp.launcher

3. Components move instantly as you interact with the LLM!

How it works: The kipy backend connects directly to KiCad's IPC socket and uses the official API to update component positions in real-time. Native undo/redo (Cmd/Ctrl+Z) works seamlessly.

Architecture

flowchart LR
    subgraph MCP["MCP Server (Python 3.10+)"]
        direction TB
        FastMCP[FastMCP]
        Tools[26 Layout Tools]
        Context[Context Generators]
    end

    subgraph KiPy["KiPy Backend (KiCad 9+)"]
        direction TB
        IPC[KiCad IPC API]
        LiveEdit[Real-time Updates]
        NativeUndo[Native Undo/Redo]
    end

    subgraph Bridge["KiCad Bridge (KiCad 8.x)"]
        direction TB
        pcbnew[pcbnew API]
        BoardIO[Board I/O]
        UndoRedo[Undo/Redo]
    end

    MCP <-->|"KiCad IPC\nSocket"| KiPy
    MCP <-->|"Unix Socket\nJSON-RPC"| Bridge

Backend Modes:

Note: KIPY mode is the primary backend for bleeding-edge development. It provides instant visual feedback in KiCad's viewport and native undo/redo integration. The server automatically falls back to IPC or direct mode if KIPY is unavailable.

Available Tools (40+ total)

Environment Variables (Optional)

Default behavior: The server attempts KIPY first, then falls back to IPC, then direct mode. For bleeding-edge KiCad 9+ users, no configuration is needed - KIPY mode activates automatically when KiCad is running with IPC enabled.

Example LLM Conversation

User: Load the board at examples/dogtracker/layouts/default/default.kicad_pcb

Claude: [Calls load_board tool]
Board loaded successfully:
- 37 components
- 72 nets

User: Find all the capacitors and align them horizontally

Claude: [Calls find_components with query="C", filter_by="ref"]
Found 12 capacitors: C1, C2, C3...

[Calls align_components with refs=["C1","C2",...], axis="y"]
Aligned 12 capacitors along the Y axis.

User: Check if there are any overlaps

Claude: [Calls check_overlaps]
No overlapping components detected. The placement is valid.

User: Save the board

Claude: [Calls save_board]
Board saved to: examples/dogtracker/layouts/default/default.placed.kicad_pcb

🔒 Atopile Lock File Persistence

When working with atopile projects, placement positions can be lost when ato build regenerates the KiCad board. The atoplace.lock sidecar file solves this by persisting component positions between builds.

How it works

After placement, atoplace automatically saves positions to a lock file next to the board:

my-project/
├── elec/
│   └── layout/
│       └── default/
│           ├── default.kicad_pcb
│           └── default.atoplace.lock  ← Saved positions
└── ato.yaml

Lock File Format

version: 1
created: 2026-01-14T10:30:00
build: default
components:
  U1:
    x: 125.5
    y: 80.0
    rotation: 0.0
    locked: true    # User-approved position
    module: mcu
  C1:
    x: 130.0
    y: 85.5
    locked: false   # Auto-placed, can be re-optimized

CLI Options

Workflow Example

# First placement - automatically saves lock file
atoplace place my-project/ --use-ato-modules

# After `ato build` regenerates board - restore positions
atoplace place my-project/ --use-lock

# Only restore approved positions, re-optimize others
atoplace place my-project/ --use-lock --only-locked

# Approve all current positions
atoplace place my-project/ --lock-all

Merge Logic

The lock file uses Lock > Physics priority:

1. locked: true positions always preserved (user-approved)
2. locked: false positions used as initial hints, can be re-optimized
3. New components (not in lock file) placed by physics engine

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• atopile: The declarative language that makes code-driven hardware possible.
• KiCad: The open-source EDA standard we build upon.
• kicad-python: Official Python bindings for KiCad's IPC API.
• Freerouting: The open-source autorouting engine.