Entity Relationship Diagram: Electrical Rules Check (ERC)

Feature: ERC Validation System Version: 1.0 Date: 2024-10-26

---

System Overview

The ERC system validates electrical connectivity and design rules in KiCAD schematics through interconnected validators and data models.

Entity Relationship Diagram

┌─────────────────────────────────────────────────────────────────┐
│                     Schematic                                    │
│  - uuid: str                                                     │
│  - components: ComponentCollection                               │
│  - wires: WireCollection                                         │
│  - labels: LabelCollection                                       │
│  - nets: Dict[str, Net]                                          │
└────────────────────┬────────────────────────────────────────────┘
                     │
                     │ 1:1
                     │
                     ▼
┌─────────────────────────────────────────────────────────────────┐
│              ElectricalRulesChecker                              │
│  - schematic: Schematic                                          │
│  - config: ERCConfig                                             │
│  - validators: List[Validator]                                   │
│  + run_all_checks() -> ERCResult                                 │
│  + run_check(check_type: str) -> List[ERCViolation]              │
└────┬────────┬────────┬────────┬────────┬──────────────────────┘
     │        │        │        │        │
     │ 1:1    │ 1:1    │ 1:1    │ 1:1    │ 1:1
     │        │        │        │        │
     ▼        ▼        ▼        ▼        ▼
┌──────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌──────────┐
│ Pin  │ │Connect │ │Comp    │ │Power │ │Hierarchy │
│Type  │ │ivity   │ │onent   │ │Valid │ │Validator │
│Valid │ │Valid   │ │Valid   │ │ator  │ │          │
│ator  │ │ator    │ │ator    │ │      │ │          │
└──┬───┘ └────┬───┘ └────┬───┘ └──┬───┘ └────┬─────┘
   │          │          │        │          │
   │          │          │        │          │
   │ uses     │ creates  │creates │creates   │ creates
   │          │          │        │          │
   ▼          ▼          ▼        ▼          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      ERCViolation                                │
│  - violation_type: str                                           │
│  - severity: str ("error", "warning", "info")                    │
│  - message: str                                                  │
│  - component_refs: List[str]                                     │
│  - net_name: Optional[str]                                       │
│  - pin_numbers: List[str]                                        │
│  - location: Optional[Point]                                     │
│  - suggested_fix: Optional[str]                                  │
│  - error_code: str                                               │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         │ N:1 collected by
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                       ERCResult                                  │
│  - errors: List[ERCViolation]                                    │
│  - warnings: List[ERCViolation]                                  │
│  - info: List[ERCViolation]                                      │
│  - total_checks: int                                             │
│  - passed_checks: int                                            │
│  - duration_ms: float                                            │
│  + has_errors() -> bool                                          │
│  + summary() -> str                                              │
│  + to_dict() -> Dict                                             │
│  + to_json() -> str                                              │
└─────────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────┐
│                       ERCConfig                                  │
│  - severity_overrides: Dict[str, str]                            │
│  - suppressed_warnings: Set[str]                                 │
│  - custom_rules: List[CustomRule]                                │
│  - pin_conflict_matrix: PinConflictMatrix                        │
│  + set_severity(rule: str, severity: str)                        │
│  + suppress_warning(code: str, component: str)                   │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         │ 1:1 uses
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                   PinConflictMatrix                              │
│  - matrix: Dict[Tuple[str, str], int]                            │
│  + check_connection(pin1: str, pin2: str) -> int                 │
│  + set_rule(pin1: str, pin2: str, severity: int)                 │
│  + get_default_matrix() -> Dict                                  │
└─────────────────────────────────────────────────────────────────┘

Detailed Entity Descriptions

Core Entities

1. ElectricalRulesChecker

Purpose: Main orchestrator for all ERC validation

Attributes:

• schematic: Schematic - The schematic being validated

• config: ERCConfig - Configuration for validation rules

• validators: List[Validator] - All registered validators

Methods:

• run_all_checks() -> ERCResult - Execute all validators

• run_check(check_type: str) -> List[ERCViolation] - Run specific check

• add_validator(validator: Validator) - Register custom validator

Relationships:

• 1:1 with Schematic (validates one schematic)

• 1:1 with ERCConfig (uses one configuration)

• 1:N with Validators (has multiple validators)

• Creates ERCResult (output)

---

2. ERCViolation

Purpose: Represents a single validation violation

Attributes:

• violation_type: str - Category (e.g., “pin_conflict”, “dangling_wire”)

• severity: str - “error”, “warning”, or “info”

• message: str - Human-readable description

• component_refs: List[str] - Affected component references

• net_name: Optional[str] - Affected net name

• pin_numbers: List[str] - Affected pin numbers

• location: Optional[Point] - Schematic coordinates

• suggested_fix: Optional[str] - Recommended fix

• error_code: str - Unique code (e.g., “E001”, “W042”)

Relationships:

• N:1 with ERCResult (many violations in one result)

• Created by Validators

---

3. ERCResult

Purpose: Aggregates all validation results

Attributes:

• errors: List[ERCViolation] - Error-level violations

• warnings: List[ERCViolation] - Warning-level violations

• info: List[ERCViolation] - Info-level violations

• total_checks: int - Total validations performed

• passed_checks: int - Number of passed checks

• duration_ms: float - Execution time

Methods:

• has_errors() -> bool - Quick error check

• summary() -> str - Human-readable summary

• to_dict() -> Dict - JSON-serializable dict

• to_json() -> str - JSON string

• filter_by_severity(severity: str) -> List[ERCViolation]

• filter_by_component(ref: str) -> List[ERCViolation]

Relationships:

• 1:N with ERCViolation (contains many violations)

• Created by ElectricalRulesChecker

---

4. ERCConfig

Purpose: Configuration for validation rules

Attributes:

• severity_overrides: Dict[str, str] - Custom severity levels

• suppressed_warnings: Set[str] - Suppressed warning codes

• custom_rules: List[CustomRule] - User-defined rules

• pin_conflict_matrix: PinConflictMatrix - Pin compatibility matrix

Methods:

• set_severity(rule: str, severity: str) - Override default severity

• suppress_warning(code: str, component: str) - Suppress specific warning

• add_custom_rule(rule: CustomRule) - Add user rule

• load_profile(name: str) - Load rule profile (strict/standard/relaxed)

Relationships:

• 1:1 with ElectricalRulesChecker (configures one checker)

• 1:1 with PinConflictMatrix (defines pin rules)

---

Validator Entities

5. PinTypeValidator

Purpose: Validates pin-to-pin connections

Attributes:

• pin_matrix: PinConflictMatrix - Pin compatibility rules

• schematic: Schematic - Schematic being validated

Methods:

• validate_pin_connections() -> List[ERCViolation]

• check_net_pins(net_name: str) -> List[ERCViolation]

• get_pin_type(component_ref: str, pin_num: str) -> str

Key Validations:

• Output-to-Output conflicts (ERROR)

• Power Output shorts (ERROR)

• Output-to-Power Output (ERROR)

• Unspecified pin warnings (WARNING)

Relationships:

• Uses PinConflictMatrix for rules

• Creates ERCViolation objects

• Accesses Schematic components and nets

---

6. ConnectivityValidator

Purpose: Validates wire connectivity

Attributes:

• schematic: Schematic

• min_connections: int - Minimum connections for valid net

Methods:

• find_dangling_wires() -> List[ERCViolation]

• find_undriven_nets() -> List[ERCViolation]

• find_unconnected_pins() -> List[ERCViolation]

• trace_net(start_point: Point) -> List[Point]

Key Validations:

• Wires with only one endpoint (WARNING)

• Input pins without drivers (WARNING)

• Nets without output pins (WARNING)

Relationships:

• Accesses Schematic wires collection

• Accesses Schematic components collection

• Creates ERCViolation objects

---

7. ComponentValidator

Purpose: Validates component properties

Attributes:

• schematic: Schematic

• reference_pattern: Pattern - Regex for valid references

Methods:

• find_duplicate_references() -> List[ERCViolation]

• validate_component_properties() -> List[ERCViolation]

• check_reference_format(ref: str) -> bool

Key Validations:

• Duplicate reference designators (ERROR)

• Missing values (WARNING)

• Missing footprints (WARNING)

• Invalid reference format (ERROR)

Relationships:

• Accesses Schematic components collection

• Creates ERCViolation objects

---

8. PowerValidator

Purpose: Validates power supply connections

Attributes:

• schematic: Schematic

• power_net_names: Set[str] - Known power net names

Methods:

• validate_power_flags() -> List[ERCViolation]

• check_power_continuity() -> List[ERCViolation]

• find_power_conflicts() -> List[ERCViolation]

• is_power_net(net_name: str) -> bool

Key Validations:

• Power Input without driver (WARNING)

• Missing PWR_FLAG (WARNING)

• Multiple voltage sources (ERROR)

• Power net shorts (ERROR)

Relationships:

• Accesses Schematic nets

• Accesses Schematic components

• Creates ERCViolation objects

---

9. HierarchyValidator

Purpose: Validates hierarchical schematic structure

Attributes:

• schematic: Schematic

• child_schematics: List[Schematic]

Methods:

• validate_sheet_pins() -> List[ERCViolation]

• validate_bus_aliases() -> List[ERCViolation]

• check_hierarchical_labels() -> List[ERCViolation]

Key Validations:

• Sheet pin mismatches (ERROR)

• Hierarchical label mismatches (ERROR)

• Bus alias inconsistency (ERROR)

Relationships:

• Accesses Schematic sheet instances

• May access child schematics

• Creates ERCViolation objects

---

Supporting Entities

10. PinConflictMatrix

Purpose: Defines pin type compatibility rules

Attributes:

• matrix: Dict[Tuple[str, str], int] - Pin type pair → severity

Constants:

• OK = 0 - Connection allowed

• WARNING = 1 - Connection warns

• ERROR = 2 - Connection forbidden

Methods:

• check_connection(pin1_type: str, pin2_type: str) -> int

• set_rule(pin1_type: str, pin2_type: str, severity: int)

• get_default_matrix() -> Dict - KiCAD default matrix

• load_from_file(path: str) - Load custom matrix

Default Matrix (partial):

{
    ("output", "output"): ERROR,
    ("power_output", "power_output"): ERROR,
    ("output", "power_output"): ERROR,
    ("input", "output"): OK,
    ("bidirectional", "output"): OK,
    ("passive", "*"): OK,  # Wildcard
    ("unspecified", "*"): WARNING,
}

Relationships:

• 1:1 with ERCConfig

• Used by PinTypeValidator

---

11. Net

Purpose: Represents an electrical net (extended from existing)

Additional Attributes for ERC:

• drivers: List[Tuple[str, str]] - (component_ref, pin_num) driving net

• loads: List[Tuple[str, str]] - Input pins on net

• power_flags: List[Point] - PWR_FLAG locations

• is_power_net: bool - Detected as power net

Methods:

• has_driver() -> bool - Check if net is driven

• driver_count() -> int - Number of outputs

• is_properly_powered() -> bool - Power Input has Power Output

Relationships:

• N:1 with Schematic (many nets in one schematic)

• Referenced by ERCViolation

---

12. CustomRule (Abstract)

Purpose: Base class for user-defined validation rules

Attributes:

• rule_id: str - Unique identifier

• severity: str - Default severity

• description: str - Human-readable description

Methods:

• validate(schematic: Schematic) -> List[ERCViolation] - Abstract

• get_metadata() -> Dict - Rule information

Relationships:

• N:1 with ERCConfig (multiple rules in config)

• Creates ERCViolation objects

---

Data Flow Diagram

User Code
    │
    ├─> Create/Load Schematic
    │       │
    │       ▼
    │   Schematic Object
    │       │
    ├───────┴──> ElectricalRulesChecker(schematic, config)
    │                   │
    │                   ├─> Initialize Validators
    │                   │   ├─> PinTypeValidator
    │                   │   ├─> ConnectivityValidator
    │                   │   ├─> ComponentValidator
    │                   │   ├─> PowerValidator
    │                   │   └─> HierarchyValidator
    │                   │
    ▼                   ▼
run_all_checks()    Each Validator:
    │                   │
    │                   ├─> Access Schematic Data
    │                   ├─> Apply Validation Rules
    │                   ├─> Create ERCViolations
    │                   └─> Return Violations
    │                           │
    ▼                           │
Collect All Violations  ◄───────┘
    │
    ├─> Filter by Severity
    ├─> Apply Config Overrides
    ├─> Suppress Configured Warnings
    │
    ▼
Create ERCResult
    │
    ├─> errors: List[ERCViolation]
    ├─> warnings: List[ERCViolation]
    ├─> info: List[ERCViolation]
    ├─> Statistics
    │
    ▼
Return to User
    │
    └─> User processes results
        ├─> Print summary
        ├─> Fix errors
        └─> Re-run ERC

Validation Flow Sequence

ElectricalRulesChecker.run_all_checks()
│
├─[1]─> PinTypeValidator.validate_pin_connections()
│       │
│       ├─> For each net in schematic:
│       │   ├─> Get all pins on net
│       │   ├─> Get pin types from symbol cache
│       │   ├─> Check each pin pair against matrix
│       │   └─> Create ERCViolation if conflict
│       │
│       └─> Return violations
│
├─[2]─> ConnectivityValidator.find_dangling_wires()
│       │
│       ├─> For each wire:
│       │   ├─> Count connections at endpoints
│       │   └─> Create violation if <2 connections
│       │
│       └─> Return violations
│
├─[3]─> ConnectivityValidator.find_undriven_nets()
│       │
│       ├─> For each net:
│       │   ├─> Check if any output pin on net
│       │   └─> Create violation if no driver
│       │
│       └─> Return violations
│
├─[4]─> ComponentValidator.find_duplicate_references()
│       │
│       ├─> Build reference → component map
│       ├─> Find duplicates
│       └─> Create violations for duplicates
│
├─[5]─> PowerValidator.validate_power_flags()
│       │
│       ├─> For each power net:
│       │   ├─> Check for Power Output or PWR_FLAG
│       │   └─> Create violation if missing
│       │
│       └─> Return violations
│
├─[6]─> HierarchyValidator.validate_sheet_pins()
│       │
│       ├─> For each hierarchical sheet:
│       │   ├─> Match pins to labels in child
│       │   └─> Create violation if mismatch
│       │
│       └─> Return violations
│
└─> Aggregate all violations into ERCResult

Database Schema (if persisting results)

-- ERC Results Table
CREATE TABLE erc_results (
    id INTEGER PRIMARY KEY,
    schematic_uuid TEXT NOT NULL,
    timestamp DATETIME NOT NULL,
    total_checks INTEGER,
    passed_checks INTEGER,
    duration_ms REAL,
    has_errors BOOLEAN
);

-- ERC Violations Table
CREATE TABLE erc_violations (
    id INTEGER PRIMARY KEY,
    result_id INTEGER REFERENCES erc_results(id),
    violation_type TEXT NOT NULL,
    severity TEXT NOT NULL,  -- 'error', 'warning', 'info'
    error_code TEXT NOT NULL,
    message TEXT NOT NULL,
    net_name TEXT,
    location_x REAL,
    location_y REAL,
    suggested_fix TEXT
);

-- Component References in Violations
CREATE TABLE violation_components (
    id INTEGER PRIMARY KEY,
    violation_id INTEGER REFERENCES erc_violations(id),
    component_ref TEXT NOT NULL,
    pin_number TEXT
);

-- Suppressed Warnings
CREATE TABLE suppressed_warnings (
    id INTEGER PRIMARY KEY,
    schematic_uuid TEXT NOT NULL,
    error_code TEXT NOT NULL,
    component_ref TEXT,
    reason TEXT,
    suppressed_at DATETIME
);

Extension Points

Adding Custom Validators

from kicad_sch_api.validation import BaseValidator, ERCViolation

class CustomSignalIntegrityValidator(BaseValidator):
    """Custom validator for signal integrity checks."""

    def validate(self, schematic: Schematic) -> List[ERCViolation]:
        violations = []

        # Custom logic
        for component in schematic.components:
            if self.has_signal_integrity_issue(component):
                violations.append(ERCViolation(
                    violation_type="signal_integrity",
                    severity="warning",
                    message="High-speed signal without termination",
                    component_refs=[component.reference],
                    error_code="C001"
                ))

        return violations

# Register with ERC
erc = ElectricalRulesChecker(sch)
erc.add_validator(CustomSignalIntegrityValidator())

Custom Pin Conflict Matrix

# Create custom matrix
custom_matrix = PinConflictMatrix()

# Set custom rule: Allow Output-to-Output (override default error)
custom_matrix.set_rule("output", "output", PinConflictMatrix.WARNING)

# Use in config
config = ERCConfig()
config.pin_conflict_matrix = custom_matrix

erc = ElectricalRulesChecker(sch, config=config)

---

Summary

This ERD defines a comprehensive, extensible ERC validation system with:

• 5 Core Validators: Pin Type, Connectivity, Component, Power, Hierarchy

• 3 Result Types: ERCViolation, ERCResult, ERCConfig

• Extensibility: Custom rules, configurable matrix, validator plugins

• Performance: Optimized for O(n) complexity

• Compatibility: Matches KiCAD 7/8 ERC behavior

The system is designed to be:

• Modular: Each validator is independent

• Configurable: Users can customize all rules

• Testable: Clear interfaces for unit testing

• Scalable: Efficient for large schematics

---

Document Version: 1.0 Last Updated: 2024-10-26 Status: Ready for Implementation