Skip to content

文本协议

# 协议格式

$X#Cmd#Content&CheckCode\r\n

$ 符号:协议开始符号

& 符号:内容分割符

\r\n 符号:协议结束符,十六进制0x0A 0x0D

# 符号:内容分割符,对协议内容进行分段。每段内容描述如下:

  • $X:协议固定开头

  • Cmd:协议功能,如Cmd为DATA为上传数据。部分指令功能码有简写,如DATA,简写为D。可减小发送数据量

  • Content:协议数据,数据格式见协议详情,注意数据中不可以出现#号。如果没有内容可以不需要该字段。

  • CheckCode:校验码,&前所有字符进行异或得到 1 个字节的十六进制数,以2 个ASCII 字符形式输出。如以下协议:$X#Cmd#Timestamp#Content&CheckCode\r\n &#之前部分异或得到校验码为0x12,则CheckCode位填12

    对于设备发给手机的长指令,可以分成几次发送,以\r\n结束

tips: 校验码计算工具小机云调试工具在线计算

# 协议回复格式

$XA#Cmd#Content&CheckCode\r\n

如果无特殊说明,指令统一回复:

成功:$XA#Cmd#OK&CheckCode

失败:$XA#Cmd#ERR:message&CheckCode

常见的错误回复

ERR:CRC:未进行KEY_CONTENT校验,详见本文发送校验内容一节

ERR:XOR:指令校验码错误

ERR:D:数据格式错误

LOAD_FAIL:加载错误

# 发送数据

CMD:DATA,简写D

格式:$X#D#key1:data1;key2:data2&#CheckCode#\r\n

可以设置一个数组也可以同时设置多组数据,bool内容支持0和1表示

示例1:$X#D#switch:1&21

示例2:$X#D#value:32;enabled1:false;enabled2:0;items:a,b,a;numbers:1,2,3;color:ff0000&1E

回复:$XA#D#OK&7D

# 查询时间

CMD:NOW,简写N

格式:$X#N#format:timestamp;AT&CheckCode\r\n

参数:

​ format: 可选,date或timestamp,默认timestamp

​ at: 可选,1为以AT指令回复,默认0

示例1:$X#N&11

示例2:$X#N#format:timestamp&65

回复:$XA#N#timestamp:1692262196515&12

示例2:$X#N#format:date&1F

回复:$XA#N#year:2023;month:8;day:17;hour:16;minute:57;second:59;millis:844&46

示例2:$X#N#format:timestamp;at:1&40

回复:AT+NOW=1692262196515\r\n

#上传设备属性

CMD:SET_PROPS,简写SP

格式:$X#SP#cap:value&CheckCode\r\n

描述:设置电量

参数:cap:电量值0~100

示例1:$X#SP#cap:11&37

设备校验

# 查询校验状态

CMD:PASS,简写P

格式:$X#P#param&CheckCode\r\n

参数:param,默认P,可不填。

参数可选值:P(默认,可不填):查询是否校验通过。返回:0(校验未通过),1(校验已通过)

​   T:查询校验方式(crcType)。返回:TS(secretGroup校验方式),TK(keyContent校验方式)

示例1:$X#P&0f

回复1:$XA#P#0&5d

示例2:$X#P#T&78

回复2:$XA#P#TS&6a

# 秘钥校验

CMD:SECRET,简写S

格式:$X#S#param&CheckCode\r\n

参数可选值:?:查询秘钥,返回秘钥前8位

​ 秘钥值:向APP发送匹配到的秘钥第8位后的任意8位

示例1:查询秘钥:$X#S#?&10

回复:

$XA#S#n6dnf34f&3b

$XA#K#ERR:TK&16 表示校验方式为KeyContent

示例2:校验秘钥:$X#S#h9230z4k&6A

回复:

$XA#S#OK&6a

$XA#S#CRC_FAIL&61 校验错误

# 发送校验内容(KeyContent)

作用:硬件与手机连接后,需要向手机发校验内容。校验通过后才可正常使用。检验内容请查看,设备校验一章。该指令可以分成几次发送,以\r\n结束

CMD:KEY,简写K

格式:$X#K#keyContent&CheckCode\r\n

示例一:

$X#K#0#E286C8CB7D983A9987BECBECF191A134BF9B58055EA87FC70E066096DCDBEF33CF5D949EA18C8DBA14C07EA9DB00CB1543169E878DDEB55FA6DC87DE4756225A&2D

回复:

$XA#K#OK&72

$XA#K#ERR&33

$XA#K#ERR:TS&0e 表示校验方式为SecretGroup

$XA#S#CRC_FAIL&61 校验错误