emc

What this skill does

# EMC Pre-Compliance Skill

Automated EMC risk analysis for KiCad PCB designs. Identifies the most common causes of EMC test failures using geometric rule checks, analytical emission formulas, and optional SPICE simulation.

**This is a risk analyzer, not a compliance predictor.** It catches ~70% of common EMC design mistakes before fabrication. It cannot guarantee FCC/CISPR compliance — only a calibrated measurement in an accredited lab can do that. But it can reduce the first-spin failure rate from ~50% toward ~20-30%, potentially saving $5K-$50K per avoided board respin.

## Related Skills

| Skill | Purpose |
|-------|---------|
| `kicad` | Schematic/PCB analysis — produces the analyzer JSON this skill consumes |
| `spice` | SPICE simulation — provides simulator backend for SPICE-enhanced PDN/filter checks |

**Handoff guidance:** Run the `kicad` skill's `analyze_schematic.py` and `analyze_pcb.py` first — this skill consumes their JSON output. Use `--full` on the PCB analyzer for best results (enables per-track coordinates for ground plane crossing, edge proximity, and return path checks). During a design review, run EMC analysis after the schematic/PCB analyzers and SPICE simulation, then incorporate EMC findings into the report.

## Requirements

- **Python 3.8+** — stdlib only, no pip dependencies
- **Schematic analyzer JSON** — from `analyze_schematic.py --output`
- **PCB analyzer JSON** — from `analyze_pcb.py --full --output` (recommended with `--full`)
- **SPICE simulator** *(optional)* — ngspice, LTspice, or Xyce for SPICE-enhanced PDN/filter checks. Auto-detected. Without one, analytical models run unchanged.

## Workflow

### Step 1: Run the analyzers

```bash
python3 <kicad-skill-path>/scripts/analyze_schematic.py design.kicad_sch --analysis-dir analysis/
python3 <kicad-skill-path>/scripts/analyze_pcb.py design.kicad_pcb --full --analysis-dir analysis/
```

### Step 2: Run EMC analysis

Point `--schematic` and `--pcb` at the current run's JSONs and pass
`--analysis-dir analysis/` so `emc.json` co-locates with them and gets tracked
in the manifest:

```bash
# Recommended: integrate into the current run
python3 <skill-path>/scripts/analyze_emc.py \
    --schematic analysis/<run_id>/schematic.json \
    --pcb analysis/<run_id>/pcb.json \
    --analysis-dir analysis/

# One-off JSON (bypasses the cache)
python3 <skill-path>/scripts/analyze_emc.py --schematic schematic.json --pcb pcb.json --output emc.json

# SPICE-enhanced (improved PDN and filter accuracy)
python3 <skill-path>/scripts/analyze_emc.py --schematic schematic.json --pcb pcb.json --spice-enhanced

# Select target standard
python3 <skill-path>/scripts/analyze_emc.py --schematic schematic.json --pcb pcb.json --standard cispr-class-b

# Select target market (sets all applicable standards)
python3 <skill-path>/scripts/analyze_emc.py --schematic schematic.json --pcb pcb.json --market eu

# Filter by severity
python3 <skill-path>/scripts/analyze_emc.py --schematic schematic.json --pcb pcb.json --severity high

# Human-readable text output
python3 <skill-path>/scripts/analyze_emc.py --schematic schematic.json --pcb pcb.json --text
```

### Step 3: Interpret results

Read the JSON report and incorporate findings into the design review. Each finding has a severity, rule ID, description, and actionable recommendation. See "Interpreting Results" below.

## What Gets Checked

44 rule IDs across 18 categories. Each rule has a specific threshold, rationale, and source citation — see `references/pcb-emc-rules.md` for full details.

| Category | Rules | What it detects |
|----------|-------|-----------------|
| **Ground plane** | GP-001 to GP-005 | Signal crossing voids, zone fragmentation, missing ground planes, low fill ratio, multiple ground domains |
| **Decoupling** | DC-001 to DC-003 | Cap too far from IC, IC with no decoupling cap, cap too far from via |
| **I/O filtering** | IO-001, IO-002 | Connector without filtering, insufficient ground pins |
| **Switching EMC** | SW-001 to SW-003 | Harmonic overlap, switching node copper area, input cap loop area |
| **Clock routing** | CK-001 to CK-003 | Clock on outer layer, long trace, clock near connector |
| **Via stitching** | VS-001 | Ground via spacing exceeds λ/20 at highest frequency |
| **Stackup** | SU-001 to SU-003 | Adjacent signal layers, signal far from reference plane, thin interplane capacitance |
| **Diff pair** | DP-001 to DP-004 | Intra-pair skew vs protocol limits, CM radiation, reference plane change, outer layer routing |
| **Board edge** | BE-001 to BE-003 | Signal near edge, incomplete ground pour ring, connector area stitching |
| **PDN impedance** | PD-001 to PD-004 | Anti-resonance peaks, distributed rail impedance at IC load points, cross-rail coupling from downstream switching regulators |
| **Return path** | RP-001 | Layer transition via without nearby ground stitching via |
| **Crosstalk** | XT-001 | 3H spacing violation, aggressor-victim pairs |
| **EMI filter** | EF-001, EF-002 | Filter cutoff too close to switching frequency (analytical or SPICE insertion loss) |
| **ESD path** | ES-001, ES-002 | TVS too far from connector, insufficient ground vias near TVS |
| **Thermal-EMC** | TH-001, TH-002 | MLCC DC bias derating (SRF shift), ferrite near heat source |
| **Shielding** | SH-001 | Connector aperture slot resonance near emission source |
| **Emission estimates** | EE-001, EE-002 | Board cavity resonance, switching harmonic envelope |

**Advisory outputs** (not findings):
- **Pre-compliance test plan** — frequency band prioritization, interface risk ranking, near-field probe points
- **Regulatory coverage** — market-to-standards mapping, coverage matrix (what the tool checks vs what requires lab testing)

## Output Format

```json
{
  "summary": {
    "total_checks": 42,
    "critical": 2, "high": 5, "medium": 8, "low": 12, "info": 15,
    "emc_risk_score": 73
  },
  "target_standard": "fcc-class-b",
  "findings": [
    {
      "category": "ground_plane",
      "severity": "CRITICAL",
      "rule_id": "GP-001",
      "title": "Signal crosses ground plane void",
      "description": "Net SPI_CLK crosses a 3.2mm gap in GND on In1.Cu",
      "components": ["U3", "U7"],
      "nets": ["SPI_CLK"],
      "recommendation": "Route around the gap, or fill the void"
    }
  ],
  "per_net_scores": [
    {"net": "SPI_CLK", "score": 67, "finding_count": 3, "rules": ["GP-001", "CK-001", "BE-001"]}
  ],
  "test_plan": {
    "frequency_bands": [{"band": "30-88 MHz", "risk_level": "high", "source_count": 12}],
    "interface_risks": [{"connector": "J1", "protocol": "USB", "risk_score": 8}],
    "probe_points": [{"ref": "L1", "x": 45.2, "y": 32.1, "reason": "switching inductor"}]
  },
  "regulatory_coverage": {
    "market": "us",
    "applicable_standards": ["FCC Part 15 Class B"],
    "coverage_matrix": [{"standard": "...", "coverage": "partial", "note": "..."}]
  }
}
```

### Severity Levels

| Severity | Meaning | Action |
|----------|---------|--------|
| **CRITICAL** | Almost certain to cause EMC failure | Must fix before fabrication |
| **HIGH** | Very likely to cause issues | Strongly recommend fixing |
| **MEDIUM** | May cause issues depending on specifics | Review and assess |
| **LOW** | Minor risk, good practice | Fix if convenient |
| **INFO** | Informational — frequencies, estimates | Useful for lab prep |

### Risk Score

Each rule ID contributes at most 3 findings to the score (worst severity first). This prevents per-net rules like GP-001 from saturating the score on 2-layer boards. All findings are still reported — only the score is capped.

`penalty = sum(worst 3 per rule × severity weight)`, `score = max(0, 100 - penalty)`. Scores below 50 indicate significant EMC risk.

## Interpreting Results

**Ground plane findings** — Any CRITICAL finding (signal crossing a void) is almost always a real problem. Fix unconditionally.

**Decoupling findings** — Distance-based findings have moderate false positive rates. A