MQTT协议（SZ-JSON）

本文档定义 SiliZap 平台当前已落地使用的 SZ-JSON MQTT 接入规范，适用于平台原生 JSON 接入场景。

如果设备现有报文格式固定，也可以通过 EMQX 等中间件的规则引擎做主题和消息转换，再转发到本协议。

一、适用范围与接入概览

SZ-JSON 是面向现网设备的 MQTT JSON 协议，特点是：

基于标准 MQTT 主题通信，设备侧实现门槛低
消息结构直观，便于 MCU、Linux、网关类设备快速接入
与平台物模型直接对应，适合属性、功能、事件、OTA 等业务
已有大量设备使用，新增接入建议保持同一产品内报文风格一致

典型接入流程如下：

组装 MQTT 连接参数并完成认证
订阅设备所需的下行主题
设备上线后上报 info/post
设备定期或按变化上报 property/post、monitor/post
接收平台下发的 function/get、monitor/get、ota/get
执行后通过对应 *_reply 或 ota/post 反馈结果

其中：

property 用于属性数据上报，如经纬度、电量、温度、状态值
function 用于平台控制设备功能，如开关、寻机、模式切换
event 用于异常、告警、特殊事件上报
ota 用于固件升级请求、升级进度和升级结果反馈

二、MQTT 连接与认证

2.1 连接建议

MQTT 服务地址、端口、账号信息请以产品详情页显示内容为准，连接时建议遵循以下约定：

协议版本：建议按 MQTT 3.1.1 接入
Client ID：同一时刻必须全局唯一
业务主题：建议使用 QoS 1
Retain：建议统一为 false
保活时间：建议 60 到 120 秒
时间字段：设备侧若会上报 time、timestamp，建议先完成 RTC 或 NTP 校时

2.2 简单认证

简单认证适合测试环境、联调环境或对安全要求不高的内网场景。

2.2.1 认证参数格式

连接 MQTT 消息服务器需要提供唯一的客户端 ID、用户名和密码。如何获取请见入门参考。

javascript

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

// 用户名
Username = MQTT账号

// 密码
Password = MQTT密码

2.2.2 认证参数示例

javascript

Client ID = "S&866965083599537&gPVvQcxKBQ&1922956817214873666"
Username = "gPVvQcxKBQ"
Password = "PVhnYjRxcUI3d3BOODk3S1BzZENXZkRPZzRBTDMzY24="

2.3 加密认证（Token 认证）

加密认证适合正式生产环境。设备端使用产品密钥或设备密钥，通过 HMAC 算法生成签名，再拼装成 Token 作为 MQTT 密码使用。

2.3.1 认证参数格式

javascript

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

// 用户名
Username = MQTT账号

// 密码
Password = Token

2.3.2 Token 组成

名称	类型	必填	说明	示例
`version`	string	是	参数组版本号，目前固定为 `2025-05-01`	`2025-05-01`
`res`	string	是	访问资源路径，支持产品级或设备级	`products/3zbwuY8QUI`
`et`	int	是	过期时间，Unix 时间戳	`1771923663`
`method`	string	是	签名算法，支持 `md5`、`sha1`、`sha256`，推荐 `sha256`	`sha256`
`sign`	string	是	签名结果，需参与 URL 编码	`wU32oxVWluQLikUqs8OfRL5HPO6XursbxsxiKgy3rOo%3D`

2.3.3 `res` 使用场景

场景	`res` 格式	示例	说明
产品级鉴权（一型一密）	`products/{product_id}`	`products/3zbwuY8QUI`	同一产品下设备使用相同产品证书
设备级鉴权（一机一密）	`products/{product_id}/devices/{device_id}`	`products/3zbwuY8QUI/devices/862419074519231`	每台设备使用独立设备证书

2.3.4 `sign` 计算规则

签名字符串 StringForSignature 按字段名顺序拼接，并以换行符 \n 分隔：

plain

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

签名计算公式为：

plain

sign = base64(hmac_<method>(base64decode(key), utf-8(StringForSignature)))

其中：

key 为平台分配的访问密钥，参与计算前先做 base64decode
method 与 Token 中的 method 参数保持一致
推荐优先使用 sha256

示例：

plain

et = 1771923663
method = sha256
res = products/3zbwuY8QUI/devices/862419074519231
version = 2025-05-01

则待签名字符串为：

plain

1771923663
sha256
products/3zbwuY8QUI/devices/862419074519231
2025-05-01

2.3.5 Token 拼装与编码

签名计算完成后，按 key=value 形式拼装，并使用 & 连接：

plain

version=2025-05-01&res=products/3zbwuY8QUI/devices/862419074519231&et=1771923663&method=sha256&sign=wU32oxVWluQLikUqs8OfRL5HPO6XursbxsxiKgy3rOo=

Token 中每个 value 都应按 URL 规则编码，常见字符如下：

字符	编码
`+`	`%2B`
空格	`%20`
`/`	`%2F`
`?`	`%3F`
`%`	`%25`
`#`	`%23`
`&`	`%26`
`=`	`%3D`

编码后可得到实际传输的 Token：

plain

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

2.4 Token 计算器

产品级和设备级 Token 都可以在 Web 端计算。路径为：

设备列表 --> 设备详情 --> token计算器

单台设备的认证信息可在以下位置查看：

设备列表 --> 设备详情 --> 认证信息

2.5 认证说明

认证类型标识：
- S：简单认证
- E：加密认证
user_id：为平台用户 ID。使用不同用户 ID 连接时，设备归属关系也会不同
设备编号：
- 可在平台中手动创建设备，由平台生成设备编号
- 也可由设备端使用唯一编号自动注册，适合批量设备接入

三、主题规范

3.1 主题前缀

所有业务主题均以如下格式为前缀：

plain

$sys/{product_id}/{device_id}/silizap/

其中：

{product_id}：产品 ID
{device_id}：设备编号，建议与认证时使用的设备标识保持一致

3.2 设备订阅主题

主题	是否常用	说明
`$sys/{product_id}/{device_id}/silizap/function/get`	是	平台下发功能控制命令
`$sys/{product_id}/{device_id}/silizap/monitor/get`	是	平台下发监测、配置或一键控制类命令
`$sys/{product_id}/{device_id}/silizap/ota/get`	是	平台下发 OTA 升级请求
`$sys/{product_id}/{device_id}/silizap/info/post_reply`	按需	平台返回设备信息上报处理结果
`$sys/{product_id}/{device_id}/silizap/property/post_reply`	按需	平台返回属性上报处理结果
`$sys/{product_id}/{device_id}/silizap/monitor/post_reply`	按需	平台返回实时监测数据处理结果
`$sys/{product_id}/{device_id}/silizap/event/post_reply`	按需	平台返回事件上报处理结果

建议至少订阅：

function/get
monitor/get
ota/get

3.3 设备发布主题

主题	是否常用	说明
`$sys/{product_id}/{device_id}/silizap/info/post`	是	设备启动、重启、版本变化后上报基本信息
`$sys/{product_id}/{device_id}/silizap/property/post`	是	设备属性数据上报
`$sys/{product_id}/{device_id}/silizap/function/get_reply`	是	设备执行功能命令后的业务回执
`$sys/{product_id}/{device_id}/silizap/monitor/post`	是	设备实时监测数据上报
`$sys/{product_id}/{device_id}/silizap/monitor/get_reply`	是	设备对监测/组合控制类命令的回执
`$sys/{product_id}/{device_id}/silizap/ota/get_reply`	是	设备确认收到 OTA 指令
`$sys/{product_id}/{device_id}/silizap/ota/post`	是	设备上报 OTA 进度与结果
`$sys/{product_id}/{device_id}/silizap/event/post`	是	设备上报异常、告警、业务事件

3.4 主题使用建议

info/post：首次上线、设备重启、版本变更、SIM 或硬件信息变化时发送
property/post：用于常规状态和属性同步，是最常见的数据上报主题
monitor/post：适合高频监测或平台要求独立展示的监测数据
event/post：只上报事件，不建议与普通状态数据混用
function/get_reply、monitor/get_reply、ota/get_reply：用于业务确认，不建议仅依赖 MQTT QoS 替代业务回执

四、通用报文规范

4.1 通用字段

字段	类型	是否常见	说明
`did`	string	是	本次消息唯一标识。主动上报时由设备生成；命令回执时建议原样回传平台下发的 `did`
`version`	string	是	协议版本，当前统一使用 `1.0`
`time`	string	常见	设备本地时间，格式建议为 `YYYY-MM-DD HH:mm:ss`
`timestamp`	number	常见	毫秒级 Unix 时间戳
`params`	object/array	是	主体业务数据。上报类通常为对象，下行命令通常为数组
`functions`	array	常见	功能状态或功能回执内容集合
`properties`	array	常见	属性数据集合
`remark`	string	可选	展示说明字段，通常不作为业务解析主字段

4.2 上报类消息结构

设备主动上报 info/post、property/post、monitor/post、event/post、ota/post 时，通常采用如下结构：

json

{
  "did": "32位随机字符串或业务唯一ID",
  "version": "1.0",
  "params": {
    "time": "2026-02-24 17:01:03",
    "timestamp": 1771923663581
  }
}

约定：

params 为对象
业务字段放在 params 内部
同一条消息建议同时带上 time 与 timestamp

4.3 下行命令结构

平台下发 function/get、monitor/get、ota/get 时，通常采用如下结构：

json

{
  "did": "平台生成的请求ID",
  "version": "1.0",
  "params": [
    {
      "sensorname": "status",
      "sensorcmd": "open",
      "extdata": {}
    }
  ]
}

约定：

params 为数组
数组每个元素表示一条命令或一组业务参数
未识别字段建议忽略，不应导致整条消息处理失败

4.4 回执消息结构

设备回执 function/get_reply、monitor/get_reply、ota/get_reply 时，通常包含 code、msg 和业务体。

推荐结构：

json

{
  "did": "与下行命令一致的did",
  "version": "1.0",
  "code": 200,
  "msg": "",
  "params": {
    "time": "2026-02-24 17:02:10",
    "timestamp": 1771923730000
  }
}

4.5 物模型项约定

属性上报和功能状态上报中，通常使用以下数据结构：

json

{
  "id": "latitude",
  "value": 39.54321,
  "remark": "纬度"
}

字段	类型	必填	说明
`id`	string	是	物模型标识，必须与平台产品定义一致
`value`	any	是	实际值，类型应与物模型数据类型一致
`remark`	string	否	中文说明或设备侧附加注释

命令下发中，常见字段如下：

字段	类型	必填	说明
`sensorname`	string	是	功能标识或命令对象名称
`sensorcmd`	string	常见	命令参数，如 `open`、`close`
`extdata`	object	否	扩展参数，用于一键控制、配置、复杂指令

五、典型业务消息示例

5.1 设备信息上报 `info/post`

设备启动后建议立即上报一次设备信息，用于平台识别设备版本、硬件信息、在线状态等。

json

{
  "did": "0db795ee45fe93a2eda268a3fda76976",
  "version": "1.0",
  "params": {
    "time": "2026-02-24 17:01:03",
    "timestamp": 1771923663581,
    "info": {
      "longitude": "",
      "latitude": "",
      "version_name": "001.000.006",
      "fversion": "",
      "rssi": 23,
      "status": 3,
      "summary": {
        "electricity": 60,
        "keepalive_interval": 30,
        "gps_interval": 30,
        "sleep_interval": 0,
        "device_model": 1,
        "product": "SZ-4G01",
        "author": "silizap",
        "create": "2025-05-18",
        "name": "device"
      },
      "userId": "1922956817214873666",
      "uuid": "d51726cc634f4738bd12328a3c026271",
      "iccid": "898608271025D1379254",
      "rtm_id": 137,
      "chip": "EC718P"
    }
  }
}

说明：

info 建议用于描述设备静态信息和启动后状态快照
summary 适合放设备配置摘要、设备型号、电量、定位周期等概览信息
longitude、latitude 如果当前没有定位结果，可为空字符串或按产品约定处理

5.2 属性上报 `property/post`

属性上报是最常见的数据上行方式。推荐将可控状态放入 functions，将监测值放入 properties。

json

{
  "did": "45e354fde01f51b4efe8641c94fb034c",
  "version": "1.0",
  "params": {
    "time": "2026-02-22 19:27:13",
    "timestamp": 1771759633329,
    "functions": [
      {
        "id": "alarm",
        "value": "close",
        "remark": "寻机"
      }
    ],
    "properties": [
      {
        "id": "longitude",
        "value": "123.951800",
        "remark": "经度"
      },
      {
        "id": "latitude",
        "value": "47.326720",
        "remark": "纬度"
      },
      {
        "id": "satellite",
        "value": 20,
        "remark": "卫星"
      },
      {
        "id": "satsnum",
        "value": 20,
        "remark": "可见卫星数"
      },
      {
        "id": "altitude",
        "value": 200.1,
        "remark": "海拔高度"
      },
      {
        "id": "gprs",
        "value": 28,
        "remark": "4G信号"
      },
      {
        "id": "electricity",
        "value": 65,
        "remark": "电量"
      },
      {
        "id": "direction",
        "value": 0,
        "remark": "地面航向"
      },
      {
        "id": "loc_type",
        "value": 1,
        "remark": "定位类型"
      },
      {
        "id": "speed_mps",
        "value": 1.299,
        "remark": "速度(m/s)"
      },
      {
        "id": "speed_kmh",
        "value": 4.6764,
        "remark": "速度(km/h)"
      }
    ]
  }
}

说明：

functions 可为空数组，也可不带；但建议保持产品内风格统一
properties.id 必须与平台物模型中的模型标识一致
value 数据类型应与平台物模型一致，例如整数、小数、布尔、字符串、枚举

5.3 接收控制指令 `function/get`

平台下发功能控制命令示例：

json

{
  "did": "yDkkSdFhdsgLgOkaClFqmsKzZUxT31nd",
  "version": "1.0",
  "params": [
    {
      "sensorname": "status",
      "sensorcmd": "open",
      "extdata": {}
    }
  ]
}

说明：

sensorname 一般对应平台中的功能标识
sensorcmd 一般对应功能命令参数，如 open、close
extdata 用于附加参数透传

5.4 执行结果回执 `function/get_reply`

设备执行完平台指令后，应尽快回执业务结果。

推荐写法：

json

{
  "did": "yDkkSdFhdsgLgOkaClFqmsKzZUxT31nd",
  "version": "1.0",
  "code": 200,
  "msg": "",
  "params": {
    "functions": [
      {
        "sensorname": "status",
        "sensorcmd": "open",
        "extdata": {}
      }
    ]
  },
  "time": "2026-02-24 17:02:10",
  "timestamp": 1771923730000
}

建议：

成功执行时 code 使用 200，did与远控下发时保持一致
如果执行失败，code 使用 500，did与远控下发时保持一致，并在 msg 中填写失败原因

5.5 一键控制 `monitor/get`

monitor/get 常用于组合命令、实时监测控制或设备配置下发。仓库中的示例固件对一键控制的处理方式如下：

json

{
  "did": "5dddc6b8e4204c43af2b4fd8f8814001",
  "version": "1.0",
  "params": [
    {
      "sensorname": "combinecontroll",
      "extdata": {
        "data": [
          {
            "sensorname": "lamp",
            "sensorcmd": "open"
          },
          {
            "sensorname": "fan",
            "sensorcmd": "close"
          }
        ]
      }
    }
  ]
}

对应回执示例：

json

{
  "did": "5dddc6b8e4204c43af2b4fd8f8814001",
  "version": "1.0",
  "code": 200,
  "msg": "",
  "params": {
    "functions": [
      {
        "sensorname": "combinecontroll",
        "extdata": {
          "data": [
            {
              "sensorname": "lamp",
              "sensorcmd": "open"
            },
            {
              "sensorname": "fan",
              "sensorcmd": "close"
            }
          ]
        }
      }
    ]
  },
  "time": "2026-02-24 17:03:16",
  "timestamp": 1771923796000
}

说明：

一键控制建议先回 monitor/get_reply，再执行命令序列
执行完后建议补发一次 property/post，把最终状态同步给平台

5.6 OTA 请求与进度反馈

ota/get、ota/get_reply、ota/post 的业务字段允许按产品差异扩展。对于新设备，推荐采用以下结构。

平台下发 OTA 请求示例：

json

{
	"version": "1.0",
	"params": [
		{
			"sensorname": "ota",
			"sensorcmd": "open",
			"extdata": {
				"url": "https://iot.silizap.com/static/2026/03/24/W766D59Noutput.sota",
				"version": "0.0.0.17"
			}
		}
	],
	"did": "AxYEXxkZWbILHGm3Kr3ehywgcQcg4W2L"
}

设备确认收到 OTA 请求：

json

{
	"did": "AxYEXxkZWbILHGm3Kr3ehywgcQcg4W2L",
	"version": "1.0",
	"code": 200,
	"msg": "",
	"params": {
		"time": "2026-03-24 23:08:59",
		"functions": [
			{
				"sensorcmd": "open",
				"sensorname": "ota",
				"extdata": {
					"version": "0.0.0.17",
					"url": "https://iot.silizap.com/static/2026/03/24/W766D59Noutput.sota"
				}
			}
		],
		"timestamp": 1774364900000
	}
}

设备上报 OTA 进度示例：

json

{
	"did": "b07859ceb682b82ed1290eebfd43948a",
	"version": "1.0",
	"params": {
		"time": "2026-03-24 23:08:59",
		"fota": {
			"progress": "--",
			"fotastatus": "fota_started",
			"msg": "升级开始",
			"version": "0.0.0.17"
		},
		"timestamp": 1774364900000
	}
}

{
	"did": "ca0dbec935d25b0061b0db93e43ce7c4",
	"version": "1.0",
	"params": {
		"time": "2026-03-24 23:09:00",
		"fota": {
			"progress": "--",
			"fotastatus": "fota_finished",
			"msg": "升级成功",
			"version": "0.0.0.17"
		},
		"timestamp": 1774364900000
	}
}

说明：

ota/get_reply 用于确认“已收到升级请求”
ota/post 用于持续上报下载中、校验中、升级中、成功、失败等状态
如果产品已有 OTA 字段定义，优先沿用现网格式，不建议在升级中途切换字段名

5.7 事件上报 `event/post`

事件类消息建议只在异常、告警或特殊业务触发时发送，不建议拿来替代普通属性上报。

推荐示例：

json

{
	"did": "qYBuvn8sRLEoCNPQ73VGrvjkis2LGvU7",
	"version": "1.0",
	"params": {
		"time": "2026-03-24 23:13:40",
		"event": {
			"reason": 1,
			"eventtype": "EVENT_POWER_ON"
		},
		"timestamp": 1774365200000
	}
}

{
	"did": "0ae8a6be3d0ede879ac8bf6b04608773",
	"version": "1.0",
	"params": {
		"time": "2026-03-24 23:09:02",
		"event": {
			"eventtype": "EVENT_POWER_RESTART",
			"reason": "fota_finished",
			"version": "0.0.0.17"
		},
		"timestamp": 1774364900000
	}
}

说明：

事件 id 建议与平台事件物模型标识保持一致
同一事件如果需要恢复通知，建议单独再上报一次恢复事件或状态变化

六、交互流程与实现建议

6.1 推荐交互流程

设备生成唯一 Client ID 并完成 MQTT 连接
设备订阅 function/get、monitor/get、ota/get
连接成功后立即上报 info/post
定时或按变化上报 property/post
收到平台命令后，先执行业务处理，再回 *_reply
如果命令改变了设备状态，建议再补发一次 property/post
发生异常时上报 event/post
固件升级时，先回 ota/get_reply，再持续上报 ota/post

6.2 `did` 使用建议

主动上报消息：由设备生成唯一 did
下行命令回执：建议使用平台下发的原始 did
同一条命令的回执和后续状态上报可以使用不同 did
did 建议为 32 位随机字符串、UUID 去连接符，或其他产品内唯一值

6.3 字段设计建议

id、sensorname 必须与平台物模型定义保持一致
value 的类型应与平台物模型中的数据类型一致
remark 建议只用于说明，不作为主业务字段
同一产品内不要混用数字和字符串类型，例如经度不要一会儿传 "116.3"，一会儿传 116.3
未使用的字段可以省略，不建议填入大量无意义空字段

七、补充说明

本文档描述的是 SZ-JSON 现网协议，重点是“如何稳定接入”，而不是重新设计一套新协议
若您正在设计低带宽、强约束、长期演进的二进制协议，可参考 SZ-HEX 版本
若您只是想快速完成设备接入，可结合快速入门一起使用

MQTT协议（SZ-JSON） ​

一、适用范围与接入概览 ​

二、MQTT 连接与认证 ​

2.1 连接建议 ​

2.2 简单认证 ​

2.2.1 认证参数格式 ​

2.2.2 认证参数示例 ​

2.3 加密认证（Token 认证） ​

2.3.1 认证参数格式 ​

2.3.2 Token 组成 ​

2.3.3 res 使用场景 ​

2.3.4 sign 计算规则 ​

2.3.5 Token 拼装与编码 ​

2.4 Token 计算器 ​

2.5 认证说明 ​

三、主题规范 ​

3.1 主题前缀 ​

3.2 设备订阅主题 ​

3.3 设备发布主题 ​

3.4 主题使用建议 ​

四、通用报文规范 ​

4.1 通用字段 ​

4.2 上报类消息结构 ​

4.3 下行命令结构 ​

4.4 回执消息结构 ​

4.5 物模型项约定 ​

五、典型业务消息示例 ​

5.1 设备信息上报 info/post ​

5.2 属性上报 property/post ​

5.3 接收控制指令 function/get ​

5.4 执行结果回执 function/get_reply ​

5.5 一键控制 monitor/get ​

5.6 OTA 请求与进度反馈 ​

5.7 事件上报 event/post ​

六、交互流程与实现建议 ​

6.1 推荐交互流程 ​

6.2 did 使用建议 ​

6.3 字段设计建议 ​

七、补充说明 ​

MQTT协议（SZ-JSON）

一、适用范围与接入概览

二、MQTT 连接与认证

2.1 连接建议

2.2 简单认证

2.2.1 认证参数格式

2.2.2 认证参数示例

2.3 加密认证（Token 认证）

2.3.1 认证参数格式

2.3.2 Token 组成

2.3.3 `res` 使用场景

2.3.4 `sign` 计算规则

2.3.5 Token 拼装与编码

2.4 Token 计算器

2.5 认证说明

三、主题规范

3.1 主题前缀

3.2 设备订阅主题

3.3 设备发布主题

3.4 主题使用建议

四、通用报文规范

4.1 通用字段

4.2 上报类消息结构

4.3 下行命令结构

4.4 回执消息结构

4.5 物模型项约定

五、典型业务消息示例

5.1 设备信息上报 `info/post`

5.2 属性上报 `property/post`

5.3 接收控制指令 `function/get`

5.4 执行结果回执 `function/get_reply`

5.5 一键控制 `monitor/get`

5.6 OTA 请求与进度反馈

5.7 事件上报 `event/post`

六、交互流程与实现建议

6.1 推荐交互流程

6.2 `did` 使用建议

6.3 字段设计建议

七、补充说明