元芒数字餐饮服务（WmCateringService）Android端接口说明文档-V1.0.2.md

# 元芒餐饮服务（WmCateringService）

## 安卓SDK接口说明文档

![image-20210604131103047](http://ai-wmdigit.oss-cn-shanghai.aliyuncs.com/ai-wmdigit/1296269352764444674/20210607/1401716255961911298/image.png)

##### Version Release v1.0.2

##### 更新时间: 2024.09.24

#### 上海元芒数字科技有限公司

<div style="page-break-after: always;"></div>

[TOC]

<div style="page-break-after: always;"></div>

# Android端SDK接口文档

# 一、 文档说明

## 1.1 版本说明

| SDK版本号 | 发布日期   | 更新内容                                 |
| --------- | ---------- | ---------------------------------------- |
| 1.0.0   | 2024.07.18 | 1.餐饮识别效果演示版本                            |
| 1.0.1 | 2024.08.01 | 1.算法模块集成<br>2.相机模块集成                             |
| 1.0.2  | 2024.09.24 | 1.发版版本 |



## 1.2 文档概述

此文档用于说明元芒数字餐饮服务(WmCateringService)Android系统接
口开发使用，集成相关软件包，以实现相关功能的接口说明文档。



## 1.3 术语定义以及说明

1. 术语说明

+ WmCateringService：元芒餐饮服务

2. 本文中所有传输内容均使用UTF- 8编码；
3. 本文SDK适用于Android 11及以上，主板要求RK3568（带有NPU模块），使用JAVA 1.8 版本；
4. 本文中的服务程序支持armeabi-v7a、arm64-v8a架构。

<div style="page-break-after: always;"></div>


# 二、 调用流程

## 2.1 集成方法说明

1. 把WmCateringService_v1.0.2_sdk.jar放在工程libs目录下；
2. module的build.gradle中添加依赖：

```
Implementation files("libs/WmCateringService_v1.0.2_sdk.jar")
```
3. AndroidManifest.xml中增加权限：

```
<uses-permissionandroid:name="android.permission.QUERY_ALL_PACKAGES"/>
```
4. 若程序开启代码混淆，在防混淆文件中增加：
```
-keep public class com.wmdigit.** {*;}
```
**接口调用流程描述 **

1. 推荐在主页Activity的onCreate()中调用bindService接口，绑定本地餐饮服务（需要预装服务程序）；
2. 绑定成功后，调用init接口，对SDK进行初始化；
3. 初始化成功后，调用registerDetectionListener接口，注册识别结果的监听回调；
4. 同时，可以在Activity的onStart()和onStop()中，分别调用registerDetectionListener接口和unregisterDetectionListener接口，保证页面不可见时，不会因触发识别而占用设备性能。这两个接口具体的调用时机，可根据实际业务场景做调整；
5. 初次使用时，请调用openSettingPage接口或直接在系统桌面打开餐饮服务程序，进入设置页面，在设置页面中注册激活码和设定检测区域
6. 关于商品学习，请先调用importProducts接口，导入客户端的商品资料，然后打开餐饮服务设置页，进入数据学习页面




<div style="page-break-after: always;"></div>

# 三、 接口说明

## 主流程接口

## 3.1 bindService（绑定服务）

- 使用场景： 此接口用于绑定WmLPService本地服务,推荐在主页Activity的onCreate()中调用
- 函数名： bindService
- 函数原型

```java
public static void bindService(Context context, IOnServiceConListener listener);
```
- 请求参数

| 请求参数 | 必填 | 类型                  | 描述             |
| -------- | ---- | --------------------- | ---------------- |
| context  | 是   | Context               | Context上下文    |
| listener | 是   | IOnServiceConListener | 本地服务连接回调 |

- 返回说明

- 请求用例

```java
WmSdk.getInstance().bindService(mContext, new IOnServiceConListener() {
      @Override
      public void onConnected(ComponentName componentName, IBinder iBinder) {
      }

      @Override
      public void onDisconnected(ComponentName componentName) {
      }
});
```






## 3.2 init（初始化服务SDK）

- 使用场景：此接口用于初始化,请在服务绑定成功后调用一次
- 函数名：init
- 函数原型

```java
public static void init();
```

- 请求参数
- 返回说明
- 请求用例

```java
WmSdk.getInstance().init();
```






## 3.3 openSettingPage（打开设置页）

- 使用场景： 此接口用于打开设置页面
- 函数名： openSettingPage
- 函数原型

```java
public static void openSettingPage();
```

- 请求参数
- 返回说明
- 请求用例

```java
WmSdk.getInstance().openSettingPage();
```





## 3.4 autoDetect（商品识别）

- 使用场景： 当扫码枪收到条码时，调用此接口
- 函数名： autoDetect
- 函数原型

```java
public void autoDetect(String barcode, String plu, String sessionId);
```
- 请求参数

| 请求参数  | 必填 | 类型   | 描述                           |
| --------- | ---- | ------ | ------------------------------ |
| barcode   | 是   | String | 扫码枪接收到的条码             |
| plu       | 否   | String | 生鲜plu(仅生鲜类商品需要传plu) |
| sessionId | 否   | String | 区分相同条码的商品             |

- 返回说明
- 请求用例

```java
// 接收到的条码
String scanCode = "223057500988"; 
// 购物车中的行号,当相同barcode的商品第一次正确,第二次发生错扫,这时行号就可以区分是哪一个商品发生了错扫
String sessionId = UUID.randomUUID().toString();
// 不是生鲜码
if(){
    WmSdk.getInstance().autoDetect(scanCode, "",  sessionId);
}else { 
    // 是生鲜码
    String plu = "30575"; 
    // 从条码中解析出对应的PLU
    WmSdk.getInstance().autoDetect(scanCode, plu,  sessionId);
}
```





## 3.5 start（开启防损检测）

- 使用场景：用于开启检测，推荐在购物车页面的onResume()中调用
- 函数名：start
- 函数原型

```java
public int start(IOnAlertEventCallback callback);
```
- 请求参数

| 请求参数 | 必填 | 类型                  | 描述                                                         |
| -------- | ---- | --------------------- | ------------------------------------------------------------ |
| callback | 是   | IOnAlertEventCallback | 当发生漏扫、错扫时，通过该回调函数进行通知，通知信息存储在回调参数AlertEvent中，AlertEvent属性:<br>bitmap : 识别图片,这里如果抓图异常,可能为空 <br/>barcode : 条码<br/>plu : 生鲜码<br/>sessionId : 行号<br/>eventType : 识别类型,0错扫,1漏扫<br/>feature : 特征值 |

- 返回说明

| 返回值类型 | 说明         |
|-------|------------|
| 0     | 成功         |
| 2001  | 缺少密钥文件1    |
| 2002  | 缺少密钥文件2    |
| 2003  | 密钥文件1校验失败  |
| 2004  | 密钥文件2校验失败  |
| 2005  | 未注册        |
| 2007  | 未标定动作检测区域  |
| 2008  | 未标定物品识别区域  |
| 3001  | 摄像头USB未连接  |
| 3002  | 摄像头尚未初始化完成 |
| 3003  | 摄像头工作停止    |

- 请求用例

```java
private final IOnAlertEventCallback callback= new IOnAlertEventCallback.Stub() {
        @Override
        public void onAlertEventCallback(AlertEvent event) throws RemoteException{
            switch (alertEventBean.getScanType()){
                case 1:
                    System.out.println("漏扫回调");
                    break;
                case 0:
                    System.out.println("错扫回调");
                    break;
                default:
                    break;
            }
        }
};

int ret = WmSdk.getInstance().start(callback);
        String message = "";
        switch (ret){
            case 0: // 成功
                message = "检测开启成功";
                break;

            case 2001:
            case 2002:
                message = "缺少密钥文件，请先注册激活";
                break;

            case 2003:
            case 2004:
                message = "密钥文件校验失败";
                break;
                
            case 2005:
                message = "未注册,请先注册激活";
                break;

            case 2007:                
                message = "未设置动作检测区域";
                break;

            case 2008:
                message = "未设置物品识别区域";
                break;
                
            case 3001:
                message = "摄像头USB断开连接";
                break;

            case 3002:
                message = "摄像头工作停止";
                break;

            default:
                message = "初始化失败" + ret;
                break;
}
```



## 3.6 pause（暂停防损检测）

- 使用场景： 用于暂停检测,推荐在购物车页面的onPause()中
- 函数名：pause
- 函数原型

```Java
public void pause();
```
- 请求参数
- 返回说明
- 请求用例

```java
WmSdk.getInstance().pause();
```



## 3.7 unbindService（解绑服务）

- 使用场景： 用于解绑服务,推荐在主页Activity的onStop()中调用
- 函数名：unbindService
- 函数原型

```Java
public void unbindService();
```

- 请求参数
- 返回说明
- 请求用例

```java
WmSdk.getInstance().unbindService();
```



## 其他接口

## 4.1 feedback（保存识别结果）

- 使用场景： 用于保存识别记录
- 函数名：feedback
- 函数原型

```Java
public void feedback(DetectResult result);
```

- 请求参数

| 请求参数 | 必填 | 类型         | 描述                                                         |
| -------- | ---- | ------------ | ------------------------------------------------------------ |
| saveBean | 是   | DetectResult | 保存识别结果DetectResult的属性:<br>productId : 商品标识<br>feature : 特征值 |

- 返回说明
- 请求用例

```java
WmSdk.getInstance().feedback(result);
```



## 4.2 setAdminPassword（设置管理员密码）

- 使用场景： 用于设置管理员密码
- 函数名：setAdminPassword
- 函数原型

```Java
public void setAdminPassword(String password);
```

- 请求参数

| 请求参数 | 必填 | 类型   | 描述 |
| -------- | ---- | ------ | ---- |
| password | 是   | String | 密码 |

- 返回说明
- 请求用例

```java
WmSdk.getInstance().setAdminPassword(password);
```

<div style="page-break-after: always;"></div>

# 附录 1 ：商品识别返回错误码

| **错误码** | **描述**                          | **解决方案**    |
|---------|---------------------------------|-------------|
| 0       | 成功                              |             |
| 1001    | 初始化失败                           |             |
| 1002    | 模型初始化失败                         |             |
| 2001    | 缺少密钥文件1                         | 重新注册激活      |
| 2002    | 缺少密钥文件2                         | 重新注册激活      |
| 2003    | 密钥文件1校验失败                       | 重新注册激活      |
| 2004    | 密钥文件2校验失败                       | 重新注册激活      |
| 2005    | 未注册                             | 重新注册激活      |
| 2007    | 未标定动作检测区域                       | 设置页动作检测区域   |
| 2008    | 未标定物品识别区域                       | 设置页图像识别区域   |
| 3001    | 摄像头USB断连                        | 检查摄像头USB口连接 |
| 3002    | 摄像头尚未初始化完成                      | 等待摄像头初始化    |
| 3003    | 摄像头停止工作                         | 等待相机恢复      |
| 65006   | 此POS的MAC地址绑定过其他设备，请联系管理员确认POS编号 |             |
| 65014   | SnCode未找到                       |             |
| 65017   | 该POS的MAC地址与服务器记录的地址不同，无法解绑      |             |
| 65019   | SnCode并未绑定，无需解绑                 |             |
| 65024   | 该SN码不属于该租户                      |             |
| 65028   | 该SN码已被其他设备绑定                    |             |

# 附录 2 ：用例说明

## 一、 识别服务程序使用说明

1. 在机器上安装WmLPService-v1.3.13-release.apk服务程序
2. 初次安装后请在桌面找到元芒防损服务程序，点击运行，会弹出权限申请界
面，请同意所需权限
3. 初次使用请先打开设置页面，完成激活码注册和检测区域标定

## 二、 注意事项

1. 相关接口使用请参考演示DEMO工程中的代码