Skip to content

关于本文档

​ 本文档的协议是小机云硬件与外部控制器的通讯协议,用于控制小机云硬件(如DTU等)

​ 从机可通过小机云硬件通讯口(如串口)向小机云发送《小机云文本协议》使用小机云功能,如上传数据

​ 小机云平台的通知指令,也会通过设备发送到从机

名词定义:

​ 硬件结构:以下协议的使用硬件结构为,由上位机(电脑,单片机等嵌入式设备)做主控,向小机云的硬件(DTU或RTU等)发送消息,控制小机云硬件

​ 平台:指点云服务平台

​ 主机:上位机,电脑,单片机等嵌入式设备

​ 从机:小机云硬件(DTU或RTU等)

关于通知:

​ 带有通知描述指令,为设备或平台主动发送的通知。带“查询/通知”描述的指令,从机可主动查询,或当相关状态变化时主机或平台主动发起通知

通讯接口:

​ 小机云硬件与主控设备连接。小机云硬件默认通讯通道顺序为:UART或RS232。如果有UART的情况下为UART,如果没有UART则默认通讯通道为RS232。如果只有RS485,则需要通过快捷指令把通讯通道切换为485。切换通讯通道指令

​ UART与RS232的默认波特率为115200,RS485的默认波特率为9600

​ 因为485协议通信协议速度慢,不建议要求高实时性的场景下使用485协议通讯

协议格式

​ 以下协议格式无特殊说明,统一格式为:$XGC#ACTION#SN#Timestamp#Content&#Code#。所有协议必须以\r\n结束

​ 具体协议说明请参考《小机云文本协议格式》

# 查询IMEI

指令:$XGC#GET_IMEI#0#0&#5A#

回复:$XGC_ACK#GET_IMEI#867435053362828#0#867435053362828&#95#

# 配置项目信息

作用:用于向固件配置小机云的项目ID与项目密钥。配置后设备将会自动连接小机云

格式:$XGC#SET_PRJINFO#SN#Timestamp#PID:小机云ProjectId;PSECRET:小机云ProjectSecret&#Code#

$XGC#SET_PRJINFO#867435053362828#0#PID:1000904556b23945fe90;PSECRET:76EDCE04DE96555E16CB34175F2B1565493A7412&#50#

回复:$XGC_ACK#SET_PRJINFO#867435053362828#0#ok&#57#

# 小机云数据通知

作用:小机云向设备发送的数据消息(如,调试页或自定义控制页发送出来的消息),小机云硬件会通过此协议主动通知到主控

格式:$XGC#DATA_PACK#SN#Timestamp#key1:value1;key2:value2&#Code#

案例一:小机云自定义页,使用了一个开关控件,该控件绑定的字段为switch1,当点击该控件,控件状态从关变为开,页面会向硬件发送如下JSON数据。小机云硬件收到后,会转换成硬件文本协议,再发送到主控

$XGC#DATA_PACK#SN#Timestamp#switch1:true;&#Code#

json
{ 
	"switch1": true
}

案例二:小机云控制台调试页向小机云硬件发送JSON格式数据时,小机云硬件收到后,会转换成硬件文本协议,再发送到主控

$XGC#DATA_PACK#SN#Timestamp#up:true;temperature:32&#Code#

json
{ 
	"up": true,
	"temperature": 32,
}

案例三:小机云控制台调试页向小机云硬件发送字符串, "abcdefg"

$XGC#DATA_PACK#SN#Timestamp#abcdefg&#Code#

# 查询/通知设备基本信息

指令:$XGC#GET_BASE_INFO##0&#48#

作用:查询设备的型号,版本,信号,电池电压,是否在充电,等基本信息

model:设备型号

version:设备版本号

rssi:信号值0~31

vbat:电池电压

vbus:充电状态

回复:XGC_ACK#GET_BASE_INFO#867435053362828#0#model:XGC-RG88C;version:1.0.0;rssi:28;vbat:3916;vbus:true&#0b#

# 查询SIM卡ICCID

指令:$XGC#GET_ICCID#867435053362828#0&#1E#

回复:$XGC_ACK#GET_ICCID#867435053362828#0#898604E0092221379975&#89#

# 查询设备网络和SIM卡状态

指令:$XGC#GET_NET_INFO##0&#48#

作用:查询设备的信号值,网络状态,网络模式,SIM卡状态

rssi:信号值0~31

netState:"INIT"表示正在初始化,"REGISTERED"表示已注册,"UNREGISTER"表示未注册

netMode:0:未注册,1:2G GSM网络,2:2.5G EDGE数据网络,3:3G TD网络,4:4G LTE网络,5:3G WCDMA网络

simStatus:true表示sim卡正常,false或者nil表示未检测到卡或者卡异常

回复:$XGC_ACK#GET_NET_INFO#867435053362828#0#rssi:30;netState:REGISTERED;netMode:4;simStatus:true&#5F#

# 查询/通知 DTU状态

作用:当小机云硬件状态发生变化,硬件发向主机发送状态通知。也可以由主机主动查询。通知与回复指令格式一致。

状态描述:

no-init:开机后的第一状态,本条消息不主动通知,下面的消息会主动通知到主机

init-ok:每次开机,系统硬件,SIM卡,网络等初始化完成

no-project-info:未配置小机云ProjectId与ProjectSecret项目信息,收到项目信息配置后会自动与小机云连接

get-mqtt-info-ok:获取小机云MQTT信息成功

get-mqtt-info-fail:获取小机云MQTT信息失败,或项目信息错误

mqtt-connected:与小机云连接成功

mqtt-disconnected:与小机云连接断开,5秒后会自动重连

指令:$XGC#GET_DTU_STATE#867435053362828#0&#17#

通知/回复:$XGC_ACK#GET_DTU_STATE#867435053362828#0#mqtt-connected&#6C#

# 通知:小机云设备配置(CONFIG)

当配置变更,由平台主动发送

格式:$XGC#NOTIFY_CONFIG#SN#Timestamp#configVersion:1693894843740;key1:value1;key2:value2&#Code#

configVersion:配置版本号

key1:自定义key1

value1:自定义key1的值

key2....等自定义的配置

配置执行完成后,需要使用指令回复小机云配置状态。上传配置状态指令详情

# 通知:远程升级(OTA)

当配置变更,由平台主动发送

格式:$XGC#NOTIFY_OTA#SN#Timestamp#configVersion:1693894843740;fwVersion:固件版本;filename:固件名;md5:固件md5;url:固件下载地址&#Code#

$XGC#NOTIFY_OTA#SN#Timestamp#fwVersion:v1.0;filename:update.bin;md5:SD9VY9H3932J0AS08310EF3;url:http%3A%2F%2Ffiles.xsgee.com%2Fdevice-center%2Fproject%2F1000904556a11945fd60%2Fota%2F1689228284937433090%2Fdtu_1_2.bin%3FExpires%3D1691581999%26OSSAccessKeyId%3DSTS.NTpTR7KAzro8BiwZPZr6fhTzn%26Signature%3DHDZ383BViHY4Qc%252FdirOLQeYThQg%253D%26security-token%3DCAIS%252FwF1q6Ft5B2yfSjIr5fFH%252BiDpp5bxa3TQE%252FGvlAPfrlKh5HRjDz2IHhLenloCeEbtPwynGFS7PgdlqdjUJBISAneYMJ86ZJT4FtI2nF4TpXng4YfgbiJREKxaXeiruKwDsz9SNTCAITPD3nPii50x5bjaDymRCbLGJaViJlhHL91N0vCGlggPtpNIRZ4o8I3LGbYMe3XUiTnmW3NFkFlyGEe4CFdkf3mnJzCt0qB1QCql7JF%252B9XLT8L6P5U2DvBWSMyo2eF6TK3F3RNL5gJCnKUM1%252FQbp2ef7oDAWQEMu0TcabSL6Kd%252FNwB0a%252B09ALUBtvX1mfp%252Bvv3DFlsOAbjc3IsagAE4ybmjZ2zeQo25r2QzwtI7Rk9I74Nj5XQ5Yq7WTxuGzlPHGVjBCntaJ8NOsyReXwzTzcAyKwwy%252Fv4ThK3KHjgrdOMuMaElIgoIZqbT%252FLSD4o9VgRfqvJk0dEV2Z%252B9xmeR%252BdcsvsEAXk%252Fml94uaAl1jv%252B3CmxGCbUFPVuFghnL1aw%253D%253D&#03#

fwVersion:固件版本

filename:固件文件名

md5:固件md5

url:固件下载地址

isXBin: 如果回复中包含isXBin,且为true,则表示该固件为小机云设备固件。小机云设备会自动升级。如果不是小机云固件,如单片机固件,单片机收到上面通知后根据自身需要执行升级流程

小机云设备升级回复:

成功:$XGC_ACK#DTU_OTA#867435053362828#0#stage:finish;fwVersion:1.0.0&#125#

失败:$XGC_ACK#DTU_OTA#867435053362828#0#stage:failed&#125#

# 设置日志等级

指令:$XGC#SET_LOG_LEVEL#867435053362828#0#LEVEL&#code#

注意:重启设备后生效

参数:

  • LEVEL:系统会打印大于该等级的日志
  • SILENT:不打印日志
  • TRACE:日志等级01
  • DEBUG:日志等级02
  • INFO:日志等级03
  • WARN:日志等级04
  • ERROR:日志等级05
  • FATAL:日志等级06

# 查询当前网络时间

指令:$XGC#GET_NOW#867435053362828#0#timestamp&#41#

$XGC_ACK#GET_NOW#867435053362828#0#1692157152787&#8#

指令:$XGC#GET_NOW#867435053362828#0#date&#3B#

$XGC_ACK#GET_NOW#867435053362828#0#year:2023;month:8;day:16;hour:11;minute:39;second:22;millis:576&#2#

# 设置GPIO

作用:设置小机云硬件的GPIO,如果IO不存在,则不返回该IO状态。其中in(x)表示小机云硬件的光耦输入检测,out(x)表示继电器io

指令:$XGC#SET_GPIO#867435053362828#0#out1:1;out2:1;out3:1;out4:1;out5:1;out6:1;out7:1;out8:1&#4f#

回复:$XGC_ACK#SET_GPIO#867435053362828#0#out1:1;out2:1;out3:1;out4:1;out5:1;out6:1;out7:1;out8:1&#91#

指令:$XGC#SET_GPIO#867435053362828#0#out1:0;out2:0;out3:0;out4:0;out5:0;out6:0;out7:0;out8:0&#4f#

回复:$XGC_ACK#SET_GPIO#867435053362828#0#out1:0;out2:0;out3:0;out4:0;out5:0;out6:0;out7:0;out8:0&#59#

# GPIO状态通知

作用:当小机云硬件GPIO有变化,小机云硬件会主动向主机发送的通知

指令:$XGC_ACK#GPIO_INT#867435053362828#0#in1:1&#70#

# 查询/通知 所有IO状态

作用:查询所有小机云硬件的GPIO状态,如果IO不存在,则不返回。开机后会主动通知所有IO状态

指令:$XGC#GET_GPIO_ALL#867435053362828#0#out1:0;out2:0;out3:0;out4:0;out5:0;out6:0;out7:0;out8:0;in1:1;in2:1;in3:1;in4:1;in5:1;in6:1;in7:1;in8:1&#4D#

# 查询基站定位

指令:$XGC#GET_LBS#867435053362828#0&#07#

回复:$XGC_ACK#GET_LBS#867435053362828#0#longitude:113.3160324;latitude:022.5571994&#122#

# 设置硬件通讯通道

作用:小机云硬件默认通讯通道顺序为:UART或RS232。如果有UART的情况下为UART,如果没有UART则默认通讯通道为RS232。如果只有RS485,需要通过快捷指令把通讯通道切换为485。因为485协议通信协议速度慢,不建议要求高实时性的场景下使用485协议通讯

指令:$XGC#SET_DTU_PIPE#867435053362828#232&#code#

参数:uart,232,485

快捷指令,用于快速设置通讯通道。

设置通讯通道为485指令:SET_DTU_PIPE#485\r\n

回复:SET_DTU_PIPE#485-ok

设置通讯通道为232指令:SET_DTU_PIPE#232\r\n

回复:SET_DTU_PIPE#232-ok

设置通讯通道为串口指令:SET_DTU_PIPE#UART\r\n

回复:SET_DTU_PIPE#uart-ok

# 查询硬件通讯通道

指令:$XGC#GET_DTU_PIPE#867435053362828#0&#4C#

回复:$XGC_ACK#GET_DTU_PIPE#867435053362828#0#485&#64#

# 485发送Modbus RTU协议

作用:使用串口或者232,通过485 Modbus RTU协议数据。固件会自动拼装数据,并自动加入CRC校验码

格式:$XGC#SEND_MBR_485#SN#Timestamp#addr:设备地址;instructions:指令值;reg:操作寄存器;value:操作值&#Code#

指令:$XGC#SEND_MBR_485#867435053362828#0#addr:01;instructions:03;reg:0000;value:0001&#33#

设备收到以上指令后会向485发送数据: 01 03 00 00 00 01 84 0A

84 0A 为 01 03 00 00 00 01 的 16 位 CRC 结果

回复:$XGC_ACK#485_RECEIVE#867435053362828#0#0103020115781B&#50#

# 485发送原始数据

作用:使用串口或者232,通过485发送数据

格式:$XGC#SEND_RAW_485#SN#Timestamp#需要发送的数据&#Code#

指令:$XGC#SEND_RAW_485#867435053362828#0#010300000001&#12#

回复:$XGC_ACK#SEND_RAW_485#867435053362828#0#ok&#3#

回复:$XGC_ACK#485_RECEIVE#867435053362828#0#303130323033&#75#

# 设置自定义参数

作用:用于给上位机,单片机等外部设备存储一些配置信息。重启后存储内容还会存在,重新烧录固件后会被清除

指令:$XGC#SAVE_KEYS#867435053362828#0#a:123;b:abc&#42#

回复:$XGC_ACK#SAVE_KEYS#867435053362828#0#ok&#56#

# 查询自定义参数

指令:$XGC#GET_KEYS#867435053362828#0#key1,key2&#52#

回复:$XGC_ACK#GET_KEYS#867435053362828#0#key1:value1;key2:value2&#50#

只返回存在key

# 设置本地参数

设置指令:$XGC_ACK#GET_LOCAL_CONFIG#867435053362828#0#dtuPipe:232;interval:165000;xBootUpdate:true;transparent:false;&#62# 查询指令:$XGC#GET_LOCAL_CONFIG#867435053362828#0&#42#

作用:设备会自动上传设备属性(信号,电量,充电状态,基站定位,iccid)到小机云,可以通过该指令配置上传参数

下面参数可以进行单独设置,也可以单独获取

interval:上传间隔(ms)。最小上传间隔10000,默认165000

updateLoc:是否上传基站定位,true上传基站定位,false不上传基站定位,默认上传

xBootUpdate:开机查询OTA参数,如果是小机云固件则自动升级小机云设备,如果不是小机云设备则会发送串口通知

transparent:是否开启透传,默认false。任何数据都会上传到小机云。如果是JSON格式,则会存到数据库同时存到日志中去,应用界面会做相应的响应。如果是文本,则会在设备日志中显示。

handleIoData:处理下发到设备的IO数据,默认false。如果把DTU的该参数为true,当给DTU下发数据{io1: 1},则DTU会把io1设为1

uploadInt: 是否上传IO中断数据,默认false。

upIntRever: 是否上传IO中断时反向,高上传0,低上传1。

uploadIo: 是否上传IO(非中断的IO)变化,默认false。

upIoRever: 是否上传IO(非中断的IO)时反向,高上传0,低上传1。

bootUpload:开机上传数据,默认false。当该选项为true,设备联网成功后3秒会执行自动读(如果已配置自动读),并上传IO状态。如果上传失败,30秒后自动重试

bootLoad: 开机加载数据库最后一条数据,并会执行相应的操作。如数据库out1为0,则会把out1拉低

$XGC#SET_LOCAL_CONFIG#867435053362828#0#interval:30000;updateLoc:false&#56#

$XGC#SET_LOCAL_CONFIG#867435053362828#0#interval:60000;updateLoc:true&#38#

回复:$XGC_ACK#SET_LOCAL_CONFIG#867435053362828#0#ok&#7f#

# IO表操作

用于设备小机云硬件的IO,如指定硬件的IO为普通IO,中断,PWM 设置指令:$XGC_ACK#GET_LOCAL_CONFIG#867435053362828#0#dtuPipe:232;interval:165000;xBootUpdate:true;transparent:false;&#62#

增加IO(add):$XGC#IO_TABLE#869701071931474#0#action:add;out1:18,0;in1:19,1;pwm1:27,10000,50;&#08# 回复:$XGC_ACK#IO_TABLE#869701071931474#0#ok&#66#

格式:引脚名加编号,如in1。前缀可选in(中断脚),out(普通io脚),pwm(pwm输出脚)

in1:19,1,in1表示设为中断io,名为in1。GPIO引脚19。1为上拉,0下拉,3为高阻态

out1:18,0,out1表示设为普通io,名为out1。GPIO引脚18。0为初始电平

pwm1:5,10000,50,pwm1表示设为pwm输出,名为pwm1。GPIO引脚5。10000设置频率为10khz。初始化高电平比为50%,或选1~100。目前该软件下的Air724模块仅支持第5脚输出PWM,频率范围:763HZ--1.39MHZ

count1:28,1,count1表示设为计数IO,名为count1。GPIO引脚28。1为上拉,0下拉,3为高阻态

查询指令(list):$XGC#IO_TABLE#869701071931474#0#action:list;&#69# 回复:$XGC_ACK#IO_TABLE#869701071931474#0#out3:10,0;out7:14,0;in4:27,1;out2:11,0;out1:4,0;in7:25,1;out5:9,0;in2:17,1;in6:24,1;in1:7,1;in8:26,1;out8:15,0;in5:28,1;out6:19,0;in3:18,1;out4:12,0;&#56#

IO描述请看增加IO指令

清除所有IO(clear):$XGC#IO_TABLE#869701071931474#0#action:clear;&#12#

# 发送短信

格式:$XGC#SEND_SMS#SN#Timestamp#PHONE:手机号;CONTENT:短信内容&#Code#

注意:需要SIM卡支持发送短信功能

指令:$XGC#SEND_SMS#867435053362828#0#PHONE:188xxxxxx;CONTENT:abc&#01#

# DTU重启

指令:$XGC#DTU_REBOOT#867435053362828#0&#48#

回复:$XGC_ACK#DTU_REBOOT#867435053362828#0#&#125#

有可能会收到不回复

# 发送AT指令

//注意,会一直监听指令回复,需要手动关闭

指令:$XGC#AT#867435053362828#0#AT+CSQ&#1A#

//关闭指令回调

指令:$XGC#AT#867435053362828#0#AT+RIL=0&#01#

//打开指令回调

指令:$XGC#AT#867435053362828#0#AT+RIL=1&#00#