circuit-synth

What this skill does

# Circuit-Synth: AI-Assisted PCB Design

Professional circuit design using Python + KiCad + AI. Define circuits in code, leverage pre-made patterns, and generate manufacturing-ready outputs.

**Tool Reference:** This skill uses [circuit-synth](https://github.com/circuit-synth/circuit-synth), a Python library for programmatic PCB design with KiCad integration.

**Additional Resources:**
- `reference.md` - Quick reference for commands, patterns, and workflows
- [Official Documentation](https://circuit-synth.readthedocs.io)

## What is Circuit-Synth?

Circuit-synth brings software engineering practices to hardware design:
- Define circuits in Python instead of GUI clicking
- Hierarchical design with modular subcircuits
- Version control friendly (text-based definitions)
- AI-accelerated design workflows
- Professional KiCad output (.kicad_pro, .kicad_sch, .kicad_pcb)
- Manufacturing exports (BOM, Gerbers, PDF schematics)

## Quick Start (60 seconds)

```python
# 1. Install
uv add circuit-synth reportlab

# 2. Create circuit (circuits/my_board.py)
from circuit_synth import circuit, Component, Net

@circuit(name="MyBoard")
def my_circuit():
    vcc = Net('VCC')
    gnd = Net('GND')

    led = Component(
        symbol="Device:LED",
        ref="D",
        value="Red",
        footprint="LED_SMD:LED_0805_2012Metric"
    )

    res = Component(
        symbol="Device:R",
        ref="R",
        value="330R",
        footprint="Resistor_SMD:R_0805_2012Metric"
    )

    # Connect: VCC -> Resistor -> LED -> GND
    res["1"] += vcc
    res["2"] += led["A"]
    led["K"] += gnd

if __name__ == "__main__":
    import os
    os.makedirs("circuits", exist_ok=True)
    my_circuit()

# 3. Generate
# uv run python circuits/my_board.py

# 4. Open in KiCad
# kicad circuits/MyBoard/MyBoard.kicad_pro
```

**That's it!** For advanced usage, see sections below or check `reference.md`.

## When to Use This Skill

Use circuit-synth when:
- Creating new PCB designs from scratch
- Generating circuits from natural language descriptions
- Converting hardware documentation/pinouts into formal schematics
- Reverse-engineering existing hardware into KiCad format
- Searching for components with real-time stock/pricing
- Designing with pre-made manufacturing-ready patterns
- Producing manufacturing outputs (BOM, Gerbers, PDF)

## When NOT to Use This Skill

Skip circuit-synth when:
- User just wants schematic symbols/footprints without circuit design
- Working with non-KiCad tools (Altium, Eagle, etc.)
- Project requires Python < 3.12
- Simple one-off circuit not worth the setup

## Installation and Setup

### Quick Start Installation

**Check if already installed:**
```bash
pip list | grep circuit-synth
```

**If not installed:**

In existing Python project (has `pyproject.toml`):
```bash
uv add circuit-synth
```

In non-Python project or new setup:
```bash
uv init --bare        # Creates pyproject.toml
uv add circuit-synth
```

Fallback with pip:
```bash
pip install circuit-synth
```

**Recommended: Install reportlab for PDF schematic generation:**
```bash
uv add reportlab
# or
pip install reportlab
```

Without reportlab, you'll see warnings and won't be able to generate PDF schematics.

That's it! No need to ask permission - just provide these commands when needed.

### Python Version Requirement

Circuit-synth requires **Python 3.12 or higher**.

Check Python version:
```bash
python --version
# or
python3 --version
```

If Python < 3.12, inform user and ask if they want to proceed with installation anyway or upgrade Python first.

### Common Installation Issues

| Error | Fix |
|-------|-----|
| `No module named 'circuit_synth'` | Run `uv add circuit-synth` or `pip install circuit-synth` |
| `No pyproject.toml found` | Run `uv init --bare` first, then `uv add circuit-synth` |
| `Python version too old` | Requires Python 3.12+, upgrade with pyenv or conda |

## Common Pin Naming Issues

**Most common source of errors!** When you get `Pin 'XXX' not found` errors, the error message shows available pins. Use those names.

### Quick Reference Table

| IC Family | Common Wrong Names | Correct Names | Example |
|-----------|-------------------|---------------|---------|
| 74xx Latches (373, 573) | 1D, 1Q, 2D, 2Q | D0-D7, O0-O7 | D0 for data in, O0 for output |
| 74xx Buffers (245) | DIR, OE | A->B, CE | Direction control renamed |
| 74xx Decoders (138, 139) | 1G, 1A0, 1Y0 | E, A0, O0 | Single decoder uses generic names |
| Polarized Caps | +, - | 1, 2 | Pin 1 is positive, pin 2 negative |
| Generic symbols | Named pins | 1, 2, 3... | Use pin numbers for placeholders |

**How to fix:** When you see the error, it lists available pins - use those exact names in your code.

```python
# Error says: Available: 'D0', 'D1', ..., 'O0', 'O1', ...
# Wrong:
latch["1D"] += data_in  # ❌

# Correct:
latch["D0"] += data_in  # ✓
```

## Incremental Development (IMPORTANT!)

**Don't write the whole circuit at once!** Build and test incrementally to catch pin name errors early.

### Step 1: Minimal Test (1-2 components)

Start with just power and one IC:

```python
from circuit_synth import circuit, Component, Net

@circuit(name="Test")
def test_circuit():
    vcc = Net('VCC_5V')
    gnd = Net('GND')

    # Test one IC first
    ic = Component(
        symbol="74xx:74HC373",  # Or whatever you need
        ref="U1",
        value="Test",
        footprint="Package_DIP:DIP-20_W7.62mm"
    )

    ic["VCC"] += vcc
    ic["GND"] += gnd
    ic["D0"] += Net('DATA0')  # Try connecting one pin
    ic["O0"] += Net('OUT0')

if __name__ == "__main__":
    c = test_circuit()
    c.generate_kicad_project(project_name="Test")
```

Run: `uv run python circuits/test.py`

### Step 2: Fix Pin Names from Error Messages

If it fails, read the error:
```
ComponentError: Pin 'D0' not found in U1 (74xx:74HC373).
Available: 'D0', 'D1', 'D2', ...
```

Use the available names shown in the error.

### Step 3: Add More Components Gradually

Once one IC works, add 2-3 more at a time, testing after each addition.

## Where Are My Files?

After running `circuit_obj.generate_kicad_project(project_name="MyBoard")`:

```
your-project/
└── circuits/                ← **CIRCUIT FOLDER**
    ├── your_circuit.py      ← Your Python circuit definition
    └── MyBoard/             ← **GENERATED HERE**
        ├── MyBoard.kicad_pro  ← Open this in KiCad
        ├── MyBoard.kicad_sch
        ├── MyBoard.json
        └── MyBoard.net
```

**Open it:** `kicad circuits/MyBoard/MyBoard.kicad_pro`

The `circuits/` folder keeps all circuit definitions and generated KiCad projects organized together.

## Common Errors & Quick Fixes

| Error | Cause | Fix |
|-------|-------|-----|
| `Pin 'X' not found` | Wrong pin name | Use exact names from error message |
| `Symbol 'XXX' not found` | Symbol doesn't exist in KiCad libraries | Try similar symbol (74HC139→74LS139) or use generic placeholder |
| `missing 1 required positional argument: 'project_name'` | Forgot parameter | Add `project_name="YourBoard"` |
| `No module named 'circuit_synth'` | Not installed | Run `uv add circuit-synth` |
| `No pyproject.toml found` | Not in uv project | Run `uv init --bare` first |

## Placeholder-First Approach for Custom/Unknown ICs

**Fast track for reverse-engineering or using ICs without KiCad symbols:**

### 1. Use Generic Symbols as Placeholders

Don't waste time searching for exact symbols. Start with placeholders:

```python
# Unknown or custom IC? Use Device:C (capacitor) as 2-pin placeholder
custom_ic = Component(
    symbol="Device:C",  # Quick 2-pin placeholder
    ref="U1",
    value="ActualPartNumber",  # Document the real part
    footprint="Package_DIP:DIP-20_W7.62mm"  # Use actual footprint
)

# Connect using pin numbers
custom_ic["1"] += vcc
custom_ic["2"] += gnd

# Document actual connections in comments for later
# Pin 1: VCC, Pin 2: GND, Pin 3: DATA0, ... etc
```

### 2. Generate Schematic Quickly

- Get project structure in place
- See component layo