公共接口协议文档

来自东骏科技波塞冬平台开发者文档
跳转至： 导航、 搜索

描述

规约

本文档所述的协议是用以东骏科技有限公司物联网服务平台和底层设备的数据交互。

客服（技术）联系方式

杭州东骏科技有限公司

电话：0571-87017551

手机：13082852087

兼容性

仅适用于授权设备。

词汇表

响应类型：上报服务端的数据响应类型。分为即时响应上报和设备主动上报。

会话ID: 由服务端生成，用以区分不同的命令数据链。

网络通讯协议

本章节内容定义通讯模块和服务器之间的通讯协议。

通讯方式

  1. 数据上报：string字符串
  2. 指令数据：定长报文
  3. 通讯网络协议：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)

命令限制

  1. ADV(设备号IMEI号) AID(SIM卡ICCID号) AXT(心跳) AAA(空指令) 为系统内置命令不能用于其他接口
  2. 业务级别的接口命令不得用 A 开头

系统及网络接口

获取设备号

请求设备号

发送方 服务器
说明 在设备连接服务端成功后，服务端立即发送指令请求该设备的设备号

现在约定设备的GSM模块的IMEI号作为唯一设备号

开始标志 1byte，“_”
报文长度 3byte，表示整个报文的总长度，ASCII数字表示
命令 3byte，ADV
会话ID 6byte，000000
分隔符 1byte，“/”
参数 IMEI
结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ 020 ADV 000000 / IMEI 0x0D 0x0A

设备号响应

发送方 通信模块
说明 设备收到设备号请求时，返回设备号

现在约定设备的GSM模块的IMEI号作为唯一设备号

设备号返回后才能开始真正的业务级别通讯

开始标志 1byte，“_”
响应类型 2byte，DV
命令 3byte，ADV
会话ID 6byte，000000
内容长度 3byte，表示内容长度，ASCII数字表示
内容 2byte ID类型：IM

2byte 编码长度：IMEI号长度，一般为15

（一般15byte）设备号：GSM模块IMEI号

结束标志 2byte，\r\n（0x0D 0x0A）

示例:

IMEI号: 987654321012345 _ DV ADV 000000 019 IM 15 987654321012345 0x0D 0x0A

心跳Ping

发送心跳Ping

发送方 通信模块
说明 设备连接成功后，轮询发送心跳包，保持长连接。

综合考虑运营商GPRS的超时、路由映射缓存超时、流量节省等因素，

心跳间隔建议在60秒

开始标志 1byte，“_”
响应类型 2byte，PG
命令 3byte，AXT
会话ID 6byte，000000
内容长度 3byte，001
内容 信号值：0-31（，分割）

误码率：0-7（#/#分割）

上次心跳响应时间：整数值（可能为负，10ms为单位，上次心跳发出时间到上次接收到服务器心跳返回的时间，可以初略估计出网络的传输和服务器的响应速度，#/#分割）

网络制式：GPRS、HSPA、WCDMA、LTE、CDMA等

结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ PG AXT 000000 016 31 , 0 #/# 74 #/# GPRS 0x0D 0x0A

信号值显示建议：

以下以5格信号显示为例：信号值0-5显示0格，信号值6-12显示为1格，信号值13-16显示为2格，信号值17-20显示为3格，信号值21-25显示为4格，信号值26-31显示为5格。同时如果误码率≥5,则信号格数在原来基础上减去1，如果计算的信号格数为负数则显示为零格。

通常信号值为15以下（包括15）的建议通过信号放大或者调整天线匹配等手段使模块获得更好的信号，在这种信号情况下会出现掉线率高，数据延时高等情况，对通讯和业务会造成影响。

关于天线：

天线是将传输线中的电磁能转化成自由空间的电磁波，或将空间电磁波转化成传输线中的电磁能的专用设备。在无线通信系统中，天线是收发信机与外界传播介质之间的接口。同一个天线既可以辐射又可以接收无线电波：发射时，把高频电流转换为电磁波；接收时把电磁波转换为高频电流。

天线是一种变换器，它把传输线上传播的导行波，变换成在无界媒介（通常是自由空间）中传播的电磁波，由于天线具有可逆性，在接收时，天线进行相反的变换；天线是发射和接收电磁波的一个重要装置，没有天线也就没有无线电通信。因此天线的好坏以及天线的安装环境直接影响通讯的质量甚至是是否可以通讯。当你发现你同一个地方2G信号是覆盖的，但是设备的信号很差时，请务必确认天线是否匹配2G网络，天线的安装环境是否良好。天线周围不应该有金属屏蔽或者对信号有反射和吸收的介质，天线周围也不应该有高频信号源或者电力线路，天线安装应该有一定的高度，并查看天线频率、增益、驻波比系数、功率，灵敏度等参数是否符合你的要求，如果你认为设备没有达到预期的信号效果，请咨询专业的天线厂家。

响应心跳Ping

发送方 服务器
说明 服务端回复心跳
开始标志 1byte，“_”
报文长度 3byte，表示整个报文的总长度，ASCII数字表示
命令 3byte，AXT
会话ID 6byte，000000
分隔符 1byte，“/”
参数 P
结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ 017 AXT 000000 / P 0x0D 0x0A

获取ICCID以及软硬件版本号

请求ICCID以及软硬件版本号

发送方 服务器
说明 在设备返回设备号后，服务端发送指令获取SIM卡的ICCID
开始标志 1byte，“_”
报文长度 3byte，表示整个报文的总长度，ASCII数字表示
命令 3byte，AID
会话ID 6byte，000000
分隔符 1byte，“/”
参数
结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ 016 AID 000000 / 0x0D 0x0A

ICCID以及软硬件版本号响应

发送方 通信模块
说明 设备收到ICCID请求时，返回ICCID
开始标志 1byte，“_”
响应类型 2byte，ID
命令 3byte，AID
会话ID 6byte，000000
内容长度 3byte，表示内容长度，ASCII数字表示
内容 ICCID号（#/#分割）

软件版本号（#/#）

硬件版本号

结束标志 2byte，\r\n（0x0D 0x0A）

示例:

ICCID号 : 898602B3131650175846

_ ID AID 000000 045 898602B3131650175846 #/# mc-2.3.0 #/# DJ-BSD-8202 0x0D 0x0A

远程重启

设置远程重启

发送方 服务器
说明 设置设备重启
开始标志 1byte，“_”
报文长度 3byte，表示整个报文的总长度，ASCII数字表示
命令 3byte，ABT
会话ID 6byte，000000
分隔符 1byte，“/”
参数
结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ 016 ABT 000000 / 0x0D 0x0A

请求设备类型

请求设备类型

发送方 服务器
说明 请求设备的类型编号，服务端约定
开始标志 1byte，“_”
报文长度 3byte，表示整个报文的总长度，ASCII数字表示
命令 3byte，ASY
会话ID 6byte，000000
分隔符 1byte，“/”
参数
结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ 016 ASY 000000 / 0x0D 0x0A

响应设备类型

发送方 通信模块
说明 响应设备的类型编号
开始标志 1byte，“_”
响应类型 2byte，RP
命令 3byte，ASY
会话ID 6byte，A00003
内容长度 3byte，表示内容长度，ASCII数字表示
内容 设备类型
结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ RP ASY A00003 001 1 0x0D 0x0A

获取固件说明

请求固件说明

发送方 服务器
说明 请求设备固件说明
开始标志 1byte，“_”
报文长度 3byte，表示整个报文的总长度，ASCII数字表示
命令 3byte，AAE
会话ID 6byte，服务器下发
分隔符 1byte，“/”
参数
结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ 016 AAE 123456 / 0x0D 0x0A

响应固件说明

发送方 通信模块
说明 响应服务器固件说明
开始标志 1byte，“_”
响应类型 2byte，RS
命令 3byte，AAE
会话ID 6byte，服务端下发
内容长度 3byte，表示内容长度，ASCII数字表示
内容 固件说明utf8字段base64之后的字符
结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ RS AAE 123456 016 5Zu65Lu26K+05piO 0x0D 0x0A

心跳和握手流程

1、设备通讯模块连接上服务器后会首先发送一次心跳，此时服务器就可以和模块通讯了， 一般来说首先进行身份鉴别，通过获取 IMEI 和 ICCID 指令，获取设备的 IMEI 和 ICCID 号校验设备的身份信息。心跳是由模块发起，当发起心跳以后服务端必须在 5 秒钟之内回 复心跳，建立连接以后模块会每隔一定的时间发送心跳给服务器用来保持长连接和通讯确 认。

获取设备扫码URL

请求设备扫码URL

发送方 通信模块
说明 设备上线后, 询问平台当前环境下的扫码入口URL,

一般用于构建二维码用于该设备的扫码使用

开始标志 1byte，“_”
响应类型 2byte，RP
命令 3byte，AAI
会话ID 6byte，A00005
内容长度 3byte，表示内容长度, ASCII数字表示
内容 设备当前的IMEI或逻辑设备号
结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ RP AAI A00005 015 861231234512345 0x0D 0x0A

扫码URL响应

发送方 服务器
说明 服务器收到后返回设备当前的扫码URL
开始标志 1byte，“_”
报文长度 3byte，表示整个报文的总长度, ASCII数字表示
命令 3byte，AAI
会话ID 6byte，服务器生成
分隔符 1byte，"/"
内容 扫码URL字符串, 如果设备非法或异常内容为空
结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ 060 AAI AbcDef / https://mobile.supeeder.com/web-wechart/s/1/ \r\n

实际使用时的完整扫码URL为: https://mobile.supeeder.com/web-wechart/s/1/861231234512345

ICCID工装测试接口

上报测试模块的ICCID

发送方 通信模块
说明 上报ICCID和IMEI对应关系
开始标志 1byte，“_”
响应类型 2byte，RP
命令 3byte，ARI
会话ID 6byte，A00022
内容长度 3byte，表示内容长度, ASCII数字表示
内容 格式为: IMEI#/#ICCID

IMEI: 15位数字, 不能为空, 模组IMEI

ICCID: 20位数字, 不能为空, SIM卡内部ICCID

结束标志 2byte，\r\n（0x0D 0x0A）

示例:

_ RP ARI A00022 038 863866048562755#89860442191940080360 \r\n

平台响应测试结果

发送方 服务器
说明 服务器收到IMEI对应的ICCID后, 校验存储并返回结果
开始标志 1byte，“_”
报文长度 3byte，表示整个报文的总长度, ASCII数字表示
命令 3byte，ARI
会话ID 6byte，服务器生成
分隔符 1byte，"/"
内容 格式为: 测试结果(1byte)IMEI(15byte)

测试结果(1byte): 1-成功, 0-失败

IMEI(15byte): 原路返回测试上报时的IMEI

结束标志 2byte，\r\n（0x0D 0x0A）

示例:

测试成功: _ 032 ARI NzTFyX / 1863866048562755 \r\n

测试失败: _ 032 ARI NzTFyX / 0863866048562755 \r\n

公共支付接口

设备获取人脸付调用凭证

获取人脸付调用凭证请求

发送方 设备
说明 设备发起人脸支付前，先向服务器请求人脸付调用凭证
开始标识（1byte） _
响应类型（2byte） RP
命令（3byte） FPA
会话ID（6byte） A00020
内容长度（3byte） 不定长
内容（1byte） JSON格式:

{"plat": 平台, "rawdata": 微信人脸SDK初始化数据}
说明
plat: 目前只支持wechat
rawdata: 初始化数据。由微信人脸SDK的接口返回。平台为wechat的话必填

结束标识（2byte） \r\n (0x0D 0x0A)

获取人脸付调用凭证响应

发送方 Server
说明 下发人脸付调用凭证
开始标识（1byte） _
报文长度（3byte） 不定长
命令（3byte） FPA
会话ID（6byte） 服务器生成
分隔符（1byte） /
参数 JSON格式：

{"success":是否成功, "message":描述, "data":数据}
说明
是否成功：布尔值
描述：base64编码，如果失败会给出失败原因
数据：如果为wechat平台，响应数据参考微信刷脸支付文档

结束标识（2byte） \r\n (0x0D 0x0A)

设备调用付款码支付

调用付款码支付请求

发送方 设备
说明 设备获得付款码后（人脸付设备也可获取），向服务器请求调用付款码支付
开始标识（1byte） _
响应类型（2byte） RP
命令（3byte） MPY
会话ID（6byte） A00021
内容长度（3byte） 不定长
内容（1byte） JSON格式:

{"plat": 平台, "authCode": 扫码支付付款码, "其他业务数据"}
说明
plat: 目前只支持wechat
authCode: 扫码支付付款码，设备读取用户微信中的条码或者二维码信息
售货机业务数据
“ch”:“货道号”,“bar”:”条码”,“qty”:购买数量,“price”:销售价格,”dstCode”:优惠码
货道号：字符串，货道的编号
条码：字符串，下单商品的条码
购买数量：整数，商品购买的数量
销售价格：整数，用户所看到的商品价格
优惠码：字符串，客户自己输入的获取到的优惠码。

结束标识（2byte） \r\n (0x0D 0x0A)

调用付款码支付响应

发送方 Server
说明 下发付款码支付结果
开始标识（1byte） _
报文长度（3byte） 不定长
命令（3byte） MPY
会话ID（6byte） 服务器生成
分隔符（1byte） /
参数 JSON格式：

{"success":是否成功, "message":描述, "data":数据}
说明
是否成功：布尔值
描述：base64编码，如果失败会给出失败原因
数据：暂无

结束标识（2byte） \r\n (0x0D 0x0A)
取自“http://doc.dongjun.org/doc/index.php?title=公共接口协议文档&oldid=1290”