MinewLockDeviceKit说明文档
本套SDK仅支持Minew公司出品的蓝牙模块设备。通过SDK可以帮助开发者处理手机和蓝牙模块之间的一切工作,包括:扫描设备,连接设备,向设备写入数据,从设备接收数据等。
前期工作
整体框架如下图所示:MTLockDeviceManager为设备管理类,在APP运行时始终是单例。MTLockDevice是设备实例类,此套件会为每一个设备生成一个MTLockDevice实例以便于对监听设备和操作设备。
MTLockDeviceManager:设备管理类,可以扫描周围的Lock设备,并且可以连接它们,校验它们等。
MTLockDevice:设备实例类,当Manager发现一个物理设备时,Manager会生成一个Module实例,这个实例就对应一个物理设备。
开始上手
开发环境:
- Xcode10+,当前SDK使用Xcode10编译,请使用Xcode10及以上版本进行开发;
- iOS10,限制最低系统版本为iOS10;
导入到工程:
CocoaPods
MTLockDeviceKit可通过CocoaPods获得。要安装它,只需将以下行添加到您的Podfile中,然后导入 <MTLockDeviceKit/MTLockDeviceKit.h>:
pod 'MTLockDeviceKit'
手动导入
- 将开发套件的framework文件:MTLockDeviceKit.framework拷贝到项目工程目录下,然后添加到工程中,target为当前的工程,然后点“Add”,如下图所示:
依次找到:“Target” -> General -> Embedded Binaries,点击下面的“+”,继续点击“Add Other”将MTTrackit.framework文件添加进来。同样的,也需要添加到 ”Linked Frameworks and Libraries“,添加完应该如下图:
- 如果使用Swift开发,需要添加一个Objective C BridgingHeader .h文件(此处不再赘述),并且在此文件添加:import ,如果使用Objective C进行开发,在需要的文件的顶端添加:import
- !!!在iOS10及以上版本,苹果对蓝牙APi添加了权限限制,你需要在工程的info.plist文件里添加一项字符串:Privacy - Bluetooth Peripheral Usage Description - "你的使用描述"。如下图所示:
开始开发
扫描设备
首先需要获取到MTLockDeviceManager的单例,然后检查手机当前的蓝牙状态,接着就可以进行设备扫描了。
// 获取Manager单例
MTLockDeviceManager *manager = [MTLockDeviceManager sharedInstance];
dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
// 手机端当前的蓝牙开关状态
if(self->manager.status == Poweron) {
// 开始进行设备扫描
[manager startScan:^(NSArray<MTLockDevice *> *devices) {
self->deviceAry = devices;
}];
}
});
// 如果你需要对手机的蓝牙状态作出响应。请监听回调。
[manager didChangesBluetoothStatus:^(BluetoothStatus status){
switch(status) {
case Poweron:
NSLog(@"bluetooth status change to poweron");
break;
case Poweroff:
NSLog(@"bluetooth status change to poweroff");
break;
case Unknown:
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
PS: 只有手机蓝牙状态处于Poweron时,整个SDK才能够正常工作。
连接到设备
// 从上一步能够获取到扫描到的设备
MTLockDevice *device = deviceAry[0];
// 监听设备连接状态。
// !!!只有在连接状态为Connected的时候,这个设备才是可以写入数据的
[((MTLockDevice *)deviceAry[0]) didChangeConnection:^(MTLockDevice *device, Connection connection) {
if (connection == Connected) {
NSLog(@"连接成功.");
NSData *verficationData = [MTLockCommand verification];
[device writeData:verficationData completion:^(BOOL success, NSError *error) {
if (success) {
NSLog(@"验证成功");
}
else {
NSLog(@"验证失败");
}
}];
}
else if (connection == Connecting) {
NSLog(@"连接中...");
}
else if (connection == Disconnected) {
NSLog(@"断开连接");
}
else {
NSLog(@"连接失败");
}
}];
// 连接到一个模块设备
[manager connect:device connectStyle:search];
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
向设备写入数据
接上一步,当手机成功与某个设备建立连接验证成功后,就可以对设备进行读写操作了。
绑定设备
//user : H--->host S--->guest password:四位数字,随用户喜好设置 NSData *bindData = [MTLockCommand bindingDeviceWithTheUser:@"H" password:@"0000"]; [device writeData:bindData completion:^(BOOL success, NSError *error) { if (success) { NSLog(@"绑定成功"); } else { NSLog(@"绑定失败"); } }];
1
2
3
4
5
6
7
8
9
10解绑设备
NSData *unbindData = [MTLockCommand unbindDeviceWithTheUser:@"H" password:@"0000"]; [device writeData:unbindData completion:^(BOOL success, NSError *error) { if (success) { NSLog(@"解绑成功"); } else { NSLog(@"解绑失败"); } }];
1
2
3
4
5
6
7
8
9验证设备密码(用于用户重新连接时绑定密码验证)
NSData *verficationPasswordData = [MTLockCommand verficationDeviceWithTheUser:@"H" password:@"0000"]; [device writeData:verficationPasswordData completion:^(BOOL success, NSError *error) { if (success) { NSLog(@"验证成功"); } else { NSLog(@"验证失败"); } }];
1
2
3
4
5
6
7
8
9
10开锁
NSData *unlockData = [MTLockCommand UnlockWithTheUser:@"H" password:@"0000"]; [device writeData:unlockData completion:^(BOOL success, NSError *error) { if (success) { NSLog(@"写入开锁成功"); } else { NSLog(@"写入开锁失败"); } }];
1
2
3
4
5
6
7
8
9
10读取开锁记录
NSData *readLockRecordData = [MTLockCommand readLockRecord:@""]; [device writeData:readLockRecordData completion:^(BOOL success, NSError *error) { if (success) { NSLog(@"写入读取记录成功"); } else { NSLog(@"写入读取记录失败"); } }];
1
2
3
4
5
6
7
8
9写入开锁记录
NSData *writeLockRecordData = [MTLockCommand writeLockRecordWithTheUser:@"H"]; [device writeData:writeLockRecordData completion:^(BOOL success, NSError *error) { if (success) { NSLog(@"写入开锁记录成功"); } else { NSLog(@"写入开锁记录失败"); } }];
1
2
3
4
5
6
7
8
9
从设备接收数据
由于手机并不知道什么时候设备会发送数据过来,所以在这里使用监听block的方式来实现数据接收。
[device didReceiveData:^(NSData *data) {
NSLog(@"从设备端接收到的数据:%@",data);
}];
2
3
从设备读取系统信息
如果固件带有系统信息,可进行获取,方法如下
/*
infos属性为设备的BLE DIS字典,包含当前设备的所有基本信息
*/
NSDictionary<String *, String *> *disDict = device.infos;
2
3
4
5
6
附表
MTLockDeviceManager 属性说明
名称 | 类型 | 备注 |
---|---|---|
status | BluetoothStatus | 当前的手机蓝牙状态 |
scannedModules | NSArray | 扫描到的设备 |
connectedModules | NSArray | 当前连接中的设备 |
MTLockDevice
名称 | 类型 | 备注 |
---|---|---|
name | NSString | 设备的蓝牙名称 |
mac | NSString | 设备的Mac地址 |
battery | NSString | 设备的电池电量 |
bindStatus | NSString | 设备的绑定状态,@“1”已绑定,@“0”未绑定 |
lockStatus | NSString | 设备锁的状态,@“1”锁开了,@“0”锁未开 |
identifier | NSString | 设备的识别码 |
advertisingData | NSData | 设备的广播数据 |
lastUpdate | NSDate | 设备最后一次被扫描到的时间戳 |
connection | Connection | 设备的连接状态 |
rssi | NSInteger | 设备的RSSI |
uuids | NSDictionary | 设备的读写服务UUID |
infos | NSDictionary | 设备信息* |
*:仅部分设备支持获取设备信息,为空即为不支持。