水肥机(自研终控)通讯文档
目录
描述
用于水肥机自研终端控制的系统通讯协议
说明
规约
本文档所述的协议是用以东骏科技有限公司物联网服务平台和安卓型水肥终控设备的数据交互。
客服（技术）联系方式
杭州东骏科技有限公司
电话：0571-87017551
手机：13082852087
兼容性
仅适用于授权设备。
词汇表
端口：充电时使用的接口，设备可以单独控制的电力输出结构。
端口编号：端口的程序代码，和设备编号共用用以表示端口在系统中的唯一值。端口编号必须以数字顺序编码，每台机器端口编号不得跳跃，不得重用。
响应类型：上报服务端的数据响应类型。分为即时响应上报和设备主动上报。
会话ID: 由服务端生成，用以区分不同的命令数据链。
网络通讯协议
本章节内容定义安卓设备和服务器之间的通讯协议。
通讯方式
- 数据上报：string字符串
- 指令数据：定长报文
- 通讯网络协议：TCP
关于粘包
由于服务器操作系统在处理TCP通讯时，将数据包转换成流传输给应用层，在数据频率高或者并发高的情况下很容易出现粘包，单片机受内存限制将不处理粘包，所以服务器在发送数据的时候需要注意的是尽量不要以特别高的频率向单片机发送数据，单片机如果接收到数据有粘包则只能处理前面一包的数据，后面的数据将会被丢弃，服务器可以通过重发机制避免粘包对业务产生影响，同时在很偶尔的情况下服务器发送数据可能出现分包(虽然现在大部分服务器发送慢充这样的数据不会出现分包)，如果大量出现分包，请调整服务器网络参数设置，如果同一条数据被分包发送间隔大于2s将被单片机将在接收到后面的数据之前就认为前面的数据是非法的。同时因为服务器内存资源充足，建议服务器尽量对接收数据进行粘包处理。
协议结构
命令结构
定义：服务器发送，通讯模块接收的数据报文。
| 1 | 2 | 3 | 4 | 5 | 6 | 7 |
1：开始标识（1byte） “_”
2：报文长度（3byte）（ASCII数字）
3：命令（3byte）（英文大写，第一字节A为保留字段）
4：会话ID（6byte）（每一字节0x00-0x3D之间数字+偏移量0x31，当然如果使用A-Za-z0-9就一定再这个范围之内了，也就满足要求了），每次不同的通讯的会话ID都需要不一样（服务器发起的通讯至少连续的20次通讯不一样，除了特殊说明以外，当然我们的建议还是让每次通讯的会话ID尽可能的不一样），通常设备会在获取到服务器指令执行以后需要回复结果的会返回相同的会话ID给服务器，服务端可以通过会话ID获得设备当前回应的数据是哪一个会话的。同一个会话ID设备会认为是同一次通讯的重复发送，如果设备已经处理了相关的指令，就会丢弃之后相同会话ID的指令。设备由于内存限制，比对的会话ID是之前10次通讯的会话ID，为了可靠期间服务端只要保证连续的20次服务器发起的通讯会话ID不一致就可以了确保设备不会触发丢弃操作而影响指令的执行。另外如果有些命令服务器为了使设备一定收到，但设备只需要执行一次的，这样的命令多次发送用同一会话ID发送就可以了
5：分隔符（1byte） “/”
6：参数（如果没有参数则没有该部分）
7：结束标识(2byte) (0x0D 0x0A)
响应结构
定义：服务器发送，设备接收的报文。
| 1 | 2 | 3 | 4 | 5 | 6 | 7 |
1：开始标识（1byte） “_”
2：响应类型（2byte） PG-ping，DV-设备号(IMEI)，ID-SIM卡ICCID号，CM-客户端命令，RP-数据上报，RS-命令响应， RJ-Json数据上报
3：命令（3byte）（大写英文，回传服务器请求的命令，如果没有服务器请求则为AAA）
4：会话ID（6byte）（无服务器会话ID则返回”000000”，文档中指令的会话ID有特殊定义的，已定义为准）
5：内容长度（3byte）（ASCII数字）6的长度
6：内容(内容长度可以为空)
7：结束标识(2byte) (0x0D 0x0A)
命令限制
- ADV(设备号IMEI号) AID(SIM卡ICCID号) AXT(心跳) AAA(空指令) 为系统内置命令不能用于其他接口
- 业务级别的接口命令不得用 A 开头
修订记录
2023年05月08日
创建文档
业务协议
设备基本参数同步
设备基本信息参数上报
| 发送方 | 设备 |
| 说明 | 设备向服务器上报设备基本信息 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RP |
| 命令 | 3byte，SBP |
| 会话ID | 6byte，A31001 |
| 内容长度 | 不定长 |
| 内容类型 | JSON |
| 内容 |
{
"afterSales":"售后电话",
"filterPressure":"过滤器压差",
"barrelNumber":"肥料桶数量(工厂模式混配系统数量)",
"barrelCapacity":"桶容量",
"barrelDiameter":"桶直径",
"storeFertilizerMax":"单桶储肥量最大值",
"levelSensorBlindZone":"液位计盲区值",
"bucketTachometerRadius":"桶流速计半径",
"pipelineTachometerRadius":"总肥管流速计半径",
"audioStatus":"语音播报启用状态",
"irrigationNum":"单轮灌溉区块数",
"valveDefault":"高频阀默认工作值",
"devicePhoto":"设备照片",
"getWater":"工厂模式取水系统数量",
"filter":"工厂模式过滤系统数量",
"fertilization":"工厂模式注肥系统数量",
"irrigation":"工厂模式输出灌溉系统数量",
"sensor":"工厂模式外围传感系统数量",
"auxiliary":"工厂模式辅助控制系统数量"
}
|
| 内容说明 |
audioStatus：语音播报启用状态，0-关闭，1-开启 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
设备基本信息参数上报响应
| 发送方 | 服务器 |
| 说明 | 服务器响应设备上报结果 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RS |
| 命令 | 3byte，SBP |
| 内容长度 | 1byte |
| 内容 |
S-成功 F-失败 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
设备基本信息参数下发
| 发送方 | 服务器 |
| 说明 | 服务器向设备下发设备基本信息参数 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，send |
| 命令 | 3byte，EBI |
| 内容长度 | 不定长 |
| 内容类型 | JSON，base64 |
| 内容 |
{
"deviceName":"设备名称",
"afterSales":"售后电话",
"filterPressure":"过滤器压差",
"barrelCapacity":"桶容量",
"barrelDiameter":"桶直径",
"storeFertilizerMax":"单桶储肥量最大值",
"levelSensorBlindZone":"液位计盲区值",
"bucketTachometerRadius":"桶流速计半径",
"pipelineTachometerRadius":"总肥管流速计半径",
"audioStatus":"语音播报启用状态",
"irrigationNum":"单轮开启电磁阀数",
"valveDefault":"高频阀默认工作值",
"devicePhoto":"设备照片"
}
|
| 内容 |
status：设备停启用状态，Y-启用，N-停用 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
设备区块信息同步
区块信息请求
| 发送方 | 设备 |
| 说明 | 设备向服务器请求区块信息 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RP |
| 命令 | 3byte，SBI |
| 会话ID | 6byte，A31002 |
| 内容长度 | 3byte |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
区块信息下发
| 发送方 | 服务器 |
| 说明 | 服务器向设备下发区块信息 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，send |
| 命令 | 3byte，SBI |
| 内容长度 | 不定长 |
| 内容类型 | JSON，base64 |
| 内容 |
{
"name": "设备名称",
"status": "设备停启用状态",
"block": [{
"name": "区块名",
"cd": "区块编号",
"area": "区块面积",
"solenoid": [{
"id": "电池阀id",
"name": "电池阀名称",
"cd": "电磁阀编号(地址)",
"area": "管理面积"
}]
}]
}
|
| 内容 |
status：设备停启用状态，Y-启用，N-停用 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
账号登录
请求验证码
| 发送方 | 设备 |
| 说明 | 设备向服务器上报请求验证码 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RP |
| 命令 | 3byte，VCS |
| 会话ID | 6byte，A31003 |
| 内容长度 | 11byte |
| 内容类型 | long |
| 内容 | 手机号 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
获取验证码响应
| 发送方 | 服务器 |
| 说明 | 服务器返回设备请求结果 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RS |
| 命令 | 3byte，VCS |
| 内容长度 | 1byte |
| 内容 |
0-发送失败 1-发送成功 2-设备未录入平台 3-手机号码不存在 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
设备上报登录请求
| 发送方 | 设备 |
| 说明 | 设备向服务器上报登录信息 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RP |
| 命令 | 3byte，ELG |
| 会话ID | 6byte，A31004 |
| 内容长度 | 不定长 |
| 内容类型 | JSON |
| 内容 |
{
"type":"密码/验证码",
"username":"手机号",
"password":"密码/验证码"
}
|
| 内容说明 |
type：密码-password，验证码-code username：手机号 password：type=password时为密码，type=code时为验证码 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
登录结果反馈
| 发送方 | 服务器 |
| 说明 | 服务器返回设备登录结果 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RS |
| 命令 | 3byte，ELG |
| 分隔符 | #/# |
| 内容 |
登录成功：S#/#token token有效期15天 登录失败：F#/#错误码 1-设备不存在 2-用户不存在/停用 3-验证码/密码错误 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
下发操作
下发单次操作
| 发送方 | 服务器 |
| 说明 | 服务器向设备下发单个元器件操作信息 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，send |
| 命令 | 3byte，SCO |
| 内容长度 | 不定长 |
| 内容类型 | JSON，base64 |
| 内容 |
{
"token": "用户token",
"type": "操作模式",
"operation": {
"操作内容"
}
}
|
| 内容说明 |
token：用户token type：操作模式，1-自动模式灌水，2-自动模式自定义施肥，3-手动模式，4-清洗模式，5-储水模式，6-自动模式模板施肥 operation：操作内容 手动模式： "blockCd": "区块编号", "index": "索引", "status": "状态" index：1-注水泵，2/3/4/5/6/7-进水阀，8/9/10/11/12/13-搅拌机，14/15/46/17/18/19-排水阀，20-注肥泵，21/22/23/24/25/26-高频阀 清洗模式： "index": "清洗部件", "time": "清洗时长(分钟)", "status": "状态" index：清洗部件,多个部件逗号分隔，2-过滤器，31-36-桶 status：0-结束，1-启动 储水模式： "index": "桶索引", "storeWater":"储水量", "startTime":"开始时间", "status": "状态" index：清洗部件,多个部件逗号分隔 startTime:开始时间，格式：yyyy-MM-dd HH:mm:ss，可以为空，为空则表示立即开始 status：0-结束，1-启动，2-暂停，3重启 自动模式灌水： "type": "工作方式", "blockCd": "区块编号", "singleNumber":"单轮数量", "param":"参数值", "cropType":"作物种类", "startTime":"开始时间，yyyy-MM-dd HH:mm:ss", "status": "状态" type：工作方式,1-用量，2-时间 param：参数值，工作方式为用量-每亩用量，工作方式为时间-单轮时长(单位：分) blockCd：区块编号,多个区块逗号分隔 cropType：作物种类，可以为空,base64加密 startTime:开始时间，格式：yyyy-MM-dd HH:mm:ss，可以为空，为空则表示立即开始 status：0-结束，1-启动，2-暂停，3-重启，4-取消 自动模式自定义施肥： "type": "施肥类型", "cropType": "作物种类", "singleNumber": "单轮数量", "blockCd": "区块编号", "status": "状态", "params": ["number#fertilizerName#fertilizerAmount#dilutionRatioFertilizer#dilutionRatioWater"] type：施肥类型,1-单肥，2-多肥 cropType：作物种类,base64加密 singleNumber：单轮数量 blockCd：区块编号,多个区块逗号分隔 status：0-结束，1-启动，2-暂停，3-重启，4-取消 params：灌溉信息 number：桶编号 fertilizerName：肥料名称,base64加密 fertilizerAmount：亩用肥量 dilutionRatioFertilizer：稀释比例-肥 dilutionRatioWater：稀释比例-水 自动模式模板施肥： "templateName": "模板名称", "type": "施肥类型", "cropType": "作物种类", "singleNumber": "单轮数量", "blockCd": "区块编号", "status": "状态", "params": ["number#fertilizerName#fertilizerAmount#dilutionRatioFertilizer#dilutionRatioWater"] templateName：模板名称,base64加密 type：施肥类型,1-单肥，2-多肥 cropType：作物种类,base64加密 singleNumber：单轮数量 blockCd：区块编号,多个区块逗号分隔 status：0-结束，1-启动，2-暂停，3-重启，4-取消 params：灌溉信息 number：桶编号 fertilizerName：肥料名称,base64加密 fertilizerAmount：亩用肥量 dilutionRatioFertilizer：稀释比例-肥 dilutionRatioWater：稀释比例-水 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
上报单次操作
| 发送方 | 设备 |
| 说明 | 设备向服务器上报单次操作 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RP |
| 命令 | 3byte，SCI |
| 会话ID | 6byte，A31005 |
| 内容长度 | 不定长 |
| 内容类型 | JSON，base64 |
| 内容 |
{
"token": "用户token",
"type": "操作模式",
"result": "操作结果",
"msg": "结果描述",
"operation": {
"操作内容"
}
}
|
| 内容说明 |
token：用户token type：操作模式，1-自动模式灌水，2-自动模式自定义施肥，3-手动模式，4-清洗模式，5-储水模式，6-自动模式模板施肥 result：操作结果，0-成功，1-失败，2-超时，3-部分超时，4-区块编号不存在，5-阀门未开启 msg：结果描述（base64，不做处理，仅供安卓查看日志用） operation：操作内容 手动模式： "blockCd": "区块编号", "index": "索引", "status": "状态" status：0-关闭，1-开启 index：1-注水泵，2/3/4/5/6/7-进水阀，8/9/10/11/12/13-搅拌机，14/15/46/17/18/19-排水阀，20-注肥泵，21/22/23/24/25/26-高频阀 清洗模式： "index": "2,31,32", "time": "清洗时长(分钟)", "status": "状态" index：清洗部件，多个部件逗号分隔，2-过滤器，31-36-桶 status：0-结束，1-启动 储水模式： "index": "1,2,3", "storeWater":"储水量", "startTime":"开始时间", "status": "状态" index：桶索引，多个部件逗号分隔 startTime:开始时间，格式：yyyy-MM-dd HH:mm:ss，可以为空，为空则表示立即开始 status：0-结束，1-启动，2-暂停，3-暂停恢复 自动模式灌水： "type": "工作方式", "singleNumber":"单轮数量", "blockCd":"区块编号", "param":"参数值", "cropType":"作物种类", "startTime":"开始时间，yyyy-MM-dd HH:mm:ss", "status": "状态", "solenoidValve": ["电磁阀地址"] type：工作方式,1-用量，2-时间 singleNumber：单轮数量 blockCd：需灌溉区块编号,多个区块逗号分隔 param：参数值，工作方式为用量-每亩用量，工作方式为时间-单轮时长(单位：分) cropType：作物种类，可以为空,base64加密 startTime:开始时间，格式：yyyy-MM-dd HH:mm:ss，可以为空，为空则表示立即开始 status：0-结束，1-启动，2-暂停，3-重启，4-取消 solenoidValve：当前开启的电磁阀地址 自动模式自定义施肥： "templateName": "模板名称", "type": "施肥类型", "cropType": "作物种类", "singleNumber": "单轮数量", "blockCd": "区块编号", "status": "状态",, "solenoidValve": ["电磁阀地址"] "params": ["number#fertilizerName#fertilizerAmount#dilutionRatioFertilizer#dilutionRatioWater"] templateName：模板名称,base64加密 type：施肥类型,1-单肥，2-多肥 cropType：作物种类,base64加密 singleNumber：单轮数量 blockCd：需灌溉区块编号,多个区块逗号分隔 status：0-结束，1-启动，2-暂停，3-重启，4-取消 solenoidValve：当前开启的电磁阀地址 params：灌溉信息 number：桶编号 fertilizerName：肥料名称,base64加密 fertilizerAmount：亩用肥量 dilutionRatioFertilizer：稀释比例-肥 dilutionRatioWater：稀释比例-水 自动模式模板施肥： "templateName": "模板名称", "type": "施肥类型", "cropType": "作物种类", "singleNumber": "单轮数量", "blockCd": "区块编号", "status": "状态", "solenoidValve": ["电磁阀地址"] "params": ["number#fertilizerName#fertilizerAmount#dilutionRatioFertilizer#dilutionRatioWater"] templateName：模板名称,base64加密 type：施肥类型,1-单肥，2-多肥 cropType：作物种类,base64加密 singleNumber：单轮数量 blockCd：需灌溉区块编号,多个区块逗号分隔 status：0-结束，1-启动，2-暂停，3-重启，4-取消 solenoidValve：当前开启的电磁阀地址 params：灌溉信息 number：桶编号 fertilizerName：肥料名称,base64加密 fertilizerAmount：亩用肥量 dilutionRatioFertilizer：稀释比例-肥 dilutionRatioWater：稀释比例-水 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
单次操作响应
| 发送方 | 服务器 |
| 说明 | 服务器返回设备单个元器件信息上报结果 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RS |
| 命令 | 3byte，SCI |
| 内容长度 | 1byte |
| 内容 |
0-成功 1-其他异常 2-token过期 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
运行中途通知
运行中途通知
| 发送方 | 设备 |
| 说明 | 设备运行启动和完成后，上报服务端，运行过程中每1分钟上报一次，连续1小时没有上报服务端可以结束本次运行 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RP |
| 命令 | 3byte，UMN |
| 会话ID | 6byte，A31006 |
| 内容长度 | 不定长 |
| 内容类型 | JSON |
| 内容 |
{
"cd": "20220803170003952967494",
"operationType":"3",
"status":"1",
"runTime": "21654",
"totalTime": "40000",
"startTime": "2023-05-31 00:00:00",
"endTime": "2023-05-31 20:00:00",
"expectTime": "2023-05-31 19:00:00",
"waterAmount": "52.1",
"fertilizerAmount": "182.1",
"ph": "7",
"ec": "300",
"instantFlowRate": "300",
"totalFlowRate": "300",
"tachometer": ["1#300", "2#300", "3#300"],
"mainPipelinePressure": "300",
"fertilizerPumpPressure": "300",
"waterPumpPressure": "300",
"storeWater": "50",
"totalStoreWater": "300",
"pressureDifference": "300",
"component": ["1#1", "2#1"],
"block": ["1#1#25", "1#1#25"],
"solenoidValve": ["A23B3456", "3D4E2A24"]
}
|
| 内容说明 |
cd: 运行编号，注意：编号仅在结束时上报一次 operationType：操作模式，1-自动模式灌水，2-自动模式自定义施肥，3-手动模式，4-清洗模式，5-储水模式，6-自动模式模板施肥 status：运行状态，1-运行中，2-暂停中，3-预约中，4-完成 runTime：已运行时长，单位：秒 totalTime：总运行时长，剩余时长 = 总运行时长 - 已运行时长 startTime: 开始时间（yyyy-MM-dd HH:mm:ss） endTime: 结束时间（yyyy-MM-dd HH:mm:ss） expectTime：预计完成时间（yyyy-MM-dd HH:mm:ss） waterAmount：用水量(L) fertilizerAmount：用肥量(L) ph：溶液PH值 ec：溶液EC值(us/s) instantFlowRate：瞬时流量(L/S) totalFlowRate：总流量 tachometer：桶编号#流速(cm/s) mainPipelinePressure：主管道压力(Pa) fertilizerPumpPressure：注肥泵压力(Pa) waterPumpPressure：注水泵压力(Pa) storeWater：当前储水量 totalStoreWater：总储水量，剩余储水量 = 总储水量 - 当前储水量 pressureDifference：过滤器压差
index：索引(手动模式时为开关索引，清洗模式为部件索引，储水模式为桶索引) status：状态，0-关闭/未选择，1-开启/选中
cd：区块编号 status：状态，0-未选中，1-选中 humidity：土壤湿度(rh%)
|
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
设备异常上报（待定）
故障上报响应
| 发送方 | 设备 |
| 说明 | 设备向服务器上报设备异常 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RP |
| 命令 | 3byte，DEI |
| 会话ID | 6byte，A31007 |
| 分隔符 | 3byte，"#/#" |
| 内容 |
故障码#/#故障描述 故障码： 0-未知故障 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
异常上报响应
| 发送方 | 服务器 |
| 说明 | 服务器返回设备异常上报结果 |
| 开始标志 | 1byte，“_” |
| 响应类型 | 2byte，RS |
| 命令 | 3byte，DEI |
| 内容长度 | 1byte |
| 内容 |
S-成功 F-失败 |
| 结束标志 | 2byte，\r\n（0x0D 0x0A） |
