---
name: molecule-breakout-board-creator
description: Create breakout board designs for electronic components (ICs, modules, sensors).
  Auto-generates a breakout PCB that exposes all chip pins to header rows with proper decoupling.
  Use when user asks to "create a breakout board", "breakout for STM32", "make a dev board",
  "generate breakout PCB", or "breakout layout for [component]".
---

# Molecule Breakout Board Creator

Generate breakout board designs for any electronic component — place the chip at center,
route all pins to edge headers, add power decoupling, and output as an Adom molecule
with symbol, footprint, 3D model, and interactive viewer.

## When to Use

- User asks to create a breakout board for any IC, module, or sensor
- User wants a dev board layout for a specific component
- A wiki component page needs its breakout board section populated
- User asks to "break out" a chip or expose its pins

## Prerequisites

Before creating a breakout board, ensure the target component has:
1. **A symbol** — created via `symbol-creator` skill, or look up in wiki
2. **A footprint** — created via `footprint-creator` skill, or look up in wiki
3. **Pin information** — from datasheet, JLCPCB, or existing symbol metadata

If any are missing, create them first using the respective skills.

## Workflow

### Step 1: Gather Component Info

Collect the target component's specifications:
- Component name and manufacturer
- Package type and pin count
- Pin names, functions, and electrical types (from symbol metadata or datasheet)
- Power pins (VCC/VDD, GND) and their voltage levels

Check for existing data:
```
# Check wiki for existing symbol/footprint
wiki_search({ query: "STM32F103C8T6" })

# Check if symbol already exists
ls /home/adom/project/project-content/schematics/symbols/STM32F103C8T6/

# Check JLCPCB for component data
jlcpcb_search({ query: "STM32F103C8T6" })
```

### Step 2: Design the Breakout Layout

Generate a breakout specification based on the component:

**Board sizing rules:**
- Width = max(component_width + 20mm, pin_rows * pitch + 10mm)
- Height = max(component_height + 30mm, pin_columns * pitch + 10mm)
- Minimum board size: 30mm x 30mm
- Round up to nearest 2mm increment

**Pin placement rules:**
- IC/module placed at board center
- All pins routed straight out to 2.54mm-pitch header rows on board edges
- Left-side IC pins → left header row
- Right-side IC pins → right header row
- Top/bottom IC pins → distributed to nearest edge
- Power pins (VCC, GND) duplicated to all 4 corners for easy access

**Decoupling capacitor rules:**
- One 100nF ceramic cap per VCC/VDD pin, placed within 3mm
- One 10uF bulk cap per power rail, near board edge
- GND via near each decoupling cap

### Step 3: Generate Breakout Specification JSON

Create a breakout spec file:

```json
{
  "name": "STM32F103C8T6_Breakout",
  "version": "v1",
  "component": {
    "name": "STM32F103C8T6",
    "manufacturer": "STMicroelectronics",
    "package": "LQFP-48",
    "pinCount": 48
  },
  "board": {
    "width_mm": 50,
    "height_mm": 60,
    "cornerRadius_mm": 1,
    "mountingHoles": true,
    "headerPitch_mm": 2.54
  },
  "powerRails": [
    { "name": "3V3", "voltage": 3.3, "pins": ["VDD_1", "VDD_2", "VDD_3", "VDDA"] },
    { "name": "GND", "voltage": 0, "pins": ["VSS_1", "VSS_2", "VSS_3", "VSSA"] }
  ],
  "decoupling": [
    { "value": "100nF", "package": "0402", "perPin": true, "rails": ["3V3"] },
    { "value": "10uF", "package": "0805", "perRail": true, "rails": ["3V3"] }
  ],
  "pinMapping": [
    { "icPin": "PA0", "function": "GPIO/ADC", "side": "left", "row": 0 },
    { "icPin": "PA1", "function": "GPIO/ADC", "side": "left", "row": 1 }
  ]
}
```

### Step 4: Generate Output Files

Create the molecule directory structure:

```
/home/adom/project/molecules/adom/COMPONENT_Breakout/
  metadata.json
  v1/
    COMPONENT_Breakout_symbol.json    # Board-level symbol (all header pins)
    COMPONENT_Breakout_footprint.json # PCB footprint with pads
    COMPONENT_Breakout.kicad_pcb      # KiCad PCB file (if KiCad CLI available)
    breakout-spec.json                # The specification from Step 3
    images/
      top.png                         # Board top render
      bottom.png                      # Board bottom render
    optimized/
      model.glb                       # 3D model for viewer
```

**Symbol JSON** — follows the scaffold symbol pattern:
```json
{
  "symbolName": "STM32F103C8T6_Breakout",
  "pins": [
    {
      "name": "PA0",
      "edge": "left",
      "position": [0, 0, 0],
      "orientation": "left",
      "originalPadDetails": {
        "finalName": "PA0",
        "holeType": "medium",
        "holeSubtype": "contact",
        "drill": 1.0
      }
    }
  ]
}
```

**Footprint JSON** — follows the scaffold footprint pattern:
```json
{
  "boardName": "STM32F103C8T6_Breakout",
  "boardDimensions": { "width": 50, "height": 60 },
  "machinePins": [
    { "name": "MH1", "packageName": "MOUNTING_HOLE", "drillDiameter": 3.2, "position": {"x": 3, "y": 3} },
    { "name": "MH2", "packageName": "MOUNTING_HOLE", "drillDiameter": 3.2, "position": {"x": 47, "y": 3} },
    { "name": "MH3", "packageName": "MOUNTING_HOLE", "drillDiameter": 3.2, "position": {"x": 3, "y": 57} },
    { "name": "MH4", "packageName": "MOUNTING_HOLE", "drillDiameter": 3.2, "position": {"x": 47, "y": 57} }
  ],
  "contacts": [
    { "name": "PA0", "elementName": "J1-1", "packageName": "HEADER_2P54", "drillDiameter": 1.0, "position": {"x": 2.54, "y": 10} }
  ]
}
```

### Step 5: Generate Interactive Viewer

Create a 2D interactive HTML viewer (self-contained, no external deps):
- Board outline with rounded corners
- IC package silhouette at center
- Header pin rows on edges with labels
- Color-coded by signal type:
  - Power (VCC): `#f85149` (red)
  - Ground: `#3fb950` (green)
  - GPIO: `#58a6ff` (blue)
  - Analog: `#d29922` (gold)
  - Communication (SPI/I2C/UART): `#bc8cff` (purple)
  - Other: `#8b949e` (gray)
- Pan and zoom via mouse
- Hover shows pin name, function, and IC pin mapping
- Dark theme matching Hydrogen (`#0d1117` background)

### Step 6: Display in Gallia Viewer

```
# Display 3D model (if available)
gv_3d_display({ glb_path: "/path/to/model.glb", title: "STM32F103 Breakout" })

# Display 2D viewer
gv_display_file({ path: "/path/to/breakout-2d.html", title: "STM32F103 Breakout - 2D" })
```

### Step 7: Update Wiki (if wiki service running)

```
# Add or update the breakout section on the component's wiki page
wiki_edit_page({
  type: "component",
  slug: "stm32f103c8t6",
  field: "content",
  content: "... updated content with breakout board section ..."
})
```

## Signal Type Classification

Classify each pin for color coding:

| Signal Type | Color | Examples |
|-------------|-------|---------|
| Power | Red `#f85149` | VCC, VDD, VBAT |
| Ground | Green `#3fb950` | GND, VSS, AGND |
| GPIO | Blue `#58a6ff` | PA0, PB1, GPIO4 |
| Analog | Gold `#d29922` | ADC_IN, DAC_OUT |
| Communication | Purple `#bc8cff` | SPI_MOSI, I2C_SDA, UART_TX |
| Clock/Reset | Cyan `#00b8b0` | XTAL, NRST, CLK |
| Debug | Orange `#f0883e` | SWDIO, SWCLK, JTAG |
| NC/Reserved | Gray `#8b949e` | NC, RESERVED |

## Board Design Templates

### Small IC (< 20 pins, QFN/SSOP/SOT)
- Board: 30mm x 40mm
- Single row headers on left and right
- 2 mounting holes (diagonal corners)

### Medium IC (20-64 pins, LQFP/QFP)
- Board: 50mm x 60mm
- Dual row headers on left and right
- 4 mounting holes (all corners)

### Large IC (64+ pins, BGA/LQFP-100+)
- Board: 70mm x 80mm
- Quad row headers on all 4 sides
- 4 mounting holes + additional mid-edge holes

### Module (ESP32, etc.)
- Board: module_width + 15mm x module_height + 30mm
- Headers match module pin spacing
- Antenna keepout zone marked
- USB/programming header at board edge

## Example: Complete STM32F103 Breakout

```
User: Create a breakout board for the STM32F103C8T6

Steps:
1. Look up STM32F103C8T6 — 48-pin LQFP, Cortex-M3
2. Get pin data from existing symbol or datasheet
3. Use "Medium IC" template: 50x60mm board
4. Map 48 pins to left/right headers (24 per side)
5. Add 4x 100nF caps (3 VDD + 1 VDDA)
6. Add 1x 10uF bulk cap
7. Add 8MHz crystal + 2x 20pF load caps (optional)
8. Add SWD debug header (4-pin: SWDIO, SWCLK, GND, 3V3)
9. Generate symbol, footprint, 3D model, 2D viewer
10. Display in Gallia Viewer
11. Save as molecule: /home/adom/project/molecules/adom/STM32F103C8T6_Breakout/
```