tirtc-device-builder 0.9.5 → 0.9.6

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 This project follows Semantic Versioning.
 
+## 0.9.6
+
+- Pin ESP32-S3 Device Kit 1.1.6 with TiRTC C SDK 2.5.0 and verify the
+  GitHub release archive checksum before npm publication.
+- Build the Kit from the builder-owned ESP32 source and validate the SDK,
+  installer, project generator, and standalone reference firmware.
+- Keep board-specific media adapters and hardware evidence separate from the
+  reusable Skill; hardware verification remains board-specific.
+
 ## 0.9.5
 
 - Add focused video-orientation and WeChat UI-profile guidance distinguishing

package/README.md

@@ -8,11 +8,11 @@ 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 中，安装时会自动下载并校验。设备互呼或微信 VoIP 的模拟/移植若超出当前 Kit 内容，则需要在用户授权后使用固定 commit 的 `tirtc-server-example` 完整仓库。ESP32-P4 必须使用匹配的 P4 SDK、BSP 与网络方案，不能复用 S3 预编译库。
+H5/AI 的 ESP32-S3 托管模板、协议文档和 TiRTC SDK 已打包在独立的 ESP32 Device Kit 中，安装时会自动下载并校验。ESP32 示例源码由本仓库的 `kit-src/` 维护；设备互呼或微信 VoIP 的移植可参考其中的独立示例。ESP32-P4 必须使用匹配的 P4 SDK、BSP 与网络方案，不能复用 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.4](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.4)
+- ESP32 Device Kit：[kit-esp32s3-v1.1.6](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.6)
 
 文档导航：
 
@@ -282,14 +282,16 @@ board-materials/
 | 参考模组 | ESP32-S3-WROOM-1-N16R8，或资源和配置经过确认的兼容板 |
 | ESP-IDF | 5.5.x |
 | 自动安装版本 | ESP-IDF v5.5.4 |
-| TiRTC SDK | `espressif-esp32s3/2.3.0` |
-| ESP32 Device Kit | 1.1.4 |
+| 本仓库源码与本地打包使用的 TiRTC SDK | `espressif-esp32s3/2.5.0` |
+| ESP32 Device Kit | 1.1.6（内含 TiRTC SDK 2.5.0） |
 | Node.js | 18 或更高版本 |
 | 支持自动安装的系统 | Linux、WSL、macOS |
 | 原生 Windows | 使用 Espressif 官方安装器准备 ESP-IDF，再重新运行检查 |
 
 当前托管自动生成器只提供 ESP32-S3 模板。ESP32-P4 可由 Skill 在已有、证据完整的 P4 BSP/工程上移植，但必须使用 `espressif-esp32p4` SDK、匹配的构建合同和明确的 ESP-Hosted 或以太网方案。Flash 或 PSRAM 容量变化时，需要重新评估 `sdkconfig.defaults`、分区表、DMA 和媒体缓存预算。
 
+从本仓库 `kit-src/` 直接生成或打包时使用 TiRTC 2.5.0；`setup esp32` 安装固定的 Kit 版本，其 SDK 版本以该 Kit 的 `manifest.json` 为准。
+
 ### 本机软件
 
 `setup esp32 --install` 会检查以下基础命令：
@@ -392,7 +394,7 @@ Cline 当前还需要在 `Settings → Features → Enable Skills` 中启用实
 |---|---|
 | Agent Skill | 上表中所选目录下的 `tirtc-esp32-builder` |
 | 托管根目录 | `~/.tirtc-device-builder` |
-| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.4` |
+| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.6` |
 | ESP-IDF | `~/.tirtc-device-builder/esp-idf-v5.5.4` |
 | Espressif 工具 | `~/.tirtc-device-builder/espressif` |
 | 安装记录 | `~/.tirtc-device-builder/config.json` |
@@ -437,7 +439,7 @@ npx --yes tirtc-device-builder@latest setup esp32 --install \
 
 ```bash
 npx --yes tirtc-device-builder@latest setup esp32 --install \
-  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.4.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.6.tar.gz
 ```
 
 安装器仍会核对固定的 SHA-256、目录结构、清单和每个资源文件，不接受未经验证的同名压缩包。
@@ -820,7 +822,7 @@ npx --yes tirtc-device-builder@latest setup esp32 --install --force-skill
 
 ```bash
 npx --yes tirtc-device-builder@latest setup esp32 --install \
-  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.4.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.6.tar.gz
 ```
 
 安装器会校验 SHA-256 和内部文件清单。如果校验不一致，请重新获取官方 Release 附件，不要跳过校验。
@@ -880,7 +882,7 @@ npx --yes tirtc-device-builder@latest setup esp32
 
 不需要。普通开发所需的生成器、模板、协议文档、TiRTC 头文件和 `libTiRTC.a` 都在版本化的 ESP32 Device Kit 中。一键安装会下载公开 Release，并把路径写进 `env.sh`。
 
-`--thing-connect-root` 主要用于维护模板、协议或 Device Kit 的开发者复用完整源码工作区。
+维护者可用 `--thing-connect-root` 指向本仓库的 `kit-src/`；普通使用者使用安装好的 Device Kit 路径。
 
 ### 为什么推荐 `npx`，不是安装一个 npm 包就结束？
 
@@ -931,29 +933,28 @@ python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
 
 ```bash
 npm run pack:esp32-kit -- \
-  --source /absolute/path/tirtc-server-example/thing-connect \
-  --kit-version 1.1.4
+  --kit-version 1.1.6
 ```
 
 输出位于 `dist/`：
 
 ```text
-tirtc-esp32s3-kit-1.1.4.tar.gz
-tirtc-esp32s3-kit-1.1.4.tar.gz.sha256
+tirtc-esp32s3-kit-1.1.6.tar.gz
+tirtc-esp32s3-kit-1.1.6.tar.gz.sha256
 ```
 
-校验后推送独立的 `kit-esp32s3-v<version>` 标签。`publish-kit.yml` 会从 metadata 固定的上游 commit 重建压缩包、核对 SHA-256，并使用 GitHub Actions token 创建 Release：
+校验后推送独立的 `kit-esp32s3-v<version>` 标签。`publish-kit.yml` 会从 metadata 固定的本仓库源码 commit 重建压缩包、核对 SHA-256，并使用 GitHub Actions token 创建 Release：
 
 ```bash
 cd dist
-sha256sum -c tirtc-esp32s3-kit-1.1.4.tar.gz.sha256
+sha256sum -c tirtc-esp32s3-kit-1.1.6.tar.gz.sha256
 cd ..
 
-git tag -a kit-esp32s3-v1.1.4 -m "TiRTC ESP32-S3 Device Kit 1.1.4"
-git push origin kit-esp32s3-v1.1.4
+git tag -a kit-esp32s3-v1.1.6 -m "TiRTC ESP32-S3 Device Kit 1.1.6"
+git push origin kit-esp32s3-v1.1.6
 ```
 
-metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地可复现打包结果一致；工作流不会从浮动的 `main` 取发布内容。
+metadata 中的版本、标签、本仓库源码 commit 和期望 SHA-256 必须与本地可复现打包结果一致；工作流不会从浮动的 `main` 取发布内容。
 
 ### 发布 npm
 
@@ -961,8 +962,8 @@ metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地
 
 ```bash
 npm test
-git tag -a v0.9.5 -m "v0.9.5"
-git push origin v0.9.5
+git tag -a v0.9.6 -m "v0.9.6"
+git push origin v0.9.6
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/bin/esp32-kit-metadata.js

@@ -1,9 +1,10 @@
 export const ESP32_KIT = Object.freeze({
-  archiveName: "tirtc-esp32s3-kit-1.1.4.tar.gz",
-  archiveRoot: "tirtc-esp32s3-kit-1.1.4",
-  releaseTag: "kit-esp32s3-v1.1.4",
-  sha256: "b041baca1fbf6f3f3bd1299921793f0f708c669023b39148a34e3f478e3789fc",
-  sourceCommit: "7e9c595b8b5531bd781e42344c584095f3f74a1b",
-  url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.1.4/tirtc-esp32s3-kit-1.1.4.tar.gz",
-  version: "1.1.4",
+  archiveName: "tirtc-esp32s3-kit-1.1.6.tar.gz",
+  archiveRoot: "tirtc-esp32s3-kit-1.1.6",
+  releaseTag: "kit-esp32s3-v1.1.6",
+  sha256: "61243703bdee3e1b492fcc6f5245143f419efbd2310127d180875f0708e91d8b",
+  sdkVersion: "2.5.0",
+  sourceCommit: "68a3b34054ea933d5ea5bfd8acf71e5ff07a7a61",
+  url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.1.6/tirtc-esp32s3-kit-1.1.6.tar.gz",
+  version: "1.1.6",
 });

package/bin/install-esp32-kit.js

@@ -24,9 +24,6 @@ const REQUIRED_FILES = [
   "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",
-  "device-sim/sdk/espressif-esp32s3/2.3.0/include/tirtc/tiRTC.h",
-  "device-sim/sdk/espressif-esp32s3/2.3.0/lib/libTiRTC.a",
-  "device-sim/sdk/espressif-esp32s3/2.3.0/manifest/build-contract.env",
 ];
 
 function hashFile(path) {
@@ -98,9 +95,21 @@ function validateExtractedKit(root, metadata) {
       `Device Kit version mismatch: expected ${metadata.version}, got ${manifest.kit_version}`,
     );
   }
-  if (manifest.target !== "esp32s3" || manifest.tirtc_sdk_version !== "2.3.0") {
+  if (manifest.target !== "esp32s3" ||
+      !/^(?:2\.3\.0|2\.5\.0)$/.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 sdkFiles = [
+    `${sdkRoot}/include/tirtc/tiRTC.h`,
+    `${sdkRoot}/lib/libTiRTC.a`,
+    `${sdkRoot}/manifest/build-contract.env`,
+  ];
+  const missingSdk = sdkFiles.filter((path) => !existsSync(join(root, path)));
+  if (missingSdk.length > 0) {
+    throw new Error(`Device Kit SDK is incomplete: ${missingSdk.join(", ")}`);
+  }
   if (!manifest.files || typeof manifest.files !== "object") {
     throw new Error("Device Kit manifest has no file checksums");
   }

package/bin/setup-esp32.js

@@ -29,12 +29,6 @@ const GENERATOR_PATH = join(
   "scripts",
   "create_esp32_project.py",
 );
-const SDK_PATH = join(
-  "device-sim",
-  "sdk",
-  "espressif-esp32s3",
-  "2.3.0",
-);
 const REQUIRED_SDK_FILES = [
   join("include", "tirtc", "tiRTC.h"),
   join("lib", "libTiRTC.a"),
@@ -233,6 +227,7 @@ export function inspectDeviceKit(root) {
   const manifestPath = root ? join(root, DEVICE_KIT_MANIFEST) : null;
   let manifestPresent = false;
   let version = null;
+  let sdkVersion = null;
   let manifestError = null;
   if (manifestPath && existsSync(manifestPath)) {
     manifestPresent = true;
@@ -245,6 +240,9 @@ export function inspectDeviceKit(root) {
         manifest.kit_version.trim()
       ) {
         version = manifest.kit_version.trim();
+        if (typeof manifest.tirtc_sdk_version === "string") {
+          sdkVersion = manifest.tirtc_sdk_version;
+        }
       } else {
         manifestError = "manifest.json does not declare kit_version";
       }
@@ -258,11 +256,13 @@ export function inspectDeviceKit(root) {
   const generatorReady = Boolean(
     root && existsSync(join(root, GENERATOR_PATH)),
   );
-  const sdk = root ? join(root, SDK_PATH) : null;
-  const sdkReady = Boolean(
-    sdk &&
-      REQUIRED_SDK_FILES.every((relative) => existsSync(join(sdk, relative))),
-  );
+  const sdkVersions = sdkVersion
+    ? [sdkVersion]
+    : [...new Set(["2.5.0", ESP32_KIT.sdkVersion])];
+  const sdkReady = Boolean(root && sdkVersions.some((candidate) => {
+    const sdk = join(root, "device-sim", "sdk", "espressif-esp32s3", candidate);
+    return REQUIRED_SDK_FILES.every((relative) => existsSync(join(sdk, relative)));
+  }));
   const structureReady = generatorReady && sdkReady;
   const versionCompatible =
     !manifestPresent ||

package/package.json

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

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

@@ -20,11 +20,12 @@ past build as proof for a new artifact.
    talkback, AI intercom, device-to-device calling, and WeChat VoIP. Do not
    silently remove a requested feature because the current starter lacks it.
 3. Resolve a versioned source of truth. The managed ESP32-S3 Device Kit is the
-   default for its packaged capabilities. Device-call/WeChat simulation or
-   protocol porting requires a pinned full `tirtc-server-example` checkout when
-   those sources are absent from the selected Kit. Clone or download it only
-   when the user authorizes that external write. Read applicable repository
-   instructions and the exact business documents routed by `workflow.md`.
+   default for its packaged capabilities; this repository's `kit-src/` owns the
+   ESP32 generator, SDK and standalone reference implementation. For
+   device-call/WeChat protocol simulation use a pinned `tirtc-server-example`
+   checkout when the Kit lacks the Linux C simulator and protocol documents.
+   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

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

@@ -74,7 +74,7 @@ printf '%s\n' "$TIRTC_THING_CONNECT_ROOT"
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
   --target esp32s3 \
-  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.1.4 \
+  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.1.6 \
   --require-workspace
 ```
 
@@ -119,4 +119,4 @@ python3 <skill-dir>/scripts/firmware_identity.py build/<app>.bin \
 
 ## 当前边界
 
-ThingConnect 仓库提供 ESP32-S3 H5/AI 模板和生成器，但默认媒体适配器不包含特定开发板的摄像头、麦克风、选定视频路径、Wi-Fi 凭证方法和扬声器驱动。模板生成和编译成功只证明工程与协议骨架可用，不代表 Web 已经出图或 AI 音频已经通过实机验收。
+Device Kit 提供 ESP32-S3 H5/AI 模板和生成器，但默认媒体适配器不包含特定开发板的摄像头、麦克风、选定视频路径和扬声器驱动。模板生成和编译成功只证明工程与协议骨架可用，不代表 Web 已经出图或 AI 音频已经通过实机验收。

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.9.5
+0.9.6

package/skills/tirtc-esp32-builder/assets/hardware-ir-v2.example.json

@@ -29,8 +29,8 @@
     "verification": "extracted",
     "tirtc": {
       "platform": "espressif-esp32s3",
-      "version": "2.3.0",
-      "sdk_path": "device-sim/sdk/espressif-esp32s3/2.3.0",
+      "version": "2.5.0",
+      "sdk_path": "device-sim/sdk/espressif-esp32s3/2.5.0",
       "build_contract": "manifest/build-contract.env"
     },
     "source_refs": [

package/skills/tirtc-esp32-builder/assets/hardware-ir.example.json

@@ -29,8 +29,8 @@
     "verification": "extracted",
     "tirtc": {
       "platform": "espressif-esp32s3",
-      "version": "2.3.0",
-      "sdk_path": "device-sim/sdk/espressif-esp32s3/2.3.0",
+      "version": "2.5.0",
+      "sdk_path": "device-sim/sdk/espressif-esp32s3/2.5.0",
       "build_contract": "manifest/build-contract.env"
     },
     "source_refs": [

package/skills/tirtc-esp32-builder/assets/lckfb-szpi-esp32s3-portable-prompt.md

@@ -8,7 +8,7 @@
 
 ```bash
 export TIRTC_AGENT_CLIENT=codex
-npx --yes tirtc-device-builder@0.9.5 setup esp32 --install \
+npx --yes tirtc-device-builder@0.9.6 setup esp32 --install \
   --client "$TIRTC_AGENT_CLIENT" --force-skill
 ```
 
@@ -17,11 +17,11 @@ npx --yes tirtc-device-builder@0.9.5 setup esp32 --install \
 本轮第一步先只读运行：
 
 ```bash
-npx --yes tirtc-device-builder@0.9.5 --version
-npx --yes tirtc-device-builder@0.9.5 setup esp32 --client "$TIRTC_AGENT_CLIENT"
+npx --yes tirtc-device-builder@0.9.6 --version
+npx --yes tirtc-device-builder@0.9.6 setup esp32 --client "$TIRTC_AGENT_CLIENT"
 ```
 
-必须根据命令的实际输出和本机文件确认：npm 包为 0.9.5、已安装 Skill 的 `VERSION` 为 0.9.5、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.4，并且 Doctor 对 `--expected-kit 1.1.4` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
+必须根据命令的实际输出和本机文件确认：npm 包为 0.9.6、已安装 Skill 的 `VERSION` 为 0.9.6、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.6、`tirtc_sdk_version` 为 2.5.0，并且 Doctor 对 `--expected-kit 1.1.6` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
 
 工作区与 clean-room 边界：
 - 将启动 Agent 客户端时的当前目录定义为 `WORKSPACE_ROOT`。

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

@@ -16,7 +16,7 @@ The automatic branch never runs `sudo` or modifies a persistent shell profile. W
 When `<setup-root>/env.sh` exists, use it only as an activation prefix for the current command:
 
 ```bash
-bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --expected-kit 1.1.4 --target esp32s3 --require-workspace'
+bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --expected-kit 1.1.6 --target esp32s3 --require-workspace'
 ```
 
 The helper contains paths, not device or network credentials. Read `<setup-root>/config.json` when exact managed paths are needed; the environment helper does not authorize unrelated downloads, shell-profile changes, flashing, or credential writes.
@@ -26,7 +26,7 @@ Run the doctor before generation, build, flash, or monitor:
 ```bash
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
-  --expected-kit 1.1.4 \
+  --expected-kit 1.1.6 \
   --target esp32s3 \
   --require-workspace
 ```
@@ -44,15 +44,18 @@ For an explicitly selected legacy workspace, omit `--expected-kit`; otherwise re
 1. an explicit `--thing-connect-root <path>`;
 2. `TIRTC_THING_CONNECT_ROOT`;
 3. an ancestor of the project or current directory containing `device-sim/scripts/create_esp32_project.py`;
-4. an ancestor whose `thing-connect/` child contains that generator.
+4. an ancestor whose `kit-src/` or `thing-connect/` child contains that generator.
 
-The default managed root is `<setup-root>/kits/esp32s3/<kit-version>`. The public ThingConnect workspace remains an optional legacy/development input; the doctor accepts either a Device Kit root, a repository root, or its `thing-connect/` child.
+The default managed root is `<setup-root>/kits/esp32s3/<kit-version>`. The `tirtc-device-builder/kit-src` directory is the ESP32 development source; the doctor also accepts an installed Device Kit root. Older `thing-connect/` layouts remain accepted as legacy inputs.
+Resolve the SDK from the selected Kit manifest or generated project. Kit 1.1.6
+and this repository's source generator use the ESP32-S3 SDK 2.5.0.
 
 The managed Kit currently contains the ESP32-S3 H5/AI starter. When the requested
 portfolio includes device-to-device calling or WeChat VoIP and the selected Kit
 does not contain `device-sim-c`, `device-call.md`, `device-voip.md`, and the API
-reference, use a full `tirtc-server-example` checkout pinned to a recorded commit
-for the simulator and porting source. Cloning is an external write and requires
+reference, use this repository's `kit-src/device-sim/device-sim-esp32` for the
+ESP32 implementation and a pinned `tirtc-server-example` commit for server
+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.

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

@@ -20,7 +20,7 @@ used by a build.
 ## SDK lifecycle
 
 TiRTC is one process-wide runtime. The exact selected header governs API and
-option availability. For SDK 2.3.0 the important order is:
+option availability. For SDK 2.5.0 the important order is:
 
 1. Set `TIRTC_OPT_MAX_SEND_BUFFER` before `TiRtcInit()` when overriding it.
 2. Call `TiRtcInit()` once.
@@ -33,7 +33,12 @@ option availability. For SDK 2.3.0 the important order is:
 6. Stop sessions and connections through deferred lifecycle work before the one
    final `TiRtcStop()` / `TiRtcUninit()` sequence.
 
-The callback table and its context outlive the SDK runtime. Callback payloads
+The callback table and its context outlive the SDK runtime. SDK 2.5.0 adds
+`on_sleep_wakeup_info` at the end of `TIRTCCALLBACKS`; zero-initialize the full
+struct and keep it `NULL` when sleep wakeup is unused. If supplied, this callback
+can run synchronously inside `TiRtcStart()`. Set a custom
+`TIRTC_OPT_TGTRP_POLL_TIMEOUT` after `TiRtcInit()`, which resets it to 10 ms.
+Callback payloads
 are borrowed; copy required data into bounded application-owned storage before
 returning.
 
@@ -85,8 +90,8 @@ drop a requested feature or call it verified.
 
 ## ESP32 targets
 
-The current managed generator and Device Kit automate ESP32-S3. Official SDK
-2.3.0 also provides a distinct ESP32-P4 package. P4 needs ESP-IDF 5.5.4, matching
+The current managed generator and Device Kit automate ESP32-S3. ESP32-P4 requires
+a distinct target-specific SDK package. P4 needs ESP-IDF 5.5.4, matching
 RISC-V toolchain/build contract, PSRAM, and an evidenced network path such as
 ESP-Hosted with C6/C61 or Ethernet. P4 and S3 archives are not interchangeable.
 

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

@@ -24,9 +24,7 @@ CONTRACT_KEYS = {
 }
 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"
-)
+SDK_RELATIVE_ROOT = Path("device-sim/sdk/espressif-esp32s3")
 DEVICE_KIT_MANIFEST = "manifest.json"
 
 
@@ -161,7 +159,7 @@ def discover_serial_ports() -> list[str]:
 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"):
+    for root in (resolved, resolved / "kit-src", resolved / "thing-connect"):
         if (root / GENERATOR_RELATIVE_PATH).is_file():
             return root
     return None
@@ -248,7 +246,20 @@ 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, "Device Kit or legacy workspace"
+        manifest_path = thing_connect_root / DEVICE_KIT_MANIFEST
+        if manifest_path.is_file():
+            try:
+                manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+                version = manifest.get("tirtc_sdk_version")
+                if isinstance(version, str) and re.fullmatch(r"\d+\.\d+\.\d+", version):
+                    return thing_connect_root / SDK_RELATIVE_ROOT / 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
+            if candidate.is_dir():
+                return candidate, "ESP32 source workspace"
+        return thing_connect_root / SDK_RELATIVE_ROOT / "2.5.0", "ESP32 source workspace"
     return None, "not found"