tirtc-device-builder 0.9.7 → 0.10.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.9.7",
+  "version": "0.10.0",
   "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
   "author": {
     "name": "TangeAI",

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 This project follows Semantic Versioning.
 
+## 0.10.0
+
+- Align the Kit's provisioning and device-binding implementation with the
+  reference XiaoTai product firmware (ships in the ESP32-S3 Device Kit
+  1.2.0 release, tagged separately):
+  - Wi-Fi provisioning: the embedded setup page gains a live scan list
+    (`POST /api/scan`, `GET /api/networks`), saved-network history with
+    `use_saved` password reuse, portal isolation to the SoftAP interface and
+    Origin checks on writes, exponential retry (1/2/4/8/15/30 s) with the
+    portal opened alongside retries after 5 consecutive failures, a manual
+    `wifi-change` entrance that retains credentials, and a station fallback
+    DNS slot (`CONFIG_WIFI_MANAGER_FALLBACK_DNS_IPV4`, default 223.5.5.5).
+  - Device binding: fresh-boot SNTP is required before any authentication;
+    the verification-code TTS endpoint (`GET /v1/device/tts`) is supported
+    behind a prompt callback (NULL by default; headless devices keep the
+    serial code); binding failures and rebinds can be retried without a
+    reboot (`bind-retry`); an `unbind` signal or a 6006 token response now
+    triggers identity reconciliation and a signed rebind that retains the
+    stored identity instead of clearing NVS and restarting.
+  - Shared components (`wifi_manager`, `platform_client`, `runtime_config`)
+    keep dual-target ESP32-S3/ESP32-P4 conditionals so future P4 ports can
+    reuse them unchanged.
+- Extend the Kit packing contract and generator tests to cover the new
+  portal endpoints, history component, embedded setup page, and portal
+  isolation; keep the `XiaoTai-` / open-auth / 192.168.6.1 SoftAP contract.
+- Add the ESP32-P4 Device Kit: TiRTC P4 SDK 2.5.0 (vendor baseline
+  `9b4e35c7`, IDF 5.5.4 / 1000 Hz / LWIP_MAX_SOCKETS=10 contract), the
+  XiaoTai P4 1.4.0 reference firmware imported as `device-sim-p4` (shared
+  transport components resolve from the S3 reference; the P4 `tirtc_sdk`
+  wrapper re-pins the archive), generator `--target esp32p4` copy mode,
+  per-target pack/metadata/installer plumbing, a `publish-p4` release job
+  that fails until the P4 kit is pinned, and P4-aware Doctor SDK resolution
+  and contract keys. Managed `setup` stays ESP32-S3-only.
+- Device Kit releases (1.2.0 for S3, 1.0.0 for P4) and checksum pinning
+  are deferred to their release workflows; no sha256 is fabricated in this
+  changelog. Until the S3 Kit 1.2.0 is tagged, managed setup keeps
+  installing the pinned 1.1.7 Kit.
+
 ## 0.9.7
 
 - Pin ESP32-S3 Device Kit 1.1.7 with the `XiaoTai-` SoftAP name and the

package/README.md

@@ -8,11 +8,12 @@ TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 开发板接入 TiRTC。输入
 |---|---|---|
 | `tirtc-esp32-builder` | ESP32-S3 / ESP32-P4、ESP-IDF 5.5.x | 板型识别、Hardware IR、工程生成/移植、H5/AI/设备互呼/微信 VoIP、AEC 门禁、编译烧录和分层验收 |
 
-H5/AI 的 ESP32-S3 托管模板、协议文档和 TiRTC SDK 已打包在独立的 ESP32 Device Kit 中，安装时会自动下载并校验。ESP32 示例源码由本仓库的 `kit-src/` 维护；设备互呼或微信 VoIP 的移植可参考其中的独立示例。ESP32-P4 必须使用匹配的 P4 SDK、BSP 与网络方案，不能复用 S3 预编译库。
+H5/AI 的 ESP32-S3 托管模板、协议文档和 TiRTC SDK 已打包在独立的 ESP32 Device Kit 中，安装时会自动下载并校验。ESP32 示例源码由本仓库的 `kit-src/` 维护；设备互呼或微信 VoIP 的移植可参考其中的独立示例。ESP32-P4 使用独立发布的 `tirtc-esp32p4-kit`（小钛 P4 参考固件：hosted C6 Wi-Fi + LVGL UI + 摄像头 + P4 SDK 2.5.0），通过生成器 `--target esp32p4` 复制生成，不能复用 S3 预编译库。
 
 - npm 包：[tirtc-device-builder](https://www.npmjs.com/package/tirtc-device-builder)
 - GitHub 仓库：[tangeai/tirtc-device-builder](https://github.com/tangeai/tirtc-device-builder)
 - ESP32 Device Kit：[kit-esp32s3-v1.1.7](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.7)
+- ESP32-P4 Device Kit：`tirtc-esp32p4-kit`（首次发布前以 `kit-esp32p4-v*` tag 发布的 GitHub Release 为准）
 
 文档导航：
 

package/bin/esp32-kit-metadata.js

@@ -1,4 +1,6 @@
 export const ESP32_KIT = Object.freeze({
+  target: "esp32s3",
+  platform: "espressif-esp32s3",
   archiveName: "tirtc-esp32s3-kit-1.1.7.tar.gz",
   archiveRoot: "tirtc-esp32s3-kit-1.1.7",
   releaseTag: "kit-esp32s3-v1.1.7",
@@ -7,4 +9,29 @@ export const ESP32_KIT = Object.freeze({
   sourceCommit: "50be0b4b6ad83ca376e010ebb7256db4fb6debcd",
   url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.1.7/tirtc-esp32s3-kit-1.1.7.tar.gz",
   version: "1.1.7",
+  released: true,
+});
+
+/*
+ * The ESP32-P4 Device Kit is pinned by its first release. Until the release
+ * workflow publishes and pins it, sha256/sourceCommit/url stay null and the
+ * publish-p4 job fails any premature kit-esp32p4-v* tag. Nothing is fabricated.
+ */
+export const ESP32_P4_KIT = Object.freeze({
+  target: "esp32p4",
+  platform: "espressif-esp32p4",
+  archiveName: "tirtc-esp32p4-kit-1.0.0.tar.gz",
+  archiveRoot: "tirtc-esp32p4-kit-1.0.0",
+  releaseTag: "kit-esp32p4-v1.0.0",
+  sha256: null,
+  sdkVersion: "2.5.0",
+  sourceCommit: null,
+  url: null,
+  version: "1.0.0",
+  released: false,
+});
+
+export const ESP32_KITS = Object.freeze({
+  esp32s3: ESP32_KIT,
+  esp32p4: ESP32_P4_KIT,
 });

package/bin/install-esp32-kit.js

@@ -16,15 +16,30 @@ import {
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ESP32_KIT } from "./esp32-kit-metadata.js";
+import { ESP32_KIT, ESP32_KITS } from "./esp32-kit-metadata.js";
 
-const REQUIRED_FILES = [
-  "manifest.json",
-  "device-sim/scripts/create_esp32_project.py",
-  "device-sim/templates/esp32-h5-ai/CMakeLists.txt",
-  "device-sim/templates/esp32-h5-ai/platform-media-contract.json",
-  "device-sim/templates/esp32-h5-ai/tirtc-runtime-contract.json",
-];
+const REQUIRED_FILES_BY_TARGET = {
+  esp32s3: [
+    "manifest.json",
+    "device-sim/scripts/create_esp32_project.py",
+    "device-sim/templates/esp32-h5-ai/CMakeLists.txt",
+    "device-sim/templates/esp32-h5-ai/platform-media-contract.json",
+    "device-sim/templates/esp32-h5-ai/tirtc-runtime-contract.json",
+  ],
+  esp32p4: [
+    "manifest.json",
+    "device-sim/scripts/create_esp32_project.py",
+    "device-sim/device-sim-p4/CMakeLists.txt",
+    "device-sim/device-sim-p4/sdkconfig.defaults",
+    "device-sim/device-sim-p4/dependencies.lock",
+    "device-sim/device-sim-esp32/components/wifi_manager/src/wifi_manager.c",
+  ],
+};
+
+const SDK_VERSION_PATTERN_BY_TARGET = {
+  esp32s3: /^(?:2\.3\.0|2\.5\.0)$/,
+  esp32p4: /^2\.5\.0$/,
+};
 
 function hashFile(path) {
   return createHash("sha256").update(readFileSync(path)).digest("hex");
@@ -77,7 +92,8 @@ function assertNoLinks(root, current = root) {
 }
 
 function validateExtractedKit(root, metadata) {
-  const missing = REQUIRED_FILES.filter((path) => !existsSync(join(root, path)));
+  const requiredFiles = REQUIRED_FILES_BY_TARGET[metadata.target] ?? [];
+  const missing = requiredFiles.filter((path) => !existsSync(join(root, path)));
   if (missing.length > 0) {
     throw new Error(`Device Kit is incomplete: ${missing.join(", ")}`);
   }
@@ -95,12 +111,15 @@ function validateExtractedKit(root, metadata) {
       `Device Kit version mismatch: expected ${metadata.version}, got ${manifest.kit_version}`,
     );
   }
-  if (manifest.target !== "esp32s3" ||
-      !/^(?:2\.3\.0|2\.5\.0)$/.test(manifest.tirtc_sdk_version) ||
+  const sdkPattern = SDK_VERSION_PATTERN_BY_TARGET[metadata.target];
+  if (!sdkPattern ||
+      manifest.target !== metadata.target ||
+      manifest.platform !== metadata.platform ||
+      !sdkPattern.test(manifest.tirtc_sdk_version) ||
       (metadata.sdkVersion && manifest.tirtc_sdk_version !== metadata.sdkVersion)) {
     throw new Error("Device Kit target or TiRTC SDK version is incompatible");
   }
-  const sdkRoot = `device-sim/sdk/espressif-esp32s3/${manifest.tirtc_sdk_version}`;
+  const sdkRoot = `device-sim/sdk/${metadata.platform}/${manifest.tirtc_sdk_version}`;
   const sdkFiles = [
     `${sdkRoot}/include/tirtc/tiRTC.h`,
     `${sdkRoot}/lib/libTiRTC.a`,
@@ -170,17 +189,20 @@ async function download(url, destination) {
 function parseArgs(args) {
   let archive = null;
   let target = null;
+  let kit = "esp32s3";
   for (let index = 0; index < args.length; index += 1) {
     const argument = args[index];
-    if (argument === "--archive" || argument === "--target") {
+    if (argument === "--archive" || argument === "--target" || argument === "--kit") {
       const value = args[index + 1];
       if (!value || value.startsWith("--")) {
-        throw new Error(`${argument} requires a path`);
+        throw new Error(`${argument} requires a value`);
       }
       if (argument === "--archive") {
         archive = resolve(value);
-      } else {
+      } else if (argument === "--target") {
         target = resolve(value);
+      } else {
+        kit = value;
       }
       index += 1;
       continue;
@@ -190,20 +212,29 @@ function parseArgs(args) {
   if (!target) {
     throw new Error("--target is required");
   }
-  return { archive, target };
+  if (!(kit in ESP32_KITS)) {
+    throw new Error(`unknown Device Kit target selector: ${kit}`);
+  }
+  return { archive, target, metadata: ESP32_KITS[kit] };
 }
 
 async function main() {
   const options = parseArgs(process.argv.slice(2));
+  const metadata = options.metadata;
   let archive = options.archive;
   let downloadDirectory = null;
   try {
     if (!archive) {
+      if (!metadata.released) {
+        throw new Error(
+          `Device Kit ${metadata.target} metadata is not yet pinned to a release; pass --archive`,
+        );
+      }
       downloadDirectory = mkdtempSync(join(tmpdir(), "tirtc-kit-download-"));
-      archive = join(downloadDirectory, ESP32_KIT.archiveName);
-      await download(ESP32_KIT.url, archive);
+      archive = join(downloadDirectory, metadata.archiveName);
+      await download(metadata.url, archive);
     }
-    installEsp32KitArchive(archive, options.target);
+    installEsp32KitArchive(archive, options.target, metadata);
   } finally {
     if (downloadDirectory) {
       rmSync(downloadDirectory, { force: true, recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.9.7",
+  "version": "0.10.0",
   "description": "Install and run TiRTC device-development Agent Skills across popular coding clients.",
   "license": "MIT",
   "author": {

package/skills/tirtc-esp32-builder/SKILL.md

@@ -27,9 +27,10 @@ past build as proof for a new artifact.
    Clone or download it only when the user authorizes that external write.
    Read the exact business documents routed by `workflow.md`.
 4. Run Doctor for the exact target and SDK package. Managed generation currently
-   automates ESP32-S3. ESP32-P4 is valid only with an evidenced P4 BSP/network
-   path and the matching `espressif_esp32p4` SDK/build contract; never link the
-   S3 archive into a P4 image.
+   automates ESP32-S3. For ESP32-P4 use the published `tirtc-esp32p4-kit`
+   (the XiaoTai P4 reference firmware with hosted C6 Wi-Fi and LVGL UI): copy it
+   with `create_esp32_project.py --target esp32p4`, build with the RISC-V
+   toolchain on ESP-IDF 5.5.4, and never link the S3 archive into a P4 image.
 
 ## 2. Identify the board and query knowledge
 

package/skills/tirtc-esp32-builder/USAGE.md

@@ -44,6 +44,24 @@ printf '%s\n' "$TIRTC_THING_CONNECT_ROOT"
 
 已有完整 ThingConnect 工作区仍可通过 `--thing-connect-root` 显式复用，主要用于维护模板或协议时的开发场景。
 
+### ESP32-P4 Device Kit
+
+P4 不上 managed 安装（需要独立的 RISC-V 工具链）。从 GitHub Release 下载
+`tirtc-esp32p4-kit`（小钛 P4 参考固件 1.4.0：hosted C6 Wi-Fi + LVGL UI +
+摄像头，含 P4 SDK 2.5.0 与构建契约）并校验 SHA-256 后：
+
+```bash
+python3 <解包目录>/device-sim/scripts/create_esp32_project.py \
+  /absolute/path/my-p4-device my_p4_device --target esp32p4
+cd /absolute/path/my-p4-device
+idf.py set-target esp32p4
+idf.py build   # 需要 ESP-IDF 5.5.4 与 riscv32-esp-elf（install.sh esp32p4）
+```
+
+诊断使用 `--target esp32p4`；P4 永远不得链接 S3 的 `libTiRTC.a`。板级差异
+（屏幕、摄像头、Codec、按键）位于参考固件的板级组件内，共享传输组件
+（platform_client/runtime_config/wifi_manager）与 S3 同源。
+
 ## 常见输入方式
 
 只有板卡型号：

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.9.7
+0.10.0

package/skills/tirtc-esp32-builder/knowledge/waveshare-esp32-p4-wifi6-touch-lcd-3.5/knowledge.md

@@ -5,6 +5,15 @@ contains source-correlated observations and targeted regressions, not an
 installable adapter or complete Hardware IR. A matching sales name does not
 authorize pin reuse. No credentials, raw call logs or user media are retained.
 
+## Current kit status (2026-09-22)
+
+The builder repository now ships the XiaoTai P4 reference firmware (product
+1.4.0, source `f33b7d2`) in `kit-src/device-sim/device-sim-p4/` and packs the
+TiRTC ESP32-P4 SDK 2.5.0 vendor baseline (libTiRTC.a sha256
+`9b4e35c7…`) into the `tirtc-esp32p4-kit` release. The historical observations
+below (TiRTC 2.3.0, archive `a7a01ffd…`, IDF 5.5.4-dirty) remain historical
+artifacts and do not describe the current kit baseline.
+
 ## Read only the needed source
 
 | Baseline | Pinned source | Locate next |

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

@@ -59,10 +59,19 @@ protocols and non-ESP32 simulators. Cloning is an external write and requires
 user authorization. Do not track a moving default branch as build evidence.
 
 ESP32-P4 uses a separate `espressif_esp32p4` SDK archive and RISC-V toolchain.
-The managed setup does not install that archive or generate a P4 starter. A P4
-task therefore needs an explicit BSP/network project plus the exact P4 SDK and
-`manifest/build-contract.env`; run Doctor with `--target esp32p4` and never accept
-the packaged S3 archive as a compatible fallback.
+The managed setup does not install that archive; P4 projects come from the
+published `tirtc-esp32p4-kit` (the XiaoTai P4 reference firmware, released
+alongside the S3 Kit). The P4 flow is:
+
+1. Download the `tirtc-esp32p4-kit` GitHub release, verify its SHA-256, and
+   extract it (or point `--thing-connect-root` at this repository's `kit-src`).
+2. `python3 device-sim/scripts/create_esp32_project.py <out> <name> --target esp32p4`
+   (copies the full reference firmware and materializes the shared transport
+   components and the P4 SDK under `third_party/tirtc`).
+3. `idf.py set-target esp32p4`, build with the RISC-V toolchain
+   (`install.sh esp32p4`; the pinned SDK requires ESP-IDF 5.5.4 exactly).
+4. Run Doctor with `--target esp32p4` and never accept the packaged S3 archive
+   as a compatible fallback.
 
 SDK resolution is independent after generation: an explicit `--sdk-dir` wins, followed by `<project>/third_party/tirtc`, then the SDK packaged in the resolved Device Kit or legacy workspace. The generated project remains diagnosable after it is moved away from the Kit.
 

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

@@ -22,10 +22,29 @@ CONTRACT_KEYS = {
     "CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS",
     "CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS",
 }
+# The P4 archive additionally pins the socket budget (absent from the S3 contract).
+CONTRACT_KEYS_P4 = CONTRACT_KEYS | {"CONFIG_LWIP_MAX_SOCKETS"}
 THING_CONNECT_ENV = "TIRTC_THING_CONNECT_ROOT"
 GENERATOR_RELATIVE_PATH = Path("device-sim/scripts/create_esp32_project.py")
-SDK_RELATIVE_ROOT = Path("device-sim/sdk/espressif-esp32s3")
 DEVICE_KIT_MANIFEST = "manifest.json"
+SDK_FALLBACK_VERSIONS = {
+    "esp32s3": ("2.5.0", "2.3.0"),
+    "esp32p4": ("2.5.0",),
+}
+
+
+def sdk_relative_root(platform: str | None, target: str) -> Path:
+    """SDK root inside the Kit; the manifest platform wins, the target is the
+    fallback. A P4 target never resolves the ESP32-S3 SDK archive."""
+    if platform == "espressif-esp32p4" or target == "esp32p4":
+        return Path("device-sim/sdk/espressif-esp32p4")
+    return Path("device-sim/sdk/espressif-esp32s3")
+
+
+def contract_keys(target: str) -> set[str]:
+    if target == "esp32p4":
+        return CONTRACT_KEYS_P4
+    return CONTRACT_KEYS
 
 
 def check(name: str, status: str, detail: str, required: bool = True) -> dict[str, Any]:
@@ -115,10 +134,10 @@ def parse_kconfig(path: Path) -> dict[str, str]:
 
 
 def compare_contract(
-    contract: dict[str, str], config: dict[str, str]
+    contract: dict[str, str], config: dict[str, str], keys: set[str] | None = None
 ) -> list[str]:
     mismatches: list[str] = []
-    for key in sorted(CONTRACT_KEYS):
+    for key in sorted(keys if keys is not None else CONTRACT_KEYS):
         expected = contract.get(key)
         actual = config.get(key)
         if expected is None:
@@ -238,6 +257,7 @@ def resolve_sdk_dir(
     explicit: Path | None,
     project: Path | None,
     thing_connect_root: Path | None,
+    target: str = "esp32s3",
 ) -> tuple[Path | None, str]:
     if explicit is not None:
         return explicit.expanduser().resolve(), "explicit --sdk-dir"
@@ -251,15 +271,22 @@ def resolve_sdk_dir(
             try:
                 manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
                 version = manifest.get("tirtc_sdk_version")
+                platform = manifest.get("platform")
                 if isinstance(version, str) and re.fullmatch(r"\d+\.\d+\.\d+", version):
-                    return thing_connect_root / SDK_RELATIVE_ROOT / version, "Device Kit"
+                    return (
+                        thing_connect_root / sdk_relative_root(platform, target) / version,
+                        "Device Kit",
+                    )
             except (OSError, json.JSONDecodeError):
                 pass
-        for version in ("2.5.0", "2.3.0"):
-            candidate = thing_connect_root / SDK_RELATIVE_ROOT / version
+        for version in SDK_FALLBACK_VERSIONS.get(target, SDK_FALLBACK_VERSIONS["esp32s3"]):
+            candidate = thing_connect_root / sdk_relative_root(None, target) / version
             if candidate.is_dir():
                 return candidate, "ESP32 source workspace"
-        return thing_connect_root / SDK_RELATIVE_ROOT / "2.5.0", "ESP32 source workspace"
+        return (
+            thing_connect_root / sdk_relative_root(None, target) / "2.5.0",
+            "ESP32 source workspace",
+        )
     return None, "not found"
 
 
@@ -373,6 +400,7 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
         args.sdk_dir,
         args.project,
         thing_connect_root,
+        args.target,
     )
     if sdk_dir is None:
         sdk_files: list[Path] = []
@@ -427,7 +455,9 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
             checks.append(check("TiRTC build contract", "FAIL", detail))
         else:
             mismatches = compare_contract(
-                parse_env_file(contract_path), parse_kconfig(config_path)
+                parse_env_file(contract_path),
+                parse_kconfig(config_path),
+                contract_keys(args.target),
             )
             checks.append(
                 check(