关于本文档

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

有两类通知，配置通知与OTA通知

收到配置通知

格式：$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：固件下载地址

# 设置日志等级

指令：$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#0out1:1;out2:1;out3:1;out4:1;out5:1;out6:1;out7:1;out8:1&#122#

指令：$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#SET_UPDATE_PROPS#867435053362828#0#interval:165000;updateLoc:true&#0C#

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

interval：上传间隔（ms）。最小上传间隔10000，默认165000

updataLoc：是否上传基站定位，true上传基站定位，false不上传基站定位，默认上传

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

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

回复：$XGC_ACK#SET_UPDATE_PROPS#867435053362828#0#ok&#7f#

# AT固件的OTA升级

对于AT固件来说，小机云的OTA任务是给到主机，如，主控，上位机，单片机等用来升级。

如果需要升级AT固件，则需要通过指令通知AT固件进行升级。

主机收到OTA通知，或通过指令查询OTA任务，拿到OTA任务固件的下载地址。能过下面指令通知AT固件进行升级。

格式：$XGC#DTU_OTA#SN#Timestamp#filename:文件名;fwVersion:固件版本号;url:固件下载地址&#Code#

filename：固件文件名，前缀需要与小机云硬件型号一致。名字长度需要小于32字节

fwVersion：固件版本号

url：固件下载地址，该地址需要经过url编码。（主机通过OTA指令查询或小机云通知拿到的固件下载链接，默认已经经过url编码）

指令：$XGC#DTU_OTA#867435053362828#0#filename:XGC-RG88C_V1.0.bin;fwVersion:1.0.0;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&#39#

AT固件升级完成后，主机会收到状态回复

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

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

当升级完成后，需要使用指令回复小机云升级状态。上传升级状态指令详情

升级完成后，需要发送指令重启新固件才会生效

# 发送短信

格式：$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#