tirtc-device-builder 0.9.7 → 0.10.1

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 This project follows Semantic Versioning.
 
+## 0.10.1
+
+- Add a knowledge-only Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3-C V1.0 package
+  with artifact-bound ST7701 display, GT911 touch and ES7210 TDM/AEC lessons.
+- Add RAM-less DSI display guidance covering safe initial back-buffer selection,
+  VSYNC ownership, partial-refresh damage carry-forward, LVGL software rotation,
+  RGB565 byte order, touch mapping and runtime display-size scaling.
+- Test exact 4.3-C registry matching while keeping adapter reuse disabled.
+
+## 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.1",
   "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
 
@@ -52,6 +53,10 @@ the user's business baseline separately from the hardware reference.
 For video orientation, unexpected cropping, or WeChat display-profile changes,
 read [video-orientation.md](references/video-orientation.md) before changing
 pixel transforms or UI angles.
+For device-panel tearing, flicker, stale regions, wrong colors, display rotation
+or touch-coordinate mismatch, read
+[display-pipeline.md](references/display-pipeline.md) before changing the panel,
+LVGL or framebuffer path.
 
 ## 3. Prove the business flows before board porting
 

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.1

package/skills/tirtc-esp32-builder/knowledge/board-registry.json

@@ -38,6 +38,68 @@
         }
       ]
     },
+    {
+      "package_id": "waveshare_esp32p4_wifi6_touch_lcd_43c_v1_0",
+      "status": "knowledge_only",
+      "identity": {
+        "vendor": "Waveshare",
+        "model": "ESP32-P4-WIFI6-Touch-LCD-4.3-C",
+        "aliases": ["Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3-C", "微雪 ESP32-P4-WIFI6-Touch-LCD-4.3-C", "ESP32-P4-WIFI6-Touch-LCD-4.3-C (SKU 33875)"],
+        "hardware_revision": "V1.0",
+        "target": "esp32p4",
+        "module": "ESP32-P4NRW32 + ESP32-C6-MINI-1-N4",
+        "flash_mb": 32,
+        "psram_mb": 32,
+        "components": [
+          {"kind": "camera", "model": "OV5647"},
+          {"kind": "audio_input", "model": "ES7210"},
+          {"kind": "audio_output", "model": "ES8311"},
+          {"kind": "display", "model": "ST7701"},
+          {"kind": "touch", "model": "GT911"},
+          {"kind": "network", "model": "ESP32-C6-MINI-1-N4"}
+        ],
+        "probes": [
+          {"kind": "camera_pid", "value": "0x5647", "required_for_exact": true},
+          {"kind": "touch_id", "value": "911", "required_for_exact": true},
+          {"kind": "es7210_i2c_7bit", "value": "0x40", "required_for_exact": true}
+        ]
+      },
+      "compatibility": {"idf": "5.5.4", "tirtc_sdk": "2.3.0-P4-validation-rebuild"},
+      "artifacts": {},
+      "knowledge_refs": ["waveshare-esp32-p4-wifi6-touch-lcd-4.3-c/knowledge.md"],
+      "lessons": [
+        {
+          "id": "waveshare_43c_dsi_partial_double_buffer",
+          "scope": "component",
+          "subject": "display:ST7701 partial double buffering",
+          "guidance": "For a RAM-less DSI panel, synchronize presented damage into the recycled back buffer after VSYNC and select a back buffer that is not initially scanned; allocating two buffers alone does not prevent tearing or stale regions.",
+          "action": "require",
+          "verification": "hil_verified",
+          "applies_to": {"kind": "display", "model": "ST7701"},
+          "evidence": [{"board_package_id": "waveshare_esp32p4_wifi6_touch_lcd_43c_v1_0", "source_ref": "waveshare-esp32-p4-wifi6-touch-lcd-4.3-c/knowledge.md#display-failures-and-resolution", "artifact_sha256": "2fb05d6985401b061ef3778f69b2f2b68a3d43cb6e7af145484d136de1ae2562"}]
+        },
+        {
+          "id": "waveshare_43c_display_orientation_color_touch",
+          "scope": "board",
+          "subject": "LVGL display orientation, RGB565 and touch",
+          "guidance": "For the verified V1.0 enclosure use LVGL 8.3 sw_rotate with ROT_90, one RGB565 byte swap when LV_COLOR_16_SWAP is enabled, and native GT911 coordinates so LVGL rotates touch with the display.",
+          "action": "prefer",
+          "verification": "hil_verified",
+          "applies_to": {"package_id": "waveshare_esp32p4_wifi6_touch_lcd_43c_v1_0"},
+          "evidence": [{"board_package_id": "waveshare_esp32p4_wifi6_touch_lcd_43c_v1_0", "source_ref": "waveshare-esp32-p4-wifi6-touch-lcd-4.3-c/knowledge.md#display-failures-and-resolution", "artifact_sha256": "2fb05d6985401b061ef3778f69b2f2b68a3d43cb6e7af145484d136de1ae2562"}]
+        },
+        {
+          "id": "waveshare_43c_es7210_address_slots",
+          "scope": "board",
+          "subject": "ES7210 address, TDM slots and AEC reference",
+          "guidance": "Probe 7-bit address 0x40, convert to the selected codec abstraction's 8-bit address form, and map compact DMA [MIC3 reference, MIC2 microphone] into the AEC microphone/reference contract.",
+          "action": "require",
+          "verification": "corroborated",
+          "applies_to": {"package_id": "waveshare_esp32p4_wifi6_touch_lcd_43c_v1_0"},
+          "evidence": [{"board_package_id": "waveshare_esp32p4_wifi6_touch_lcd_43c_v1_0", "source_ref": "waveshare-esp32-p4-wifi6-touch-lcd-4.3-c/knowledge.md#hardware-facts"}]
+        }
+      ]
+    },
     {"package_id":"lckfb_szpi_esp32s3_v1_0_1","status":"knowledge_only","identity":{"vendor":"深圳嘉立创科技集团股份有限公司（立创开发板）","model":"立创·实战派 ESP32-S3 开发板","aliases":["LCKFB SZPI ESP32-S3"],"hardware_revision":"V1.0.1","target":"esp32s3","module":"ESP32-S3 module","flash_mb":16,"psram_mb":8,"components":[{"kind":"camera","model":"GC2145"},{"kind":"aec_reference","model":"ES7210 MIC3 hardware reference"}],"probes":[]},"compatibility":{"idf":"5.5.4","tirtc_sdk":"2.3.0"},"artifacts":{},"lessons":[]},
     {"package_id":"alientek_atk_dnesp32s3_v1","status":"knowledge_only","identity":{"vendor":"正点原子 (ALIENTEK)","model":"ATK-DNESP32S3","aliases":[],"hardware_revision":"V1.0","target":"esp32s3","module":"ATK-MWS3S","flash_mb":16,"psram_mb":8,"components":[{"kind":"camera","model":"OV5640 PID 0x5640"},{"kind":"audio_codec","model":"ES8388"}],"probes":[]},"compatibility":{"idf":"5.5.4","tirtc_sdk":"2.3.0"},"artifacts":{},"lessons":[]}
   ]

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/knowledge/waveshare-esp32-p4-wifi6-touch-lcd-4.3-c/knowledge.md

@@ -0,0 +1,68 @@
+# Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3-C V1.0
+
+Knowledge only. Exact board declared as Waveshare SKU 33875, PCB V1.0, with
+OV5647 installed. The verified product artifact is XiaoTai `43c-port.10`, built
+with ESP-IDF 5.5.4 and the TiRTC P4 2.3.0 validation archive. This package
+records board and component lessons; it does not ship an adapter or authorize
+reuse on another 4.3-inch revision.
+
+## Hardware facts
+
+- ESP32-P4NRW32 with 32 MiB PSRAM, 32 MiB flash and ESP32-C6-MINI-1-N4 Hosted
+  Wi-Fi over SDIO (CLK18/CMD19/D0..3=14..17/RST54).
+- ST7701 MIPI-DSI, two lanes at 500 Mbps, native portrait 480x800, RGB565,
+  DPI 30 MHz, DSI PHY LDO_VO3 at 2.5 V, backlight GPIO26 inverted and reset27.
+- GT911 at I2C 0x5D, native portrait coordinates, RST/INT not connected; polling
+  worked. OV5647 CSI two-lane PID 0x5647 shares I2C1 SDA7/SCL8.
+- ES8311 DAC at 7-bit 0x18 and ES7210 ADC at **7-bit 0x40**, PA GPIO53. Both
+  share I2S1 MCLK13/BCLK12/WS10/DOUT9/DIN11. The codec abstraction used by this
+  port accepts the ES7210 control address in 8-bit form, so pass `0x40 << 1`.
+- ES7210 serial order is CH1/CH3/CH2/CH4. The selected compact DMA pair is
+  `[MIC3 playback reference, MIC2 onboard microphone]`; swap it to the AEC
+  contract `[microphone, reference]`. ES8311 OUTN is physically fed to MIC3.
+- Product key K2 is GPIO23. K1/POWER GPIO21 participates in the PMIC/power path
+  and needs separate short/long-press HIL; BOOT is GPIO35.
+
+## Display failures and resolution
+
+The ST7701 is a RAM-less video panel. Panel `swap_xy` is unavailable, so the
+working product path exposes physical 480x800 to LVGL 8.3, sets `sw_rotate=1`,
+and selects `LV_DISP_ROT_90` for the tested enclosure. GT911 reports native
+coordinates and LVGL applies the same rotation to touch.
+
+Observed traps:
+
+| Symptom | Cause | Correction |
+| --- | --- | --- |
+| Horizontal tear lines | Dirty rectangles copied into the framebuffer being scanned | Compose only in a safe back buffer and request presentation at the DSI frame boundary |
+| Flicker or local UI corruption after double buffering | Alternating buffers contained different generations because only current dirty regions were updated | After flip completion, copy the presented frame's damage into the recycled back buffer before the next LVGL refresh |
+| Startup tear | Code assumed fb0 was the back buffer while DPI initially scanned fb0 | Initialize equal buffers with the backlight off and compose the first frame in fb1 |
+| Portrait/garbled output | LVGL 8.3 90/270 rotation configured without `sw_rotate=1` | Enable software rotation before setting the display rotation |
+| Dark blue rendered yellow/brown | `LV_COLOR_16_SWAP=y` data reached a natural-endian RGB565 DSI input | Byte-swap each RGB565 word once while composing the panel framebuffer |
+| UI did not fill 800x480 | Shared product helpers scaled a 320x240 design grid using fixed predecessor dimensions | Use runtime logical display width/height in position, zoom, video viewport and pool sizing |
+| Touch opposite to UI | Display rotation changed independently of touch mapping | Keep GT911 native coordinates and let LVGL rotate both display and pointer |
+
+`lvgl_port` avoid-tearing did not solve this composition because software
+rotation flushed through temporary non-framebuffer-resident chunks. A PPA
+transpose experiment introduced separate direction/color uncertainty. These
+failed experiments are diagnostic history, not preferred implementations.
+
+## Evidence boundary
+
+User HIL on 2026-09-23 reported UI and video normal with `43c-port.10` after the
+ROT_90 and damage carry-forward correction. This establishes the board display
+path for that artifact, not AEC double-talk, weak-network recovery, PMIC power
+semantics or 24-hour stability.
+
+- Application BIN SHA256:
+  `2fb05d6985401b061ef3778f69b2f2b68a3d43cb6e7af145484d136de1ae2562`
+- ELF SHA256:
+  `38b1ce6f0a5455fbd658b1c5e5275b89a07f2d5a7561652cfac04a5b3e6368de`
+- Local source evidence at capture time:
+  `waveshare-esp32p4-4.3c-xiaotai/`, its Hardware IR, display driver, audio
+  contract and `docs/ESP32-P4-WIFI6-Touch-LCD-4.3-C-移植诊断手册.md`.
+
+Apply the general display invariants from
+[display-pipeline.md](../../references/display-pipeline.md) to other panels.
+Treat the GPIO, rotation, codec address, TDM slots and AEC wiring above as exact
+board facts only.

package/skills/tirtc-esp32-builder/references/display-pipeline.md

@@ -0,0 +1,61 @@
+# Device display pipeline
+
+Use this reference for tearing, intermittent flicker, stale UI regions, wrong
+RGB colors, panel orientation, touch-coordinate mismatch, or UI layouts that do
+not fill a new display. Keep panel scan geometry, LVGL logical geometry, pixel
+storage order, framebuffer ownership and touch mapping as separate facts.
+
+## RAM-less video panels
+
+ST7701 and similar MIPI-DSI video panels continuously scan a framebuffer and
+have no panel RAM that makes a partial write atomic. Identify the buffer being
+scanned before writing. A successful `draw_bitmap` call or two allocated frame
+buffers does not by itself prevent tearing.
+
+For a partial-rendering double-buffer path, prove all of these invariants:
+
+- LVGL writes only the back buffer; initialization must not assume framebuffer
+  zero is free when the controller starts by scanning framebuffer zero.
+- Presentation changes the scan buffer at a frame boundary and the old front
+  buffer is recycled only after the corresponding VSYNC/refresh completion.
+- Before the recycled buffer receives the next dirty regions, carry forward
+  every region changed in the presented frame. Alternating two buffers while
+  updating only the latest dirty rectangles produces different UI generations,
+  seen as intermittent flicker, stale widgets or local corruption.
+- A semaphore token must correspond to a refresh after the requested flip.
+  Drain earlier periodic VSYNC tokens around the request or use a monotonic
+  generation/counter; an already-full binary semaphore is not flip evidence.
+
+Valid implementations include damage carry-forward after VSYNC, a canonical
+shadow frame copied into a safe back buffer, or a genuinely full-frame path.
+Choose using measured memory bandwidth and audio/video deadlines. LVGL 8.3
+software rotation cannot be combined with its `direct_mode` or `full_refresh`
+shortcut; inspect the selected LVGL version before choosing a strategy.
+
+## Rotation, color and touch
+
+- A RAM-less panel's fixed native raster can prevent panel-level `swap_xy`.
+  With LVGL 8.3 partial buffers, set `sw_rotate=1` before selecting 90/270
+  software rotation. `lv_disp_drv_update()` alone does not enable it.
+- Treat 90 versus 270 as a physical installation fact. Verify with asymmetric
+  corner labels on the exact enclosure; a vendor portrait drawing does not
+  decide the product's landscape direction.
+- Let one layer own display and touch rotation. When LVGL rotates the display,
+  feed the touch driver native panel coordinates and verify all four corners.
+  A second manual transform commonly creates a 180-degree mismatch.
+- Derive RGB565 byte order across assets, `LV_COLOR_16_SWAP`, the rotation
+  buffer and the panel input. A dark-blue word rendered yellow/brown is a useful
+  byte-swap signature. Apply one evidenced swap at the framebuffer boundary.
+
+## Layout and video checks
+
+Find design-grid scaling that still uses a predecessor board's fixed width or
+height. Scale against the runtime logical display size, including image zoom,
+canvas placement, call-video viewport, decoder pools and presentation depth.
+Keep camera/encoded-pixel orientation separate from device-display rotation;
+read [video-orientation.md](video-orientation.md) for the remote video path.
+
+Hardware acceptance requires static and animated UI, rapid page changes,
+subtitles or timers, four-corner touch, solid RGB test colors and sustained
+video. Bind the observation to the exact application BIN hash. Compiler success
+does not verify VSYNC ownership, physical rotation or color order.

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(