# MinewSensorKit说明文档

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

目前SDK仅支持工业温湿度传感器的使用。

# 前期工作

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

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

IndustrialHtSensor：扫描时获取到的工业温湿度传感器设备实例，继承自SensorModule；

# 导入到工程

开发环境

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

android {

    defaultConfig {
        applicationId "com.xxx.xxx"
        minSdkVersion 21
    }
}

1
2
3
4
5
6
7

将 industry_ht_sensor_sdk.jar添加到module的libs文件夹下，并在该module的build.gradle中添加如下语句（直接添加依赖）：
```
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
或者右键该jar文件，选择Add as Library，添加到当前module。

在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" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

1
2
3
4
5
6

# 使用

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

# 扫描部分

# 开始扫描

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

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

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
        }
    });
    //设置扫描时长5分钟，sdk默认扫描时长5分钟
        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

sdk内部并没有对蓝牙扫描时长进行处理，但是扫描是耗电操作，SDK默认5分钟就停止扫描了，如果还需要继续扫描，可以提供定时器或者刷新等操作以便继续调用扫描方法继续扫描设备。

# 取出数据

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

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

名称	类型	说明
macAddress	String	设备mac
name	String	设备名称，可自定义。工业温湿度传感器初始化名称为为“MST01”
rssi	int	信号强度

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

DeviceStaticInfoFrame deviceInforFrame = (DeviceStaticInfoFrame)module.getMinewFrame(HtFrameType.DEVICE_STATIC_INFO_FRAME);
IndustrialHtFrame industrialHtFrame = (IndustrialHtFrame) module.getMinewFrame(HtFrameType.INDUSTRIAL_HT_FRAME);
if (deviceInforFrame != null) {
    //设备mac地址
    String macAddress = deviceInforFrame.getMacAddress();
    //电量百分比
    int battery = deviceInforFrame.getBattery();
    //固件版本
    String firmwareVersion = deviceInforFrame.getFirmwareVersion();
}

if (industrialHtFrame != null) {
    //温湿度传感器当前温度
    float temperature = industrialHtFrame.getTemperature();
    //温湿度传感器当前湿度
    float humidity = industrialHtFrame.getHumidity();
    //传感器类型 0: 温湿度，1: 单温
    int type = industrialHtFrame.getType();
    //温度单位 为0表示摄氏度，为1表示华氏度
    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

工业温湿度设备有2种广播帧类型。

设备静态信息帧

DeviceStaticInfoFrame

名称	类型	说明
frameVersion	int	设备类型
firmwareVersion	String	固件版本
batteryLevel	int	电池电量百分比
macAddress	String	固件mac
peripheralSupportInfo	PeripheralSupportInfo	外设支持描述，包含设备产品id

工业温湿度帧

IndustrialHtFrame

名称	类型	说明
frameVersion	int	设备类型
tempHumiVersion	int	MST01 温湿度帧版本
type	int	传感器类型。0: 温湿度，1: 单温
sensorStatus	DeviceExceptionEnum	设备状态，如正常、传感器异常等
temperatureUnit	int	温度单位为0表示摄氏度，为1表示华氏度
temperature	float	传感器当前温度
humidity	float	传感器当前湿度
isMark	float	是否标记，1: 已经标记, 0: 未标记
deviceName	String	设置名字

# 连接

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

//停止扫描
manager.stopScan(context);
//设置设备秘钥
String key = "minewtech1234567";
manager.setSecretKey(key);
//连接，module为准备连接的设备 
IndustrialHtSensor module;
manager.connect(context,module);
//断开连接。macAddress为设备mac
manager.disConnect(macAddress);

1
2
3
4
5
6
7
8
9
10

注意：连接设备前，请确认是否扫描到设备，如果没扫描到设备广播，调用连接方法，将连接失败。

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

//设置监听器
manager.setOnConnStateListener(new OnConnStateListener() {
    
    /*
     * 连接过程中的状态回调
     *
     * @param macAddress      设备mac
     * @param connectionState 状态
     */
    @Override
    public void onUpdateConnState(String address, MSensorConnectionState state) {
        switch (state) {
            case Disconnect:
				//连接失败或者设备断开连接会回调，主动断开不会回调该状态
                break;
            case Connecting:
				//调用connect()后就会回调该状态
                break;
            case Connected:
                //初步连接成功，作为一个过渡阶段，此时并未真正成功
                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

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

MSensorConnectionState.Connecting，MSensorConnectionState.Connected: 连接设备中，在这里状态下不要做耗时操作，因为此时在连接设备发现服务，并发送认证数据等。
MSensorConnectionState.ConnectComplete: 此时传感器设备已经连接成功，可以进行读写操作，比如配置广播参数、传感器配置、读取历史数据等。
MSensorConnectionState.Disconnect: 连接失败或者设备断开连接会回调。如果APP主动调用manager.disConnect(macAddress);不会回调该状态。

# 读写

读写API如下：

    /**
     * 设置设备的秘钥
     * @param eaxKey 设备对应的秘钥
     */
    @Override
    public void setSecretKey(String macAddress, String password);


    /**
     * 读取温湿度历史数据
     *
     * @param macAddress 设备mac
     * @param startTime LE，起始时间戳 单位：秒
     * @param endTime LE，结束时间戳 单位：秒
     * @param systemTime LE，实时时间戳 单位：秒
     * @param listener   监听器
     */
    @Override
    public void readHtHistoryData(String macAddress,long startTime,long endTime,long systemTime, 	OnReceiveDataListener<HtHistoryData> listener);

    /**
     * 读取温度单位 
     *
     * @param macAddress 设备mac
     * @param listener   监听器 0使用摄氏度，1则使用华氏度
     */
    @Override
    public void queryTemperatureUnit(String macAddress, OnQueryResultListener<Integer> listener) ;

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

    /**
     * 设置设备信息帧广播参数
     *
     * @param macAddress 设备mac
     * @param advertisingInterval 广播间隔 单位毫秒,100ms ~ 5000ms 可调，刻度为 100ms；
     * @param txPower -40 -20 -16 -12 -8 -4 0 4dBm
     * @param listener   监听器
     */
    public void setDeviceInfoFrameAdvertisingParametersConfiguration(String macAddress, int advertisingInterval, int txPower, OnModifyConfigurationListener listener);

    /**
     * 查询设备信息帧广播参数
     *
     * @param macAddress 设备mac
     * @param listener   监听器
     */
    public void queryDeviceInfoFrameAdvertisingParametersConfiguration(String macAddress,  OnQueryResultListener<DeviceInfoAdvertisingParametersConfiguration>  listener);
    /**
     * 设置工业温湿度帧广播参数
     *
     * @param macAddress 设备mac
     * @param advertisingInterval 广播间隔 单位毫秒,广播间隔 1s ~ 60s 可调，刻度为 1s；
     * @param txPower -40 -20 -16 -12 -8 -4 0 4dBm
     * @param advertisingName 广播设备名
     * @param listener   监听器
     */
    public void setIndustryHTFrameAdvertisingParametersConfiguration(String macAddress, int advertisingInterval, int txPower, String advertisingName, OnModifyConfigurationListener listener);

    /**
     * 查询工业温湿度帧广播参数
     *
     * @param macAddress 设备mac
     * @param listener   监听器
     */
    public void queryIndustryHTFrameAdvertisingParametersConfiguration(String macAddress,  OnQueryResultListener<IndustryHtParametersConfiguration> listener);
    /**
     * 设置工业温湿度传感器配置
     *
     * @param macAddress 设备mac
     * @param htSettingData 触发阈值list 固定长度2
     * @param samplingInterval 采样间隔 单位：秒 ,1s ~24h，默认值 30s
     * @param listener   监听器
     */
    public void setIndustryHTSensorConfiguration(String macAddress, List<HTSensorSettingData> htSettingData,int samplingInterval,OnModifyConfigurationListener listener);

    /**
     * 查询工业温湿度传感器配置
     *
     * @param macAddress 设备mac
     * @param listener   监听器
     */
    public void queryIndustryHTSensorConfiguration(String macAddress, OnQueryResultListener<IndustryHtSensorConfiguration> listener);

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


    /**String macAddress
     * 恢复出厂设置
     *
     * @param macAddress 设备mac
     * @param listener   监听器
     */
    public void reset(String macAddress, OnModifyConfigurationListener listener);

    /**
     * 关机
     * @param macAddress 设备mac
     * @param 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

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

读取历史数据。

//读取温湿度传感器历史数据 时间戳单位：秒
long startTime;//开始时间填0则查传感器所有的温湿度历史数据
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

设置温度单位，温湿度传感器支持设置摄氏度和华氏度。

/**
 * 设置传感器温度单位
 *
 * @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

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

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

if(openAlarm1){
    //温湿度报警1打开
   	htSensorSettingData1.setOpenAlarmTemperature(true);//true打开温度1报警,false关闭温度1报警
	htSensorSettingData1.setHighTemperature(20f);//设置温度报警1最高报警温度默认值 20℃
	htSensorSettingData1.setLowTemperature(2f);//设置温度报警1最低报警温度 ，默认值 2℃ 
	htSensorSettingData1.setOpenAlarmHumidity(true);//true打开湿度1报警,false关闭湿度1报警
	htSensorSettingData1.setHighHumidity(60f);//设置湿度报警1最高报警温度默认值 60%
	htSensorSettingData1.setLowHumidity(50f);//设置湿度报警1最低报警温度 ，默认值 50%  
}else{
    //温湿度报警1打开
    htSensorSettingData1.setOpenAlarmTemperature(false);//false关闭温度1报警
	htSensorSettingData1.setHighTemperature(-128f);//默认值 -128f
	htSensorSettingData1.setLowTemperature(-128f);//设置温度报警1最低报警温度 ，默认值 -128f
	htSensorSettingData1.setOpenAlarmHumidity(false);//true打开湿度1报警,false关闭湿度1报警
	htSensorSettingData1.setHighHumidity(-128f);//设置湿度报警1最高报警温度默认值 -128f
	htSensorSettingData1.setLowHumidity(-128f);//设置湿度报警1最低报警温度 ，默认值 -128f
}
htSettingData.add(0,htSensorSettingData1);


HTSensorSettingData htSensorSettingData2 = new HTSensorSettingData();
if(openAlarm2){
    //温度报警2打开
   	htSensorSettingData2.setOpenAlarmTemperature(true);//true打开温度1报警,false关闭温度1报警
	htSensorSettingData2.setHighTemperature(30f);//设置温度报警1最高报警温度默认值 30℃
	htSensorSettingData2.setLowTemperature(15f);//设置温度报警1最低报警温度 ，默认值 15℃ 
	htSensorSettingData2.setOpenAlarmHumidity(false);//第二组报警不能设置湿度报警，所有这里填false
	htSensorSettingData2.setHighHumidity(-128f);//设置湿度报警2最高报警温度默认值 -128f
	htSensorSettingData2.setLowHumidity(-128f);//设置湿度报警2最低报警温度 ，默认值 -128f 
}else{
    //温湿度报警1打开
    htSensorSettingData2.setOpenAlarmTemperature(false);//false关闭温度1报警
	htSensorSettingData2.setHighTemperature(-128f);//默认值 -128f
	htSensorSettingData2.setLowTemperature(-128f);//设置温度报警1最低报警温度 ，默认值 -128f
	htSensorSettingData2.setOpenAlarmHumidity(false);//第二组报警不能设置湿度报警，所有这里填false
	htSensorSettingData2.setHighHumidity(-128f);//设置湿度报警2最高报警温度默认值 -128f
	htSensorSettingData2.setLowHumidity(-128f);//设置湿度报警2最低报警温度 ，默认值 -128f 
}
htSettingData.add(1,htSensorSettingData1);
int samplingInterval = 30;//采样间隔 1s ~24h，默认值 30s， 单位秒

manager.setIndustryHTSensorConfiguration(macAddress,htSettingData, samplingInterval,new OnModifyConfigurationListener(){
    @Override
    public void onModifyResult(boolean success) {
		//success为true，表明设置成功，反之为失败
    }
});

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

固件升级。

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

    /**
     * 升级成功回调，此时设备会主动跟手机断开连接，所以会触发OnConnStateListener回调，返回
     * MSensorConnectionState.Disconnect状态
     */
    @Override
    public void upgradeSuccess() {

    }
    
    /**
     * 升级失败
     */
    @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

设置广播参数。

//获取设备信息帧广播参数信息
DeviceInfoAdvertisingParametersConfiguration infoAdvParames ;
manager.queryDeviceInfoFrameAdvertisingParametersConfiguration(macAddress, new 				      OnQueryResultListener<DeviceInfoAdvertisingParametersConfiguration>() {
            @Override
            public void OnQueryResult(boolean queryResult, DeviceInfoAdvertisingParametersConfiguration queryInfo) {
                //queryResult为true，表明查询成功，反之为失败
                if(queryResult){
                    infoAdvParames=queryInfo;
                }else{
                    //查询失败
                }
            }
        });
//设置设备信息帧广播参数
manager.setDeviceInfoFrameAdvertisingParametersConfiguration(macAddress,infoAdvParames.getAdvertisingInterval(), 
                                         infoAdvParames.getTxPower(),new OnModifyConfigurationListener(){
    @Override
    public void onModifyResult(boolean success) {
		//success为true，表明设置成功，反之为失败
    }
});
//获取工业温湿度帧广播参数信息
IndustryHtParametersConfiguration htAdvParames ;
manager.queryIndustryHTFrameAdvertisingParametersConfiguration(macAddress, new 				      OnQueryResultListener<IndustryHtParametersConfiguration>() {
            @Override
            public void OnQueryResult(boolean queryResult, IndustryHtParametersConfiguration queryInfo) {
                //queryResult为true，表明查询成功，反之为失败
                if(queryResult){
                    htAdvParames = queryInfo;
                }else{
                    //查询失败
                }
            }
        });
//设置工业温湿度帧广播参数
manager.setIndustryHTFrameAdvertisingParametersConfiguration(macAddress,htAdvParames.getAdvertisingInterval(), 
                                         htAdvParames.getTxPower(),
                                         htAdvParames.getAdvertisingContent(),new OnModifyConfigurationListener(){
    @Override
    public void onModifyResult(boolean success) {
		//success为true，表明设置成功，反之为失败
    }
});

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

恢复出厂设置。

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

7.关机。

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

    }
});

1
2
3
4
5
6
7
8
9
10
11

# 历史记录

**2023/04/11 添加编辑文档；