# MinewSensorKit说明文档

本套SDK仅支持Minew公司出品的蓝牙传感器设备。通过SDK可以帮助开发者处理手机和传感器之间的一切工作，包括：扫描设备，广播数据、连接设备，向设备写入数据，从设备接收数据等。

目前SDK仅支持温湿度传感器和门磁传感器的使用。

# 前期工作

整体框架：MinewSensorManager为设备管理类，在APP运行时始终是单例。SensorModule是设备实例类，此套件会为每一个设备生成一个实例，在扫描和连接后都会使用，内部包含设备广播数据，在扫描期间该数据会随着设备不停广播而更新。

MinewSensorCenterManager：设备管理类，可以扫描周围的ESL设备，并且可以连接它们，校验它们等；

SensorModule：扫描时获取到的设备实例，通过type属性来判断为温湿度还是门磁传感器；

ThSensorModule：温湿度传感器设备，继承自SensorModule；

DoorSensorModule：门磁传感器设备，继承自SensorModule。

# 导入到工程

  1. 开发环境

    sdk最低支持Android 4.3，对应API Level为18。在module的build.gradle中设置minSdkVersion为18或18以上

    android {

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

  2. 将 MinewSensorKit.jar添加到module的libs文件夹下，并在该module的build.gradle中添加如下语句（直接添加依赖）：

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

    或者右键该jar文件，选择Add as Library，添加到当前module。

  3. 在AndroidManifest.xml需要以下权限，如果targetSdkVersion大于23，则需要做权限管理以获取权限：

    <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" />


//targetSdkVersion版本选择 31（Android 12）蓝牙权限用如下方式添加
<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
    22

​

# 使用

sdk分为扫描、连接和读写三个阶段。

# 扫描部分

# 开始扫描

开启蓝牙扫描需要首先打开蓝牙，如果未打开蓝牙就去扫描，APP会闪退。可通过BLETool.isBluetoothTurnOn来判断蓝牙是否已经打开。

Android6.0系统以上，进行BLE扫描时，需要先申请到定位权限后并且打开定位开关才能进行！

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

sdk内部并没有对蓝牙扫描时长进行处理，但是扫描是耗电操作，一般90秒就可以停止扫描了，如果还需要继续扫描，可以提供刷新等操作以便继续扫描。

# 取出数据

在扫描期间，APP能够通过sdk获取到设备当前的一部分数据。如下所示通过ThSensorModule获取设备温湿度数据，该数据保存在广播帧对象中。

sdk提供了SensorModule作为ThSensorModule和DoorSensorModule的基类，用于存储传感器设备的公有数据，如下表所示：

名称 类型 说明
macAddress String 设备mac
name String 设备名称，可自定义。温湿度传感器初始化名称为“S3”，门磁为“S4”
rssi int 信号强度
type int 设备类型。如果为3，表示设备是温湿度传感器，为4表示为门磁传感器

SensorModule还保存了一个Map，内部用于存储其在扫描期间获取到的设备广播数据帧，可通过如下方式取出：

ThFrame thFrame = (ThFrame) module.getMinewFrame(ThFrameType.TH_FRAME);
if (thFrame != null) {
    //温湿度传感器当前温度
    float temperature = thFrame.getTemperature();
    //温湿度传感器当前湿度
    float humidity = thFrame.getHumidity();
}
1
2
3
4
5
6
7

温湿度和门磁传感器各有各自的帧类型。

  1. 温湿度传感器

    • DeviceStaticInfoFrame（无用）

    • HistoryErrorInfoFrame（无用）

    • ThFrame

      名称 类型 说明
      temperatureUnit int 温度单位，为0表示摄氏度，为1表示华氏度
      power int 电量
      temperature float 温度
      humidity float 湿度

  2. 门磁传感器

    • DoorStaticInfoFrame（无用）

    • HistoryErrorInfoFrame（无用）

    • DoorAlarmInfoFrame

      名称 类型 说明
      power int 电量
      doorSensorState boolean 门磁触发状态
      doorAlarmState boolean 防拆报警状态
      doorTriggerTag boolean 门磁触发标记

# 连接

连接前一般需要先停止扫描。sdk提供了连接和断开连接方法。

//停止扫描
manager.stopScan();
//连接，module为准备连接的设备 
manager.connect(module);
//断开连接。macAddress为设备mac
manager.disConnect(macAddress);
1
2
3
4
5
6

在调用connect()后，sdk中会对连接过程会有状态监听。

//设置监听器
manager.setOnConnStateListener(new OnConnStateListener() {
    
    /*
     * 连接过程中的状态回调
     *
     * @param macAddress      设备mac
     * @param connectionState 状态
     */
    @Override
    public void onUpdateConnState(String address, SensorConnectionState state) {
        switch (state) {
            case Disconnect:
				//连接失败或者设备断开连接会回调，主动断开不会回调该状态
                break;
            case Connecting:
				//调用connect()后就会回调该状态
                break;
            case Connected:
                //初步连接成功，作为一个过渡阶段，此时并未真正成功
                break;
            case VerifyPassword:
				//密码验证，回调该状态后，设备需要写入密码，通过sendPassword()写入
                manager.sendPassword(address, "minew123")
                break;
            case PasswordError:
				//密码错误，设备会断开连接，并且不会回调Disconnect状态
                break;           
            case FirmwareUpgradeSuccessfully:
				//固件升级成功，不会回调Disconnect状态
                break;
            case ConnectComplete:
				//连接完成，此时设备可进行读写操作
                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

在连接过程中，sdk会返回多个连接状态到app中，app需要做好处理。

  • ConnectionState.VerifyPassword: 传感器连接需要验证密码，一旦回调该状态，那么就需要通过manager.sendPassword(address, "minew123")来写入密码。注意，密码长度为8位。
  • ConnectionState.PasswordError: 密码错误，传感器设备会断开连接，并且不会返回ConnectionState.Disconnect状态。
  • ConnectionState.ConnectComplete: 此时传感器设备已经连接成功，可以进行读写操作，比如读取历史数据等。
  • ConnectionState.FirmwareUpgradeSuccessfully: 进行固件升级，sdk会给出另一个回调方法，并且升级成功后会回调该状态，连接会断开，且不会回调ConnectionState.Disconnect状态。
  • ConnectionState.Disconnect: 连接失败或者设备断开连接会回调，主动断开不会回调该状态。即调用manager.disConnect(macAddress);不会回调该状态。注意：升级失败是会回调该状态的。

# 读写

读写API如下：

/**
 * 发送（写入）密码，注意密码是8位
 *
 * @param macAddress 设备mac
 * @param password   密码
 */
void sendPassword(String macAddress, String password);

/**
 * 读取温湿度历史数据
 *
 * @param macAddress 设备mac
 * @param listener   监听器
 */
void readThHistoryData(String macAddress, OnReceiveDataListener<ThHistoryData> listener);

/**
 * 读取门磁历史数据
 *
 * @param macAddress 设备mac
 * @param listener   监听器
 */
void readDoorHistoryData(String macAddress, OnReceiveDataListener<DoorHistoryData> listener);

/**
 * 设置温度单位
 *
 * @param macAddress 设备mac
 * @param isCelsius  是否设置为摄氏度
 * @param listener   监听器
 */
void setTemperatureUnit(String macAddress, boolean isCelsius, OnSetTemperatureUnitListener listener);


/**
 * 设置温湿度报警值
 *
 * @param macAddress 设备mac
 * @param minTemp    最低温度
 * @param maxTemp    最高温度
 * @param minHumi    最低湿度
 * @param maxHumi    最高湿度
 * @param listener   监听器
 */
void setThAlarmValue(String macAddress, int minTemp, int maxTemp, int minHumi, 
                     int maxHumi, OnModifyConfigurationListener listener);


/**
 * 关闭温湿度触发报警
 *
 * @param macAddress 设备mac
 * @param listener   监听器
 */
void setThAlarmOff(String macAddress, OnModifyConfigurationListener listener);

/**
 * 固件升级
 *
 * @param macAddress  设备mac
 * @param upgradeData 升级包数据
 * @param listener    监听器
 */
void firmwareUpgrade(String macAddress, byte[] upgradeData, OnFirmwareUpgradeListener listener);

/**
 * 历史数据存储开关
 *
 * @param macAddress 设备mac
 * @param isOpen     开或关
 * @param listener   监听器
 */
void setOpenHistoryDataStore(String macAddress, boolean isOpen, OnModifyConfigurationListener listener);

/**
 * 恢复出厂设置
 *
 * @param macAddress 设备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

对部分方法进行补充说明：

  1. 读取历史数据。

    注意：温湿度传感器和门磁传感器读取历史数据使用的是不同的api，传入的接口类型也不一样。但二者每次返回的历史数据都是设备存储的全部历史数据。

    //读取温湿度传感器历史数据
manager.readThHistoryData(mAddress, 
                          new OnReceiveDataListener<ThHistoryData>() {
    @Override
    public void receiverData(String macAddress, 
                             List<ThHistoryData> historyData) {

    }
});

//读取门磁传感器历史数据
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. 设置温度单位，温湿度传感器支持设置摄氏度和华氏度。

    /**
 * 存储开关设置
 *
 * @param macAddress 设备mac
 * @param isCelsius  是否设置为摄氏度
 * @param listener   监听器
 */
manager.setTemperatureUnit(macAddress, true, new OnSetTemperatureUnitListener() {
    @Override
    public void onSetTemperatureUnitResult(boolean success) {
		//success为true，表明设置成功，反之为失败
    }
});
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

  3. 设置温湿度报警值。请注意，摄氏度单位下，温度最大为85°C，最小为-40°C，华氏度下，温度最大为185°F，最小为-40°F；湿度最大为100，最小为0。

    
manager.setThAlarmValue(macAddress, 
                        10, 
                        60, 
                        10, 
                        60, new OnModifyConfigurationListener(){
    @Override
    public void onModifyResult(boolean success) {
		//success为true，表明设置成功，反之为失败
    }
});
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11

  4. 关闭温湿度报警。

    manager.setThAlarmOff(macAddress, new OnModifyConfigurationListener() {
    @Override
    public void onModifyResult(boolean success) {
		//success为true，表明设置成功，反之为失败
    }
});
    1
    2
    3
    4
    5
    6

  5. 固件升级。

    /**
 * 固件升级
 *
 * @param macAddress  设备mac
 * @param upgradeData 升级包数据
 * @param listener    监听器
 */
manager.firmwareUpgrade(mac, upgradeData, new OnFirmwareUpgradeListener() {
    
    /**
     * 升级包数据写入进度
     */
    @Override
    public void updateProgress(int progress) {

    }

    /**
     * 升级成功会触发OnConnStateListener回调，返回
     * ConnectionState.Firmware_Upgrade_Successfully状态
     */
    @Override
    public void upgradeSuccess() {

    }
    
    /**
     * 升级失败。升级失败会断开连接，会触发OnConnStateListener回调，返回
     * ConnectionState.Disconnect状态
     */
    @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. 历史数据存储开关。

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

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

  7. 重置。

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

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

# 附录

SensorModule：

名称 类型 描述
macAddress String 设备mac
name String 设备名称，APP可自定义
type int 设备类型，为3表示是温湿度传感器，4为门磁传感器

注意，扫描期间获取到的数据都在其广播帧中。

ThSensorModule，以下属性值在连接时获取，因此在连接后才能使用。

名称 类型 描述
firmwareVersion String 固件版本
maxAlarmTemperature float 设置的最高温度
minAlarmTemperature float 设置的最低温度
maxAlarmHumidity int 设置的最高湿度
minAlarmHumidity int 设置的最低湿度
isOpenThAlarm boolean 是否开启报警开关。如果报警开关关闭，那么设置的最高低温湿度值就是无效的
temperatureUnit int 温度单位，0为摄氏度，1位华氏度
isOpenStorage boolean 是否已经打开存储开关

DoorSensorModule，以下属性值在连接时获取，因此在连接后才能使用。

名称 类型 描述
firmwareVersion String 固件版本
isOpenStorage boolean 是否已经打开存储开关

# 历史记录

  • 2022/05/05 sdk修复已知bug;
  • 2020/10/27 sdk修复越南语等系统环境下的类型转换异常；
  • 2020/07/03 添加文档；
上次更新:: 2023/8/21 18:14:31