# MinewSensorKit Instruction document

This SDK only supports the Bluetooth sensor devices from Minew. The SDK helps developers to handle everything between the phone and the sensor, 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: IndustrySensorBleManager is the device management class, which is always a single instance when the app is running. IndustrialHtSensor 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.

IndustrySensorBleManager：Device management class that scans the surrounding ESL devices and can connect them, verify them, etc.；

IndustrialHtSensor：Example of an industrial temperature and humidity sensor device acquired during scanning, inherited from SensorModule；

# Import to project

  1. Development Environment

    The minimum sdk support is Android 5.0, corresponding to API Level 21. set minSdkVersion to 21 or above in build.gradle of the module.

    android {

    defaultConfig {
        applicationId "com.xxx.xxx"
        minSdkVersion 21
    }
}
    1
    2
    3
    4
    5
    6
    7

  2. Add industry_ht_sensor_sdk.jar to the module's libs folder and add the following statement to the build.gradle of the module (add the dependency directly).

    implementation files('libs/industry_ht_sensor_sdk.jar')
implementation files('libs/sensor_sdk_base.jar')
implementation 'org.lucee:bcprov-jdk15on:1.52.0'
    1
    2
    3

    Or right-click the jar file and select Add as Library to add it to the current module.

  3. The following permissions are required in AndroidManifest.xml, and if targetSdkVersion is greater than 23, you need to do permission management to get the permissions.

    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    1
    2
    3
    4
    5
    6
    7

​

# Use

The sdk is divided into three phases: scanning, connecting, and reading and writing.

# Scanning section

# Start scanning

For Android 6.0 or above, you need to apply for location permission and turn on the location switch before you can perform BLE scanning.

To turn on Bluetooth scanning, you need to turn on Bluetooth first, if you go to scan without turning on Bluetooth, the app will flash back. BLETool.isBluetoothTurnOn can be used to determine if Bluetooth is turned on. If not open, you can call BLETool.setBluetoothTurnOn to open it.

IndustrySensorBleManager manager = 	IndustrySensorBleManager.getInstance(context);
if(BLETool.isBluetoothTurnOn(context)){
    manager.startScan(context,new OnScanSensorResultListener() {
        @Override
        public void onScanResult(List<IndustrialHtSensor> scanBadgeList) {
            //scan result
        }
        @Override
        public void onStopScan(List<IndustrialHtSensor> scanBadgeList) {
            //stop scan result
        }
    });
    //Set scan duration 5 minutes, sdk default scan duration 5 minutes
        manager.startScan(context,5*60*1000，new OnScanSensorResultListener() {
        @Override
        public void onScanResult(List<IndustrialHtSensor> scanBadgeList) {
            //scan result
        }
        @Override
        public void onStopScan(List<IndustrialHtSensor> scanBadgeList) {
            //stop scan result
        }
    });
}
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

The sdk does not handle the length of the Bluetooth scan internally, but the scan is a power hungry operation, the sdk stops scanning in 5 minutes by default, if you still need to continue scanning, you can provide a timer or refresh and other operations to continue to call the scan 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 industrial temperature and humidity data of the device is obtained through IndustrialHtSensor as shown below, which is stored in the broadcast frame object.

The sdk provides SensorModule as the base class of IndustrialHtSensor 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, customizable. The initialized name of the industrial temperature and humidity sensor is "MST01".
rssi int Signal strength

The SensorModule 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

DeviceStaticInfoFrame deviceInforFrame = (DeviceStaticInfoFrame)module.getMinewFrame(HtFrameType.DEVICE_STATIC_INFO_FRAME);
IndustrialHtFrame industrialHtFrame = (IndustrialHtFrame) module.getMinewFrame(HtFrameType.INDUSTRIAL_HT_FRAME);
if (deviceInforFrame != null) {
    //Device mac address
    String macAddress = deviceInforFrame.getMacAddress();
    //Percentage of power
    int battery = deviceInforFrame.getBattery();
    //firmware version
    String firmwareVersion = deviceInforFrame.getFirmwareVersion();
}

if (industrialHtFrame != null) {
    //Temperature and humidity sensor current temperature
    float temperature = industrialHtFrame.getTemperature();
    //Temperature and humidity sensor current humidity
    float humidity = industrialHtFrame.getHumidity();
    //Sensor type 0: Temperature and humidity, 1: Single temperature
    int type = industrialHtFrame.getType();
    //Temperature units are 0 for Celsius and 1 for Fahrenheit
    int type = industrialHtFrame.getTemperatureUnit();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

There are 2 types of broadcast frames for industrial temperature and humidity equipment.

  1. Device static information frame

    • DeviceStaticInfoFrame

      Name Type Description
      frameVersion int device type
      firmwareVersion String Firmware Version
      batteryLevel int Battery Level Percentage
      macAddress String firmware mac
      peripheralSupportInfo PeripheralSupportInfo Description of peripheral support

  2. Industrial temperature and humidity frames

    • IndustrialHtFrame

      Name Type Description
      frameVersion int device type
      tempHumiVersion int MST01 Temperature and humidity frame version
      type int Sensor type. 0: Temperature and humidity, 1: Single temperature
      sensorStatus DeviceExceptionEnum Device status, such as normal, sensor abnormal, etc.
      temperatureUnit int Temperature units : 0 : Celsius , 1 : Fahrenheit
      temperature float Sensor current temperature
      humidity float Sensor current humidity
      isMark float Marked or unmarked, 1: marked, 0: unmarked
      deviceName String Device Name

# Connections

It is usually necessary to stop scanning before connecting. sdk provides methods to connect and disconnect.

//Stop scanning
manager.stopScan(context);
//Setting the device secret key
String key;
manager.setSecretKey(key);
//Connection, module for the device to be connected
IndustrialHtSensor module;
manager.connect(context,module);
//Disconnect. macAddress is the device mac
manager.disConnect(macAddress);
1
2
3
4
5
6
7
8
9
10

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 calling connect(), there will be a status listener in sdk for the connection process.

//Setting the listener
manager.setOnConnStateListener(new OnConnStateListener() {
    
    /*
     * Status callbacks during connection
     *
     * @param macAddress      device mac
     * @param connectionState status
     */
    @Override
    public void onUpdateConnState(String address, MSensorConnectionState state) {
        switch (state) {
            case Disconnect:
				//Connection failure or device disconnection will be called back, active disconnection will not call back the 					//status
                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 ConnectComplete:
				//Connection is complete, the device is now ready for read and write operations
                break;
            default:
                break;
        }
    }
});
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

During the connection process, sdk will return multiple connection states to the app, which the app needs to handle properly.

  • MSensorConnectionState.Connecting, MSensorConnectionState.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.
  • MSensorConnectionState.ConnectComplete: The sensor device is successfully connected at this point, and can perform read and write operations, such as configuring broadcast parameters, sensor configuration, reading historical data, etc.
  • Disconnect: The callback will be made if the connection fails or the device is disconnected. If the APP actively calls manager.disConnect(macAddress); it will not call back this state.

# Reading and writing

The read and write APIs are as follows.

    /**
     * Set the secret key of the device
     * @param eaxKey The secret key corresponding to the device
     */
    @Override
    public void setSecretKey(String macAddress, String password);


    /**
     * Read temperature and humidity history data
     *
     * @param macAddress device mac
     * @param startTime LE, start timestamp in seconds
     * @param endTime LE, end time stamp Unit: second
     * @param systemTime LE, real-time timestamp in seconds
     * @param listener listener
     */
    @Override
    public void readHtHistoryData(String macAddress,long startTime,long endTime,long systemTime, OnReceiveDataListener<HtHistoryData> listener);

    /**
     * Read temperature units 
     *
     * @param macAddress device mac
     * @param listener listener 0 uses Celsius, 1 uses Fahrenheit
     */
    @Override
    public void queryTemperatureUnit(String macAddress, OnQueryResultListener<Integer> listener) ;

    /**
     * Set the temperature unit
     *
     * @param macAddress device mac
     * @param isCelsius whether to set to Celsius
     * @param listener listener
     */
    @Override
    public void setTemperatureUnit(String macAddress, boolean isCelsius, OnModifyConfigurationListener listener) ;

    /**
     * Set the device information frame broadcast parameters
     *
     * @param macAddress device mac
     * @param advertisingInterval broadcast interval unit milliseconds,100ms ~ 5000ms adjustable, scale is 100ms.
     * @param txPower -40 -20 -16 -12 -8 -4 0 4dBm
     * @param listener listener
     */
    public void setDeviceInfoFrameAdvertisingParametersConfiguration(String macAddress, int advertisingInterval, int txPower, OnModifyConfigurationListener listener);

    /**
     * Query device information frame broadcast parameters
     *
     * @param macAddress device mac
     * @param listener listener
     */
    public void queryDeviceInfoFrameAdvertisingParametersConfiguration(String macAddress,  OnQueryResultListener<DeviceInfoAdvertisingParametersConfiguration>  listener);
    /**
     * Set industrial temperature and humidity frame broadcast parameters
     *
     * @param macAddress device mac
     * @param advertisingInterval broadcast interval unit milliseconds, broadcast interval 1s ~ 60s adjustable, scale is 1s.
     * @param txPower -40 -20 -16 -12 -8 -4 0 4dBm
     * @param advertisingName Broadcast device name
     * @param listener listener
     */
    public void setIndustryHTFrameAdvertisingParametersConfiguration(String macAddress, int advertisingInterval, int txPower, String advertisingName, OnModifyConfigurationListener listener);

    /**
     * Query industrial temperature and humidity frame broadcast parameters
     *
     * @param macAddress device mac
     * @param listener listener
     */
    public void queryIndustryHTFrameAdvertisingParametersConfiguration(String macAddress,  OnQueryResultListener<IndustryHtParametersConfiguration> listener);
    /**
     * Set industrial temperature and humidity sensor configuration
     *
     * @param macAddress device mac
     * @param htSettingData trigger threshold list fixed length 2
     * @param samplingInterval sampling interval unit milliseconds ,1s ~24h, default value 30s
     * @param listener listener
     */
    public void setIndustryHTSensorConfiguration(String macAddress, List<HTSensorSettingData> htSettingData,int samplingInterval,OnModifyConfigurationListener listener);

    /**
     * Query industrial temperature and humidity sensor configuration
     *
     * @param macAddress device mac
     * @param listener listener
     */
    public void queryIndustryHTSensorConfiguration(String macAddress, OnQueryResultListener<IndustryHtSensorConfiguration> listener);

    /**
     * Firmware upgrade
     *
     * @param macAddress device mac
     * @param upgradeData Upgrade package data
     * @param listener listener
     */
    public void firmwareUpgrade(String macAddress,byte[] upgradeData, OnFirmwareUpgradeListener listener);


    /**String macAddress
     * 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);
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
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

Additional explanation of some methods

  1. Read historical data.

    //Read temperature and humidity sensor history data
long startTime;//If the start time is 0, all temperature and humidity history data of the sensor will be checked.
long endTime;
long systemTime;
manager.readHtHistoryData(mAddress,startTime,endTime,systemTime new OnReceiveDataListener<HtHistoryData>() {
    @Override
    public void receiverData(String macAddress, 
                             List<HtHistoryData> historyData) {
		
    }
});
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12

  2. Set the temperature unit, the temperature and humidity sensor supports setting Celsius and Fahrenheit degrees.

    /**
 * Set the sensor temperature unit
 *
 * @param macAddress device mac
 * @param isCelsius whether to set to Celsius
 * @param listener listener
 */
manager.setTemperatureUnit(macAddress, true, new OnModifyConfigurationListener() {
    @Override
    public void onModifyResult(boolean success) {
		//success is true, indicating that the setting was successful, and vice versa
    }
});
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

  3. Set the temperature and humidity alarm values. Note that the temperature is 85°C maximum and -40°C minimum in Celsius units, 185°F maximum and -40°F minimum in Fahrenheit, and the humidity is 100 maximum and 0 minimum.

    List<HTSensorSettingData> htSettingData = new ArrayList<>();
HTSensorSettingData htSensorSettingData1 = new HTSensorSettingData();

if(openAlarm1){
    //open temperature alarm 2
   	htSensorSettingData1.setOpenAlarmTemperature(true);//true opens temperature 1 alarm, false closes temperature 1 alarm
	htSensorSettingData1.setHighTemperature(20f);//Set the default value of the highest alarm temperature of temperature alarm 1 20℃
	htSensorSettingData1.setLowTemperature(2f);//Set the temperature alarm 1 lowest alarm temperature , default value 2 ℃ 
	htSensorSettingData1.setOpenAlarmHumidity(true);//true opens the humidity 1 alarm, false closes the humidity 1 alarm
	htSensorSettingData1.setHighHumidity(60f);//Set the default value of 60% for the highest alarm temperature of humidity alarm 1
	htSensorSettingData1.setLowHumidity(50f);//Set the humidity alarm 1 lowest alarm temperature , default value 50%  
}else{
    //close temperature and humidity alarm 1 
    htSensorSettingData1.setOpenAlarmTemperature(false);//false turn off temperature 1 alarm
	htSensorSettingData1.setHighTemperature(-128f);//default -128f
	htSensorSettingData1.setLowTemperature(-128f);//Set temperature alarm 1 minimum alarm temperature , default value -128f
	htSensorSettingData1.setOpenAlarmHumidity(false);//true opens the humidity 1 alarm, false closes the humidity 1 alarm
	htSensorSettingData1.setHighHumidity(-128f);//Set the default value of the highest alarm temperature of humidity alarm 1 -128f
	htSensorSettingData1.setLowHumidity(-128f);//Set the humidity alarm 1 lowest alarm temperature , default value -128f
}
htSettingData.add(0,htSensorSettingData1);


HTSensorSettingData htSensorSettingData2 = new HTSensorSettingData();
if(openAlarm2){
    //open temperature alarm 2
   	htSensorSettingData2.setOpenAlarmTemperature(true);//true open temperature 1 alarm, false close temperature 1 alarm
	htSensorSettingData2.setHighTemperature(30f);//Set the default value of the highest alarm temperature of temperature alarm 1 30℃
	htSensorSettingData2.setLowTemperature(15f);//Set the temperature alarm 1 lowest alarm temperature , default value 15 ℃ 
	htSensorSettingData2.setOpenAlarmHumidity(false);//The second group of alarms can not set the humidity alarm, all fill in false here
	htSensorSettingData2.setHighHumidity(-128f);//Set the default value of the highest alarm temperature of humidity alarm 2 -128f
	htSensorSettingData2.setLowHumidity(-128f);//Set humidity alarm 2 lowest alarm temperature , default value -128f 
}else{
    //close temperature and humidity alarm 2 
    htSensorSettingData2.setOpenAlarmTemperature(false);//false to turn off temperature 1 alarm
	htSensorSettingData2.setHighTemperature(-128f);//default value -128f
	htSensorSettingData2.setLowTemperature(-128f);//Set temperature alarm 1 minimum alarm temperature , default value -128f
	htSensorSettingData2.setOpenAlarmHumidity(false);//The second group of alarms can not set the humidity alarm, all fill in false here
	htSensorSettingData2.setHighHumidity(-128f);//Set the default value of the highest alarm temperature of humidity alarm 2 -128f
	htSensorSettingData2.setLowHumidity(-128f);//Set humidity alarm 2 lowest alarm temperature , default value -128f 
}
htSettingData.add(1,htSensorSettingData1);
int samplingInterval = 30*1000;//sampling interval 1s ~24h, default value 30s, unit milliseconds

manager.setIndustryHTSensorConfiguration(macAddress,htSettingData, samplingInterval,new OnModifyConfigurationListener(){
    @Override
    public void onModifyResult(boolean success) {
		//success is true, indicating that the setting is successful, otherwise it is a failure
    }
});
    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

  4. Firmware Upgrade。

    /**
 * Firmware upgrade
 *
 * @param macAddress device mac
 * @param upgradeData Upgrade package data
 * @param listener listener
 */
manager.firmwareUpgrade(mac, upgradeData, new OnFirmwareUpgradeListener() {
    
    /**
     * Progress of writing upgrade package data
     */
    @Override
    public void updateProgress(int progress) {
		
    }

    /**
     * Upgrade success callback, at this time the device will actively disconnect from the phone, so it will trigger          	   *OnConnStateListener callback, return
     * MSensorConnectionState.Disconnect state
     */DisconnectState.
    @Override
    public void upgradeSuccess() {

    }
    
    /**
     * Upgrade failure.
     */
    @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

  5. Set broadcast parameters.

    // Get information about the broadcast parameters of the device information frame
DeviceInfoAdvertisingParametersConfiguration infoAdvParames ;
manager.queryDeviceInfoFrameAdvertisingParametersConfiguration(macAddress, new 				      OnQueryResultListener<DeviceInfoAdvertisingParametersConfiguration>() {
            @Override
            public void OnQueryResult(boolean queryResult, DeviceInfoAdvertisingParametersConfiguration queryInfo) {
                //queryResult is true, indicating that the query is successful, and vice versa is failure
                if(queryResult){
                    infoAdvParames=queryInfo;
                }else{
                    //Query failure
                }
            }
        });
// Set the device information frame broadcast parameters
manager.setDeviceInfoFrameAdvertisingParametersConfiguration(macAddress,infoAdvParames.getAdvertisingInterval(), 
                                         infoAdvParames.getTxPower(),new OnModifyConfigurationListener(){
    @Override
    public void onModifyResult(boolean success) {
		//success is true, indicating that the setting is successful, otherwise it is a failure
    }
});
// Get information on industrial temperature and humidity frame broadcast parameters
IndustryHtParametersConfiguration htAdvParames ;
manager.queryIndustryHTFrameAdvertisingParametersConfiguration(macAddress, new 				      OnQueryResultListener<IndustryHtParametersConfiguration>() {
            @Override
            public void OnQueryResult(boolean queryResult, IndustryHtParametersConfiguration queryInfo) {
                //queryResult is true, indicating that the query is successful, and vice versa is failure
                if(queryResult){
                    htAdvParames = queryInfo;
                }else{
                    //Query failure
                }
            }
        });
//Setting industrial temperature and humidity frame broadcast parameters
manager.setIndustryHTFrameAdvertisingParametersConfiguration(macAddress,htAdvParames.getAdvertisingInterval(), 
                                         htAdvParames.getTxPower(),
                                         htAdvParames.getAdvertisingContent(),new OnModifyConfigurationListener(){
    @Override
    public void onModifyResult(boolean success) {
		//success is true, indicating that the setting is successful, otherwise it is a failure
    }
});
    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

  6. Restore the factory settings.

    /**
 * Restore factory settings
 *
 * @param macAddress device mac
 */
manager.reset(macAddress, new OnModifyConfigurationListener() {
    @Override
    public void onModifyResult(boolean success) {
		//success is true, indicating that the setting is successful, otherwise it is a failure
    }
});
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11

7.Shutdown.

/**
 * Reset
 *
 * @param macAddress device mac
 */
manager.powerOff(macAddress, new OnModifyConfigurationListener() {
    @Override
    public void onModifyResult(boolean success) {

    }
});
1
2
3
4
5
6
7
8
9
10
11

# History

  • **2023/04/11 add；
Last Updated:: 11/14/2023, 3:25:44 PM