Atopile + KiCad on Linux Mint

Full Debugging Journey, Lessons Learned & Minimal Working Examples

Why This Exists

This document captures a real debugging journey of getting:

Atopile (ato)
KiCad
Linux Mint (Ubuntu Noble base)

to work together.

This is not a tutorial written after success.

This is a forensic reconstruction of failure → iteration → understanding → resolution.

Goal:

Make future debugging faster by documenting what actually went wrong.

Why Atopile?

We explored different approaches for electronics design:

Approach	Problem
KiCad GUI-only	Hard to scale, low reproducibility
Python EDA tools	Fragmented ecosystems
SPICE-only workflows	No PCB/layout integration
Atopile	✅ Code-first + PCB + BOM + constraints

Atopile stood out because:

Code-based hardware design (.ato)
Declarative design + constraint solving
Direct KiCad integration
Automatic BOM and layout updates

Initial Goal (MWE)

We wanted a minimal working example

ato build

that:

resolves dependencies
picks parts
generates a PCB
outputs BOM + artifacts
optionally integrates with KiCad

Environment

System:

Linux Mint (based on Ubuntu Noble 24.04)
Python via uv tool install
KiCad initially 7.0.11 → later upgraded to 10.0.3

Atopile installed via:

uv tool install atopile

First Success

✅ ato build worked

Output:

Build successful! 🚀

Artifacts:

elec/layout/default/default.kicad_pcb
elec/layout/default/default.kicad_pro

This proves:

✅ Atopile core pipeline works independent of KiCad plugin

First Failure: KiCad Plugin Warning

Repeated warning:

Couldn't install plugin: Could not find KiCad plugin path
Couldn't enable plugin api: KeyErrorNotFound()

Important insight:

⚠️ Build succeeded anyway → plugin is optional, not blocking

Debugging Phase 1: Path Guessing

We tried:

~/.local/share/kicad/7.0/scripting/plugins
~/Documents/KiCad/7.0/scripting/plugins

Also:

kicad:
  search_paths:

Result:

✅ Config accepted
❌ Warning unchanged

Key Insight #1

From faebryk/libs/kicad/paths.py:

KICAD_VERSION = "9.0"

This was the breakthrough.

Root Cause

❌ Atopile internally assumes:

KiCad version = 9.0

❌ But system actually had:

KiCad 7 → first
KiCad 10 → later

Critical Bug Pattern

The path logic:

return [Path(p) / KICAD_VERSION]

Meaning:

If you give:

/home/<userName>/.local/share/kicad/10.0/scripting/plugins

It looks for:

/home/<userName>/.local/share/kicad/10.0/scripting/plugins/9.0

→ impossible path

Debugging Phase 2: Correct Mental Model

We learned:

Atopile expects base paths, not final plugin directories

Correct:

kicad:
  search_paths:
    - ~/.local/share/kicad
    - ~/.config/kicad
    - ~/Documents/KiCad

Not:

.../10.0/scripting/plugins

Debugging Phase 3: Upgrade KiCad

Installed latest KiCad:

sudo add-apt-repository ppa:kicad/kicad-10.0-releases
sudo apt install kicad

Verified:

kicad-cli version
→ 10.0.3

Debugging Phase 4: Patch Required

Because Atopile still used:

KICAD_VERSION = "9.0"

We patched:

KICAD_VERSION = "10.0"

Working Fix

1. Config

kicad:
  search_paths:
    - ~/.local/share/kicad
    - ~/.config/kicad
    - ~/Documents/KiCad
    - /usr/share/kicad

2. Ensure directories exist

mkdir -p ~/.local/share/kicad/10.0/plugins
mkdir -p ~/.local/share/kicad/10.0/scripting/plugins
mkdir -p ~/.config/kicad/10.0

3. Patch Atopile

KICAD_VERSION = "10.0"

4. Enable KiCad API

Inside KiCad:

Preferences → Plugins → Enable plugin API

Remaining Warning

Even after fixes:

Couldn't enable plugin api: KeyErrorNotFound()

Interpretation:

Likely requires running KiCad instance
IPC API interaction not fully initialized
Not blocking

✅ Safe to ignore for now

Final Working State

✅ ato build works
✅ KiCad project generated
✅ PCB file usable
✅ Full pipeline functional

Verified Workflow

ato build
kicad ./elec/layout/default/default.kicad_pro

or:

pcbnew ./elec/layout/default/default.kicad_pcb

Lessons Learned (Critical)

1. Build ≠ Plugin

Atopile builds independently of KiCad plugin

2. Version mismatches are silent killers

Hardcoded:

KICAD_VERSION = "9.0"

→ broke everything subtly

3. Paths must be semantically correct

Not just "existing"
Must match internal assumptions

4. AI-assisted debugging works best iteratively

We used:

Copilot
Gemini
Claude

Each helped:

Tool	Strength
Gemini	hardware reasoning
Claude	high-level structuring
Copilot	step-by-step diagnostics

5. Minimal Working Example (MWE) is essential

Without:

ato build

working first → debugging would be chaotic

Bonus: Hardware Parallel (from Gemini)

Your debugging pattern mirrors hardware constraints:

Sensor limits → field-of-view
Software limits → plugin path resolution

Both cases show:

System behavior is governed by hidden assumptions

What Still Needs Improvement (Atopile)

Auto-detect KiCad version (not hardcoded)
Better error message than:
```
Could not find KiCad plugin path
```
Show actual paths being checked
Remove need for manual patching

Final Takeaway

This journey shows:

Real engineering ≠ following docs
Real engineering = understanding why things fail

If You Are Reading This

Start here:

ato build

Then:

Ignore plugin at first
Confirm PCB generation works
Only then debug KiCad integration

End

This document is intentionally verbose.

Because debugging is expensive.

Understanding once saves time forever.

Foadsf/atopile-kicad-linux-mint-debugging-journey.md