tirtc-device-builder 0.2.0 → 0.4.0

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

@@ -1,49 +1,69 @@
 # 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:
+Hardware IR describes one exact board revision and product contract. It is the deterministic handoff from board evidence to capability assessment, generation, build, and HIL reporting.
+
+Create the current schema:
 
 ```bash
 python3 <skill-dir>/scripts/hardware_ir.py init <output>/hardware-ir.json
 ```
 
+The initializer creates schema v2. The validator still accepts schema v1 for existing H.264-only projects; update new or materially changed boards to v2.
+
 ## 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.
+- Reference source IDs from board facts, selected profiles, onboarding methods, resources, and runtime evidence.
+- Use `null` for unknown facts. Retain contradictory values as explicit issues instead of choosing silently.
+- Hardware revision `unspecified` is valid during intake but blocks reusable-board readiness.
+- Keep requested product features under `features.requested`; desired behavior is not hardware evidence.
+- Store concrete sensors, pins, clocks, codecs, slots, and task allocation in this board IR/adapter, never in generic Skill defaults.
 
 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.
+1. `extracted`: one source.
+2. `corroborated`: another authoritative artifact confirms it.
+3. `build_verified`: matching implementation builds with the locked toolchain.
+4. `hardware_verified`: the local peripheral works on the exact board revision.
+5. `hil_verified`: retained for legacy facts; schema v2 feature HIL additionally requires matching artifact evidence.
 
-## Minimum facts
+## Schema v2 contracts
 
 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.
+- exact board identity, module, Flash/PSRAM, ESP-IDF, TiRTC SDK and build contract;
+- camera identity evidence plus `video_profiles[]` and `selected_video_profile`;
+- audio input/output paths;
+- `hardware_resources` for I2C, I2S/GPIO ownership, audio channel mapping, camera realtime policy, and memory budget;
+- `onboarding.wifi_credentials` with selectable SoftAP/BLE/SmartConfig/factory/development/custom methods;
+- selectable ThingConnect binding methods plus stored-binding states and reset control;
+- requested features;
+- optional `runtime_evidence[]`, each bound to a full firmware SHA-256.
+
+The selected Wi-Fi method must be available and corroborated, credentials must remain outside tracked source, and reprovisioning must be defined. A board without SoftAP is valid when another selected method meets those conditions.
+
+The selected video profile controls assessment. An unselected H.264 fallback cannot make an MJPEG target pass, and missing H.264 cannot block an evidenced MJPEG target.
+
+## Artifact-bound HIL
+
+Run:
+
+```bash
+python3 <skill-dir>/scripts/hardware_ir.py assess hardware-ir.json \
+  --artifact-sha256 <64-character-sha256> --strict
+```
 
-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.
+H5 features require matching L5 evidence; AI requires matching L6 evidence. Evidence from an older firmware remains provenance but does not verify the current artifact.
 
 ## Intake quality
 
-Preferred input order:
+Preferred evidence 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.
+3. sensor, codec, amplifier and module datasheets;
+4. minimal peripheral projects built for that board;
+5. product pages, photographs and community material;
+6. artifact-bound boot, media and browser observations.
 
-A schematic establishes electrical connectivity, not driver maturity, encoding throughput, acoustic behavior, or end-to-end TiRTC compatibility. Preserve those as separate verification facts.
+A schematic establishes connectivity, not driver family compatibility, encoding throughput, acoustic behavior, provisioning usability, network performance, or end-to-end TiRTC operation. Preserve each as a separate fact and verification level.

package/skills/tirtc-esp32-builder/references/porting-risks.md

@@ -0,0 +1,49 @@
+# Board-porting risk gates
+
+Read this reference for every new board or failing media bring-up. It defines generic evidence gates; concrete values belong in the board's Hardware IR and adapter.
+
+## Freeze the contract before code
+
+Record the selected video profile, audio formats and stream IDs, duplex/AEC policy, onboarding method, platform-discovery transport, output path, and mutation authorization. Keep unknown values explicit. A server supporting several codecs does not select one for the device.
+
+## Hardware identity and ownership
+
+- Sensor and codec identity: reconcile schematic/BOM names with BSP probes or ID registers. Store every evidenced variant in an allowlist; retain contradictions as issues.
+- I2C: select one ESP-IDF driver family for the final image. Audit the linked ELF when third-party components can introduce another family; a conflict bypass is not a resolution.
+- I2S/audio: record controller, GPIO, master/slave mode, clocks, DMA, channel/TDM slot to physical-signal mapping, and shared-signal handoff. A codec name or I2C address does not prove the audio path.
+- Realtime camera path: record DMA/event queues, task core/priority, and competing Wi-Fi work. Treat queue overflows as scheduling or throughput evidence, then change one variable per HIL comparison.
+
+Turn every discovered invariant that can regress into a focused test or post-link gate. Generate board-specific values with the project; keep the Skill generic.
+
+## Wi-Fi credentials and device binding
+
+Wi-Fi provisioning and ThingConnect binding are separate state machines.
+
+Select one evidenced Wi-Fi credential method from SoftAP, BLE, SmartConfig, secure factory/NVS provisioning, development configuration, or a documented custom path. SoftAP is not mandatory. A board without AP provisioning can reach `READY_TO_PORT` through another available method when credentials remain outside source control and a reprovisioning path is defined.
+
+Development configuration may inject credentials through an untracked sdkconfig, environment, or provisioning artifact. Treat committed plaintext credentials as `BLOCKED`. Never copy SSIDs/passwords into Hardware IR, reports, examples, or source.
+
+Select the binding method from the applicable platform/product contract: verification code, factory-bound identity, development credentials, or a documented custom flow. When verification-code binding is selected, distinguish at least:
+
+- no Wi-Fi credentials;
+- Wi-Fi present but no device binding, so the verification-code flow runs;
+- stored binding present, so verification is skipped intentionally;
+- binding-only reset and Wi-Fi reset.
+
+For every method, keep device credentials outside source control, handle an already stored identity explicitly, and define binding reset/replacement behavior.
+
+## Startup memory, TLS, and transport
+
+Platform service discovery and the TiRTC SDK service endpoint are different settings. Record both. HTTPS requires valid time, DNS, certificate validation, TLS client/TLS 1.2, and enough contiguous internal memory.
+
+Before sizing TiRTC buffers, measure internal free/largest blocks, PSRAM, frame size distribution, queue watermarks, and send/drop rates. A larger queue can prevent drops, exhaust startup memory, or add buffer latency. If an authorized HTTP baseline exists, stage transport changes separately from media changes and retain the HTTPS requirements as a pending acceptance item.
+
+## Network and media evidence
+
+Disable Wi-Fi power saving for the realtime baseline unless the product contract says otherwise. Record BSSID, channel, RSSI, reconnect/roaming events, media counters, queue watermarks, camera overflows, internal heap, and largest block. Establish a strong, stable AP baseline before controlled weak-network testing.
+
+Confirm SDK send return semantics and callback payload lifetimes from the selected SDK version. Keep SDK callbacks bounded and copy payloads before returning.
+
+## Artifact discipline
+
+Record BIN/ELF SHA-256 for every build used in HIL. Runtime evidence applies only to the exact artifact. Diagnose one failing invariant, make the smallest correction, rerun that layer, and preserve the comparison in the report.

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

@@ -18,6 +18,10 @@ Use [the report template](../assets/report-template.md) and preserve separate `P
 
 ## 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.
+Record exact board revision, selected media, Wi-Fi, and binding profiles, 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.
+
+Runtime evidence belongs to one artifact. Label superseded artifacts and keep their observations as history; do not promote them to the current BIN/ELF. For HIL assessment, add the full SHA-256 to `runtime_evidence` and run `hardware_ir.py assess --artifact-sha256 <sha> --strict`.
+
+For L3-L7 media runs, capture the signals that distinguish software regressions from environment changes: onboarding/binding state, BSSID/channel/RSSI, reconnect or roaming events, audio/video send/receive/drop/error counters, queue watermarks, camera overflow count, internal heap/largest block, PSRAM, and measured latency when available. Never record credential values.
 
 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

@@ -19,11 +19,12 @@ The branch is complete when the new run has its own build and verification evide
 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.
+2. Freeze the user-supplied product contract: selected video profile, audio/stream formats, duplex/AEC policy, supported Wi-Fi credential methods, selected onboarding method, transport staging, output path, and mutation boundary. Use `unknown` where the prompt lacks an answer.
+3. 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.
+4. Cross-check critical pins, clocks, power enables, reset lines, sensor/codec variants, ESP-IDF version, resource ownership, and onboarding behavior across at least two independent artifacts when possible.
+5. Create the Hardware IR v2. Use `null` for unknown facts and retain contradictory values as an explicit issue instead of selecting one silently. Store concrete board values in the IR/adapter rather than Skill files.
+6. Validate and assess requested features. Ask only for unresolved facts that block the next safe step. SoftAP is optional when another evidenced Wi-Fi credential method is available, keeps credentials outside source, and defines reprovisioning.
+7. 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.
 
@@ -55,16 +56,16 @@ The runtime-facing `starter_media` interface stays stable. A reusable board inte
 
 The adapter owns:
 
-- camera capture and H.264 encoding tasks;
+- camera capture and the selected MJPEG/H.264/H.265 media path;
 - 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;
+- DMA buffers, hardware clocks, power, reset, GPIO, refresh/key-frame requests, and realtime task allocation;
 - 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.
+Use a bounded loop per layer: diagnose one failing invariant, make the smallest correction, and rerun that layer before moving forward. Change one high-risk variable per HIL comparison. Turn reusable invariants into tests or post-link gates. 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.
+Do not use successful compilation as evidence for camera frames, speaker output, Web rendering, AI audio, or long-run stability. Bind every runtime conclusion to the tested firmware SHA-256.

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

@@ -204,7 +204,7 @@ def resolve_sdk_dir(
         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 thing_connect_root / DEFAULT_SDK_RELATIVE_PATH, "Device Kit or legacy workspace"
     return None, "not found"
 
 
@@ -272,7 +272,7 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
     )
     checks.append(
         check(
-            "ThingConnect workspace",
+            "ESP32 Device Kit",
             workspace_status,
             (
                 f"{thing_connect_root} ({thing_connect_source})"
@@ -286,7 +286,7 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
     )
     if args.require_workspace and thing_connect_root is None:
         next_actions.append(
-            "Clone the public ThingConnect repository or pass its absolute path with "
+            "Run setup esp32 --install or pass an existing Device Kit path with "
             "--thing-connect-root."
         )
 
@@ -414,7 +414,7 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--require-workspace",
         action="store_true",
-        help="fail when a ThingConnect workspace with the ESP32 generator is unavailable",
+        help="fail when a Device Kit or legacy workspace with the ESP32 generator is unavailable",
     )
     parser.add_argument("--sdk-dir", type=Path)
     parser.add_argument("--project", type=Path)