智能有屏售货机系列解决方案

快速入门

前言

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

适用范围：方案适用于有屏售货机、口红机、售货机等自助零售设备

协议文档

下载乐摇摇有屏售货机串口通信协议

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

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

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

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

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

SDK

下载串口与函数SDK

串口调测功工具

下载乐摇摇串口调试助手

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

开发流程

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

对接流程	参考文档
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位。

通信机制

主机查询方式

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

正常通信时序：

异常通信时序：

终端上传数据帧方式

正常通信时序：

异常通信时序：

数据帧格式

帧格式图

格式说明

起始字节	名称	定义	数据类型	备注
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

功能与指令

功能指令文档简介

进行有屏售货机/零售机串口协议对接之前，您需要先了解娃娃机的串口功能指令。

功能指令	参考文档
设备登录	查看设备登录指令文档
终端参数	查看终端参数指令文档
有屏售货机主扫支付	查看有屏售货机主扫支付指令文档
有屏售货机反扫支付	查看有屏售货机反扫支付指令文档
远程上分	查看远程上分指令文档
上传账面增量	查看上传账面增量指令文档
查询网络信号	查看查询网络信号指令文档
扩展指令	查看查看扩展指令文档

设备登录

登录流程

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

支付盒子 -------------> 售货机主板

起始字节	名称	数据类型	描述	备注
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

指令说明——同步本地通道信息

售货机主板 ------------->支付盒子

起始字节	名称	数据类型	描述	备注
0	Head(帧头)	BYTE	0xAA
1	Length(长度)	BYTE	0xXX	以实际情况为准
2	Index (索引)	BYTE	0x02	标识售货机主板
3	CMD(命令)	BYTE	0xC9	售货机特定指令
4	Data(数据)	见表1		见表1
4+n	Check(校验)	BYTE	异或校验码	校验范围：Length+ Index+ CMD+ Data
14	End(帧尾)	BYTE	0xDD

表1支付盒子获取设备状态指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——同步本地通道信息	BYTE	0x02
Data[1-2]	通道总数	WORD	0x0000-0xFFFF；小端模式传输
Data[3-4]	通道序号	WORD	0x0000-0xFFFF；小端模式传输
Data[5-8]	购买价格	DWORD	单位：分；游戏出礼模式下置0
Data[9-12]	游戏价格	DWORD	单位：分；购买出礼模式下置0
Data[13-14]	通道货品数量	WORD	0x0000-0xFFFF；小端模式传输
Data[15-16]	通道货品容量	WORD	0x0000-0xFFFF；小端模式传输
Data[17]	通道名称字段长度	BYTE
Data[18-n]	通道名称	BYTE[n]	支持GB18030，ASCII编码 注意：本字段长度需与Data[17]中数值保持一致

支付盒子 -------------> 售货机主板

起始字节	名称	数据类型	描述	备注
0	Head(帧头)	BYTE	0xAA
1	Length(长度)	BYTE	0x0C
2	Index (索引)	BYTE	0x01	标识盒子主机
3	CMD(命令)	BYTE	0xC9	售货机特定指令
4	Data(数据)	见表2		详见表2
13	Check(校验)	BYTE	异或校验码	校验范围：Length+ Index+ CMD+ Data
14	End(帧尾)	BYTE	0xDD

表2支付盒子获取设备状态指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——获取设备状态	BYTE	0x01
Data[1-6]	支付唯一码	BYTE[6]	每个支付流程的支付唯一码不改变
Data[7-8]	预留	WORD	取值0x00-0xFFFF；小端模式传输

登录标识

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

标识码获取流程

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

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

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

主板信息填写与要求：

1主板名称格式为厂家名称+设备类型，例如：乐摇摇有屏售货机

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

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

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

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

终端参数

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

支付盒子 -------------> 售货机主板

起始字节	名称	数据类型	描述	备注
0	Head(帧头)	BYTE	0xAA
1	Length(长度)	BYTE	0x03
2	Index (索引)	BYTE	0x01	标识盒子主机
3	CMD(命令)	BYTE	0x05	查询终端参数
-	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	0x05	查询终端参数
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	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	0x02	标识售货机主板
3	CMD(命令)	BYTE	0x15	设置终端参数
4	Data(数据)	BYTE	参数设置结果	0x00：设置失败 0x01：设置成功
5	Check(校验)	BYTE	异或校验码	校验范围：Length+ Index+ CMD+ Data
6	End(帧尾)	BYTE	0xDD

自定义终端参数项

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

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

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

（4）界面预览

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

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

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

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

有屏售货机指令集

---

指令综述

有屏售货机指令集中指令CMD皆为0xC9，通过对数据区进行定制实现不同命令，利用其首位的子命令标识码区分，详情见下文指令说明

通用框架

支付盒子 -------------> 售货机主板

起始字节	名称	数据类型	描述	备注
0	Head(帧头)	BYTE	0xAA
1	Length(长度)	BYTE	0xXX	以实际情况为准
2	Index(索引)	BYTE	0x01	标识盒子主机
3	CMD(命令)	BYTE	0xC9	售货机特定指令
4	Data(数据)	详见后文		详见后文
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	0xC9	售货机特定指令
4	Data(数据)	详见后文		详见后文
4+N	Check(校验)	BYTE	异或校验码	校验范围：Length+ Index+ CMD+ Data
5+N	End(帧尾)	BYTE	0xDD

有屏售货机主扫支付

支付流程

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

售货机主板 -------------> 支付盒子 获取二维码支付链接指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——获取二维码支付链接	BYTE	0x0A
Data[1-6]	支付唯一码	BYTE[6]	每个支付流程的支付唯一码不改变 若线下启动则随机产生唯一码
Data[7-10]	本次支付总金额	DWORD	单位：分 0x0000表示支付失败

支付盒子 -------------> 售货机主板 获取二维码支付链接应答指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——获取二维码支付链接	BYTE	0x0A
Data[1-n]	二维码链接数据	BYTE[n]	通用格式：http://m.leyaoyao.com/lyy/t/<设备号>

指令说明——获取设备状态

支付盒子 -------------> 售货机主板 获取设备状态指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——获取设备状态	BYTE	0x01
Data[1-6]	支付唯一码	BYTE[6]	每个支付流程的支付唯一码不改变
Data[7-8]	预留	WORD	0x0000-0xFFFF；小端模式传输

售货机主板 -------------> 支付盒子 获取设备状态应答指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——获取设备状态	BYTE	0x01
Data[1-6]	支付唯一码	BYTE[6]	每个支付流程的支付唯一码不改变
Data[7]	设备状态	BYTE	0x00:空闲状态 0x01:支付状态（显示二维码后进 入此状态） 0x02:故障状态 0x03:游戏状态 0x04:其他状态
Data[8]	预留	BYTE

指令说明——上报上分结果

售货机主板 -------------> 支付盒子 上报上分结果指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——上报上分结果	BYTE	0x04
Data[1-6]	支付唯一码	BYTE[6]	每个支付流程的支付唯一码不改变
Data[7-10]	支付总金额	DWORD	单位：分 0x0000表示支付失败

支付盒子 -------------> 售货机主板 上报上分结果应答指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——上报上分结果	BYTE	0x04
Data[1-6]	支付唯一码	BYTE[6]	每个支付流程的支付唯一码不改变
Data[7-10]	支付总金额	DWORD	单位：分 0x0000表示支付失败

指令说明——同步支付结果

支付盒子 -------------> 售货机主板 同步支付结果指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——同步支付结果	BYTE	0x03
Data[1-6]	支付唯一码	BYTE[6]	每个支付流程的支付唯一码不改变
Data[7-10]	支付总金额	DWORD	单位：分 数值为0表示支付失败
Data[11]	中奖概率	BYTE	0xFF表示无效
Data[12]	用户ID字段长度	BYTE
Data[13-n]	用户ID	BYTE[n]	注意：本字段长度需与Data[12]中数值保持一致

售货机主板 -------------> 支付盒子 同步支付结果应答指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——同步支付结果	BYTE	0x03
Data[1-6]	支付唯一码	BYTE[6]	每个支付流程的支付唯一码不改变
Data[7-10]	核对金额结果	DWORD	单位：分 0x0000表示支付失败

指令说明——上报交易结果（线上支付）

售货机主板 -------------> 支付盒子 上报交易结果（线上支付）指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——上报交易结果（线上支付）	BYTE	0x09
Data[1-6]	支付唯一码	BYTE[6]	每个支付流程的支付唯一码不改变
Data[7-10]	本次支付总金额	DWORD	单位：分 0x0000表示支付失败
Data[11-14]	退款总金额	DWORD
Data[15-16]	出礼品通道个数	WORD	未出礼仍需上报，但此项置0
Data[17-18]	出礼品通道序号	WORD	未出礼则上报所选通道序号
Data[19-20]	购买礼品数量	WORD
Data[21-22]	出礼品数量	WORD	未出礼仍需上报，但此项置0
Data[23-26]	累计出礼品数量	DWORD
Data[27-30]	购买价格	DWORD	单位：分 通过游戏出礼时此项置0
Data[31-34]	游戏价格	DWORD	单位：分 通过购买出礼时此项置0

支付盒子 -------------> 售货机主板 上报交易结果（线上支付）应答指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——上报交易结果 （线上支付）	BYTE	0x09
Data[1-6]	支付唯一码	BYTE[6]	每个支付流程的支付唯一码不改变

指令说明——上报交易结果（线下支付）

售货机主板 -------------> 支付盒子 上报交易结果（线下支付）指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——上报交易结果（线下支付）	BYTE	0x06
Data[1-6]	预留	BYTE[6]	填充随机数
Data[7-10]	本次支付总金额	DWORD	单位：分 0x0000表示支付失败
Data[11-12]	出礼品通道个数	WORD	未出礼仍需上报，但此项置0
Data[13-14]	出礼品通道序号	WORD
Data[15-16]	出礼品数量	WORD	未出礼仍需上报，但此项置0
Data[17-20]	累计出礼品数量	DWORD
Data[21-24]	购买价格	DWORD	单位：分 通过游戏出礼时此项置0
Data[25-28]	游戏价格	DWORD	单位：分 通过购买出礼时此项置0
Data[29-32]	此通道支付累计金额	DWORD	单位：分

支付盒子 -------------> 售货机主板 上报交易结果（线下支付）应答指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——上报交易结果（线下支付）	BYTE	0x06
Data[1-6]	预留	BYTE[6]

有屏售货机反扫支付

支付流程

指令说明——上传扣款金额（反扫设备）

售货机主板 -------------> 支付盒子 上传扣款金额指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——上传扣款金额	BYTE	0x0B
Data[1-6]	随机数	BYTE[6]
Data[7-10]	本次支付总金额	DWORD	单位：分 0x0000表示支付失败

支付盒子 -------------> 售货机主板 上传扣款金额应答指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——上传扣款金额	BYTE	0x0B
Data[1-6]	随机数	BYTE[6]

同步通道坐标

功能说明

此指令用于同步售货机的通道坐标与通道序号间对应关系，消息总长所限，一次最大同步20条货道。

指令说明——同步货道坐标

售货机主板 -------------> 支付盒子 同步货道坐标指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——同步货道坐标	BYTE	0x10
Data[1-2]	本条指令所含通道总数	WORD	取值小于等于20
Data[3-4]	通道序号	WORD	通道坐标信息1
Data[5]	通道行坐标	BYTE
Data[6]	通道列坐标	BYTE
Data[7-8]	通道序号	WORD	通道坐标信息2
Data[9]	通道行坐标	BYTE
Data[10]	通道列坐标	BYTE
……

支付盒子 -------------> 售货机主板 同步货道坐标应答指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——同步货道坐标	BYTE	0x10
Data[1-2]	本条指令所含通道总数	WORD	取值小于等于20
Data[3-4]	通道序号1	WORD
Data[5-6]	通道序号2	WORD
……

通道使能

功能说明

此指令对应设备管理后台中，货道管理内对个别货道的启用/禁用选项，商户可利用该指令禁用故障货道，未启用的货道将不会再货道商品管理内显示。

指令说明

支付盒子 -------------> 售货机主板 通道使能指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——通道使能	BYTE	0x11
Data[1-6]	指令唯一码	BYTE[6]
Data[7-8]	通道序号1	WORD
Data[9]	行坐标	BYTE
Data[10]	列坐标	BYTE
Data[11]	使能	BYTE	0x00：停用 0x01：启用

售货机主板 -------------> 支付盒子 通道使能应答指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——通道使能	BYTE	0x11
Data[1-6]	指令唯一码	BYTE[6]

远程上分

---

功能说明

本功能用以实现由商户直接控制售货机出货，日常交易中不会涉及。有屏售货机点击货道测试时，盒子会向主板下发此指令消息。

指令说明——远程上分

支付盒子 -------------> 售货机主板

起始字节	名称	数据类型	描述	备注
0	Head(帧头)	BYTE	0xAA
1	Length(长度)	BYTE	0xXX	以实际情况为准
2	Index(索引)	BYTE	0x01	标识盒子主机
3	CMD(命令)	BYTE	0xC9	售货机特定指令
4	Data(数据)	见表3.6.2.1		见表3.6.2.1
14	Check(校验)	BYTE	异或校验码	校验范围：Length+ Index+ CMD+ Data
15	End(帧尾)	BYTE	0xDD

表3.6.2.1 远程上分指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——远程上分	BYTE	0x0D
Data[1-6]	订单号	BYTE[6]
Data[7-8]	通道号	WORD	小端模式传输
Data[9]	上分模式	BYTE	0x00：游戏启动 0x01：商品出货

售货机主板 -------------> 支付盒子

起始字节	名称	数据类型	描述	备注
0	Head(帧头)	BYTE	0xAA
1	Length(长度)	BYTE	0xXX	以实际情况为准
2	Index(索引)	BYTE	0x02	标识售货机主板
3	CMD(命令)	BYTE	0xC9	售货机特定指令
4	Data(数据)	见表3.6.2.2		见表3.6.2.2
11	Check(校验)	BYTE	异或校验码	校验范围：Length+ Index+ CMD+ Data
12	End(帧尾)	BYTE	0xDD

表3.6.2.2 远程上分应答指令数据区说明

数据字段	名称	数据类型	备注
Data[0]	子命令 ——远程上分	BYTE	0x0D
Data[1-6]	订单号	BYTE[6]

上传账目增量

功能说明

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

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

创建故障参数

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

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

3有屏售货机（售货机、礼品机）主板上报故障代码后，可以在乐摇摇手机后台的消息通知中接收到对应的故障信息，如下图所示

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

售货机主板 ------------->支付盒子

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

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

数据字段	名称	数据类型	备注
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(数据)	见表4		详见表4
6	Check(校验)	BYTE	异或校验码	校验范围：Length+ Index+ CMD+ Data
7	End(帧尾)	BYTE	0xDD

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

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

扩展指令

功能说明

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

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

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

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

指令说明——扩展指令

支付盒子 ------------->售货机主板

起始字节	名称	数据类型	描述	备注
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

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

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	设备类型， SHJ 售货机
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初始化成功后，自身机制管理与服务器链接状态，自动发起随机数获取、登陆、货到上传流程，完成服务器约定的设备初始化流程。 步骤如下：

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

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

货道上传 详见“上传货道信息”说明

扫码支付

用户点击商品生成二维码进行支付操作，程序要严谨处理支付逻辑、出礼和退款操作。

1请求生成二维码，显示到终端屏幕；

方法名称：MsgProducer.getPayCode(GetPayCodeParam param);。

详细参数说明如下：

参数名称	参数说明
selectChannels	选择的货道信息，每个元素分别表示一个货道的选择情况，元素内容为 仓位id,购买数量, 单价组成，例 1,2,300 表示第一货道需要购买两每个3元；多个货道信息使用”;”分隔。
isGaming	表示是否是玩游戏，如果是玩游戏 则上面 单价 表示游戏的价格
uniqueKey	随机生成，作为支付事务校验唯一码，在支付结果回调，启动结果上传都需要使用到该 唯一码

代码示例：

public static boolean getPayCode() {

System.out.println("获取支付二维码......");

GetPayCodeParam param = new GetPayCodeParam();

param.setUniqueKey(UUID.randomUUID().toString());

param.setSelectChannels(Arrays.asList("2,2,2;1,1,1"));

param.setIsGaming(true);

return MsgProducer.getPayCode(param);

}

代码示例：二维码请求参数返回处理，重写handler子类的qrCodeHandler方法，完成显示逻辑。

@Override

protected boolean qrCodeHandler(ResponseParam responseParam) \{

QrCodeResp resp = getResp(responseParam, QrCodeResp.class);

System.out.println(String.format("get 设备注册二维码为：%s", gson.toJson(resp)));

return true;

}

2监听用户支付返回消息，启动终端出礼设备；

用户支付成功后，服务会下发消息通知到APP，开发者需要重写handler子类的payResultHandler方法，完成显示逻辑。

代码示例：

@Override

protected boolean payResultHandler(ResponseParam responseParam) \{

System.out.println(String.format("支付结果为：%s", gson.toJson(responseParam)));

// 完成设备相关的启动逻辑

return true;

}

扫码支付流程时序图如下：

反扫信息上传

接口名称：MsgProducer.reportReversePayInfo(ReportReversePayInfoParam param)

详细参数说明如下：

参数名称	参数说明
List<PayInfoChannelParam>	商品选择信息列表 【每个元素为: 仓位，数量，金额】（例：1,2,12）
isGaming	是游戏还是购买，默认购买
qrCode	反扫码信息
uniqueKey	生成支付二维码唯一码：本次生成在后面的 支付结果下发，启动结果上传 中使用

说明：设备发起该请求，服务端会直接发起支付扣款。如果设备间隔3分钟后都未收到支付结果通知，则视为支付失败。

代码示例：

public static boolean reversePay(String authcode) {
ReportReversePayInfoParam param = new ReportReversePayInfoParam();
param.setIsGaming(false);
param.setQrCode(authcode);
param.setUniqueKey(UUID.randomUUID().toString());
List<PayInfoChannelParam> payInfoChannelParams = new ArrayList<>();
PayInfoChannelParam payInfoChannelParam = new PayInfoChannelParam();
payInfoChannelParam.setAmount("2");
payInfoChannelParam.setChannelNo("4");
payInfoChannelParam.setCount("2");
PayInfoChannelParam payInfoChannelParam1 = new PayInfoChannelParam();
payInfoChannelParam1.setAmount("1");
payInfoChannelParam1.setChannelNo("3");
payInfoChannelParam1.setCount("1");
payInfoChannelParams.add(payInfoChannelParam1);
payInfoChannelParams.add(payInfoChannelParam);
param.setDetails(payInfoChannelParams);
return MsgProducer.reportReversePayInfo(param);
}

支付结果通知

详见扫码支付

启动状态上报

终端用户支付成功，本地成启动设备并通知服务器当前设备的启动状态。

当前接口是必须实现的功能接口，启动状态（成功/失败）作为退款依据！

方法名称：MsgProducer.eqStartResult(EqStartResultParam param)。

详细参数说明如下：

参数名称	参数说明
isSuccess	表示设备启动成功或者失败
uniqueCode	用户支付结果通知中获取到的 k
channels	启动失败，退款仓位列表：仓位，数量，金额。

代码示例如下：

public static boolean eqStartResult(String key) {

System.out.println("设备启动失败上传...");

EqStartResultParam param = new EqStartResultParam();

param.setUniqueCode(key);

param.setIsSuccess(false);

// 退款金额

List<String> strs = new ArrayList<String>();

strs.add("3,1,5");

strs.add("2,1,4");

param.setChannels(strs);

MsgProducer.eqStartResult(param);

return true;

}

设备上报结果返回处理：

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

/**

* 设备启动结果上传 结果返回

*

* @param responseParam

*@return

**/

@Override

protected boolean eqStartResultReHandler(ResponseParam responseParam) {

System.out.println(String.format("get 设备启动结果上传返回结果为：%s", gson.toJson(responseParam)));

return true;

}

上传货道信息

方法名称：MsgProducer.updloadMainboardInfo(UpdloadMainboardInfoParam param)。

设备初始化、货道信息变更的情况下，必须调用本接口上传货道信息。

支付环节进行货道参数校验，如果缺少货道信息会引发支付异常。

详细参数说明如下：

参数名称	参数说明
mainPosition	货道id 对于设备唯一
produceName	商品名称 售卖商品的名称
gamePrice	货道游戏价格
buyPrice	商品购买价格
Probability	游戏概率
Capture	容量
Stock	库存
uniqueCode	上传事务随机码（重复上传时使用同一个随机码）

代码示例：

public static boolean uploadMainboard(String mp) {

System.out.println("上传仓位信息......：" + mp);

int max = Integer.valueOf(mp);

for (int i = 1 ; i <= max ; ++i) {

String key = UUID.randomUUID().toString();

UploadMainboardInfoParam param = new UploadMainboardInfoParam();

param.setUniqueCode(key);

param.setStock("10");

param.setCapture("50");

param.setProbability("10");

param.setBuyPrice("2000");

param.setGamePrice("100");

param.setProductName("暂无");

param.setMainPosition(i + "");

param.setProductCost("500");

param.setPicture("https://picture");

param.setPositionName("仓位名");

param.setPositionStatus("1");

MsgProducer.uploadMainboardInfo(param);

}

return true;

}

重写handler接口setMainboardHandler方法处理服务器下发通知消息。

示例代码：

@Override

protected boolean setMainboardHandler(ResponseParam responseParam) {

SetMainboardResp resp = getResp(responseParam, SetMainboardResp.class);

System.out.println(String.format("set 设置仓位信息：%s", gson.toJson(resp)));

return true;

}

设置仓位信息

重写handler子类的setMainboardHandler方法，完成显示逻辑。

代码示例如下：

@Override
protected boolean setMainboardHandler(ResponseParam responseParam) {
SetMainboardResp resp = getResp(responseParam, SetMainboardResp.class);
System.out.println(String.format("set 设置仓位信息：%s", gson.toJson(resp)));
return true;
}

批量设置仓位信息

重写handler子类的setMainboardHandler方法，完成显示逻辑。

代码示例如下：

@Override
protected boolean batchSetMainboardHandler(ResponseParam responseParam) {
BatchSetMainboardResp resp = getResp(responseParam, BatchSetMainboardResp.class);
System.out.println(String.format("set 批量设置仓位信息：%s", gson.toJson(resp)));
return true;
}

线下投币

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

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

详细参数说明如下：

参数名称	参数说明
mainPosition	仓位编号：正整数，对设备唯一
coinsInc	投币增量：本次投币数量
coinsTotal	投币总量：设备投币总量（当该数大于上次上传的投币总量时：本次投币数量=本次投币总量-上次投币总量，否则：本次投币数量=投币增量）

代码示例如下：

public static boolean uploadCoins(String total, String inc) {

System.out.println("上传投币信息......");

String key = UUID.randomUUID().toString();

UploadCoinsParam param = new UploadCoinsParam();

param.setUniqueCode(key);

param.setMainPosition("2");

param.setCoinsTotal(total);

param.setCoinsInc(inc);

MsgProducer.uploadCoins(param);

return true;

}

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

@Override

protected boolean uploadCoinsResultHandler(ResponseParam responseParam) {

System.out.println(String.format("get 上传投币信息返回结果为：%s", gson.toJson(responseParam)));

return true;

}

设备退礼

上传设设备仓位的退礼信息到服务器，存档对应的退礼数据。

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

详细参数说明如下：

参数名称	参数说明
mainPosition	货道的唯一编号
giftInc	退礼增量
giftTotal	退礼总量
uniqueCode	上传事务随机码：没有收到响应消息，重复上传情况下请使用同一个随机码。
originType	退礼来源：GAME=游戏退礼，BUY=购买退礼，RD=远程上分退礼

代码示例如下：

public static boolean uploadGift() {

System.out.println("上传礼品信息");

String key = UUID.randomUUID().toString();

UploadGiftParam param = new UploadGiftParam();

param.setUniqueCode(key);

param.setGiftTotal("2");

param.setGiftInc("2");

param.setMainPosition("4");

param.setOriginType("BUY");

MsgProducer.uploadGift(param);

System.out.println("上传礼品信息......");

key = UUID.randomUUID().toString();

param = new UploadGiftParam();

param.setUniqueCode(key);

param.setGiftTotal("1");

param.setGiftInc("1");

param.setMainPosition("3");

MsgProducer.uploadGift(param);

return true;

}

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

重写handler子类的uploadGiftResultHandler方法，接收退礼上报结果。

代码示例：

@Override

protected boolean uploadGiftResultHandler(ResponseParam responseParam) \{

System.out.println(String.format("上传退礼信息返回结果为：%s", gson.toJson(responseParam)));

return true;

}

 

设备绑定

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

操作成功后，服务器下发的设备消息到安卓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;

}

B端设置操作

B端是指公众号【设备管理系统】提供的商户后台管理系统，提供一系列的设备管理、经营统计、会员管理等相关的管理工具和数据统计功能。

通过一些的设备管理操作功能，实现对联网设备的动态管理和监控，提供运营效率。

B端界面：

参数设置

商户在公众号后台设置设备参数，服务器下发消息到终端APP，开发者需要重写handler的setEquipmentParamHandler方法，实现设备参数同步。

示例代码：

@Override

protected boolean setEquipmentParamHandler(ResponseParam responseParam) {

System.out.println(String.format("set 参数设置通知：%s", gson.toJson(responseParam)));

List<SetEquipmentParamResp> resps = getRespList(responseParam, SetEquipmentParamResp.class);

System.out.println(String.format("解析参数为：%s", gson.toJson(resps)));

// 实现参数同步逻辑

return true;

}

参数查询

方法名：getEquipmentParam(GetEquipmentParamParam param)

参数详细说明：

参数名称	参数说明
uniqueCode	uuid

代码示例：

public static boolean getEquipmentParam() {
System.out.println("获取设备参数设置......");
GetEquipmentParamParam param = new GetEquipmentParamParam();
param.setUniqueCode(UUID.randomUUID().toString());
MsgProducer.getEquipmentParam(param);
return true;
}

重写handler子类的getEquipmentParamHandler方法，接收返回结果。

@Override
protected boolean getEquipmentParamHandler(ResponseParam responseParam) {
System.out.println(String.format("获取设备参数设置结果返回：%s", gson.toJson(responseParam)));
return true;
}

自定义参数查询

方法名：reportCustomizeEquipmentParam()

参数详细说明：

参数名称	参数说明
uniqueCode	指令唯一码：由 服务器 随机生成下发
f	查询功能码
i	参数序号，从0开始
v	参数值，参数值换算成标准的类型值
vt	参数类型，开放平台自定义参数设置的类型

重写handler子类的setCustomizeEquipmentParamHandler方法，接收服务器发送过来的功能码，并查询相应的参数，上报。

代码示例：

@Override
protected boolean queryCustomizeEquipmentParamHandler(ResponseParam responseParam) {
System.out.println(String.format("查询设备自定义参数：%s", gson.toJson(responseParam)));
CustomizeQueryEquipmentParam resp = getResp(responseParam, CustomizeQueryEquipmentParam.class);
System.out.println(String.format("解析参数为: %s", gson.toJson(resp)));
return true;
}

响应服务器，上报自定义参数：

代码示例：

private static boolean uploadCustomEquipmentParamQuery(String function,String key){
ReportCustomizeEquipmentParamParam param = new ReportCustomizeEquipmentParamParam();
param.setUniqueCode(key);
CustomizeEquipmentParam detail = new CustomizeEquipmentParam();
detail.setF(function);
List<CustomizeEquipmentFunctionCodeParam> fcs = new ArrayList<>();
fcs.add(new CustomizeEquipmentFunctionCodeParam("0","1","int"));
fcs.add(new CustomizeEquipmentFunctionCodeParam("1","6","int"));
detail.setD(fcs);
param.setDetail(detail);
System.out.println("获取自定义参数设置结果:" + new Gson().toJson(detail));
return MsgProducer.reportCustomizeEquipmentParam(param);
}

自定义参数设置

方法名：setCustomizeEquipmentParamResult

参数详细说明：

参数名称	参数说明
uniqueCode	uuid

重写handler子类的setCustomizeEquipmentParamHandler方法，接收自定义参数并设置，并响应服务器。

代码示例：

@Override
protected boolean setCustomizeEquipmentParamHandler(ResponseParam responseParam) {
System.out.println(String.format("设置设备自定义参数：%s", gson.toJson(responseParam)));
CustomizeEquipmentParam resp = getResp(responseParam, CustomizeEquipmentParam.class);
System.out.println(String.format("解析参数为: %s", gson.toJson(resp)));
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;
}

远程上分

方法名：reportRemoteDivision

详细参数说明：

参数名称	参数说明
i	仓位编号
t	上分模式：0=游戏启动，1=商品出货
uniqueCode	指令唯一码：由 服务器 生成下发

重写handler子类的remoteDivisionHandler方法，进行上分操作，并上报上分结果。

代码示例：

@Override
protected boolean remoteDivisionHandler(ResponseParam responseParam) {
LogUtil.printLog("接收到远程上分消息", ClientConstants.LogLevel.INFO);
RemoteDivisionResp resp = getResp(responseParam, RemoteDivisionResp.class);
RemoteDivisionParam param = new RemoteDivisionParam();
param.setI(resp.getI());
param.setT(resp.getT());
param.setUniqueCode(responseParam.getK());
//上分逻辑

...
return MsgProducer.reportRemoteDivision(param);

说明：当设备发生吃币时，商户可以在设备管理后台通过该指令对具体的仓位进行远程游戏启动或者出货。设备在接收到该通知后应立即响应rast指令再进行后续操作。如果服务端5s内接收不到设备响应的rasr指令，则会重发该通知（k不变），最多重发3次。

注意：远程上分暂时不支持设备启动结果处理，服务端接收到rasr指令后统一按启动成功处理。

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);
}

仓位状态下发

方法名：replyOpenPositionNotice

详细参数说明：

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

重写handler子类的openPositionNoticeHandler方法，更新仓位状态，并响应服务器处理结果。

代码示例：

@Override
protected boolean openPositionNoticeHandler(ResponseParam responseParam) {
System.out.println("货道开启关闭通知");
super.openPositionNoticeHandler(responseParam);
OpenPositionNoticeResp resp = getResp(responseParam, OpenPositionNoticeResp.class);

// 处理

...
ReplyOpenPositionNoticeParam param = new ReplyOpenPositionNoticeParam();
param.setUniqueCode(responseParam.getK());
return MsgProducer.replyOpenPositionNotice(param);
}

仓位状态 查询/设置

方法名：applyOpenPosition

参数详细说明：

参数名称	参数说明
o	操作：put=设置，get=查询
i	仓位id
s	仓位状态：0=关闭，1=开启
k	指令唯一码：由 client 生成

代码示例：

private static boolean reportOpenPosition(String o) {
System.out.println("货道开启关闭上传，查询");
ApplyOpenPositionParam param = new ApplyOpenPositionParam();
param.setI("1");
param.setO(o);
param.setS("0");
param.setK("888888");
return MsgProducer.applyOpenPosition(param);
}

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

代码示例：

@Override
protected boolean openPositionResultHandler(ResponseParam responseParam) {
System.out.println("货道开启关闭查询/设置");
OpenPositionResultResp resp = getResp(responseParam, OpenPositionResultResp.class);
return super.openPositionResultHandler(responseParam);
}

电机测试

方法名：replyMotorTestNotice(ReplyMotorTestNoticeParam)

详细参数说明：

参数名称	参数说明
i	仓位编号
s	状态 1 成功 0 失败

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

代码示例：

@Override
protected boolean motorTestHandler(ResponseParam responseParam) {
System.out.println("电机测试");
MotorTestNoticeResp resp = getResp(responseParam, MotorTestNoticeResp.class);
return super.motorTestHandler(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);
}

上传礼品信息

方法名：reportGiftInfo

参数详细说明：

参数名称	参数说明
ci	礼品id（设备上的）
si	礼品id（服务器上的）。创建时可以没有
n	礼品名称
i	礼品图片
p	商品成本（分）
o	put
uniqueCode	指令唯一码：由 client 生成

代码示例：

private static boolean reportGiftInfo(String o) {
System.out.println("上传礼品信息");
ReportGiftInfoParam param = new ReportGiftInfoParam();
param.setCi("g001");
// param.setSi("1000023");
param.setI("https://img.leyaoyao.com");
param.setN("测试礼品T5");
param.setP("1000");
param.setUniqueCode("123456");
param.setO(o);
return MsgProducer.reportGiftInfo(param);
}

说明：如果5s内接收不到服务器响应的rgr指令，则需要重发该通知（uniqueCode不变），最多重发3次

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

@Override
protected boolean giftInfoReportResultHandler(ResponseParam responseParam) {
System.out.println("礼品信息上传结果返回");
GiftInfoReportResultResp resp = getResp(responseParam, GiftInfoReportResultResp.class);
return super.giftInfoReportResultHandler(responseParam);
}

下发礼品信息

方法名：replyGiftInfoNotice

参数详细说明：

参数名称	参数说明
ci	礼品id（设备上的）
si	礼品id（服务器上的）。创建时可以没有
n	礼品名称
i	礼品图片
p	商品成本（分）
uniqueCode	指令唯一码：由 服务器 生成

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

@Override
protected boolean giftInfoNoticeHandler(ResponseParam responseParam) {
System.out.println("礼品设置");
GiftInfoNoticeResp resp = getResp(responseParam, GiftInfoNoticeResp.class);
return super.giftInfoNoticeHandler(responseParam);
}

开门操作

商户在B端点击补货， 服务器下发设备参数到终端，开发者重写handler的openDoorHandler方法，解析仓位列表参数，打开对应的仓门。

示例代码如下：

@Override

protected boolean openDoorHandler(ResponseParam responseParam) {

System.out.println(String.format("set 开门通知：%s", gson.toJson(responseParam)));

List<OpenDoorResp> resps = getRespList(responseParam, OpenDoorResp.class);

System.out.println(String.format("解析参数为：%s", gson.toJson(resps)));

return true;

}

33.补货/清货操作

商户在B端点击补货/清货（参考下图操作界面），服务器下发消息通知到APP。开发者重写handler的addOrcleanStockHandler方法进行数据处理，参数包括补货的仓位列表、数量，打开对应的仓门进行补货。

示例外码如下：

@Override

protected boolean addOrCleanStockHandler(ResponseParam responseParam) {

System.out.println(String.format("set 补货/清货通知：%s", gson.toJson(responseParam)));

List<AddOrCleanStockResp> resps = getRespList(responseParam, AddOrCleanStockResp.class);

System.out.println(String.format("解析参数为：%s", gson.toJson(resps)));

return true;

}

设备Android主板接入方案

方案介绍

模组名称：有屏售货机Android板

主板图片：

方案概述：通过串口进行数据交互，与设备双向通讯：向设备发送控制指令、接受设备上报数据。不容易受到干扰，传输数据准确率高。方案优点是不受限于SOC片上资源、应用扩展度高；

适用设备：有屏售货机

联网方式：2G/4G/wifi

连接方式：与设备传感器连接

工厂开发：基于Android板与控制板通讯指令开发