Add TVS generic, matcher

Author: akhilles

bom/helpers.zen

@@ -341,6 +341,41 @@ def ferrite_bead(impedance: str, frequency: str, current: str, dcr: str, mpn: st
     }
 
 
+def tvs(standoff_voltage: str, clamping_voltage: str, peak_pulse_power: str, mpn: str, manufacturer: str) -> dict:
+    """Helper to create TVS diode catalog entry.
+
+    Args:
+        standoff_voltage: Reverse standoff voltage (e.g., "5V" or "5V to 6V")
+        clamping_voltage: Clamping voltage @ Ipp (e.g., "9.2V" or "9V to 12V")
+        peak_pulse_power: Peak pulse power (e.g., "200W" or "200W to 400W")
+        mpn: Manufacturer part number
+        manufacturer: Manufacturer name
+
+    Returns:
+        TVS diode dictionary
+    """
+    # Use ranges for all values to support flexible matching
+    standoff_val = (
+        VoltageRange(standoff_voltage)
+        if "to" in standoff_voltage
+        else VoltageRange(standoff_voltage + " to " + standoff_voltage)
+    )
+    clamping_val = (
+        VoltageRange(clamping_voltage)
+        if "to" in clamping_voltage
+        else VoltageRange(clamping_voltage + " to " + clamping_voltage)
+    )
+    power_val = Power(peak_pulse_power)
+
+    return {
+        "standoff_voltage": standoff_val,
+        "clamping_voltage": clamping_val,
+        "peak_pulse_power": power_val,
+        "mpn": mpn,
+        "manufacturer": manufacturer,
+    }
+
+
 def match_component(match: dict, parts: tuple | list, matcher: str = "match_component"):
     """Create a component modifier that matches specific properties and assigns MPN.
 

bom/match_generics.zen

@@ -30,6 +30,7 @@ load(
     "led",
     "ferrite_bead",
     "pin_header",
+    "tvs",
 )
 
 
@@ -249,6 +250,26 @@ HOUSE_PH = {
     ("2.54mm", 2, 20, "Vertical"): [("61304021121", "Würth Elektronik")],
 }
 
+# House TVS diode catalog by package (8/20µs pulse ratings per IEC 61000-4-5)
+HOUSE_TVS_BY_PKG = {
+    "DO-219AB": [
+        # Vishay eSMP series - 5V standoff
+        tvs("5V", "9.2V", "1000W", "SMF5V0A-E3-08", "Vishay General Semiconductor - Diodes Division"),
+        # Littelfuse SZSMF series - 5V standoff (AEC-Q101 automotive)
+        tvs("5V", "9.2V", "1000W", "SZSMF5.0AT1G", "Littelfuse Inc."),
+        # Vishay eSMP series - 20V standoff
+        tvs("20V", "32.4V", "1000W", "SMF20A-E3-08", "Vishay General Semiconductor - Diodes Division"),
+        # Littelfuse SMF series - 20V standoff
+        tvs("20V", "32.4V", "1000W", "SMF20A", "Littelfuse Inc."),
+        # Littelfuse SZSMF series - 20V standoff (AEC-Q101 automotive)
+        tvs("20V", "32.4V", "1000W", "SZSMF20AT1G", "Littelfuse Inc."),
+    ],
+    "DO-214AC": [
+        # Vishay TransZorb series - 20V standoff
+        tvs("20V", "32.4V", "2000W", "SMAJ20A-E3/61", "Vishay General Semiconductor - Diodes Division"),
+    ],
+}
+
 
 def assign_house_resistor(c, series_by_pkg):
     """Assign house resistor MPNs."""
@@ -507,6 +528,51 @@ def assign_house_pin_header(c, house_ph):
     )
 
 
+def assign_house_tvs(c, house_tvs_by_pkg):
+    """Assign house TVS diode MPNs."""
+    pkg = prop(c, ["package", "Package"])
+    req_standoff = prop(c, ["reverse_standoff_voltage", "Reverse_standoff_voltage"])
+    req_clamping = prop(c, ["reverse_clamping_voltage", "Reverse_clamping_voltage"])
+    req_power = prop(c, ["peak_pulse_power", "Peak_pulse_power"])
+
+    parts = house_tvs_by_pkg.get(pkg, [])
+    matches = []
+
+    for p in parts:
+        # Standoff voltage: part must be within the requirement
+        if req_standoff and p["standoff_voltage"] not in req_standoff:
+            continue
+
+        # Clamping voltage: part must be within the requirement
+        if req_clamping and p["clamping_voltage"] not in req_clamping:
+            continue
+
+        # Power: part must be within the requirement
+        if req_power and p["peak_pulse_power"] not in req_power:
+            continue
+
+        matches.append(p)
+
+    if matches:
+        # Use first match as primary, rest as alternatives
+        manufacturer = matches[0]["manufacturer"]
+        all_mpns = [p["mpn"] for p in matches]
+        set_primary_and_alts(c, all_mpns[0], manufacturer, all_mpns[1:])
+        c.matcher = "assign_house_tvs"
+        return
+
+    # Generate warning
+    warn(
+        "No house TVS diode found for "
+        + c.value
+        + " "
+        + pkg
+        + ".\nTry using different component values or specify mpn directly "
+        + "(https://docs.pcb.new/pages/spec#match-component-match%2C-parts)",
+        kind="bom.match_generic",
+    )
+
+
 def assign_house_parts(c):
     """Single modifier that dispatches component matching by type."""
     # Skip if already has MPN
@@ -522,6 +588,8 @@ def assign_house_parts(c):
         assign_house_led(c, HOUSE_LEDS_BY_PKG)
     elif c.type == "ferrite_bead":
         assign_house_ferrite_bead(c, HOUSE_FB_BY_PKG)
+    elif c.type == "tvs":
+        assign_house_tvs(c, HOUSE_TVS_BY_PKG)
     elif c.type == "connector":
         connector_type = prop(c, ["connector_type", "Connector_type"])
         if connector_type == "Pin Header":

generics/Tvs.zen

@@ -0,0 +1,79 @@
+load("../units.zen", "PowerRange", "Voltage", "VoltageRange", "CurrentRange")
+load("../interfaces.zen", "Power", "Ground")
+load("../utils.zen", "format_value")
+
+# Package      JEDEC         LxWxH
+# SMF          DO-219AB      3.0×1.8×1.0
+# SMA          DO-214AC      4.6×2.6×2.1
+# SMB          DO-214AA      5.3×3.7×2.5
+# SMC          DO-214AB      7.8×6.8×2.5
+Package = enum("DO-219AB", "DO-214AC", "DO-214AA", "DO-214AB")
+
+USB_5V_STANDOFF_VOLTAGE = VoltageRange("5 to 6V")
+USB_5V_CLAMPING_VOLTAGE = VoltageRange("9 to 12V")
+USB_5V_POWER_PP = PowerRange("800 to 1200W")
+
+package = config("package", Package, default=Package("DO-219AB"))
+# 8/20 μs waveform acc. IEC 61000-4-5
+reverse_standoff_voltage = config("reverse_standoff_voltage", VoltageRange, default=USB_5V_STANDOFF_VOLTAGE)
+reverse_clamping_voltage = config("reverse_clamping_voltage", VoltageRange, default=USB_5V_CLAMPING_VOLTAGE)
+peak_pulse_power = config("peak_pulse_power", PowerRange, default=USB_5V_POWER_PP)
+
+mpn = config("mpn", str, optional=True)
+manufacturer = config("manufacturer", str, optional=True)
+
+A = io("A", Ground)
+K = io("K", Power, default=Power("VCC", voltage=VoltageRange("5V")))
+
+if reverse_clamping_voltage.min < reverse_standoff_voltage.max:
+    error(
+        "reverse clamping voltage ("
+        + str(reverse_clamping_voltage)
+        + ") must be >= reverse standoff voltage ("
+        + str(reverse_standoff_voltage)
+        + ")"
+    )
+
+if hasattr(K, "voltage"):
+    if K.voltage.max > reverse_clamping_voltage.min:
+        error(
+            "Power net voltage ("
+            + str(K.voltage)
+            + ") must be <= reverse clamping voltage ("
+            + str(reverse_clamping_voltage)
+            + ")"
+        )
+else:
+    warn("No voltage specified for power net")
+
+
+def _footprint(package: Package) -> str:
+    kicad_footprints = {
+        Package("DO-219AB"): "@kicad-footprints/Diode_SMD.pretty/D_SMF.kicad_mod",
+        Package("DO-214AC"): "@kicad-footprints/Diode_SMD.pretty/D_SMA.kicad_mod",
+        Package("DO-214AA"): "@kicad-footprints/Diode_SMD.pretty/D_SMB.kicad_mod",
+        Package("DO-214AB"): "@kicad-footprints/Diode_SMD.pretty/D_SMC.kicad_mod",
+    }
+    return kicad_footprints[package]
+
+
+Component(
+    name="D",
+    mpn=mpn,
+    manufacturer=manufacturer,
+    prefix="D",
+    symbol=Symbol(library="@kicad-symbols/Device.kicad_sym", name="D_Zener"),
+    footprint=File(_footprint(package)),
+    properties={
+        "value": format_value(reverse_standoff_voltage, "TVS Diode", peak_pulse_power),
+        "package": package,
+        "peak_pulse_power": peak_pulse_power,
+        "reverse_standoff_voltage": reverse_standoff_voltage,
+        "reverse_clamping_voltage": reverse_clamping_voltage,
+    },
+    type="tvs",
+    pins={
+        "A": A,
+        "K": K,
+    },
+)

generics/test/test_Tvs.zen

@@ -0,0 +1,42 @@
+"""Comprehensive test for TVS Diode component."""
+
+load("../../interfaces.zen", "Power", "Ground")
+load("../../units.zen", "PowerRange", "Voltage", "VoltageRange")
+
+Tvs = Module("../Tvs.zen")
+
+vcc = Power("VCC", voltage=VoltageRange("3.3V"))
+gnd = Ground("GND")
+
+# Test all Package values
+for package in Tvs.Package.values():
+    name = "D_TVS_" + str(package)
+    Tvs(
+        name=name,
+        package=package,
+        peak_pulse_power=PowerRange("800 to 1200W"),
+        reverse_clamping_voltage=VoltageRange("9 to 12V"),
+        A=gnd,
+        K=vcc,
+    )
+
+# Test with different voltage ratings
+Tvs(
+    name="D_TVS_3V3",
+    package="DO-219AB",
+    peak_pulse_power=PowerRange("400 to 600W"),
+    reverse_standoff_voltage=VoltageRange("3.3V"),
+    reverse_clamping_voltage=VoltageRange("6 to 8V"),
+    A=gnd,
+    K=vcc,
+)
+
+Tvs(
+    name="D_TVS_12V",
+    package="DO-214AC",
+    peak_pulse_power=PowerRange("1200 to 1500W"),
+    reverse_standoff_voltage=VoltageRange("12V"),
+    reverse_clamping_voltage=VoltageRange("19 to 21V"),
+    A=gnd,
+    K=vcc,
+)