# MinewSensorKit说明文档

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

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

# 前期工作

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

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

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

IndustrialHtSensor：蓝牙温湿度传感器设备，继承自SensorModule；

HtSensorV3Module：温湿度传感器设备，继承自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作为HtSensorV3Module和IndustrialHtSensor的基类，用于存储传感器设备的公有数据，如下表所示：

名称 类型 说明
macAddress String 设备mac
name String 设备名称，可自定义。温湿度传感器初始化名称为“S3”，蓝牙为“MST01”
rssi int 信号强度
type int 设备类型。如果为30，表示设备是温湿度传感器，为32表示为单温传感器，为33表示为蓝牙温湿度传感器，为34表示为蓝牙单温传感器

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

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

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

  1. 温湿度传感器

    • HtFrame

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

  2. 蓝牙温湿度传感器

    • IndustrialHtFrame

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

# 连接

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

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

注意：只针对工业温湿度设备和工业单温设备，连接设备前需要校验下是否获取到设备静态信息帧(DeviceStaticInfoFrame)。如果没获取到静态信息帧，sdk默认走旧协议解析数据，导致读取信息错误并且不能无法配置信息。请在保证获取到静态信息帧的情况下，再去连接设备

//工业温湿度设备和工业单温设备
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
8
9

在调用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如下：

    /**
     * 发送（写入）密码
     *
     * @param macAddress 设备mac
     * @param password   密码
     */
    @Override
    public void sendPassword(String macAddress, String password);
	/**
     * 设置设备名称
     *
     * @param macAddress 设备mac
     * @param name   名称
     * @param listener   监听器
     */
    @Override
    public void setSensorName(String macAddress, String name, OnModifyConfigurationListener listener);

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

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

    /**
     * 设置温湿度报警值，如果关闭温湿度报警，就都传入0x8000（两个字节）
     *
     * @param macAddress 设备mac
     * @param minTemp    最低温度
     * @param maxTemp    最高温度
     * @param minHumi    最低湿度
     * @param maxHumi    最高湿度
     * @param listener   监听器
     */
    @Override
    public void setHtAlarmValue(String macAddress, boolean isTempWarn, boolean isHumiWarn, float minTemp, float maxTemp, int minHumi, int maxHumi, OnModifyConfigurationListener listener);

    /**
     * 设置工业温湿度报警值，如果关闭温湿度报警，就都传入0x8000（两个字节）
     *
     * @param macAddress
     * @param isTempWarn1 温度1报警开关
     * @param isTempWarn2 温度2报警开关
     * @param isHumiWarn  湿度报警开关
     * @param minTemp1    温度1下界
     * @param maxTemp1    温度1上界
     * @param minTemp2    温度2下界
     * @param maxTemp2    温度2上界
     * @param minHumi     湿度下界
     * @param maxHumi     湿度上界
     * @param 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);

    /**
     * 设置广播功率
     *
     * @param macAddress 设备mac
     * @param power      广播功率 广播功率的值只能设置 -40, -20, -16, -12, -8, -4, 0, 4 dbm.
     * @param listener   修改结果监听器
     */
    @Override
    public void setBroadcastPower(String macAddress, int power, OnModifyConfigurationListener listener);

    /**
     * 设置广播间隔
     *
     * @param macAddress 设备mac
     * @param interval   广播间隔。广播间隔范围为 100 - 5000ms
     * @param listener   修改结果监听器
     */
    @Override
    public void setBroadcastInterval(String macAddress, int interval, OnModifyConfigurationListener listener);

    /**
     * 设置延迟记录时间。延时时间为0-18h，最大时间能设置为18小时整，按键开机默认是10min，固件调整延时时间范围0-18h，支持10min以内时间设置
     *
     * @param macAddress 设备mac
     * @param time       时间，单位秒（s)
     * @param listener   修改结果监听器
     */
    @Override
    public void setDelayedRecordingTime(String macAddress, int time, OnModifyConfigurationListener listener);

    /**
     * 关机
     *
     * @param macAddress 设备mac
     * @param listener   修改结果监听器
     */
    @Override
    public void powerOff(String macAddress, OnModifyConfigurationListener listener);

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

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

    /**
     * 恢复出厂设置
     *
     * @param macAddress 设备mac
     * @param listener   监听器
     */
    @Override
    public void reset(String macAddress, OnModifyConfigurationListener listener);
	
	 /**
     * 设置温湿度广播间隔和设置信息帧广播间隔(版本大于等于3.1.0用这个方法)
     *
     * @param macAddress 设备mac
     * @param htInterval 温湿度广播间隔,unit毫秒， 范围(1-600单位秒)
     * @param infoInterval 设备信息广播间隔,unit毫秒，范围(100-5000单位毫秒)
     * @param listener   监听器
     */
    @Override
	public void setMultiBroadcastInterval(String macAddress, int htInterval, int infoInterval, OnModifyConfigurationListener 		listener)

	 /**
     * 设置数据采集间隔(版本大于大于等于3.1.0用这个方法)
     *
     * @param macAddress 设备mac
     * @param interval 数据采集间隔 unit毫秒，范围(0-24单位小时)
     * @param 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

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

  1. 读取历史数据。

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

    /**
 * 存储开关设置
 *
 * @param macAddress 设备mac
 * @param isCelsius  是否设置为摄氏度
 * @param listener   监听器
 */
manager.setTemperatureUnit(macAddress, true, new OnModifyConfigurationListener() {
    @Override
    public void onModifyResult(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.setHtAlarmValue(macAddress, 
                        true,
                        true,
                        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
    12
    13

  4. 固件升级。

    /**
 * 固件升级
 *
 * @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

  5. 历史数据存储开关。

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

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

  6. 重置。

    /**
 * 重置
 *
 * @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 设备类型。如果为30，表示设备是温湿度传感器，为32表示为单温传感器，为33表示为蓝牙温湿度传感器，为34表示为蓝牙单温传感器

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

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

名称 类型 描述
firmwareVersion String 固件版本
alarmMaxTemp1st float 设置的最高温度
alarmMinTemp1st float 设置的最低温度
alarmMaxTemp2nd float 设置的最高温度
alarmMinTemp2nd float 设置的最低温度
alarmMaxHumi int 设置的最高湿度
alarmMinHumi int 设置的最低湿度
isAlarmTemp1st boolean 是否开启第一组温度报警开关。如果报警开关关闭，那么设置的最高低温湿度值就是无效的
isAlarmTemp2nd boolean 是否开启第二组温度报警开关。如果报警开关关闭，那么设置的最高低温湿度值就是无效的
isAlarmHumidity boolean 是否开启湿度报警开关。如果报警开关关闭，那么设置的最高低温湿度值就是无效的
temperatureUnit int 温度单位，0为摄氏度，1位华氏度
broadcastPower int 广播功率
broadcastInterval int 广播间隔
delayedRecordingTime int 延迟记录时间
isOpenStorage boolean 是否已经打开存储开关

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

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

# 历史记录

  • **2022/08/29 添加文档；
  • **2022/05/06 添加文档；
上次更新:: 2023/8/21 18:14:31