# MinewSensorKit说明文档

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

目前SDK仅支持资产温度标签传感器的使用。

# 前期工作

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

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

MST03Entity：扫描时获取到的资产温度标签传感器设备实例，继承自BaseBleDeviceEntity；

# 导入到工程

开发环境

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

android {

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

1
2
3
4
5
6
7

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

implementation files('libs/base_ble_library.jar')
implementation files('libs/minew_mst03.jar')
implementation 'org.lucee:bcprov-jdk15on:1.52.0'

1
2
3

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

添加.so库文件，App目录下build.gradle添加如下配置

android {
    defaultConfig {
  
        ndk {
            abiFilters 'armeabi-v7a','arm64-v8a','x86','x86_64'
        }

    }
    sourceSets {
        main {
            jniLibs.srcDirs = ['libs']
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" tools:node="replace" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" tools:node="replace" />
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
    <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
    <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

    <!-- Required to maintain app compatibility. -->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
        android:maxSdkVersion="32" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
        android:maxSdkVersion="32"
        />

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

# 使用

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

# 扫描部分

# 开始扫描

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

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

MST03SensorBleManager mBleManager = 	MST03SensorBleManager.getInstance();

switch (BLETool.checkBluetooth(this)){
    case BLE_NOT_SUPPORT:
        Toast.makeText(this, "Not Support BLE", Toast.LENGTH_SHORT).show();
        break;
    case BLUETOOTH_ON:
		//设置扫描时长5分钟，sdk默认扫描时长5分钟
		mBleManager.startScan(this, 5 * 60 * 1000, new OnScanDevicesResultListener<MST03Entity>() {

            @Override
            public void onScanResult(List<MST03Entity> list) {
                
            }

            @Override
            public void onStopScan(List<MST03Entity> list) {

            }

        });
        
        break;
    case BLUETOOTH_OFF:
        Intent enableIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);
        startActivityForResult(enableIntent, 4);
        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内部并没有对蓝牙扫描时长进行处理，但是扫描是耗电操作，SDK默认5分钟就停止扫描了，如果还需要继续扫描，可以提供定时器或者刷新等操作以便继续调用扫描方法继续扫描设备。

# 取出数据

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

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

名称	类型	说明
macAddress	String	设备mac
name	String	设备名称
rssi	int	信号强度

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

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

if (combinationFrame != null) {
    //温湿度传感器当前温度
    float temperature = combinationFrame.getTemperature();
    //三轴加速度
    float xAxis = combinationFrame.getxAxi();
    float yAxis = combinationFrame.getyAxis();
    float zAxis = combinationFrame.getzAxis();
}

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

资产温度标签传感器设备有2种广播帧类型。

设备静态信息帧

DeviceStaticInfoFrame

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

组合帧
- CombinationFrame
  
  名称类型说明
  
  temperature float 传感器当前温度
  
  xAxis float 三轴加速度x
  
  yAxis float 三轴加速度y
  
  zAxis float 三轴加速度z

名称	类型	说明
temperature	float	传感器当前温度
xAxis	float	三轴加速度x
yAxis	float	三轴加速度y
zAxis	float	三轴加速度z

# 连接

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

MST03SensorBleManager mBleManager = 	MST03SensorBleManager.getInstance();

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

1
2
3
4
5
6
7
8
9
10
11
12

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

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

//设置监听器
mBleManager.setOnConnStateListener(new OnConnStateListener() {
    
    /*
     * 连接过程中的状态回调
     *
     * @param macAddress      设备mac
     * @param connectionState 状态
     */
    @Override
    public void onUpdateConnState(String address, BleConnectionState state) {
        switch (state) {
            case Disconnect:
				//连接失败或者设备断开连接会回调，主动断开不会回调该状态
                break;

            case Connecting:
				//调用connect()后就会回调该状态
                break;
            case Connected:
                //初步连接成功，作为一个过渡阶段，此时并未真正成功
                break;
            case AuthenticateFail:
				//秘钥检验失败。
                break;
            case AuthenticateSuccess:
				//秘钥检验成功，
                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

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

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

# 读写

读写API如下：

    /**
     * 设置设备秘钥
     * @param macAddress 设备mac
     * @param secretKey 秘钥key
     * @param listener
     */
    public void setDeviceSecretKey(String macAddress, String secretKey, OnModifyConfigurationListener listener);


    /**
     * 查询设备版本信息
     * @param macAddress 设备mac
     * @param listener   监听器
     */
    public void queryDeviceFirmwareInfo(String macAddress, OnQueryResultListener<FirmwareVersionModel>  listener);

    /**
     * 读取历史数据
     *
     * @param macAddress 设备mac
     * @param rules 历史数据获取规则，0 表示获取所有数据, 1 表示获取某个时间段的数据,当rules==0,startTime、endTime 都不需要传，默认传0
     * @param startTime 起始时间戳 单位：秒
     * @param endTime 结束时间戳 单位：秒
     * @param systemTime 实时时间戳 单位：秒
     * @param listener   监听器
     */
    public void queryHistoryData(String macAddress,int rules,long startTime,long endTime,long systemTime, OnQueryResultListener<HistoryHtData>  listener);




    /**
     * 查询广播帧广播参数
     * @param macAddress 设备mac
     * @param slot 查询广播的通道值，默认值0
     * @param listener   监听器
     */
    public void queryAdvParametersConfiguration(String macAddress,int slot,  OnQueryResultListener<AdvParametersConfiguration>  listener);
    /**
     * 设置广播帧广播参数
     *
     * @param macAddress 设备mac
     * @param frameType FrameType枚举获取 getFrameTypeVersion()
     * @param slotNumber 设置广播对应的通道值
     * @param advertisingInterval 广播间隔 单位毫秒,广播间隔 1s ~ 60s 可调，刻度为 1s；
     * @param txPower -40 -20 -16 -12 -8 -4 0 4dBm
     * @param listener   监听器
     */
    public void setAdvParametersConfiguration(String macAddress,String frameType, int slotNumber,int advertisingInterval, int txPower, OnModifyConfigurationListener listener);


    /**
     * 设置温湿度传感器配置
     *
     * @param macAddress 设备mac
     * @param htSensorConfiguration 传感器配置
     * @param listener   监听器
     */
    public void setHTSensorConfiguration(String macAddress, HtSensorConfiguration htSensorConfiguration, OnModifyConfigurationListener listener);

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

	/**
     * 固件升级
     *
     * @param macAddress  设备mac
     * @param isLinkUpgrade true url升级，false 固件包升级。默认值false,不支持url升级方式
     * @param dfuTarget isLinkUpgrade =true, dfuTarget = 0
     * @param upgradeData 升级包数据
     * @param listener    监听器
     */
    public void firmwareUpgrade(String macAddress,boolean isLinkUpgrade,int dfuTarget,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

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

设置设备秘钥。

MST03SensorBleManager mBleManager = 	MST03SensorBleManager.getInstance();
String secretKey = "3141592653589793"
mBleManager.setSecretKey(mAddress,secretKey);

1
2
3
4

查询设备版本信息。

MST03SensorBleManager mBleManager = 	MST03SensorBleManager.getInstance();
    /**
     * 查询设备版本信息
     * @param macAddress 设备mac
     * @param listener   监听器
     */
mBleManager.queryDeviceFirmwareInfo(macAddress,new OnQueryResultListener<FirmwareVersionModel>() {
            @Override
            public void OnQueryResult(boolean b, FirmwareVersionModel firmwareVersionModel) {
				//b true查询成功，false查询失败firmwareVersionModel=null。
                Toast.makeText(context,"Query Result:"+b,Toast.LENGTH_LONG).show();
                if(b){
                    List<VersionInfo> versionInfoList = firmwareVersionModel.getVersionInfoList();
                    String firmwareName = versionInfoList.get(0).getFirmwareName();
                    int firmwareType = versionInfoList.get(0).getFirmwareType();
                    String firmwareVersion = versionInfoList.get(0).getFirmwareVersion();
                }
            }
        });

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

查询广播帧广播参数和配置广播参数。

    /**
     * 设置广播帧广播参数
     *
     * @param macAddress 设备mac
     * @param frameType FrameType枚举获取 
     * @param slotNumber 设置广播对应的通道值
     * @param advertisingInterval 广播间隔 单位毫秒,广播间隔 1s ~ 60s 可调，刻度为 1s；
     * @param txPower -40 -20 -16 -12 -8 -4 0 4dBm
     * @param listener   监听器
     */
MST03SensorBleManager mBleManager = 	MST03SensorBleManager.getInstance();
MST03Entity module
String macAddress = module.getMacAddress();
//slot = 0 DeviceStaticInfoFrame 、slot = 1 CombinationFrame
//查询DeviceStaticInfoFrame广播帧广播 
AdvParametersConfiguration deviceInfoAdvParametersConfiguration = null;
mBleManager.queryAdvParametersConfiguration(macAddress, 0, new OnQueryResultListener<AdvParametersConfiguration>() {
    @Override
    public void OnQueryResult(boolean b, AdvParametersConfiguration advParametersConfiguration) {
        if(b){
            deviceInfoAdvParametersConfiguration = advParametersConfiguration;
        }
        Toast.makeText(context,"Query Adv Result:"+b,Toast.LENGTH_LONG).show();
    }
});
//设置DeviceStaticInfoFrame广播帧参数
mBleManager.setAdvParametersConfiguration(macAddress, deviceInfoAdvParametersConfiguration.getFrameType(), 						         deviceInfoAdvParametersConfiguration.getSlotNumber(),
        1000,-4,new OnModifyConfigurationListener() {
    @Override
    public void onModifyResult(boolean b) {

        Toast.makeText(context,"Set Adv Parameters Result:"+b,Toast.LENGTH_LONG).show();
    }
});

//查询CombinationFrame广播帧广播 
AdvParametersConfiguration combinationAdvParametersConfiguration = null
mBleManager.queryAdvParametersConfiguration(macAddress, 1, new OnQueryResultListener<AdvParametersConfiguration>() {
    @Override
    public void OnQueryResult(boolean b, AdvParametersConfiguration advParametersConfiguration) {
        if(b){
            combinationAdvParametersConfiguration = advParametersConfiguration;
        }
        Toast.makeText(context,"Query Adv Result:"+b,Toast.LENGTH_LONG).show();
    }
});
//设置CombinationFrame广播帧参数
mBleManager.setAdvParametersConfiguration(macAddress, combinationAdvParametersConfiguration.getFrameType(), 						         combinationAdvParametersConfiguration.getSlotNumber(),
        1000,-4,new OnModifyConfigurationListener() {
    @Override
    public void onModifyResult(boolean b) {

        Toast.makeText(context,"Set Adv Parameters Result:"+b,Toast.LENGTH_LONG).show();
    }
});

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

查询温度历史数据

    /**
     * 读取历史数据
     *
     * @param macAddress 设备mac
     * @param rules 历史数据获取规则，0 表示获取所有数据, 1 表示获取某个时间段的数据,当rules==0,startTime、endTime 都不需要传，默认传0
     * @param startTime 起始时间戳 单位：秒
     * @param endTime 结束时间戳 单位：秒
     * @param systemTime 实时时间戳 单位：秒
     * @param listener   监听器
     */
long systemTime = System.currentTimeMillis()/1000;
long startTime = (systemTime-60*60*1000*24)/1000;
long endTime = systemTime;

int rule = 0;

mBleManager.queryHistoryData(macAddress,rule, startTime, endTime, systemTime, new OnQueryResultListener<HistoryHtData>() {

    @Override
    public void OnQueryResult(boolean b, HistoryHtData historyHtData) {
        if(b){
               List<HtData> htDataList = historyHtData.getHistoryDataList();
               for (HtData htData : htDataList) {
                        
               }
        }else{
            Toast.makeText(context,"selectHTHistoryData Result: fail",Toast.LENGTH_LONG).show();
        }

    }


});

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

查询传感器参数和配置传感器参数。

//查询传感器参数
HtSensorConfiguration htSensorConfig = null;
mBleManager.queryHTSensorConfiguration(macAddress, new OnQueryResultListener<HtSensorConfiguration>() {
    @Override
    public void OnQueryResult(boolean b, HtSensorConfiguration htSensorConfiguration) {
        if(b){
            htSensorConfig = htSensorConfiguration;
            //采集间隔。单位秒
            int samplingInterval = htSensorConfig.getSamplingInterval();
            //延迟记录时间。单位秒.
            int delay = htSensorConfig.getDelay();
            //2组温度阈值数据
            List<SensorSettingData> htSettingData = htSensorConfig.getHtSettingData();
        }
        Toast.makeText(context,"Query Result:"+b,Toast.LENGTH_LONG).show();
    }
});
//设置传感器参数
        List<SensorSettingData> htSettingData = new ArrayList<>();
		//常温上下限配置范围：0℃~50℃,湿度设置默认值为无效值-128
        SensorSettingData normalSettingData1 = new SensorSettingData();
        normalSettingData1.setHighTemperature(40f);
        normalSettingData1.setLowTemperature(5f);
        normalSettingData1.setHighHumidity(-128f);
        normalSettingData1.setLowHumidity(-128f);     
        htSettingData.add(settingData1);
		//低温上下限配置范围：-30℃~-1℃,湿度设置默认值为无效值-128
        SensorSettingData lowSettingData1 = new SensorSettingData();
        lowSettingData1.setHighTemperature(-30f);
        lowSettingData1.setLowTemperature(-1f);
        lowSettingData1.setHighHumidity(-128f);
        lowSettingData1.setLowHumidity(-128f);

        HtSensorConfiguration htSensorConfiguration = new HtSensorConfiguration();
        htSensorConfiguration.setDelay(5*60);//延迟测温：默认烧录5min,App可配置范围:5min~30min，单位秒
        htSensorConfiguration.setSamplingInterval(30);//采样间隔 1s ~24h，默认值 10s，采样间隔为5秒的倍数。单位秒
        htSensorConfiguration.setHtSettingData(htSettingData);

mBleManager.setHTSensorConfiguration(macAddress, htSensorConfiguration,new OnModifyConfigurationListener() {
    @Override
    public void onModifyResult(boolean b) {
        Toast.makeText(DeviceConnectedCompleteActivity.this,"Set Sensor Parameters Result:"+b,Toast.LENGTH_LONG).show();
    }
});

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

固件升级。

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

    /**
     * 升级成功回调，此时设备会主动跟手机断开连接，所以会触发OnConnStateListener回调，返回
     * BleConnectionState.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

恢复出厂设置

/**
 * 恢复出厂设置
 *
 * @param macAddress 设备mac
 */
mBleManager.reset(macAddress, new OnModifyConfigurationListener() {
    @Override
    public void onModifyResult(boolean success) {

    }
});

1
2
3
4
5
6
7
8
9
10
11

关机。

/**
 * 关机
 *
 * @param macAddress 设备mac
 */
mBleManager.powerOff(macAddress, new OnModifyConfigurationListener() {
    @Override
    public void onModifyResult(boolean success) {

    }
});

1
2
3
4
5
6
7
8
9
10
11

# 历史记录

**2024/02/29 添加编辑文档；