云平台与 IoT 协议

本文档介绍 AC792N SDK 中与云端平台对接及 IoT 协议相关的完整能力：以 OneSDK 为核心的设备接入框架（sdk/apps/common/LLM/onesdk），涵盖设备认证（一机一密/一型一密）、MQTT/MQTTS 协议栈（基于 libwebsockets）、物模型（thing model）、OTA 升级、NTP 校时、KV 存储、日志上报以及大模型 AI 网关（AIGW）接入。

Purpose and Scope

本页面向需要为 AC792N 设备接入云端 IoT 平台的开发者，系统说明：

• OneSDK 整体架构与各功能模块（iot_basic、iot_mqtt、thing_model、iot/ota、iot/kv、iot/ntp、iot/log、aigw）的职责与相互关系；
• 设备认证机制：三种认证方式（设备密钥、动态预注册、动态免预注册）的配置项与语义；
• MQTT 协议实现细节：事件模型、QoS 支持、订阅/发布待处理队列、断线自动重连、PING 保活、MQTTS 加密；
• 端到端控制流：从应用初始化、连接建立、订阅/发布到云端 Broker 的完整时序；
• 配置选项、API 参考、失败模式与并发行为。

以下主题不在本页范围内，属于相邻目录页内容：Wi-Fi 配网/网络栈本身（include_lib/net 下的 HTTP 客户端等）、音频/LLM 对话应用逻辑（onesdk_realtime 示例的对话流程）、以及 AC792N 外设驱动。本页聚焦于"云平台协议与设备接入"这一能力边界。

Overview

AC792N SDK 的云端能力由 OneSDK（位于 sdk/apps/common/LLM/onesdk）承载。OneSDK 是一个面向嵌入式设备的 IoT 接入 SDK，代码注释显示其由字节跳动（bytedance）团队于 2025 年创建，面向火山引擎 IoT 平台等云服务。它的设计目标是让设备以最小的资源开销完成：

1. 安全上云：通过 HTTP 动态注册（dynreg）或静态密钥完成设备身份认证，并支持 MQTT over TLS（MQTTS）；
2. 双向消息：基于 MQTT 协议订阅云端下发指令、上报设备属性和事件；
3. 物模型化：通过 thing_model 模块把设备能力（属性/事件/服务）抽象为标准物模型，便于云端统一管理；
4. 生命周期管理：OTA 固件升级、NTP 校时、日志上报、KV 持久化，支撑设备长期稳定运行；
5. AI 能力扩展：通过 aigw（AI Gateway）模块接入大模型，实现实时语音对话等智能化场景。

MQTT 协议栈直接基于成熟的 libwebsockets（lws）实现，而不是自研协议栈——这保证了协议正确性（CONNECT/CONNACK/SUBACK/PUBACK、QoS 流控等），同时通过 iot_mqtt_ctx_t 封装把 lws 的异步事件模型适配为 OneSDK 的同步回调接口（event_callback / message_callback）。

Architecture

flowchart TD
    subgraph sg_Device["设备端 (AC792N SDK)"]
        App["应用层<br/>(onesdk_realtime 示例)"]
        OneSDK["OneSDK (onesdk)"]
        subgraph sg_Modules["OneSDK 功能模块"]
            Basic["iot_basic<br/>(连接配置/认证)"]
            MQTT["iot_mqtt<br/>(MQTT over libwebsockets)"]
            ThingModel["thing_model<br/>(物模型)"]
            OTA["iot/ota<br/>(固件 OTA)"]
            Aux["iot/{kv,ntp,log,utils}<br/>(辅助能力)"]
            AIGW["aigw<br/>(大模型网关)"]
        end
        TLS["TLS 层<br/>(enable_mqtts/verify_ssl)"]
    end

    subgraph sg_Cloud["云端"]
        Broker["MQTT Broker<br/>(IoT 平台)"]
        GW["IoT 网关<br/>(http_host/instance_id)"]
        LLM["大模型服务<br/>(AIGW)"]
    end

    App --> OneSDK
    OneSDK --> Basic
    Basic --> MQTT
    Basic -->|"HTTP (动态注册 dynreg)"| GW
    MQTT --> TLS
    TLS -->|"MQTTS (TCP 8883)"| Broker
    OneSDK --> ThingModel
    OneSDK --> OTA
    OneSDK --> Aux
    OneSDK --> AIGW
    AIGW -->|"MQTT/WebSocket"| LLM
    GW -->|"签发设备凭证"| Basic

架构说明

• 应用层：onesdk_realtime 等示例演示如何调用 OneSDK 完成实时对话与云端交互，是设备厂商二次开发的起点。
• iot_basic：负责连接元信息与设备认证配置的持有和管理。它保存 http_host、instance_id、product_key/product_secret、device_name/device_secret 等参数，并通过 onesdk_iot_basic_set_option 提供运行时修改能力。它不直接收发协议数据，而是作为其他模块的"身份与配置中心"。
• iot_mqtt：MQTT 客户端核心。使用 libwebsockets 的 lws_mqtt_* API 完成连接、订阅、发布，通过 lws 回调机制驱动事件分发。所有对外行为通过 iot_mqtt_event_type_t 事件和 topic 回调暴露给上层。
• thing_model：物模型层，将设备属性/事件/服务映射为云端可识别的消息格式（iot_tm_api.h/iot_tm_header.h），配合 iot_ntp 保证时间戳一致性。
• iot/ota：基于 iot_ota_api 的固件升级通道，与 MQTT 或 HTTP 配合完成固件拉取与校验。
• aigw：大模型网关模块（auth.c/llm.c），负责与云端大模型服务的认证与会话管理，支撑 LLM 实时对话场景。
• 底层依赖 AWS C Common（src/aws/common：string/byte_buf/json/encoding/hash_table 等）与平台适配层（platform/plat：alloc/util/platform），为上层提供跨平台的基础数据结构。

这样的分层设计让"协议细节"（lws、TLS、QoS）与"业务语义"（物模型、OTA、对话）解耦：协议层的变化不影响业务层，新增云平台接入只需替换 iot_basic 的认证逻辑与 Broker 地址。

设备认证与连接配置（iot_basic）

三种认证方式

iot_basic.h 通过 onesdk_auth_type_t 枚举定义了三种设备认证方式，对应不同安全等级与部署流程：

设计意图：一机一密适合量产时离线烧录的场景；一型一密则降低产线管理成本，用产品密钥统一签发，但要求云端支持动态注册接口（HTTP http_host 上的 dynreg 流程，见 src/iot/iot_mqtt.c 中引用的 dynreg.h 与 util/hmac_sha256.h——设备密钥派生基于 HMAC-SHA256 签名）。

配置结构体

iot_basic_config_t 是 OneSDK 所有模块共享的"身份档案"：

typedef struct iot_basic_config {
    // connection config
    char *http_host;
    char *instance_id;

    // auth config
    onesdk_auth_type_t auth_type;
    char *product_key;
    char *product_secret;
    char *device_name;
    char *device_secret;

    // certificate config
    bool verify_ssl;              // 是否验证SSL证书
    char *ssl_ca_cert ;           // CA证书，base64编码
    char *ssl_ca_path;      // CA证书路径
} iot_basic_config_t;

来源：iot_basic.h

其中 verify_ssl/ssl_ca_cert/ssl_ca_path 三件套体现了嵌入式 IoT 的证书管理策略：既支持把 CA 证书以 base64 内嵌（ssl_ca_cert，适合无文件系统的 MCU），也支持从文件路径加载（ssl_ca_path，适合带文件系统的设备）。iot_config_dup() 提供深拷贝，避免上层临时栈上配置与模块内部生命周期冲突。

MQTT 协议实现（iot_mqtt）

客户端上下文与配置

iot_mqtt_ctx_t 封装了完整 MQTT 客户端状态：lws 连接（wsi）、lws 全局上下文（context）、连接参数（ccinfo）、订阅 topic 映射、待处理订阅/发布队列、两把互斥锁以及连接/等待标志位。配置结构 iot_mqtt_config_t 如下：

typedef struct {
    const char *mqtt_host;
    iot_basic_config_t *basic_config;
    struct aws_string *username;
    struct aws_string *password;
    uint16_t keep_alive;
    bool auto_reconnect;
    int32_t ping_interval;
    bool enable_mqtts;
} iot_mqtt_config_t;

来源：iot_mqtt.h

• mqtt_host：Broker 地址；username/password 由认证流程生成（动态注册后由云端签发）；
• keep_alive：MQTT CONNECT 报文中的保活时间（秒）；
• auto_reconnect：断线后自动重连开关；
• ping_interval：lws 定时器触发的 PING 周期，默认 IOT_DEFAULT_PING_INTERVAL_S（60 秒），见 iot_mqtt.h；
• enable_mqtts：是否启用 MQTTS（MQTT over TLS）。

事件模型

MQTT 客户端通过事件回调把异步协议状态通知上层：

typedef enum {
    MQTT_EVENT_CONNECTED,
    MQTT_EVENT_DISCONNECTED,
    MQTT_EVENT_PUBLISHED,
    MQTT_EVENT_SUBSCRIBED,
    MQTT_EVENT_UNSUBSCRIBED,
    MQTT_EVENT_MESSAGE_RECEIVED,
    MQTT_EVENT_ERROR,
} iot_mqtt_event_type_t;

来源：iot_mqtt.h

订阅采用 topic → 回调 的映射注册方式（iot_mqtt_topic_map_t）：每个 topic 可独立挂载 message_callback 与 event_callback，并指定 QoS，见 iot_mqtt.h。这样上层业务（物模型、OTA、日志）只需各自注册关心的 topic，互不干扰。

QoS 支持

仅支持 IOT_MQTT_QOS0 与 IOT_MQTT_QOS1，代码注释明确标注"QOS2 // 暂不支持"，见 iot_mqtt.h。这是嵌入式场景的典型取舍：QoS2 需要四段握手与消息去重状态机，资源开销大且收益有限，QoS1 的"至少一次"语义配合业务层幂等处理已满足绝大多数上报/下发场景。

回调驱动的事件循环实现

iot_mqtt.c 中的 callback_mqtt() 是 lws 回调入口，负责把 lws 协议事件翻译为 OneSDK 状态。关键分支：

case LWS_CALLBACK_MQTT_CLIENT_CLOSED:
    lwsl_err("%s: CLIENT_CLOSED\n", __func__);
    ctx->is_connected = false;
    if (ctx->config->auto_reconnect) {
        iot_mqtt_reconnect(ctx);
    }
    break;

case LWS_CALLBACK_MQTT_CLIENT_ESTABLISHED:
    lwsl_info("%s: MQTT_CLIENT_ESTABLISHED\n", __func__);
    ctx->is_connected = true;
    ctx->waiting_for_puback = 0;
    ctx->waiting_for_suback = 0;
    lws_callback_on_writable(wsi);
    lws_set_timer_usecs(wsi, ctx->config->ping_interval * 1000000);
    return 0;

来源：iot_mqtt.c

设计要点：

1. 连接建立即保活：ESTABLISHED 后立即 lws_set_timer_usecs 启动 PING 定时器，并在可写时处理待办队列；
2. 自动重连：CLIENT_CLOSED 时若 auto_reconnect 开启则调用 iot_mqtt_reconnect()，使设备在断网/平台踢线后能自愈；
3. 订阅分批：LWS_CALLBACK_MQTT_CLIENT_WRITEABLE 中每次最多处理 7 个待订阅 topic（num_to_subscribe = count > 7 ? 7 : count），并用 waiting_for_suback 标志防止上一批 SUBACK 未返回就发送下一批，见 iot_mqtt.c。这既规避了单报文过大，又保证了订阅顺序。

线程与锁

iot_mqtt_ctx_t 内 pthread_mutex_t sub_topic_mutex / pub_topic_mutex 分别保护待订阅列表与待发布列表，配合 volatile bool waiting_for_suback/puback 实现"事件循环线程"与"业务调用线程"之间的安全交接——业务线程调用 iot_mqtt_publish/subscribe 入队，lws 事件循环线程在 writable 回调中真正发包。

Core Flow（核心流程）

连接 → 订阅 → 发布 时序

sequenceDiagram
    participant App as 应用层
    participant MQTT as iot_mqtt
    participant LWS as libwebsockets
    participant Broker as MQTT Broker

    App->>MQTT: iot_mqtt_init(ctx, config)
    App->>MQTT: iot_mqtt_connect(ctx)
    MQTT->>LWS: lws_client_connect_via_info(ccinfo)
    LWS->>Broker: TCP/TLS 连接 + CONNECT(keep_alive)
    Broker-->>LWS: CONNACK
    LWS-->>MQTT: LWS_CALLBACK_MQTT_CLIENT_ESTABLISHED
    MQTT->>MQTT: is_connected = true，启动 PING 定时器
    MQTT-->>App: MQTT_EVENT_CONNECTED
    App->>MQTT: iot_mqtt_subscribe(ctx, topic_map)
    MQTT->>LWS: lws_mqtt_client_send_subcribe(每批 ≤ 7)
    LWS-->>MQTT: LWS_CALLBACK_MQTT_SUBSCRIBED
    MQTT-->>App: MQTT_EVENT_SUBSCRIBED
    App->>MQTT: iot_mqtt_publish(ctx, topic, payload, len, qos)
    MQTT->>LWS: lws_mqtt_client_send_publish(qos1 等待 PUBACK)
    Broker-->>LWS: PUBACK
    MQTT-->>App: MQTT_EVENT_PUBLISHED

时序说明：整个生命周期由 lws 事件循环驱动，iot_mqtt_ctx_t 内的 waiting_for_suback/puback 与互斥锁保证上层同步调用与底层异步事件不冲突。MQTT_EVENT_CONNECTED 是上层业务启动订阅/发布的前提——所有待处理订阅都排入 pending_sub_list，等 writable 事件逐批发送。

断线自愈流程

flowchart TD
    Start([连接建立]) --> Active["运行中"]
    Active -->|"网络异常/平台踢线"| Closed["LWS_CALLBACK_MQTT_CLIENT_CLOSED"]
    Closed --> Flag["is_connected = false"]
    Flag --> Check{"auto_reconnect?"}
    Check -->|"是"| Reconnect["iot_mqtt_reconnect(ctx)"]
    Check -->|"否"| Wait["等待上层 iot_mqtt_connect"]
    Reconnect --> Active
    Wait --> Active

物模型与辅助能力（thing_model / ota / kv / ntp / log）

物模型（thing model）

include/thing_model/iot_tm_api.h 与 iot_tm_header.h 提供物模型 API：把设备的属性（properties）、事件（events）、服务（services）按平台约定的 JSON 结构封装，经 MQTT 发布到物模型 topic。iot_ntp.h 提供 NTP 校时，保证上报数据的时间戳与云端一致——对于告警、计费等对时间敏感的业务这是硬前提。

OTA 升级

include/iot/iot_ota_api.h、iot_ota_header.h、iot_ota_utils.h 及实现 src/iot/ota/iot_ota_api.c 构成 OTA 模块：负责从云端拉取固件、分片校验、写入 flash。OTA 与 MQTT 解耦设计，可独立于业务消息运行，升级失败不会污染业务连接状态。

KV 与日志

• iot_kv（iot_kv.h/iot_kv.c）：轻量键值持久化，适合保存设备配置、云端下发的参数、断点续传状态；
• iot_log（iot_log.h，实现位于 src/iot/log/iot_log.c 与 iot_log_report.c）：设备日志采集与上报，便于云端远程排障；
• iot_popen / iot_utils：进程/命令执行封装与通用工具函数。

AIGW 大模型网关

src/aigw/auth.c 与 src/aigw/llm.c 提供大模型网关接入：完成与云端 AI 服务的认证（复用 iot_basic 的密钥体系）与实时会话管理，支撑 examples/onesdk_realtime 中的语音对话示例。它体现了 OneSDK 从"传统 IoT"向"AIoT"演进的扩展方向：设备既上报传感数据，也能直接与云端大模型交互。

Usage Examples（使用示例）

示例 1：配置设备基础信息（认证与连接）

iot_basic_config_t config = {
    .http_host = "https://iot.example.com",
    .instance_id = "your-instance",
    .auth_type = ONESDK_AUTH_DEVICE_SECRET, // 一机一密
    .product_key = "pk-xxxx",
    .device_name = "dev-001",
    .device_secret = "ds-xxxx",
    .verify_ssl = true,
    .ssl_ca_path = "/data/certs/ca.pem",
};
iot_basic_ctx_t *ctx = ...;
onesdk_iot_basic_init(ctx, &config);

来源：iot_basic.h（字段定义）；认证枚举见 iot_basic.h

示例 2：初始化并连接 MQTT 客户端

iot_mqtt_config_t mqtt_config = {
    .mqtt_host = "broker.example.com",
    .basic_config = &basic_config,        // 复用设备身份
    .keep_alive = 120,                    // CONNECT 保活秒数
    .auto_reconnect = true,               // 断线自动重连
    .ping_interval = IOT_DEFAULT_PING_INTERVAL_S, // 默认 60s
    .enable_mqtts = true,                 // MQTT over TLS
};

iot_mqtt_ctx_t mqtt_ctx;
iot_mqtt_init(&mqtt_ctx, &mqtt_config);   // 初始化上下文
iot_mqtt_connect(&mqtt_ctx);              // 发起连接（异步）
iot_mqtt_run_event_loop(&mqtt_ctx, 100);  // 驱动事件循环

来源：iot_mqtt.h（配置结构）；API 原型见 iot_mqtt.h

示例 3：注册订阅回调并发布消息

// 注册 topic → 回调映射
iot_mqtt_topic_map_t topic_map = {
    .topic = "product/dev001/property/set",
    .message_callback = on_property_set,  // 收到下行指令
    .event_callback = on_mqtt_event,      // 连接状态事件
    .user_data = app_ctx,
    .qos = IOT_MQTT_QOS1,
};
iot_mqtt_subscribe(&mqtt_ctx, &topic_map);

// 上报属性
const char *payload = "{\"temperature\":25.6}";
iot_mqtt_publish(&mqtt_ctx, "product/dev001/property/post",
                 (const uint8_t *)payload, strlen(payload), IOT_MQTT_QOS1);

来源：iot_mqtt.h（回调与 topic map 定义）、iot_mqtt.h（publish/subscribe 签名）

Configuration Options（配置选项）

iot_mqtt_config_t

iot_basic_config_t

运行时配置接口

onesdk_iot_basic_set_option(ctx, option, value) 支持在运行期动态调整以下配置项（iot_basic_option_t 枚举，见 iot_basic.h）：

API Reference（API 参考）

iot_basic 模块（iot_basic.h）

int onesdk_iot_basic_init(iot_basic_ctx_t *ctx, const iot_basic_config_t *config)

• 描述：以给定配置初始化 iot_basic 上下文，校验并持有设备身份信息。
• 参数：ctx 输出上下文；config 输入配置。
• 返回：0 成功，其他失败。

int onesdk_iot_basic_set_option(iot_basic_ctx_t *ctx, iot_basic_option_t option, void *value)

• 描述：运行时修改某项连接/认证配置。
• 返回：0 成功，其他失败。

int onesdk_iot_basic_deinit(iot_basic_ctx_t *ctx)

• 描述：释放上下文资源，反初始化。
• 返回：0 成功。

iot_basic_config_t *iot_config_dup(const iot_basic_config_t *src)

• 描述：深拷贝配置结构，返回堆上副本（调用方负责释放），避免生命周期冲突。

const char *iot_auth_type_c_str(const onesdk_auth_type_t auth_type)

• 描述：将认证类型枚举转为可读字符串，用于日志打印与调试。

iot_mqtt 模块（iot_mqtt.h）

int iot_mqtt_init(iot_mqtt_ctx_t *ctx, iot_mqtt_config_t *config)

• 描述：初始化 MQTT 客户端上下文（含锁、队列、lws 上下文）。
• 返回：0 成功；失败可能为内存分配错误（如 VOLC_ERR_MALLOC）。

void iot_mqtt_deinit(iot_mqtt_ctx_t *ctx)

• 描述：销毁上下文，释放订阅/发布队列与 lws 资源。

int iot_mqtt_connect(iot_mqtt_ctx_t *ctx)

• 描述：异步发起连接（基于 ccinfo 调用 lws 连接）。连接结果通过 MQTT_EVENT_CONNECTED / MQTT_EVENT_ERROR 事件通知。
• 返回：0 表示已发起；非 0 表示参数错误或资源不足。

int iot_mqtt_disconnect(iot_mqtt_ctx_t *ctx)

• 描述：主动断开与 Broker 的连接。

int iot_mqtt_reconnect(iot_mqtt_ctx_t *ctx)

• 描述：重新连接。供 auto_reconnect 内部调用，也可由上层在收到 MQTT_EVENT_DISCONNECTED 后手动触发。

int iot_mqtt_publish(iot_mqtt_ctx_t *ctx, const char *topic, const uint8_t *payload, size_t len, int qos)

• 描述：发布消息到指定 topic。QoS1 时等待 PUBACK 后上报 MQTT_EVENT_PUBLISHED；QoS0 直接上报。
• 参数：qos 取 IOT_MQTT_QOS0 或 IOT_MQTT_QOS1（QoS2 不支持）。
• 返回：0 入队/发送成功；非 0 失败。

int iot_mqtt_subscribe(iot_mqtt_ctx_t *ctx, iot_mqtt_topic_map_t *topic_map)

• 描述：注册单个 topic 的订阅（含消息/事件回调）。实际订阅报文由事件循环在 writable 时按批（≤7 个）发送。
• 返回：0 成功；非 0 失败。

int iot_mqtt_run_event_loop(iot_mqtt_ctx_t *ctx, int timeout_ms)

• 描述：驱动 lws 事件循环，处理网络事件、定时器与待处理队列，是协议栈的心跳入口；需由上层线程周期性调用或阻塞运行。
• 返回：0 正常；非 0 异常。

Failure Modes, Edge Cases & Concurrency（失败模式、边界与并发）

连接失败与断线重连

• 连接建立失败：lws 回调 LWS_CALLBACK_CLIENT_CONNECTION_ERROR 触发时，is_connected 被置 false，错误信息（in 参数）打印日志。上层应通过 MQTT_EVENT_ERROR/MQTT_EVENT_DISCONNECTED 感知并决定重试策略。
• 断线自愈：LWS_CALLBACK_MQTT_CLIENT_CLOSED 分支中，若 auto_reconnect == true 立即调用 iot_mqtt_reconnect()（见 iot_mqtt.c）。设计上重连由协议栈自动完成，业务层无需干预；若关闭该开关，则依赖上层在收到 DISCONNECTED 事件后手动 iot_mqtt_connect()。
• 注意：当前实现未看到指数退避（exponential backoff）逻辑，若平台侧对重连频率敏感，建议上层在 auto_reconnect = false 时自行实现退避策略。

订阅/发布的边界行为

• 订阅分批上限：每次 writable 事件最多发送 7 个 topic 的 SUBSCRIBE（见 iot_mqtt.c），超过部分留在 pending_sub_list 等待下一批。waiting_for_suback 标志保证同一时刻只有一批在途，避免 SUBACK 乱序。
• QoS2 不支持：调用 iot_mqtt_publish 传入 QoS2 属于未定义行为，业务层必须只使用 QoS0/QoS1。
• 内存失败：订阅批量分配失败时返回 VOLC_ERR_MALLOC 并释放已分配内存（见 iot_mqtt.c），上层需做资源检查。

并发模型

• 双线程交接：业务线程调用 iot_mqtt_publish/subscribe 向待处理队列入队；lws 事件循环线程在 writable 回调中出队发送。sub_topic_mutex/pub_topic_mutex 保护队列，volatile waiting_for_suback/puback 作为跨线程状态标志（见 iot_mqtt.h）。
• 回调线程上下文：message_callback/event_callback 在事件循环线程内执行，回调中不应做耗时操作或调用可能阻塞事件循环的 API，否则会拖慢 PING 保活与订阅处理。

Performance & Operational Notes（性能与运维）

• 保活开销：默认 ping_interval = 60s，与 MQTT keep_alive 配合维持长连接；在弱网环境可适当调小 ping_interval 以更快发现死链，但会略微增加空包流量。
• 内存 footprint：MQTT 客户端依赖 AWS C Common（string/json/byte_buf 等）与 libwebsockets，建议在链接时裁剪未用模块（如无需 JSON 的模块可去掉 aws/common/json.c），并核对堆栈大小满足 lws 上下文需求。
• 日志分级：lwsl_err/info/notice 分级输出（见 iot_mqtt.c），量产固件应关闭 info 级日志以降低串口/存储开销；云端排障可借助 iot_log_report 远程收集设备日志。
• OTA 窗口：升级期间建议暂停业务上报（或至少降低频率），避免大流量固件拉取与业务消息竞争带宽导致超时。

Extension Points（扩展点）

1. 新增云平台：替换/扩展 iot_basic 的认证流程（如新增 onesdk_auth_type_t 枚举值）与 iot_mqtt_config_t 的 mqtt_host/username/password 生成逻辑，即可对接其他兼容 MQTT 的平台；Broker 协议差异由 libwebsockets 屏蔽。
2. 物模型扩展：在 thing_model 层按 iot_tm_api.h 的封装模式新增属性/事件模板，无需改动 iot_mqtt 传输层。
3. 业务主题扩展：通过 iot_mqtt_topic_map_t 自由注册任意自定义 topic 及其回调，OTA、日志、AI 会话各自独立挂载，互不影响。
4. 底层替换：platform/plat（alloc/platform/util）是平台适配层，移植到其他芯片时主要修改该层与 TLS 后端，OneSDK 上层业务代码可保持稳定。
5. AI 能力：aigw/auth.c 与 aigw/llm.c 是独立的 AI 网关接入路径，可单独启用，不依赖物模型链路。

Related Links（相关链接）

• iot_basic.h（认证与连接配置）
• iot_mqtt.h（MQTT 客户端接口）
• iot_mqtt.c（MQTT 协议实现）
• iot_basic.c（认证逻辑实现）
• thing_model/iot_tm_api.h（物模型接口）
• thing_model/iot_ntp.h（NTP 校时）
• iot/iot_ota_api.h（OTA 接口）
• iot/iot_kv.h（KV 持久化）
• iot_log.h（日志上报）
• aigw/auth.c 与 aigw/llm.c（大模型网关）
• onesdk_realtime 示例（应用层接入范例）

相关能力指引：Wi-Fi 配网与底层网络栈、HTTP 客户端（include_lib/net/uC-HTTPc）属网络基础设施主题；LLM 实时对话的完整应用流程见 OneSDK 实时对话示例页；AC792N 外设与音频链路见各自外设目录页。