# Minew Repeater Kit Instruction document
This SDK only supports the Bluetooth devices from Minew. The SDK helps developers to handle everything between the phone and the device, including: scanning the device, broadcasting data, connecting to the device, writing data to the device, receiving data from the device, etc.
# Preliminary work
Overall framework: MBT02RepeaterBleManager
is the device management class, which is always a single instance when the app is running. MBTRepeaterEntity
is the device instance class, this suite generates an instance for each device, which is used after scanning and connecting, and contains device broadcast data inside, which will be updated during scanning as the device keeps broadcasting.
MBT02RepeaterBleManager
:Device management class that scans the surrounding mbt02 devices and can connect them, verify them, etc.;
MBTRepeaterEntity
:Example of an mbt02 sensor device acquired during scanning, inherited fromBaseBleDeviceEntity
;
# Import to project
Development Environment
The minimum sdk support is Android 5.0, corresponding to API Level 21. set
minSdkVersion
to 21 or above inbuild.gradle
of the module.android { defaultConfig { applicationId "com.xxx.xxx" minSdkVersion 21 } }
1
2
3
4
5
6
7Add jar to the module's libs folder and add the following statement to the
build.gradle
of themodule
(add the dependency directly):implementation files('libs/base_ble_library.jar') implementation files('libs/minew_mbt02.jar') implementation 'org.lucee:bcprov-jdk15on:1.52.0'
1
2
3Or right-click the jar file and select
Add as Library
to add it to the current module.Add the configuration to the.so library file in the App directory 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
13
14The following permissions are required in
AndroidManifest.xml
, and iftargetSdkVersion
is greater than 23, you need to do permission management to get the permissions.<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
# Use
The sdk is divided into three phases: scanning, connecting, and reading and writing.
# Scanning section
# Start scannin
For Android 6.0 and above systems, when performing BLE scanning, you need to apply for Bluetooth permission and turn on the positioning switch before proceeding.
To enable Bluetooth scanning, you need to turn on Bluetooth first. If you scan without turning on Bluetooth, the APP will crash. You can use BLETool.checkBluetooth(this) to determine whether Bluetooth is turned on. If it is not turned on, you can turn on Bluetooth first.
MBT02RepeaterBleManager mBleManager = MBT02RepeaterBleManager.getInstance();
switch (BLETool.checkBluetooth(this)){
case BLE_NOT_SUPPORT:
Toast.makeText(this, "Not Support BLE", Toast.LENGTH_SHORT).show();
break;
case BLUETOOTH_ON:
//Set the scan time to 5 minutes. The default scan time of SDK is 5 minutes.
mBleManager.startScan(this, new OnScanDevicesResultListener<MBTRepeaterEntity>() {
@Override
public void onScanResult(List<MBTRepeaterEntity> list) {
}
@Override
public void onStopScan(List<MBTRepeaterEntity> 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
The SDK does not process the Bluetooth scanning duration internally, but scanning is a power-consuming operation. The SDK stops scanning after 5 minutes by default. If you still need to continue scanning, you can provide a timer or refresh operation to continue calling the scanning method to continue scanning the device.。
# Retrieve data
During the scan, the APP is able to get a part of the current data of the device through the sdk. The data of the device is obtained throughMBTRepeaterEntity
as shown below, which is stored in the broadcast frame object.
The sdk provides BaseBleDeviceEntity
as the base class of MBTRepeaterEntity
to store the public data of the sensor device as shown in the following table.
Name | Type | Description |
---|---|---|
macAddress | String | device mac |
name | String | Device name |
rssi | int | Signal strength |
BaseBleDeviceEntity
also keeps a Map, which is used internally to store the device broadcast data frames it acquires during a scan, and can be retrieved as follows
MBTRepeaterEntity module;
CombinationFrame combinationFrame = (CombinationFrame) module.getMinewFrame(FrameType.COMBINATION_FRAME);
RepeaterFrame repeaterFrame = (RepeaterFrame)module.getMinewFrame(FrameType.BLUETOOTH_REPEATER_FRAME);
if (combinationFrame != null) {
//Device mac address
String macAddress = deviceInforFrame.getMacAddress();
//Percentage of power
int battery = deviceInforFrame.getBattery();
//tamperProof States
String tamperProofStates = deviceInforFrame.getTamperProofStates();
}
if (repeaterFrame != null) {
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
There are 2 types of adv frames for MBT02 device
CombinationFrame
CombinationFrame
Name Type Description battery int Battery Level Percentage macAddress String firmware mac tamperProofStates int tamper Proof States 1 Trigger 0 Normal
RepeaterFrame
RepeaterFrame
Name Type Description totalNumberOfPacket int Total number of broadcast packets, 0 to 255 If the number exceeds 255 reset relayInformationLists List Reply message packet RelayInformation
Name Type Description mac String The mac of the beacon device was scanned rssi int The rssi of the beacon device was scanned
# Connections
It is usually necessary to stop scanning before connecting. sdk provides methods to connect and disconnect.。
MBT02RepeaterBleManager mBleManager = MBT02RepeaterBleManager.getInstance();
//Stop scanning
mBleManager.stopScan(context);
//Setting the device secret key
String key="minewtech1234567";
mBleManager.setSecretKey(key);
//Connection, module for the device to be connected
MBTRepeaterEntity module;
mBleManager.connect(context,module);
//Disconnect. macAddress is the device mac
mBleManager.disConnect(macAddress);
2
3
4
5
6
7
8
9
10
11
12
Note: Before connecting the device, please confirm whether the device is scanned, if no device broadcast is scanned and the connection method is called, the connection will fail.
After callingconnect()
,there will be a status listener in sdk for the connection process.
//Setting the listener
mBleManager.setOnConnStateListener(new OnConnStateListener() {
/*
* Status callbacks during connection
*
* @param macAddress device mac
* @param connectionState status
*/
@Override
public void onUpdateConnState(String address, BleConnectionState state) {
switch (state) {
case Disconnect:
//Connection failure or device disconnection will be called back, active disconnection will not call back the .
break;
case Connecting:
//This state will be called back after calling connect()
break;
case Connected:
//The initial connection was successful, as a transition phase, but not really successful at this point.
break;
case AuthenticateFail:
//Key verification failed.
break;
case AuthenticateSuccess:
//Key verification successful.
break;
case ConnectComplete:
//Connection is complete, the device is now ready for read and write operations.
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
During the connection process, sdk will return multiple connection states to the app, which the app needs to handle properly.
- BleConnectionState.Connecting,BleConnectionState.Connected: Connecting the device in, do not do time-consuming operations in this state, because at this time in the connected device discovery service, and send authentication data, etc.
- BleConnectionState.ConnectComplete: The sensor device is successfully connected at this point, and can perform read and write operations, such as configuring adv parameters, scan configuration. etc.
- BleConnectionState.AuthenticateFail:The secret key is verified during the authentication process. If the entered secret key is incorrect, this state will be called back and the device will actively disconnect.
- BleConnectionState.AuthenticateSuccess:The secret key is verified during the authentication process. If the entered secret key is correct, this status will be called back.
- BleConnectionState.Disconnect: The callback will be made if the connection fails or the device is disconnected.
# Reading and writing
The read and write APIs are as follows.:
/**
*Set device key
* @param macAddress device mac
* @param secretKey secret key key
* @param listener
*/
public void setSecretKey(String macAddress, String secretKey);
/**
* Query device version information
* @param macAddress device mac
* @param listener listener
*/
public void getFirmwareVersion(String macAddress, OnQueryResultListener<FirmwareVersionModel> listener);
/**
* Query device status
* @param macAddress device mac
* @param listener listener
*/
public void getDeviceOperationStatus(String macAddress, OnQueryResultListener<DeviceOperationStatusModel> listener);
/**
* Query device TamperProof status
* @param macAddress device mac
* @param listener listener
*/
void queryTamperProofSwitch(String macAddress, OnQueryResultListener<OptionSwitchConfig> listener);
/**
* Set device TamperProof status
* @param macAddress device mac
* @param optionValue 1=open,0=close
* @param listener listener
*/
void setTamperProofSwitch(String macAddress, int optionValue, OnModifyConfigurationListener listener);
/**
* Query adv frame broadcast parameters
* @param macAddress device mac
* @param slot Query the broadcast channel value, default value 0.slot = 0 CombinationFrame 、slot = 1
* RepeaterFrame
* @param listener listener
*/
public void queryAdvParametersConfiguration(String macAddress,int slot, OnQueryResultListener<AdvParametersConfiguration> listener);
/**
* Set broadcast frame broadcast parameters
*
* @param macAddress device mac
* @param frameType FrameType enumeration gets getFrameTypeVersion()
* @param slotNumber sets the channel value corresponding to the broadcast,
* @param advertisingInterval broadcast interval in milliseconds, the broadcast interval is adjustable from 1s to 60s, and * the scale is 1s;
* @param txPower -40 -20 -16 -12 -8 -4 0 4dBm
* @param listener listener
*/
public void setAdvParametersConfiguration(String macAddress,String frameType, int slotNumber,int advertisingInterval, int txPower, OnModifyConfigurationListener listener);
/**
* Set scan params
* @param macAddress device mac
* @param scanConfigurationModel params
* @param listener listener
*/
public void setScanParameters(String macAddress, ScanConfigurationModel scanConfigurationModel, OnModifyConfigurationListener listener);
/**
* query scan params
*
* @param macAddress device mac
* @param listener listener
*/
public void queryScanConfiguration(String macAddress, OnQueryResultListener<ScanConfigurationModel> listenerr);
/**
* query Acc Sensor config
* @param macAddress device mac
* @param listener listener
*/
void queryAccConfiguration(String macAddress, OnQueryResultListener<AccConfig> listener);
/**
* set Acc Sensor config
* @param macAddress device mac
* @param accConfig acc params
* @param listener listener
*/
void setAccConfiguration(String macAddress, AccConfig accConfig, OnModifyConfigurationListener listener);
/**
* Set sensor configuration
* @param macAddress device mac
* @param triggerConfigList trigger params
* @param listener listener
*/
public void setTriggerConfiguration(String macAddress, List<TriggerConfigBean> triggerConfigList, OnModifyConfigurationListener listener);
/**
* query sensor configuration
*
* @param macAddress mac
* @param listener listener
*/
public void queryTriggerConfiguration(String macAddress, OnQueryResultListener<List<TriggerConfigBean>> listenerr);
/**
* Verify the correctness of OTA upgrade files
* @param zipFilePath ota upgrade file path
* @return true= upgrade file, false= not upgrade file
*/
boolean verifyOtaFile(String zipFilePath);
/**
* firmware upgrade
*
* @param macAddress device mac
* @param isLinkUpgrade true url upgrade, false firmware package upgrade. The default value is false, and the url upgrade * method is not supported.
* @param dfuTarget ZipUtil.getDfuTargets(zipFilePath)
* @param upgradeData upgrade package data
* @param listener listener
*/
public void firmwareUpgrade(String macAddress,boolean isLinkUpgrade,int dfuTarget,byte[] upgradeData, OnFirmwareUpgradeListener listener);
/**
* Restore factory settings
*
* @param macAddress device mac
* @param listener listener
*/
public void reset(String macAddress, OnModifyConfigurationListener listener);
/**
* Shutdown
* @param macAddress device mac
* @param listener 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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
Some methods are supplemented:
set the device secret key. This method call must be set before the connect() method
MBT02RepeaterBleManager mBleManager = MBT02RepeaterBleManager.getInstance(); String secretKey = "minewtech1234567" mBleManager.setSecretKey(mAddress,secretKey);
1
2
3
4Query device version information。
MBT02RepeaterBleManager mBleManager = MBT02RepeaterBleManager.getInstance(); mBleManager.queryDeviceFirmwareInfo(macAddress,new OnQueryResultListener<FirmwareVersionModel>() { @Override public void OnQueryResult(boolean b, FirmwareVersionModel firmwareVersionModel) { //b true query succeeds, false query fails ,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
15Query device status。
MBT02RepeaterBleManager mBleManager = MBT02RepeaterBleManager.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
11Query and set device TamperProof status
MBT02RepeaterBleManager mBleManager = MBT02RepeaterBleManager.getInstance(); OptionSwitchConfig mOptionSwitchConfig = null; mBleManager.queryTamperProofSwitch(mMac, new OnQueryResultListener<OptionSwitchConfig>() { @Override public void OnQueryResult(boolean b, OptionSwitchConfig optionSwitchConfig) { if (b) { mOptionSwitchConfig = optionSwitchConfig; } Toast.makeText(DeviceConnectedCompleteActivity.this, "Query Result:" + b, Toast.LENGTH_LONG).show(); } }); mBleManager.setTamperProofSwitch(mMac, 1, 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
19Query adv frame broadcast parameters and configure adv parameters.
MBT02RepeaterBleManager mBleManager = MBT02RepeaterBleManager.getInstance(); MBTRepeaterEntity 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(); } }); 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(); } }); 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
44query and set scan params
MBT02RepeaterBleManager mBleManager = MBT02RepeaterBleManager.getInstance(); ScanConfigurationModel mScanConfigurationModel = null; //query mBleManager.queryScanConfiguration(macAddress, new OnQueryResultListener<ScanConfigurationModel>() { @Override public void OnQueryResult(boolean b, ScanConfigurationModel scanConfigurationModel) { if (b) { mScanConfigurationModel = scanConfigurationModel; } Toast.makeText(DeviceConnectedCompleteActivity.this, "Query Result:" + b, Toast.LENGTH_LONG).show(); } }); //setting 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
20Query and Set Acc Sensor params.
MBT02RepeaterBleManager mBleManager = MBT02RepeaterBleManager.getInstance(); AccConfig mAccConfig = null; mBleManager.queryAccConfiguration(macAddress, new OnQueryResultListener<AccConfig>() { @Override public void OnQueryResult(boolean b, AccConfig accConfig) { if (b) { mAccConfig = accConfig; } Toast.makeText(DeviceConnectedCompleteActivity.this, "Query Result:" + b, Toast.LENGTH_LONG).show(); } }); mBleManager.setAccConfiguration(macAddress, mAccConfig, 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
20query and set trigger params
MBT02RepeaterBleManager mBleManager = MBT02RepeaterBleManager.getInstance(); List<TriggerConfigBean> mTriggerConfigBeanList = new ArrayList<>(); //query mBleManager.queryTriggerConfiguration(macAddress, new OnQueryResultListener<List<TriggerConfigBean>>() { @Override public void OnQueryResult(boolean b, List<TriggerConfigBean> triggerConfigBeanList) { if (b) { mTriggerConfigBeanList.clear(); mTriggerConfigBeanList.addAll(triggerConfigBeanList); } Toast.makeText(DeviceConnectedCompleteActivity.this, "Query Result:" + b, Toast.LENGTH_LONG).show(); } }); //set 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
21Firmware upgrade.
MBT02RepeaterBleManager mBleManager = MBT02RepeaterBleManager.getInstance(); // Before the upgrade, verify the upgrade file only when true is used to upgrade the device, and false is not the upgrade file of the device String otaFilePath = "***/****.zip" Boolean result = mBleManager.verifyOtaFile(otaFilePath) mBleManager.firmwareUpgrade(mac, false,0,upgradeData, new OnFirmwareUpgradeListener() { /** * Upgrade package data writing progress */ @Override public void updateProgress(int progress) { } /** * Callback when the upgrade is successful. At this time, the device will actively disconnect from the mobile phone, so * the OnConnStateListener callback will be triggered and return * BleConnectionState.Disconnect state */ @Override public void upgradeSuccess() { } /** * Upgrade failed */ @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
35Restore the factory settings.
/**
* Restore factory settings
*
* @param macAddress device mac
*/
mBleManager.reset(macAddress, new OnModifyConfigurationListener() {
@Override
public void onModifyResult(boolean success) {
}
});
2
3
4
5
6
7
8
9
10
11
Shutdown.
/** * Reset * * @param macAddress device mac */ mBleManager.powerOff(macAddress, new OnModifyConfigurationListener() { @Override public void onModifyResult(boolean success) { } });
1
2
3
4
5
6
7
8
9
10
11
# History
- **2024/7/4 edit;