7.5.1 CMS Connect 组件

📚 本节导读

学习时长：约 25 分钟
难度级别：⭐⭐⭐☆☆
前置知识：MQTT 协议基础、设备认证概念、第 7.2 节网络协议栈

🎯 学习目标

• 理解 CMS（China Mobile Service）平台的整体架构和定位
• 掌握 CMS Connect 组件的核心功能
• 掌握设备连接管理、属性上报、事件上报、命令下发
• 了解 OTA 升级机制
• 能够使用 CMS Connect 组件实现设备上云

---

一、CMS 平台概述

CMS（China Mobile Service） 是中国移动物联网云平台，为物联网设备提供设备接入、数据存储、规则引擎、应用使能等一站式服务。OneOS 深度集成了 CMS 平台 SDK，通过 CMS Connect 和 CMS ID 两大组件简化设备接入流程。

CMS 平台核心能力：

┌─────────────────────────────────────────────────────┐
│                   CMS 云平台                          │
│  ┌───────────┐ ┌───────────┐ ┌───────────────────┐ │
│  │ 设备管理   │ │ 数据存储   │ │ 规则引擎           │ │
│  ├───────────┤ ├───────────┤ ├───────────────────┤ │
│  │ 设备注册   │ │ 时序数据库 │ │ 数据流转           │ │
│  │ 设备影子   │ │ 文件存储   │ │ 消息路由           │ │
│  │ OTA 升级   │ │ 数据可视化 │ │ 场景联动           │ │
│  └───────────┘ └───────────┘ └───────────────────┘ │
└─────────────────────────────────────────────────────┘
                          ▲
                          │ MQTT / CoAP / HTTP
                          │
┌─────────────────────────────────────────────────────┐
│              OneOS 设备端                             │
│  ┌───────────────────┐ ┌───────────────────┐        │
│  │  CMS Connect 组件  │ │  CMS ID 组件       │        │
│  │  (连接管理)        │ │  (身份认证)        │        │
│  └───────────────────┘ └───────────────────┘        │
└─────────────────────────────────────────────────────┘

---

二、CMS Connect 组件

2.1 概述

CMS Connect 是设备与 CMS 云平台之间的连接管理组件，负责设备登录、数据上报、命令下发、OTA 升级等核心功能。它基于 MQTT 协议实现，封装了 CMS 平台的私有协议规范。

2.2 核心功能

功能	描述
设备登录	使用设备密钥（ProductKey/DeviceName/DeviceSecret）进行身份认证
数据上报	支持属性上报（Property）、事件上报（Event），支持 QoS 0/1
命令下发	接收来自云平台的命令，调用用户注册的回调函数处理
设备影子	同步云端设备影子状态，支持期望值和上报值
OTA 升级	接收云端推送的固件升级通知，下载并校验固件
NTP 时间同步	从云端获取精确时间
日志上报	将设备端日志上传到云端

2.3 核心数据结构

/* CMS 设备信息 */
typedef struct {
    char product_key[PRODUCT_KEY_MAX + 1];     /* 产品标识 */
    char device_name[DEVICE_NAME_MAX + 1];      /* 设备名称 */
    char device_secret[DEVICE_SECRET_MAX + 1];  /* 设备密钥 */
} cms_device_info_t;

/* CMS 连接配置 */
typedef struct {
    char *mqtt_broker_url;       /* MQTT Broker 地址 */
    int  mqtt_port;              /* MQTT 端口 (默认 1883) */
    int  keepalive_interval;     /* 心跳间隔 (秒) */
    int  auto_reconnect;         /* 是否自动重连 */
    int  reconnect_interval;     /* 重连间隔 (秒) */
} cms_connect_config_t;

/* 属性上报 */
typedef struct {
    char *identifier;            /* 属性标识符 */
    char *value;                 /* 属性值 (JSON 字符串) */
    int  qos;                    /* QoS 级别 */
} cms_property_report_t;

/* 事件上报 */
typedef struct {
    char *identifier;            /* 事件标识符 */
    char *params;                /* 事件参数 (JSON 字符串) */
    int  qos;                    /* QoS 级别 */
} cms_event_report_t;

2.4 核心 API

/* CMS Connect 初始化 */
int cms_connect_init(cms_device_info_t *device_info, cms_connect_config_t *config);

/* 连接 CMS 平台 */
int cms_connect_start(void);

/* 断开连接 */
int cms_connect_stop(void);

/* 属性上报 */
int cms_property_report(const char *identifier, const char *value);

/* 批量属性上报 */
int cms_property_batch_report(cms_property_report_t *reports, int count);

/* 事件上报 */
int cms_event_report(const char *identifier, const char *params);

/* 注册命令回调 */
int cms_register_command_callback(const char *cmd_name,
                                   int (*callback)(const char *params, char *response));

/* 获取连接状态 */
int cms_get_connect_state(void);

/* OTA 升级 */
int cms_ota_enable(void);
int cms_ota_disable(void);

/* 主循环（需周期性调用） */
int cms_connect_yield(int timeout_ms);

2.5 使用示例

#include <cms_connect.h>

/* 命令回调函数 */
static int cmd_led_control(const char *params, char *response)
{
    /* 解析 JSON 参数：{"led_id":0, "state":1} */
    /* 控制 LED 操作 */
    sprintf(response, "{\"code\":0,\"msg\":\"success\"}");
    return 0;
}

void cms_connect_example(void)
{
    /* 设备信息 */
    cms_device_info_t dev_info = {
        .product_key   = "a1b2c3d4e5",
        .device_name   = "device_001",
        .device_secret = "your_device_secret_here",
    };

    /* 连接配置 */
    cms_connect_config_t config = {
        .mqtt_broker_url    = "a1b2c3d4e5.iot-as-mqtt.cn-shanghai.aliyuncs.com",
        .mqtt_port          = 1883,
        .keepalive_interval = 60,
        .auto_reconnect     = 1,
        .reconnect_interval = 5,
    };

    /* 初始化并连接 */
    cms_connect_init(&dev_info, &config);
    cms_connect_start();

    /* 注册命令回调 */
    cms_register_command_callback("led_control", cmd_led_control);

    /* 上报属性 */
    cms_property_report("temperature", "{\"value\":25.5}");
    cms_property_report("humidity", "{\"value\":65}");

    /* 主循环 */
    while (1) {
        cms_connect_yield(1000);

        /* 定期上报数据 */
        char temp_buf[64];
        snprintf(temp_buf, sizeof(temp_buf), "{\"value\":%.1f}", get_temperature());
        cms_property_report("temperature", temp_buf);

        os_task_tsleep(5000);
    }
}

---

📝 本节小结

本节介绍了 OneOS CMS Connect 组件。CMS Connect 基于 MQTT 协议，负责设备与 CMS 云平台之间的连接管理，提供设备登录、属性上报、事件上报、命令下发、OTA 升级等核心功能。

核心要点回顾：

1. CMS Connect 基于 MQTT 协议实现设备与云平台的双向通信
2. 通过 cms_connect_init + cms_connect_start 完成初始化与连接
3. cms_property_report 上报属性，cms_event_report 上报事件
4. cms_register_command_callback 注册命令回调，处理云端下发的控制指令
5. cms_connect_yield 必须周期性调用以维持 MQTT 心跳和消息处理

🔗 相关链接

• 7.5.2 CMS ID 组件
• 7.5 CMS 平台组件（总览）
• 7.2.3 MQTT 协议
• 第7章 README