From 729cd55acf1e42267697f54cde4813b3aa0df368 Mon Sep 17 00:00:00 2001 From: wangsn Date: Fri, 7 Aug 2026 17:34:16 +0800 Subject: [PATCH] docs: correct inaccuracies across guides, references, and tutorials Fix factual errors in docs-site based on actual SDK behavior: - faq: RTC TCP client needs agent_token at connect; remove stale CONNECTION_REFRESH auto-refresh claim - dp-persistence: note that dump/restore omits RAW DPs; schema_id is immutable so no rewrite needed on schema update - ota-upgrade: report success before reboot; add esp_crt_bundle include, cert_bundle_attach field, and required iot_init() call - porting-to-new-platform: correct PAL_FR_TASK_STACK_WORDS size (6144 words ~= 24KB on 32-bit) - vad-and-interrupt: replace session_attrs_json with event_user_data_json/chatAttributes; document default VAD=true - iot-client: expand iot_client_process/publish return values (OPRT_INVALID_PARAMETER, OPRT_UNINITIALIZED, etc.) - openapi-activate: note pairing-result --poll for token verification - pair-by-ble: tuya_ble_nimble_stop() always returns 0 --- docs-site/docs/faq.md | 3 +-- docs-site/docs/guides/dp-persistence.md | 4 ++-- docs-site/docs/guides/ota-upgrade.md | 9 ++++++++- docs-site/docs/guides/porting-to-new-platform.md | 2 +- docs-site/docs/guides/vad-and-interrupt.md | 11 +++++++---- docs-site/docs/reference/iot-client.md | 4 ++-- docs-site/docs/tutorials/openapi-activate.md | 2 +- docs-site/docs/tutorials/pair-by-ble.md | 2 +- 8 files changed, 23 insertions(+), 14 deletions(-) diff --git a/docs-site/docs/faq.md b/docs-site/docs/faq.md index 6f5f1b0..7de5fa1 100644 --- a/docs-site/docs/faq.md +++ b/docs-site/docs/faq.md @@ -89,9 +89,8 @@ UDP实现版本有非常好的弱网性能支持, 即使在网络条件很差的 - 重新调用 `iot_client_get_session_token()` 获取新 token，然后创建新 session **RTC TCP Client：** -- 使用长连接 + Ping/Pong 保活，不依赖 session_token +- 连接建立时需要 `agent_token`（通过 `iot_client_get_session_token()` 获取），但建立后使用长连接 + Ping/Pong 保活，无需定期刷新 token - 如果连接断开（`on_disconnect` 回调），由持有 `tai_ctx_t` 的线程重新调用 `tai_connect()` 即可 -- 连接刷新由协议内部自动处理（`CONNECTION_REFRESH_REQ/RESP`） :::caution 不要在回调里重连 所有回调都运行在后台工作线程上。**绝对不要**在回调（包括 `on_disconnect`）内部调用 `tai_connect()` / `tai_disconnect()` / `tai_ctx_deinit()`——这些函数会 join 工作线程，导致自死锁（self-deadlock）。 diff --git a/docs-site/docs/guides/dp-persistence.md b/docs-site/docs/guides/dp-persistence.md index 0fceedc..1bd1adb 100644 --- a/docs-site/docs/guides/dp-persistence.md +++ b/docs-site/docs/guides/dp-persistence.md @@ -43,7 +43,7 @@ if (iot_dp_dump_json(client, &json) == OPRT_OK && json) { } ``` -`iot_dp_dump_json` 与 `iot_dp_restore_json` 产出 / 消费同一种 `{"dps":{...}}` 格式,可无损往返。 +`iot_dp_dump_json` 与 `iot_dp_restore_json` 产出 / 消费同一种 `{"dps":{...}}` 格式,可往返恢复。**注意:`iot_dp_dump_json` 的快照不含 RAW 类型 DP**(见 `iot_dp.h` 中 RAW omission 说明),因此 dump→restore 周期会丢失运行中的 RAW 值;如需保留 RAW,请通过保存回调(回调快照同样不含 RAW,需应用自行另行保存)或避免依赖其往返。 ## 保存回调在嵌入式上的注意事项 @@ -95,5 +95,5 @@ iot_client_t *client = iot_client_init(&cfg); 应用周期调用 `iot_dp_schema_check_update()` 轮询最新 schema。若有更新,SDK 会**保留仍存在的 DP 的当前值、给新增 DP 填默认值**,然后触发 `iot_schema_update_callback_t`。在该回调里: -1. 把新的 `schema_id` / `schema` 覆盖持久化; +1. 把新的 `schema` 覆盖持久化(`schema_id` 不变,无需重写); 2. 建议随后调一次 `iot_dp_report_all()` 做一次全量同步。 diff --git a/docs-site/docs/guides/ota-upgrade.md b/docs-site/docs/guides/ota-upgrade.md index f6c2690..34d10bd 100644 --- a/docs-site/docs/guides/ota-upgrade.md +++ b/docs-site/docs/guides/ota-upgrade.md @@ -65,7 +65,7 @@ typedef struct { typedef enum { OTA_STATUS_IDLE = 0, // 空闲 OTA_STATUS_UPGRADING = 1, // 升级中（下载/烧写前） - OTA_STATUS_UPGRAD_FINI = 2, // 升级成功（通常重启后回报） + OTA_STATUS_UPGRAD_FINI = 2, // 升级成功（重启前回报） OTA_STATUS_UPGRD_EXEC = 3, // 升级失败 OTA_STATUS_UPGRD_ABORT = 4, // 升级中止 } iot_ota_status_t; @@ -109,6 +109,7 @@ CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_FULL=y #include "iot_client.h" #include "iot_ota.h" #include "esp_app_desc.h" +#include "esp_crt_bundle.h" const esp_app_desc_t *desc = esp_app_get_description(); @@ -122,7 +123,13 @@ iot_client_config_t iot_cfg = { .mqtt_auto_connect = false, /* 应用固件版本：init 时自动上报，供云端 OTA 比较（NULL 用 SDK 默认） */ .sw_ver = desc->version, + /* 公共 CA 证书包：ATOP HTTPS（版本上报/升级查询/状态回报）需要 */ + .cert_bundle_attach = (tls_cert_bundle_attach_fn)esp_crt_bundle_attach, }; + +/* iot_init(pal) 必须在 iot_client_init 前调用，否则 iot_client_init 返回 NULL */ +iot_init(tai_pal_freertos()); + iot_client_t *iot = iot_client_init(&iot_cfg); /* 查询升级（云端与 init 时上报的 sw_ver 比较，无需再传版本号） */ diff --git a/docs-site/docs/guides/porting-to-new-platform.md b/docs-site/docs/guides/porting-to-new-platform.md index 45501ec..8fe6197 100644 --- a/docs-site/docs/guides/porting-to-new-platform.md +++ b/docs-site/docs/guides/porting-to-new-platform.md @@ -146,7 +146,7 @@ CONFIG_FREERTOS_HZ=1000 ## 通用注意事项 -- PAL `thread_create` 需要设置足够的栈大小；`pal_freertos.c` 默认使用 `PAL_FR_TASK_STACK_WORDS`（约 6KB，可按平台内存情况调小或调大） +- PAL `thread_create` 需要设置足够的栈大小；`pal_freertos.c` 默认使用 `PAL_FR_TASK_STACK_WORDS`（6144 words，32 位平台上约 24KB，可按平台内存情况调小或调大） - SDK 内部通过 mbedTLS 处理 TLS，需要正确的系统时间用于证书验证；若未提供 CA 证书，TLS 连接可能退化为不校验证书的模式 - `tcp_recv` 应支持阻塞/超时语义（后台线程会循环调用） - `tcp_poll` 用于检查套接字的可读/可写状态，需正确实现 events 位掩码 diff --git a/docs-site/docs/guides/vad-and-interrupt.md b/docs-site/docs/guides/vad-and-interrupt.md index c38f3dd..4a86e1d 100644 --- a/docs-site/docs/guides/vad-and-interrupt.md +++ b/docs-site/docs/guides/vad-and-interrupt.md @@ -41,19 +41,22 @@ void on_event(tai_ctx_t *ctx, const tai_event_msg_t *msg, void *ud) ### 启用/配置云端 VAD -通过 `session_attrs_json` 传入自定义会话属性 JSON。当前 SDK 只负责原样透传该字符串，具体字段含义和支持情况以平台侧配置为准： +通过 `event_user_data_json` 传入 `chatAttributes`，该字符串会随每个 EventStart 包发送给云端。SDK 默认已启用云端 VAD（留空时使用内置默认值），如需自定义可覆盖： ```c tai_config_t cfg = { // ... - .session_attrs_json = "{\"vad_enable\":true,\"vad_silence_ms\":800}", + .event_user_data_json = + "{\"sys.workflow\":\"asr-llm-tts\"," + "\"asr.enableVad\":true," + "\"processing.interrupt\":true}", }; ``` | 字段 | 类型 | 说明 | |------|------|------| -| `vad_enable` | bool | 是否启用云端 VAD | -| `vad_silence_ms` | int | 静默判定时长（毫秒），默认约 800ms | +| `asr.enableVad` | bool | 是否启用云端 VAD（默认 true） | +| `processing.interrupt` | bool | 是否启用打断处理（默认 true） | ### 设备端 VAD 是否需要？ diff --git a/docs-site/docs/reference/iot-client.md b/docs-site/docs/reference/iot-client.md index f029016..7a1e8c2 100644 --- a/docs-site/docs/reference/iot-client.md +++ b/docs-site/docs/reference/iot-client.md @@ -235,7 +235,7 @@ int iot_client_process(iot_client_t *client, uint32_t timeout_ms); - `client` — IoT 客户端实例 - `timeout_ms` — 处理超时时间（毫秒） -**返回值：** `OPRT_OK` 成功。 +**返回值：** `OPRT_OK` 成功；`client` 为 NULL 时返回 `OPRT_INVALID_PARAMETER`；无 MQTT 连接时返回 `OPRT_UNINITIALIZED`。 --- @@ -252,7 +252,7 @@ int iot_client_publish(iot_client_t *client, const uint8_t *data, size_t data_le - `data` — 明文数据（内部自动加密） - `data_len` — 数据长度 -**返回值：** `OPRT_OK` 成功。 +**返回值：** `OPRT_OK` 成功；`client` 为 NULL 或 `data` 为 NULL / `data_len` 为 0 时返回 `OPRT_INVALID_PARAMETER`；无 MQTT 连接时返回 `OPRT_UNINITIALIZED`；加密缓冲区分配失败返回 `OPRT_MALLOC_FAILED`；加密或发布失败返回 `OPRT_COMMUNICATION_ERROR`。 --- diff --git a/docs-site/docs/tutorials/openapi-activate.md b/docs-site/docs/tutorials/openapi-activate.md index a42fac6..6e896e1 100644 --- a/docs-site/docs/tutorials/openapi-activate.md +++ b/docs-site/docs/tutorials/openapi-activate.md @@ -124,7 +124,7 @@ python3 ./build/tuya_openapi.py pairing-token --uid "ay..." --paring-type BLE \ ## 注意事项 -- 配网 Token 有有效期（通常 100 秒），需在有效期内完成设备激活。 +- 配网 Token 有有效期，需在有效期内完成设备激活；可用 `tuya_openapi.py pairing-result --poll` 轮询确认结果（`--timeout` 默认 100 秒）。 - `tuya_openapi.py` 使用 Python 标准库实现，无需安装额外依赖。 - 实际产品中，OpenAPI 调用应在厂商自己的后台服务中完成，**不应将 Access Secret 暴露在客户端或设备端**。 diff --git a/docs-site/docs/tutorials/pair-by-ble.md b/docs-site/docs/tutorials/pair-by-ble.md index dff36d4..341188e 100644 --- a/docs-site/docs/tutorials/pair-by-ble.md +++ b/docs-site/docs/tutorials/pair-by-ble.md @@ -129,7 +129,7 @@ int tuya_ble_nimble_stop(void); 停止 BLE 广播和服务，释放 NimBLE 资源。 -**返回值：** `0` 成功，非零表示错误。 +**返回值：** 当前实现始终返回 `0`（内部 `nimble_port_stop()` 的结果被忽略，不返回错误码）。 ### `tuya_ble_wifi_creds_t`