文档首页

智能娃娃机解决方案

快速入门

前言

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

协议文档

下载乐摇摇娃娃机串口通信协议

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

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

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

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

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

ee19192f5b2a427aacb3fb21bbc4418d.png

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 登录标识 小端模式传输 获取方式见登录标识
5 Check(校验) BYTE 异或校验码 校验范围:Length+ Index+ CMD+ Data
6 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

线上支付

支付流程

支付盒子

ec3fe47c00d84020bbe43ae0c5deac5c.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

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

查询与设置终端参数

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

支付盒子 -------------> 娃娃机主板

起始字节 名称 数据类型 描述 备注
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 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)在智能化产品列表中,找到需要进行自定义参数项的主板,点击“编辑”。若找不到该主板,请参照登录标识中的说明,添加需要对接的主板。

9531063777914040ae45e578c3601827.png

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

5734aa2340b945e894c35100265d7466.png

(4)界面预览

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

5bd25fc8c10a4526b620407d08fe643d.png

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

5aea59eca0664b70a6765c4bfdced908.png

abb6270dc4e142cca9ac418ab1e3464c.jpg

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

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

获取支付二维码

功能说明

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

上传账目增量

功能说明

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

2其中,故障代码可根据厂商需求,在乐摇摇后台网站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:离线

远程升级


功能说明

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

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

24d06dca6cca443881719ff46b65d56e.png

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

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

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

此时可以进行批量升级操作,一次最多添加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

已有账号,立即登录