收银插件对接视频

课程简介

蜻蜓小指令接入指南

  • 2. 整体架构
  • 3. 蜻蜓小程序发送/接收小指令
  • 4. Android收银机发送/接收小指令
  • 5. Windows收银机SDK
  •  

1. 介绍

蜻蜓小指令是实现蜻蜓与其他收银设备联动的一种方法。其他收银设备可以向蜻蜓发送小指令唤起对应的程序,同时蜻蜓可以通过小指令发送数据到其他收银设备。

注意:目前有两种收银机连接方式支持小指令。

1)USB转串口线,需要点击链接单独购买。

2)蜻蜓F4蓝牙键盘,需要升级键盘固件才能支持小指令,预计十月底系统升级后可以在 系统设置 中自助升级。

2. 整体架构

2.1 概述

蜻蜓通过指定的USB转串口线等方式连接外部设备比如收银机、电脑或者通过蓝牙连接手机,两者之间可以相互发送数据。其中传输层随通信介质和平台各有不同,协议经过多层设计,不同平台及通信介质通用。

 

2.2 协议分层架构

协议根据需求不同,采用分层设计。

  1. 业务层根据业务类型不同,可以传输收款金额、28码、刷脸指令,以及小指令等。
  2. 传输层是对业务层的数据进行封包并做数据完整性可靠性验证。
  3. 安全层是对封包数据帧进行加密以及签名操作,保证数据的安全性。

2.3 数据帧格式

2.3.1 v1版本

帧结构

帧头

版本号

数据长度

数据

校验和

帧尾

长度(bytes)

3

1

4

n

1

3

2.3.2 帧格式说明

1)帧头(3字节): 0xDF 0x20 0x19

2)版本号(1字节):从1开始

3)数据长度:

4)数据:该字段为用Protobuf定义的结构,模拟键盘按键的指令示例如下

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

message TinyCommand {

  int32 version = 1;

  uint64 seq = 2;

  bool ack = 3;

  enum Type {

    HANDSHAKE = 0// 握手指令,协议内部使用,应用请勿发送

    BARCODE = 1;    // 预留

    PAY = 2;        // 收款:对应键盘收款键,独立收银场景需要传入金额

    FACE = 3;       // 刷脸:对应键盘刷脸键,独立收银场景需要先发起收款

    SETTINGS = 4;   // 设置:对应键盘设置键

    CANCEL = 5;     // 取消:对应键盘取消键

    TINY_APP = 100; // 小指令,data为json字串

  }

  Type type = 4;

  string data = 5;

}

5)校验和:0~n+7位的checksum

6)帧尾:0xFD 0x91 0x02

2.4 蓝牙BLE协议包

因为蓝牙通信不同于串口字节流模式,BLE基于特征值读写,每个包的大小有限制(通常为20bytes,可协商),所以要在串口通信的基础上进行分包并且加上相关自定义的帧头帧尾。

注意:蜻蜓自带Alipay K1蓝牙键盘需要升级固件才支持小指令通信

帧结构

功能码

session id

总包数

索引

数据

长度(bytes)

1

1

1

1

N

说明:

  • 功能码: 从F1开始,F1代表双向通信小指令
  • session id: 从0开始,当前小指令对应数据块的索引
  • 总包数:当前小指令对应的的总包数
  • 索引:当前数据包在小指令数据块中的索引
  • 数据:小指令生成的的二进制码,拆成16个字节的一个包。拆包之后如果最后一个包少于16个字节,则补0

 

3. 蜻蜓小程序发送/接收小指令

小程序可以透过 JSAPI 发送指令出去,对应的 ix API 为 tinyCommand,指令格式和代码范例如下。

指令格式

名称 类型 是否必填 描述
target string

待接收指令的对象。ix代表小程序,QT代表蜻蜓

content

Json

给对象的自定义内容

target 若为小程序,content 內容如下

1

2

3

4

5

6

# 将content内容派发给当前运行在最顶部的小程序接收

{target: 'ix', content: {...}}

# 将content内容派发给2019090909090909的小程序接收, 若不在运行状态则启动该小程序

{target: 'ix', content: {appid: 2019090909090909, wakeup: true, ...}}

# 将content内容派发给2019090909090909的小程序接收, 若不在运行状态则不派发

{target: 'ix', content: {appid: 2019090909090909, wakeup: false, ...}}

 

详细说明请参考蜻蜓小程序文档 点击访问

4. Android收银机发送/接收小指令

4.1 发送

 

1

2

3

4

5

6

// 获取TinyCommandManager实例

TinyCommandManager mCommandManager = TinyCommandManager.getInstance(this);

// 绑定服务

mCommandManager.bind();

// 调用sendCommand发送

mCommandManager.sendCommand(TinyCommandManager.COMMAND_TINY_APP, jsonContent);

 

当前可用指令类型如下,与2.4节protobuffer中Type对应

1

2

3

4

5

6

public static final int COMMAND_SEND_BARCODE = 1;

public static final int COMMAND_PAY = 2;

public static final int COMMAND_FACE_SCAN = 3;

public static final int COMMAND_SETTINGS = 4;

public static final int COMMAND_CANCEL = 5;

public static final int COMMAND_TINY_APP = 100;

 

4.2 接收

加入 BroadcastReceiver 来接收指令。

应用需要申请权限 com.alipay.iot.tinycommand.permission.RECEIVER

Intent名称

名称 类型

说明

ACTION_TINYCOMMAND string 为 intent action name,值为
com.alipay.iot.tinycommand.action.RECEIVER

EXTRA_TARGET

string

为 intent extra data name,值为

com.alipay.iot.tinycommand.extras.TARGET

EXTRA_CONTENT

string

为 intent extra data name,值为

com.alipay.iot.tinycommand.extras.CONTENT

Intent栏位说明

名称 类型 是否必填 描述
target string

欲接收指令的对象。

content

string

给对象的内容。内容为Json转换为string

参考代码

 

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

private BroadcastReceiver mReceiver = new BroadcastReceiver() {

        @Override

        public void onReceive(Context context, Intent intent) {

            Log.d(TAG, "onReceive: " + intent.getAction());

            final String target = intent.getStringExtra(TinyCommandManager.EXTRA_TINY_COMMAND_TARGET);

            final String content = intent.getStringExtra(TinyCommandManager.EXTRA_TINY_COMMAND_CONTENT);

            final String temp = target + "-->" + content;

            if (mResultView != null) {

                mResultView.setText(temp);

            }

        }

    };

 

protected void onCreate() {

    TinyCommandManager mCommandManager = TinyCommandManager.getInstance(this);

    mCommandManager.bind();

    Handler handler = new Handler();

    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {

        registerReceiver(mReceiver, filter, TinyCommandManager.PERMISSION_TINY_COMMAND_RECEIVER, handler);

    } else {

        registerReceiver(mReceiver, filter);

    }

}

 

@Override

protected void onDestroy() {

    super.onDestroy();

    mCommandManager.unbind();

    unregisterReceiver(mReceiver);

}

 4.3 Android收银机测试DEMO

  1. 用串口线连接蜻蜓与android收银机。蜻蜓上请勿插上USB调试口,部分android收银机也不能同时插USB调试口,如需要调试请用wifi adb。
  2. 在android收银机上安装iohub-pos以及iohub-demo.apk 。安装完成之后,可以在程序菜单里面点击[小指令]打开双向通信DEMO。
iohub-pos 点击下载 Android小指令应用服务
iohub-demo  iohub-demo源码、      iohub-demo.apk demo源码,及demo apk安装文件

 注:目前SDK仅支持 Android 6.0 以上的系统平台。

         3. 点击小指令后打开如下界面,可以向蜻蜓发送收款、设置、取消、刷脸这些兼容键盘操作的指令。也可以发送默认小指令唤起收银台。收银台上可以做出对应的操作(刷脸、取消),同时POS机DEMO可以收到蜻蜓回复的结果。

5. Windows收银机SDK

5.1 环境配置

Windows电脑与蜻蜓设备通过USB转串口的方式进行通信。

 注:SDK暂不支持 Windows XP 系统平台。

名称

链接/位置

备注

demo及SDK包

DuplexComm-windows-20190802.zip

双向通信sdk包,内含demo及示例代码

驱动安装

http://www.prolific.com.tw/US/ShowProduct.aspx?p_id=225&pcid=41

USB转串口驱动

VC++2017运行库

见sdk包下redist目录

sdk运行所需环境,若电脑已经安装则跳过

串口助手工具

?sscom5.13.1.zip          

参照sdk包下的testContent.txt做模拟测试使用

SimpleHIDWrite工具 SimpleHIDWrite.zip PC和蓝牙键盘模拟测试工具

5.2功能与接口

  • 支持USB口热插拔,即插即用,拔出串口或者串口出错时回调通知用户;
  • 支持同步、异步方式发送和接受数据;
  • 支持唤起刷脸、打开设置、小指令等操作;

 

导出接口定义,参见DragonflyCommApi.h。支持windows下C#、Java、C++等语言调用。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

enum ETinyCmdType {

      HANDSHAKE = 0,

      BARCODE = 1,

      PAY = 2,

      FACE = 3,

      SETTINGS = 4,

      CANCEL = 5,

      TINY_APP = 100,

      COMERR_MSG = 2019,    //异步串口操作时的错误消息提示

    };

 

    typedef void(*PDragonflyCallBack) (int iCmdType, const char* pResult);

 

    //< 打开串口同步发送,发送完毕后关闭串口

    //< 返回值:返回0成功,负数表示失败

    int ZCOMMON_EXPORT  Send2com( int tinyCmdType, const char* pData);

 

    //< 异步接受数据回调

    void ZCOMMON_EXPORT SetDragonflyCallback(PDragonflyCallBack  pCbDragonfly);

 

    int ZCOMMON_EXPORT AsyncSend2Com(int tinyCmdType, const char* pData);

 

5.3 测试示例

测试数据参见sdk包下的testContent.txt,下图所示的TINY_APP和发送数据,对应蜻蜓上的收银台。

5.3.1 SDK包测试Demo

注意:

PAY, FACE, SETTINGS, CANCEL对应模拟键盘按键的指令。HANDSHAKE可以忽略,请勿使用。

调用收银功能的json范例如下,对应的命令类型为 TINY_APP。

1

{ "target ": "QT ","content ": { "bizNo ": "123423 ", "totalAmount ": "0.01 ", "from ": "com.alipay.iot.iohub.demo ", "method ": "start "}}

5.3.2 串口助手测试示例

  • 串口波特率选择9600,无校验;
  • 由于发送的数据在内部是转为protoBuf发送的,故这里要勾选十六进制发送;

 

刷脸:DF 20 19 01 00 00 00 02 20 03 3E FD 91 02

取消:DF 20 19 01 00 00 00 02 20 05 40 FD 91 02  

设置:DF 20 19 01 00 00 00 02 20 04 3F FD 91 02

 

 

FAQ

关于此文档暂时还没有FAQ

有用(0)

所有学员评价