平台服务 商城 产品实现 开发者中心
工厂后台 开发者中心 注销账户 ()
文档首页

智能兑币机解决方案

前言

针对厂商设备主板与乐摇摇串口联网模组对接，平台提供标准串口数据通讯协议、自动生成参数界面、串口调试工具，简化开发过程，使设备快速联网获得增值功能。本文档基于乐摇摇串口联网模组与设备主板的标准对接流程编写。

协议文档

下载乐摇摇兑币机串口通信协议

下载主板协议对接操作指南

集成芯片****对接参考设计资料

若选择串口集成芯片对接方案，请下载相应参考资料

2G&WIFI-集成对接硬件设计资料

4G-集成对接硬件设计资料

ee19192f5b2a427aacb3fb21bbc4418d.png

SDK

下载[串口与函数SDK][SDK]

串口调试工具

下载乐摇摇串口调试助手

准备工作**：**对接前，需要先获取乐摇摇联网芯片或模组，以便后续开发测试。

开发流程

如果您是首次接入乐摇摇联网方案，请按以下流程进行对接。下文将针对各个步骤进行详细描述。

4e21b2376bae43c5a1095d0a2fffb3db.jpg

对接流程 参考文档
1注册开发账号 查看流程文档
2创建产品 查看流程文档
3主板参数配置 查看流程文档
4硬件嵌入式开发 查看流程文档
5硬件联调 查看流程文档
6发布，体验功能 查看流程文档

协议基础

通信配置

通信接口： 串口（RS485/RS232/TTL）

波特率：38400

停止位：1位

数据位：8位

校验位：0位

数据类型

数据类型 描述
BYTE 无符号单字节整型（字节，8位）
WORD 无符号双字节整型（双字节，16位）
DWORD 无符号四字节整型（四字节，32位）
BYTE[n] N字节

传输规则

协议采用小端模式(little-endian)的网络字节序来传递字和双字。

约定如下：

——字节(BYTE)的传输约定：按照字节流的方式传输；

——字(WORD)的传输约定：先传递低八位，再传递高八位；

——双字(DWORD)的传输约定：先传递低八位，然后传递高八位，再传递高16位，

最后传递高24位。

通信机制

主机查询方式

主机按照一定的时间间隔向终端发送数据帧，终端接收到数据帧后返回应答帧，终端不主动上传数据，若主机在规定时间内未接受到规定的数据帧的应答数据帧，则重发数据帧直到终端返回应答数据帧。

正常通信时序：

654bb817a1334f979b0803416c5746f4.png

异常通信时序：

fe791bdf1ccf444cb996762c0b0a7109.png

终端上传数据帧方式

正常通信时序：

243d45a61d984d6d8545d7967edec4cf.png

异常通信时序：

5b599ca44f654b93bf138e7aef91cb30.png

数据帧格式

帧格式图

832df2472c87452e9d9c7323c3e3d341.png

格式说明

起始字节 名称 定义 数据类型 备注
0 Head(帧头) 固定为0xAA BYTE
1 Length(长度) Index + CMD +Data + Check 数据总长 BYTE
2 Index (索引) 主机：0x01 终端：0x02 BYTE 标识消息发出方 兑币机主板为02
3 CMD(命令) 表明数据帧的类型 BYTE
4 Data(数据) 数据区 BYTE[n] (n<200) 数据区长度可以为0
4+n Check(校验) 校验范围：Length+ Index+ CMD+ Data BYTE 异或校验
5+n End(帧尾) 固定为0xDD BYTE

功能与指令

设备登录

登录流程

支付盒子

f97c729db2b940198a6fbd60d33341b2.png

指令说明——查询链接状态

支付盒子 -------------> 兑币机 主板

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x0B
2 Index (索引) BYTE 0x01 标识盒子主机
3 CMD(命令) BYTE 0x01 查询链接状态
4 Data(数据) BYTE[8] 8位设备唯一码
12 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
13 End(帧尾) BYTE 0xDD

兑币机 主板 -------------> 支付盒子

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x05
2 Index (索引) BYTE 0x02 标识兑币机主板
3 CMD(命令) BYTE 0x01 查询链接状态
4 Data(数据) WORD 登录标识 小端模式传输 获取方式见 登录 标识
6 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
7 End(帧尾) BYTE 0xDD

登录标识

登录标识是乐摇摇支付盒子用以识别所对接设备主板身份的标识码，每个产品都有且只有一个（请把登录标识烧录到设备中。当设备激活时，会上报到云端鉴权认证设备参数）。

标识码获取流程：

（1）打开乐摇摇后台网站https://open.leyaoyao.com（推荐Chrome浏览器），输入账号密码并登录。若无账号，请先注册开发账号。

（2）登录成功后，即可进入开发者中心。

2ae47381cab54a0d995533d621d4b10b.png

（3）点击创建产品出现弹窗，请按要求完善产品信息。

908ecc04a2a04bfbaf540c0590791732.png

c4b5c8f5875c401785bada15fe4898b3.png

主板信息填写与要求 ：

1主板名称格式为厂家名称+设备类型，例如：乐摇摇****兑币机

2上传的主板原图与接线方式图片参照上方示例，特别注意拍摄清晰保证主板与支付盒子间的接口电路，以便工作人员审核

（4）主板信息提交成功后，乐摇摇硬件工作人员将在3个工作日内对其进行审核，审核结果会同步以短信形势发送到主板厂商预留的手机号码，请注意查收。

（5）待审核通过后，即可在该页面看到该主板对应登录标识。如未通过，请留意申请反馈并与乐摇摇硬件工作人员进一步沟通。

e5aae4a30af94db192f08b481abc57da.png

（6）注意：获取到的登录标识为十进制，通信数据中需转换为16进制，并令低位在前，高位在后，以小端模式传输。如：登录标识为150，则通信中实际需传输的登录标识数据为 0x96 0x00

线上支付

支付流程

支付盒子

85bf938b5bd24522a84e8a8f27c5a5c7.png

指令说明——云上分

支付盒子 -------------> 兑币机 主板

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x08
2 Index (索引) BYTE 0x01 标识盒子主机
3 CMD(命令) BYTE 0x03 云上分
4 Data(数据) 见表3.2.2.1 详见表1
9 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
10 End(帧尾) BYTE 0xDD

表1 支付盒子云上分指令数据区说明

数据字段 名称 数据类型 备注
Data[0] 自增码 BYTE 避免数据重复处理，新发送的上分数据自增码增加，重发的数据帧自增码不变。 自增码到达0xFF后置0，建议默认0x10
Data[1-2] 投币数 WORD 小端模式传输
Data[3-4] 金额 WORD 小端模式传输

兑币机 主板 -------------> 支付盒子

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x04
2 Index (索引) BYTE 0x02 标识兑币机主板
3 CMD(命令) BYTE 0x03 云上分
4 Data(数据) BYTE 登录结果 0x00：失败 0x01：成功
6 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
7 End(帧尾) BYTE 0xDD

开发建议：投币数与金额默认取相同值，在实际应用中，建议兑币机上分数取投币数，兑币机取金额。

获取支付二维码

功能说明

1该指令用于配有显示屏的兑币机主板从支付盒子获取指向支付页面的二维码链接。

2该二维码链接的地址格式为：http://m.leyaoyao.com/lyy/t/<设备号>

指令说明——获取二维码链接

兑币机 主板 -------------> 支付盒子

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x03 视自定义情况
2 Index (索引) BYTE 0x02 标识兑币机主板
3 CMD(命令) BYTE 0x10 获取二维码链接
- Data(数据) - - 不含数据区
4 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
5 End(帧尾) BYTE 0xDD

支付盒子 -------------> 兑币机 主板

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0xXX 以自定义情况为准
2 Index (索引) BYTE 0x01 标识盒子主机
3 CMD(命令) BYTE 0x06 查询终端参数
4 Data(数据) BYTE[n] 支付地址链接 链接地址格式见获取支付二维码-功能说明
4+n Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
5+n End(帧尾) BYTE 0xDD

上传账目增量

功能说明

此功能不可去除，后台关于兑币机的收益、出礼等各项经营统计，皆基于本指令中数据完成。

其中，故障代码可根据厂商需求，在乐摇摇后台网站https://open.leyaoyao.com（推荐Chrome浏览器打开）中的主板参数配置（参考设置终端参数）页面中最下方一栏自行定义。

创建故障参数：

点击添加，然后根据实际需求填写故障情况

5474cd2ba1d24879aac0746bdc5916f4.png

编写完成提交后，点击同步主板参数，即可进行调试。

5aea59eca0664b70a6765c4bfdced908.png

兑币机主板上报故障代码后，可以在乐摇摇手机后台的消息通知中接收到对应的故障信息，如下图所示

112744ec23c142c789b10b80ff6cad52.png

指令说明——终端主动上传账目增量

兑币机 主板 -------------> 支付盒子

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x0A
2 Index (索引) BYTE 0x02 标识兑币机主板
3 CMD(命令) BYTE 0x13 终端主动上传账目增量
4 Data(数据) 见表3.6.2.1 详见表2
11 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
12 End(帧尾) BYTE 0xDD

表 2 终端主动上传账目增量指令数据区说明

数据字段 名称 数据类型 备注
Data[0] 自增码 BYTE 避免数据重复处理，新发送的上分数据自增码增加，重发的数据帧自增码不变。 自增码到达0xFF后置0，建议默认0x10
Data[1] 故障代码 BYTE 设备故障码（定制方法见上传账目增量-功能说明）
Data[2] 投币增量 BYTE 设备一段时间投币的增量
Data[3] 退礼增量 BYTE 设备一段时间退礼的增量
Data[4] 营收增量 BYTE 设备一段时间营收的增量
Data[5-6] 预留字节 WORD

支付盒子 -------------> 兑币机 主板

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x03
2 Index (索引) BYTE 0x01 标识盒子主机
3 CMD(命令) BYTE 0x13 终端主动上传账目增量
- Data(数据) - - 数据区无数据
4 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
5 End(帧尾) BYTE 0xDD

查询网络信号

功能说明

此功能可以使兑币机主板主动获取到支付盒子当前的网络状态。需要注意，在开机约10分钟后，才可以正常获取到支付盒子的信号值。

指令说明——查询支付盒子网络状态

兑币机 主板 -------------> 支付盒子

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x03
2 Index (索引) BYTE 0x02 标识兑币机主板
3 CMD(命令) BYTE 0x19 查询支付盒子网络状态
- Data(数据) - - 不含数据区
4 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
5 End(帧尾) BYTE 0xDD

支付盒子 -------------> 兑币机 主板

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x03
2 Index (索引) BYTE 0x01 标识盒子主机
3 CMD(命令) BYTE 0x19 查询支付盒子网络状态
4 Data(数据) 见表3 详见表3
6 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
7 End(帧尾) BYTE 0xDD

表 3 查询支付盒子网络状态指令数据区说明

数据字段 名称 数据类型 备注
Data[0] 信号值 BYTE 0-31种级别 数字越大，信号越强
Data[1] 链接服务器状态 BYTE 0x00：在线 0x01：离线

远程升级

功能说明

此功能可使主板厂家实现对其兑币机主板的远程升级，通过该指令，服务器将会把固件程序分包下发到主板。

首先进入开放平台开发者中心https://open.leyaoyao.com/factory/motherboard，点击固件远程升级，进入固件升级页面。

点击新增固件，填写各项信息，上传固件程序，点击确定。

在批量升级前，需要先进行验证固件操作，点击验证固件。根据盒子设备编号添加设备，验证固件最多选择两台，点击确定，即开始升级。

升级完成则后台显示升级成功。

此时可以进行批量升级操作，一次最多添加50台设备。

指令说明 —— 数据包下载

支付盒子 -------------> 兑币机主板

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0xFF 为0xFF表示超过255个字节
2 Index (索引) BYTE 0x01 标识盒子主机
3 CMD(命令) BYTE 0xCD 大文件下载指令集
4 frame_length WORD 数据帧中数据长度
6 sub_cmd BYTE 0x01 子命令
7 Name_length BYTE 1-20 文件名的字符串长度
8 File_name String[M] 不包含后缀，只支持字符，不支持中文
9+M File_size WORD 文件大小，单位字节，小端模式
11+M Packet_Sum WORD 分包数量，每包上传数据512字节，小端模式
13+M Packet_Num WORD 当前包的编号 起始包编号为1
15+M Data_length WORD 数据区长度
16+M File_data BYTE[N] 文件数据
16+N+M Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
17+N+M End(帧尾) BYTE 0xDD

兑币机主板 -------------> 支付盒子

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0xXX 以自定义情况为准
2 Index (索引) BYTE 0x02 标识兑币机主板
3 CMD(命令) BYTE 0xCD 自定义指令
4 sub_cmd BYTE 0x01 子命令
5 Name_length BYTE 1-20 文件名的字符串长度，单位是字节
6 File_name String[M] 不包含后缀，只支持字符，不支持中文
6+M File_size WORD 文件大小，单位字节，小端模式
8+M Packet_Sum WORD 分包数量，每包上传数据512字节，小端模式
10+M Packet_Num WORD 当前包的编号
12+M File_result BYTE 0：接受成功
1：续传数据，按照应答中的编号接着往下传。
2：文件命名不一样，直接更新文件。
13+M Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
14+M End(帧尾) BYTE 0xDD

指令说明 —— 上传本地固件信息

兑币机主板------------->支付盒子

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0xXX 为0xff表示超过255个字节
2 Index (索引) BYTE 0x02 标识盒子主机
3 CMD(命令) BYTE 0xCD 大文件下载相关指令
4 sub_cmd BYTE 0x02 子命令
5 Name_length BYTE 1-20 文件名的字符串长度
6 File_name String[M] 不包含后缀，只支持字符，不支持中文
6+M File_size WORD 已保存的文件大小，单位字节
8+M version_length BYTE 软件版本号长度
10+M+N version String[N] 软件版本号
10+N+M Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
10+N+M End(帧尾) BYTE 0xDD

支付盒子 -------------> 兑币机主板

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x05 以自定义情况为准
2 Index (索引) BYTE 0x01 标识兑币机主板
3 CMD(命令) BYTE 0xCD 自定义指令
4 sub_cmd BYTE 0x02 子命令
5 File_result BYTE 预留
6 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
7 End(帧尾) BYTE 0xDD

指令说明 —— 获取本地固件信息

支付盒子 -------------> 兑币机主板

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x05 以自定义情况为准
2 Index (索引) BYTE 0x01 标识兑币机主板
3 CMD(命令) BYTE 0xCD 自定义指令
4 sub_cmd BYTE 0x03 子命令
5 File_result BYTE 预留
6 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
7 End(帧尾) BYTE 0xDD

兑币机主板------------->支付盒子

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0xXX 为0xff表示超过255个字节
2 Index (索引) BYTE 0x02 标识盒子主机
3 CMD(命令) BYTE 0xCD 大文件下载相关指令
4 sub_cmd BYTE 0x03 子命令
5 Name_length BYTE 1-20 文件名的字符串长度
6 File_name String[M] 不包含后缀，只支持字符，不支持中文
6+M File_size WORD 已保存的文件大小，单位字节
8+M version_length BYTE 软件版本号长度
10+M+N version String[N] 软件版本号
10+N+M Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
10+N+M End(帧尾) BYTE 0xDD

扩展指令

功能说明

厂商可通过此功能根据自身需求定义扩展指令，如清空当前局数，恢复出厂设置等功能。

在乐摇摇后台网站https://open.leyaoyao.com（推荐Chrome浏览器打开）中的主板参数配置（参考终端参数）页面中，新增终端操作。

5e8f637eb3814c2c9107ece3db7c6990.png

根据实际情况填写各项内容。若设置功能不含参，则该指令固定不含数据区；若设置功能含参，则需进一步设置子参数，具体可参考自定义终端参数项。设置中的功能码对应数据帧中的CMD项，数值范围0x30-0xC8（48-200）。

设置完成后，功能会显示在乐摇摇设备管理系统-设备管理模块中，右图4

abb6270dc4e142cca9ac418ab1e3464c.jpg

指令说明——扩展指令

支付盒子 -------------> 兑币机 主板

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0xXX 以自定义情况为准
2 Index (索引) BYTE 0x01 标识盒子主机
3 CMD(命令) BYTE 0xXX 自定义指令
4 Data(数据) BYTE[n] 自定义参数项 自定义方法说明见扩展指令-功能说明
4+n Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
5+n End(帧尾) BYTE 0xDD

兑币机 主板 -------------> 支付盒子

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0xXX 以自定义情况为准
2 Index (索引) BYTE 0x02 标识兑币机主板
3 CMD(命令) BYTE 0xXX 自定义指令
4 Data(数据) BYTE[n] 自定义参数项 自定义方法说明见扩展指令-功能说明
4+n Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
5+n End(帧尾) BYTE 0xDD

终端参数查询与设置

终端参数

指令说明——查询终端参数

支付盒子 -------------> 兑币机 主板

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0x03
2 Index (索引) BYTE 0x01 标识盒子主机
3 CMD(命令) BYTE 0x15 查询终端参数
- Data(数据) - - 不含数据区
4 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
5 End(帧尾) BYTE 0xDD

兑币机 主板 -------------> 支付盒子

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0xXX 以自定义情况为准
2 Index (索引) BYTE 0x02 标识兑币机主板
3 CMD(命令) BYTE 0x15 查询终端参数
4 Data(数据) BYTE[n] 自定义参数项 自定义方法说明见设置终端参数
4+n Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
5+n End(帧尾) BYTE 0xDD

指令说明——设置终端参数

支付盒子 -------------> 兑币机 主板

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0xXX 以自定义情况为准
2 Index (索引) BYTE 0x01 标识盒子主机
3 CMD(命令) BYTE 0x06 设置终端参数
4 Data(数据) BYTE[n] 自定义参数项 自定义方法说明见设置终端参数
4+n Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
5+n End(帧尾) BYTE 0xDD

兑币机 主板 -------------> 支付盒子

起始字节 名称 数据类型 描述 备注
0 Head(帧头) BYTE 0xAA
1 Length(长度) BYTE 0xXX 视自定义情况
2 Index (索引) BYTE 0x02 标识兑币机主板
3 CMD(命令) BYTE 0x06 设置终端参数
4 Data(数据) BYTE 参数设置结果 0x00：设置失败 0x01：设置成功
5 Check(校验) BYTE 异或校验码 校验范围：Length+ Index+ CMD+ Data
6 End(帧尾) BYTE 0xDD

自定义终端参数项

（1）打开乐摇摇后台网站https://open.leyaoyao.com（推荐Chrome浏览器），输入账号密码并登录开发者中心。若无账号，请先注册开发账号。

（2）在智能化产品列表中，找到需要进行自定义参数项的主板，点击“编辑”。若找不到该主板，请参照登录标识中的说明，添加需要对接的主板。

e5aae4a30af94db192f08b481abc57da.png

（3）进入主板参数配置页面，参数配置由3部分组成，包括基础参数、终端参数、故障参数。参数配置是对产品功能的抽象表示，可以通过不同功能类型定义。目前平台提供：布尔型、数值型、枚举型、故障型这四种参数类型。详情设置说明见参数配置

5734aa2340b945e894c35100265d7466.png

（4）界面预览

配置完成后，点击写一步，系统根据你配置的参数，自动生成设备参数管理界面，通过微信扫码二维码即可查看。确定功能、界面是否符合，若符合点击下一步即可，若不符合，返回参数配置界面调整。

5bd25fc8c10a4526b620407d08fe643d.png

（5）参数配置以及开发完成后，需要发布主板参数才完成入库对接。发布后，终端参数功能会显示在乐摇摇设备管理系统-设备管理模块中。

abb6270dc4e142cca9ac418ab1e3464c.jpg

（6）当主板参数状态变为已发布后，即可进行对应的调试工作。若在此后修改参数项，需在修改完成后再次点击同步更新。

（7）发布后请厂商务必做好主板调试，主板调试完成，发布前请联系乐摇摇对接人员

SDK解决方案

面向对象

本文档面向合作伙伴的技术员，适用于乐摇摇SAAS平台有屏售货机产品的硬件技术对接，便于双方技术团队遵循既定的合作流程，完成技术的沟通和对接，提升效率。

集成文档包括《技术协议文档》、《open-netty-client.jar》、《open-netty-client-sources.jar》

联系方式：陈先生-13728058558

SDK说明

设备接入SDK封装了有屏售货机与乐摇摇SAAS系统的云端通讯过程。 这些过程包括配置、连接、心跳、状态上报以及场景功能接口等。 使用SDK，可以使得开发者快速完成APP开发，开发者仅需关注APP的UI和UE设计即可，而相对复杂的协议与错误处理等事项可忽略。

接入流程

第一步，和技术沟通，获得APP的产品参数appid和secrect。 第二部，下载SDK包和开发文档，实现场景应用接口。

SDK文档

下载安卓SDK

正式的域名:ehw.leyaoyao.com
端口:5923

合作方根据实际情况选择jar包的版本，可以在maven仓库查询maven和gradle依配置

仓库地址：https://mvnrepository.com

eb71d66892bc4d05a50e98e718b4fcbb.png

Gradle依赖

引入netty和json包

compile group: 'io.netty', name: 'netty-all', version: '4.1.16.Final' 
compile group: 'com.google.code.gson', name: 'gson', version: '2.8.2'

Mave依赖

io.netty netty-all 4.1.16.Final 
com.google.code.gson gson 2.8.2 |

SDK接入指南

初始化

开发团队已经对福袋机通讯协议进行封装，app只需要在工程中引入open-netty-client.jar，即可调用相应api进行数据收发操作。

登陆流程示意图

客户端实例声明

NettyClient client = new NettyClient ( appId , key , host , port , uuid,equipmentType, loginFlag,handler ) ;

client.connect(); // 请求服务器建立链接

参数说明:

参数名称 参数说明
appId 系统分配的应用编号
Key 秘钥
host 通讯域名或者IP
port 端口
uuid 设备唯一编码,由厂家自定义生成，全局唯一，否则登陆失败。 目前推荐规则：厂家前缀+设备唯一码
equipmentType 设备类型， DBJ 兑币机
loginFlag 登录标识
handler 参考“消息处理器”说明

消息处理器 消息子类继承AbstractMsgHandler，重写业务逻辑方法，详见“处理器实现”说明。 实现样例：

public class SimpleMsgHandler extends AbstractMsgHandler {

/**

重写登陆逻辑

**/

@Override

protected boolean loginHandler(ResponseParam responseParam) {

// 业务实现代码

return true;

}

……

获取随机字串

方法名称：MsgProducer.getSignRandom(GetSignRandomParam param)。

该接口为 获取随机字串，获取随即字串接口是用于登录使用， SDK 在获取随即字段成功后会自动调用登录接口。如果自动登录接收登录结果为失败，需要手工调用该接口进行重试；

设备登录接口

方法名称：MsgProducer.login(LoginParam param)。

如果登录结果返回失败，需要手动调用 getSignRandom(GetSignRandomParam param) 进行重新登录，建议重试时间间隔 5 秒。

参数名称 参数说明
random 通过MsgProducer.getSignRandom(GetSignRandomParam param)获取的随机码

设备登陆

SDK初始化成功后，自身机制管理与服务器链接状态，自动发起随机数获取、登陆，完成服务器约定的设备初始化流程。 步骤如下：

获取随机数 详见“获取随机字串”说明。

设备登陆 详见“设备登录接口”说明。

设备启动

方法名：replyStartEq(ReplyStartEqParam param)

参数详细说明：

参数名称 参数说明
data 应答结果：0=成功，1=失败，当值为1时failure不为空
failure 应答失败的原因
uniqueCode 指令唯一码：在接收启动设备指令时由服务端下发

重写handler子类的sendAdsHandler方法，处理逻辑，并响应服务器处理结果。

代码示例：

@Override
protected boolean startEquipmentHandler(ResponseParam responseParam) {
super.startEquipmentHandler(responseParam);
ReplyStartEqParam param = new ReplyStartEqParam();
param.setUniqueCode(responseParam.getK());
param.setData(0);
// param.setData(1);
// param.setFailure("主板启动失败");
return MsgProducer.replyStartEq(param);
}

说明：设备收到此指令后应根据实际情况响应ser指令，否则服务端会隔5s重发该通知（k不变），最多重复3次

注意：如果设备应答的结果为失败，服务端会直接进行退款；应答成功则会根据启动结果上传esr指令进行判断是否启动成功。

启动结果上报

方法名：uploadEqStartResult(ReplyStartEqParam param)

详细参数说明如下：

参数名称 参数说明
data 应答结果：0=成功，1=失败，当值为1时failure不为空
failure 应答失败的原因
uniqueCode 指令唯一码：在接收启动设备指令时由服务端下发
mi 主板编号
pi 仓位编号

代码示例如下：

private static boolean uploadEqStartResult(String mi, String pi, String d, String k) {
ReplyStartEqParam param = new ReplyStartEqParam();
param.setMi(Integer.parseInt(mi));
param.setPi(Integer.parseInt(pi));
int data = Integer.parseInt(d);
if (data == 1) {
param.setFailure("主板离线");
}
param.setData(data);
param.setUniqueCode(k);
return MsgProducer.uploadEqStartResult(param);
}

说明：设备将启动结果上报给服务端，如果启动结果失败时，服务端会进行退款，如果5s内未收到服务端下发的esrr指令，要进行重发（k不变），最多重发3次

注意：如果服务端在收到ser指令后，120s内没有接收到esr指令，则会认为设备启动成功

设备上报结果返回处理：

重写handler子类的eqStartResultReHandler方法，代码示例如下：

@Override
protected boolean eqStartResultRespHandler(ResponseParam responseParam) {
System.out.println(String.format("get 设备启动结果上传返回结果为：%s", gson.toJson(responseParam)));
return true;
}

上传线下投币数据

当设备有线下投币的时候，需要调用 MsgProducer 中的 uploadCommonCoins方法 同步数据到服务端。 同步投币数据后 AbstractMsgHandler 中的 uploadCommonCoinsResultHandler方法会返回服务端的接收结果。 如果没有接收到消息或者返回接收失败，则需要进行 3次 重试；

方法名称：MsgProducer. uploadCommonCoins(UploadGiftParam param);   

详细参数说明如下：

参数名称 参数说明
uniqueCode 指令唯一码： 上传投币数据时 client 生成
count 投币增量：本次投币数量
total 投币总量：设备投币总量（当该数大于上次上传的投币总量时：本次投币数量=本次投币总量-上次投币总量，否则：本次投币数量=投币增量）

代码示例如下：

public static boolean uploadCommonCoins(String total, String count) {
System.out.println("上传投币信息......");
String key = UUID.randomUUID().toString();
CommonUploadCoinsParam param = new CommonUploadCoinsParam();
param.setUniqueCode(key);
param.setTotal(total);
param.setCount(count);
return MsgProducer.uploadCommonCoins(param);
}

代码示例：重写handler的uploadCommonCoinsResultHandler方法，处理消息通知。

@Override
protected boolean uploadCommonCoinsResultHandler(ResponseParam responseParam) {
System.out.println(String.format("get 上传投币信息返回结果为：%s", gson.toJson(responseParam)));
return true;
}

 

设备绑定

在公众号后台进行设备绑定和解除绑定操作，流程如下：

IMG_258

操作成功后，服务器下发的设备消息到安卓APP；如果操作失败，请开发这重复上述流程，重复操作流程不下发消息通知。

开发者实现handler的通知逻辑，重写eqBindNoticeHandler绑定通知；重写 eqUnBindNoticeHandler解绑通知。

示例代码如下：

/**

* 设备绑定通知

*@param responseParam

*@return

**/

protected boolean eqBindNoticeHandler(ResponseParam responseParam) {

System.out.println(String.format("get 收到设备绑定通知: %s", gson.toJson(responseParam)));

return true;

}

/**

*设备解绑通知

*@param responseParam

*@return

**/

@Override

protected boolean eqUnBindNoticeHandler(ResponseParam responseParam) {

System.out.println(String.format("get 收到设备解绑通知: %s", gson.toJson(responseParam)));

return true;

}

上报设备故障

方法名：reportEquipmentFailure

参数详细说明：

参数名称 参数说明
errorCode c:故障码
errorDesc d:故障描述
errorStatus s:故障状态
uniqueCode 指令唯一码：由 client 生成

示例代码：

public static boolean reportEquipmentFailure() {
ReportEquipmentFailureParam param = new ReportEquipmentFailureParam();
param.setErrorCode("234");
param.setErrorDesc("设备故障上报测试");
param.setErrorStatus("1");
param.setUniqueCode(uuid());
return MsgProducer.reportEquipmentFailure(param);
}

该操作需要确认上报结果，如果没有接收到消息或者返回接收失败，建议进行3次重试。

重写handler子类的reportEquipmentFailureResultHandler方法，接收故障上报结果。

代码示例：

@Override
protected boolean reportEquipmentFailureResultHandler(ResponseParam responseParam) {
System.out.println(String.format("上报设备错误信息 结果返回：%s", gson.toJson(responseParam)));
return true;
}

ICCID上传（流量卡设备，wifi设备则不用）

方法名： reportICCID

详细参数说明：

参数名称 参数说明
iccid iccid
uniqueCode 指令唯一码：由 client 生成

代码示例：

private static boolean iccidReport(String iccid) {
System.out.println("上传iccid。。。。" + iccid);
ICCIDParam param = new ICCIDParam();
param.setIccid(iccid);
param.setUniqueCode(uuid());
return MsgProducer.reportICCID(param);
}

说明：设备登录完成后，应上传iccid。如果5s内接收不到服务器响应，则需要重发该通知（uniqueCode不变），最多重发3次。

重写handler子类的reportICCIDResultHandler方法，接收服务器响应并处理。

代码示例：

@Override
protected boolean reportICCIDResultHandler(ResponseParam responseParam) {
System.out.println("Iccid 上报结果返回");
return super.reportICCIDResultHandler(responseParam);
}

定位信息查询

方法名：replyGps(ReplyGpsParam)

详细参数说明：

参数名称 参数说明
longitude 经度
latitude 纬度
uniqueCode 指令唯一码：由 服务器 生成

重写handler子类的gpsHandler方法，并响应服务器处理结果。

代码示例：

@Override
protected boolean gpsHandler(ResponseParam responseParam) {
super.gpsHandler(responseParam);
ReplyGpsParam param = new ReplyGpsParam();
param.setUniqueCode(responseParam.getK());
param.setLongitude("113.38795");
param.setLatitude("22.9753936");
return MsgProducer.replyGps(param);
}

广告屏幕及广告位信息查询

方法名：replyQueryAds

详细参数说明：

参数名称 参数说明
type 屏幕类型:1-福袋机屏,2-落地屏
screenWidth 屏幕宽度
screenHeight 屏幕高度
resolutionWidth 分辨率宽度
resolutionHeight 分辨率高度
positions 广告位信息列表
uniqueCode 指令唯一码：由 服务器 生成
value 广告位编号
name 广告位名称
area 广告位区域

重写handler子类的queryAdsHandler方法，处理逻辑，并响应服务器处理结果。

代码示例：

@Override
protected boolean queryAdsHandler(ResponseParam responseParam) {
super.queryAdsHandler(responseParam);
ReplyQueryAdsParam param = new ReplyQueryAdsParam();
param.setUniqueCode(responseParam.getK());
param.setType("1");
param.setScreenWidth(100);
param.setScreenHeight(100);
param.setResolutionWidth(6700);
param.setResolutionHeight(4000);

List<AdsPosition> positions = new ArrayList<>();
AdsPosition position1 = new AdsPosition();
position1.setValue("left0010");
position1.setName("左广告位");
position1.setArea("(0,0),(10,10)");
position1.setWidth(10);
position1.setHeight(10);
position1.setIsFullScreen("N");
position1.setScreenType("V");

AdsPosition position2 = new AdsPosition();
position2.setValue("right0010");
position2.setName("右广告位");
position2.setArea("(10,10),(60,60)");
position2.setWidth(40);
position2.setHeight(40);
position2.setIsFullScreen("N");
position2.setScreenType("H");

positions.add(position1);
positions.add(position2);
param.setPositions(positions);
return MsgProducer.replyQueryAds(param);
}

下发广告

方法名：replySendAds

详细参数说明：

参数名称 参数说明
uniqueCode 指令唯一码：由 服务器 生成

重写handler子类的sendAdsHandler方法，处理逻辑，并响应服务器处理结果。

代码示例：

@Override
protected boolean sendAdsHandler(ResponseParam responseParam) {
super.sendAdsHandler(responseParam);
BaseParam param = new BaseParam();
param.setUniqueCode(responseParam.getK());
return MsgProducer.replySendAds(param);
}

上传广告数据

方法名：uploadAdsData(UploadAdsParam param)

参数详细说明：

为一个数组，各个参数名分别为：

参数名称 参数说明
values 广告位编号
adval 广告编号
total 该广告总播放次数
count 播放增量
uniqueCode 指令唯一码：由 client 生成

说明：设备每分钟判断一次，如有播放广告，将播放数据上传到服务器统计。

重写handler子类的uploadAdsResultHandler方法，接收服务器的响应并处理。

代码示例：

@Override
protected boolean uploadAdsResultHandler(ResponseParam responseParam) {
return super.uploadAdsResultHandler(responseParam);
}

更新广告

方法名：replyUpdateAds

详细参数说明：

参数名称 参数说明
uniqueCode 指令唯一码：由 服务器 生成

说明：服务器查询到广告信息有更新，会下发更新广告指令，设备若有此广告信息，根据状态值做相应的处理。

重写handler子类的updateAdsHandler方法，处理逻辑，并响应服务器处理结果。

@Override
protected boolean updateAdsHandler(ResponseParam responseParam) {
super.updateAdsHandler(responseParam);
BaseParam param = new BaseParam();
param.setUniqueCode(responseParam.getK());
return MsgProducer.replyUpdateAds(param);
}

已有账号，立即登录