MQTT协议

本指南将帮助您了解如何将支持 MQTT 协议的智能设备接入到 SiliZap 物联网平台。

一. 接入步骤提示

若设备的 MQTT 消息格式是固定的，可以通过规则引擎进行转发，适配到平台，例如使用 EMQX 中间件：支持内容转发，主题可以通过 emqx 自带的规则引擎转发

设备接入主要包括以下几个步骤：

设备认证
- 简单认证
- 加密认证
设备交互
- 发布主题：属性(property)、设备信息(info)、设备升级(ota) 、事件(event)
- 订阅主题：功能(function)、设备升级(ota)、监测数据(monitor)

二. 设备认证

设备认证是确保设备安全接入平台的重要步骤。SiliZap 物联网平台支持两种认证方式：

2.1 简单认证

简单认证 是指设备通过产品详情页获取的MQTT账号和密码直接进行认证，适合测试环境使用。

2.1.1 认证参数格式

连接MQTT消息服务器需要提供唯一的客户端ID、用户名和密码（如何获取请见入门参考），具体格式如下：

javascript

// 客户端ID等于 认证类型 + 设备编号 + 产品编号 + 用户ID
Client ID = "S" + "&" + IMEI/MAC + "&" + product_id + "&" + user_id

// 用户名
Username = MQTT账号

// 密码
Password = MQTT密码

2.1.2 认证参数示例

账号配置信息示例：

javascript

Client ID  = "S&866380070100001&110&1981912444385239040"
Username = "SiliZap"
Password = "P263P08771126N53"

2.2 Token认证

Token认证 是一种安全的认证方式，设备端使用产品秘钥或设备秘钥通过HMAC算法生成签名，与其他参数组合成Token进行认证。平台通过相同的秘钥和算法验证签名的有效性。

2.2.1 认证参数格式

连接MQTT消息服务器需要提供唯一的客户端ID、用户名和Token，具体格式如下：

javascript

// 客户端ID等于 认证类型 + 设备编号 + 产品编号 + 用户ID
Client ID = "E" + "&" + IMEI/MAC + "&" + product_id + "&" + user_id

2.2.2 认证参数计算

采用MQTT协议时，设备需要通过Token进行认证。以下是平台的Token计算方式：

1. Token的组成

设备秘钥鉴权需包含产品ID+设备编号+鉴权Token，其中Token由多个参数构成：

名称	类型	是否必须	参数说明	参数示例
version	string	是	参数组版本号，日期格式，目前仅支持"2025-05-01"	2025-05-01
res	string	是	访问资源路径，产品级或设备级格式	products/3zbwuY8QUI products/3zbwuY8QUI/devices/862419074519231
et	int	是	访问过期时间，unix时间戳	1714582963（北京时间：2025-05-01 16:15:63）
method	string	是	签名方法，支持md5、sha1、sha256	sha256
sign	string	是	签名结果字符串	wU32oxVWluQLikUqs8OfRL5HPO6XursbxsxiKgy3rOo%3D

2. res使用场景说明

场景	res参数格式	示例	说明
产品级鉴权（一型一密）	products/{产品ID}	products/3zbwuY8QUI	使用产品级密钥，同一产品下设备烧录相同产品证书
设备级别鉴权（一机一密）	products/{产品ID}/devices/{设备编号}	products/3zbwuY8QUI/devices/862419074519231	使用设备级密钥，每台设备烧录自己的设备证书

3. sign签名算法

参数sign的生成算法为：

sign = base64(hmac_sha256(base64decode(key), utf-8(StringForSignature)))

其中：

Key：为平台为资源分配的访问密钥(产品级、设备级均可)，参与计算前应先进行base64decode操作
StringForSignature：用于计算签名的字符串，按参数名称顺序排序，以'\n'分隔，顺序为：et、method、res、version

StringForSignature组成示例：

StringForSignature = et + '\n' + method + '\n' + res + '\n' + version

签名计算示例：

若token参数如下：
- et = 1537255523
- method = sha1
- res = products/3zbwuY8QUI
- version = 2025-05-01

则StringForSignature为：

"1537255523" + "\n" + "sha1" + "\n" + "products/3zbwuY8QUI" + "\n" + "2025-05-01"

计算出sign后，将每个参数以key=value形式表示，并用'&'分隔：

version=2025-05-01&res=products/3zbwuY8QUI/devices/862419074519231&et=1537255523&method=sha1&sign=wU32oxVWluQLikUqs8OfRL5HPO6XursbxsxiKgy3rOo%3D

4. 参数编码

Token中key=value的形式的value部分需要经过URL编码，需要编码的特殊符号如下：

序号	符号	编码
1	+	%2B
2	空格	%20
3	/	%2F
4	？	%3F
5	%	%25
6	#	%23
7	&	%26
8	=	%3D

编码后，实际传输的token示例：

version=2025-05-01&res=products%2F3zbwuY8QUI%2Fdevices%2F862419074519231&et=1537255523&method=sha1&sign=wU32oxVWluQLikUqs8OfRL5HPO6XursbxsxiKgy3rOo%3D

注意：实际使用时，请根据SiliZap平台提供的具体产品ID、设备编号和访问密钥进行相应计算。

2.3 Token计算器

产品级和设备级的token都可以在web进行token的计算，在设备列表-->设备详情-->token计算器，支持产品级和设备级鉴权的token计算，示例如下：

单台设备的认证信息，获取方式为设备列表-->设备详情-->认证信息，示例如下：

2.4 认证类型说明

认证类型标识：
- S：表示简单认证（Simple Authentication）
- E：表示加密认证（Encrypted Authentication）
用户ID说明：
- 即登录用户的ID号
- 使用不同用户ID，设备将归属于不同用户
- 推荐做法：可使用部门管理员账号的ID，后续通过扫码方式将设备关联分配给不同用户
设备编号获取方式：
- 方式一：从平台界面操作在设备列表中手动新增设备，系统会自动生成设备编号
- 方式二：自动注册（推荐大量设备使用）当系统未预先创建设备时，硬件端生成一个唯一编号作为设备编号，认证成功后系统会自动注册该设备实体

三. 设备交互

设备接入平台后，需要通过 MQTT 协议与平台进行交互。以下是设备需要订阅和发布的主题及消息格式说明：

4.1 主题命名规则

平台使用标准的 MQTT 主题格式，所有主题均以 $sys/{product_id}/{serial_number}/silizap/ 为前缀，其中：

{product_id}：产品 ID
{serial_number}：设备编号

4.2 订阅主题

设备需要订阅以下主题以接收平台下发的指令和响应：

主题	描述
$sys/{product_id}/{serial_number}/silizap/info/post_reply	平台回复设备信息上报结果
$sys/{product_id}/{serial_number}/silizap/function/get	平台下发的控制指令
$sys/{product_id}/{serial_number}/silizap/monitor/get	监测指令（包含监测数据、一键控制、设备配置信息）
$sys/{product_id}/{serial_number}/silizap/ota/get	设备升级指令
$sys/{product_id}/{serial_number}/silizap/monitor/post_reply	平台回复订阅实时监测信号的结果
$sys/{product_id}/{serial_number}/silizap/event/post_reply	平台回复设备事件处理结果
$sys/{product_id}/{serial_number}/silizap/property/post_reply	平台回复设备属性数据接收结果

4.3 发布主题

设备需要通过以下主题向平台上报数据和响应：

主题	描述
$sys/{product_id}/{serial_number}/silizap/info/post	发布设备基本信息（设备启动时发布）
$sys/{product_id}/{serial_number}/silizap/function/get_reply	发布设备执行控制指令的结果
$sys/{product_id}/{serial_number}/silizap/monitor/post	发布设备实时监测数据
$sys/{product_id}/{serial_number}/silizap/monitor/get_reply	回复监测指令执行结果
$sys/{product_id}/{serial_number}/silizap/ota/get_reply	回复设备升级指令执行结果
$sys/{product_id}/{serial_number}/silizap/ota/post	发布设备升级进度和状态
$sys/{product_id}/{serial_number}/silizap/event/post	发布设备异常或特殊事件
$sys/{product_id}/{serial_number}/silizap/property/post	发布设备属性数据

4.4 消息格式示例

4.4.1 设备信息上报

功能说明：设备启动时必须上报的基本信息，包含设备型号、版本、状态等

消息格式：

json

{
    "did": "f8ffe7ca310057e7dab2ce83fe621c31",
    "payload": {
        "time": "2025-10-26 06:56:42",
        "info": {
            "longitude": "",
            "version_name": "0.0.0.4",
            "rssi": -78,
            "latitude": "",
            "fversion": "V1003",
            "status": 3,
            "summary": {
                "electricity": 100,
                "interval": 30000,
                "author": "silizap",
                "deeprest_interval": 0,
                "device_model": 1,
                "product": "JL-U02",
                "create": "2025-05-18",
                "name": "device"
            },
            "userId": "1",
            "uuid": "8a626f2f6efd409cb34c5c8308f13e34",
            "chip": "EC718P"
        },
        "timestamp": 1761433000000
    }
}

4.4.2 设备属性上报

功能说明：设备定期或状态变化时向平台上报运行状态和关键属性数据

消息格式：

json

{
    "did": "758546534407f222c6dc47412a7cfd81",
    "params": {
        "time": "2025-10-26 06:58:12",
        "functions": [
            {
                "id": "alarm",
                "value": "close",
                "remark": "寻机"
            }
        ],
        "properties": [
            {
                "id": "longitude",
                "value": "116.5675278",
                "remark": "经度"
            },
            {
                "id": "latitude",
                "value": "39.8080025",
                "remark": "纬度"
            }
        ],
        "timestamp": 1761433100000
    },
    "version": "1.0"
}

4.4.3 接收控制指令

功能说明：设备接收平台下发的功能控制指令

消息格式：

json

{
    "did": "yDkkSdFhdsgLgOkaClFqmsKzZUxT31nd",
    "params": [
        {
            "extdata": {

            },
            "sensorcmd": "open",
            "sensorname": "alarm"
        }
    ],
    "version": "1.0"
}

4.4.4 执行结果上报

功能说明：设备执行完平台指令后，需要上报执行结果确认

消息格式：

json

{
    "code": 200,
    "did": "yDkkSdFhdsgLgOkaClFqmsKzZUxT31nd",
    "msg": "",
    "payload": {
        "functions": [
            {
                "extdata": {

                },
                "sensorcmd": "open",
                "sensorname": "alarm"
            }
        ],
        "time": "2025-10-25 23:53:40",
        "timestamp": 1761407700000
    }
}

4.5 通信流程说明

设备与平台的典型通信流程如下：

设备连接：使用正确的认证信息连接到MQTT服务器
信息上报：连接成功后立即通过 info/post 主题上报设备基本信息
订阅必要主题：根据设备功能需求，订阅相应的平台指令主题
数据交互：
- 定期上报监测数据和属性信息
- 接收并执行平台控制指令，上报执行结果
- 发生异常时通过事件主题上报
保持连接：定期发送心跳包，确保连接稳定
处理升级：接收并执行OTA升级指令，上报升级进度

四. MQTT 协议介绍

4.1 MQTT的来源与发展

MQTT（Message Queuing Telemetry Transport）是一种轻量级发布/订阅消息传输协议，由IBM的Andy Stanford-Clark和Arcom的Arlen Nipper于1999年共同发明，最初用于解决石油管道远程监控系统在低带宽、不稳定网络环境下的通信问题。

值得注意的是，MQTT名称中的"MQ"（Message Queuing）并不表示它使用消息队列存储消息，这是为符合IBM产品命名规范而保留的。后来也被解释为"MQ Telemetry Transport"，更准确反映其遥测传输特性。

2013年，IBM将MQTT贡献给OASIS标准组织，使其成为开放标准。目前最新版本为MQTT 5.0（2019年发布），在3.1.1版本基础上增加了多项新功能和改进。

4.2 MQTT的主要用途

MQTT协议因轻量级、低带宽占用、可靠传输等特点，广泛应用于以下场景：

物联网设备通信：智能家居、工业传感器、智能电表等资源受限设备
移动应用：需保持长连接且节省电量的电池供电设备
远程监控系统：环境监控、设备状态监控、远程数据采集
消息推送服务：手机通知、状态更新等实时推送
微服务架构：分布式系统中服务间松耦合通信

4.3 MQTT为什么受欢迎？

物联网初学者选择MQTT主要原因：

简单易学：协议规范简洁明了，易于理解和实现
轻量级：消息头部最小仅2字节，适合带宽有限场景
低资源消耗：客户端实现精简，适合内存和处理器能力有限的设备
灵活的消息传递：发布/订阅模式实现消息发送者和接收者解耦
可靠传输：支持QoS（服务质量）级别确保消息可靠到达
广泛支持：几乎所有主流编程语言都有MQTT客户端库，各物联网平台均支持

MQTT协议 ​

一. 接入步骤提示 ​

二. 设备认证 ​

2.1 简单认证 ​

2.1.1 认证参数格式 ​

2.1.2 认证参数示例 ​

2.2 Token认证 ​

2.2.1 认证参数格式 ​

2.2.2 认证参数计算 ​

1. Token的组成 ​

2. res使用场景说明 ​

3. sign签名算法 ​

4. 参数编码 ​

2.3 Token计算器 ​

2.4 认证类型说明 ​

三. 设备交互 ​

4.1 主题命名规则 ​

4.2 订阅主题 ​

4.3 发布主题 ​

4.4 消息格式示例 ​

4.4.1 设备信息上报 ​

4.4.2 设备属性上报 ​

4.4.3 接收控制指令 ​

4.4.4 执行结果上报 ​

4.5 通信流程说明 ​

四. MQTT 协议介绍 ​

4.1 MQTT的来源与发展 ​

4.2 MQTT的主要用途 ​

4.3 MQTT为什么受欢迎？ ​

MQTT协议

一. 接入步骤提示

二. 设备认证

2.1 简单认证

2.1.1 认证参数格式

2.1.2 认证参数示例

2.2 Token认证

2.2.1 认证参数格式

2.2.2 认证参数计算

1. Token的组成

2. res使用场景说明

3. sign签名算法

4. 参数编码

2.3 Token计算器

2.4 认证类型说明

三. 设备交互

4.1 主题命名规则

4.2 订阅主题

4.3 发布主题

4.4 消息格式示例

4.4.1 设备信息上报

4.4.2 设备属性上报

4.4.3 接收控制指令

4.4.4 执行结果上报

4.5 通信流程说明

四. MQTT 协议介绍

4.1 MQTT的来源与发展

4.2 MQTT的主要用途

4.3 MQTT为什么受欢迎？