云平台接入 SDK

本页面介绍 AC79 AIoT SDK 中接入主流物联网云平台（腾讯云 IoT Explorer、阿里云 IoT、涂鸦 Tuya）的 SDK 体系：包括各云平台的目录结构、移植层（HAL）、数据模板/设备模型机制、配置方式与端到端接入流程。

Purpose and Scope

本页面覆盖 AC79 平台上三类云平台接入能力的完整技术细节：

• 腾讯云 IoT Explorer SDK（apps/common/LLM/tc_iot_twetalk/qcloud_iot_explorer_sdk/）：包含 FreeRTOS 移植层（HAL）、数据模板（Property/Event/Action）机制、MQTT 订阅管理、BLE llsync 配网与 COS 固件下载；
• 阿里云 IoT SDK（lib/net/aliyun/）：包含 dev_model 设备模型体系、COAP/MQTT 通道、OTA（FOTA/COTA）、设备影子等；
• 涂鸦 Tuya SDK 接入配置（CONFIG_TUYA_SDK_ENABLE）：涉及固件分区（profile 区）与链接脚本配置。

以下主题属于相邻页面，不在本页展开：Wi-Fi 配网与网络管理本身（见网络管理相关页面）、具体应用层的 LLM 对话逻辑（见 LLM 应用页面）、BLE 协议栈细节（见 BLE 相关页面）。本页聚焦于"如何把设备接入云平台"这一能力的 SDK 结构与运行机制。

Overview

AC79（杰理 AC79NN 系列）AIoT SDK 面向音频、摄像头、故事机等智能硬件场景，设备需要与云端进行属性上报、事件上报、指令下发、OTA 升级等交互。SDK 提供三类接入路径：

1. 腾讯云 IoT Explorer：完整移植的官方 IoT Explorer SDK（基于 Tencent IoT Hub），通过 port/ 目录下的 HAL 适配层对接 AC79 的 FreeRTOS、Wi-Fi、NVS、OTA、BLE 等能力；src/ 目录实现数据模板（物模型）的 MQTT 通信、解析与回调分发。
2. 阿里云 IoT：阿里官方 LinkSDK 的 dev_model（设备模型）体系，包含设备管理（dm_*）、OTA、日志上报、设备影子等模块，COAP 通道指向 coaps://%s.coap.cn-shanghai.link.aliyuncs.com:5684。
3. 涂鸦 Tuya：通过编译宏 CONFIG_TUYA_SDK_ENABLE 使能，并在固件分区中预留 TUYA profile 区域（TUYA_LEN=0x1000，即 4KB）。

三类 SDK 的共同点是：云厂商提供协议栈与设备模型，AC79 SDK 提供 OS/网络/存储/OTA 的适配层，应用层只需按物模型填写属性、事件与指令回调，即可完成云端互联。

Architecture

flowchart TD
    subgraph sg_App["应用层 (apps/)"]
        App["应用代码 (LLM / 摄像头 / 故事机)"]
    end

    subgraph sg_QCloud["腾讯云 IoT Explorer SDK"]
        QTemplate["数据模板 data_template_*"]
        QMqtt["MQTT 通信层"]
        QBle["BLE llsync 配网"]
        QCos["COS 固件下载"]
        QPort["HAL 移植层<br/>HAL_OS/TCP/WiFi/NVS/OTA"]
    end

    subgraph sg_Aliyun["阿里云 IoT SDK (lib/net/aliyun)"]
        ADm["dev_model 设备模型<br/>dm_api / dm_manager"]
        AMqttCoap["MQTT / COAP 通道<br/>iotx_cm_coap"]
        AOta["OTA (FOTA/COTA)"]
        AShadow["设备影子 dm_shadow"]
        ACerts["根证书 certs/root_ca"]
    end

    subgraph sg_Tuya["涂鸦 SDK"]
        TConfig["CONFIG_TUYA_SDK_ENABLE"]
        TFlash["TUYA profile 分区 0x1000"]
    end

    subgraph sg_Platform["云平台服务端"]
        TCloud["腾讯云 IoT Explorer"]
        ACloud["阿里云 IoT (上海)"]
        TuyaCloud["涂鸦云"]
    end

    App --> QTemplate
    App --> ADm
    App --> TConfig

    QTemplate --> QMqtt
    QMqtt --> QPort
    QBle --> QPort
    QCos --> QPort
    QPort --> TCloud

    ADm --> AMqttCoap
    ADm --> AOta
    ADm --> AShadow
    AMqttCoap --> ACerts
    ACerts --> ACloud

    TConfig --> TFlash
    TFlash --> TuyaCloud

架构解读：

• 应用层通过各云 SDK 提供的物模型 API（腾讯云 data_template_*、阿里云 dm_api）上报属性/事件、接收指令，不直接接触协议细节；
• 腾讯云 SDK 内部按"数据模板（物模型）→ MQTT 会话 → HAL 移植层"分层，HAL 层是 AC79 适配的关键，覆盖 FreeRTOS 线程/互斥锁、TCP/UDP Socket、Wi-Fi 状态、NVS 持久化、OTA 烧录、定时器与软 AP 配网；
• 阿里云 SDK 以 dev_model 为核心，dm_client/dm_server 处理上下行，dm_tsl_alink 解析物模型（TSL/ALink JSON），COAP 通道用于轻量级通信，根证书随固件内置；
• 涂鸦 SDK 以编译宏 + 分区预留方式接入，链接脚本（sdk_ld_sdram.c / sdk_ld_sfc.c）中导出 lib_aliyun_version 等符号用于版本标识。

腾讯云 IoT Explorer SDK 详解

腾讯云 SDK 位于 apps/common/LLM/tc_iot_twetalk/qcloud_iot_explorer_sdk/，是 Tencent IoT Hub 官方 SDK（MIT License，Copyright 2018-2021 THL A29 Limited）在 AC79 上的完整移植。

目录结构

数据模板（物模型）机制

数据模板是腾讯云 IoT Explorer 的物模型实现，将设备能力抽象为 属性（Property）、事件（Event） 与 指令（Action） 三类。data_template_mqtt.c 中通过枚举与 topic 模板将三者统一映射到 MQTT 主题：

typedef enum {
    DATA_TEMPLATE_DIRECTION_UP = 0,
    DATA_TEMPLATE_DIRECTION_DOWN,
} DataTemplateDirection;

static int _data_template_topic_generate(char *buf, int buf_len, DataTemplateDirection direction, DataTemplateType type,
        const char *product_id, const char *device_name)
{
    const char *topic_method[] = {
        [DATA_TEMPLATE_TYPE_PROPERTY] = "property",
        [DATA_TEMPLATE_TYPE_EVENT]    = "event",
        [DATA_TEMPLATE_TYPE_ACTION]   = "action",
    };
    // $thing/down/property/C283SMY3W3/test1
    return HAL_Snprintf(buf, buf_len, "$thing/%s/%s/%s/%s", direction ? "down" : "up", topic_method[type],
                        STRING_PTR_PRINT_SANITY_CHECK(product_id), STRING_PTR_PRINT_SANITY_CHECK(device_name));
}

来源：data_template_mqtt.c

设计意图： 将 topic 生成集中到一个函数，通过 DataTemplateType 数组索引直接得到 property/event/action 方法名，再拼接 $thing/{up|down}/{method}/{product_id}/{device_name}。DATA_TEMPLATE_DIRECTION_UP 对应上行（设备→云）发布，DATA_TEMPLATE_DIRECTION_DOWN 对应下行（云→设备）订阅，一次定义即可复用于属性、事件、指令三条链路。

订阅与消息分发

订阅采用"按需检查 + 注册回调"策略：data_template_topic_check_and_sub 先判断对应下行 topic 是否已订阅（IOT_MQTT_IsSubReady），已订阅则直接注册上下文；未订阅则创建上下文链表、按 QOS1 发起订阅，并把 on_message_handler 绑定到对应类型的处理函数：

int data_template_topic_check_and_sub(void *client, DataTemplateType type, DataTemplateContext context)
{
    OnMessageHandler msg_handle[] = {
        [DATA_TEMPLATE_TYPE_PROPERTY] = data_template_property_message_handler,
        [DATA_TEMPLATE_TYPE_EVENT]    = data_template_event_message_handler,
        [DATA_TEMPLATE_TYPE_ACTION]   = data_template_action_message_handler,
    };

    char data_template_topic[MAX_SIZE_OF_CLOUD_TOPIC];
    _data_template_topic_generate(data_template_topic, MAX_SIZE_OF_CLOUD_TOPIC, DATA_TEMPLATE_DIRECTION_DOWN, type,
                                  IOT_MQTT_GetDeviceInfo(client)->product_id,
                                  IOT_MQTT_GetDeviceInfo(client)->device_name);
    if (IOT_MQTT_IsSubReady(client, data_template_topic)) {
        return data_template_context_register(client, type, context);
    }
    ...
    SubscribeParams sub_params    = DEFAULT_SUB_PARAMS;
    sub_params.on_message_handler = msg_handle[type];
    sub_params.qos                = QOS1;
    sub_params.user_data          = data_template_context_list;
    sub_params.user_data_free     = utils_list_destroy;

来源：data_template_mqtt.c

设计意图： 消息处理器按类型索引成表，新增物模型类型只需扩展数组；user_data 携带上下文链表、user_data_free 绑定链表销毁函数，保证断线重连或注销时资源可回收，避免内存泄漏。QOS1 确保下行指令至少送达一次，适合指令类场景。

BLE llsync 配网与 COS 固件下载

腾讯云 SDK 除了 MQTT 数据通道外，还集成了两套与云端联动的能力：

• BLE llsync（低功耗蓝牙低功耗同步配网）：ble_llsync_service.c 实现 llsync 服务，ble_llsync_device_info.c 管理设备信息（product_id、device_name 等）。配网流程为：手机 App 通过 BLE 与设备建立 llsync 会话，将 Wi-Fi SSID/密码以及云凭证（设备密钥）下发给设备，设备再通过 HAL_wifi_ac79.c 连接路由器并完成 MQTT 上线。这解决了无屏设备（如故事机）无法手动输入 Wi-Fi 密码的痛点。
• COS 固件下载：cos_download.c 实现从腾讯云对象存储 COS 拉取固件，与 HAL_ota_ac79.c 配合完成 OTA。其典型场景是：设备通过 MQTT 收到 OTA 指令（含 COS 下载地址），随后走 HTTPS/HTTP 下载并校验，最后调用 HAL OTA 接口写入 flash。

flowchart LR
    subgraph sg_Phone["手机 App"]
        Phone["厂商 App (llsync)"]
    end
    subgraph sg_Device["AC79 设备"]
        Ble["BLE llsync 服务<br/>ble_llsync_service.c"]
        Wifi["HAL_wifi_ac79.c"]
        Mqtt["MQTT 数据通道"]
        Cos["cos_download.c"]
        Ota["HAL_ota_ac79.c"]
    end
    subgraph sg_Cloud["腾讯云"]
        Explorer["IoT Explorer"]
        CosSrv["COS 对象存储"]
    end

    Phone -->|"BLE 下发 Wi-Fi + 设备密钥"| Ble
    Ble --> Wifi
    Wifi -->|"连接路由器"| Mqtt
    Mqtt <-->|"$thing 物模型"| Explorer
    Explorer -->|"OTA 指令 (含 COS URL)"| Mqtt
    Mqtt --> Cos
    Cos -->|"下载固件"| Ota
    CosSrv --> Cos

阿里云 IoT SDK 详解

阿里云 SDK 位于 lib/net/aliyun/，是阿里 LinkSDK（Copyright 2015-2018 Alibaba Group Holding Limited）的设备端实现，核心是 dev_model（设备模型）体系。

模块划分

COAP 通道与服务器寻址

iotx_cm_coap.c 定义了 COAP 通道的服务器地址，区分预发布（pre）与在线环境：

#ifdef ON_PRE
#define IOTX_COAP_SERVER_URI      "coaps://pre.coap.cn-shanghai.link.aliyuncs.com:5684"
#else /* online */
#define IOTX_COAP_SERVER_URI      "coaps://%s.coap.cn-shanghai.link.aliyuncs.com:5684"
#endif

来源：iotx_cm_coap.c

设计意图： 使用 ON_PRE 编译宏区分预发布与生产环境，避免联调期误连生产服务器；在线环境通过 %s 占位符注入设备所属 region（如 cn-shanghai），使同一份固件可适配多地部署。COAP 采用 DTLS（coaps://）保证轻量设备的安全传输，适合低功耗、低带宽场景。

设备影子与 OTA

• 设备影子（dm_shadow）：云端维护一份设备的影子 JSON（含 reported 期望状态与 desired 期望状态），设备离线时云端指令暂存于 desired，设备上线后拉取并同步，保证离线指令不丢失——这是弱网设备的核心一致性机制。
• FOTA/COTA：dm_fota.c 负责固件升级，dm_cota.c 负责配置（参数）升级，两者都依赖 dm_ota.c 的下载与校验流程。链接脚本（sdk_ld_sdram.c / sdk_ld_sfc.c）中导出的 lib_aliyun_version 符号用于在版本信息区标识 SDK 版本。

涂鸦 Tuya 接入配置

涂鸦 SDK 以编译期宏 + 固件分区方式接入：

• 编译宏：CONFIG_TUYA_SDK_ENABLE 使能涂鸦 SDK 编译与链接；
• 固件分区：cpu/wl82/tools/isd_config_rule.c 在 CONFIG_TUYA_SDK_ENABLE 下为涂鸦预留独立 profile 区域：

#if defined CONFIG_TUYA_SDK_ENABLE
TUYA_ADR=AUTO; [涂鸦profile]
TUYA_LEN=0x1000;
TUYA_OPT=1;

来源：isd_config_rule.c

设计意图： 涂鸦云接入需要保存设备激活凭证（激活码/密钥）与配网状态，因此必须在固件烧录规则中显式划分独立 flash 分区（TUYA_LEN=0x1000，4KB），TUYA_ADR=AUTO 让工具自动选择可用地址，避免与其他分区（如升级区、参数区）重叠；TUYA_OPT=1 使能该分区的特殊处理。这种"宏使能 + 分区预留"的接入方式与腾讯云/阿里云 SDK 源码内嵌不同，涂鸦以预编译库 + 配置接入，因此 SDK 本体不随仓库源码分发。

Core Flow：设备接入云端全流程

以腾讯云 IoT Explorer 为例，AC79 设备从上电到云端双向通信的完整时序如下：

sequenceDiagram
    participant App as 应用层
    participant QSdk as 腾讯云 SDK<br/>(data_template_*)
    participant HAL as HAL 移植层
    participant Net as Wi-Fi / 网络栈
    participant Cloud as 腾讯云 IoT Explorer

    App->>QSdk: IOT_* 初始化 + 设备信息注入<br/>(product_id/device_name/密钥)
    QSdk->>HAL: HAL_OS 创建线程 / 互斥锁
    QSdk->>Net: HAL_TCP/UDP 建立网络连接
    QSdk->>Cloud: MQTT 连接 + TLS 握手<br/>(证书来自 HAL 或内置)
    Cloud-->>QSdk: CONNACK (会话建立)
    QSdk->>QSdk: data_template_topic_check_and_sub<br/>生成 $thing/down/{property|event|action} topic
    QSdk->>Cloud: SUBSCRIBE (QOS1)
    Cloud-->>QSdk: SUBACK
    QSdk-->>App: 上线就绪回调
    App->>QSdk: 上报属性 (data_template_property)
    QSdk->>Cloud: PUBLISH $thing/up/property/... (QOS1)
    Cloud-->>QSdk: 下行指令 $thing/down/action/...
    QSdk->>QSdk: data_template_action_message_handler 分发
    QSdk-->>App: 指令回调 (应用处理业务)

关键步骤说明：

1. 初始化与鉴权：应用层注入云端三元组（product_id / device_name / 设备密钥），SDK 据此计算 MQTT clientId 与用户名密码（Hmac 签名），并完成 TLS 双向/单向认证；
2. 订阅准备：data_template_topic_check_and_sub 是上线的必经步骤，它保证三类下行 topic（property/event/action）都已订阅且消息处理回调已注册，之后应用才能安全收发物模型消息；
3. 上行发布：属性/事件经 data_template_property.c / data_template_event.c 序列化为 JSON，发布到 $thing/up/...；云端物模型校验通过后写入设备影子；
4. 下行分发：云端指令到达 $thing/down/... 后，MQTT 层按订阅时注册的 handler 路由到对应类型的消息处理函数，再由应用回调执行实际业务；
5. 断线恢复：HAL 层感知网络断开后，SDK 按指数退避重连，重连成功后自动恢复订阅（因为 IsSubReady 检查 + 重新 SUBSCRIBE），云端缓存的指令在影子/队列机制下补发。

阿里云路径的时序类似，差异在于：入口为 dm_api.c 的 IOT_* 接口、物模型解析走 dm_tsl_alink.c、COAP 通道用于轻量级场景，且设备影子（dm_shadow）承担离线指令缓存角色。

Configuration Options

API Reference（核心接口）

以下为从源码中提取的关键接口签名（以腾讯云数据模板层为主）：

data_template_topic_check_and_sub(void *client, DataTemplateType type, DataTemplateContext context): int

检查下行 topic 是否已订阅，未订阅则创建上下文链表并发起 QOS1 订阅，同时绑定对应类型的消息处理回调。

参数：

• client (void*)：MQTT 客户端实例；
• type (DataTemplateType)：物模型类型，取 DATA_TEMPLATE_TYPE_PROPERTY / DATA_TEMPLATE_TYPE_EVENT / DATA_TEMPLATE_TYPE_ACTION；
• context (DataTemplateContext)：该类型对应的上下文（回调与用户数据）。

返回： 遵循 IotReturnCode 约定，QCLOUD_RET_SUCCESS 表示成功，QCLOUD_ERR_MALLOC 表示内存分配失败（topic 生成或上下文链表创建失败时）。

_data_template_topic_generate(char *buf, int buf_len, DataTemplateDirection direction, DataTemplateType type, const char *product_id, const char *device_name): int

生成 $thing/{up|down}/{property|event|action}/{product_id}/{device_name} 形式的 topic 字符串。

参数：

• buf / buf_len：输出缓冲区及其长度；
• direction：DATA_TEMPLATE_DIRECTION_UP（上行发布）或 DATA_TEMPLATE_DIRECTION_DOWN（下行订阅）；
• type：物模型类型，决定 topic 方法名；
• product_id / device_name：云端三元组中的产品 ID 与设备名（经 STRING_PTR_PRINT_SANITY_CHECK 防空指针）。

返回： topic 字符串长度（>0 成功），否则失败。

阿里云侧（lib/net/aliyun/dev_model/）

• dm_api.c 提供设备模型对外统一入口（IOT_* 系列）；dm_manager.c 负责模块注册与生命周期；iotx_cm_coap.c 提供 COAP 通道，其服务器 URI 由 ON_PRE 宏与 region 占位符共同决定。具体函数签名以各模块头文件为准。

Failure Modes、边界情况与并发

网络断连与重连

• 腾讯云数据模板层的订阅状态依赖 IOT_MQTT_IsSubReady 判断：断线重连后 SDK 需重新走 data_template_topic_check_and_sub，若 HAL 层未及时上报网络恢复，可能导致订阅滞后、下行指令丢失；云端侧的影子/队列机制可补偿。
• 阿里云 COAP 通道使用 DTLS（coaps://），握手失败（证书过期、时钟未同步）会直接导致通道不可用；certs/root_ca.c 内置根证书需与云端签发链匹配。

内存与资源边界

• _data_template_context_push 与 utils_list_create 失败均返回 QCLOUD_ERR_MALLOC，调用方需检查返回值并销毁已创建的链表（utils_list_destroy），否则会泄漏——代码中通过 user_data_free = utils_list_destroy 将销毁责任交给 MQTT 层，规避了该风险。
• topic 缓冲区使用 MAX_SIZE_OF_CLOUD_TOPIC 上限，HAL_Snprintf 截断时返回长度可能不可靠，超长 product_id/device_name 属非法配置，应在应用层校验。

并发访问

• SDK 内部线程模型为：MQTT 收包线程 + 应用调用线程 + 定时器线程（HAL_OS_free_rtos.c / HAL_Timer_free_rtos.c）。上行发布与下行回调可能并发触碰同一物模型变量，应用层需自行保证属性读写的互斥；dm_message_cache.c 的存在说明阿里云侧消息在收发线程间有缓存队列，需注意队列满时的背压处理。

边界情况

• STRING_PTR_PRINT_SANITY_CHECK 宏对 product_id/device_name 做空指针防护，避免 HAL_Snprintf 传入 NULL 导致崩溃；
• IOT_MQTT_IsSubReady 在未连接时返回未就绪，data_template_topic_check_and_sub 会尝试重新订阅，调用方需处理其返回错误码（如 QCLOUD_ERR_MALLOC）；
• 涂鸦分区 TUYA_ADR=AUTO 在 flash 空间紧张时可能与其他分区冲突，量产前应核对 isd_config_rule.c 生成的地址分配表。

性能与运维注意事项

• QOS1 双倍流量：腾讯云下行订阅固定 QOS1，每消息有 PUBACK 往返；高频属性上报建议走 QOS0 或批量上报，减少空口占用；
• COAP 轻量通道：阿里云 COAP 相比 MQTT 更省电省流量，适合电池供电的低频上报场景；高频双向交互应改用 MQTT；
• OTA 流量峰值：COS/dm_ota 下载固件时会产生大流量突发，应错峰触发，且下载线程优先级需低于实时音频/视频线程，避免卡顿；
• 日志与版本标识：lib_aliyun_version 等符号被链接脚本导出，运维可通过版本区读取 SDK 版本；dm_log_report.c 支持设备日志上报云端，便于远程排障。

Extension Points（扩展点）

1. 新平台接入：仿照 qcloud_iot_explorer_sdk/port/ 编写新平台的 HAL 适配层（OS/网络/NVS/OTA 四件套），即可把任意 MQTT 云 SDK 移植到 AC79；
2. 物模型扩展：腾讯云侧新增消息类型时，扩展 DataTemplateType 枚举、topic_method[] 数组与 msg_handle[] 处理器表三处即可，框架天然支持；
3. OTA 通道替换：HAL_ota_ac79.c 与 cos_download.c / dm_ota.c 解耦，可替换为自定义下载源（如私有服务器）而不改动云协议栈；
4. 分区规划：新增云厂商（类似涂鸦）可在 isd_config_rule.c 中追加 XXX_ADR/XXX_LEN/XXX_OPT 规则，为厂商凭证预留独立 flash 区。

Tests

• 云平台 SDK 的源码树中未发现随附的单元测试工程（腾讯云/阿里云 SDK 为厂商官方源码，测试通常在厂商 CI 与真实云账号联调中完成）；
• 应用层调试主要依赖：腾讯云 IoT Explorer 控制台的"设备日志"、阿里云物联网平台的消息日志、以及 dm_log_report.c 的设备日志上报；建议在 apps/common/LLM/tc_iot_twetalk/ 的演示工程中先用官方体验账号跑通三元组鉴权与属性上报，再替换为量产密钥。

Related Links

• data_template_mqtt.c — 腾讯云物模型 MQTT 层
• iotx_cm_coap.c — 阿里云 COAP 通道
• isd_config_rule.c — 涂鸦分区配置
• 腾讯云 SDK HAL 移植层目录：apps/common/LLM/tc_iot_twetalk/qcloud_iot_explorer_sdk/port/
• 阿里云 SDK dev_model 目录：lib/net/aliyun/dev_model/
• 网络管理相关能力（Wi-Fi 连接、配网流程）见本目录相邻页面；LLM 应用层调用逻辑见 LLM 应用相关页面。