关于本文档

​ 本文档的协议是小机云硬件与外部控制器的通讯协议，用于控制小机云硬件（如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#

{ 
	"switch1": true
}

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

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

{ 
	"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#