Skip to content

A
Android_Catering_service
Commit 1c36dc18 authored by 陈宇雄's avatar 陈宇雄
Browse files
Options

doc: 更新接口文档

parent 255716f8
Hide whitespace changes
Inline Side-by-side
Showing with 188 additions and 189 deletions
元芒数字餐饮服务（WmCateringService）Android端接口说明文档-V1.0.2.md
View file @ 1c36dc18
......@@ -6,7 +6,7 @@
##### Version Release v1.0.2
##### 更新时间: 2024.09.24
##### 更新时间: 2025.07.30
#### 上海元芒数字科技有限公司
......@@ -76,10 +76,6 @@ Implementation files("libs/WmCateringService_v1.0.2_sdk.jar")
3. 初始化成功后，调用registerDetectionListener接口，注册识别结果的监听回调；
4. 同时，可以在Activity的onStart()和onStop()中，分别调用registerDetectionListener接口和unregisterDetectionListener接口，保证页面不可见时，不会因触发识别而占用设备性能。这两个接口具体的调用时机，可根据实际业务场景做调整；
5. 初次使用时，请调用openSettingPage接口或直接在系统桌面打开餐饮服务程序，进入设置页面，在设置页面中注册激活码和设定检测区域
6. 关于商品学习，请先调用importProducts接口，导入客户端的商品资料，然后打开餐饮服务设置页，进入数据学习页面
<div style="page-break-after: always;"></div>
......@@ -89,12 +85,12 @@ Implementation files("libs/WmCateringService_v1.0.2_sdk.jar")
## 3.1 bindService（绑定服务）
- 使用场景： 此接口用于绑定WmLPService本地服务,推荐在主页Activity的onCreate()中调用
- 使用场景： 此接口用于绑定WmCateringService本地服务,推荐在主页Activity的onCreate()中调用
- 函数名： bindService
- 函数原型
```java
public static void bindService(Context context, IOnServiceConListener listener);
public static void bindService(Context context, IOnServiceConListener listener);
```
- 请求参数
......@@ -108,289 +104,305 @@ public static void bindService(Context context, IOnServiceConListener list
- 请求用例
```java
WmSdk.getInstance().bindService(mContext, new IOnServiceConListener() {
      @Override
      public void onConnected(ComponentName componentName, IBinder iBinder) {
      }
      @Override
      public void onDisconnected(ComponentName componentName) {
      }
WmSdk.getInstance().bindService(mContext, new IOnServiceConListener() {
@Override
public void onConnected(ComponentName componentName, IBinder iBinder) {
}
@Override
public void onDisconnected(ComponentName componentName) {
}
});
```
## 3.2 unbindService（解绑服务程序）
- 使用场景：用于解绑服务,推荐在主页Activity的onStop()中调用
- 函数名： unbindService
- 函数原型
```java
public void unbindService();
```
- 请求参数
- 返回说明
- 请求用例
```java
WmSDK.getInstance().unbindService();
```
## 3.2 init（初始化服务SDK）
## 3.3 init（初始化接口）
- 使用场景：此接口用于初始化,请在服务绑定成功后调用一次
- 函数名：init
- 函数原型
```java
public static void init();
public void init(IOnInitListener listener);
```
- 请求参数
| 请求参数 | 必填 | 类型 | 描述 |
| -------- | ---- | --------------------- | ---------------- |
| listener | 是 | IOnInitListener | 初始化回调 |
- 返回说明
- 请求用例
```java
WmSdk.getInstance().init();
WmSdk.getInstance().init(new IOnInitListener.Stub() {
@Override
public void onComplete() throws RemoteException {
log("学习数据初始化完成");
runOnUiThread(() -> {
// 接口3.5 注册识别结果回调
WmSdk.getInstance().registerDetectionListener(generateBitmap, detectionListener);
});
}
});
```
## 3.4 importProducts（导入商品资料）
- 使用场景： 导入商品资料
- 函数名： importProducts
- 函数原型
```java
public void importProducts(List<ProductsDTO> products);
```
- 请求参数
| 请求参数 | 必填 | 类型 | 描述 |
| -------- | ---- | -------------- |----------|
| products | 是 | List<ProductsDTO> | 商品信息数据数组 |
## 3.3 openSettingPage（打开设置页）
- 使用场景： 此接口用于打开设置页面
- 函数名： openSettingPage
ProductsDTO
| 参数名 | 必填 | 类型 | 描述 |
| -------- | ---- | -------------- |----------|
| productName | 是 | String | 品名 |
| productCode | 是 | String | 商品代码 |
| productMnemonicCode | 是 | String | 商品助记码 |
| unitPrice | 是 | String | 商品单价（元/份） |
| onSale | 是 | Integer | 在售状态，1：在售 2：下架 |
- 返回说明
- 请求用例
```java
log("准备导入测试用商品资料");
// 导入商品资料
List<ProductsDTO> list = new ArrayList<>();
list.add(new ProductsDTO("红烧肉", "1", "HSR", "25", 1));
WmSdk.getInstance().importProducts(list);
log("商品资料导入完成");
```
## 3.5 registerDetectionListener（注册识别结果回调）
- 使用场景： 此接口用于注册识别结果回调，注意当MainActivity初次启动时，服务未完成连接，该方法不会生效，需要在服务连接成功后，再次调用该接口注册回调
- 函数名： registerDetectionListener
- 函数原型
```java
public static void openSettingPage();
public void registerDetectionListener(boolean generateBitmap, IOnDetectionListener listener)
```
- 请求参数
| 请求参数 | 必填 | 类型 | 描述 |
| -------- | ---- | -------------- |----------|
| generateBitmap | 是 | boolean | 是否在识别时生成图片并返回，如无需展示该图片，建议关闭可以提升运算速度 |
| listener | 是 | IOnDetectionListener | 注册识别结果回调 |
- 返回说明
- 请求用例
```java
WmSdk.getInstance().openSettingPage();
WmSdk.getInstance().registerDetectionListener(generateBitmap, detectionListener);
```
## 3.6 unregisterDetectionListener（反注册识别结果回调）
- 使用场景： 此接口用于反注册识别结果回调
- 函数名： unregisterDetectionListener
- 函数原型
```java
public void unregisterDetectionListener()
```
- 请求参数
- 返回说明
- 请求用例
## 3.4 autoDetect（商品识别）
```java
WmSdk.getInstance().unregisterDetectionListener();
```
- 使用场景： 当扫码枪收到条码时，调用此接口
## 3.7 autoDetect（重新识别）
- 使用场景： 重新识别
- 函数名： autoDetect
- 函数原型
```java
public void autoDetect(String barcode, String plu, String sessionId);
public DetectResult autoDetect(boolean generateBitmap);
```
- 请求参数
| 请求参数 | 必填 | 类型 | 描述 |
| --------- | ---- | ------ | ------------------------------ |
| barcode | 是 | String | 扫码枪接收到的条码 |
| plu | 否 | String | 生鲜plu(仅生鲜类商品需要传plu) |
| sessionId | 否 | String | 区分相同条码的商品 |
| 请求参数 | 必填 | 类型 | 描述 |
| --------- | ---- | ------ |----------------|
| generateBitmap | 是 | boolean | 是否在识别时生成图片并返回，如无需展示该图片，建议关闭可以提升运算速度 |
- 返回说明
- 请求用例
```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);
}
```
log("准备重新识别");
executorService.execute(()->{
// 子线程执行识别接口
DetectResult result = WmSdk.getInstance().autoDetect(generateBitmap);
showDetectResult(result);
});
```
## 3.5 start（开启防损检测）
## 4.1 checkServiceAppInstalled（获取服务程序安装状态）
- 使用场景：用于开启检测，推荐在购物车页面的onResume()中调用
- 函数名：start
- 使用场景： 获取服务程序安装状态
- 函数名： checkServiceAppInstalled
- 函数原型
```java
public int start(IOnAlertEventCallback callback);
public boolean checkServiceAppInstalled(Context context);
```
- 请求参数
| 请求参数 | 必填 | 类型 | 描述 |
| -------- | ---- | --------------------- | ------------------------------------------------------------ |
| callback | 是 | IOnAlertEventCallback | 当发生漏扫、错扫时，通过该回调函数进行通知，通知信息存储在回调参数AlertEvent中，AlertEvent属性:<br>bitmap : 识别图片,这里如果抓图异常,可能为空 <br/>barcode : 条码<br/>plu : 生鲜码<br/>sessionId : 行号<br/>eventType : 识别类型,0错扫,1漏扫<br/>feature : 特征值 |
| 请求参数 | 必填 | 类型 | 描述 |
| --------- | ---- | ------ |----------------|
| context | 是 | Context | Context上下文 |
- 返回说明
| 返回值类型 | 说明 |
|-------|------------|
| 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;
// 接口4.1 判断服务程序是否安装
if (WmSdk.getInstance().checkServiceAppInstalled(this)) {
log("服务已安装");
}
```
## 4.2 checkServiceConnected（获取服务连接状态）
## 3.6 pause（暂停防损检测）
- 使用场景： 用于暂停检测,推荐在购物车页面的onPause()中
- 函数名：pause
- 使用场景： 获取服务连接状态
- 函数名： checkServiceConnected
- 函数原型
```Java
public void pause();
```java
public boolean checkServiceConnected()
```
- 请求参数
- 返回说明
- 请求用例
```java
WmSdk.getInstance().pause();
boolean isServiceConnected = WmSdk.getInstance().checkServiceConnected();
log("获取服务程序连接状态：" + isServiceConnected);
```
## 4.3 checkActivation（获取激活状态）
## 3.7 unbindService（解绑服务）
- 使用场景： 用于解绑服务,推荐在主页Activity的onStop()中调用
- 函数名：unbindService
- 使用场景： 获取激活状态
- 函数名： checkActivation
- 函数原型
```Java
public void unbindService();
```java
public boolean checkActivation();
```
- 请求参数
- 返回说明
- 请求用例
```java
WmSdk.getInstance().unbindService();
boolean isActivated = WmSdk.getInstance().checkActivation();
log("获取服务程序激活状态：" + isActivated);
```
## 4.4 checkCameraCrop（获取摄像头裁剪状态）
- 使用场景： 获取摄像头裁剪状态
- 函数名： checkCameraCrop
- 函数原型
```java
public boolean checkCameraCrop();
```
- 请求参数
- 返回说明
- 请求用例
## 其他接口
```java
boolean isCameraCropped = WmSdk.getInstance().checkCameraCrop();
log("获取摄像头裁剪状态：" + isCameraCropped);
```
## 4.1 feedback（保存识别结果）
## 4.5 checkLearningDataInitCompleted（获取算法初始化状态）
- 使用场景： 用于保存识别记录
- 函数名：feedback
- 使用场景： 获取算法初始化状态
- 函数名： checkLearningDataInitCompleted
- 函数原型
```Java
public void feedback(DetectResult result);
```java
public boolean checkLearningDataInitCompleted();
```
- 请求参数
| 请求参数 | 必填 | 类型 | 描述 |
| -------- | ---- | ------------ | ------------------------------------------------------------ |
| saveBean | 是 | DetectResult | 保存识别结果DetectResult的属性:<br>productId : 商品标识<br>feature : 特征值 |
- 返回说明
- 请求用例
```java
WmSdk.getInstance().feedback(result);
boolean isLearningDataInitCompleted = WmSdk.getInstance().checkLearningDataInitCompleted();
log("获取学习数据初始化状态：" + isLearningDataInitCompleted);
```
## 5.1 openSettingPage（打开设置页）
## 4.2 setAdminPassword（设置管理员密码）
- 使用场景： 用于设置管理员密码
- 函数名：setAdminPassword
- 使用场景： 此接口用于打开设置页面
- 函数名： openSettingPage
- 函数原型
```Java
public void setAdminPassword(String password);
```java
public static void openSettingPage();
```
- 请求参数
- 返回说明
- 请求用例
| 请求参数 | 必填 | 类型 | 描述 |
| -------- | ---- | ------ | ---- |
| password | 是 | String | 密码 |
```java
WmSdk.getInstance().openSettingPage();
```
## 5.2 resetCameraBackground（重置摄像头背景）
- 使用场景： 此接口用于重置摄像头背景。重置摄像头背景，请先清空摄像头下的台面
- 函数名： resetCameraBackground
- 函数原型
```java
public void resetCameraBackground();
```
- 请求参数
- 返回说明
- 请求用例
```java
WmSdk.getInstance().setAdminPassword(password);
WmSdk.getInstance().resetCameraBackground();
```
<div style="page-break-after: always;"></div>
......@@ -400,31 +412,18 @@ WmSdk.getInstance().setAdminPassword(password);
| **错误码** | **描述** | **解决方案** |
|---------|---------------------------------|-------------|
| 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码已被其他设备绑定 | |
| 2000 | 摄像头不可用 | 检查摄像头状态 |
| 2001 | 未激活 | 重新注册激活 |
| 2002 | 学习数据初始化未完成 | 初始化学习数据 |
| 2003 | 摄像头未裁剪 | 前往设置也裁剪摄像头 |
| 2004 | 区域内无对象 | 确保区域内有对象 |
# 附录 2 ：用例说明
## 一、 识别服务程序使用说明
## 一、 餐饮服务程序使用说明
1. 在机器上安装WmLPService-v1.3.13-release.apk服务程序
2. 初次安装后请在桌面找到元芒防损服务程序，点击运行，会弹出权限申请界
1. 在机器上安装WmCateringService-v1.0.2-release.apk服务程序
2. 初次安装后请在桌面找到元芒餐饮服务程序，点击运行，会弹出权限申请界
面，请同意所需权限
3. 初次使用请先打开设置页面，完成激活码注册和检测区域标定
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment