tirtc-device-builder 0.2.0

package/skills/tirtc-esp32-builder/references/hardware-ir.md

@@ -0,0 +1,49 @@
+# Hardware IR
+
+Hardware IR is a generated, reviewable description of one exact board revision. It is the only input consumed by deterministic capability checks. Start from [the example](../assets/hardware-ir.example.json) with:
+
+```bash
+python3 <skill-dir>/scripts/hardware_ir.py init <output>/hardware-ir.json
+```
+
+## Evidence rules
+
+- Give every source a stable `id`, `kind`, `location`, and revision when available.
+- Reference those IDs from `soc`, `toolchain`, `camera`, `audio_input`, and `audio_output`.
+- Use `null` for unknown presence, pins, formats, or encoder properties. Empty strings are invalid facts.
+- Hardware revision `unspecified` is acceptable during intake but blocks registration as a reusable supported board.
+- Keep desired features under `features.requested`; do not encode wishes as hardware facts.
+- Record the strongest evidenced verification level, not the intended future state.
+
+Verification levels are ordered:
+
+1. `extracted`: obtained from one source.
+2. `corroborated`: confirmed by another authoritative artifact, such as schematic plus BSP.
+3. `build_verified`: the matching implementation builds with the locked toolchain.
+4. `hardware_verified`: the peripheral works on the exact physical revision.
+5. `hil_verified`: the requested H5/AI path passes end to end.
+
+## Minimum facts
+
+The IR contains:
+
+- exact board identity and revision;
+- SoC target, module, Flash, and PSRAM;
+- ESP-IDF and TiRTC SDK platform/version/build contract plus their verification level;
+- camera presence, sensor/interface, and H.264 output/key-frame properties;
+- audio input and output presence, interface, codecs, sample rates, and verification;
+- requested ThingConnect feature IDs.
+
+Pin and driver details may live in a board adapter manifest referenced from the IR once the adapter exists. Until then, missing pins remain capability issues even if the high-level media path appears possible.
+
+## Intake quality
+
+Preferred input order:
+
+1. exact schematic/netlist and BOM for the physical revision;
+2. official BSP pinned to a commit or release;
+3. sensor, codec, amplifier, and module datasheets;
+4. a minimal project that has been built for the board;
+5. product pages, README files, photographs, and community material.
+
+A schematic establishes electrical connectivity, not driver maturity, encoding throughput, acoustic behavior, or end-to-end TiRTC compatibility. Preserve those as separate verification facts.

package/skills/tirtc-esp32-builder/references/reporting.md

@@ -0,0 +1,23 @@
+# Reporting and acceptance
+
+Use [the report template](../assets/report-template.md) and preserve separate `PASS`, `FAIL`, and `SKIP` results.
+
+## Acceptance levels
+
+| Level | Completion evidence |
+|---|---|
+| L-1 Environment | ESP-IDF version, target compiler, TiRTC SDK, build contract, and requested serial access pass doctor checks |
+| L0 Generate | Project and Hardware IR exist; no existing output was overwritten |
+| L1 Build | Hardware IR valid, SDK contract checked, `idf.py build` succeeds, artifacts recorded |
+| L2 Boot | Exact chip/port resolved, flash succeeds, firmware boots without panic |
+| L3 Online | Wi-Fi provisioning, binding, MQTT, and TiRTC reach ready state |
+| L4 Media | Camera/microphone/speaker local paths work and counters/measurements are captured |
+| L5 H5 | Browser receives the declared video/audio and talkback reaches the device |
+| L6 AI | Token, WHIP, `start_session`, bidirectional audio, stop, and H5 recovery work |
+| L7 Stability | Requested weak-network, repeated-session, resource, and soak criteria pass |
+
+## Evidence
+
+Record exact board revision, toolchain and SDK versions, source/adapter revisions, commands, return codes, firmware size and SHA-256, serial port/chip, sanitized log paths, browser or platform observations, and every unavailable dependency.
+
+Reports describe observed current behavior. A `SKIP` caused by missing hardware, account, service, browser, or external network does not become a pass. If the user's requested completion level includes a skipped critical case, the final outcome remains incomplete.

package/skills/tirtc-esp32-builder/references/workflow.md

@@ -0,0 +1,70 @@
+# Workflow
+
+## Select one branch
+
+### Registered board
+
+Use this branch when a board and exact hardware revision already have a Hardware IR plus a matching board media adapter.
+
+1. Validate and assess the saved Hardware IR against the requested features.
+2. Confirm that its BSP, ESP-IDF, TiRTC SDK, and adapter revisions are still resolvable.
+3. Generate a new starter project without overwriting an existing path.
+4. Install the matching board adapter and configuration overlay.
+5. Build, optionally flash, execute the requested acceptance levels, and issue a fresh report.
+
+The branch is complete when the new run has its own build and verification evidence; an older board report is provenance, not proof of the new artifact.
+
+### New-board intake
+
+Use this branch when the user supplies a board model, vendor URL, schematic, BOM, pin map, BSP, datasheets, photographs, or peripheral example projects without a verified adapter.
+
+1. Resolve the full model, module, PCB marking, and hardware revision. Treat different revisions as different boards.
+2. Prefer official schematic/BOM and BSP facts. For a PDF schematic, inspect page labels and net names; prefer an exported netlist, pin CSV, or vendor board definition when available.
+3. Cross-check critical pins, clocks, power enables, reset lines, sensor/codec variants, and ESP-IDF version across at least two independent artifacts when possible.
+4. Create the Hardware IR. Use `null` for unknown facts and retain contradictory values as an explicit issue instead of selecting one silently.
+5. Validate and assess requested features. Ask only for unresolved facts that block the next safe step.
+6. When all requirements reach `READY_TO_PORT`, generate the starter and implement the board adapter. When requirements remain blocked, generate only the IR, capability report, and an optional compile-safe skeleton if requested.
+
+The branch is complete when every supplied artifact maps to an IR fact, provenance entry, contradiction, or declared irrelevant item.
+
+### Existing project
+
+Use this branch when the user supplies an ESP-IDF/BSP project instead of board documents.
+
+1. Inspect its target, `sdkconfig`, partitions, component manifests/CMake, pin definitions, sensor and codec initialization, and working peripheral examples.
+2. Build the existing minimal peripheral examples when the environment permits; code that compiles for a named target is stronger evidence than prose but does not prove hardware behavior.
+3. Create the Hardware IR from the project and any companion hardware documents.
+4. Preserve reusable vendor drivers behind the board adapter. Keep product UI and board code out of ThingConnect session/TiRTC modules.
+
+The branch is complete when the reused and replaced parts are explicit and the original project remains intact unless the user requested in-place work.
+
+## Repository document routing
+
+Read only the documents for the active branch, but read each selected document completely.
+
+- ESP32 starter or adapter work: `device-sim/device-sim-esp32/README.md`, `device-sim/ESP32_STARTER.md`, the selected SDK package README, and the generated template README.
+- H5 live view or talkback: `device-h5-live.md`.
+- AI intercom: `device-ai.md`.
+- H5/AI switching, delayed callbacks, ownership, or timeouts: `device-session-model.md` and `device-session-arbiter.md`.
+- Onboarding, binding, MQTT, token, or identity: `device-integration.md`.
+- Public HTTP field or error changes: `api-reference.md` and `error-response-policy.md`.
+
+## Generation and board seam
+
+The runtime-facing `starter_media` interface stays stable. A reusable board integration should implement an internal `BoardMediaAdapterV1`-style adapter owned by `starter_media` rather than editing H5, AI, `starter_runtime`, or `starter_tirtc` for each board.
+
+The adapter owns:
+
+- camera capture and H.264 encoding tasks;
+- microphone capture and audio encoding;
+- downlink audio decode, buffering, codec, amplifier, and I2S playback;
+- DMA buffers, hardware clocks, power, reset, GPIO, and key-frame requests;
+- bounded stop, resource release, and generation-aware flushing.
+
+The stable modules own stream IDs, negotiated/contracted formats, TiRTC callback copying, connection handles, session generation, and H5/AI sequencing.
+
+## Verification loop
+
+Use a bounded loop per layer: diagnose one failing invariant, make the smallest correction, and rerun that layer before moving forward. Stop and report when the remaining failure requires unavailable hardware, credentials, a new SDK binary, a public protocol change, or a user choice.
+
+Do not use successful compilation as evidence for camera frames, speaker output, Web rendering, AI audio, or long-run stability.

package/skills/tirtc-esp32-builder/scripts/doctor.py

@@ -0,0 +1,441 @@
+#!/usr/bin/env python3
+"""Diagnose an ESP-IDF and TiRTC ESP32 build environment."""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+VERSION_PATTERN = re.compile(r"(?:ESP-IDF\s+)?v?(\d+)\.(\d+)(?:\.(\d+))?", re.I)
+CONTRACT_KEYS = {
+    "CONFIG_FREERTOS_HZ",
+    "CONFIG_FREERTOS_USE_TRACE_FACILITY",
+    "CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS",
+    "CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS",
+}
+THING_CONNECT_ENV = "TIRTC_THING_CONNECT_ROOT"
+GENERATOR_RELATIVE_PATH = Path("device-sim/scripts/create_esp32_project.py")
+DEFAULT_SDK_RELATIVE_PATH = Path(
+    "device-sim/sdk/espressif-esp32s3/2.3.0"
+)
+
+
+def check(name: str, status: str, detail: str, required: bool = True) -> dict[str, Any]:
+    return {
+        "name": name,
+        "status": status,
+        "required": required,
+        "detail": detail,
+    }
+
+
+def parse_version(text: str) -> tuple[int, ...] | None:
+    match = VERSION_PATTERN.search(text)
+    if match is None:
+        return None
+    parts = [int(match.group(1)), int(match.group(2))]
+    if match.group(3) is not None:
+        parts.append(int(match.group(3)))
+    return tuple(parts)
+
+
+def version_matches(actual: tuple[int, ...] | None, expected: str) -> bool:
+    if actual is None:
+        return False
+    expected_match = re.fullmatch(r"v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:\.x)?", expected)
+    if expected_match is None:
+        raise ValueError(f"invalid expected ESP-IDF version: {expected}")
+    expected_parts = tuple(
+        int(part) for part in expected_match.groups() if part is not None
+    )
+    return actual[: len(expected_parts)] == expected_parts
+
+
+def run_version(command: list[str]) -> tuple[int, str]:
+    try:
+        completed = subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return 1, str(exc)
+    output = "\n".join(part for part in (completed.stdout, completed.stderr) if part)
+    return completed.returncode, output.strip()
+
+
+def find_idf(explicit: Path | None) -> tuple[Path | None, str]:
+    if explicit is not None:
+        return explicit.resolve(), "explicit --idf-py"
+    on_path = shutil.which("idf.py")
+    if on_path:
+        return Path(on_path).resolve(), "PATH"
+    idf_path = os.environ.get("IDF_PATH")
+    if idf_path:
+        candidate = Path(idf_path).expanduser() / "tools" / "idf.py"
+        if candidate.is_file():
+            return candidate.resolve(), "IDF_PATH"
+    return None, "not found"
+
+
+def parse_env_file(path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip().strip('"')
+    return values
+
+
+def parse_kconfig(path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    unset_pattern = re.compile(r"#\s+(CONFIG_[A-Z0-9_]+)\s+is not set")
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        unset = unset_pattern.fullmatch(line)
+        if unset:
+            values[unset.group(1)] = "off"
+        elif line.startswith("CONFIG_") and "=" in line:
+            key, value = line.split("=", 1)
+            normalized = value.strip().strip('"')
+            values[key] = "on" if normalized == "y" else normalized
+    return values
+
+
+def compare_contract(
+    contract: dict[str, str], config: dict[str, str]
+) -> list[str]:
+    mismatches: list[str] = []
+    for key in sorted(CONTRACT_KEYS):
+        expected = contract.get(key)
+        actual = config.get(key)
+        if expected is None:
+            mismatches.append(f"SDK contract does not declare {key}")
+        elif actual is None:
+            mismatches.append(f"project does not explicitly configure {key}={expected}")
+        elif actual.lower() != expected.lower():
+            mismatches.append(f"{key}: expected {expected}, got {actual}")
+    return mismatches
+
+
+def compiler_name(target: str) -> str:
+    names = {
+        "esp32s3": "xtensa-esp32s3-elf-gcc",
+        "esp32": "xtensa-esp32-elf-gcc",
+        "esp32c3": "riscv32-esp-elf-gcc",
+        "esp32c6": "riscv32-esp-elf-gcc",
+        "esp32p4": "riscv32-esp-elf-gcc",
+    }
+    return names.get(target, "")
+
+
+def discover_serial_ports() -> list[str]:
+    if os.name == "nt":
+        return []
+    ports: list[str] = []
+    for pattern in ("/dev/ttyACM*", "/dev/ttyUSB*", "/dev/cu.usb*"):
+        ports.extend(glob.glob(pattern))
+    return sorted(set(ports))
+
+
+def normalize_thing_connect_root(candidate: Path) -> Path | None:
+    """Accept either the ThingConnect directory or its parent repository."""
+    resolved = candidate.expanduser().resolve()
+    for root in (resolved, resolved / "thing-connect"):
+        if (root / GENERATOR_RELATIVE_PATH).is_file():
+            return root
+    return None
+
+
+def find_thing_connect_root(
+    explicit: Path | None,
+    project: Path | None,
+    *,
+    cwd: Path | None = None,
+) -> tuple[Path | None, str]:
+    if explicit is not None:
+        return normalize_thing_connect_root(explicit), "explicit --thing-connect-root"
+
+    from_environment = os.environ.get(THING_CONNECT_ENV)
+    if from_environment:
+        return (
+            normalize_thing_connect_root(Path(from_environment)),
+            THING_CONNECT_ENV,
+        )
+
+    search_starts = [path for path in (project, cwd or Path.cwd()) if path is not None]
+    seen: set[Path] = set()
+    for start in search_starts:
+        resolved = start.expanduser().resolve()
+        if resolved.is_file():
+            resolved = resolved.parent
+        for candidate in (resolved, *resolved.parents):
+            if candidate in seen:
+                continue
+            seen.add(candidate)
+            root = normalize_thing_connect_root(candidate)
+            if root is not None:
+                return root, f"discovered from {start}"
+    return None, "not found"
+
+
+def resolve_sdk_dir(
+    explicit: Path | None,
+    project: Path | None,
+    thing_connect_root: Path | None,
+) -> tuple[Path | None, str]:
+    if explicit is not None:
+        return explicit.expanduser().resolve(), "explicit --sdk-dir"
+    if project is not None:
+        bundled = project.expanduser().resolve() / "third_party" / "tirtc"
+        if bundled.is_dir():
+            return bundled, "generated project"
+    if thing_connect_root is not None:
+        return thing_connect_root / DEFAULT_SDK_RELATIVE_PATH, "ThingConnect workspace"
+    return None, "not found"
+
+
+def diagnose(args: argparse.Namespace) -> dict[str, Any]:
+    checks: list[dict[str, Any]] = []
+    next_actions: list[str] = []
+
+    checks.append(check("python3", "PASS", sys.version.split()[0]))
+    for tool, required in (("git", True), ("cmake", False), ("ninja", False)):
+        location = shutil.which(tool)
+        status = "PASS" if location else ("FAIL" if required else "WARN")
+        checks.append(check(tool, status, location or "not found", required))
+
+    idf_path, idf_source = find_idf(args.idf_py)
+    if idf_path is None or not idf_path.is_file():
+        checks.append(check("idf.py", "FAIL", "not found in PATH or IDF_PATH"))
+        next_actions.append(
+            f"Install or activate an official ESP-IDF {args.expected_idf}.x environment, then rerun doctor."
+        )
+    else:
+        command = [str(idf_path), "--version"]
+        if idf_path.suffix == ".py" and not os.access(idf_path, os.X_OK):
+            command.insert(0, sys.executable)
+        returncode, output = run_version(command)
+        actual = parse_version(output)
+        if returncode != 0:
+            status = "FAIL"
+            detail = f"{idf_path} failed: {output or f'exit {returncode}'}"
+        elif not version_matches(actual, args.expected_idf):
+            status = "FAIL"
+            detail = f"{output}; expected {args.expected_idf}.x"
+        else:
+            status = "PASS"
+            detail = f"{output} ({idf_source}: {idf_path})"
+        checks.append(check("idf.py", status, detail))
+        if idf_source == "IDF_PATH" and shutil.which("idf.py") is None:
+            checks.append(
+                check(
+                    "idf activation",
+                    "FAIL",
+                    "IDF_PATH contains idf.py but the current shell is not exported",
+                )
+            )
+            next_actions.append("Activate the existing IDF_PATH installation; do not install a duplicate copy.")
+
+    compiler = compiler_name(args.target)
+    if compiler:
+        compiler_path = shutil.which(compiler)
+        checks.append(
+            check(
+                "target compiler",
+                "PASS" if compiler_path else "FAIL",
+                compiler_path or f"{compiler} not found; ESP-IDF environment may be inactive",
+            )
+        )
+    else:
+        checks.append(check("target compiler", "FAIL", f"unsupported target {args.target}"))
+
+    thing_connect_root, thing_connect_source = find_thing_connect_root(
+        args.thing_connect_root,
+        args.project,
+    )
+    workspace_status = "PASS" if thing_connect_root else (
+        "FAIL" if args.require_workspace else "WARN"
+    )
+    checks.append(
+        check(
+            "ThingConnect workspace",
+            workspace_status,
+            (
+                f"{thing_connect_root} ({thing_connect_source})"
+                if thing_connect_root
+                else (
+                    f"not found; pass --thing-connect-root or set {THING_CONNECT_ENV}"
+                )
+            ),
+            required=args.require_workspace,
+        )
+    )
+    if args.require_workspace and thing_connect_root is None:
+        next_actions.append(
+            "Clone the public ThingConnect repository or pass its absolute path with "
+            "--thing-connect-root."
+        )
+
+    sdk_dir, sdk_source = resolve_sdk_dir(
+        args.sdk_dir,
+        args.project,
+        thing_connect_root,
+    )
+    if sdk_dir is None:
+        sdk_files: list[Path] = []
+        missing_sdk = [
+            "SDK location unresolved; pass --sdk-dir, --project, or --thing-connect-root"
+        ]
+        sdk_detail = missing_sdk[0]
+    else:
+        sdk_files = [
+            sdk_dir / "include" / "tirtc" / "tiRTC.h",
+            sdk_dir / "lib" / "libTiRTC.a",
+            sdk_dir / "manifest" / "build-contract.env",
+        ]
+        missing_sdk = [str(path) for path in sdk_files if not path.is_file()]
+        sdk_detail = (
+            "missing: " + ", ".join(missing_sdk)
+            if missing_sdk
+            else f"{sdk_dir} ({sdk_source})"
+        )
+    checks.append(
+        check(
+            "TiRTC SDK",
+            "FAIL" if missing_sdk else "PASS",
+            sdk_detail,
+        )
+    )
+
+    if args.project is not None:
+        project = args.project.resolve()
+        config_path = project / "sdkconfig"
+        if not config_path.is_file():
+            config_path = project / "sdkconfig.defaults"
+        contract_path = (
+            sdk_dir / "manifest" / "build-contract.env"
+            if sdk_dir is not None
+            else None
+        )
+        if not config_path.is_file():
+            checks.append(
+                check(
+                    "TiRTC build contract",
+                    "FAIL",
+                    f"no sdkconfig or sdkconfig.defaults in {project}",
+                )
+            )
+        elif contract_path is None or not contract_path.is_file():
+            detail = (
+                "TiRTC SDK location is unresolved"
+                if contract_path is None
+                else f"missing {contract_path}"
+            )
+            checks.append(check("TiRTC build contract", "FAIL", detail))
+        else:
+            mismatches = compare_contract(
+                parse_env_file(contract_path), parse_kconfig(config_path)
+            )
+            checks.append(
+                check(
+                    "TiRTC build contract",
+                    "FAIL" if mismatches else "PASS",
+                    "; ".join(mismatches) if mismatches else f"matches {config_path}",
+                )
+            )
+
+    ports = discover_serial_ports()
+    if args.serial_port:
+        serial = Path(args.serial_port)
+        if serial.exists() and os.access(serial, os.R_OK | os.W_OK):
+            serial_status, serial_detail = "PASS", f"{serial} is readable and writable"
+        elif serial.exists():
+            serial_status, serial_detail = "FAIL", f"{serial} lacks read/write permission"
+        else:
+            serial_status, serial_detail = "FAIL", f"{serial} does not exist"
+        checks.append(check("serial port", serial_status, serial_detail))
+    else:
+        checks.append(
+            check(
+                "serial discovery",
+                "PASS" if ports else "WARN",
+                ", ".join(ports) if ports else "no serial device detected",
+                required=False,
+            )
+        )
+
+    overall = "FAIL" if any(
+        item["required"] and item["status"] == "FAIL" for item in checks
+    ) else "PASS"
+    return {
+        "overall": overall,
+        "expected_idf": args.expected_idf,
+        "target": args.target,
+        "thing_connect_root": (
+            str(thing_connect_root) if thing_connect_root is not None else None
+        ),
+        "sdk_dir": str(sdk_dir) if sdk_dir is not None else None,
+        "checks": checks,
+        "next_actions": next_actions,
+    }
+
+
+def print_human(result: dict[str, Any]) -> None:
+    for item in result["checks"]:
+        suffix = " [required]" if item["required"] else ""
+        print(f"{item['status']:4} {item['name']}{suffix}: {item['detail']}")
+    print(f"OVERALL: {result['overall']}")
+    for action in result["next_actions"]:
+        print(f"NEXT: {action}")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Check ESP-IDF, target tools, TiRTC SDK, project contract, and serial access."
+    )
+    parser.add_argument("--expected-idf", default="5.5")
+    parser.add_argument("--target", default="esp32s3")
+    parser.add_argument("--idf-py", type=Path)
+    parser.add_argument("--thing-connect-root", type=Path)
+    parser.add_argument(
+        "--require-workspace",
+        action="store_true",
+        help="fail when a ThingConnect workspace with the ESP32 generator is unavailable",
+    )
+    parser.add_argument("--sdk-dir", type=Path)
+    parser.add_argument("--project", type=Path)
+    parser.add_argument("--serial-port")
+    parser.add_argument("--json", action="store_true")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        result = diagnose(args)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print_human(result)
+    return 0 if result["overall"] == "PASS" else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())