# MinewSensorKit documentation

This SDK only supports Bluetooth sensor devices produced by Minew. The SDK can help developers handle everything between mobile phones and sensors, including: scanning devices, broadcasting data, connecting devices, writing data to devices, and receiving data from devices.

Currently, the SDK only supports the use of temperature and humidity sensors and BLE temperature and humidity sensor.

# Preliminary work

Overall framework: MinewSensorManager is a device management class, which is always a singleton when the APP is running. SensorModule is a device instance class. This suite will generate an instance for each device, which will be used after scanning and connection. It contains device broadcast data internally. During scanning, the data will be updated as the device keeps broadcasting.

MinewSensorCenterManager: Device management class, you can scan the surrounding ESL devices, and you can connect them, verify them, etc.;

SensorModule: Device instance obtained during scanning, judged as temperature and humidity or door sensor by type attribute;

IndustrialHtSensor: BLE temperature and humidity sensor device, inherited from SensorModule;

HtSensorV3Module: temperature and humidity sensor device, inherited from SensorModule.

# Import to project

  1. Development environment

    The SDK supports Android 4.3 at a minimum, and the corresponding API Level is 18. Set minSdkVersion to 18 or above in module's build.gradle

    android {

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

  2. Add MinewSensorKit.jar to the libs folder of the module, and add the following statement in build.gradle of the module (add dependencies directly):

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

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

  3. The following permissions are required in AndroidManifest.xml. If targetSdkVersion is greater than 23, you need to do Permission Management to obtain 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" />

//When the targetSdkVersion version is greater than or equal to 31（Android 12）Bluetooth permissions are added as follows
<uses-permission android:name="android.permission.BLUETOOTH"
    android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"
    android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"
    tools:targetApi="s" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
        <receiver
            android:name="com.minewtech.sensor.ble.manager.OreoPendingReceiver"
            android:exported="false">
            <intent-filter>
                <action android:name="com.minew.sensor.sdk.ACTION_FOUND" />
            </intent-filter>
        </receiver>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20

# Usage

The SDK is divided into three stages: scanning, connection, and reading and writing.

# Scanning part

# Start scanning

To turn on Bluetooth scanning, you need to turn on Bluetooth first. If you don't turn on Bluetooth to scan, the APP will flash back. You can judge whether Bluetooth has been turned on by BLETool.isBluetoothTurnOn.

For Android 6.0 and above, when performing BLE scanning, you need to apply for positioning permission and turn on the positioning switch to proceed!

MinewSensorCenterManager manager = 	MinewSensorCenterManager.getInstance(context);
if(BLETool.isBluetoothTurnOn(context)){
    manager.startScan(new OnScanSensorResultListener() {
        @Override
        public void onScanSensorResult(ArrayList<SensorModule> result) {
            //scan result
        }
    });
}
1
2
3
4
5
6
7
8
9

The sdk does not process the Bluetooth scan duration, but the scan is a power-consuming operation. Generally, the scan can be stopped in 90 seconds. If you still need to continue the scan, you can provide refresh and other operations to continue the scan.

# Fetch data

During the scan, the APP can obtain part of the device's current data through the SDK. Obtain the device temperature and humidity data through ThSensorModule as shown below, and the data is saved in the broadcast frame object.

SDK provides SensorModule as the base class of HtSensorV3Module and IndustrialHtSensor, which is used to store public data of sensor devices, as shown in the following table:

Name Type Description
macAddress String device mac
name String The device name can be customized. The initial name of the temperature and humidity sensor is "S3", and the door sensor is "S4"
rssi int Signal strength
type int Equipment type. If it is 30, it means that the device is a temperature and humidity sensor, and if it is 32, it means a temperature sensor, If it is 33, it means that the device is a BLE temperature and humidity sensor, and if it is 34, it means a BLE temperature sensor

SensorModule also saves a Map, which is used internally to store the device broadcast data frames it acquired during the scan, which can be taken out as follows:

HtFrame thFrame = (HtFrame) module.getMinewFrame(HtFrameType.TH_FRAME);
if (thFrame != null) {
    //Current temperature of temperature and humidity sensor
    float temperature = thFrame.getTemperature();
    //Current humidity of temperature and humidity sensor
    float humidity = thFrame.getHumidity();
}
1
2
3
4
5
6
7

Temperature and humidity and door sensor have their own frame types.

  1. Temperature and humidity sensor

    • HtFrame

      Name Type Description
      temperatureUnit int Temperature unit, 0 means Celsius, 1 means Fahrenheit
      power int Power
      temperature float temperature
      humidity float humidity

  2. BLE sensor

    • IndustrialHtFrame

      Name Type Description
      power int power
      doorSensorState boolean Door sensor trigger state
      doorAlarmState boolean Tamper alarm status
      doorTriggerTag boolean Door magnet trigger mark

# Connection

Generally, you need to stop scanning before connecting. SDK provides connection and disconnection methods.

//Stop scanning
manager.stopScan();
//Connect, module is the device to be connected
manager.connect(module);
//Disconnect. macAddress is the device mac
manager.disConnect(macAddress);
1
2
3
4
5
6

Note: Only for SensorType.INDUSTRIAL_HT_TYPE and SensorType.INDUSTRIAL_TEMPERATURE_TYPE, you need to check whether the DeviceStaticInfoFrame is obtained before connecting the equipment. If the DeviceStaticInfoFrame is not obtained, the sdk uses the old protocol to parse the data by default, resulting in an error in reading the information and the information cannot be configured. Please connect the device only when it is guaranteed to obtain the DeviceStaticInfoFrame.

if(module.getType() == SensorType.INDUSTRIAL_HT_TYPE ||module.getType() == 						                  SensorType.INDUSTRIAL_TEMPERATURE_TYPE){
     //DeviceStaticInfoFrame
  MinewFrame minewFrame = module.getMinewFrame(HtFrameType.DEVICE_STATIC_INFO_FRAME);
  if(minewFrame!=null){
  	manager.connect(module);
  }
}
1
2
3
4
5
6
7

After calling connect(), the SDK will monitor the connection process.

//Set the listener
manager.setOnConnStateListener(new OnConnStateListener() {
    
    /*
     * Status callback during connection
     *
     * @param macAddress      Device mac
     * @param connectionState state
     */
    @Override
    public void onUpdateConnState(String address, SensorConnectionState state) {
        switch (state) {
            case Disconnect:
				//If the connection fails or the device is disconnected, it will be 
                //called back, and the active disconnection will not call back this 
                //state.
                break;
            case Connecting:
				//This state will be called back after calling connect()
                break;
            case Connected:
                //The initial connection was successful. As a transitional stage, 
                //it was not really successful at this time
                break;
            case VerifyPassword:
				//Password verification, after calling back this state, the device 
                //needs to write a password, write it through sendPassword()
                manager.sendPassword(address, "minew123")
                break;
            case PasswordError:
				//If the password is incorrect, the device will be disconnected, and 
                //the Disconnect status will not be recalled
                break;           
            case FirmwareUpgradeSuccessfully:
				//The firmware upgrade is successful and the Disconnect status will 
                //not be recalled
                break;
            case ConnectComplete:
				//The connection is complete, and the device can read and write 
                //at this time
                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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

During the connection process, the SDK will return multiple connection states to the app, and the app needs to be processed.

  • ConnectionState.VerifyPassword: The sensor connection needs to verify the password. Once this status is called back, the password needs to be written through manager.sendPassword(address, "minew123"). Note that the password is 8 digits long.
  • ConnectionState.PasswordError: If the password is wrong, the sensor device will be disconnected and will not return to ConnectionState.Disconnect state.
  • ConnectionState.ConnectComplete: At this point, the sensor device has been successfully connected and can perform read and write operations, such as reading historical data.
  • ConnectionState.FirmwareUpgradeSuccessfully: When the firmware is upgraded, the SDK will give another callback method, and the status will be called back after the upgrade is successful, the connection will be disconnected, and the ConnectionState.Disconnect state will not be called back.
  • ConnectionState.Disconnect: If the connection fails or the device is disconnected, it will be called back, and the active disconnection will not call back this state. That is, calling manager.disConnect(macAddress); will not call back this state. Note: This status will be called back if the upgrade fails.

# Read-write part

The read and write APIs are as follows:


    /**
     * Send (write) password, Note that the password is 8 digits long
     *
     * @param macAddress device mac
     * @param password   password
     */
    @Override
    public void sendPassword(String macAddress, String password);
	/**
     * set device alias
     *
     * @param macAddress device mac
     * @param name   name
     * @param listener   listener
     */
    @Override
    public void setSensorName(String macAddress, String name, OnModifyConfigurationListener listener);

    /**
     * Read historical temperature and humidity data
     *
     * @param macAddress device mac
     * @param listener   listener
     */
    @Override
    public void readHtHistoryData(String macAddress, OnReceiveDataListener<HtHistoryData> listener);

    /**
     * set Temperature Unit
     *
     * @param macAddress device mac
     * @param isCelsius  Whether set to Celsius
     * @param listener   listener
     */
    @Override
    public void setTemperatureUnit(String macAddress, boolean isCelsius, OnModifyConfigurationListener listener) ;

    /**
     * Set the temperature and humidity alarm value
     *
     * @param macAddress device mac
     * @param minTemp    Minimum temperature
     * @param maxTemp    Maximum temperature
     * @param minHumi    Minimum humidity
     * @param maxHumi    Maximum humidity
     * @param listener   listener
     */
    @Override
    public void setHtAlarmValue(String macAddress, boolean isTempWarn, boolean isHumiWarn, float minTemp, float maxTemp, int minHumi, int maxHumi, OnModifyConfigurationListener listener);

    /**
     * Set the ble sensor temperature and humidity alarm value
     *
     * @param macAddress  device mac
     * @param isTempWarn1 Temp1 alarm switch
     * @param isTempWarn2 Temp2 alarm switch
     * @param isHumiWarn  humidity alarm switch
     * @param minTemp1    Minimum Temp1
     * @param maxTemp1    Maximum Temp1
     * @param minTemp2    Minimum Temp2
     * @param maxTemp2    Maximum Temp2
     * @param minHumi     Minimum humidity
     * @param maxHumi     Maximum humidity
     * @param listener    listener
     */
    @Override
    public void setIndustrialHtAlarmValue(String macAddress, boolean isTempWarn1, boolean isTempWarn2,
                                          boolean isHumiWarn, float minTemp1, float maxTemp1, float minTemp2,
                                          float maxTemp2, int minHumi, int maxHumi, OnModifyConfigurationListener listener);

    /**
     * set Broadcast Power
     *
     * @param macAddress device mac
     * @param power      Broadcast Power values -40, -20, -16, -12, -8, -4, 0, 4 dbm.
     * @param listener   listener
     */
    @Override
    public void setBroadcastPower(String macAddress, int power, OnModifyConfigurationListener listener);

    /**
     * set Broadcast Interval
     *
     * @param macAddress device mac
     * @param interval   Broadcast Interval values 100 - 5000ms
     * @param listener   listener
     */
    @Override
    public void setBroadcastInterval(String macAddress, int interval, OnModifyConfigurationListener listener);

    /**
     * set Delayed Recording Time
     *
     * @param macAddress device mac
     * @param time       time，unit（s)
     * @param listener   listener
     */
    @Override
    public void setDelayedRecordingTime(String macAddress, int time, OnModifyConfigurationListener listener);

    /**
     * powerOff
     *
     * @param macAddress device mac
     * @param listener   listener
     */
    @Override
    public void powerOff(String macAddress, OnModifyConfigurationListener listener);

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

    /**
     * Historical data storage switch
     *
     * @param macAddress device mac
     * @param isOpen     whether to open
     * @param listener   listener
     */
    @Override
    public void setOpenHistoryDataStore(String macAddress, boolean isOpen, OnModifyConfigurationListener listener);

    /**
     * reset
     *
     * @param macAddress device mac
     * @param listener   listener
     */
    @Override
    public void reset(String macAddress, OnModifyConfigurationListener listener);




	 /**
     * Set the temperature and humidity broadcast interval and set the information frame broadcast interval
     *(versions greater than or equal to 3.1.0 use this method)
     * @param macAddress device mac
     * @param htInterval Temperature and humidity broadcast interval, unit milliseconds, range (1-600 unit seconds)
     * @param infoInterval Device information broadcast interval, unit milliseconds, range (100-5000 unit milliseconds)
     * @param listener   listener
     */
    @Override
	public void setMultiBroadcastInterval(String macAddress, int htInterval, int infoInterval, OnModifyConfigurationListener 		listener)

	 /**
     * Set the data collection interval(versions greater than or equal to 3.1.0 use this method)
     *
     * @param macAddress device mac
     * @param interval Data collection interval unit milliseconds, range (0-24 unit hours)
     * @param listener   listener
     */
    @Override
    public void setDataCollectionInterval(String macAddress, int interval, 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
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

Supplementary explanation of some methods:

  1. Read historical data.

    Note: The temperature and humidity sensor and door sensor use different APIs to read historical data, and the incoming interface types are different. However, the historical data returned by the two each time are all historical data stored by the device.

    //Read historical data of temperature and humidity sensor
manager.readHtHistoryData(mAddress, 
                          new OnReceiveDataListener<HtHistoryData>() {
    @Override
    public void receiverData(String macAddress, 
                             List<HtHistoryData> historyData) {

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

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

    /**
 * Storage switch settings
 *
 * @param macAddress device mac
 * @param isCelsius  Whether 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 is successful, otherwise it fails
    }
});
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

  3. Set the temperature and humidity alarm value. Please note that in degrees Celsius, the maximum temperature is 85°C and the minimum is -40°C. In Fahrenheit, the maximum temperature is 185°F and the minimum is -40°F; the maximum humidity is 100 and the minimum is 0.

    
manager.setThAlarmValue(macAddress, 
                        true,
                        true,
                        10, 
                        60, 
                        10, 
                        60, new OnModifyConfigurationListener(){
    @Override
    public void onModifyResult(boolean success) {
		//success is true, indicating that the setting is successful, otherwise it fails
    }
});
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

  4. Firmware upgrade.

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

    }

    /**
     * Successful upgrade will trigger OnConnStateListener callback and return
     * ConnectionState.Firmware_Upgrade_Successfully
     */
    @Override
    public void upgradeSuccess() {

    }
    
    /**
     * Upgrade failed. Failure to upgrade will disconnect, trigger 
     * OnConnStateListener callback, returnConnectionState.Disconnect state
     */
    @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
    35

  5. Historical data storage switch.

    manager.setOpenHistoryDataStore(macAddress, 
                                true, 
                                new OnModifyConfigurationListener() {
    @Override
    public void onModifyResult(boolean success) {

    }
});
    1
    2
    3
    4
    5
    6
    7
    8

  6. Reset.

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

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

# Schedule

SensorModule：

Name Type Description
macAddress String device mac
name String Device name, APP can be customized
type int Equipment type. If it is 30, it means that the device is a temperature and humidity sensor, and if it is 32, it means a temperature sensor, If it is 33, it means that the device is a BLE temperature and humidity sensor, and if it is 34, it means a BLE temperature sensor,

Note that the data acquired during the scan is in its broadcast frame.

IndustrialHtSensor. The following property values are obtained at the time of connection, so they can only be used after connection.

Name Type Description
firmwareVersion String firmware version
alarmMaxTemp1st float The maximum temperature that has been set
alarmMinTemp1st float The minimum temperature that has been set
alarmMaxTemp2nd float The maximum temperature that has been set
alarmMinTemp2nd float The minimum temperature that has been set
alarmMaxHumi int The maximum humidity that has been set
alarmMinHumi int The maximum humidity that has been set
isAlarmTemp1st boolean Whether to open the alarm switch. If the alarm switch is closed, the set maximum low temperature1 value is invalid
isAlarmTemp2nd boolean Whether to open the alarm switch. If the alarm switch is closed, the set maximum low temperature2 value is invalid
isAlarmHumidity boolean Whether to open the alarm switch. If the alarm switch is closed, the set maximum low humidity value is invalid
temperatureUnit int Temperature unit, 0 is Celsius, 1 Fahrenheit
broadcastPower int broadcast Power
broadcastInterval int broadcast Interval
delayedRecordingTime int delayed RecordingTime
isOpenStorage boolean Whether the storage switch has been turned on

HtSensorV3Module. The following property values are obtained at the time of connection, so they can only be used after connection.

Name Type Description
firmwareVersion String firmware version
maxAlarmTemperature float The maximum temperature that has been set
minAlarmTemperature float The minimum temperature that has been set
maxAlarmHumidity int The maximum humidity that has been set
minAlarmHumidity int The maximum humidity that has been set
isAlarmTemperature boolean Whether to open the alarm switch. If the alarm switch is closed, the set maximum low temperature value is invalid
isAlarmHumidity boolean Whether to open the alarm switch. If the alarm switch is closed, the set maximum low humidity value is invalid
isOpenStorage boolean Whether the storage switch has been turned on

# Change log

  • **2022/08/29 Add document；
  • **2022/05/06 Add document；
Last Updated:: 8/21/2023, 6:14:31 PM