# 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. 将开发套件的文件：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");
    }
}];

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. 对设备写入开锁指令

   // 从上一步能够获取到扫描到的设备
   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 属性说明

# MTLPeripheral属性说明

# MTLBroadcastHanler属性说明

# MTLConnectionHandler属性说明

# MTLDeviceInfo属性说明