# 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 door 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;

ThSensorModule: temperature and humidity sensor device, inherited from SensorModule;

DoorSensorModule: Door 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
    21

# 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 ThSensorModule and DoorSensorModule, 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 3, it means that the device is a temperature and humidity sensor, and if it is 4, it means a door 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:

ThFrame thFrame = (ThFrame) module.getMinewFrame(ThFrameType.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

    • DeviceStaticInfoFrame (useless)

    • HistoryErrorInfoFrame (useless)

    • ThFrame

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

  2. Door sensor

    • DoorStaticInfoFrame (useless)

    • HistoryErrorInfoFrame (useless)

    • DoorAlarmInfoFrame

      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

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
 */
void sendPassword(String macAddress, String password);

/**
 * Read historical temperature and humidity data
 *
 * @param macAddress device mac
 * @param listener   listener
 */
void readThHistoryData(String macAddress, OnReceiveDataListener<ThHistoryData> listener);

/**
 * Read door sensor historical data
 *
 * @param macAddress device mac
 * @param listener   listener
 */
void readDoorHistoryData(String macAddress, OnReceiveDataListener<DoorHistoryData> listener);

/**
 * Set temperature unit
 *
 * @param macAddress device mac
 * @param isCelsius  Whether set to Celsius
 * @param listener   listener
 */
void setTemperatureUnit(String macAddress, boolean isCelsius, OnSetTemperatureUnitListener 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
 */
void setThAlarmValue(String macAddress, int minTemp, int maxTemp, int minHumi, 
                     int maxHumi, OnModifyConfigurationListener listener);


/**
 * Turn off temperature and humidity to trigger alarm
 *
 * @param macAddress device mac
 * @param listener   listener
 */
void setThAlarmOff(String macAddress, OnModifyConfigurationListener listener);

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

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

/**
 * reset
 *
 * @param macAddress device mac
 */
void reset(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

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.readThHistoryData(mAddress, 
                          new OnReceiveDataListener<ThHistoryData>() {
    @Override
    public void receiverData(String macAddress, 
                             List<ThHistoryData> historyData) {

    }
});

//Read historical data of door sensor
manager.readDoorHistoryData(mAddress, 
                            new OnReceiveDataListener<DoorHistoryData>() {
    @Override
    public void receiverData(String macAddress, 
                             List<DoorHistoryData> historyData) {

    }
});
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19

  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 OnSetTemperatureUnitListener() {
    @Override
    public void onSetTemperatureUnitResult(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, 
                        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

  4. Turn off the temperature and humidity alarm.

    manager.setThAlarmOff(macAddress, 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

  5. 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

  6. Historical data storage switch.

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

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

  7. 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 Device type, 3 means temperature and humidity sensor, 4 means door sensor

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

ThSensorModule. 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
isOpenThAlarm boolean Whether to open the alarm switch. If the alarm switch is closed, the set maximum low temperature humidity value is invalid
temperatureUnit int Temperature unit, 0 is Celsius, 1 Fahrenheit
isOpenStorage boolean Whether the storage switch has been turned on

DoorSensorModule. 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
isOpenStorage boolean Whether the storage switch has been turned on

# Change log

  • 2022/05/05 sdk fix bugs;
  • 2020/10/27 sdk repaired abnormal type conversion in Vietnamese and other system environments;
  • 2020/07/03 Add document；
Last Updated:: 8/21/2023, 6:14:31 PM