小机云

协议定义 ​

本文档的协议提供给硬件快捷使用小机云服务功能，与小机云的http接口功能基本一致

# 协议格式 ​

$XGC#Cmd#SN#Timestamp#Content&#CheckCode#\r\n

$ 符号：协议开始符号

&# 符号：内容分割符

\r\n 符号：协议结束符，十六进制0x0A 0x0D，可以是\r\n

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

  • $XGC：协议固定开头
  • Cmd：协议功能，如Cmd为DATA为上传数据，Cmd为OTA为上传OTA状态
  • SN：设备唯一编码，需要与控制台中录入的设备SN保持项目中唯一
  • Timestamp：协议生成时间，13位UTC格式，不用可填0，系统会自动填入接收到的时间
  • Content：协议数据，数据格式见协议详情，注意数据中不可以出现#号。如果没有内容可以不需要该字段。
  • CheckCode：校验码，&#前所有字符进行异或得到 1 个字节的十六进制数，以2 个ASCII 字符形式输出。如以下协议：$XGC#Cmd#SN#Timestamp#Content&#CheckCode#\r\n &#之前部分异或得到校验码为0x28，则CheckCode位填28

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

指令类型：

通知指令：带有通知描述指令，为设备或平台主动发送的通知。

操作指令：带“查询/通知”描述的指令，从机可主动查询，或当相关状态变化时主机或平台主动发起通知

# 协议回复格式 ​

$XGC_ACK#Cmd#SN#Timestamp#Content&#CheckCode#\r\n

如果无特殊说明，指令统一回复：

成功：$XGC_ACK#Cmd#SN#Timestamp#OK&#CheckCode#

失败：$XGC_ACK#Cmd#SN#Timestamp#ERR:message&#CheckCode#

#上传数据-KV格式 ​

格式：$XGC#DATA#SerialNo#Timestamp#key1:data1;key2:data2&#CheckCode#\r\n

注意：只支持上传key:value格式数据，字符串内容需要加""，数组格式内容需要加[]，bool内容支持0和1表示

可以设置一个数组也可以同时设置多组数据

示例一：$XGC#DATA#123456#0#value:32;enabled:false;msg:"ok";items:["a","b","a"];numbers:[1,2,3]&#6A#

回复：$XGC_ACK#DATA#123456#1692263526373#OK&#40#

示例二：$XGC#DATA#switch:1&#71#

# 查询最新一条数据 ​

格式：$XGC#GET_LAST_DATA#SerialNo#Timestamp&#CheckCode#\r\n

示例：$XGC#GET_LAST_DATA#123456#0&#20#

回复：$XGC_ACK#GET_LAST_DATA#123456#1692263213303#noData&#2F#

回复：$XGC_ACK#GET_LAST_DATA#1231#1692263605101#msg:ok;value:32;enabled:false;timestamp:1692263526273&#7D#

# 查询设备TAGS ​

格式：$XGC#GET_TAGS#SerialNo#Timestamp&#CheckCode#\r\n

示例：$XGC#GET_TAGS#123456#0&#64#

回复：$XGC_ACK#GET_TAGS#123456#1679995315528#A,BB&#38#

回复：$XGC_ACK#GET_TAGS#1231#1692265017707#tagsNotFound&#5E#

#上传设备属性 ​

格式：$XGC#SET_PROPS#SerialNo#Timestamp#capacity:value;rssi:value;longititu:value;lagtitude:value&#CheckCode#\r\n

描述：用于设置设备属性，如电量，信号，位置，以及自定义属性。

其中电量，信号，位置这三个属性将会在地图上显示。最多可定义32个属性

字符串的值需要加""

示例一：更新电量

$XGC#SET_PROPS#123456#0#capacity:11&#32#

示例二：更新电量，信号，经度，纬度

$XGC#SET_PROPS#123456#0#capacity:10;rssi:30;longitude:113.391845;latitude:25.365365&#6F#

经度和纬度值保留到小数点后六位，注意，经度和纬度数值必须同时存在

示例一：更新电量和自定义属性，字符串的值需要加""

$XGC#SET_PROPS#123456#0#capacity:82;temperature:56;aa:"bb";cc:"dd";ee:"ff"&#57#

回复：$XGC_ACK#SET_PROPS#123456#1680071835177#OK&#08#

# 查询设备属性 ​

格式：$XGC#GET_PROPS#SerialNo#Timestamp&#CheckCode#\r\n

示例：$XGC#GET_PROPS#123456&#0#0D#

回复：$XGC_ACK#GET_PROPS#123456#1679994827900#rssi:22;longitude:116.40154828045652;latitude:39.90310373211554;capacity:18&#69#

回复：$XGC_ACK#GET_PROPS#1231#1692265017707#propsNottFound&#0A#

# 删除设备属性 ​

格式：$XGC#DEL_PROP#SerialNo#Timestamp#key1,key2&#CheckCode#\r\n

示例：$XGC#DEL_PROP#123456#0#rssi,aa&#77#

回复：$XGC_ACK#DEL_PROP#123456#1680073820673#OK&#51#

# 查询远程升级（OTA） ​

格式：$XGC#GET_OTA#SerialNo#Timestamp#isHttpsUrl:false;isEncode:true&#CheckCode#\r\n

参数：

isHttpsUrl：可选，是否返回https链接，可选值true/false。false或去掉该参数则返回http链接

isEncode：可选，下载地址是否经过url编码。该指令默认返回的url已经过url编码

示例：$XGC#GET_OTA#123456#0&#3F#

回复：

未找到OTA任务：$XGC_ACK#GET_OTA#1231#1692273102836#otaNotFound&#71#

找到OTA任务，下载链接经过url编码：$XGC_ACK#GET_OTA#123456#1679994375469#fwVersion:1;filename:ota.bin;md5:b8f752928c4ed3931bcae18d2df02bd4;url:http%3A%2F%2Ffiles.xsgee.com%2Fdevice-center-dev%2Fproject%2F10118e22fa5dd3f10ca2%2Fota%2F1640005786251366402%2Fhosts%3FExpires%3D1679997970%26OSSAccessKeyId%3DLTAI4gDKwEZaW2PGxNSFSignature%3DiF70T1bVKWmlYb54wiGBuFIBo%253D%26%2370%23&#78#

#上传远程升级（OTA）状态 ​

格式：$XGC#OTA_STATE#SerialNo#Timestamp#stage:finish;swVersion:1.0&#CheckCode#\r\n

state: 执行状态

  • finish：配置完成，需要带上OTA任务的swVersion

  • failed：配置失败，无需带上swVersion

  • downloading：正在下载

  • upgrading：正在升级

    状态说明：状态说明

示例：

$XGC#OTA_STATE#123456#0#stage:finish;swVersion:1&#09#

$XGC#OTA_STATE#123456#0#stage:failed&#77#

回复：

配置成功：

$XGC_ACK#OTA_STATE#123456#1680075126979#OK&#00#

上传finish状态，上传的swVersion与OTA任务的swVersion不一致：

$XGC_ACK#OTA_STATE#123456#1692275671777#ERR:software version is not expected&#7B#

# 查询设备配置 ​

格式：$XGC#GET_CONFIG#SerialNo#Timestamp&#CheckCode#\r\n

示例：$XGC#GET_CONFIG#123456&#0#5A#

回复：

未找到配置任务

$XGC_ACK#GET_CONFIG#1231#1692265017707#configNotFound&#5E#

$XGC_ACK#GET_CONFIG#1231#1692270217631#configVersion:230817190334;max:40;min:20&#24#

#上传设备配置状态 ​

格式：$XGC#CONFIG_STATE#SerialNo#Timestamp#stage:finish;configVersion:230329001&#CheckCode#\r\n

state: 执行状态

  • finish：配置完成，需要带上收到的配置configVersion
  • failed：配置失败，无需带上configVersion

示例：

$XGC#CONFIG_STATE#123456#0#stage:finish;configVersion:230324180246&#4D#

$XGC#CONFIG_STATE#123456#0#stage:failed&#01#

回复：

$XGC_ACK#CONFIG_STATE#123456#1680057814047#OK&#7A#

$XGC_ACK#CONFIG_STATE#123456#1692276082697#ERR:version of config is not expected&#01#

#上传日志 ​

格式：$XGC#PUSH_LOG#SerialNo#Timestamp#log_content@level@code&#CheckCode#\r\n

log_content：日志内容，必填，不可包含，"$"，"#"，"&#"，"@"

level：日志等级，非必填，info（默认），warning，error，三个等级

code：错误码，非必填

示例一：$XGC#PUSH_LOG#123456#0#device boot ok. temperature sensor:ok. g-sensor: ok@info@200&#5A#

示例二：$XGC#PUSH_LOG#123#0#设备开机成功，温度传感器：正常，重力传感器：正常&#4D#

回复示例：$XGC_ACK#PUSH_LOG#123456#1680017055067#OK&#50#

# 查询平台时间 ​

格式：$XGC#NOW#SerialNo#Timestamp#format:timestamp&#CheckCode#\r\n

format: 可选，date或timestamp，默认timestamp

示例：$XGC#NOW#123456#0#format:timestamp&#4E#

回复：$XGC_ACK#NOW#123456#1692262196515#timestamp:1692262196515&#6B#

回复：$XGC_ACK#NOW#1231#1692262679844#year:2023;month:8;day:17;hour:16;minute:57;second:59;millis:844&#36#