WmAceService对接文档

Last updated: ... / Reads: 89 Edit

元芒数字 i 识别服务（WmAceService）

安卓SDK接口说明文档

image-20210604131103047

Version Release v1.1.003
更新时间: 2023. 06.26

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

[TOC]

Android端SDK接口文档

一、 文档说明

1.1 版本说明

SDK版本号发布日期更新内容
v1.0.0002022.04.061. 初版SDK发布，核心算法V1
v1.0.0012022.04.081. 修复部分BUG
v1.0.0022022.04.141. 增加秤盘裁剪接口 3.5
2. 增加服务程序权限获取
v1.0.0032022.04.181. 增加获取秤盘裁剪参数接口3.4
2. 增加判断初始化是否完成接口5.7
3. 更新接口3.2
v1.0.0042022.05.201. 补充识别接口日志
v1.0.0052022.05.231. 解决离线或者局域网情况下不会向本地保存图片的问题
v1.0.0062022.05.261. 新增更新在售商品数据接口4.4
2. 优化服务程序大小
3. 更新错误码表
v1.0.0072022.07.251. 已知问题修改
v1.0.0082022.11.181. 核心算法升级V2(与旧算法不兼容)
2. 增加设置页的打开注册页面功能
3. 增加 5.8 判断服务是否安装接口
4. 更新 3.5 打开裁剪页面接口名称
5. 更新IOnDataOperate回调参数
6. 优化 4.1 和 4.2 导入导出数据的性能
7. 更新DEMO演示示例代码
8. 增加APP LOGO
9. 增加点击服务程序图标时的反馈
v1.0.0092022.12.051. 增加断开服务连接接口,已废弃
2. 扩增算法库容量
3. 增加老版本服务兼容
v1.0.0102023.01.031. 增加 4.7 自动配图接口
2. 增加 5.9 查询POS注册信息接口
3. 增加在线检测、日志上传
4. 优化算法存储策略
5. 增加Android11适配
6. 更新 4.4 不再推荐某商品接口
v1.0.0112023.02.021. 更新 3.6 识别接口返回值
v1.0.0122023.02.131. 算法容量扩容
v1.1.0012023.03.081. 核心算法升级V3（与V2、V1算法不兼容)
v1.1.0022023.04.151. 支持不规则矩形裁剪秤盘
2. 增加 5.10 SN合法性校验接口
3. 增加 4.6 预学习数据接口
4. 修复已知BUG
v1.1.0032023.06.021. 增加学习数据回传云端
2. 增加接口 4.5 根据sn码下载云端学习数据
3. 增加接口 3.8 查询设备本地激活状态
4. 增加服务程序设置页，点击程序图标即可进入
5. 修复已知BUG
6. 优化接口文档
v1.1.0042023.07.131. 增加 5.11 识别图片接口（商米需求）
2. 修改 3.5 打开秤盘裁剪页跳转的目标界面
v1.1.0052023.07.181. 新增功能：从云端下载v3向量

1.2 文档概述

此文档用于说明元芒数字（WM）i识别服务(简称WmAceService)Android系统接口开发使用，集成相关软件包，以实现相关功能的接口说明文档。

1 3 术语定义以及说明

  1. 术语说明
  • WmAceService：元芒识别服务SDK
  • WmService：预装在系统上的服务APP，用于AI识别并与SDK通信；
  1. 本文中所有传输内容均使用UTF- 8编码；
  2. 本文SDK适用于Android 5.1 以上，使用JAVA语言 1.8 版本；
  3. 本文中的WmService服务程序支持armeabi-v7a、arm64-v8a架构。

二、 继承方法说明

2.1 在工程中引入sdk

1.把WmAceService_v1.1.003 _sdk.jar放在工程libs目录下

2.module的build.gradle中添加依赖：

implementation files ('libs/WmAceService_v1.1.003_sdk.jar')

3.Android11以上，需要在AndroidManifest.xml中增加权限：

<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>

2.2 主要接口调用时序图

flowchart TB

a1(连接本地服务<br/>3.1 bindService) --> a2[初始化sdk<br/>3.2 init] --> a3{设备是否激活<br>3.8getPosActivationStatus}

b1[注册pos机<br/>3.3 initPos]

c1{秤盘是否裁剪<br/>3.4getScaleSetting} 
c2[打开秤盘裁剪页面<br/>3.5 openCropPage]

d1[识别商品<br/>3.6 autoDetect]
d2[回传识别结果<br/>3.7 setFeedBack]

e1(解绑本地服务<br/>3.9 unbindService)


a3 --> |是| c1
a3 --> |否| b1
b1 --> c1
c1 --> |是| d1
c1 --> |否| c2
c2 --> d1
d1 --> d2
d2 --> e1

2.3 主要接口调用描述

  1. 在主页面创建(onCreate)时调用 3.1 bindService接口绑定本地识别服务（需要预装WmService.apk）
  2. 绑定成功后调用 3.2 init接口初始化SDK；
  3. 首次使用需要先激活POS机，调用 3.3 initPos接口，需要传入SN、租户和POS编号，或者点击服务程序，在【注册激活】页面进行设备激活；
  4. 首次使用需要对识别范围进行裁剪，调用 3.5 openCropPage接口，打开裁剪页面，指定识别范围并保存，或者点击服务程序，在【识别区域】页面进行识别区域裁剪；
  5. 当秤盘重量变化大于 30 g时调用 3.6 autoDetect进行识别，识别结果会以商品ID列表的形式进行返回，由于该接口会耗费CPU大量资源，推荐从零点到稳重的过程中只调用一次；
  6. 当操作员对识别的结果进行确认后，请将确认的商品ID和本次识别的 sessionId通过3.7 setFeedback接口进行返回；
  7. 当主页面销毁(onDestory)后，请调用3.9 unbindService使客户端与服务程序解绑。

三、 接口说明

主流程接口

3.1 bindService（连接服务）

  • 使用场景：此接口用于绑定WmService本地服务
  • 函数名： bindService
  • 函数原型
public static void bindService(Context context, IOnWmServiceConListener listener);
  • 请求参数
请求参数必填类型描述
context是ContextContext上下文
listener是IOnWmServiceConListener本地服务连接回调
  • 返回说明
  • 请求用例
WmSDK.getInstance().bindService(mView.getContext(), new IOnWmServiceConListener() {
    @Override
    public void onConnectSuccess() {
    }
    @Override
    public void onConnectFailed() {
    }
}

3.2 init（初始化服务SDK）

  • 使用场景：此接口用于初始化服务程序
  • 函数名：init
  • 函数原型
public static int init( boolean isDebug,int modelId,float selfLearnMinScore) 

public static int initWithCallback(boolean isDebug,int modelId,float selfLearnMinScore, IOnDataOperate callback)
  • 请求参数
请求参数必填类型描述
isDebug是BooleanTrue: 正式环境；False: 测试环境
modelId是Int默认0，0：生鲜零食模式；1：农贸市场模式
selfLearnMinScore否Float默认0.8f
callback否IOnDataOperate模型加载完成的回调
  • 返回说明
返回值类型返回值说明
Int0：初始化成功1001：初始化失败1002：模型初始化失败
  • 请求用例
WmSDK.getInstance().initWithCallback(Constant.isDebug, 0, 0.8f,new IOnDataOperate.Stub(){
    @Override
    public void onSuccess() throws RemoteException {
    }

    @Override
    public void onFail(int errorCode) throws RemoteException {
    }
});

3.3 initPos（设备激活）

  • 使用场景： 此接口用于设备注册并向云端验证
  • 函数名：initPos
  • 函数原型
public static void initPos(String posCode, String tenant, String snCode, IOnBindPosCallback listener)
  • 请求参数
请求参数必填类型描述
posCode是StringPos编码
tenant是String租户代码
snCode是String激活密钥
listener是IOnBindPosCallback注册回调
  • 返回说明
  • 请求用例
WmSDK.getInstance().initPos(Constant.POS_CODE, Constant.TENANT, Constant.SN_CODE, new IOnBindPosCallback.Stub() {
    @Override
    public void bindFail(int code, String message) throws RemoteException {
    }

    @Override
    public void bindLoading() throws RemoteException {
    }

    @Override
    public void bindSuccess() throws RemoteException {
    }
});

3.4 getScaleSetting（判断识别区域是否裁剪）

  • 使用场景： 此接口用于判断识别区域是否裁剪
  • 函数名： getScaleSetting
  • 函数原型
public static boolean getScaleSetting()
  • 请求参数
  • 返回说明
返回值类型返回值说明
BooleanTrue：已裁剪；False：未裁剪
  • 请求用例
WmSDK.getInstance().getScaleSetting();

3.5 openCropPage（打开秤盘裁剪页面）

  • 使用场景：此接口用于打开服务程序的识别区域裁剪界面， 注意要在调用 3.2 init接口之后再调用
  • 函数名： cropCameraBitmap
  • 函数原型
public static void cropCameraBitmap();
  • 请求参数
  • 返回说明
  • 请求用例
WmSDK.getInstance().openCropPage();

3.6 autoDetect（商品识别）

  • 使用场景：当重量大于 30 g时或者重量稳定后变化大于 30 g时，进行商品识别
  • 函数名： autoDetect
  • 函数原型
public DetectResult autoDetect()
  • 请求参数
  • 返回说明
返回值类型返回值说明
DetectResultInt errorCode: 错误码（0为成功）；
String sessionId: 会话ID；
Long startTime: 识别开始时间戳；
List productIds: 识别结果;
float[] scores: 识别结果相似度，与productIds一一对应。
  • 请求用例
DetectResult result = WmSDK.getInstance().autoDetect();
if (result != null && result.getProductIds() != null){
	// 对识别结果进行处理
}
else{
	// 本次未识别出结果
}

3.7 setFeedBack（回传识别结果）

  • 使用场景： 当操作员对商品识别接口的返回值进行确认时，调用该接口
  • 函数名： setFeedBack
  • 函数原型
public void setFeedBack(String sessionId, String productId, String ,productName,boolean hit)
  • 请求参数
请求参数必填类型描述
sessionId是String3.6 autoDetect接口返回的会话ID
productId是String商品识别码
productName是String商品名称
hit是Boolean不再由客户端判断，直接传false即可
  • 返回说明
  • 请求用例
WmSDK.getInstance().setFeedBack(sessionId, plu, "测试商品名称", false);

3.8 getPosActivationStatus（获取设备激活状态）

  • 使用场景： 此接口用于判断设备本地是否激活
  • 函数名： getPosActivationStatus
  • 函数原型
public static boolean getPosActivationStatus()
  • 请求参数
  • 返回说明
返回值类型返回值说明
BooleanTrue：已激活；
False：未激活
  • 请求用例
WmSDK.getInstance().getPosActivationStatus();

3.9 unbindService（解除和服务的绑定）

  • 使用场景：此接口用于解绑WmService本地服务，一般在绑定服务的页面销毁时调用，保证服务程序的生命周期与客户端一致
  • 函数名： unbindService
  • 函数原型
public static void unbindService();
  • 请求参数
  • 返回说明
  • 请求用例
WmSDK.getInstance().unbindService();

数据管理接口

4.1 exportData（导出学习数据）

  • 使用场景： 将本机的学习数据以数据库形式导出，导出的文件在"/根目录/database/ExportWmAceKG.db"
  • 函数名： exportData
  • 函数原型
// /storage/emulated/0/database/ExportWmAceKG.db 
public static void exportData(IOnDataOperate listener)
  • 请求参数
请求参数必填类型描述
Listener是IOnDataOperate导出数据的结果回调

  • 返回说明

  • 请求用例

WmSDK.getInstance().exportData(new IOnDataOperate.Stub() {
    @Override
    public void onSuccess() throws RemoteException {
    }

    @Override
    public void onFail(int errorCode) throws RemoteException {
    }
});

4.2 importData（导入学习数据）

  • 使用场景： 将4.1接口导出的数据库进行导入，实现学习数据共享，导入的目录与4.1接口相同，在"/根目录/database/ExportWmAceKG.db"
  • 函数名： importData
  • 函数原型
public static int importData(boolean delete, IOnDataOperate listener)
  • 请求参数
请求参数必填类型描述
Delete是BooleanTrue: 删除原来数据False: 保留原来数据
listener是IOnDataOperate导入数据的结果回调errorCode: 4001->数据库文件不存在

  • 返回说明

  • 请求用例

WmSDK.getInstance().importData(isDelete, new IOnDataOperate.Stub() {
    @Override
    public void onSuccess() throws RemoteException {
    }

    @Override
    public void onFail(int errorCode) throws RemoteException {
    }
});

4.3 clearTrainedData（清除训练数据）

  • 使用场景： 清空本地学习数据
  • 函数名： clearTrainedData
  • 函数原型
public static void clearTrainedData()
  • 请求参数
  • 返回说明
  • 请求用例
WmSDK.getInstance().clearTrainedData();

4.4 setNoRecommend（不再推荐某商品）

  • 使用场景：删除某商品ID对应的全部学习数据
  • 函数名： setNoRecommend
  • 函数原型
public void setNoRecommend (String productId)
  • 请求参数
请求参数必填类型描述
productId是String不再推荐的商品ID
  • 返回说明
  • 请求用例
WmSDK.getInstance().setNoRecommend(plu);

4.5 downloadFeatureBySn（根据sn下载云端学习数据）

  • 使用场景： 此接口可以从云端下载对应SN下的学习数据
  • 函数名： downloadFeatureBySn
  • 函数原型
public void downloadFeatureBySn(String snCode, IOnDownloadBySnCallback callback);
  • 请求参数
请求参数必填类型描述
snCode是Stringsn码
callback是IOnDownloadBySnCallback云端下载结果回调
  • 返回说明
  • 请求用例
WmSDK.getInstance().downloadFeatureBySn(snCode, new IOnDownloadBySnCallback.Stub() {
    @Override
    public void onSuccess(int i, String s) throws RemoteException {
        mView.appendLog("返回码:"+i+",返回信息:"+s);
    }

    @Override
    public void onFailure(int i, String s) throws RemoteException {
        mView.appendLog("返回码:"+i+",返回信息:"+s);
    }
});

4.6 preLearning（预学习数据）

  • 使用场景：将传入的商品名称，与后台预设好的学习数据进行匹配，再将匹配的学习记录下载到本地
  • 函数名： preLearning
  • 函数原型
public static void preLearning(List<ProductMatch> productList, IOnPreLearningCallback callback)
  • 请求参数
请求参数必填类型描述
productList是List全部商品的PLU和名称列表
callback是IOnPreLearningCallback预学习结果回调
  • 返回说明
  • 请求用例
WmSDK.getInstance().preLearning(list, new IOnPreLearningCallback.Stub() {
    @Override
    public void onSuccess(int successNum) throws RemoteException {
        mView.appendLog(String.format("预学习成功，学习的商品数量:%s", successNum));
    }

    @Override
    public void onFailure(int code, String message, int successNum) throws RemoteException {
        mView.appendLog(String.format("预学习失败, code:%s, message:%s, 学习的商品数量:%s", code, message, successNum));
    }
});

4.7 thumbnailsAutoMatch（自动配图）

  • 使用场景： 此接口用于根据传入的商品名称，在后台进行商品预览图的匹配，并返回商品预览图url
  • 函数名： thumbnailsAutoMatch
  • 函数原型
public static void thumbnailsAutoMatch (List<ProductMatch> products, IOnAutoMatchCallBack listener)
  • 请求参数
请求参数必填类型描述
products是ListproductNumber: 商品编码productName: 商品名称
listener是IOnAutoMatchCallBack后台匹配图片完成后的回调方法
  • 返回说明
  • 请求用例
WmSDK.getInstance().thumbnailsAutoMatch(list, new IOnAutoMatchCallBack.Stub(){
    @Override
    public void onSuccess(int successNum, List<ProductMatch> data) throws RemoteException {
    }

    @Override
    public void onFailed(int failedNum) throws RemoteException {
    }
});

其他接口

5.1 setCameraId（设置摄像头ID并重启相机）

  • 使用场景： 此接口用于设置摄像头ID，默认 0
  • 函数名： setCameraId
  • 函数原型
public static void setCameraId(int cameraId)
  • 请求参数
请求参数必填类型描述
cameraId是Int摄像头位置，默认0
  • 返回说明
  • 请求用例
WmSDK.getInstance().setCameraId(position);

5.2 getScaleBitmap（获取识别区域照片）

  • 使用场景：拍摄一张识别区域的照片
  • 函数名： getScaleBitmap
  • 函数原型
public ScaleBitmap getScaleBitmap(boolean cropByScale);
  • 请求参数
请求参数必填类型描述
cropByScale是BooleanTrue：返回裁剪后的图像；
False：返回原图
  • 返回说明
返回值类型返回值说明
ScaleBitmapBitmap raw：原图；
Bitmap crop：裁剪后的图片
  • 请求用例
WmSDK.getInstance().getScaleBitmap(false);

5.3 unBindPos（解绑Pos）

  • 使用场景：调用此接口在后台将SN与设备解绑
  • 函数名： unBindPos
  • 函数原型
public static void unBindPos( String tenant, String snCode, IOnUnBindPosCallback listener)
  • 请求参数
请求参数必填类型描述
tenant是String租户代码
snCode是StringPOS的SN
listener是IOnUnBindPosCallback解绑回调
  • 返回说明
  • 请求用例
WmSDK.getInstance().unBindPos(tenant, snCode, callback);

5.4 getLocalImagePath（获取本地图片地址）

  • 使用场景：通过SessionId获取本次识别的图片路径
  • 函数名： getLocalImagePath
  • 函数原型
public static String getLocalImagePath(String sessionId)
  • 请求参数
请求参数必填类型描述
sessionId是String识别时返回的会话ID
  • 返回说明
返回值类型返回值说明
String识别的图片路径
  • 请求用例
WmSDK.getInstance().getLocalImagePath(sessionId);

5.5 startServer（启动局域网同步）

  • 使用场景： 启动局域网同步，会在新品学习时，自动传输到局域网内另一台设备上
  • 函数名： startServer
  • 函数原型
//启动服务
public static void startServer();
  • 请求参数
  • 返回说明
  • 请求用例
WmSDK.getInstance().startServer();

5.6 stopServer（停止局域网同步）

  • 使用场景： 停止该设备向局域网内其他设备同步数据
  • 函数名： stopServer
  • 函数原型
public static void stopServer();
  • 请求参数
  • 返回说明
  • 请求用例
WmSDK.getInstance().stopServer();

5.7 isInitSuccess（获取当前初始化状态）

  • 使用场景： 此接口用于获取模型初始化的状态，如果未完成初始化，识别时会报 2007 异常
  • 函数名： isInitSuccess
  • 函数原型
public static boolean isInitSuccess()

  • 请求参数

  • 返回说明

返回值类型返回值说明
booleanTrue：已完成模型初始化；
False: 未完成初始化
  • 请求用例
WmSDK.getInstance().isInitSuccess();

5.8 isServicePackageInstalled（服务是否安装）

  • 使用场景： 此接口用于检测服务程序是否安装
  • 函数名： isServicePackageInstalled
  • 函数原型
public static boolean isServicePackageInstalled(Context context);
  • 请求参数
请求参数必填类型描述
context是Context上下文
  • 返回说明
返回值类型返回值说明
booleanTrue：本地服务已安装；
False: 本地服务未安装
  • 请求用例
WmSDK.getInstance().isServicePackageInstalled(context);

5.9 queryPosByMac（根据mac查询注册信息）

  • 使用场景： 此接口用于向后台查询本机的注册信息
  • 函数名：queryPosByMac
  • 函数原型
public static void queryPosByMac (OnQueryPosRegisterInfoCallback listener);
  • 请求参数
请求参数必填类型描述
listener是OnQueryPosRegisterInfoCallback请求注册信息的回调
  • 返回说明
  • 请求用例
WmSDK.getInstance().queryPosByMac(new OnQueryPosRegisterInfoCallback.Stub(){
    @Override
    public void onSuccess(String posId, String snCode, String tenant) throws RemoteException {
    }
    
    @Override
    public void onFailed(int code, String errorMessage) throws RemoteException {
    }
});

5.10 checkSnCodeVerification（检查SnCode合法性）

  • 使用场景：此接口用于查询本机的SnCode在云端的状态
  • 函数名： checkSnCodeVerification
  • 函数原型
public static void checkSnCodeVerification(String snCode, long timeout, IOnCheckSnCodeVerificationCallback callback)
  • 请求参数
请求参数必填类型描述
snCode否String设备激活时使用的SN密钥，当传空值时，会取服务程序本地保存的SN密钥进行校验
timeout是long该接口进行请求时的网络超时时间，单位秒
callback是IOnCheckSnCodeVerificationCallback校验结果的回调
  • 返回说明
  • 请求用例
WmSDK.checkSnCodeVerification(snCode, 3L, new IOnCheckSnCodeVerificationCallback.Stub() {
    @Override
    public void onSuccess(int code, String message) throws RemoteException {
    }

    @Override
    public void onFailure(int code, String message) throws RemoteException {
    }
});

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

错误码描述解决方案
0成功
1001初始化失败
1002模型初始化失败
1003识别的Bitmap为空查看图片是否正确
1004获取图片信息失败查看图片是否正确
1005图片转化失败查看图片是否正确
1010新品写入失败
1011获取模型版本号失败
2000打开摄像头失败检查使用系统自带相机能否打开
2001wmkey.wm密钥文件不存在重新注册激活
2002Wmkey.pem密钥文件不存在重新注册激活
2003解密失败解密为空或者获取MAC地址为空
2004解密失败对比失败
2005模型识别失败传入图片模型识别失败
2006没有租户重新注册
2007没有初始化数据请调用updateLearningData接口
2008本地未找到SnCode重新注册
3001裁剪参数不规范参数应大于0
3002裁剪比例不规范未按宽高比4：3裁剪
3003未设置相机裁剪区域调用3.24openCropPage接口进行裁剪
4001数据库文件不存在
4002接口传入参数非法参数不应为空
4003WmService本地服务连接失败检查WmService是否安装启动
4004本机已有学习数据, 不需要重复导入
4005后台正在执行耗时任务
4007本机已有学习数据，无需下载
65006该POS的MAC地址绑定过其他设备
65014该SN码不存在
65017该POS的MAC地址和服务器记录的MAC地址不一致
65019该SN码未绑定
65024该SN码不属于该租户
65027该SN码未绑定
65028该SN码已被其他设备绑定
66001找不到指定的POS机

附录 2 ：用例说明

一、 识别服务序使用说明

  1. 在机器上安装WmService-v1.1.003-release.apk服务程序；
  2. 在桌面找到"识别服务"程序，点击运行（点击一次即可），如果为第一次使用，会弹出权限申请界面，请同意“相机”和“储存”权限，若系统版本为Android11及以上，需要额外同意"悬浮在其他应用上层"的权限；
  3. 授权成功后，会跳转到设置页面，请在设置页的【注册激活】和【识别区域】两个界面，完成设备激活和识别区域裁剪，若客户端APP已集成注册和裁剪功能，该步骤可跳过；
  4. 客户端启动时，服务程序会被自动调起，仅初次安装需要执行上述 2 、3两步骤；
  5. 日志文件存放在/Android/data/com.wmdigit.wmaidl/files/Log/目录下，每日的日志最多存放 7 天，服务出现异常时，若设备可以连接外网，请联系运维人员从后台拉取日志；若设备是内网环境，则麻烦手动拷贝该日志。

二、 识别接口的调用时机

  1. 重量超过30g开始触发识别；
  2. 重量稳定后，如果又发生了变化，变化值超过10g，再触发一次。这里的稳定，就是秤stable那个状态，且两次稳定的值都不为0；

三、 注意事项

  1. 除了bindService接口，其他接口所使用的回调，返回后均在子线程，请注意线程切换
  2. 相关接口使用请参考WmServiceSdkDemo工程中的代码，注意替换snCode、tenant、posCode等参数

Comments

Make a comment

  • Index