# 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获得 (opens new window)。要安装它，只需将以下行添加到您的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 设备状态（关锁/开锁/故障）
上次更新:: 2024/1/12 14:37:29