快充设备通讯文档-服务接口
描述
规约
本文档所述的协议是用以东骏科技有限公司物联网服务平台和快充投币设备的数据交互。
客服(技术)联系方式
杭州东骏科技有限公司
电话: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 开头
业务协议
端口查询
服务端查询可用端口
发送方 | 服务器 |
说明 | 服务端查询设备可用端口 |
开始标志 | 1byte,“_” |
报文长度 | 3byte,表示整个报文的总长度,ASCII数字表示 |
命令 | 3byte,CXD |
会话ID | 6byte,服务器生成 |
分隔符 | 1byte,“/” |
参数 | 端口号(1byte 0-全部端口,1-1号端口,2-2号端口) |
结束标志 | 2byte,\r\n(0x0D 0x0A) |
示例:
_ 017 CXD 123456 / 1 <0x0D> <0x0A>
状态查询响应
发送方 | 通信模块 |
说明 | 设备收到服务器查询命令时,返回端口状态 |
开始标志 | 1byte,“_” |
响应类型 | 2byte,RS |
命令 | 3byte,CXD |
会话ID | 6byte,服务端下发 |
内容长度 | 3byte,表示内容长度,ASCII数字表示 |
内容 | 端口(1byte 1-1号端口,2-2号端口)
分隔符:/ 端口状态(1byte 0-不可用,1-可用) (端口分隔符:#) |
结束标志 | 2byte,\r\n(0x0D 0x0A) |
示例:
_ RS CXD 123456 003 1 / 1 <0x0D> <0x0A>
_ RS CXD 123456 007 1 / 1 # 2 / 0 <0x0D> <0x0A>
第三方支付充值
服务器下发充值命令
发送方 | 服务器 |
说明 | 服务器向设备下发充值命令 |
开始标志 | 1byte,“_” |
报文长度 | 3byte,表示整个报文的总长度,ASCII数字表示 |
命令 | 3byte,CON |
会话ID | 6byte,服务器生成 |
分隔符 | 1byte,“/” |
参数 | 订单号(23byte)
充值端口号(1byte): 1或2 充值数量(2byte): 1~99 |
结束标志 | 2byte,\r\n(0x0D 0x0A) |
示例:
_ 042 CON A80001 / 12345678901234567890123 1 01 <0x0D> <0x0A>
设备充值命令响应
发送方 | 通信模块 |
说明 | 设备响应充值命令并返回是否成功 |
开始标志 | 1byte,“_” |
响应类型 | 2byte,RS |
命令 | 3byte,CON |
会话ID | 6byte,服务器生成 |
内容长度 | 3byte,表示内容长度,ASCII数字表示 |
内容 | 订单号(23byte) #/#
是否成功:S-成功,F-失败 |
结束标志 | 2byte,\r\n(0x0D 0x0A) |
示例:
_ RS CON 123456 027 12345678901234567890123 #/# S <0x0D> <0x0A>
下发学习内容
服务器下发学习内容
发送方 | 服务器 |
说明 | 服务端设置模块的信号模式及信号时长 |
开始标志 | 1byte,“_” |
报文长度 | 3byte,表示整个报文的总长度,ASCII数字表示 |
命令 | 3byte,CSN |
会话ID | 6byte,服务器生成 |
分隔符 | 1byte,“/” |
参数 | 信号模式(1byte):(0 — 常开模式,1 — 常闭模式)
信号时长(2byte):大于20(单位:毫秒) |
结束标志 | 2byte,\r\n(0x0D 0x0A) |
示例:
_ 019 CSN 123456 / 0 60 <0x0D> <0x0A>
学习结果上报
发送方 | 通信模块 |
说明 | 模块响应服务端执行情况 |
开始标志 | 1byte,“_” |
响应类型 | 2byte,RS |
命令 | 3byte,CSN |
会话ID | 6byte,服务端下发 |
内容长度 | 3byte,表示内容长度,ASCII数字表示 |
内容 | S-成功,F-失败 |
结束标志 | 2byte,\r\n(0x0D 0x0A) |
示例:
_ RS CSN 123456 001 S <0x0D> <0x0A>
投币上报
是否启用投币上报
发送方 | 服务器 |
说明 | 服务端下发是否需要投币上报(默认为关闭状态) |
开始标志 | 1byte,“_” |
报文长度 | 3byte,表示整个报文的总长度,ASCII数字表示 |
命令 | 3byte,CTB |
会话ID | 6byte,服务器生成 |
分隔符 | 1byte,“/” |
参数 | 是否启用(1byte):(0 — 关闭,1 — 启用) |
结束标志 | 2byte,\r\n(0x0D 0x0A) |
示例:
_ 017 CTB 123456 / 0 <0x0D> <0x0A>
响应服务端设置
发送方 | 通信模块 |
说明 | 响应服务端设置投币上报功能是否成功 |
开始标志 | 1byte,“_” |
响应类型 | 2byte,RS |
命令 | 3byte,CTB |
会话ID | 6byte(服务端下发) |
内容长度 | 3byte,表示内容长度 001 |
内容 | S-成功,F-失败 |
结束标志 | 2byte,\r\n(0x0D 0x0A) |
示例:
_ RP CTB 123456 001 S <0x0D> <0x0A>
发起投币上报
发送方 | 通信模块 |
说明 | 发现投币后上报服务器 |
开始标志 | 1byte,“_” |
响应类型 | 2byte,RP |
命令 | 3byte,CIN |
会话ID | 6byte,A80002 |
内容长度 | 3byte,表示内容长度 001 |
内容 | 1 |
结束标志 | 2byte,\r\n(0x0D 0x0A) |
示例:
_ RP CIN 123456 001 1 <0x0D> <0x0A>
运行完成上报
发送方 | 通信模块 |
说明 | 设备运行结束后,负载拔出,上报服务端完成 |
开始标志 | 1byte,“_” |
响应类型 | 2byte,RP |
命令 | 3byte,STP |
会话ID | 6byte,A80012 |
内容长度 | 3byte,表示内容长度 001 |
内容 | 1-1号端口结束,2-2号端口结束 |
结束标志 | 2byte,\r\n(0x0D 0x0A) |
示例:
_ RP STP A80012 001 1 <0x0D> <0x0A>