MTWristbandKit说明文档
本套SDK仅支持Minew公司出品的蓝牙Wristband设备。通过SDK可以帮助开发者处理手机和Wristband之间的一切工作,包括:扫描设备,连接设备,向设备写入数据,从设备接收数据等。
前期工作
整体框架:MTWristbandCentralManager为设备管理类,在APP运行时始终是单例。MTWristbandPeripheral是设备实例类,此套件会为每一个设备生成一个MTWristbandPeripheral实例以便于对监听设备和操作设备。
MTWristbandCentralManager:设备管理类,可以扫描周围的Wristband设备,并且可以连接它们,校验它们等。
MTWristbandPeripheral:设备实例类,当MTWristbandCentralManager发现一个物理设备时,MTWristbandCentralManager会生成一个MTWristbandPeripheral实例,这个实例就对应一个物理设备。
MTWristbandBroadcast:设备广播类,可以获取设备广播时的数据。
MTWristbandConnection:设备连接类,进行设备的接发数据,监听设备连接状态。
MTCommand:数据处理。
开始上手
开发环境:
- Xcode12+,当前SDK使用Xcode12编译,请使用Xcode12及以上版本进行开发;
- iOS12,限制最低系统版本为iOS12;
导入到工程:
- CocoaPods
- 下载CocoaPods环境;
- 在项目根目录下创建Podfile文件;
- pod search MTWristbandKit;
- 将 pod 'MTWristbandKit' 加入Podfile文件中;
- 最后运行 pod install,等待下载成功即可。
- 手动导入
- 将开发套件的文件:MTWristbandKit.framework文件和.h文件拷贝到项目工程目录下,然后添加到项目中。
PS:
- !!!在iOS10及以上版本,苹果对蓝牙APi添加了权限限制,你需要在工程的info.plist文件里添加一项字符串:Privacy - Bluetooth Peripheral Usage Description - "你的使用描述"。
- !!!在iOS13及以上版本,苹果对蓝牙APi添加了权限限制,你需要在工程的info.plist文件里添加一项字符串:Privacy - Bluetooth Always Usage Description - "你的使用描述"。
- 如采用CocoaPods无法搜索到MTWristbandKit,建议删除缓存
rm ~/Library/Caches/CocoaPods/search_index.json
,再次搜索一次。
开始开发
1.扫描设备
首先需要获取到MTWristbandCentralManager的单例,然后检查手机当前的蓝牙状态,接着就可以进行设备扫描了。
// MTWristbandCentralManager
MTWristbandCentralManager *manager = [MTWristbandCentralManager sharedInstance];
dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
// 手机端当前的蓝牙开关状态
if(self->manager.state == PowerStatePoweredOn) {
// 开始进行设备扫描
[manager startScan:^(NSArray<MTWristbandPeripheral *> *devices) {
self->deviceAry = devices;
}];
}
});
//扫描到的设备也可以使用manager.scannedPeris获得
// 如果你需要对手机的蓝牙状态作出响应。请监听回调。
[manager didChangesBluetoothStatus:^(PowerState status){
switch(status) {
case PowerStatePoweredOn:
NSLog(@"bluetooth status change to poweron");
break;
case PowerStatePoweredOff:
NSLog(@"bluetooth status change to poweroff");
break;
case PowerStateUnknown:
NSLog(@"bluetooth status change to unknown");
}
}];
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
PS: 只有手机蓝牙状态处于Poweron时,整个SDK才能够正常工作。
2.唤醒设备
// 从上一步能够获取到扫描到的设备
MTWristbandPeripheral *device = deviceAry[0];
//唤醒设备,即手机开始广播唤醒数据
[manager startAdvertising:device.broadcast.mac];
//当设备的isConnect为YES时,表示该设备已经被唤醒
if (device.broadcast.isConnect) {
NSLog(@"the device is Awakened");
}
else {
NSLog(@"the device need to wakeUp");
}
//当设备被唤醒后,需要停止手机的广播
[manager stopAdvertising];
2
3
4
5
6
7
8
9
10
11
12
13
3.连接到设备
// 从上一步能够获取到扫描到的设备
MTWristbandPeripheral *device = deviceAry[0];
//连接设备
[manager connectToPeriperal:device];
// 监听设备连接状态。
[device.connector didChangeConnection:^(Connection connection) {
if (connection == Vaildating) {
//验证成功,成功连接设备,验证成功后向设备写入密码
}
if (connection == Disconnected) {
NSLog(@"device has disconnected.");
}
}];
2
3
4
5
6
7
8
9
10
11
12
13
4.写入密码
接上一步,当手机成功与某个设备建立连接验证成功后,就开始写入密码,等待密码验证成功后,就可以进行其他操作。
[MTCommand writePassword:per password:@"minew123" handler:^(bool status) {
if (status) {
NSLog(@"password is right");
//then do what you want to.
}
else{
NSLog(@"password is error");
}
}];
2
3
4
5
6
7
8
9
5.读取历史数据记录
当密码写入成功后,即成功连接设备,可以进行读取历史数据记录等操作。
读取接触历史记录
[MTCommand readWarningHistory:per begin:0 end:per.broadcast.totalNum-1 handler:^(NSArray * _Nonnull valueAry) { }];
1
2
3读取温度历史记录
[MTCommand readTempHistory:per begin:0 end:per.broadcast.tempTotalNum-1 handler:^(NSArray * _Nonnull valueAry) { }];
1
2
3
注意⚠️:
device.broadcast.versionType == 1&&device.broadcast.usage == 2,那么只有OTA功能/关机功能/是否存储设置功能;
device.broadcast.versionType == 1&&device.broadcast.usage == 3,那么在原来的功能上增加恢复出厂设置功能和设置告警距离档位功能;
device.broadcast.versionType == 2&&device.broadcast.usage == 3,那么在原来的功能上增加温度告警历史记录/测温时间间隔设置功能/告警温度设置功能/当前测量温度。
读取设备接触告警历史记录和温度告警历史记录需要注意,begin和end参数均为想要读取的索引-1,例如共有200条数据,想读取第9到第13条总共5条数据,那么begin=8,end=12
6.设置是否储存
[MTCommand setIsStorageData:per isStorage:isStorage handler:^(bool status) {
if (status) {
NSLog(@"setIsStorageData successfully");
}
else {
NSLog(@"setIsStorageData failed");
}
}];
2
3
4
5
6
7
8
7.设置和读取距离档位(0-4)
读取
[MTCommand readAlarmDistance:per handler:^(int value) { if (value != -1) { NSLog(@"read success,the level is %d",value); } else { NSLog(@"read failed"); } }];
1
2
3
4
5
6
7
8设置
[MTCommand setAlarmDistance:per level:level handler:^(bool status) { if (status) { NSLog(@"setAlarmDistance successfully"); } else { NSLog(@"setAlarmDistance failed"); } }];
1
2
3
4
5
6
7
8.设置和读取告警温度(30-42℃)
读取
[MTCommand readAlarmTemperature:per handler:^(int value) { if (value != -1) { NSLog(@"read success,the temperature is %d",value); } else { NSLog(@"read failed"); } }];
1
2
3
4
5
6
7
8设置
[MTCommand setAlarmTemperature:per temp:temp handler:^(bool status) { if (status) { NSLog(@"setAlarmTemperature successfully"); } else { NSLog(@"setAlarmTemperature failed"); } }];
1
2
3
4
5
6
7
9.设置和读取温度测量时间间隔(0-7200s)
读取
[MTCommand readTemperatureInterval:per handler:^(int value) { if (value != -1) { NSLog(@"read success,the temperatureInterval is %d",value); } else { NSLog(@"read failed"); } }];
1
2
3
4
5
6
7
8设置
[MTCommand setReadTemperatureInterval:per interval:interval handler:^(bool status) { if (status) { NSLog(@"setReadTemperatureInterval successfully"); } else { NSLog(@"setReadTemperatureInterval failed"); } }];
1
2
3
4
5
6
7
10.设置和读取距离震动开关
读取
[MTCommand readDeviceDistanceVibration:per handler:^(bool status) { if (status) { NSLog(@"the distanceVibration's switch is true"); } else { NSLog(@"the distanceVibration's switch is false"); } }];
1
2
3
4
5
6
7
8设置
[MTCommand setDeviceDistanceVibration:per isOn:isOn handler:^(bool status) { if (status) { NSLog(@"setDeviceDistanceVibration successfully"); } else { NSLog(@"setDeviceDistanceVibration failed"); } }];
1
2
3
4
5
6
7
11.设置和读取温度震动开关
读取
[MTCommand readDeviceTempVibration:per handler:^(bool status) { if (status) { NSLog(@"the tempVibration's switch is true"); } else { NSLog(@"the tempVibration's switch is false"); } }];
1
2
3
4
5
6
7
8设置
[MTCommand setDeviceTempVibration:per isOn:isOn handler:^(bool status) { if (status) { NSLog(@"setDeviceTempVibration successfully"); } else { NSLog(@"setDeviceTempVibration failed"); } }];
1
2
3
4
5
6
7
8
12.设置和读取温度震动阀值(30-42℃)
读取
[MTCommand readDeviceTempVibrationThreshold:per handler:^(int value) { if (value != -1) { NSLog(@"readDeviceTempVibrationThreshold successfully,the tempVibrationThreshold is %d",value); } else { NSLog(@"readDeviceTempVibrationThreshold failed"); } }];
1
2
3
4
5
6
7设置
[MTCommand setDeviceTempVibrationThreshold:per temp:temp handler:^(bool status) { if (status) { NSLog(@"setDeviceTempVibrationThreshold successfully"); } else { NSLog(@"setDeviceTempVibrationThreshold failed"); } }];
1
2
3
4
5
6
7
以下为高级操作,请清楚了解后再调用接口。
13.关机
[MTCommand setPowerOff:per handler:^(bool status) {
if (status) {
NSLog(@"setPowerOff successfully");
}
else {
NSLog(@"setPowerOff failed");
}
}];
2
3
4
5
6
7
8
14.恢复出厂设置
[MTCommand reset:per handler:^(bool status) {
if (status) {
NSLog(@"reset successfully");
}
else {
NSLog(@"reset failed");
}
}];
2
3
4
5
6
7
8
15.OTA
[MTCommand ota:per fileData:targetData handler:^(bool status, double progress) {
if (status) {
if (progress == 1) {
NSLog(@"ota successfully");
}
else {
NSLog(@"ota loading,progress:%f",progress);
}
}
else {
NSLog(@"ota failed");
}
}];
2
3
4
5
6
7
8
9
10
11
12
13
注意⚠️:OTA固件升级的时候一定要保持手机和Wristband设备在50cm之内,否则会影响升级的成功
详细使用可见demo:https://github.com/minewdevelop/iOS_Minew_WristbandDemo
附表
MTWristbandCentralManager 属性说明
名称 | 类型 | 备注 |
---|---|---|
state | PowerState | 当前的手机蓝牙状态 |
scannedPeris | NSArray | 扫描到的设备 |
MTWristbandPeripheral属性说明
名称 | 类型 | 备注 |
---|---|---|
identifier | NSString | 设备的Identifier |
broadcast | MTWristbandBroadcast | 广播类实例对象 |
connector | MTWristbandConnection | 连接类实例对象 |
MTWristbandBroadcast属性说明
名称 | 类型 | 备注 |
---|---|---|
name | NSString | 设备的蓝牙名称 |
rssi | NSInteger | 设备的RSSI |
mac | NSString | 设备的Mac地址 |
identifier | NSString | 设备的识别码 |
firmwareVersion | NSString | 设备固件版本号 |
isConnect | Bool | 设备是否唤醒 |
isStorage | Bool | 设备是否存储数据 |
totalNum | int | 设备接触告警历史记录总数量 |
tempTotalNum | int | 设备温度告警历史记录总数量 |
versionType | int | 设备硬件版本 |
usage | int | 设备固件兼容版本 |
MTWristbandConnection属性说明
名称 | 类型 | 备注 |
---|---|---|
macString | NSString | 设备Mac地址 |
connection | Connection | 设备连接状态 |