# MinewRepeaterKit说明文档
本套SDK仅支持Minew公司出品的蓝牙传感器设备。通过SDK可以帮助开发者处理手机和传感器之间的一切工作,包括:扫描设备,广播数据、连接设备,向设备写入数据,从设备接收数据等。
目前SDK仅支持卡牌中继器的使用。
# 前期工作
整体框架:RepeaterBleManager
为设备管理类,在APP运行时始终是单例。RepeaterEntity
是设备实例类,此套件会为每一个设备生成一个实例,在扫描和连接后都会使用,内部包含设备广播数据,在扫描期间该数据会随着设备不停广播而更新。
RepeaterBleManager
:设备管理类,可以扫描周围的设备,并且可以连接它们,校验它们等;
RepeaterEntity
:扫描时获取到的卡牌中继器设备实例,继承自BaseBleDeviceEntity
;
# 导入到工程
开发环境
sdk最低支持Android 5.0,对应API Level为18。在module的
build.gradle
中设置minSdkVersion
为21或21以上android { defaultConfig { applicationId "com.xxx.xxx" minSdkVersion 21 } }
1
2
3
4
5
6
7将 jar包添加到module的libs文件夹下,并在该
module
的build.gradle
中添加如下语句(直接添加依赖):implementation files('libs/base_ble_library.jar') implementation files('libs/minew_mwc01.jar') implementation 'org.lucee:bcprov-jdk15on:1.52.0'
1
2
3或者右键该jar文件,选择
Add as Library
,添加到当前module。android { defaultConfig { ndk { abiFilters 'armeabi-v7a','arm64-v8a','x86','x86_64' } } sourceSets { main { jniLibs.srcDirs = ['libs'] } } }
1
2
3
4
5
6
7
8
9
10
11
12
13
14在
AndroidManifest.xml
需要以下权限,如果targetSdkVersion
大于23,则需要做权限管理以获取权限:<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" tools:node="replace" /> <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" tools:node="replace" /> <uses-permission android:name="android.permission.BLUETOOTH_SCAN" /> <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" /> <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" /> <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" /> <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" /> <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" /> <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 使用
sdk分为扫描、连接和读写三个阶段。
# 扫描部分
# 开始扫描
Android6.0系统以上,进行BLE扫描时,需要先申请到蓝牙权限后并且打开定位开关才能进行。
开启蓝牙扫描需要首先打开蓝牙,如果未打开蓝牙就去扫描,APP会闪退。可通过BLETool.checkBluetooth(this)来判断蓝牙是否已经打开。如果没有打开,可以先打开蓝牙。
RepeaterBleManager mBleManager = RepeaterBleManager.getInstance();
switch (BLETool.checkBluetooth(this)){
case BLE_NOT_SUPPORT:
Toast.makeText(this, "Not Support BLE", Toast.LENGTH_SHORT).show();
break;
case BLUETOOTH_ON:
//设置扫描时长5分钟,sdk默认扫描时长5分钟
mBleManager.startScan(this, new OnScanDevicesResultListener<RepeaterEntity>() {
@Override
public void onScanResult(List<RepeaterEntity> list) {
}
@Override
public void onStopScan(List<RepeaterEntity> list) {
}
});
break;
case BLUETOOTH_OFF:
Intent enableIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);
startActivityForResult(enableIntent, 4);
break;
}
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
sdk内部并没有对蓝牙扫描时长进行处理,但是扫描是耗电操作,SDK默认5分钟就停止扫描了,如果还需要继续扫描,可以提供定时器或者刷新等操作以便继续调用扫描方法继续扫描设备。
# 取出数据
在扫描期间,APP能够通过sdk获取到设备当前的一部分数据。如下所示通过RepeaterEntity
获取设备资产中继标签数据,该数据保存在广播帧对象中。
sdk提供了BaseBleDeviceEntity
作为RepeaterEntity
的基类,用于存储设备的公有数据,如下表所示:
名称 | 类型 | 说明 |
---|---|---|
macAddress | String | 设备mac |
name | String | 设备名称 |
rssi | int | 信号强度 |
BaseBleDeviceEntity
还保存了一个Map,内部用于存储其在扫描期间获取到的设备广播数据帧,可通过如下方式取出:
RepeaterEntity module;
CombinationFrame combinationFrame = (CombinationFrame) module.getMinewFrame(FrameType.COMBINATION_FRAME);
RepeaterFrame repeaterFrame = (RepeaterFrame)module.getMinewFrame(FrameType.BLUETOOTH_REPEATER_FRAME);
if (combinationFrame != null) {
//设备mac地址
String macAddress = deviceInforFrame.getMacAddress();
//电量百分比
int battery = deviceInforFrame.getBattery();
//sos状态 1触发 0正常
String sosStates = deviceInforFrame.getSosStates();
}
if (repeaterFrame != null) {
int totalNumberOfPacket = combinationFrame.getTotalNumberOfPacket();
List<RelayInformation> replayInfoList = combinationFrame.getRelayInformationLists();
for (RelayInformation information : replayInfoList) {
String mac = information.getMac();
int rssi1 = information.getRssi();
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
资产中继标签设备有2种广播帧类型。
组合帧
CombinationFrame
名称 类型 说明 battery int 电池电量百分比 macAddress String 固件mac sosStates int sos状态 1触发 0正常
中继帧
RepeaterFrame
名称 类型 说明 totalNumberOfPacket int 广播包总数,0-255超过255重置 relayInformationLists List 回复信息数据包 RelayInformation
名称 类型 说明 mac String 扫描到信标设备的mac rssi int 扫描到信标设备的rssi
# 连接
连接前一般需要先停止扫描。sdk提供了连接和断开连接方法。
RepeaterBleManager mBleManager = RepeaterBleManager.getInstance();
//停止扫描
mBleManager.stopScan(context);
//设置设备秘钥
String key="minewtech1234567";
mBleManager.setSecretKey(macAddress,key);
//连接,module为准备连接的设备
RepeaterEntity module;
mBleManager.connect(context,module);
//断开连接。macAddress为设备mac
mBleManager.disConnect(macAddress);
2
3
4
5
6
7
8
9
10
11
12
注意:连接设备前,请确认是否扫描到设备,如果没扫描到设备广播,调用连接方法,将连接失败。
在调用connect()
后,sdk中会对连接过程会有状态监听。
//设置监听器
mBleManager.setOnConnStateListener(new OnConnStateListener() {
/*
* 连接过程中的状态回调
*
* @param macAddress 设备mac
* @param connectionState 状态
*/
@Override
public void onUpdateConnState(String address, BleConnectionState state) {
switch (state) {
case Disconnect:
//连接失败或者设备断开连接会回调,主动断开不会回调该状态
break;
case Connecting:
//调用connect()后就会回调该状态
break;
case Connected:
//初步连接成功,作为一个过渡阶段,此时并未真正成功
break;
case AuthenticateFail:
//秘钥检验失败。
break;
case AuthenticateSuccess:
//秘钥检验成功,
break;
case ConnectComplete:
//连接完成,此时设备可进行读写操作
break;
default:
break;
}
}
});
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
31
32
33
34
35
36
在连接过程中,sdk会返回多个连接状态到app中,app需要做好处理。
- BleConnectionState.Connecting,BleConnectionState.Connected: 连接设备中,在这里状态下不要做耗时操作,因为此时在连接设备发现服务,并发送认证数据等。
- BleConnectionState.ConnectComplete: 此时传感器设备已经连接成功,可以进行读写操作,比如配置广播参数、传感器配置、读取历史数据等。
- BleConnectionState.AuthenticateFail:认证过程中校验秘钥,输入的秘钥不正确,将回调这个状态并且设备主动断开连接。
- BleConnectionState.AuthenticateSuccess:认证过程中校验秘钥,输入的秘钥正确,将回调这个状态。
- BleConnectionState.Disconnect: 连接失败或者设备断开连接会回调。
# 读写
读写API如下:
/**
* 设置设备秘钥
* @param macAddress 设备mac
* @param secretKey 秘钥key
* @param listener
*/
public void setSecretKey(String macAddress, String secretKey);
/**
* 查询设备版本信息
* @param macAddress 设备mac
* @param listener 监听器
*/
public void getFirmwareVersion(String macAddress, OnQueryResultListener<FirmwareVersionModel> listener);
/**
* 查询设备版本运行状态
* @param macAddress 设备mac
* @param listener 监听器
*/
public void getDeviceOperationStatus(String macAddress, OnQueryResultListener<DeviceOperationStatusModel> listener);
/**
* 查询设备蓝牙扫描开关状态
* @param macAddress 设备mac
* @param listener 监听器
*/
public void queryBleScanSwitch(String macAddress, OnQueryResultListener<Boolean> listener);
/**
* 设置设备蓝牙扫描开关状态
*
* @param macAddress 设备mac
* @param isOpen true打开蓝牙扫描,false关闭蓝牙扫描
* @param listener 监听器
*/
public void setBleScanSwitch(String macAddress, boolean isOpen, OnModifyConfigurationListener listener);
/**
* 查询广播帧广播参数
* @param macAddress 设备mac
* @param slot 查询广播的通道值,默认值slot=0 组合帧,slot=1 中继帧
* @param listener 监听器
*/
public void queryAdvParametersConfiguration(String macAddress,int slot, OnQueryResultListener<AdvParametersConfiguration> listener);
/**
* 设置广播帧广播参数
*
* @param macAddress 设备mac
* @param frameType FrameType枚举获取 getFrameTypeVersion()
* @param slotNumber 设置广播对应的通道值
* @param advertisingInterval 广播间隔 单位毫秒,广播间隔 1s ~ 60s 可调,刻度为 1s;
* @param txPower -40 -20 -16 -12 -8 -4 0 4dBm
* @param listener 监听器
*/
public void setAdvParametersConfiguration(String macAddress,String frameType, int slotNumber,int advertisingInterval, int txPower, OnModifyConfigurationListener listener);
/**
* 设置扫描参数
* @param macAddress 设备mac
* @param scanConfigurationModel 扫描参数
* @param listener 监听器
*/
public void setScanParameters(String macAddress, ScanConfigurationModel scanConfigurationModel, OnModifyConfigurationListener listener);
/**
* 查询扫描参数
*
* @param macAddress 设备mac
* @param listener 监听器
*/
public void queryScanConfiguration(String macAddress, OnQueryResultListener<ScanConfigurationModel> listenerr);
/**
* 设置设备触发器数据
* @param macAddress 设备mac
* @param triggerConfigList 触发器配置参数集合
* advertisingInterval(100ms~10000ms,step=100ms),advertisingDuration(1s~30s,step=1s) txPower (-40 ,-20, -16, -12 ,-8 ,-4, 0 ,4dBm)
* @param listener 监听器
*/
public void setTriggerConfiguration(String macAddress, List<TriggerConfigBean> triggerConfigList, OnModifyConfigurationListener listener);
/**
* 查询设备触发器数据
*
* @param macAddress 设备mac
* @param listener 监听器
*/
public void queryTriggerConfiguration(String macAddress, OnQueryResultListener<List<TriggerConfigBean>> listenerr);
/**
* 固件升级
*
* @param macAddress 设备mac
* @param isLinkUpgrade true url升级,false 固件包升级。默认值false,不支持url升级方式
* @param dfuTarget isLinkUpgrade =true, dfuTarget = 0,isLinkUpgrade =true,通过ZipUtil.getDfuTargets(zipFilePath)
* @param upgradeData 升级包数据
* @param listener 监听器
*/
public void firmwareUpgrade(String macAddress,boolean isLinkUpgrade,int dfuTarget,byte[] upgradeData, OnFirmwareUpgradeListener listener);
/**String macAddress
* 恢复出厂设置
*
* @param macAddress 设备mac
* @param listener 监听器
*/
public void reset(String macAddress, OnModifyConfigurationListener listener);
/**
* 关机
* @param macAddress 设备mac
* @param listener 监听器
*/
public void powerOff(String macAddress, OnModifyConfigurationListener listener);
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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
对部分方法进行补充说明:
设置设备秘钥,此方法调用必须在connect()方法前设置。
RepeaterBleManager mBleManager = RepeaterBleManager.getInstance(); String secretKey = "minewtech1234567" mBleManager.setSecretKey(mAddress,secretKey);
1
2
3
4查询设备版本信息。
RepeaterBleManager mBleManager = RepeaterBleManager.getInstance(); /** * 查询设备版本信息 * @param macAddress 设备mac * @param listener 监听器 */ mBleManager.queryDeviceFirmwareInfo(macAddress,new OnQueryResultListener<FirmwareVersionModel>() { @Override public void OnQueryResult(boolean b, FirmwareVersionModel firmwareVersionModel) { //b true查询成功,false查询失败firmwareVersionModel=null。 Toast.makeText(context,"Query Result:"+b,Toast.LENGTH_LONG).show(); if(b){ List<VersionInfo> versionInfoList = firmwareVersionModel.getVersionInfoList(); String firmwareName = versionInfoList.get(0).getFirmwareName(); int firmwareType = versionInfoList.get(0).getFirmwareType(); String firmwareVersion = versionInfoList.get(0).getFirmwareVersion(); } } });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19查询设备运行状态
RepeaterBleManager mBleManager = RepeaterBleManager.getInstance(); DeviceOperationStatusModel mDeviceOperationStatusModel = null; mBleManager.getDeviceOperationStatus(macAddress, new OnQueryResultListener<DeviceOperationStatusModel>() { @Override public void OnQueryResult(boolean b, DeviceOperationStatusModel deviceOperationStatusModel) { if (b) { mDeviceOperationStatusModel = deviceOperationStatusModel; } Toast.makeText(DeviceConnectedCompleteActivity.this, "Query Result:" + b, Toast.LENGTH_LONG).show(); } });
1
2
3
4
5
6
7
8
9
10
11查询和设置蓝牙扫描状态
RepeaterBleManager mBleManager = RepeaterBleManager.getInstance(); mBleManager.queryBleScanSwitch(mMac, new OnQueryResultListener<Boolean>() { @Override public void OnQueryResult(boolean b, status Boolean) { Toast.makeText(DeviceConnectedCompleteActivity.this, "Query Result:" + b, Toast.LENGTH_LONG).show(); } }); mBleManager.setBleScanSwitch(mMac, true, new OnModifyConfigurationListener() { @Override public void onModifyResult(boolean b) { Toast.makeText(DeviceConnectedCompleteActivity.this, "Set Result:" + b, Toast.LENGTH_LONG).show(); } });
1
2
3
4
5
6
7
8
9
10
11
12
13
14查询广播帧广播参数和配置广播参数。
/** * 设置广播帧广播参数 * * @param macAddress 设备mac * @param frameType FrameType枚举获取 * @param slotNumber 设置广播对应的通道值 * @param advertisingInterval 广播间隔 单位毫秒,100ms ~ 30000ms 可调,刻度为 100ms; * @param txPower -40 -20 -16 -12 -8 -4 0 4dBm * @param listener 监听器 */ RepeaterBleManager mBleManager = RepeaterBleManager.getInstance(); RepeaterEntity module String macAddress = module.getMacAddress(); //slot = 0 CombinationFrame 、slot = 1 RepeaterFrame //查询CombinationFrame广播帧广播 AdvParametersConfiguration combinationAdvParametersConfiguration = null; mBleManager.queryAdvParametersConfiguration(macAddress, 0, new OnQueryResultListener<AdvParametersConfiguration>() { @Override public void OnQueryResult(boolean b, AdvParametersConfiguration advParametersConfiguration) { if(b){ combinationAdvParametersConfiguration = advParametersConfiguration; } Toast.makeText(context,"Query Adv Result:"+b,Toast.LENGTH_LONG).show(); } }); //设置CombinationFrame广播帧参数 mBleManager.setAdvParametersConfiguration(macAddress, combinationAdvParametersConfiguration.getFrameType(), combinationAdvParametersConfiguration.getSlotNumber(), 1000,-4,new OnModifyConfigurationListener() { @Override public void onModifyResult(boolean b) { Toast.makeText(context,"Set Adv Parameters Result:"+b,Toast.LENGTH_LONG).show(); } }); //查询RepeaternFrame广播帧广播 AdvParametersConfiguration repeaterFrameAdvParametersConfiguration = null mBleManager.queryAdvParametersConfiguration(macAddress, 1, new OnQueryResultListener<AdvParametersConfiguration>() { @Override public void OnQueryResult(boolean b, AdvParametersConfiguration advParametersConfiguration) { if(b){ repeaterFrameAdvParametersConfiguration = advParametersConfiguration; } Toast.makeText(context,"Query Adv Result:"+b,Toast.LENGTH_LONG).show(); } }); //设置RepeaternFrame广播帧参数 mBleManager.setAdvParametersConfiguration(macAddress, repeaterFrameAdvParametersConfiguration.getFrameType(), repeaterFrameAdvParametersConfiguration.getSlotNumber(), 1000,-4,new OnModifyConfigurationListener() { @Override public void onModifyResult(boolean b) { Toast.makeText(context,"Set Adv Parameters Result:"+b,Toast.LENGTH_LONG).show(); } });
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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55查询设置扫描参数
RepeaterBleManager mBleManager = RepeaterBleManager.getInstance(); ScanConfigurationModel mScanConfigurationModel = null; //查询扫描参数 mBleManager.queryScanConfiguration(macAddress, new OnQueryResultListener<ScanConfigurationModel>() { @Override public void OnQueryResult(boolean b, ScanConfigurationModel scanConfigurationModel) { if (b) { mScanConfigurationModel = scanConfigurationModel; //扫描配置 ScanOptionConfig scanOption = scanConfigurationModel.getScanOptionConfig(); int scanRule = scanOption.getScanRule();//0 for and(&&), 1 for or(||) int scanInterval = scanConfigurationModel.getScanInterval(); int scanWindow = scanConfigurationModel.getScanWindow(); int scanTimeOut = scanConfigurationModel.getScanTimeOut(); //过滤设备规则 List<FilterConfig> filterList= scanConfigurationModel.getFilterList(); } Toast.makeText(DeviceConnectedCompleteActivity.this, "Query Result:" + b, Toast.LENGTH_LONG).show(); } }); //设置扫描参数 mBleManager.setScanParameters(macAddress, mScanConfigurationModel, new OnModifyConfigurationListener() { @Override public void onModifyResult(boolean b) { Toast.makeText(DeviceConnectedCompleteActivity.this, "Set Result:" + b, Toast.LENGTH_LONG).show(); } });
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查询设置设备触发器参数
RepeaterBleManager mBleManager = RepeaterBleManager.getInstance(); List<TriggerConfigBean> mTriggerConfigBeanList = new ArrayList<>(); //查询设备触发器参数 mBleManager.queryTriggerConfiguration(macAddress, new OnQueryResultListener<List<TriggerConfigBean>>() { @Override public void OnQueryResult(boolean b, List<TriggerConfigBean> triggerConfigBeanList) { if (b) { mTriggerConfigBeanList.clear(); mTriggerConfigBeanList.addAll(triggerConfigBeanList); for(TriggerConfigBean trigger:mTriggerConfigBeanList){ int advertisingInterval = trigger.getAdvertisingInterval(); int txPower = trigger.getTxPower(); int advertisingDuration = trigger.getAdvertisingDuration(); String triggerSource = trigger.getTriggerSource(); int slotNumber = trigger.getSlotNumber();// 读取广播通道下的trigger配置,以slot值校对 if(TriggerSource.DOUBLE_CLICK_TRIGGER.getTriggerValueHex().equal(triggerSource) ){ //紧急模式(双击触发模式) }else if(TriggerSource.DOUBLE_CLICK_TRIGGER.ACCELERATION_TRIGGER().equal(triggerSource) ){ //常规模式(加速度模式) }else{ } //tips:休眠模式数据,直接从广播参数读取 } } Toast.makeText(DeviceConnectedCompleteActivity.this, "Query Result:" + b, Toast.LENGTH_LONG).show(); } }); //设置设备触发器参数 mBleManager.setTriggerConfiguration(macAddress, mTriggerConfigBeanList, new OnModifyConfigurationListener() { @Override public void onModifyResult(boolean b) { Toast.makeText(DeviceConnectedCompleteActivity.this, "Set Result:" + b, Toast.LENGTH_LONG).show(); } });
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
31
32
33
34
35
36
37
38固件升级。
/** * 固件升级 * * @param macAddress 设备mac * @param upgradeData 升级包数据 * @param listener 监听器 */ mBleManager.firmwareUpgrade(mac, false,0,upgradeData, new OnFirmwareUpgradeListener() { /** * 升级包数据写入进度 */ @Override public void updateProgress(int progress) { } /** * 升级成功回调,此时设备会主动跟手机断开连接,所以会触发OnConnStateListener回调,返回 * BleConnectionState.Disconnect状态 */ @Override public void upgradeSuccess() { } /** * 升级失败 */ @Override public void upgradeFailed() { } });
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
31
32
33
34恢复出厂设置
/**
* 恢复出厂设置
*
* @param macAddress 设备mac
*/
mBleManager.reset(macAddress, new OnModifyConfigurationListener() {
@Override
public void onModifyResult(boolean success) {
}
});
2
3
4
5
6
7
8
9
10
11
关机。
/** * 关机 * * @param macAddress 设备mac */ mBleManager.powerOff(macAddress, new OnModifyConfigurationListener() { @Override public void onModifyResult(boolean success) { } });
1
2
3
4
5
6
7
8
9
10
11
# 历史记录
- **2024/6/27 添加编辑文档;