Consume OBC registry + shared firmware templates (Ecosystem Integration I1/I6)

hardware/registry.py: typed loader for the canonical registry.json exported
by Oh-Ben-Claw's emit-registry (bundled copy + OBC_REGISTRY_PATH override),
schema_version gate, name/USB/capability lookups, and platform_for_board
routing registry boards onto Accelerapp codegen platforms (every emitted
name pinned instantiable via get_platform).

firmware/obc_templates.py: consumer for the shared starter-sketch set from
emit-firmware-templates (template_for_board with node-id substitution;
codegen_route pairs the OBC node-protocol scaffold with the platform
generator). Both JSON documents packaged via package-data + MANIFEST.

25 pytest tests (registry 16, templates 9), incl. a templates-vs-registry
flashable-set drift guard.

Author: thewriterben

MANIFEST.in

@@ -2,5 +2,7 @@ include README.md
 include LICENSE
 include requirements.txt
 recursive-include src/accelerapp/templates *
+include src/accelerapp/hardware/registry.json
+include src/accelerapp/firmware/templates.json
 recursive-include examples *.yaml
 recursive-include docs *.md

pyproject.toml

@@ -64,6 +64,10 @@ Documentation = "https://github.com/thewriterben/Accelerapp/blob/main/README.md"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+"accelerapp.hardware" = ["registry.json"]
+"accelerapp.firmware" = ["templates.json"]
+
 [tool.pytest.ini_options]
 minversion = "7.0"
 testpaths = ["tests"]

src/accelerapp/firmware/__init__.py

@@ -4,5 +4,19 @@
 """
 
 from .generator import FirmwareGenerator
+from .obc_templates import (
+    FirmwareTemplate,
+    TemplatesSchemaError,
+    codegen_route,
+    load_templates,
+    template_for_board,
+)
 
-__all__ = ["FirmwareGenerator"]
+__all__ = [
+    "FirmwareGenerator",
+    "FirmwareTemplate",
+    "TemplatesSchemaError",
+    "codegen_route",
+    "load_templates",
+    "template_for_board",
+]

src/accelerapp/firmware/obc_templates.py

@@ -0,0 +1,123 @@
+"""
+OBC shared firmware templates — Ecosystem Integration I6.
+
+The canonical starter-sketch template set is generated by Oh-Ben-Claw's
+``emit-firmware-templates`` binary (one capability-conditioned Arduino sketch
+per flashable registry board) and bundled here as ``templates.json`` —
+refreshed alongside ``registry.json``::
+
+    # in Oh-Ben-Claw
+    cargo run --bin emit-firmware-templates -- firmware-templates/templates.json
+    cp firmware-templates/templates.json ../Accelerapp/src/accelerapp/firmware/templates.json
+
+Use :func:`template_for_board` for the OBC node-protocol scaffold, and
+:func:`codegen_route` to decide how Accelerapp should treat a registry board:
+start from the shared scaffold, route to one of Accelerapp's platform
+generators, or both.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from accelerapp.hardware.registry import Board, platform_for_board
+
+#: The templates.json schema this consumer understands (mirrors OBC's
+#: TEMPLATES_SCHEMA_VERSION).
+SUPPORTED_TEMPLATES_SCHEMA_VERSION = 1
+
+#: Environment variable overriding the bundled template document.
+TEMPLATES_PATH_ENV = "OBC_FIRMWARE_TEMPLATES_PATH"
+
+_BUNDLED = Path(__file__).parent / "templates.json"
+
+#: The node id baked into canonical templates, to be substituted per node.
+NODE_ID_PLACEHOLDER = "obc-node"
+
+
+class TemplatesSchemaError(RuntimeError):
+    """The template document's schema_version is unsupported."""
+
+
+@dataclass(frozen=True)
+class FirmwareTemplate:
+    """One canonical starter sketch for a flashable registry board."""
+
+    board: str
+    language: str
+    filename: str
+    source: str
+    capabilities: List[str]
+    vendor: str
+
+    def with_node_id(self, node_id: str) -> "FirmwareTemplate":
+        """The same template with the placeholder node id substituted."""
+        return FirmwareTemplate(
+            board=self.board,
+            language=self.language,
+            filename=self.filename,
+            source=self.source.replace(NODE_ID_PLACEHOLDER, node_id),
+            capabilities=self.capabilities,
+            vendor=self.vendor,
+        )
+
+
+def load_templates(path: Optional[os.PathLike] = None) -> List[FirmwareTemplate]:
+    """Load and validate the template document (path → env var → bundled)."""
+    resolved = Path(path) if path else Path(os.environ.get(TEMPLATES_PATH_ENV, _BUNDLED))
+    with open(resolved, encoding="utf-8") as f:
+        doc = json.load(f)
+
+    version = doc.get("schema_version")
+    if version != SUPPORTED_TEMPLATES_SCHEMA_VERSION:
+        raise TemplatesSchemaError(
+            f"templates.json schema_version {version!r} is not supported "
+            f"(this consumer understands {SUPPORTED_TEMPLATES_SCHEMA_VERSION})"
+        )
+
+    return [
+        FirmwareTemplate(
+            board=t["board"],
+            language=t.get("language", "arduino"),
+            filename=t["filename"],
+            source=t["source"],
+            capabilities=list(t.get("capabilities", [])),
+            vendor=t.get("vendor", ""),
+        )
+        for t in doc.get("templates", [])
+    ]
+
+
+@lru_cache(maxsize=1)
+def _bundled() -> List[FirmwareTemplate]:
+    return load_templates()
+
+
+def template_for_board(board_name: str, node_id: Optional[str] = None) -> Optional[FirmwareTemplate]:
+    """The shared OBC starter sketch for a board, optionally node-id'd."""
+    t = next((t for t in _bundled() if t.board == board_name), None)
+    if t is None:
+        return None
+    return t.with_node_id(node_id) if node_id else t
+
+
+def codegen_route(board: Board) -> Tuple[Optional[str], Optional[FirmwareTemplate]]:
+    """
+    How should Accelerapp generate firmware for this registry board?
+
+    Returns ``(platform_name, template)``:
+    - ``platform_name`` — an Accelerapp platform generator (``get_platform``)
+      when the board maps to one, else ``None``;
+    - ``template`` — the shared OBC node-protocol scaffold when the board is
+      flashable, else ``None``.
+
+    Typical use: start from the scaffold (correct OBC announce/command
+    skeleton), then generate platform-specific drivers with the platform
+    generator.
+    """
+    return platform_for_board(board), template_for_board(board.name)