tirtc-device-builder 0.10.0 → 0.10.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.10.0",
+  "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,15 @@
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.10.0",
+  "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

@@ -53,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/VERSION

@@ -1 +1 @@
-0.10.0
+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-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.