traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/firmware/mcus.py

@@ -0,0 +1,177 @@
+"""MCU pin tables (data). Package pin number -> pin name, and what each pin can do.
+
+Sources are cited per entry. ``functions`` use these tokens: GPIO, ADC, PWM, I2C_SDA,
+I2C_SCL, SPI_MOSI, SPI_MISO, SPI_SCK, UART_TX, UART_RX. Pins a design may use even
+though the datasheet warns about them go in ``caution``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Mcu:
+    key: str
+    family: str  # avr | esp32 | stm32
+    name: str
+    package: str
+    source: str  # datasheet table the data was taken from
+    match: str  # regex over "<symbol> <value> <footprint>"
+    pins: dict[str, str] = field(default_factory=dict)  # package pin number -> pin name
+    functions: dict[str, tuple[str, ...]] = field(default_factory=dict)  # pin name -> tokens
+    arduino: dict[str, int] = field(default_factory=dict)  # pin name -> Arduino number
+    adc: dict[str, int] = field(default_factory=dict)  # pin name -> ADC channel
+    caution: dict[str, str] = field(default_factory=dict)  # pin name -> warning
+    power_pins: tuple[str, ...] = ()
+    platformio: dict[str, str] = field(default_factory=dict)
+    fqbn: str = ""
+    f_cpu: int = 0
+
+
+_ATTINY85 = Mcu(
+    key="attiny85",
+    family="avr",
+    name="ATtiny85",
+    package="SOIC-8 / DIP-8",
+    source="Microchip ATtiny25/45/85 datasheet (DS40002586), section 1.1 Pin Descriptions, "
+    "section 10.3 Alternate Port Functions",
+    match=r"attiny85",
+    pins={
+        "1": "PB5",
+        "2": "PB3",
+        "3": "PB4",
+        "4": "GND",
+        "5": "PB0",
+        "6": "PB1",
+        "7": "PB2",
+        "8": "VCC",
+    },
+    functions={
+        # PB0: MOSI/DI/SDA/AIN0/OC0A; PB1: MISO/DO/AIN1/OC0B/OC1A; PB2: SCK/USCK/SCL/ADC1
+        "PB0": ("GPIO", "PWM", "I2C_SDA", "SPI_MOSI"),
+        "PB1": ("GPIO", "PWM", "SPI_MISO"),
+        "PB2": ("GPIO", "ADC", "I2C_SCL", "SPI_SCK"),
+        "PB3": ("GPIO", "ADC", "PWM"),
+        "PB4": ("GPIO", "ADC", "PWM"),
+        "PB5": ("GPIO", "ADC"),
+    },
+    arduino={"PB0": 0, "PB1": 1, "PB2": 2, "PB3": 3, "PB4": 4, "PB5": 5},
+    adc={"PB5": 0, "PB2": 1, "PB4": 2, "PB3": 3},
+    caution={"PB5": "RESET pin: using it as I/O needs the RSTDISBL fuse and loses ISP"},
+    power_pins=("VCC", "GND"),
+    platformio={"platform": "atmelavr", "board": "attiny85", "framework": "arduino"},
+    fqbn="ATTinyCore:avr:attinyx5",
+    f_cpu=8_000_000,
+)
+
+_ESP32S3_PINS = {
+    "1": "GND",
+    "2": "3V3",
+    "3": "EN",
+    "4": "IO4",
+    "5": "IO5",
+    "6": "IO6",
+    "7": "IO7",
+    "8": "IO15",
+    "9": "IO16",
+    "10": "IO17",
+    "11": "IO18",
+    "12": "IO8",
+    "13": "IO19",
+    "14": "IO20",
+    "15": "IO3",
+    "16": "IO46",
+    "17": "IO9",
+    "18": "IO10",
+    "19": "IO11",
+    "20": "IO12",
+    "21": "IO13",
+    "22": "IO14",
+    "23": "IO21",
+    "24": "IO47",
+    "25": "IO48",
+    "26": "IO45",
+    "27": "IO0",
+    "28": "IO35",
+    "29": "IO36",
+    "30": "IO37",
+    "31": "IO38",
+    "32": "IO39",
+    "33": "IO40",
+    "34": "IO41",
+    "35": "IO42",
+    "36": "IO44",
+    "37": "IO43",
+    "38": "IO2",
+    "39": "IO1",
+    "40": "GND",
+    "41": "GND",
+}
+_ESP32S3_GPIO = [n for n in range(49) if n not in range(22, 26)]  # GPIO22-25 do not exist
+_ESP32S3_FUNCS: dict[str, tuple[str, ...]] = {}
+for _n in _ESP32S3_GPIO:
+    # The GPIO matrix routes any digital peripheral to any pin; ADC1 = 1-10, ADC2 = 11-20.
+    _f = ["GPIO", "PWM", "I2C_SDA", "I2C_SCL", "SPI_MOSI", "SPI_MISO", "SPI_SCK"]
+    _f += ["UART_TX", "UART_RX"]
+    if 1 <= _n <= 20:
+        _f.append("ADC")
+    _ESP32S3_FUNCS[f"IO{_n}"] = tuple(_f)
+_ESP32S3_ADC = {f"IO{n}": n - 1 for n in range(1, 21)}  # ADC1 ch0-9, ADC2 ch0-9 (n 11-20)
+_ESP32S3_ADC.update({f"IO{n}": n - 11 for n in range(11, 21)})
+_ESP32S3_CAUTION = {
+    **{f"IO{n}": "strapping pin: keep its boot level" for n in (0, 3, 45, 46)},
+    **{f"IO{n}": "connected to the module's flash/PSRAM: not usable" for n in range(26, 33)},
+    **{
+        f"IO{n}": "octal PSRAM on N8R8/N16R8 modules: not usable there"
+        for n in (33, 34, 35, 36, 37)
+    },
+    "IO19": "USB D- (native USB); using it as GPIO disables USB",
+    "IO20": "USB D+ (native USB); using it as GPIO disables USB",
+}
+_ESP32S3 = Mcu(
+    key="esp32s3",
+    family="esp32",
+    name="ESP32-S3-WROOM-1",
+    package="module, 41 pads",
+    source="Espressif ESP32-S3-WROOM-1 datasheet, Table 3-1 Pin Definitions; ESP32-S3 datasheet "
+    "section 2.2 (IO MUX, GPIO matrix, strapping pins)",
+    match=r"esp32-s3|esp32s3",
+    pins=_ESP32S3_PINS,
+    functions=_ESP32S3_FUNCS,
+    arduino={f"IO{n}": n for n in _ESP32S3_GPIO},
+    adc=_ESP32S3_ADC,
+    caution=_ESP32S3_CAUTION,
+    power_pins=("3V3", "GND", "EN"),
+    platformio={
+        "platform": "espressif32",
+        "board": "esp32-s3-devkitc-1",
+        "framework": "arduino",
+    },
+    fqbn="esp32:esp32:esp32s3",
+    f_cpu=240_000_000,
+)
+
+_STM32F103 = Mcu(
+    key="stm32f103",
+    family="stm32",
+    name="STM32F103C8T6",
+    package="LQFP-48",
+    source="ST STM32F103x8/xB datasheet (DS5319), Table 5 pin definitions. Only pin names "
+    "are used (e.g. PA5); package pin numbers are not tabulated here",
+    match=r"stm32f103",
+    functions={},
+    power_pins=("VDD", "VSS", "VBAT", "VDDA", "VSSA", "NRST", "BOOT0"),
+    platformio={"platform": "ststm32", "board": "bluepill_f103c8", "framework": "stm32cube"},
+    f_cpu=8_000_000,
+)
+
+MCUS: dict[str, Mcu] = {m.key: m for m in (_ATTINY85, _ESP32S3, _STM32F103)}
+
+
+def find_mcu(text: str) -> Mcu | None:
+    for mcu in MCUS.values():
+        if re.search(mcu.match, text, re.I):
+            return mcu
+    return None

traceforge/firmware/netlist.py

@@ -0,0 +1,55 @@
+"""Read the connections of a design: nets -> (reference, pin) and what each part is."""
+
+from __future__ import annotations
+
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class NetlistError(Exception):
+    pass
+
+
+@dataclass
+class Netlist:
+    nets: dict[str, list[tuple[str, str]]]
+    parts: dict[str, str] = field(default_factory=dict)  # reference -> "symbol value footprint"
+    source: str = ""
+
+
+def load_netlist(path: str | Path) -> Netlist:
+    """Load a design spec (.yaml/.json), a schematic (.kicad_sch) or a KiCad netlist (.net)."""
+    path = Path(path)
+    if not path.exists():
+        raise NetlistError(f"{path} does not exist")
+    suffix = path.suffix.lower()
+    if suffix in {".yaml", ".yml", ".json"}:
+        from traceforge.design.spec import load_spec
+
+        spec = load_spec(path)
+        parts = {p.ref: f"{p.symbol} {p.value} {p.footprint}" for p in spec.parts}
+        return Netlist(spec.all_nets(), parts, str(path))
+    if suffix == ".kicad_sch":
+        from traceforge.kicad.cli import KicadCli, KicadCliError
+        from traceforge.kicad.schematic import read_schematic
+
+        cli = KicadCli()
+        if not cli.available:
+            raise NetlistError("exporting a netlist from a schematic needs kicad-cli")
+        try:
+            with tempfile.TemporaryDirectory() as tmp:
+                nets = cli.netlist(path, Path(tmp))
+        except KicadCliError as exc:
+            raise NetlistError(str(exc)) from exc
+        sch = read_schematic(path)
+        parts = {
+            ref: f"{units[0].lib_id} {units[0].value} {units[0].footprint}"
+            for ref, units in sch.components().items()
+        }
+        return Netlist(nets, parts, str(path))
+    if suffix in {".net", ".xml"}:
+        from traceforge.kicad.cli import parse_netlist
+
+        return Netlist(parse_netlist(path.read_text(encoding="utf-8")), {}, str(path))
+    raise NetlistError(f"unsupported design file {path.name} (use .yaml, .kicad_sch or .net)")

traceforge/firmware/pinmap.py

@@ -0,0 +1,296 @@
+"""Signal-to-pin assignments for an MCU from the netlist, and the pin headers."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from traceforge.firmware.mcus import MCUS, Mcu, find_mcu
+from traceforge.firmware.netlist import Netlist, NetlistError
+
+_POWER = re.compile(
+    r"^(\+?\d+V\d*|\+?\d+\.\d+V|VCC\w*|VDD\w*|VBUS\w*|VIN|VBAT|GND\w*|AGND|VSS\w*)$", re.I
+)
+
+# (regex over the upper-case net name, peripheral function, direction)
+_ROLES: list[tuple[str, str, str]] = [
+    (r"(^|_)(SDA|SIOD)(\d*)($|_)", "I2C_SDA", "io"),
+    (r"(^|_)(SCL|SIOC)(\d*)($|_)", "I2C_SCL", "io"),
+    (r"(^|_)(MOSI|COPI|SDI)($|_)", "SPI_MOSI", "out"),
+    (r"(^|_)(MISO|CIPO|SDO)($|_)", "SPI_MISO", "in"),
+    (r"(^|_)(SCK|SCLK|SPI_CLK)($|_)", "SPI_SCK", "out"),
+    (r"(^|_)(TX|TXD|UART_TX)\d*($|_)", "UART_TX", "out"),
+    (r"(^|_)(RX|RXD|UART_RX)\d*($|_)", "UART_RX", "in"),
+    (r"(^|_)(PWM|BL|BACKLIGHT)($|_)", "PWM", "out"),
+    (r"(^|_)(ADC|AIN|VSENSE|VBAT_SENSE|VMON|NTC)\d*($|_)", "ADC", "in"),
+    (r"(^|_)(BTN|BUTTON|SW|KEY|IRQ|INT|DRDY|PIR|BOOT|PCLK|VSYNC|HREF|Y\d)($|_)", "GPIO", "in"),
+    (r"(^|_)(LED|EN|CS|SS|NSS|CSN|RST|RESET|PWDN|XCLK|BUZZER|RELAY)($|_)", "GPIO", "out"),
+]
+_SPI_CS = re.compile(r"(^|_)(CS|SS|NSS|CSN)($|_)")
+
+
+@dataclass
+class PinAssignment:
+    net: str
+    macro: str  # identifier-safe upper-case name, unique in the map
+    ref: str
+    pin: str  # as written in the netlist (number or name)
+    pin_name: str  # the MCU pin name (PB3, IO4, PA5)
+    function: str  # GPIO, ADC, PWM, I2C_SDA, ...
+    direction: str  # in | out | io
+    pull_up: bool = False
+    capabilities: tuple[str, ...] = ()
+    port: str | None = None  # AVR/STM32 port letter
+    bit: int | None = None
+    number: int | None = None  # the number code uses (GPIO number, Arduino pin)
+    adc_channel: int | None = None
+    warnings: list[str] = field(default_factory=list)
+
+
+@dataclass
+class PinMap:
+    mcu: Mcu
+    ref: str
+    assignments: list[PinAssignment]
+    unconnected: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    def by_net(self, net: str) -> PinAssignment | None:
+        return next((a for a in self.assignments if a.net == net), None)
+
+    def as_dict(self) -> dict:
+        return {
+            "mcu": self.mcu.name,
+            "ref": self.ref,
+            "source": self.mcu.source,
+            "pins": [
+                {
+                    "net": a.net,
+                    "macro": f"PIN_{a.macro}",
+                    "pin": a.pin,
+                    "pin_name": a.pin_name,
+                    "function": a.function,
+                    "direction": a.direction,
+                    "number": a.number,
+                    "adc_channel": a.adc_channel,
+                    "warnings": a.warnings,
+                }
+                for a in self.assignments
+            ],
+            "warnings": self.warnings,
+        }
+
+
+def classify(net: str) -> tuple[str, str, bool]:
+    """Guess (function, direction, pull-up) from a net name."""
+    name = net.upper().lstrip("/")
+    for pattern, function, direction in _ROLES:
+        if re.search(pattern, name):
+            pull = function == "GPIO" and direction == "in" and "BTN" in name
+            if function == "SPI_SCK" and re.search(r"(^|_)SCL($|_)", name):
+                continue
+            return function, direction, pull
+    if _SPI_CS.search(name):
+        return "GPIO", "out", False
+    return "GPIO", "io", False
+
+
+def macro_name(net: str) -> str:
+    return re.sub(r"[^A-Z0-9]+", "_", net.upper().replace("+", "P").replace("~", "N")).strip("_")
+
+
+def _pin_name(mcu: Mcu, pin: str) -> str | None:
+    if pin in mcu.pins:
+        return mcu.pins[pin]
+    upper = pin.upper()
+    if mcu.family == "esp32":
+        upper = {"RXD0": "IO44", "TXD0": "IO43"}.get(upper, re.sub(r"^GPIO", "IO", upper))
+        names = set(mcu.pins.values())
+        return upper if upper in names else None
+    return (
+        upper if re.fullmatch(r"P[A-K]\d{1,2}", upper) or upper in set(mcu.pins.values()) else None
+    )
+
+
+def _split(mcu: Mcu, name: str) -> tuple[str | None, int | None, int | None]:
+    """Return (port, bit, number) for a pin name."""
+    if mcu.family == "avr":
+        m = re.fullmatch(r"P([A-F])(\d)", name)
+        return (m.group(1), int(m.group(2)), mcu.arduino.get(name)) if m else (None, None, None)
+    if mcu.family == "esp32":
+        m = re.fullmatch(r"IO(\d+)", name)
+        return (None, None, int(m.group(1))) if m else (None, None, None)
+    m = re.fullmatch(r"P([A-K])(\d{1,2})", name)
+    if m:
+        return m.group(1), int(m.group(2)), (ord(m.group(1)) - 65) * 16 + int(m.group(2))
+    return None, None, None
+
+
+def find_mcu_ref(netlist: Netlist, mcu: Mcu | None = None) -> tuple[str, Mcu]:
+    for ref, text in sorted(netlist.parts.items()):
+        found = find_mcu(text)
+        if found is not None and (mcu is None or found.key == mcu.key):
+            return ref, found
+    raise NetlistError(
+        "no known MCU in the design (supported: "
+        + ", ".join(m.name for m in MCUS.values())
+        + "); pass --mcu and --ref"
+    )
+
+
+def build_pinmap(netlist: Netlist, ref: str | None = None, mcu: str | None = None) -> PinMap:
+    chosen = MCUS.get(mcu) if mcu else None
+    if mcu and chosen is None:
+        raise NetlistError(f"unknown MCU {mcu!r} (known: {', '.join(MCUS)})")
+    if ref is None:
+        ref, chosen = find_mcu_ref(netlist, chosen)
+    elif chosen is None:
+        chosen = find_mcu(netlist.parts.get(ref, ""))
+        if chosen is None:
+            raise NetlistError(f"{ref} is not a known MCU; pass --mcu")
+    pm = PinMap(chosen, ref, [])
+    used: set[str] = set()
+    for net, members in netlist.nets.items():
+        if _POWER.match(net.lstrip("/")) or net.lstrip("/").startswith("unconnected-"):
+            continue
+        for member_ref, pin in members:
+            if member_ref != ref:
+                continue
+            name = _pin_name(chosen, str(pin))
+            if name is None:
+                pm.warnings.append(f"{ref}.{pin} (net {net}): not a pin of {chosen.name}")
+                continue
+            if name in chosen.power_pins or name == "GND":
+                continue
+            function, direction, pull = classify(net)
+            port, bit, number = _split(chosen, name)
+            caps = chosen.functions.get(name, ())
+            macro = macro_name(net)
+            base, k = macro, 2
+            while macro in used:
+                macro, k = f"{base}_{k}", k + 1
+            used.add(macro)
+            item = PinAssignment(
+                net, macro, ref, str(pin), name, function, direction, pull, caps,
+                port, bit, number, chosen.adc.get(name),
+            )  # fmt: skip
+            if caps and function not in caps and function != "GPIO":
+                item.warnings.append(
+                    f"{net} looks like {function} but {name} cannot do it (can: {', '.join(caps)})"
+                )
+            if function == "GPIO" and caps and "GPIO" not in caps:
+                item.warnings.append(f"{name} has no GPIO function")
+            if name in chosen.caution:
+                item.warnings.append(f"{name}: {chosen.caution[name]}")
+            pm.assignments.append(item)
+    pm.assignments.sort(key=lambda a: (a.number is None, a.number or 0, a.net))
+    mapped = {a.pin_name for a in pm.assignments}
+    pm.unconnected = sorted(
+        n
+        for n in set(chosen.pins.values())
+        if n not in mapped and n not in chosen.power_pins and n != "GND"
+    )
+    for a in pm.assignments:
+        pm.warnings.extend(a.warnings)
+    _check_peripherals(pm)
+    return pm
+
+
+def _check_peripherals(pm: PinMap) -> None:
+    funcs: dict[str, list[PinAssignment]] = {}
+    for a in pm.assignments:
+        funcs.setdefault(a.function, []).append(a)
+    for function, items in funcs.items():
+        if function.startswith(("I2C", "SPI", "UART")) and len(items) > 1:
+            pm.warnings.append(
+                f"{function} appears on several nets: " + ", ".join(i.net for i in items)
+            )
+
+
+# ---- headers -------------------------------------------------------------------------
+
+_HEADER_NOTE = "Generated by traceforge firmware pins from {src}. Do not edit; regenerate."
+
+
+def _entries(pm: PinMap) -> list[tuple[str, str, PinAssignment]]:
+    """(macro, value expression, assignment) for every pin."""
+    out = []
+    for a in pm.assignments:
+        value = str(a.number) if a.number is not None else f'"{a.pin_name}"'
+        out.append((f"PIN_{a.macro}", value, a))
+    return out
+
+
+def _aliases(pm: PinMap) -> list[tuple[str, str]]:
+    """Peripheral aliases (PIN_I2C_SDA = PIN_<net>) and camera names for esp_camera."""
+    aliases: list[tuple[str, str]] = []
+    seen: set[str] = set()
+    for a in pm.assignments:
+        if a.function.startswith(("I2C_", "SPI_", "UART_")) and a.function not in seen:
+            seen.add(a.function)
+            aliases.append((f"PIN_{a.function}", f"PIN_{a.macro}"))
+        if a.macro.startswith("CAM_"):
+            aliases.append((f"CAM_PIN_{a.macro[4:]}", f"PIN_{a.macro}"))
+    return aliases
+
+
+def render_header(pm: PinMap, style: str = "c", source: str = "the netlist") -> str:
+    """Render ``pins.h`` (style c), ``pins.hpp`` (cpp) or ``board_pins.rs`` (rust)."""
+    note = _HEADER_NOTE.format(src=source)
+    entries = _entries(pm)
+    aliases = _aliases(pm)
+    if style == "rust":
+        lines = [f"//! {note}", f"//! MCU {pm.mcu.name} ({pm.ref}); pin data: {pm.mcu.source}", ""]
+        for macro, value, a in entries:
+            lines.append(f"/// {a.net}: {pm.ref} pin {a.pin} = {a.pin_name}, {a.function}")
+            if a.number is not None:
+                lines.append(f"pub const {macro}: u8 = {value};")
+            else:
+                lines.append(f"pub const {macro}: &str = {value};")
+            if a.port is not None:
+                lines.append(f"pub const {macro}_PORT: char = '{a.port}';")
+                lines.append(f"pub const {macro}_BIT: u8 = {a.bit};")
+            if a.adc_channel is not None and a.function == "ADC":
+                lines.append(f"pub const {macro}_ADC: u8 = {a.adc_channel};")
+        for alias, target in aliases:
+            lines.append(f"pub const {alias}: u8 = {target};")
+        return "\n".join(lines) + "\n"
+    cpp = style == "cpp"
+    guard = "TRACEFORGE_PINS_HPP" if cpp else "TRACEFORGE_PINS_H"
+    lines = [f"/* {note} */", f"/* MCU {pm.mcu.name} ({pm.ref}); pin data: {pm.mcu.source} */"]
+    lines += [f"#ifndef {guard}", f"#define {guard}", ""]
+    if pm.mcu.family == "avr":
+        lines += ["#include <avr/io.h>", ""]
+    for macro, value, a in entries:
+        lines.append(f"/* {a.net}: {pm.ref} pin {a.pin} = {a.pin_name}, {a.function} */")
+        if cpp:
+            lines.append(f"constexpr int {macro} = {value};")
+        else:
+            lines.append(f"#define {macro} {value}")
+        extras: list[tuple[str, str]] = []
+        if a.port is not None:
+            extras.append((f"{macro}_BIT", str(a.bit)))
+            if pm.mcu.family == "avr":
+                extras += [
+                    (f"{macro}_DDR", f"DDR{a.port}"),
+                    (f"{macro}_PORT", f"PORT{a.port}"),
+                    (f"{macro}_PINREG", f"PIN{a.port}"),
+                ]
+            else:
+                extras += [(f"{macro}_PORT", f"'{a.port}'"), (f"{macro}_PIN", str(a.bit))]
+        if a.adc_channel is not None and a.function == "ADC":
+            extras.append((f"{macro}_ADC", str(a.adc_channel)))
+        for name, val in extras:
+            if cpp and val.lstrip("-").isdigit():
+                lines.append(f"constexpr int {name} = {val};")
+            else:
+                lines.append(f"#define {name} {val}")
+    if aliases:
+        lines.append("")
+    for alias, target in aliases:
+        lines.append(f"constexpr int {alias} = {target};" if cpp else f"#define {alias} {target}")
+    lines += ["", f"#endif /* {guard} */", ""]
+    return "\n".join(lines)
+
+
+HEADER_FILES = {"c": "pins.h", "cpp": "pins.hpp", "rust": "board_pins.rs"}