文本协议
# 协议格式
$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结束
# 协议回复格式
$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:设置switch组件为1,
$X#D#switch:1&21示例1.1:1后面多一个分号也是允许的
$X#D#switch:1;&1A示例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#S#CRC_FAIL&61校验错误
# 发送图表数据
作用:设备向手机发送图表/曲线数据。数据支持两种模式:全量替换(覆盖整个图表)和追加模式(追加到已有数据末尾)。追加模式下,数据会按
keyName定位已有数据的末尾位置进行合并。补充说明:根据图表的要求,一组数据要有key,value,timestamp。
CMD:C
格式:
$X#C#<functionBit>,<keyName>,<value1>,<timestamp1>,<value2>,<timestamp2>,...&<xor>\r\n
参数 说明 <functionBit>操作标识: A= 追加模式,N= 全量替换<keyName>数据键名,如 temperature、humidity、pressure<valueN>数据值(整数) <timestampN>13位时间戳(整数,Unix毫秒时间戳) 注:
<value>和<timestamp>必须成对出现,数量为偶数,否则最后一对会被丢弃。示例一:全量替换 — 初始化温度曲线数据(3个数据点)
$X#C#N,temperature,25,1700000000,26,1700000010,27,1700000020&3A回复:
$XA#C#OK&<xor>示例二:追加模式 — 追加2个温度数据点
$X#C#A,temperature,28,1700000030,29,1700000040&1F回复:
$XA#C#OK&<xor>示例三:追加模式 — 追加另一条曲线数据
前提:已有图表数据 temperature,25,1700000000,发送湿度数据与之合并:
建议:
humidity应上传和temperature同样时间戳的数据,他们在曲线上就会对齐
$X#C#A,humidity,60,1700000000,65,1700000010&<xor>回复:
$XA#C#OK&<xor>
小机云