tirtc-device-builder 0.11.0 → 0.11.1

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 This project follows Semantic Versioning.
 
+## 0.11.1
+
+- Pin the BK7258 public baseline to the official Gitee
+  `release/v3.1.1.8` tag at commit
+  `1cfd56af09a3cb6470f35f1e0c604035ed1b6ee7`; explicitly classify the local
+  `3.1.1.8-20260605` GitLab delivery as modified reference material only.
+- Add artifact-derived LCKFB BK7258 XiaoTai gates for ABI/TLS identity,
+  AP/CP cache provenance, internal-memory budgets, asynchronous credential
+  lifetime, protocol exactness, media truthfulness and hardware acceptance.
+- Define conventional ERROR/WARN/INFO/DEBUG logging: release builds default to
+  INFO without complete wire payloads, while controlled DEBUG builds expose
+  complete HTTP, MQTT and TiRTC/WHIP inputs and results for integration work.
+
 ## 0.11.0
 
 - Add the `tirtc-beken-builder` Skill and CLI platform aliases for BK7258 and

package/package.json

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

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

@@ -14,6 +14,10 @@ Read [architecture](references/architecture.md) when planning a new product or
 explaining the platform split and delivery stages.
 Read [BK probe research](references/bk-research.md) when selecting an SDK line,
 implementing a probe, or checking the primary-source basis for an API.
+Read [LCKFB BK7258 lessons](references/lckfb-bk7258-lessons.md) before porting
+XiaoTai/TiRTC to BK7258, reviewing a BK7258 product project, or accepting its
+build. Apply the gates to the target's evidence; copy the case-study constants
+only when its board, SDK and binary identities match.
 
 ## 1. Establish the target
 
@@ -29,8 +33,12 @@ implementing a probe, or checking the primary-source basis for an API.
    authorizes changing them.
 4. Inspect the selected SDK headers and examples before naming APIs. Beken SDK
    branches differ; source-visible symbols in the pinned checkout outrank prose
-   and this Skill. Start discovery from <https://docs.bekencorp.com/> and
-   <https://github.com/bekencorp/>, then pin the concrete page and revision.
+   and this Skill. Start discovery from <https://docs.bekencorp.com/>,
+   <https://github.com/bekencorp/> and the official Gitee mirror. For the
+   reproducible BK7258 Kit baseline, use official Gitee tag
+   `release/v3.1.1.8` at commit
+   `1cfd56af09a3cb6470f35f1e0c604035ed1b6ee7`. A locally delivered
+   `3.1.1.8-20260605` tree is modified reference material, not that baseline.
 
 Run the read-only environment check when a checkout is available:
 
@@ -103,6 +111,12 @@ when it is available. Then bind the pinned Beken TiRTC library/header and build
 contract. If no compatible Beken TiRTC binary exists, report `BLOCKED_SDK_ABI`;
 do not substitute an ESP32 archive or claim source compatibility.
 
+For BK7258 TiRTC product work, run the case-study gates for AP/CP ownership,
+toolchain and TLS ABI identity, clock/signing order, exact HTTP methods,
+asynchronous credential lifetime, failed-connection draining, internal-SRAM
+headroom and capability-report truthfulness. A successful link is not an ABI or
+runtime-media pass.
+
 ## 5. Build and verify
 
 Build with the exact vendor toolchain and board project. Record the application
@@ -120,9 +134,15 @@ matrix, integration changes, exact artifact identity, HIL results, and remaining
 blockers. Promote a board profile for reuse only after the exact PCB revision
 and its required active probes pass.
 
-## Security boundary
+## Security and logging boundary
 
 Keep device keys, Wi-Fi passwords, MQTT/WHIP tokens, certificates, calibration
-data, MAC-derived identifiers and captured user audio outside source and reports.
-Redact logs. Downloads, account access, flashing, erasing, factory-partition
-changes and publishing a reusable board profile retain separate authorization.
+data, MAC-derived identifiers, captured user audio and captured logs outside
+source control and generated reports. Use the conventional `ERROR`, `WARN`,
+`INFO`, `DEBUG` levels. Product/release firmware defaults to `INFO` and does not
+print complete network request or response payloads. A deliberately enabled
+`DEBUG` build may print complete HTTP, MQTT and TiRTC/WHIP inputs and results,
+including authorization values, for controlled integration work; handle that
+output as sensitive development data and return the build to `INFO` before
+release. Downloads, account access, flashing, erasing, factory-partition changes
+and publishing a reusable board profile retain separate authorization.

package/skills/tirtc-beken-builder/VERSION

@@ -1 +1 @@
-0.11.0
+0.11.1

package/skills/tirtc-beken-builder/references/bk-research.md

@@ -22,10 +22,19 @@ Beken 官方 `bk_idk` README 要求使用 release 分支/tag，而不是随意
 
 本次直接核对了：
 
-- BK7258：`bk_avdk_smp release/v3.1.1`，提交 `993df5647f084551a677a2bc741b200cfd75d5f2`；
+- BK7258 Kit 的公开复现基准：官方 Gitee `bk_avdk_smp`
+  `release/v3.1.1.8`，提交
+  `1cfd56af09a3cb6470f35f1e0c604035ed1b6ee7`；下文固定到
+  `993df5647f084551a677a2bc741b200cfd75d5f2` 的链接是早期
+  `release/v3.1.1` API 调研证据，不能替代 Kit 的版本基准；
 - BK7259：`bk_avdk_smp release/v4.0.1`，提交 `584b947920c414230f9909375f008e7d6a2c6c6b`，该提交包含 `bk7259_ap` SoC/BSP、BK7259 音频库、显示与触控实现，可作为公开可复现基线。[BK7259 defconfig](https://github.com/bekencorp/bk_avdk_smp/blob/584b947920c414230f9909375f008e7d6a2c6c6b/ap/middleware/soc/bk7259_ap/bk7259_ap.defconfig) [BK7259 音频能力头](https://github.com/bekencorp/bk_avdk_smp/blob/584b947920c414230f9909375f008e7d6a2c6c6b/ap/include/soc/bk7259/aud_cap.h)
 
-因此建议 skill 把 SDK baseline 固定为 tag/commit，并为 BK7258 v3.1.1 与 BK7259 v4.0.1 分设 adapter。不要假定两个版本的目录和显示 API 完全相同：v4 已把 panel 注册进一步改为 linker-section 模式。
+本机名为 `bk_avdk_smp_v3.1.1.8_20260605` 的 GitLab 交付目录含私有
+Tange 组件及音频、DVP、H.264、lwIP、编译选项和工程配置差异，只作为
+问题案例参考，不能作为公开基准或声称与 Gitee 标签等同。因此 skill 把
+SDK baseline 固定为 tag/commit，并为 BK7258 v3.1.1.8 与 BK7259 v4.0.1
+分设 adapter。不要假定两个版本的目录和显示 API 完全相同：v4 已把
+panel 注册进一步改为 linker-section 模式。
 
 ## 已确认的可探测能力
 
@@ -127,7 +136,9 @@ skill 流程：识别 SDK/tag 与 target → 导入/生成 board profile → 构
 
 ## 推荐落地顺序
 
-1. 首版支持两条固定基线：BK7258 `v3.1.1.x`、BK7259 `v4.0.1.x`；
+1. 首版支持两条固定基线：BK7258 官方 Gitee `release/v3.1.1.8`
+   (`1cfd56af09a3cb6470f35f1e0c604035ed1b6ee7`) 与 BK7259
+   `release/v4.0.1`；
 2. 先实现 Flash/heap/PSRAM/touch 与 manifest，因这些已有明确官方 API；
 3. 再实现 profile 驱动的 LCD ID/readback + test pattern；
 4. 实现 audio format sweep、录音统计与安全声学回环；

package/skills/tirtc-beken-builder/references/lckfb-bk7258-lessons.md

@@ -0,0 +1,152 @@
+# LCKFB BK7258 XiaoTai lessons
+
+Use this case study for BK7258 XiaoTai/TiRTC ports and reviews. It distils the
+failures fixed in `lckfb-bk7258-xiaotai` through source commit `8a156ff`. These
+are gates, not a generic board profile: retain the decisions, but use the exact
+numbers only when the target matches the identity below.
+
+## Identity gate
+
+The reproducible public SDK baseline is:
+
+- default LCKFB BK7258 board;
+- official Beken Gitee repository `bekencorp/bk_avdk_smp`, tag
+  `release/v3.1.1.8`, commit
+  `1cfd56af09a3cb6470f35f1e0c604035ed1b6ee7`;
+- GCC Arm None EABI 10.3.1, Cortex-M33, hard-float;
+- TiRTC-Nano 2.3.0 `mini`, BK7258 hard-float archive;
+- TiRTC build metadata reporting Mbed TLS 2.25.0, linked with the project's
+  BK7258 Mbed TLS 2.28.5 compatibility archive;
+- AP + CP + bootloader package and 16 MiB PSRAM.
+
+The locally delivered folder named `bk_avdk_smp_v3.1.1.8_20260605` contains a
+private Tange component and changes to audio, DVP, H.264, lwIP, build options and
+project configuration. It is useful only as implementation and fault-history
+evidence. Do not identify it as the public tag, use it for SDK checksums, or make
+it the default Kit source.
+
+Hash the TiRTC and compatibility archives and record the SDK commit, compiler,
+float ABI, libc/RTOS and partition maps. AP-only or CP-only output is diagnostic;
+the deliverable is the combined package. A different value makes a new artifact
+that must pass link, DTLS/WHIP and hardware validation again. Disable the SMP
+SDK's ABI-incompatible PSA Mbed TLS 3 path when using this TiRTC package.
+Treat the AP and CP CMake caches as part of the SDK identity: both the cached
+toolchain path and `beken-armino_SOURCE_DIR` must point inside the selected
+official checkout. Reject or clean a cache created by the local modified SDK;
+otherwise a nominally successful package can silently mix SDK implementations.
+
+## Board truth gate
+
+The demonstrated LCKFB board uses a 320x240 ST7789V2 SPI display in landscape,
+an active-low KEY on GPIO7, onboard microphone/speaker paths, an 8 MiB Flash and
+16 MiB PSRAM. It has no fitted touch controller. The optional FT6336 code and
+simulated-I2C GPIO42/43 profile describe a later product board; their presence
+in the source is not evidence of touch on the LCKFB board.
+
+Check the actual LCD bus/pin profile before debugging pixels, then validate
+panel rotation and touch rotation independently. On this board expose status,
+AI and call state plus the verified KEY actions; keep touch-only contact, room
+and settings navigation disabled.
+
+## Resource gate
+
+Physical capacity did not predict product viability:
+
+- 8 MiB Flash was constrained by the AP code partition, not total Flash. The
+  demonstrated layout uses 1904 KiB AP code, 1360 KiB CP code and a 680 KiB
+  resource partition; a full roughly 1 MiB CJK font still does not fit the
+  intended UI budget. Use a product glyph subset and measure the linked image.
+- TiRTC/DTLS needs internal SRAM and sufficiently large contiguous blocks;
+  free PSRAM does not replace them. The project reclaimed SRAM by reducing the
+  single-session lwIP heap to 80 KiB and TCP send/window sizes to 22 MSS, then
+  measured the final workload. Those values are evidence for this product, not
+  defaults for every board.
+- Reserve the roughly 80 KiB DVP/H.264 controller block before network/TiRTC
+  fragmentation. Place eligible supervisor/task storage in PSRAM while keeping
+  DMA/internal-only objects in the correct region.
+- Size deep WebClient/TLS call stacks from high-water evidence. Move large URL,
+  authorization and credential buffers off the control-task stack with bounded
+  heap ownership. The demonstrated control and bootstrap tasks required more
+  headroom than the original 8 KiB assumptions.
+- Keep `CONFIG_LWIP_MEM_STATS` and `CONFIG_LWIP_MEMP_STATS` enabled when the
+  selected AVDK allocator references their fields; removing apparently unused
+  statistics can break the build.
+
+Report boot, post-driver and worst-session internal free/minimum/largest block,
+PSRAM free/minimum/largest block and every static partition/image size. Reject
+the build when only aggregate free bytes are known.
+
+## Platform and protocol gate
+
+Lock these semantics with host contract tests instead of rediscovering them on
+hardware:
+
+- synchronize network time in the current boot before signed requests or
+  TiRTC startup; bridge newlib `_gettimeofday()` to the AON RTC when the SDK
+  otherwise links the failing libnosys stub;
+- preserve the platform's exact MAC text/client identity and route product APIs
+  through the discovered `device`, `ai`, `call` and `voip` services;
+- preserve HTTP method and body identity: the device-token operation is an
+  empty-body POST, not GET and not `{}`. In the demonstrated AVDK WebClient,
+  `webclient_post(..., NULL, 0)` also requires explicit response handling;
+- configure the send buffer before `TiRtcInit`, initialize/start one TiRTC
+  process, and pass SDK option string lengths with the exact convention used by
+  the matching headers/reference. For TiRTC 2.3.0 here, string lengths exclude
+  the trailing NUL;
+- treat a positive `TIRTC_OPT_TGTRP_POLL_TIMEOUT` return as the applied timeout,
+  not a failure. A false retry loop repeatedly initialized/uninitialized SDK
+  task state;
+- retain WHIP peer descriptors and bearer tokens in bounded storage until the
+  asynchronous callback completes. Pointers into a freed JSON tree are invalid;
+- keep one outgoing connect in flight. A failed or stale callback that returns a
+  connection handle must disconnect/drain that handle before another attempt;
+  generation and monotonic-deadline checks prevent late callbacks reviving an
+  expired owner.
+
+Service URL schemes are a product/deployment contract. Preserve the exact
+descriptor returned for the operation that consumes it; apply any HTTP/WHIP
+normalization only when the pinned platform and TiRTC package require and test
+it. Do not generalize this case study into a universal plain-transport rule.
+
+## Media and capability gate
+
+The demonstrated audio contract is 8 kHz, 16-bit mono PCM with 20 ms TiRTC
+G.711 A-law packets; the board path may capture/play in larger chunks. SDK
+callbacks enqueue bounded copies and return. A camera-start failure degrades
+video while leaving an otherwise valid audio session active.
+
+BK7258 provides H.264 encoding but no demonstrated H.264 hardware decoder. The
+AVDK virtual H.264 decoder is NAL inspection/logging, not decoded video. The
+validated STREAM direction is native H.264 1280x720 at 10 fps uplink plus
+full-duplex audio. Report call/VoIP as audio-only until their video path passes.
+For local remote-video display, first prove a platform-negotiated 320x240
+JPEG/MJPEG path and hardware JPEG decode; otherwise require server transcoding
+or another SoC.
+
+Capability JSON must describe only implemented paths using fields accepted by
+the live profile API. A camera driver, an encoder block or TiRTC `on_video`
+callback alone does not justify bidirectional-video advertising.
+
+## Release gate
+
+Require a host contract test plus artifact-bound HIL. At minimum verify:
+
+- exact archive hashes, ABI/config/partition invariants and AP-only TiRTC
+  ownership;
+- provisioning, binding, clock, signed login and one complete capability report;
+- first uplink/downlink audio frames and first H.264 frame;
+- ten AI enter/exit cycles after background polling starts, with no UsageFault,
+  HardFault, reboot, leaked media owner or permanent busy state;
+- camera failure with audio preserved, two consecutive remote-view sessions,
+  connect/confirmation timeouts and late-callback rejection;
+- minimum/largest internal heap during DTLS, camera and full-duplex overlap.
+
+Use conventional `ERROR`, `WARN`, `INFO`, `DEBUG` levels. The checked-in release
+configuration defaults to `INFO`; at that level log failures, recovery and state
+transitions but not complete network inputs or responses. An explicitly enabled
+`DEBUG` build prints complete HTTP, MQTT and TiRTC/WHIP inputs and results,
+including authorization values, so developers can reproduce protocol failures.
+Contract tests must keep those full-payload format strings behind `BK_LOGD` or
+an equivalent DEBUG guard and reject them at INFO/WARN/ERROR. Treat DEBUG logs as
+sensitive development artifacts, keep them out of source control and restore
+INFO before producing release firmware.

package/skills/tirtc-beken-builder/references/probe-porting.md

@@ -5,11 +5,13 @@ SDK/BSP project.
 
 ## SDK baseline
 
-For BK7258 multimedia work, start with Beken's `bk_avdk_smp`. Prefer the highest
-formal `release/v3.1.1.x` tag compatible with the product solution; the moving
-`release/v3.1.1` branch contains unreleased maintenance work. Keep an upper-layer
-solution and SDK on matching tags. Confirm BK7259 against its own published
-support matrix and release line rather than assuming BK7258 compatibility.
+For BK7258 multimedia work, start with Beken's official Gitee `bk_avdk_smp`
+tag `release/v3.1.1.8`, commit
+`1cfd56af09a3cb6470f35f1e0c604035ed1b6ee7`. Do not substitute the locally
+delivered `3.1.1.8-20260605` tree: it contains product/private modifications and
+is reference evidence only. Keep an upper-layer solution and SDK on matching
+tags. Confirm BK7259 against its own published support matrix and release line
+rather than assuming BK7258 compatibility.
 
 ## Output contract
 

package/skills/tirtc-beken-builder/references/tirtc-integration.md

@@ -1,6 +1,8 @@
 # TiRTC integration on Beken
 
 Use this reference when moving from hardware diagnosis to XiaoTai business code.
+For BK7258, also read the artifact-derived
+[LCKFB lessons](lckfb-bk7258-lessons.md) and apply its release gates.
 
 ## Compatibility gate
 
@@ -10,6 +12,10 @@ stack and required callbacks. Record their versions and hashes. An ESP32 library
 is not portable evidence. When a compatible package is unavailable, hardware
 diagnosis can finish but business integration is `BLOCKED_SDK_ABI`.
 
+Compatibility includes TLS dependencies. Record the Mbed TLS ABI expected by
+the TiRTC archive and the exact archive/headers selected by the platform build;
+a successful static link still requires a device DTLS/WHIP handshake.
+
 ## Stable/application boundary
 
 Stable product modules own:
@@ -42,5 +48,20 @@ screen widget own a second session state machine.
 7. Re-run the probe/resource snapshot in the final firmware and bind HIL results
    to its SHA-256.
 
+Lock exact HTTP method/body semantics, option-length conventions, callback
+object lifetimes and unusual SDK return values in host contract tests. Measure
+internal free/minimum/largest heap during connect; PSRAM totals alone do not
+clear the resource gate.
+
 Use the exact selected TiRTC header for lifecycle and callback details; public
 documentation is context, not a substitute for the binary's build contract.
+
+## Logging contract
+
+Use `ERROR` for failed operations that cannot continue, `WARN` for degraded or
+recoverable behavior, `INFO` for lifecycle/state summaries, and `DEBUG` for wire
+diagnostics. Default product builds to INFO. At DEBUG, log complete HTTP method,
+URL, headers, body and response; MQTT connect/subscribe/publish/receive fields and
+payloads; and TiRTC/WHIP descriptors, authorization values, callback results and
+generation identifiers. At INFO and above, do not print those complete network
+inputs or responses. Lock both sides of this rule in host contract tests.

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.11.0
+0.11.1