MinewTools说明文档

本套SDK仅支持Minew公司出品的智能车设备。通过SDK可以帮助开发者处理手机和智能锁之间的一切工作,包括:扫描设备,连接设备,向设备写入数据,从设备接收数据等。

前期工作

整体框架:MTLCentralManager为设备管理类,在APP运行时始终是单例。MTLPeripheral是设备实例类,此套件会为每一个设备生成一个MTLPeripheral实例以便于对监听设备和操作设备。

MTLCentralManager:设备管理类,可以扫描周围的智能锁设备,并且可以连接它们,校验它们等。

MTLPeripheral:设备实例类,当MTLCentralManager发现一个物理设备时,MTLCentralManager会生成一个MTLPeripheral实例,这个实例就对应一个物理设备。

MTLBroadcastHandler:设备广播类,可以获取设备广播时的数据。

MTLConnectionHandler:设备连接类,进行设备的接发数据。

MTLOTAManager:空中升级,此类只能用来更新设备固件,它操作的是MTLConnectionHandler实例。

开始上手

开发环境:

  • Xcode10+,当前SDK使用Xcode11编译,请使用Xcode10及以上版本进行开发;
  • iOS11,限制最低系统版本为iOS11;

导入到工程:

CocoaPods

MinewToolsKit可通过CocoaPods获得。要安装它,只需将以下行添加到您的Podfile中,然后导入 <MinewToolsKit/MinewToolsKit.h>:

pod 'MinewToolsKit'
1
手动导入
  1. 将开发套件的文件:MinewToolsKit.framework文件拷贝到项目工程目录下,然后添加到项目中。

PS:

  1. !!!在iOS10及以上版本,苹果对蓝牙APi添加了权限限制,你需要在工程的info.plist文件里添加一项字符串:Privacy - Bluetooth Peripheral Usage Description - "你的使用描述"。
  2. !!!在iOS13及以上版本,苹果对蓝牙APi添加了权限限制,你需要在工程的info.plist文件里添加一项字符串:Privacy - Bluetooth Always Usage Description - "你的使用描述"。

开始开发

扫描设备

首先需要获取到MTCentralManager的单例,然后检查手机当前的蓝牙状态,接着就可以进行设备扫描了。

// 获取Manager单例
MTLCentralManager *manager = [MTLCentralManager sharedInstance];

dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
    // 手机端当前的蓝牙开关状态
    if(self->manager.status == PowerStatePoweredOn) {
        // 开始进行设备扫描
        [self->manager startScan:^(NSArray<MTLPeripheral *> *peripherals) {
          	//可根据broadcast属性的type筛选所需要的传感器种类
          	self->scanPeripherals = peripherals;
        }];
    }
});
//扫描到的设备也可以使用manager.scannedPeris获得

// 如果你需要对手机的蓝牙状态作出响应。请监听回调。
[manager didChangesBluetoothStatus:^(MTLPowerState statues) {

    switch(statues) {
        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");
    }
}];
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

PS: 只有手机蓝牙状态处于Poweron时,整个SDK才能够正常工作。

连接到设备
// 从上一步能够获取到扫描到的设备
MTLPeripheral *peripheral = scanPeripherals[0];
//连接设备
[manager connectToPeriperal:peripheral];
// 监听设备连接状态。
[peripheral.connector didChangeConnection:^(MTLConnection connection) {

    if (connection == Vaildated) {
          //验证成功,成功连接设备
        NSLog(@"vaildated");
          //验证成功后进行其他的操作
    }
    if (connection == Disconnected) {
        NSLog(@"device has disconnected.");
    }
}];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
开锁

接上一步,当手机成功与某个设备建立连接验证成功后,就可以对设备进行开锁操作了。

  1. 对设备写入开锁指令

    // 从上一步能够获取到扫描到的设备
    MTLPeripheral *peripheral = scanPeripherals[0];
    // Unlock
    [peripheral.connector writeData:UnLockWrited];
    
    1
    2
    3
    4
  2. 手机端接收到设备对开锁指令的回复

    // 从上一步能够获取到扫描到的设备
    MTLPeripheral *peripheral = scanPeripherals[0];
    // Receive Unlock Notify
    [peripheral.connector didUnlock:^(BOOL isSuccess, NSError * _Nonnull error) {
        if(isSuccess) {
            NSLog(@"Unlock Success");
        } else {
            NSLog(@"Unlock Failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
读取设备信息

当手机成功与某个设备建立连接验证成功后,就可以对设备进行读取设备信息操作了。

  1. 对设备写入读取设备信息指令

    // 从上一步能够获取到扫描到的设备
    MTLPeripheral *peripheral = scanPeripherals[0];
    // Read Deveice Info
    [peripheral.connector writeData:ReadDeviceInfoWrited];
    
    1
    2
    3
    4
  2. 手机端接收到设备对读取设备信息指令的回复

    // 从上一步能够获取到扫描到的设备
    MTLPeripheral *peripheral = scanPeripherals[0];
    // Read Device Info Notify
    [peripheral.connector didReadDeviceInfo:^(MTLDeviceInfo * _Nonnull deviceInfo, BOOL isSuccess, NSError * _Nonnull error) {
      if(isSuccess) {
          NSLog(@"ReadDeviceInfo Success: deviceType:%ld, firmVersion:%@, deviceState:%ld", deviceInfo.deviceType, deviceInfo.firmwareVersion, deviceInfo.deviceState);
      } else {
          NSLog(@"ReadDeviceInfo Failed");
      }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
OTA升级

当手机成功与某个设备建立连接验证成功后,就可以对设备进行 OTA 升级了。

  1. 写入数据

    // 从上一步能够获取到扫描到的设备
    MTLPeripheral *peripheral = scanPeripherals[0];
    // 拿到升级包数据
    NSData *data = [NSData dataWithContentsOfURL:url];
    // OTA
    [MTLOTAManager startOTAUpdate:peripheral.connector OTAData:data progressHandler:^(float progress) {
    	NSLog(@"ota progress: %f", progress);
    } completionHandler:^(BOOL isSuccess, NSError * _Nonnull error) {
      NSLog(@"ota success:%@", isSuccess ? @"Yes" : @"NO");
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

注意事项

  1. 在扫描过程中,有些属性可能是无法获取的,特别是mac地址(iOS平台下的限制),如果当前设备广播了DeviceInfo数据帧,那么name,mac地址,电池都是可以获取到的。
  2. 如果添加SDK之后,运行显示无法找到路径,可以在 General -> Frameworks,Libraries,and Embedded Content ,把包删除再重新添加一次即可。
  3. 由于设备在未断开的情况下,设备不可重新连接,建议在每次操作之后手动断开,需要的时候再重新连接进行下一步操作。

文档版本记录

  • 2020.10.15 v1.0 初版;

附表

MTLCentralManager 属性说明
名称 类型 备注
state PowerState 当前的手机蓝牙状态
scannedPeris NSArray 扫描到的设备
MTLPeripheral属性说明
名称 类型 备注
identifier NSString 设备的Identifier
broadcast MTBroadcastHandler 广播类实例对象
connector MTConnectionHandler 连接类实例对象
MTLBroadcastHanler属性说明
名称 类型 备注
name NSString 设备的蓝牙名称
rssi NSInteger 设备的RSSI
battery NSString 设备的电池电量
mac NSString 设备的Mac地址
identifier NSString 设备的识别码
firmVersion NSString 固件版本
hardwareVersion NSString 硬件版本
smartLockState NSString 智能锁状态
MTLConnectionHandler属性说明
名称 类型 备注
macString NSString 设备Mac地址
connection Connection 设备连接状态
MTLDeviceInfo属性说明
名称 类型 备注
deviceType MTLDeviceType 设备类型(购物车/其他)
firmwareVersion NSString 固件版本
deviceState MTLDeviceState 设备状态(关锁/开锁/故障)
上次更新:: 2021/1/19 下午3:31:48