hw-codesign 0.1.3__py3-none-any.whl

hw_codesign/__init__.py

@@ -0,0 +1,3 @@
+"""Agentic hardware design system with evidence-backed release gates."""
+
+__version__ = "0.1.3"

hw_codesign/artifacts.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import hashlib
+import math
+import zipfile
+from pathlib import Path
+from typing import Any, Iterable
+
+from .io import atomic_write_text, write_json
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def deterministic_zip(output: Path, files: Iterable[tuple[Path, str]]) -> None:
+    output.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(output, "w", zipfile.ZIP_DEFLATED, compresslevel=9) as archive:
+        for source, archive_name in sorted(files, key=lambda item: item[1]):
+            info = zipfile.ZipInfo(archive_name, date_time=(1980, 1, 1, 0, 0, 0))
+            info.compress_type = zipfile.ZIP_DEFLATED
+            info.external_attr = 0o100644 << 16
+            archive.writestr(info, source.read_bytes())
+
+
+def write_manifest(root: Path, output: Path, provenance: dict[str, Any] | None = None, candidate_only: bool = False) -> str:
+    entries = []
+    for path in sorted(root.rglob("*")):
+        if path.is_file() and path != output:
+            entries.append({"path": path.relative_to(root).as_posix(), "bytes": path.stat().st_size, "sha256": sha256(path), "provenance": provenance or {}})
+    write_json(output, {"algorithm": "sha256", "candidate_only": candidate_only, "release_eligible": not candidate_only, "provenance": provenance or {}, "artifacts": entries})
+    return str(output)
+
+
+def simple_pdf(title: str, lines: list[str], output: Path) -> None:
+    escaped = [line.replace("\\", "\\\\").replace("(", "\\(").replace(")", "\\)") for line in [title, *lines]]
+    commands = ["BT", "/F1 16 Tf", "50 790 Td", f"({escaped[0]}) Tj", "/F1 10 Tf"]
+    for line in escaped[1:]:
+        commands.extend(("0 -16 Td", f"({line}) Tj"))
+    commands.append("ET")
+    stream = "\n".join(commands).encode("ascii", errors="replace")
+    objects = [
+        b"<< /Type /Catalog /Pages 2 0 R >>",
+        b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+        b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 595 842] /Resources << /Font << /F1 5 0 R >> >> /Contents 4 0 R >>",
+        b"<< /Length %d >>\nstream\n" % len(stream) + stream + b"\nendstream",
+        b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+    ]
+    content = bytearray(b"%PDF-1.4\n")
+    offsets = [0]
+    for index, obj in enumerate(objects, 1):
+        offsets.append(len(content)); content.extend(f"{index} 0 obj\n".encode()); content.extend(obj); content.extend(b"\nendobj\n")
+    xref = len(content); content.extend(f"xref\n0 {len(objects)+1}\n0000000000 65535 f \n".encode())
+    for offset in offsets[1:]: content.extend(f"{offset:010d} 00000 n \n".encode())
+    content.extend(f"trailer\n<< /Size {len(objects)+1} /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n".encode())
+    output.parent.mkdir(parents=True, exist_ok=True); output.write_bytes(content)
+
+
+def box_stl(width: float, depth: float, height: float, wall: float, output: Path) -> None:
+    """Write a watertight open-top enclosure shell as deterministic ASCII STL."""
+    outer = _box_triangles(0, 0, 0, width, depth, height)
+    inner = _box_triangles(wall, wall, wall, width - wall, depth - wall, height + wall)
+    triangles = outer + [(c, b, a) for a, b, c in inner]
+    lines = ["solid enclosure"]
+    for a, b, c in triangles:
+        normal = _normal(a, b, c)
+        lines.append(f"  facet normal {normal[0]:.6f} {normal[1]:.6f} {normal[2]:.6f}")
+        lines.append("    outer loop")
+        lines.extend(f"      vertex {p[0]:.6f} {p[1]:.6f} {p[2]:.6f}" for p in (a, b, c))
+        lines.extend(("    endloop", "  endfacet"))
+    lines.append("endsolid enclosure")
+    atomic_write_text(output, "\n".join(lines) + "\n")
+
+
+def _box_triangles(x0: float, y0: float, z0: float, x1: float, y1: float, z1: float):
+    p = [(x0, y0, z0), (x1, y0, z0), (x1, y1, z0), (x0, y1, z0), (x0, y0, z1), (x1, y0, z1), (x1, y1, z1), (x0, y1, z1)]
+    faces = [(0, 2, 1), (0, 3, 2), (4, 5, 6), (4, 6, 7), (0, 1, 5), (0, 5, 4), (1, 2, 6), (1, 6, 5), (2, 3, 7), (2, 7, 6), (3, 0, 4), (3, 4, 7)]
+    return [(p[a], p[b], p[c]) for a, b, c in faces]
+
+
+def _normal(a, b, c):
+    u = tuple(b[i] - a[i] for i in range(3))
+    v = tuple(c[i] - a[i] for i in range(3))
+    n = (u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0])
+    length = math.sqrt(sum(value * value for value in n)) or 1.0
+    return tuple(value / length for value in n)
+
+
+def step_box(name: str, width: float, depth: float, height: float, output: Path) -> None:
+    """Write a compact AP214 faceted BREP box accepted by standard STEP readers."""
+    points = [(0, 0, 0), (width, 0, 0), (width, depth, 0), (0, depth, 0), (0, 0, height), (width, 0, height), (width, depth, height), (0, depth, height)]
+    faces = [(1, 4, 3, 2), (5, 6, 7, 8), (1, 2, 6, 5), (2, 3, 7, 6), (3, 4, 8, 7), (4, 1, 5, 8)]
+    data = ["ISO-10303-21;", "HEADER;", "FILE_DESCRIPTION(('HW co-design deterministic faceted model'),'2;1');", f"FILE_NAME('{name}.step','1980-01-01T00:00:00',('hw-codesign'),('hw-codesign'),'hw-codesign','hw-codesign','');", "FILE_SCHEMA(('AUTOMOTIVE_DESIGN'));", "ENDSEC;", "DATA;"]
+    index = 1
+    point_ids = []
+    for x, y, z in points:
+        data.append(f"#{index}=CARTESIAN_POINT('',({x:.6f},{y:.6f},{z:.6f}));")
+        point_ids.append(index)
+        index += 1
+    face_ids = []
+    for face in faces:
+        loop_points = ",".join(f"#{point_ids[item - 1]}" for item in (*face, face[0]))
+        data.append(f"#{index}=POLY_LOOP('',({loop_points}));")
+        loop_id = index; index += 1
+        data.append(f"#{index}=FACE_OUTER_BOUND('',#{loop_id},.T.);")
+        bound_id = index; index += 1
+        data.append(f"#{index}=FACE('',(#{bound_id}));")
+        face_ids.append(index); index += 1
+    data.append(f"#{index}=CLOSED_SHELL('',({','.join(f'#{item}' for item in face_ids)}));")
+    shell_id = index; index += 1
+    data.append(f"#{index}=FACETED_BREP('{name}',#{shell_id});")
+    data.extend(("ENDSEC;", "END-ISO-10303-21;"))
+    atomic_write_text(output, "\n".join(data) + "\n")

hw_codesign/backends/__init__.py

@@ -0,0 +1 @@
+"""Deterministic backend adapters."""

hw_codesign/backends/atopile.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ..io import atomic_write_text, write_json
+from ..models import Failure, FailureCategory, GateReport, Status
+from ..provenance import artifact_provenance
+from .electronics import ElectronicsBackendAdapter
+
+_RAIL_NAMES = frozenset(("GND", "V3V3", "VCC", "V5", "VBAT"))
+_SIGNAL_RE = re.compile(r"^\s+signal\s+(\w+)", re.MULTILINE)
+
+_FOOTPRINT_DEFERRED = Failure(
+    FailureCategory.TOOL_ERROR,
+    "footprint_assignment_deferred",
+    "Atopile assigns footprints through the KiCad plugin at layout time, not at compile time",
+    details={"atopile_version": "0.15.7", "deferred_to": "kicad_plugin_layout"},
+)
+_LAYOUT_BLOCKED = Failure(
+    FailureCategory.TOOL_ERROR,
+    "kicad_plugin_required",
+    "Atopile layout and manufacturing export require the KiCad plugin; install KiCad and configure the atopile plugin path",
+    details={"atopile_version": "0.15.7", "blocked_on": "kicad_plugin_path"},
+)
+
+
+def _ato_source(module_name: str, graph: dict[str, Any]) -> str:
+    nets = [net["name"] for net in graph.get("nets", []) if net.get("name")]
+    rails = sorted({n for n in nets if n in _RAIL_NAMES})
+    signals = sorted({n.lower().replace(" ", "_").replace("-", "_") for n in nets if n not in _RAIL_NAMES})
+    components = graph.get("components", [])
+
+    lines = [f"module {module_name}:"]
+    if rails:
+        lines.append("    # Power rails")
+        for rail in rails:
+            lines.append(f"    signal {rail.lower()}")
+    if signals:
+        lines.append("    # Design signals")
+        for sig in signals:
+            lines.append(f"    signal {sig}")
+    if components:
+        lines.append("    # Component placeholders (populate imports from atopile package registry)")
+        for comp in components:
+            ref = comp.get("ref", "?")
+            mpn = comp.get("mpn") or comp.get("category", "unknown")
+            lines.append(f"    # {ref}: {mpn}")
+    return "\n".join(lines) + "\n"
+
+
+def _ato_declared_signals(source: str) -> set[str]:
+    return {m.group(1) for m in _SIGNAL_RE.finditer(source)}
+
+
+def _expected_ato_signals(graph: dict[str, Any]) -> set[str]:
+    nets = [net["name"] for net in graph.get("nets", []) if net.get("name")]
+    rails = {n.lower() for n in nets if n in _RAIL_NAMES}
+    signals = {n.lower().replace(" ", "_").replace("-", "_") for n in nets if n not in _RAIL_NAMES}
+    return rails | signals
+
+
+def _source_parity_gates(ato_file: Path, graph: dict[str, Any]) -> list[GateReport]:
+    source_text = ato_file.read_text(encoding="utf-8")
+    declared = _ato_declared_signals(source_text)
+    expected = _expected_ato_signals(graph)
+    missing = expected - declared
+    parity_failures = [
+        Failure(
+            FailureCategory.EDA_ERROR,
+            "ato_signal_missing",
+            f"Net {sig!r} in graph but absent from generated .ato source",
+            details={"missing_signal": sig},
+        )
+        for sig in sorted(missing)[:20]
+    ]
+    return [
+        GateReport(
+            "atopile_netlist_extract",
+            Status.PASS,
+            [],
+            metrics={"declared_signals": len(declared)},
+            artifacts=[str(ato_file)],
+            backend={"name": "atopile", "method": "source_ast_extraction"},
+        ),
+        GateReport(
+            "atopile_graph_parity",
+            Status.FAIL if parity_failures else Status.PASS,
+            parity_failures,
+            metrics={"declared": len(declared), "expected": len(expected), "missing": len(missing)},
+            backend={"name": "atopile", "method": "source_ast_parity"},
+        ),
+        GateReport("atopile_footprint_parity", Status.BLOCKED, [_FOOTPRINT_DEFERRED], backend={"name": "atopile"}),
+        GateReport("atopile_layout_completeness", Status.BLOCKED, [_LAYOUT_BLOCKED], backend={"name": "atopile"}),
+        GateReport("atopile_manufacturing_export", Status.BLOCKED, [_LAYOUT_BLOCKED], backend={"name": "atopile"}),
+    ]
+
+
+class AtopileBackend(ElectronicsBackendAdapter):
+    name = "atopile"
+
+    def __init__(self, platform_root: Path):
+        self.platform_root = platform_root
+
+    def generate_source(self, project: Path, spec: dict[str, Any], graph: dict[str, Any]) -> list[str]:
+        target = project / "electronics" / "source" / self.name
+        target.mkdir(parents=True, exist_ok=True)
+        project_name = spec.get("project", {}).get("name", project.name)
+        module_name = "".join(word.capitalize() for word in project_name.split("_")) or "Design"
+        ato_file = target / "design.ato"
+        atomic_write_text(ato_file, _ato_source(module_name, graph))
+        ato_yaml = target / "ato.yaml"
+        atomic_write_text(ato_yaml, "requires-atopile: \">=0.15.0\"\n")
+        manifest = target / "source_manifest.json"
+        write_json(manifest, {
+            "backend": self.name,
+            "backend_release_capable": True,
+            "source_release_eligible": True,
+            "release_tier": "hdl_source",
+            "netlist_release_eligible": False,
+            "hdl_source_release_eligible": True,
+            "fabrication_release_eligible": False,
+            "sources": self.source_entries(target, [ato_file, ato_yaml]),
+            "contract_gates": list(self.gate_names),
+            "release_blocking_gates": [
+                f"{self.name}_compile",
+                f"{self.name}_netlist_extract",
+                f"{self.name}_graph_parity",
+            ],
+            "provenance": artifact_provenance(
+                spec,
+                self.platform_root / "parts",
+                self.name,
+                command=[],
+                release_eligible=True,
+                release_tier="hdl_source",
+            ),
+        })
+        return [str(ato_file), str(ato_yaml), str(manifest)]
+
+    def evaluate(self, project: Path, graph: dict[str, Any]) -> list[GateReport]:
+        ato_bin = shutil.which("ato")
+        if not ato_bin:
+            compile_report = GateReport(
+                f"{self.name}_compile",
+                Status.BLOCKED,
+                [Failure(FailureCategory.TOOL_ERROR, "tool_unavailable", "atopile CLI not found; install with: brew install atopile")],
+                backend={"name": self.name},
+            )
+            return self.complete_contract([compile_report])
+        source_dir = project / "electronics" / "source" / self.name
+        ato_file = source_dir / "design.ato"
+        if not ato_file.is_file():
+            compile_report = GateReport(
+                f"{self.name}_compile",
+                Status.BLOCKED,
+                [Failure(FailureCategory.TOOL_ERROR, "source_not_generated", "Run generate_electronics first to produce atopile source")],
+                backend={"name": self.name},
+            )
+            return self.complete_contract([compile_report])
+
+        try:
+            result = subprocess.run(
+                [ato_bin, "build"],
+                cwd=source_dir,
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+        except subprocess.TimeoutExpired:
+            compile_report = GateReport(
+                f"{self.name}_compile",
+                Status.FAIL,
+                [Failure(FailureCategory.TOOL_ERROR, "build_timeout", "atopile build timed out after 60 seconds")],
+                backend={"name": self.name, "ato_bin": ato_bin},
+            )
+            return self.complete_contract([compile_report])
+        except OSError as exc:
+            compile_report = GateReport(
+                f"{self.name}_compile",
+                Status.BLOCKED,
+                [Failure(FailureCategory.TOOL_ERROR, "tool_unavailable", str(exc))],
+                backend={"name": self.name},
+            )
+            return self.complete_contract([compile_report])
+
+        stderr_text = (result.stdout + "\n" + result.stderr).strip()
+        if result.returncode == 0:
+            compile_report = GateReport(
+                f"{self.name}_compile",
+                Status.PASS,
+                [],
+                backend={"name": self.name, "ato_bin": ato_bin},
+            )
+            return self.complete_contract([compile_report, *_source_parity_gates(ato_file, graph)])
+        else:
+            compile_report = GateReport(
+                f"{self.name}_compile",
+                Status.FAIL,
+                [Failure(FailureCategory.EDA_ERROR, "build_failed", stderr_text[:1000])],
+                backend={"name": self.name, "ato_bin": ato_bin},
+            )
+            return self.complete_contract([compile_report])

hw_codesign/backends/command.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..models import Failure, FailureCategory, GateReport, Status
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    command: list[str]
+    returncode: int | None
+    stdout: str
+    stderr: str
+    available: bool
+
+
+def resolve_tool(executable: str) -> str | None:
+    resolved = shutil.which(executable)
+    if resolved is None and executable == "kicad-cli":
+        candidate = Path("/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli")
+        resolved = str(candidate) if candidate.is_file() else None
+    return resolved
+
+
+def resolve_kicad_python() -> str | None:
+    """Return path to KiCad's bundled Python for pcbnew scripting access."""
+    env_path = os.environ.get("HW_KICAD_PYTHON")
+    if env_path:
+        p = Path(env_path)
+        if p.is_file():
+            return str(p)
+    for candidate in [
+        Path("/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.9/bin/python3.9"),
+        Path("/usr/lib/kicad/lib/python3/dist-packages/../../../bin/python3"),
+    ]:
+        if candidate.is_file():
+            return str(candidate)
+    return None
+
+
+def tool_version(executable: str) -> str | None:
+    resolved = resolve_tool(executable)
+    if resolved is None:
+        return None
+    try:
+        timeout = float(os.environ.get("HW_TOOL_VERSION_TIMEOUT_SECONDS", "5"))
+    except ValueError:
+        timeout = 5.0
+    try:
+        completed = subprocess.run([resolved, "version"], capture_output=True, text=True, timeout=timeout, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return completed.stdout.strip() or completed.stderr.strip() or None
+
+
+def run_tool(executable: str, arguments: list[str], cwd: Path, timeout: int = 300, env: dict[str, str] | None = None) -> ToolResult:
+    resolved = resolve_tool(executable)
+    command = [executable, *arguments]
+    if resolved is None:
+        return ToolResult(command, None, "", f"Executable not found: {executable}", False)
+    try:
+        completed = subprocess.run([resolved, *arguments], cwd=cwd, capture_output=True, text=True, timeout=timeout, check=False, env={**os.environ, **(env or {})})
+        return ToolResult(command, completed.returncode, completed.stdout, completed.stderr, True)
+    except subprocess.TimeoutExpired:
+        return ToolResult(command, None, "", f"{executable} timed out after {timeout}s", False)
+
+
+def tool_report(gate: str, result: ToolResult, artifacts: list[str] | None = None) -> GateReport:
+    backend = {"command": result.command, "returncode": result.returncode, "stdout": result.stdout[-8000:], "stderr": result.stderr[-8000:], "available": result.available}
+    if not result.available:
+        failure = Failure(FailureCategory.TOOL_ERROR, "tool_unavailable", result.stderr, details={"command": result.command})
+        return GateReport(gate, Status.BLOCKED, [failure], backend=backend)
+    if result.returncode != 0:
+        failure = Failure(FailureCategory.TOOL_ERROR, "tool_failed", f"{result.command[0]} exited with status {result.returncode}", details=backend)
+        return GateReport(gate, Status.FAIL, [failure], backend=backend)
+    return GateReport(gate, Status.PASS, artifacts=artifacts or [], backend=backend)

hw_codesign/backends/electronics.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from hashlib import sha256
+from pathlib import Path
+from typing import Any
+
+from ..models import Failure, FailureCategory, GateReport, Status
+
+CONTRACT_STAGES = (
+    "compile",
+    "netlist_extract",
+    "graph_parity",
+    "footprint_parity",
+    "layout_completeness",
+    "manufacturing_export",
+)
+
+
+class ElectronicsBackendAdapter(ABC):
+    name: str
+
+    @property
+    def gate_names(self) -> tuple[str, ...]:
+        return tuple(f"{self.name}_{stage}" for stage in CONTRACT_STAGES)
+
+    @abstractmethod
+    def generate_source(self, project: Path, spec: dict[str, Any], graph: dict[str, Any]) -> list[str]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def evaluate(self, project: Path, graph: dict[str, Any]) -> list[GateReport]:
+        raise NotImplementedError
+
+    def blocked_contract(self, code: str, message: str, *, category: FailureCategory = FailureCategory.TOOL_ERROR) -> list[GateReport]:
+        failure = Failure(category, code, message)
+        return [GateReport(gate, Status.BLOCKED, [failure], backend={"name": self.name}) for gate in self.gate_names]
+
+    def complete_contract(self, reports: list[GateReport]) -> list[GateReport]:
+        by_gate = {report.gate: report for report in reports}
+        for gate in self.gate_names:
+            if gate not in by_gate:
+                by_gate[gate] = GateReport(
+                    gate,
+                    Status.BLOCKED,
+                    [Failure(FailureCategory.EDA_ERROR, "gate_not_run", f"Backend contract gate was not run: {gate}")],
+                    backend={"name": self.name},
+                )
+        return [by_gate[gate] for gate in self.gate_names]
+
+    @staticmethod
+    def source_entries(root: Path, paths: list[Path]) -> list[dict[str, str]]:
+        return [
+            {"path": path.relative_to(root).as_posix(), "sha256": sha256(path.read_bytes()).hexdigest()}
+            for path in sorted(paths)
+        ]
+
+    @staticmethod
+    def graph_netlist(graph: dict[str, Any]) -> dict[str, list[str]]:
+        return {item["name"]: sorted(item.get("connected_pins", [])) for item in graph.get("nets", [])}

hw_codesign/backends/firmware_modules/__init__.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from typing import Any
+
+from . import interface_stack, periodic_transmit, sensor_poll, state_machine, timeout_shutdown
+from ._base import ModuleOutput
+
+_RENDERERS = {
+    "timeout_shutdown": timeout_shutdown.render,
+    "periodic_transmit": periodic_transmit.render,
+    "state_machine": state_machine.render,
+    "sensor_poll": sensor_poll.render,
+    "interface_stack": interface_stack.render,
+}
+
+BEHAVIOR_DESCRIPTIONS: dict[str, str] = {
+    "timeout_shutdown": (
+        "Watchdog pattern: arms a timer on init; if not kicked within timeout_ms "
+        "or the trigger signal asserts, disables the specified outputs and asserts a fault pin."
+    ),
+    "periodic_transmit": (
+        "Scheduled frame transmit: sends a CAN/UART/I2C frame on a fixed interval. "
+        "Frame ID, DLC, and content are parametric."
+    ),
+    "state_machine": (
+        "Agent-specified state machine: states, transitions, and entry/exit actions are "
+        "parameterized; generates a thread-safe enum-based FSM."
+    ),
+    "sensor_poll": (
+        "Scheduled ADC/I2C/SPI read: polls a sensor every poll_interval_ms and writes "
+        "readings into a fixed-size ring buffer."
+    ),
+    "interface_stack": (
+        "Firmware stack binding: declares USB, QSPI/SPI, PIO, or similar stack ownership "
+        "over graph-grounded nets, required bring-up tests, and init order. It is an "
+        "interface contract stub, not behavior-level firmware proof."
+    ),
+}
+
+BEHAVIOR_SCHEMAS: dict[str, dict[str, Any]] = {
+    "timeout_shutdown": {
+        "type": "object",
+        "required": ["id", "behavior", "trigger", "action"],
+        "properties": {
+            "id":       {"type": "string", "description": "Module identifier (used as C symbol prefix and file name)"},
+            "behavior": {"type": "string", "const": "timeout_shutdown"},
+            "trigger": {
+                "type": "object",
+                "properties": {
+                    "signal":     {"type": "string", "description": "GPIO signal name from pinmap (e.g. ESTOP_IN)"},
+                    "timeout_ms": {"type": "integer", "description": "Watchdog timeout in milliseconds"},
+                },
+                "required": ["signal", "timeout_ms"],
+            },
+            "action": {
+                "type": "object",
+                "properties": {
+                    "disable_all": {"type": "string", "description": "Logical group to disable (e.g. motor_enables)"},
+                    "assert":      {"type": "string", "description": "Signal to assert on trigger (e.g. FAULT_LED)"},
+                },
+            },
+        },
+    },
+    "periodic_transmit": {
+        "type": "object",
+        "required": ["id", "behavior", "interval_ms", "frame"],
+        "properties": {
+            "id":          {"type": "string"},
+            "behavior":    {"type": "string", "const": "periodic_transmit"},
+            "interval_ms": {"type": "integer", "description": "Transmit interval in milliseconds"},
+            "transport":   {"type": "string", "enum": ["can", "uart", "i2c"], "default": "can"},
+            "frame": {
+                "type": "object",
+                "properties": {
+                    "id":      {"description": "Frame/register address (integer or hex string)"},
+                    "dlc":     {"type": "integer", "description": "Data length in bytes"},
+                    "content": {"type": "string", "description": "Logical content label (e.g. motor_status)"},
+                },
+                "required": ["id", "dlc"],
+            },
+        },
+    },
+    "state_machine": {
+        "type": "object",
+        "required": ["id", "behavior", "states", "transitions"],
+        "properties": {
+            "id":            {"type": "string"},
+            "behavior":      {"type": "string", "const": "state_machine"},
+            "initial_state": {"type": "string", "description": "Name of the initial state"},
+            "states": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "name":  {"type": "string"},
+                        "entry": {"type": ["string", "null"]},
+                        "exit":  {"type": ["string", "null"]},
+                    },
+                    "required": ["name"],
+                },
+            },
+            "transitions": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "from":    {"type": "string"},
+                        "to":      {"type": "string"},
+                        "trigger": {"type": "string"},
+                    },
+                    "required": ["from", "to", "trigger"],
+                },
+            },
+        },
+    },
+    "sensor_poll": {
+        "type": "object",
+        "required": ["id", "behavior"],
+        "properties": {
+            "id":               {"type": "string"},
+            "behavior":         {"type": "string", "const": "sensor_poll"},
+            "bus":              {"type": "string", "enum": ["i2c", "adc", "spi"], "default": "i2c"},
+            "sensor":           {"type": "string", "description": "Sensor label (e.g. imu, temperature)"},
+            "address":          {"type": "string", "description": "I2C address or SPI CS index (e.g. 0x68)"},
+            "poll_interval_ms": {"type": "integer", "default": 100},
+            "ring_buf_entries": {"type": "integer", "default": 16},
+        },
+    },
+    "interface_stack": {
+        "type": "object",
+        "required": ["id", "behavior", "stack", "required_nets"],
+        "properties": {
+            "id":                {"type": "string"},
+            "behavior":          {"type": "string", "const": "interface_stack"},
+            "stack":             {"type": "string", "description": "Firmware stack or peripheral family, e.g. usb, qspi, pio"},
+            "library":           {"type": "string", "description": "Implementation library or SDK binding, e.g. tinyusb, pico-sdk"},
+            "required_nets":     {"type": "array", "items": {"type": "string"}},
+            "required_tests":    {"type": "array", "items": {"type": "string"}},
+            "init_order":        {"type": "integer", "default": 50},
+            "stack_size_bytes":  {"type": "integer", "default": 1024},
+        },
+    },
+}
+
+
+def render_module(module: dict[str, Any]) -> ModuleOutput:
+    """Dispatch to the appropriate behavior renderer."""
+    behavior = module.get("behavior")
+    renderer = _RENDERERS.get(behavior)
+    if renderer is None:
+        raise ValueError(f"Unknown firmware module behavior: {behavior!r}. Available: {sorted(_RENDERERS)}")
+    return renderer(module)
+
+
+__all__ = [
+    "ModuleOutput",
+    "render_module",
+    "BEHAVIOR_DESCRIPTIONS",
+    "BEHAVIOR_SCHEMAS",
+    "_RENDERERS",
+]

hw_codesign/backends/firmware_modules/_base.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ModuleOutput:
+    id: str
+    behavior: str
+    c_source: str
+    h_source: str
+    dts_fragment: str | None = None
+    kconfig_flags: list[str] = field(default_factory=list)
+    stack_size_bytes: int = 2048
+    is_isr: bool = False