# MinewMWC03Kit 说明文档
本套 SDK 仅支持 Minew 公司出品的蓝牙设备。
通过 SDK 可以帮助开发者处理手机和蓝牙设备之间的一切工作,包括:扫描设备,广播数据、连接设备,向设备写入数据,从设备接收数据等。
目前 SDK 仅支持 4G 智能工牌设备使用。
# 前期工作
整体框架:MWC03BleManager
为设备管理类,在 APP 运行时始终是单例。MWC03Model
是设备实例类,此套件会为每一个设备生成一个实例,在扫描和连接后都会使用,内部包含设备广播数据,在扫描期间该数据会随着设备不停广播而更新。
MWC03BleManager
:设备管理类,可以扫描周围的设备,并且可以连接它们,校验它们等
MWC03Model
:扫描时获取到的 4G 智能工牌设备实例,继承自 BaseBleDeviceEntity
# 导入到工程
开发环境
SDK 最低支持 Android 5.0,对应 API Level 为 21 。在 module 的
build.gradle
中设置minSdkVersion
为 21 或 21 以上 :android { defaultConfig { applicationId "com.xxx.xxx" minSdkVersion 21 } }
1
2
3
4
5
6将 jar 包添加到 module 的 libs 文件夹下,并在该
module
的build.gradle
中添加如下语句(直接添加依赖):implementation files('libs/lib_ble_base.jar') implementation files('libs/lib_ble_mwc03.jar') implementation files('libs/lib_ble_nl.jar') implementation files('libs/lib_ble_v3.jar') api 'org.lucee:bcprov-jdk15on:1.52.0' api 'com.fasterxml.jackson.dataformat:jackson-dataformat-cbor:2.16.0'
1
2
3
4
5
6或者右键该 jar 文件,选择
Add as Library
,添加到当前module。添加 .so 库文件,App 目录下
build.gradle
添加如下配置: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在
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
# 使用
SDK 分为扫描、连接和读写三个阶段。
# Android 6.0 系统以上,进行 BLE 扫描时,需要先申请到蓝牙权限后并且打开定位开关才能进行。
# 开始扫描
Android6.0 系统以上,进行 BLE 扫描时,需要先申请到蓝牙权限后并且打开定位开关才能进行。
开启蓝牙扫描需要首先打开蓝牙,如果未打开蓝牙就去扫描,APP 会闪退。可通过 BLETool.checkBluetooth(this) 来判断蓝牙是否已经打开。如果没有打开,可以先打开蓝牙。
MWC03BleManager mBleManager = MWC03BleManager.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, 5 * 60 * 1000, new OnScanDevicesResultListener<MWC03Model>() {
@Override
public void onScanResult(List<MWC03Model> list) {
}
@Override
public void onStopScan(List<MWC03Model> 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
在扫描期间 APP 能够通过 sdk 获取到设备当前的一部分数据。如下所示通过 MWC03Model
获取设备数据,该数据保存在广播帧对象中。
SDK 提供了 BaseBleDeviceEntity
作为 MWC03Model
的基类,用于存储设备的公有数据,如下表所示:
名称 | 类型 | 说明 |
---|---|---|
macAddress | String | 设备mac |
name | String | 设备名称 |
rssi | int | 信号强度 |
BaseBleDeviceEntity
还保存了一个 Map ,内部用于存储其在扫描期间获取到的设备广播数据帧,可通过如下方式取出:
MWC03Model module;
DeviceStaticInfoFrame deviceInforFrame = (DeviceStaticInfoFrame) module.getMinewFrame(FrameType.DEVICE_INFORMATION_FRAME);
LTEDeviceFrame lteDeviceFrame = (LTEDeviceFrame) module.getMinewFrame(FrameType.LET_DEVICE_FRAME);
if (deviceInforFrame != null) {
//设备mac地址
String macAddress = deviceInforFrame.getMacAddress();
//电量百分比
int battery = deviceInforFrame.getBattery();
//固件版本
String firmwareVersion = deviceInforFrame.getFirmwareVersion();
}
if (lteDeviceFrame != null) {
//蜂窝信号强度:数值范围 -140 到 0 —> 越接近 0,信号越强
float signalStrength = lteDeviceFrame.getSignalStrength();
//纬度信息
float latitude = lteDeviceFrame.getLatitude();
//经度信息
float longitude = lteDeviceFrame.getLongitude();
//海拔信息
float altitude = lteDeviceFrame.getAltitude();
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
4G 智能工牌设备有2种广播帧类型。
设备静态信息帧
DeviceStaticInfoFrame
名称 类型 说明 frameVersion int 设备类型 firmwareVersion String 固件版本 batteryLevel int 电池电量百分比 macAddress String 固件mac peripheralSupportInfo PeripheralSupportInfo 外设支持描述,包含设备产品id
蜂窝信息帧
LTEDeviceFrame
名称 类型 说明 signalStrength int 蜂窝信号强度 latitude double 纬度信息 longitude double 经度信息 altitude double 海拔信息
# 连接
连接前一般需要先停止扫描 ,SDK 提供了连接和断开连接方法。
MWC03BleManager mBleManager = MWC03BleManager.getInstance();
//停止扫描
mBleManager.stopScan(context);
//设置设备秘钥
String key="minewtech1234567";
mBleManager.setSecretKey(macAddress,key);
//连接 : module 为准备连接的设备
MWC03Model module;
mBleManager.connect(context,module);
//断开连接 :macAddress 为设备 mac
mBleManager.disConnect(macAddress);
2
3
4
5
6
7
8
9
10
11
注意:连接设备前,请确认是否扫描到设备,如果没扫描到设备广播,调用连接方法,将连接失败。
在调用 connect()
后,SDK 中会对连接过程会有状态监听。
//设置监听器
mBleManager.setOnConnStateListener(new OnConnStateListener() {
/*
* 连接过程中的状态回调
* @param macAddress 设备mac
* @param BleConnectionState 状态
*/
@Override
public void onUpdateConnState(String address, BleConnectionState state) {
switch (state) {
case Connecting:
//调用connect()后就会回调该状态
break;
case Connected:
//初步连接成功,作为一个过渡阶段,此时并未真正成功
break;
case EnterAuthenticatePassword:
//V3 协议设备会要求输入设备连接密码,并且超时时间为 30s
//这里需要通过弹窗或者其他界面交互方式要求客户输入设备连接密码
//e.g. showDialog -> input password ->
//设置用户输入的设备秘钥,并发起鉴权
String key="minewtech1234567";
mBleManager.setSecretKey(macAddress,key);
mBleManager.authenticateV3Password(mwC03Model)
break;
case Bond_None:
//NanoLink 协议设备配对回调,此处为无效配对状态
break;
case Bond_Bonding:
//NanoLink 协议设备配对回调,此处为正在配对状态
break;
case Bond_Bonded:
//NanoLink 协议设备配对回调,此处为配对完成状态
//NanoLink 协议设备配对完成,才能通过 MWC03BleManager 中提供的方法操作 NanoLink 协议设备
break;
case AuthenticateFail:
//V3 协议设备秘钥检验失败
break;
case AuthenticateSuccess:
//V3 协议设备秘钥检验成功
break;
case ConnectComplete:
//V3 协议设备连接完成,才能通过 MWC03BleManager 中提供的方法操作 V3 协议设备
break;
case Disconnect:
//连接失败或者设备断开连接会回调,主动断开不会回调该状态
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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
在连接过程中,sdk会返回多个连接状态到app中,app需要做好处理。
- BleConnectionState.Connecting,BleConnectionState.Connected: 连接设备中,在这里状态下不要做耗时操作,因为此时在连接设备发现服务,并发送认证数据等。
- BleConnectionState.EnterAuthenticatePassword: V3 协议类型设备需提示用户输入连接秘钥,通过 MWC03BleManager 的 setSecretKey 方法传入用户输入的密码,然后调用 MWC03BleManager 的 authenticateV3Password 方法进行鉴权。
- BleConnectionState.Bond_None: NanoLink 协议设备配对无效状态。
- BleConnectionState.Bond_Bonding: NanoLink 协议设备正在配对状态。
- BleConnectionState.Bond_Bonded: NanoLink 协议设备配对完成状态,NanoLink 协议设备配对完成,才能通过 MWC03BleManager 中提供的方法操作 NanoLink 协议设备。
- BleConnectionState.ConnectComplete: V3 协议设备已经连接成功,可以进行读写操作,比如配置广播参数、读取历史数据等。
- BleConnectionState.AuthenticateFail:设备认证过程中校验秘钥,输入的秘钥不正确,将回调这个状态并且设备主动断开连接。
- BleConnectionState.AuthenticateSuccess:设备认证过程中校验秘钥,输入的秘钥正确,将回调这个状态。
- BleConnectionState.Disconnect: 连接失败或者设备断开连接会回调。
# 设备配置读取写入操作
设备配置读取写入操作 API 如下,使用 MWC03BleManager mBleManager = MWC03BleManager.getInstance() 对象调用完成:
/**
* 清空扫描设备列表
*/
void clearScanResult();
/**
* 设置默认扫描时长
*
* @param scanTime 扫描时长,单位为 ms
*/
void setDefaultScanTime(int scanTime);
/**
* 开始扫描设备
*
* @param context 上下文
* @param listener 监听器
*/
void startScan(Context context, OnScanDevicesResultListener listener) ;
/**
* 开始扫描设备
*
* @param context 上下文
* @param scanTime 扫描时长,单位 ms
* @param listener 监听器
*/
void startScan(Context context, int scanTime, OnScanDevicesResultListener listener) ;
/**
* 停止扫描设备
*
* @param context 上下文
*/
void stopScan(Context context) ;
/**
* 判断是否正在扫描
*
*/
boolean isScanning() ;
/**
* 设置 V3 协议设备的连接秘钥
*
* @param macAddress 设备 mac 地址
* @param key 设备秘钥
*/
void setSecretKey(String macAddress, String key) ;
/**
* 恢复出厂设置
*
* @param macAddress 设备mac
* @param listener 监听器
*/
void reset(String macAddress, OnModifyConfigurationListener listener);
/**
* 关机
*
* @param macAddress 设备mac
* @param listener 监听器
*/
void powerOff(String macAddress, OnModifyConfigurationListener listener);
/**
* 重启
*
* @param macAddress 设备mac
* @param listener 监听器
*/
void reboot(String macAddress, OnModifyConfigurationListener listener);
/**
* 连接设备
*
* @param context 上下文
* @param macAddress 设备mac
*/
void connect(Context context, String macAddress);
/**
* 连接设备
*
* @param context 上下文
* @param module 设备实体
*/
void void connect(Context context, MWC03Model module);
/**
* 断开连接
*
* @param macAddress 设备mac
*/
void void disConnect(String macAddress);
/**
* 设置设备连接监听器
*
* @param listener 监听器
*/
void setOnConnStateListener(OnConnStateListener listener)
/**
* V3 协议设备固件升级
*
* @param macAddress 设备mac
* @param isLinkUpgrade :true url升级,false 固件包升级。默认值false,不支持url升级方式
* @param dfuTarget isLinkUpgrade =true, dfuTarget = 0
* @param upgradeData 升级包数据
* @param listener 监听器
*/
void firmwareUpgrade(String macAddress,boolean isLinkUpgrade,int dfuTarget,byte[] upgradeData, OnFirmwareUpgradeListener listener);
/**
* V3 协议设备与 NanoLink 协议设备固件升级
*
* @param macAddress 设备mac
* @param isLinkUpgrade :true url升级,false 固件包升级。默认值false,不支持url升级方式
* @param dfuTarget isLinkUpgrade =true, dfuTarget = 0 (用于 V3 协议设备升级,NanoLink 协议设备升级无效)
* @param upgradeData 升级包数据(用于 V3 协议设备升级,NanoLink 协议设备升级可以为空)
* @param listener 监听器
* @param firmwareUpgradeConfig (用于 NanoLink 协议设备升级配置对象,V3 协议设备升级可以为空)
*/
void combineFirmwareUpgrade(String macAddress,boolean isLinkUpgrade,int dfuTarget,byte[] upgradeData, OnFirmwareUpgradeListener listener,FirmwareUpgradeConfig firmwareUpgradeConfig);
//关于 FirmwareUpgradeConfig 类简要内容【NanoLink 协议升级使用该配置对象】
public class FirmwareUpgradeConfig {
//公共使用:Context
private Context context;
//公共使用:mac地址
private String macAddress;
public static final String URL_LINK_MODEM = "Modem";
public static final String URL_LINK_APP = "APP";
//链接升级方式使用:升级的固件模块名称,默认:URL_LINK_APP,可选URL_LINK_APP,URL_LINK_MODEM
private String upGradeFwName;
//链接升级方式使用:升级的固件url
private String path;
//文件升级方式使用:发送的文件内容
private byte[] fileContent = null;
}
/**
* 设置蜂窝APN参数
*
* @param macAddress 设备mac
* @param PDAType PDAType 类型
* @param apnName apn 名称
* @param listener 监听器
*/
void setLteAPN(String macAddress, PDAType PDAType, String apnName, OnModifyConfigurationListener listener);
/**
* 设置蜂窝APN参数
*
* @param macAddress 设备mac
* @param PDAType PDAType 类型
* @param apnName apn 名称
* @param authType 鉴权类型:默认 "None",1 为 "PAP",2 为 "CHAP"
* @param userName 用户名称
* @param passWord 鉴权秘钥
* @param listener 监听器
*/
void setLteAPN(String macAddress, PDAType PDAType, String apnName,int authType,String userName,String passWord, OnModifyConfigurationListener listener);
/**
* 获取蜂窝APN参数
*
* @param macAddress 设备mac
* @param listener 监听器
*/
void getLteAPN(String macAddress, OnQueryResultListener<LTEAPNModel> listener);
//关于 LTEAPNModel 类简要内容
public class LTEAPNModel {
//默认无鉴权类型
public static final int NO_USE_AUTH_TYPE = 255;
//【v3 协议】pda类型
private PDAType pdnType ;
//apn名称
private String apnName;
//IP地址
private String ipAddress;
//【v3 协议】鉴权类型
private int authentication;
//用户名
private String userName;
//密码
private String passWord;
//【NanoLink 协议】pda类型
private String type;
//【NanoLink 协议】鉴权类型
private String auth;
}
/**
* 查询固件版本
*
* @param macAddress 设备mac
* @param listener 监听器
*/
void getFirmwareVersion(String macAddress, OnQueryResultListener<FirmwareVersionModel> listener);
//关于 FirmwareVersionModel 类简要内容
public class FirmwareVersionModel {
List<VersionInfo> versionInfoList;
}
//关于 VersionInfo 类简要内容
public class VersionInfo {
// 固件名称
private String firmwareName;
// 固件类型
private int firmwareType;
// 固件版本
private String firmwareVersion;
// 固件插槽
private String slot;
}
/**
* 查询网络类型
*
* @param macAddress 设备mac
* @param listener 监听器
*/
void getNetworkType(String macAddress, OnQueryResultListener<NetworkType> listener);
/**
* 设置网络类型
*
* @param macAddress 设备mac
* @param networkType 网络类型
* @param listener 监听器
*/
void setNetworkType(String macAddress, NetworkType networkType, OnModifyConfigurationListener listener);
/**
* 连接鉴权
*
* @param module 设备实体对象
*/
void authenticateV3Password(@NonNull MWC03Model module);
/**
* OTA 固件升级文件格式验证使用【V3 协议设备】
*
* @param macAddress 设备mac
* @param zipFilePath zip格式文件路径
* @param dfuProductIdTypes zip格式文件中对应允许通过的产品 ID 集合
*/
boolean verifyOtaFile(String macAddress,String zipFilePath,List<String> dfuProductIdTypes);
/**
* 获取证书文件上传路径【NanoLink 协议设备】
*
* @param macAddress 设备mac
* @param listener 监听器
*/
void getCertificatesPath(String macAddress, OnQueryResultListener<CertificatesPathInfo> listener);
/**
* 上传证书文件【NanoLink 协议设备】
*
* @param macAddress 设备mac
* @param fileUploadConfig 文件上传配置
* @param onFileUploadListener 上传处理监听器
*/
void updateCertificates(String macAddress, FileUploadConfig fileUploadConfig, OnFileUploadListener onFileUploadListener);
//关于 FileUploadConfig 类简要内容
public class FileUploadConfig {
//设备端存储文件的路径,通过getCertificatesPath()方法获取
private String devicePath = null;
//设备端存储文件的名称,ca.pem类型文件使用"ca" ,client.pem类型文件使用"cert",client.key类型文件使用"priv"
private String deviceFileName = null;
//文件上传使用:Context
private Context context;
//文件上传使用:mac地址
private String macAddress;
//文件上传使用:发送的文件内容
private byte[] fileContent = null;
}
/**
* 设置 MQTT 连接参数【NanoLink 协议设备】
*
* @param macAddress 设备mac
* @param MQTTNanoLink MQTT配置
* @param listener 监听器
*/
void setMQTTConnection(String macAddress, MQTTNanoLink MQTTNanoLink, OnModifyConfigurationListener listener);
/**
* 设置 MQTT 主题参数【NanoLink 协议设备】
*
* @param macAddress 设备mac
* @param MQTTNanoLink MQTT配置
* @param listener 监听器
*/
void setMQTTTopic(String macAddress, MQTTNanoLink MQTTNanoLink, OnModifyConfigurationListener listener);
/**
* 获取 MQTT 连接参数【NanoLink 协议设备】
*
* @param macAddress 设备mac
* @param listener 监听器
*/
void getMQTTConnection(String macAddress, OnQueryResultListener<MQTTNanoLink> listener);
/**
* 获取 MQTT 主题参数【NanoLink 协议设备】
*
* @param macAddress 设备mac
* @param listener 监听器
*/
void getMQTTTopic(String macAddress, OnQueryResultListener<MQTTNanoLink> listener);
//关于 MQTTNanoLink 类简要内容
public class MQTTNanoLink {
//数据上报URL
private String url = "";
//数据上报端口号
private String port = "8883";
//mqtt 服务质量级别
private int qos = 0;
//心跳间隔
private int intvl = 0;
//客户端ID
private String client_id = "";
//用户名
private String usrname = "";
//密码
private String pwd = "";
//是否启用了SSL/TLS,"None"为不启用,"TLS"为启用
private String sec = "";
//数据上报主题
private String notify = "";
//命令控制主题
private String req = "";
//命令控制响应主题
private String rsp = "";
}
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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
对部分方法进行补充说明:
让一些蜂窝网络配置生效指令,这个指令非常重要,需要在配置 MQTT ,APN 等与设备网络相关参数 API 调用成功之后使用,使设备网络相关参数配置生效:
/** * 网络配置生效指令 * * @param macAddress 设备 mac * @param listener 监听器 * * 在调用 setLteAPN,setNetworkType,updateCertificates,setMQTTConnection,setMQTTTopic 方法成功之后必须调用此方法一次 * */ void networkConfigOn(String macAddress, OnNetworkConfigOnListener listener);
1
2
3
4
5
6
7
8
9
10
11固件升级。
/** * 固件升级 * * @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
# 文档更新记录
- 2025/06/11 新增 MWC03 设备操作基本功能 API