生鲜识别SDK使用文档

本文档主要提供给生鲜秤端APP进行调用,进而来实现商品自动识别的功能。 需要在创迹AI开放平台购买该能力后, 下载SDK进行使用。 下文中的生鲜识别, 代表生鲜智能识别。本文将指引您如何开启开发之旅 。

1、生鲜识别SDK配置文档

1.1、SDK下载

请联系客服获取SDK。

1.2、SDK接入配置

1.2.1 aar放入libs文件夹

将SDK下载到本地后将文件解压,找到里面的.arr文件,将其放入项目中的libs文件中:

1.2.2 在build.gradle中加入代码:

implementation fileTree(dir: 'libs', include: ['*.aar']) // 本地依赖
//添加dependency:
implementation 'io.reactivex:rxjava:1.1.6'
implementation 'io.reactivex:rxandroid:1.2.1'
implementation 'org.pytorch:pytorch_android:1.6.0'
implementation 'org.pytorch:pytorch_android_torchvision:1.6.0'
implementation group: 'com.google.code.gson', name: 'gson', version: '2.8.5'
implementation 'com.squareup.okhttp3:okhttp:3.12.12'
implementation group: 'org.bouncycastle', name: 'bcprov-jdk15on', version: '1.55'
implementation group: 'com.rabbitmq', name: 'amqp-client', version: '5.12.0'

1.2.3 添加对应的权限:

1.3、SDK使用流程

需要按照操作流程来,先调用初始化接口,未初始化直接调用检测将会导致程序报错。

注意点:

①初始化完毕后进行检测(可以循环调用检测),初始化一次即可,识别工作完毕后,最后进行SDK注销接口的调用。

1.4、注意事项

1.SDK是按照设备数来购买的,当一个设备使用成功后就减少一台次数,所以请合理安排设备,避免造成购买次数的浪费。

2、生鲜识别SDK接口文档

2.1、能力介绍

实时调用usb-camera进行拍照,拍照之后进行AI识别,把识别结果返回给调用者App。

2.2、调用方式

该SDK 主要用于android端,服务授权请参考[接入指南-SDK接入指南],根据指南进行服务授权,授权后进行SDK使用。

2.3、调用说明

点击下载,生鲜识别SDK。

下载完成后解压,对应文档目录:

|---libs
|    |---AISCALE-SDK-TRECHINA-release-20210823a-p.aar    生鲜识别的SDK
|---explanatoryDocument.txt            说明文件

建议硬件信息:

Android版本:6.0 +
内存:2G +

详细调用:

记录下网站下的appkey,secretkey,servicekey。
然后调用初始化接口,再调用生鲜识别接口。

2.4、接口说明

所有接口list:

NO 接口 描述
1 RetailBot_Api_Init 此接口用于初始化RetailBot所有属性,并开启后台服务
2 RetailBot_Api_UnInit 此接口用于释放RetailBot所有属性,并关闭后台服务
3 RetailBot_Api_GetSDKVersion 此接口用于获取SDK版本,在未连接设备时也可使用
4 RetailBot_Api_GetRecognizedResult 此接口用于拍照并且识别当前商品
5 RetailBot_Api_UploadReport 此接口用于回传点选结果
6 RetailBot_Api_Exec 此接口为通用指令接口
7 GetDeviceInfo 此接口用于查询当前设备的SDK版本、固件版本、 算法模型及配置表版本、SN序列号、客户编 号、 客户名称和客户状态信息等
8 ActiveDevice 此接口绑定门店与设备之间的关联。 在当前已经存在 有效门店编号的情况下,绑定失败,不生效。只有在当前 clientID为空,即出厂状 态时,才可设置成功。
9 GetImage 此指令为获取当前摄像头图片。 在秤盘标定时,需要图片作为参考
10 SetCalib 此指令为设置秤盘标定参数
11 GetCalib 此指令为获取当前使用的秤盘标定参数。 位置 参数基于1280x720分辨率,图像坐上角为坐标原点。
1.public int RetailBot_Api_Init(String companyID, String keyInfo, @NonNull String rootPath)

功能:sdk初始化,此接口用于初始化RetailBot所有属性,并开启后台服务。添加sdk认证,通过认证后,才可以继续进行初始化。

参数详解:

参数名称 是否必选 数据类型 说明
companyID string 公司标识,需要电话联系进行申请。电话:024-23782472,转AI中心 (周一至周五9:00-17:00)
keyInfo string 服务认证信息,向SDK提供者申请。格式:"{"appKey":"","appSecret":"","serviceKey":""}"
rootPath string app传输给sdk的工作目录,例如"/sdcard/aiModule"等

返回值:

返回值 含义
0 初始化成功
其他 错误码,详见错误码表
立即返回

接口调用示例:

try{
String id = "8EZXQXWzB9PDTWTSCxYEiQ==";
JSONObject keyInfo = new JSONObject();
keyInfo.put("appKey",  "ac5a7fd3-afc0-438b-b0b1-3bada1aa057e");
keyInfo.put("appSecret",  "9e192a6a-384b-4555-a851-703f103c4fcb");
keyInfo.put("serviceKey",  "1a0545d6-ea94-4595-8fd0-c653ddd73c03");
int ret = RetailBot_Api_Init(id, keyInfo.toString(),"sdcard/cache");
}catch(Exception e){
}
2.public int RetailBot_Api_UnInit()

功能:此接口用于对SDK进行注销,与初始化对应。不再需要使用SDK功能的时候,调用该接口。

返回值:

返回值 含义
0 成功
其他 错误码,详见错误码表
立即返回

接口调用示例:

int ret = RetailBot_Api_UnInit();
3.public int RetailBot_Api_GetSDKVersion(@NonNull StringBuffer sdkVersion)

功能:返回SDK版本号(此接口用于获取SDK版本,在未连接设备时也可使用)。

注:一般在连接上设备后使用 RetailBot_Api_Exec::GetDeviceInfo 获取所有信息。

返回值:

返回值 含义
0 成功
其他 错误码,详见错误码表
立即返回

接口调用示例:

StringBuffer strBuf = new StringBuffer();
int ret = RetailBot_Api_GetSDKVersion(strBuf);
4.public int RetailBot_Api_GetRecognizedResult(@NonNull StringBuffer sid, @NonNull StringBuffer result)

功能:发起生鲜识别,识别当前商品。

参数名称 是否必选 数据类型 说明
sid StringBuffer 会话ID
result StringBuffer 接收识别结果的buffer,为JSON格式,包含会话ID,商品ID 以及置信度

返回值:

返回值 含义
0 成功
其他 错误码,详见错误码表
立即返回

接口调用示例:

StringBuffer sid = new StringBuffer();
StringBuffer result = new StringBuffer(1024);
int ret = Api_GetRecognizedResult(sid,result);

返回样例:

["20191116155718582894697",  //session_id
["800116",  0.325056], //商品ID,置信度
["800115",  0.0590677],
["800148",  0.0549332],
["800126",  0.0441865],
["800144",  0.042612],
["800140",  0.0355421],
["800123",  0.00685513],
["800124",  0.00685513],
["800121",  0.00685513],
["800122",  0.00685513]]
5.public int RetailBot_Api_UploadReport(String sid ,String itemID,String weight,String inTop,String itemName) ;

功能:此接口用于回传点选结果。

参数名称 是否必选 数据类型 说明
sid String GetRecognizeResult时获得的唯一会话ID
itemID String 点选商品ID,即为店员选择的商品的ID
weight String 商品重量,单位为KG
inTop String 点选结果是否在推荐列表中(true/false)
itemName String 点选商品名称,一般为中文名

返回值:

返回值 含义
0 成功
其他 错误码,详见错误码表
立即返回

接口调用示例:

int ret = RetailBot_Api_UploadReport("20191116155718582894697","800116","3.2","true",   "西红 柿");
6.int RetailBot_Api_Exec(String strIn ,@NonNull StringBuffer strOut,int timeOut);

功能:此接口为通用指令接口。

参数名称 是否必选 数据类型 说明
strIn String 输入命令
strOut StringBuffer 指令返回结果具体内容,部分指令只返回错误码, 没有具体 内容,但是也有传入一个StringBuffer
timeOut int 命令执行超时时间,单位毫秒

返回值:

返回值 含义
0 成功
其他 错误码,详见错误码表
立即返回
7.通用指令接口之GetDeviceInfo

功能:此接口用于查询当前设备的综合信息。 如果信息没有查到,默认为空字符。

输入指令:

json key value类型 key说明
method String 指令名称 GetDeviceInfo

指令返回:

json key value类型 key说明
sn String 设备序列号
firmware_version String 设备固件版本号
model_version String 设备模型版本号 (无)
online_version String 设备配置表版本号 (无)
sdk_version String 上位机sdk版本号
clientID String 客户门店编号,出厂为空
clientName String 客户门店名称,出厂为空 (无)
clientCheck String 客户门店状态,有三种状态 “CHECKING”、"NORMAL"、"ERROR"状态, 分别表示校验中、 门店正常、门店异常。一般在clientID不为空时, 再判断该门店 状态。 (默认 NORMAL)

超时设置:建议2000ms

返回值:

返回值 含义
0 成功
其他 错误码,详见错误码表
立即返回

接口调用示例:

try{
JSONObject jo = new JSONObject();
jo.put("method",  "get_device_info");
StringBuffer strBuf = new StringBuffer(512);
int ret = RetailBot_Api_Exec(jo.toString(),strBuf,1000*2);
if(ret == 0){
JSONObject joRoot   = new JSONObject(strBuf.toString());
String clientCheck  = joRoot.getString("clientCheck");
String clientID = joRoot.getString("clientID");
String clientName   = joRoot.getString("clientName");
String firmware_version = joRoot.getString("firmware_version");
String model_version    =  joRoot.getString("model_version");
String online_version   =  joRoot.getString("online_version");
String sdk_version  = joRoot.getString("sdk_version");
String sn   = joRoot.getString("sn");
}
}catch(Exception e){
}
8.通用指令接口之ActiveDevice

功能:此接口完成设备与门店的绑定功能。 如果当前设备已经存在有效门店编号, 绑定失败, 不生效 。该指令无需理会返回字符串,绑定结果见错误码。

输入指令:

json key value类型 key说明
method String 指令名称 ActiveDevice
clientID String 需要设置的客户门店编码店铺,Code只能是长度20以内的纯数字
clientName String 需要设置的客户门店名称,如果没有门店名称,可传递clientID一致的值

指令返回:无

超时设置:建议2000ms

返回值:

返回值 含义
0 成功
其他 错误码,详见错误码表
立即返回

接口调用示例:

try{
JSONObject jo = new JSONObject();
jo.put("method", "ActiveDevice");
String clientID = “0001”;
String clientName= “xxxx超市(花园城店)”;
JSONObject joo = new JSONObject(); \
joo.put("clientID",clientID);
joo.put("clientName",clientName);
jo.put("parameters",joo);
StringBuffer strBuf = new StringBuffer();
int ret = RetailBot_Api_Exec(jo.toString(), strBuf,2000);
}catch(Exception e){
}
9.通用指令接口之GetImage

功能:此指令为获取当前摄像头图片。 在秤盘标定时,需要图片作为参考。

输入指令:

json key value类型 key说明
method String 指令名称 GetImage

指令返回:

json key value类型 key说明
ImageMD5 String 图片base64编码前的md5校验值
Image String Jpeg图片经过base64编码,分辨率1280x720

超时设置:建议13000ms

返回值:

返回值 含义
0 成功
其他 错误码,详见错误码表
立即返回

接口调用示例:

try{
JSONObject jo = new JSONObject(); jo.put("method", "GetImage");
StringBuffer strBuf = new StringBuffer(1024 * 300);
int ret = RetailBot_Api_Exec(jo.toString(), strBuf, 13000);
if (ret == 0)
{
JSONObject joRoot = new JSONObject(sb.toString());
String md5 = joRoot.getString("ImageMD5");
String imageData = joRoot.getString("Image");
}
}catch (Exception e){
}
10.通用指令接口之SetCalib

功能:此指令为设置秤盘标定参数。 位置参数基于1280x720分辨率,图像坐上角为坐标原点。 应保证left>=0 且 top>=0 且 (left+width)<1280 且 (top+height)<720。 并保证(height/width)尽量接近(3/4),比值误差<0.01(大于0.74且小于0.76)。 height应在375~600之间。 无指令返回,执行结果见 RetailBot_Api_Exec 返回值。

输入指令:

json key value类型 key说明
method String 指令名称 SetCalib

指令返回:无

方向 类型 说明
left int 秤盘框左边线位置
top int 秤盘框上边线位置
width int 秤盘框宽度
height int 秤盘框高度

超时设置:建议2000ms

返回值:

返回值 含义
0 成功
其他 错误码,详见错误码表
立即返回

接口调用示例:

try{
JSONObject jo = new JSONObject();
jo.put("method", "SetCalib");
JSONObject joo = new JSONObject();
joo.put("height",450);  // 应根据实际值,此处仅为示例
joo.put("left",100); // 应根据实际值,此处仅为示例
joo.put("top",100); // 应根据实际值,此处仅为示例
joo.put("width",600); // 应根据实际值,此处仅为示例
jo.put("parameters",joo);
StringBuffer strBuf = new StringBuffer();
int ret = RetailBot_Api_Exec(jo.toString(), strBuf, 2000);
}catch(Exception e){

}
11.通用指令接口之GetCalib

功能:此指令为获取当前使用的秤盘标定参数。 位置参数基于1280x720分辨率,图像坐上角为坐标原点。

输入指令:

json key value类型 key说明
method String 指令名称 GetCalib

指令返回

json key value类型 key说明
left int 秤盘框左边线位置
top int 秤盘框上边线位置
width int 秤盘框宽度
height int 秤盘框高度

超时设置:建议2000ms

返回值:

返回值 含义
0 成功
其他 错误码,详见错误码表
立即返回

接口调用示例:

try{
JSONObject jo = new JSONObject();
jo.put("method", "GetCalib");
StringBuffer strBuf = new StringBuffer();
int ret = RetailBot_Api_Exec(jo.toString(), strBuf, 2000);
if(ret == 0){
JSONObject joRoot = new JSONObject(strBuf);
int height = joRoot.getInt("height");
int left    = joRoot.getInt("left");
int top = joRoot.getInt("top");
int width   = joRoot.getInt("width");
}
}catch (Exception e){

}

2.5、错误码表:

Code返回码 返回码含义
-6000 无效的输入字符串
-6100 设备未初始化或者已经被拔出
-6103 摄像头丢失
-6110 固件升级中,接口暂不可用
-6111 初始化传入的目录不存在
-6112 没有读写权限
-6126 clientID格式错误
-6128 设备未激活
-6201 传入参数为空
-6500 设备正忙
-6502 算法初始化异常
-6509 初始化本地配置失败
-7001 SDK未通过认证
-7002 SDK认证出现错误