MQTT协议（SZ-HEX）

本文档用于规范定位器与云平台的数据交互标准，包括数据上报格式、设备配置指令、OTA远程升级规则及MQTT通信配置，适用于技术对接、设备调试及维护场景。

示例产品参数：

产品名称：SZ-4G01
产品编码：gPVvQcxKBQ
IMEI：866965083599537

一、数据上报基本格式

定位器向云平台上报数据采用MQTT协议，数据经AES-128加密后以Base64格式传输（以下格式说明均以明文展示）。字段间用英文逗号（,） 分隔，帧尾以星号（*） 结束。

1.1 帧通用格式

字段顺序	字段名称	长度（字符）	说明
1	起始码	7	固定为 `@SZ-4G01`（必填，产品名称）
2	分隔符	1	英文逗号（,）
3	设备ID	15	设备自身IMEI串号（唯一标识）
4	分隔符	1	英文逗号（,）
5	帧类型	2	数据包类型标识（00-FF，具体见1.2节）
6	分隔符	1	英文逗号（,）
7	数据部分	可变	长度由帧类型决定（具体字段见对应帧说明）
8	校验值	8	CRC32校验值（计算范围：起始码至数据部分的所有字符串）
9	结束码	1	固定为 `*`（必填）

通用格式示例

plain text

@SZ-4G01,<设备IMEI>,<数据类型>,<数据部分>,<CRC32校验值>*

1.2 具体数据帧说明

1.2.1 心跳数据上报帧（帧类型：01）

用于设备向平台上报运行状态基础信息。

字段顺序	字段内容	说明
1-6	起始码~帧类型	固定为 `@SZ-4G01,<IMEI>,01,`
7	数据部分（DATA）	格式：`设备电量,4G信号强度,ICCID,设备版本号,GPS标识`
8-9	校验值~结束码	CRC32校验值 + `*`

数据部分字段说明

设备电量：数值型（如80代表80%）
4G信号强度：数值型（如30代表信号强度等级）
ICCID：物联网卡唯一标识
设备版本号：格式如 001.001.003
GPS标识：A（已接收GPS信号）/ V（未接收GPS信号）

示例与解析

plain text

@SZ-4G01,866965083599537,01,60,21,898608271025D1379254,001.000.006,V,afcc0d72*

解析项	对应值
设备IMEI	866965083599537
帧类型	01（心跳数据）
设备电量	60
4G信号强度	21
ICCID	898608271025D1379254
设备版本号	001.000.006
GPS标识	V（未接收GPS信号）
CRC32校验值	afcc0d72

1.2.2 GPS数据上报帧（帧类型：02）

用于上报设备定位信息，经纬度采用WGS84坐标系。

字段顺序	字段内容	说明
1-6	起始码~帧类型	固定为 `@SZ-4G01,<IMEI>,02,`
7	数据部分（DATA）	格式：`纬度,纬度半球,经度,经度半球,地面速率,地面航向,海拔高度,可见卫星数`，设备电量，4G信号强度
8-9	校验值~结束码	CRC32校验值 + `*`

数据部分字段说明

字段	格式/范围	单位	备注
纬度	dd.dddd（如31.28506）	-	-
纬度半球	N（北纬）/ S（南纬）	-	二选一
经度	dd.dddd（如121.0803）	-	-
经度半球	E（东经）/ W（西经）	-	二选一
地面速率	000.0~999.9	节	-
地面航向	000.0~359.9	度	-
海拔高度	数值型	米	-
可见卫星数	数值型	个	-
设备电量	数值型	%	-
4G信号强度	数值型	-	-

示例与解析

plain text

@SZ-4G01,866965083599651,02,30.29297,N,120.0290,E,6.219000,0,11.20000,38,67,22,ab3df478*

解析项	对应值
设备IMEI	866965083599651
帧类型	02（GPS数据）
纬度+半球	30.29297（北纬N）
经度+半球	120.0290（东经E）
地面速率	6.219000 节
地面航向	0 度
海拔高度	11.20000米
可见卫星数	38个
设备电量	67%
4G信号强度	22
CRC32校验值	ab3df478

1.2.3 蓝牙扫描数据上报帧（帧类型：03）--待更新

用于上报周边蓝牙信标扫描结果。

字段顺序	字段内容	说明
1-6	起始码~帧类型	固定为 `@SZ-4G01,<IMEI>,03,`
7	数据部分（DATA）	格式：`信标1_MAC,信标1_RSSI,信标2_MAC,信标2_RSSI,...`（支持多信标批量上报）
8-9	校验值~结束码	CRC32校验值 + `*`

数据部分字段说明

MAC地址：蓝牙信标硬件地址（如d435388496d5）
RSSI：信号强度（负值，如-63，数值越接近0信号越强）

示例与解析

plain text

@SZ-4G01,866965083599545,03,d435388496d5,-63,305f77f51f2f,-64,5223bc10*

解析项	对应值
设备IMEI	866965083599545
帧类型	03（蓝牙扫描数据）
信标1	MAC：d435388496d5，RSSI：-63
信标2	MAC：305f77f51f2f，RSSI：-64
CRC32校验值	5223bc10

1.2.4 WiFi扫描数据上报帧（帧类型：04）--待更新

用于上报周边WiFi热点扫描结果。

字段顺序	字段内容	说明
1-6	起始码~帧类型	固定为 `@SZ-4G01,<IMEI>,04,`
7	数据部分（DATA）	格式：`热点1_MAC,热点1_RSSI,热点2_MAC,热点2_RSSI,...`（支持多热点批量上报）
8-9	校验值~结束码	CRC32校验值 + `*`

数据部分字段说明

MAC地址：WiFi热点硬件地址（如483fda1a7759）
RSSI：信号强度（负值，如-52，数值越接近0信号越强）

示例与解析

plain text

@SZ-4G01,866965083599545,04,483fda1a7759,-52,30eda0b14570,-60,fefeea98*

解析项	对应值
设备IMEI	866965083599545
帧类型	04（WiFi扫描数据）
热点1	MAC：483fda1a7759，RSSI：-52
热点2	MAC：30eda0b14570，RSSI：-60
CRC32校验值	fefeea98

1.2.5 设备信息数据上报帧（帧类型：05）

设备上电后第一帧数据，用于设备向平台上报设备的基础信息。

字段顺序	字段内容	说明
1-6	起始码~帧类型	固定为 `@SZ-4G01,<IMEI>,05,`
7	数据部分（DATA）	格式：`设备电量,4G信号强度,ICCID,设备版本号,GPS标识,uuid唯一编码、rtm_id`
8-9	校验值~结束码	CRC32校验值 + `*`

数据部分字段说明

设备电量：数值型（如65代表65%）
4G信号强度：数值型（如21代表信号强度等级）
ICCID：物联网卡唯一标识，898608271025D1379254
设备版本号：格式如 001.001.003
GPS标识：A（已接收GPS信号）/ V（未接收GPS信号）
UUID：唯一配置信息编码，e190089b085d42f2b92764df1db611f7；
rtm_id：平台配置信息在平台唯一标识

示例与解析

plain text

@SZ-4G01,866965083599537,05,60,23,898608271025D1379254,001.000.006,V,d51726cc634f4738bd12328a3c026271,137,f6ff0fa1*

解析项	对应值
设备IMEI	866965083599537
帧类型	05（设备信息）
设备电量	60
4G信号强度	23
ICCID	898608271025D1379254
设备版本号	001.000.006
GPS标识	V（未接收GPS信号）
UUID	d51726cc634f4738bd12328a3c026271
rtm_id	137
CRC32校验值	f6ff0fa1

二、设备配置指令

云平台通过自定义AT指令远程配置设备参数，指令以字符串形式传输，设备执行后返回结果。

2.1 指令通用格式

字段名称	格式	长度（字节）	说明
起始码	AT	2	固定字符串
连接符	+	1	固定字符
配置指令	自定义	可变	参数类型标识（如HEARTTIMESET）
连接符	=	1	固定字符
配置参数	自定义	可变	具体配置值（多参数用英文逗号分隔）
结束码	#	1	固定字符

通用格式示例：AT+<配置指令>=<配置参数>#

2.2 常用配置指令定义

指令类型	指令名称	配置指令	配置参数格式	示例	备注
配置/监测	MQTT服务器地址设置	RTMCONFIG	<rtm_id>,<IP>,<PORT>,<username>,<password>,<产品编号>,<产品密钥>,<保活时长>,<加密方式>	`AT+RTMCONFIG=137,127.0.0.1,1883,gPVvQcxKBQ,PWZldGVFZVcxTDdJRzlvOVIwQm94WkE3YjFjMUtoN11=,KmZwYW9VeXJuNHhxRlh6MG1rVE1Hb3V4UnhtS1llRz2=,30,E#`	8个参数必须同时设置，否则无法连接MQTT服务器
配置/监测	心跳上报时间设置	HEARTTIMESET	0~300（单位：s）	`AT+HEARTTIMESET=100#`	0表示不上报心跳数据
配置/监测	GPS数据上报时间设置	GPSTIMESET	0~300（单位：s）	`AT+GPSTIMESET=100#`	0表示不上报GPS数据
配置/监测	设备休眠	SLEEPSET	600~86400（单位：s）	`AT+SLEEPSET=3600#`	设备休眠唤醒时间在10分钟~24小时之间
配置/监测	组合指令下发	TIMESET	-	`@SZ-4G01,866965083599537,03,AT+TIMESET=AT+TIMESET=d51726cc634f4738bd12328a3c026271,30,10,1#`	uuid、心跳、GPS、休眠时长
配置/监测	扫描数据上报时间设置	SCANTIMESET	5~300（单位：s）	`AT+SCANTIMESET=100#`	<5表示不上报扫描数据（蓝牙/WiFi）
配置/监测	扫描模式切换	SCANMODESET	WIFI_SCAN / BT_SCAN	`AT+SCANMODESET=WIFI_SCAN#`	二选一，仅支持单一模式扫描
远控	设备状态刷新	REFRESH	1	`AT+REFRESH=1#`	参数固定为1
远控	远程重启	REBOOT	1	`AT+REBOOT=1#`	参数固定为1
升级	设备升级	OTA	-	`AT+OTA=https://127.0.0.1/statics/2026/02/08/E0AC25R20output.sota#`	参数是一个URL固件地址

2.3 配置指令回复格式

设备执行指令后，主动向云平台返回执行结果，格式如下：

回复帧格式

字段顺序	字段内容	说明
1	起始码	@SZ-4G01（固定）
2	分隔符	,（英文逗号）
3	设备IMEI	15字节（设备唯一标识）
4	分隔符	,（英文逗号）
5	数据类型	EE（固定）
6	分隔符	,（英文逗号）
7	指令	云平台下发的配置指令
8	分隔符	,（英文逗号）
9	执行结果	0~5（含义见下表）
10	校验值	CRC32校验值（8字节）
11	结束码	*（固定）

回复示例

plain

text
@SZ-4G01,866965083599537,EF,OTA,1,df6174db*

执行结果编码说明

结果编码	含义
0	执行成功
1	帧格式错误（指令不符合AT指令通用格式）
2	IMEI错误（设备IMEI与指令目标IMEI不匹配）
3	CRC32校验错误（指令校验值计算异常）
4	指令错误（配置指令不存在，如拼写错误）
5	数据错误（配置参数超出范围或格式非法）

三、MQTT通信配置及加密参数

3.1 MQTT核心配置

分类	项目	取值	说明
配置项	服务器IP	xx.xx.xx.xx/域名	实际部署时替换为真实IP/域名
配置项	服务器端口	1883	MQTT默认通信端口
配置项	登录账号	xxxxxx	预设固定账号（根据实际情况设置）
配置项	登录密码	xxxxxx	预设固定密码（根据实际情况设置）
Client ID	Client ID	格式："E" + "&" + IMEI + "&" + <产品ID> + "&" + user_id 示例： E&866965083599537&gPVvQcxKBQ&1 S&866965083599537&gPVvQcxKBQ&1	客户端ID等于：认证类型 + 设备IMEI + 产品ID + 用户ID 认证类型：E加密认证(推荐)、S简单认证设备IMEI：866965083599537 产品ID：gPVvQcxKBQ 用户ID默认：1
设备订阅	远控下发	格式：$sys/<产品ID>/<自身IMEI>/silizap/function/get 示例：$sys/gPVvQcxKBQ/866965083599537/silizap/function/get `@SZ-4G01,866965083599537,03,AT+REFRESH=1#*`	接收平台远控指令
设备订阅	OTA升级	格式：$sys/<产品ID>/<自身IMEI>/silizap/ota/get 示例：$sys/gPVvQcxKBQ/866965083599537/silizap/ota/get @SZ-4G01,866965083599537,03,AT+OTA=https://127.0.0.1/statics/2026/02/08/E0AC25R20output.sota#*	接收平台升级命令
设备订阅	配置下发	格式：$sys/<产品ID>/<自身IMEI>/silizap/monitor/get 示例：$sys/gPVvQcxKBQ/866965083599537/silizap/monitor/get `@SZ-4G01,866965083599537,03,AT+TIMESET=iXk9woovRhzkR8syOMgGeVRarmV9KKCg,30,10,1#*`	接收平台远控指令
设备订阅	~~平台回复设备信息上报结果~~	~~格式：$sys/<产品ID>/<自身IMEI>/silizap/info/post_reply~~	~~接收平台远控指令：平台回复设备信息上报结果~~
设备订阅	~~平台回复订阅实时监测信号的结果~~	~~1. 格式：$sys/<产品ID>`/<自身IMEI>/silizap/monitor/post_reply`~~ ~~2.示例：~~ ~~$sys/gPVvQcxKBQ/866965083599537/silizap/monitor/post_reply~~	~~接收平台远控指令：平台回复订阅实时监测信号的结果~~
设备订阅	~~平台回复设备事件处理结果~~	~~1. 格式：$sys/<产品ID>`/<自身IMEI>/silizap/event/post_reply`~~ ~~2.示例：~~ ~~$sys/gPVvQcxKBQ/866965083599537/silizap/event/`post_reply`~~	~~接收平台远控指令：平台回复设备事件处理结果~~
设备订阅	~~平台回复设备属性数据接收结果~~	~~1. 格式：$sys/<产品ID>`/<自身IMEI>/silizap/property/post_reply`~~ ~~2.示例：~~ ~~$sys/gPVvQcxKBQ/866965083599537/silizap/property/post_reply~~	~~接收平台远控指令：平台回复设备属性数据接收结果~~
设备发布	设备基本信息	1.格式：$sys/<产品ID>`/<自身IMEI>/`silizap/info/post 2.示例：$sys/gPVvQcxKBQ/866965083599537/silizap/info/post @SZ-4G01,866965083599537,05,60,23,898608271025D1379254,001.000.006, V,d51726cc634f4738bd12328a3c026271,137,f6ff0fa1*	设备向平台设备基本信息（设备上电启动时发布）
设备发布	上报属性数据	1.格式：$sys/<产品ID>`/<自身IMEI>/`silizap/property/post 2.示例：$sys/gPVvQcxKBQ/866965083599537/silizap/property/post	设备向平台上报属性数据的统一主题
设备发布	发布设备升级进度和状态	1.格式：$sys/<产品ID>`/<自身IMEI>/`silizap/ota/post 2.示例：$sys/gPVvQcxKBQ/866965083599537/silizap/ota/post	设备向平台发布设备升级进度和状态
设备发布	~~发布设备异常或特殊事件~~	~~1.格式：$sys/<产品ID>`/<自身IMEI>/`silizap/event/post~~ ~~2.示例：$sys/gPVvQcxKBQ/866965083599537/silizap/event/post~~	~~设备向平台发布设备异常或特殊事件~~
设备发布	~~发布设备实时监测数据~~	~~1.格式：$sys/<产品ID>`/<自身IMEI>/`silizap/monitor/post~~ ~~2.示例：$sys/gPVvQcxKBQ/866965083599537/silizap/monitor/post~~	~~设备向平台发布设备实时监测数据~~
设备发布	回复FOTA升级指令执行结果	1. 格式：$sys/<产品ID>`/<自身IMEI>/`silizap/ota/get_reply 2.示例： $sys/gPVvQcxKBQ/866965083599537/silizap/ota/get_reply @SZ-4G01,866965083599537,EF,OTA,1,df6174db*	设备向平台上报：回复FOTA升级
设备发布	回复远控/配置指令执行结果	1. 格式：$sys/<产品ID>`/<自身IMEI>/`silizap/function/get_reply 2.示例： $sys/gPVvQcxKBQ/866965083599537/silizap/function/get_reply @SZ-4G01,866965083599537,EE,REFRESH,0,28dc35d1*	设备向平台上报：回复远控/配置
设备发布	回复监测指令执行结果	1. 格式：$sys/<产品ID>`/<自身IMEI>/`silizap/monitor/get_reply 2.示例： $sys/gPVvQcxKBQ/866965083599537/silizap/monitor/get_reply @SZ-4G01,866965083599537,EE,TIMESET,0,28dc35d1*	设备向平台上报：回复监测指令执行结果

3.2 AES-128加密参数（默认配置）

参数名称	取值	说明
运算模式	CBC（密码块链模式）	固定加密模式
填充模式	PKCS7	数据长度不足时的填充规则
密钥长度	128 bits	固定密钥长度
密钥（Hex格式）	1989905867707723	固定加密密钥(示例)
偏移（Hex格式）	4504921702684196	固定偏移量(示例)

AES-128算法参数如图（示例）：

四、其他

4.1设备类型

产品ID	含义
SZ-4G01	OBD车载定位通讯终端
SZ-H01	GPS、WiFi、蓝牙三合一定位通讯终端
SZ-H02	头盔定位通讯终端
SZ-G01	人体定位器
SZ-G02	工牌定位器
SZ-U01	无人机定位器
SZ-4G100S	物品定位器

4.2术语说明

术语	含义
IMEI	国际移动设备识别码（15位，设备唯一标识）
CRC32	32位循环冗余校验码（用于数据完整性校验）
WGS84	全球定位系统（GPS）采用的坐标系
RSSI	接收信号强度指示（负值，绝对值越小信号越强）
FOTA	固件空中升级（远程升级设备固件）
AES-128	128位高级加密标准（数据传输加密算法）

五、常见问题

5.1 常见问题

5.1.1 地图显示的设备位置与实际有差异

数据解析：请检查经纬度解析是否正常，经纬度是否按照协议文档解析，是否存在解析格式错误；
经纬度转换：设备均使用国际标准 WGS-84 坐标系，国内常见地图（高德地图 GCJ-02 坐标系、百度地图 BD-09 坐标系）采用非标坐标系，直接使用设备输出经纬度会产生几十米误差，此为坐标系差异导致，非模块故障。开发者需对经纬度进行加偏处理，可参考：https://docs.openluat.com/file/GPS-Offset.html
遮挡信号：设备周围若有高楼、金属遮挡物会影响卫星信号接收，建议在开阔地带进行定位测试。

5.1.2 定位延迟过高

卫星搜星数量：检查设备搜星数量是否≥4 颗，搜星数量不足会导致定位延迟或定位失败；可通过设备日志查看卫星信号强度，若信号弱可调整设备安装位置（远离金属、电磁干扰源）。
数据传输链路：排查 MQTT 传输延迟，查看 EMQX 服务器与设备的网络时延（可通过 ping 命令测试）；若时延过高，可优化服务器部署位置或切换网络运营商。
后端处理逻辑：检查后端对定位数据的处理效率，是否存在数据库写入阻塞、业务逻辑冗余等问题；可对写入语句进行优化，减少数据处理耗时。

5.2 设备离线

SIM 卡状态：确认 SIM 卡是否欠费、是否开通数据业务、是否插卡到位；可更换测试 SIM 卡验证是否为卡体问题。
MQTT 连接配置：检查设备端 MQTT 客户端配置（服务器地址、端口、客户端 ID、用户名密码）是否正确；确认 EMQX 服务器是否正常运行，是否开启对应端口的防火墙权限。
心跳机制失效：设备与 EMQX 需配置合理的心跳间隔，若心跳间隔过长可能被服务器判定为离线；建议心跳间隔设置为 30 - 60s，同时检查设备休眠策略是否影响心跳包发送。

5.3 定位数据上传失败

协议格式错误：检查设备上传的定位数据是否符合后端接口协议（如 JSON 字段是否完整、字段类型是否匹配）；可通过 EMQX 控制台订阅设备主题，查看原始数据格式。

MQTT协议（SZ-HEX） ​

一、数据上报基本格式 ​

1.1 帧通用格式 ​

1.2 具体数据帧说明 ​

1.2.1 心跳数据上报帧（帧类型：01） ​

1.2.2 GPS数据上报帧（帧类型：02） ​

1.2.3 蓝牙扫描数据上报帧（帧类型：03）--待更新 ​

1.2.4 WiFi扫描数据上报帧（帧类型：04）--待更新 ​

1.2.5 设备信息数据上报帧（帧类型：05） ​

二、设备配置指令 ​

2.1 指令通用格式 ​

2.2 常用配置指令定义 ​

2.3 配置指令回复格式 ​

三、MQTT通信配置及加密参数 ​

3.1 MQTT核心配置 ​

3.2 AES-128加密参数（默认配置） ​

四、其他 ​

4.1设备类型 ​

4.2术语说明 ​

五、常见问题 ​

5.1 常见问题 ​

5.1.1 地图显示的设备位置与实际有差异 ​

5.1.1 地图显示的设备位置与实际有差异 ​

5.1.2 定位延迟过高 ​

5.2 设备离线 ​

5.3 定位数据上传失败 ​

MQTT协议（SZ-HEX）

一、数据上报基本格式

1.1 帧通用格式

1.2 具体数据帧说明

1.2.1 心跳数据上报帧（帧类型：01）

1.2.2 GPS数据上报帧（帧类型：02）

1.2.3 蓝牙扫描数据上报帧（帧类型：03）--待更新

1.2.4 WiFi扫描数据上报帧（帧类型：04）--待更新

1.2.5 设备信息数据上报帧（帧类型：05）

二、设备配置指令

2.1 指令通用格式

2.2 常用配置指令定义

2.3 配置指令回复格式

三、MQTT通信配置及加密参数

3.1 MQTT核心配置

3.2 AES-128加密参数（默认配置）

四、其他

4.1设备类型

4.2术语说明

五、常见问题

5.1 常见问题

5.1.1 地图显示的设备位置与实际有差异

5.1.1 地图显示的设备位置与实际有差异

5.1.2 定位延迟过高

5.2 设备离线

5.3 定位数据上传失败