Build And Test

Build & Test Workflow

Typical Order

1. ato validate -- quick syntax check. Catches parse errors before a full build. No solver, no parts, no PCB. Use after editing .ato files to confirm they parse cleanly.
2. ato build -- the main command. Runs from the project directory (wherever ato.yaml lives). Stages in order: resolve dependencies, build context, instantiate, verify design, pick parts from JLCPCB, update PCB, generate reports. A successful build means the design is electrically valid and all parts are available.
3. ato build --open -- same as above, then launches KiCad layout editor so you can inspect/route the PCB.
4. ato build -b -- build a specific target from ato.yaml (e.g. ato build -b test). Useful when a project has multiple build targets.
5. ato build --verbose -- runs sequentially without the live display. Better for reading error messages.
6. ato inspect -- debug connectivity. Shows what is connected to a module at a given boundary. Use --inspect --context to see connections from a specific viewpoint.
7. ato create part -s "" -- search JLCPCB and generate a component package (.ato + KiCad footprint/symbol) in parts/. Interactive: presents matches and lets you pick.

Run any command with --help for full flag details.

Build Outputs

After a successful build, outputs land in build/builds//:

| File | Contents | |------|----------| | .bom.csv | Bill of materials -- designators, footprints, manufacturer, LCSC part numbers | | .bom.json | Same BOM in JSON format | | .variables.ato.json | All solved parameter values -- spec vs actual, whether constraints are met | | .power_tree.ato.json | Power tree structure (JSON) | | power_tree.md | Power tree as Mermaid diagram | | .data_interface_tree.ato.json | Data interface topology | | pinout/ | Per-component pinout JSON files | | backups/ | PCB backup snapshots |

The build/cache/ directory stores downloaded datasheets (PDFs) for picked parts.

Debugging Build Errors

"No parts found matching constraints"

The most common error. The JLCPCB part solver cannot find a real part matching your parameter assertions. Fix in this order:

1. Add tolerances -- resistance = 10kohm matches nothing (0% tolerance). Use resistance = 10kohm +/- 5% or assert resistance within 10kohm +/- 10%.
2. Widen package constraint -- package = "0201" severely limits options. Try "0402" or remove the package constraint entirely.
3. Check for conflicting assertions -- two assertions on the same parameter can create an impossible range. Use get_hover from the LSP on the parameter to see the effective constraint.
4. Check maxvoltage / maxcurrent -- if you assert max_voltage within 100V +/- 10% on a 0402 cap, nothing exists. Relax or remove secondary constraints.
5. Inspect the variables report -- after a partial build, check build/builds//.variables.ato.json to see what the solver computed for each parameter.

"Assertion failed"

A design rule check (assert statement) evaluated to false after part picking. The error message names the specific assertion and the values it compared.

1. Read the assertion in the .ato source -- it tells you what relationship was expected.
2. Use get_hover on the parameters involved to see their solved values.
3. Either loosen the assertion (widen the tolerance) or tighten the input (pick a more precise part, constrain upstream parameters).

Connection / wiring errors

Symptoms: "cannot connect X to Y", type mismatch on ~, or missing pins.

1. You can only connect interfaces of the same type. ElectricPower ~ Electrical will fail -- you need to connect to the correct sub-interface (e.g. power.hv ~ some_electrical).
2. Use ato inspect --inspect --context to see what is actually connected where.
3. Check ~ vs ~> usage. ~> is the bridge-connect operator and requires #pragma experiment("BRIDGE_CONNECT") and the module must have the can_bridge trait.
4. Make sure pin names match. Use get_hover or get_definition on the component to verify pin names.

Import / dependency errors

Symptoms: "module not found", "cannot resolve import", file path errors.

1. Check ato.yaml -- is the dependency listed? Is the path correct for type: file deps?
2. Run ato dependencies sync to install/update dependencies.
3. For registry packages: ato dependencies add to add and install.
4. For local packages: use type: file with a relative path from the project root.
5. Verify the import path matches the actual file path and module name.

Build hangs or is very slow

The part picker queries JLCPCB and can be slow. If it hangs:

1. Check your internet connection -- part picking requires network access.
2. Use --verbose to see which stage is stalling.
3. If stuck on "Picking parts", you may have too many unconstrained components. Add package constraints to narrow the search space.
4. Use --keep-picked-parts to reuse previously picked parts and skip re-solving.

PCB-related errors

1. --frozen mode (CI) fails if the PCB needs changes. Remove --frozen locally to let it update, then commit the result.
2. "Backing up unsaved pcb changes" is informational, not an error -- it saves your KiCad session before overwriting.
3. If KiCad is open and locked, close it or remove the .lck file before building.

Package Management

# ato.yaml dependency types:
dependencies:
  - type: registry          # From packages.atopile.io
    identifier: atopile/netties
    release: 0.2.0

  - type: file              # Local/vendored package
    identifier: /
    path: ../packages/

| Command | What it does | |---------|-------------| | ato dependencies add | Add a registry package (e.g. atopile/netties) | | ato dependencies add file:// | Add a local package | | ato dependencies remove | Remove a dependency | | ato dependencies sync | Install/update all deps to match ato.yaml | | ato dependencies sync -U | Upgrade deps, ignoring pinned versions | | ato dependencies list | Show current dependencies |

LSP Integration for Debugging

Use the atopile LSP MCP tools (see the lsp skill) alongside builds:

• get_diagnostics -- faster than a full build for catching syntax errors after edits.
• get_hover -- inspect solved parameter constraints, interface types, and member lists. Essential for debugging "no parts found" and "assertion failed".
• get_definition -- jump to where an interface or module is defined when you need to understand its structure.
• get_references -- find everywhere a symbol is used when tracing connectivity issues.

Build Flags Quick Reference

| Flag | Use case | |------|----------| | --verbose / -v | See full sequential output instead of live display | | --open | Launch KiCad after build | | --frozen | CI mode -- fail if PCB would change | | --keep-picked-parts | Reuse previously picked parts | | --keep-net-names | Preserve net names from PCB | | --keep-designators | Preserve designators from PCB | | --all | Build all projects found recursively | | -j N | Set max concurrent builds (default: 14) |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mawildoer
• Source: mawildoer/atopile-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.