atopile VSCode Extension

The official Visual Studio Code extension for atopile - the language and toolchain to design electronics with code.

Design circuit boards with the same powerful workflows that software developers use: version control, modularity, and automated validation. Write human-readable .ato files instead of point-and-click schematics.

✨ Features

🔤 Language Support

Syntax highlighting for .ato files with rich semantic coloring
IntelliSense with auto-completion for modules, interfaces, and parameters
Go to definition and find references for symbols
Hover information showing parameter types and documentation
Error diagnostics with real-time validation

🏗️ Project Management

Create new projects with templates and scaffolding
Build integration with one-click builds and error reporting
Build target selection for different project outputs
Project explorer showing module hierarchy and dependencies

📦 Package Management

Add packages from the atopile package registry
Remove packages with dependency cleanup
Package explorer for browsing available modules
Automatic dependency resolution

🔧 Design Tools Integration

KiCAD integration - launch PCB editor directly from VS Code
Layout preview with integrated kicanvas viewer
3D model preview for visualizing your designs
Real-time build feedback with instant error detection

🤖 AI & Automation

LLM setup for AI-assisted design with MCP (Model Context Protocol)
Code snippets for common circuit patterns
Design validation with automated checks

🚀 Getting Started

Prerequisites

Visual Studio Code 1.78.0 or later
Python extension for VS Code
Git (recommended for version control)

Installation

From VS Code Marketplace:
- Open VS Code
- Go to Extensions (Ctrl+Shift+X)
- Search for "atopile"
- Click Install

From Command Line:

code --install-extension atopile.atopile

Quick Start

Create a new project:
- Open Command Palette (Ctrl+Shift+P)
- Run "atopile: Create project"
- Choose a template and location
Open an example:
- Open Command Palette (Ctrl+Shift+P)
- Run "atopile: Open Example Project"
- Explore the examples to learn atopile syntax

Start coding:

module MyFirstCircuit:
    # Create a simple LED circuit
    led = new LED
    resistor = new Resistor

    # Set component values
    resistor.resistance = 220ohm +/- 5%
    resistor.max_power = 0.25W

    # Connect components
    power.hv ~> resistor ~> led.anode
    led.cathode ~ power.lv

📋 Commands

Access these commands via the Command Palette (Ctrl+Shift+P):

Command	Description
`atopile: Create project`	Create a new atopile project
`atopile: Build`	Build the current project
`atopile: Choose build target`	Select build configuration
`atopile: Add package dependency`	Install a package from registry
`atopile: Remove package dependency`	Remove a package
`atopile: Add part`	Add electronic components
`atopile: Launch KiCAD`	Open PCB in KiCAD editor
`atopile: Open Layout Preview`	View PCB layout
`atopile: Open 3D Model Preview`	View 3D rendering
`atopile: Generate Manufacturing Data`	Generate manufacturing data
`atopile: Package Explorer`	Browse available packages
`atopile: Restart Server`	Restart language server
`atopile: Setup LLM rules & MCP`	Configure AI assistance

🎯 Workspace Features

The extension provides a dedicated atopile activity bar with:

Project Explorer: Navigate your module hierarchy
Quick Actions: Create projects, add packages, build
Examples: Access sample projects and tutorials

🔧 Requirements

VS Code: Version 1.78.0 or later
Python Extension: Required for language server
Git Extension: Recommended for version control

🐛 Troubleshooting

Language Server Issues

If you encounter problems with syntax highlighting or IntelliSense:

Run "atopile: Restart Server" from Command Palette
Check Output panel → atopile for error messages
Verify atopile installation: ato --version

Build Errors

Ensure your project has a valid ato.yaml file
Check that all dependencies are installed
Review build output in the integrated terminal

Missing Features

Verify the extension is activated (check status bar)
Try reloading the window (Ctrl+Shift+P → "Developer: Reload Window")

📚 Resources

Documentation: docs.atopile.io
Package Registry: packages.atopile.io
GitHub Repository: github.com/atopile/atopile
Community: Join our Discord or discussions

🛠️ Development

Starting the Dev Server

The extension UI is built with React and requires two servers running together:

Python Backend (port assigned by ato serve backend) - FastAPI server for project/build data
Vite Dev Server (port 5173) - React hot-reload development server

Quick Start (Recommended)

Use the provided startup script that handles everything (requires DASHBOARD_PORT set):

cd src/ui-server
./dev.sh

This will:

Kill any existing processes on the required ports
Start the Python backend
Start Vite with hot reloading
Show you URLs for all services

Press Ctrl+C to stop all servers.

Custom Workspace Paths

You can specify custom workspace paths to scan for projects:

./dev.sh /path/to/your/project /another/project

By default, it uses the atopile repo and ../packages as workspaces.

Manual Startup

If you need to run servers individually:

# Terminal 1: Python backend
ato serve backend --workspace "$(pwd)"

# Terminal 2: Vite
cd src/ui-server
npm run dev

Accessing the UI

Once running, open http://localhost:5173 in your browser to see the development UI.

Project Structure

src/vscode-atopile/
├── src/                    # Extension TypeScript source
│   ├── extension.ts        # Main extension entry point
│   ├── common/             # Shared utilities
│   │   ├── findbin.ts      # Binary detection & UV management
│   │   ├── lspServer.ts    # LSP client lifecycle
│   │   ├── appState-ws-standalone.ts  # WebSocket state sync
│   │   └── settings.ts     # VS Code settings
│   └── ui/                 # VS Code webview integration
├── docs/
│   └── ARCHITECTURE.md     # Developer architecture docs
└── README.md

src/ui-server/
├── src/                    # React components + hooks
├── index.html              # Dev entry (sidebar + log viewer)
├── sidebar.html            # Sidebar entry
├── log-viewer.html         # Log viewer entry
└── dev.sh                  # Dev environment startup script

Architecture Documentation

For detailed information about how the extension works internally, see:

docs/ARCHITECTURE.md - Component architecture, event flows, and state management

🤝 Contributing

Found a bug or want to contribute?

Issues: Report bugs
Code: Submit PRs
Docs: Help improve documentation

📄 License

This extension is licensed under the MIT License.

Happy designing! 🚀⚡

Design electronics like software - version controlled, modular, and validated.