hashgraph-online/awesome-codex-plugins / plugins/aklofas/kicad-happy/skills/kicad
kicad
VerifiedAnalyze KiCad projects and PDF schematics: schematics, PCB layouts, Gerbers, footprints, symbols, netlists, and design rules. Reviews designs for bugs, traces nets, cross-references schematic to PCB, extracts BOM data, checks DRC/ERC, DFM, power trees, and regulator circuits. Every finding carries a confidence label and evidence source with trust_summary rollup. Analyzes PDF schematics from dev boards, reference designs, eval kits, and datasheets. Supports KiCad 5–10. Use whenever the user mentions .kicad_sch, .kicad_pcb, .kicad_pro, PCB design review, schematic analysis, PDF schematics, reference designs, Gerber files, DRC/ERC, netlist issues, BOM extraction, signal tracing, power budget, DFM, or wants to understand, debug, compare, or review any hardware design. Also for "check my board", "review before fab", "what's wrong with my schematic", "is this ready to order", "check my power supply", "verify this circuit", OSHWA certification readiness, or any electronics/PCB design question.
references/manual-pcb-parsing.md
View on GitHub# Manual PCB Parsing (Script Fallback)
When `analyze_pcb.py` fails (unsupported format, newer KiCad version, corrupted file), fall back to direct file parsing. This is more expensive (reading raw S-expressions) but always works as long as the file is valid KiCad.
## Table of Contents
1. [When to Use Manual Parsing](#when-to-use-manual-parsing)
2. [Performance: Line-by-Line Parsing](#performance-line-by-line-parsing)
3. [Net Extraction](#net-extraction)
4. [Footprint Extraction](#footprint-extraction)
5. [Track and Via Extraction](#track-and-via-extraction)
6. [Zone Extraction](#zone-extraction)
7. [Board Outline](#board-outline)
8. [Connectivity Analysis](#connectivity-analysis)
9. [KiCad 5 Legacy Format](#kicad-5-legacy-format)
10. [Validation Methodology](#validation-methodology)
---
## When to Use Manual Parsing
Use manual parsing when:
- `analyze_pcb.py` crashes or returns unexpected results on a file you know is valid
- The PCB is from a KiCad version newer than the script supports
- You need to validate script output against raw file data
- You need to extract data the script doesn't provide (e.g., specific filled_polygon vertices)
- The file is partially corrupt but still readable
Always try the script first — it handles coordinate transforms, via classification, connectivity analysis, and 25+ analysis stages automatically.
---
## Performance: Line-by-Line Parsing
KiCad PCB files can be 20K-70K+ lines, with zones containing thousands of polygon vertices. **Never use full-content regex with `re.DOTALL` on the entire file** — it causes catastrophic backtracking on large files. Use line-by-line state-machine parsing instead for top-level extraction. `re.DOTALL` is acceptable on small, pre-extracted blocks (e.g., a single footprint or pad block) where the input size is bounded.
### Buffer Accumulation Pattern
For simple blocks (segments, vias):
```python
import re
with open(pcb_file) as f:
lines = f.readlines()
segments = []
buf = None
for line in lines:
if '\t(segment' in line:
buf = line
elif buf:
buf += line
if line.strip() == ')':
m_s = re.search(r'\(start\s+([\d.-]+)\s+([\d.-]+)\)', buf)
m_e = re.search(r'\(end\s+([\d.-]+)\s+([\d.-]+)\)', buf)
m_w = re.search(r'\(width\s+([\d.]+)\)', buf)
m_l = re.search(r'\(layer\s+"([^"]+)"\)', buf)
# KiCad ≤9: (net 7), KiCad 10: (net "NetName")
m_n = re.search(r'\(net\s+(\d+)\)', buf) or re.search(r'\(net\s+"([^"]+)"\)', buf)
if all([m_s, m_e, m_w, m_l, m_n]):
net_val = m_n.group(1)
segments.append({
'sx': float(m_s.group(1)), 'sy': float(m_s.group(2)),
'ex': float(m_e.group(1)), 'ey': float(m_e.group(2)),
'w': float(m_w.group(1)), 'layer': m_l.group(1),
'net': int(net_val) if net_val.isdigit() else net_val
})
buf = None
```
### Depth-Tracked Parsing
For nested blocks (footprints, zones), track parenthesis depth:
```python
footprints = {}
current_fp = None
fp_text = []
depth = 0
for line in lines:
if line.startswith('\t(footprint '):
current_fp = True
fp_text = [line]
depth = line.count('(') - line.count(')')
elif current_fp:
fp_text.append(line)
depth += line.count('(') - line.count(')')
if depth <= 0:
block = ''.join(fp_text)
# Extract data from the bounded block (regex is safe here)
m_ref = re.search(r'\(property\s+"Reference"\s+"([^"]+)"', block)
m_at = re.search(r'\n\t\t\(at\s+([\d.-]+)\s+([\d.-]+)(?:\s+([\d.-]+))?\)', block)
if m_ref and m_at:
ref = m_ref.group(1)
footprints[ref] = {
'x': float(m_at.group(1)),
'y': float(m_at.group(2)),
'angle': float(m_at.group(3)) if m_at.group(3) else 0,
'block': block
}
current_fp = None
```
---
## Net Extraction
**KiCad ≤9:** Net declarations are single-line entries near the top of the file:
```python
nets = {}
for line in lines:
m = re.match(r'\s*\(net\s+(\d+)\s+"([^"]*)"\)', line)
if m:
nets[int(m.group(1))] = m.group(2)
```
Net 0 is always the unconnected net (empty name).
**KiCad 10:** No net declarations section. Nets are referenced by name string directly in pads, tracks, vias, and zones. Collect unique net names from those elements instead.
Power nets typically have names like `GND`, `+3V3`, `+5V`, `VBUS`.
---
## Footprint Extraction
After extracting footprint blocks with depth-tracking (see above), split each block into its `(pad ...)` sub-blocks the same way and read every field from that pad's own text. A single regex over the whole footprint block is not safe: a pad with no `(net ...)` would take the next pad's net.
```python
def pad_blocks(block):
"""Yield each top-level (pad ...) sub-block of a footprint block."""
start = None
depth = 0
in_str = False
for i, ch in enumerate(block):
if ch == '"':
in_str = not in_str
elif in_str:
continue
elif ch == '(':
if start is None and block.startswith('(pad', i):
start, depth = i, 0
depth += 1 if start is not None else 0
elif ch == ')' and start is not None:
depth -= 1
if depth == 0:
yield block[start:i + 1]
start = None
pads = []
for ref, fp in footprints.items():
for pb in pad_blocks(fp['block']):
m_pad = re.match(r'\(pad\s+"([^"]+)"\s+(\w+)', pb)
m_at = re.search(r'\(at\s+([\d.-]+)\s+([\d.-]+)', pb)
m_size = re.search(r'\(size\s+([\d.-]+)\s+([\d.-]+)\)', pb)
# KiCad <=9: (net 5 "+3V3"), KiCad 10: (net "+3V3"); no (net ...) = unconnected
m_net = re.search(r'\(net\s+(?:\d+\s+)?"([^"]*)"', pb)
if m_pad and m_at and m_size:
pads.append((ref, m_pad.group(1), m_pad.group(2),
float(m_at.group(1)), float(m_at.group(2)),
float(m_size.group(1)), float(m_size.group(2)),
m_net.group(1) if m_net else ""))
# pads: (ref, pad_num, type, rel_x, rel_y, size_w, size_h, net_name)
```
### Absolute Pad Positions
Pad coordinates are relative to footprint origin. Transform to board coordinates:
```python
import math
def pad_to_absolute(fp_x, fp_y, fp_angle_deg, pad_rx, pad_ry):
rad = math.radians(-fp_angle_deg) # KiCad: CW positive in layout
abs_x = fp_x + pad_rx * math.cos(rad) - pad_ry * math.sin(rad)
abs_y = fp_y + pad_rx * math.sin(rad) + pad_ry * math.cos(rad)
return abs_x, abs_y
```
### Key Footprint Fields
| Field | Where | Purpose |
|-------|-------|---------|
| `(property "Reference" "U1")` | Footprint block | Component designator |
| `(property "Value" "STM32F407")` | Footprint block | Component value |
| `(at X Y ANGLE)` | 2nd-level child | Position and rotation |
| `(layer "F.Cu")` | 1st-level child | Board side (F.Cu = front, B.Cu = back) |
| `(attr smd)` | 1st-level child | SMD vs through-hole |
| `(path "/uuid")` | 1st-level child | Link to schematic symbol |
| `(sheetname "Power")` | 1st-level child | Source schematic sheet |
| `(pad ...)` | Nested children | Pads with net assignments |
### Courtyard Extraction
Courtyard shapes define the component's keep-out area:
```python
# From footprint block:
crtyd_lines = re.findall(
r'\(fp_(?:line|rect)\s+\(start\s+([\d.-]+)\s+([\d.-]+)\)\s+'
r'\(end\s+([\d.-]+)\s+([\d.-]+)\).*?'
r'\(layer\s+"[FB]\.CrtYd"\)',
fp['block'], re.DOTALL)
```
Build a bounding box from all courtyard primitives, then transform to absolute coordinates.
---
## Track and Via Extraction
### Tracks (Segments)
See the buffer accumulation pattern above. KiCad 7+ also has `(arc ...)` blocks with `(start)`, `(mid)`, `(end)` for curved tracks.
For arc length calculation:
```python
import math
def arc_length(sx, sy, mx, my, ex, ey):
"""Calculate arc length from start/mid/end points."""
# Find circle center from 3 points
ax, ay = sx - mx, sy - my
bx, by = ex - mx, ey - my
D = 2 * (ax * by - ay * bx)
if abs(D) < 1e-10:
return math.hypot(ex - sx, ey - sy) # Degenerate: straight line
ux = (by * (ax*ax + ay*ay) - ay * (bx*bx + by*by)) / D + mx
uy = (ax * (bx*bx + by*by) - bx * (ax*ax + ay*ay)) / D + my
radius = math.hypot(sx - ux, sy - uy)
# Angle swept from start through mid to end
a1 = math.atan2(sy - uy, sx - ux)
a2 = math.atan2(ey - uy, ex - ux)
am = math.atan2(my - uy, mx - ux)
sweep = (a2 - a1) % (2 * math.pi) # counter-clockwise, start -> end
if (am - a1) % (2 * math.pi) > sweep: # the mid point is on the other way round
sweep = 2 * math.pi - sweep
return radius * sweep
```
### Vias
```python
vias = []
buf = None
for line in lines:
if '\t(via' in line and '(via' in line:
buf = line
elif buf:
buf += line
if line.strip() == ')':
m_at = re.search(r'\(at\s+([\d.-]+)\s+([\d.-]+)\)', buf)
m_sz = re.search(r'\(size\s+([\d.]+)\)', buf)
m_dr = re.search(r'\(drill\s+([\d.]+)\)', buf)
m_ly = re.search(r'\(layers\s+"([^"]+)"\s+"([^"]+)"\)', buf)
# KiCad ≤9: (net 5) with numeric ID; KiCad 10: (net "NetName") with string
m_n = re.search(r'\(net\s+(\d+)\)', buf)
m_nn = re.search(r'\(net\s+"([^"]+)"\)', buf)
via_type = 'through'
if '(via blind' in buf: via_type = 'blind'
elif '(via buried' in buf: via_type = 'buried'
elif '(via micro' in buf: via_type = 'micro'
if all([m_at, m_sz, m_dr]) and (m_n or m_nn):
vias.append({
'x': float(m_at.group(1)), 'y': float(m_at.group(2)),
'size': float(m_sz.group(1)), 'drill': float(m_dr.group(1)),
'type': via_type,
'layers': (m_ly.group(1), m_ly.group(2)) if m_ly else ('F.Cu', 'B.Cu'),
'net': int(m_n.group(1)) if m_n else m_nn.group(1),
'free': '(free yes)' in buf
})
buf = None
```
### Annular Ring Check
```python
for via in vias:
annular_ring = (via['size'] - via['drill']) / 2
if annular_ring < 0.125: # JLCPCB standard minimum
print(f"Annular ring violation: {annular_ring:.3f}mm at ({via['x']}, {via['y']})")
```
---
## Zone Extraction
Zones are the trickiest part — they contain massive `filled_polygon` blocks. For most analyses, extract only the header:
```python
zones = []
in_zone = False
zone_info = {}
for line in lines:
stripped = line.strip()
if re.match(r'\(zone\s*$', stripped) or re.match(r'\(zone\s+\(', stripped):
in_zone = True
zone_info = {}
elif in_zone:
m = re.search(r'\(net\s+(\d+)\)', line)
if m: zone_info['net'] = int(m.group(1))
m = re.search(r'\(net_name\s+"([^"]*)"', line)
if m: zone_info['net_name'] = m.group(1)
m = re.search(r'\(net\s+"([^"]*)"\)', line) # KiCad 10: (net "GND")
if m: zone_info['net_name'] = m.group(1)
m = re.search(r'\(layer\s+"([^"]+)"', line)
if m: zone_info['layer'] = m.group(1)
m = re.search(r'\(priority\s+(\d+)\)', line)
if m: zone_info['priority'] = int(m.group(1))
if '(keepout' in line:
zone_info['is_keepout'] = True
if '(polygon' in line or '(filled_polygon' in line:
zones.append(zone_info)
in_zone = False
```
### Zone Fill Polygon Extraction
Extract filled polygons only when containment tests need them. Select zones by net name and fills by layer; an empty result is not proof that copper is absent. `<skill-path>` is the installed kicad skill directory (as in SKILL.md). This reads fills through the shared parser, so if the parser itself rejects the file, use the line-based zone header above and read the fills by hand. In a KiCad 5 board (zones without `(filled_areas_thickness no)`), KiCad grows each stored fill by half the zone's `min_thickness`, so these polygons are slightly smaller than the copper.
```python
import sys
sys.path.insert(0, '<skill-path>/scripts')
from kicad_core.sexp import parse_file, find_all, get_value
def extract_zone_polygons(pcb_file, zone_net, zone_layer):
"""Return the filled polygons of zones on net name zone_net, one list of (x, y) per fill on zone_layer."""
polygons = []
for zone in find_all(parse_file(pcb_file), 'zone'):
name = get_value(zone, 'net_name') or get_value(zone, 'net')
if str(name) != str(zone_net):
continue
for fill in find_all(zone, 'filled_polygon'):
# KiCad 5 fills carry no (layer): they belong to the zone's own layer
if (get_value(fill, 'layer') or get_value(zone, 'layer')) != zone_layer:
continue
for pts in find_all(fill, 'pts'):
polygons.append([
(float(xy[1]), float(xy[2]))
for xy in find_all(pts, 'xy')
])
return polygons
```
---
## Board Outline
When the shared parser is available, use `pcb.reader.extract_board_outline(parse_file(pcb_file))` for Edge.Cuts geometry and bounds (it returns `edge_count`, `edges`, `bounding_box`, `width_mm`, `height_mm`). For an independent fallback, accumulate complete expressions with quote-aware parenthesis tracking before interpreting them, and include arc extrema in the bounds; endpoints alone are not enough.
---
## Connectivity Analysis
### Unrouted Net Detection
Checking whether a net has *any* routing is insufficient — nets can be partially routed with breaks. A proper connectivity analysis builds a graph per net and checks if all pads are in a single connected component.
#### Algorithm
1. **Extract pad positions** (absolute coordinates) — transform relative pad coords using footprint position/angle
2. **Extract routing elements per net** — segments, vias, and zone filled polygons
3. **Build union-find graph** for each net:
- Union segment endpoints (each segment connects its start and end)
- Union coincident points within ~50µm tolerance on the same copper layer
- Union pad-to-trace (segment endpoint within pad area)
- Union via connections (vias exist on multiple layers)
- Union zone connections (point-in-polygon for filled areas)
4. **Count connected components** among pad points:
- All pads in same component → fully routed
- Multiple components → net has breaks (ratsnest lines)
#### Common False Positives
- ESP32/QFN ground slug pads may appear disconnected if they're just outside the zone fill boundary
- Zone fills may need to be re-poured after component moves
- Nets named `unconnected-(...)` are explicitly marked no-connect — skip these
---
## KiCad 5 Legacy Format
KiCad 5 PCB files use `(module ...)` instead of `(footprint ...)`, and `(fp_text reference ...)` instead of `(property "Reference" ...)`.
### Key Differences
| Modern (KiCad 6+) | Legacy (KiCad 5) |
|--------------------|------------------|
| `(footprint "Lib:Name" ...)` | `(module "Lib:Name" ...)` |
| `(property "Reference" "U1" ...)` | `(fp_text reference "U1" ...)` |
| `(property "Value" "STM32" ...)` | `(fp_text value "STM32" ...)` |
| `(uuid "...")` | `(tstamp HEXID)` |
| Layer numbers: F.Cu=0, B.Cu=2 (KiCad 9-10; KiCad 6-8 use B.Cu=31) | Layer numbers: F.Cu=0, B.Cu=31 |
### Net Classes (KiCad 5 only)
KiCad 5 stores net classes directly in the PCB file:
```
(net_class Default "Default net class"
(clearance 0.2)
(trace_width 0.25)
(via_dia 0.6)
(via_drill 0.3)
(uvia_dia 0.3)
(uvia_drill 0.1)
(add_net "GND")
(add_net "+3V3")
)
```
### Dimension Annotations (KiCad 5)
```
(dimension 50.0
(width 0.12)
(layer "F.SilkS")
(gr_text "50 mm" (at X Y ANGLE) ...)
(feature1 (pts (xy X1 Y1) (xy X2 Y2)))
(feature2 (pts (xy X3 Y3) (xy X4 Y4)))
(crossbar (pts (xy X5 Y5) (xy X6 Y6)))
)
```
---
## Validation Methodology
When verifying analyzer output (or your own manual parse):
### Component Count Validation
1. Count all `(footprint ...)` or `(module ...)` top-level blocks
2. Compare against the analyzer's footprint count — should match exactly
3. Check for `(attr board_only)` or `(attr virtual)` components that may be excluded from counts
### Net Count Validation
1. Count all `(net N "name")` declarations (subtract net 0)
2. Compare against analyzer's net count
3. Spot-check 3-5 nets by finding all pads/segments/vias with that net ID
### Routing Completeness
1. Collect all unique net IDs from pads
2. For each net, check if it has at least one segment, via, or zone
3. Nets with multiple pads but no routing elements are unrouted
4. Nets with routing but disconnected islands need the full union-find analysis
### Known Edge Cases
- **Test points**: Single-pad footprints appear as "unrouted" nets — they only have one endpoint, which is correct
- **Mounting holes**: Non-plated holes (`np_thru_hole`) have no net and should be excluded
- **Board-only components**: Logos, fiducials with `(attr board_only)` may not have nets
- **Zone-only routing**: Some nets (especially GND) are routed entirely through copper pours with no tracks — check zone net assignments
- **Multi-layer zones**: A zone on F.Cu doesn't connect to the same zone on B.Cu unless there are vias between them
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |