MinewKeyfinder iOS开发套件说明

开始之前的配置

SDK使用的Cocoa模块:CoreLocation(用于记录设备断开时的地理位置)/CoreBluetooth(用于实现手机与设备之间的通信交互)。

苹果逐年收紧设备模块的权限,因此需要在项目工程的Plist文件中添加如下配置:

  <!-- 蓝牙 --> 
<key>NSBluetoothPeripheralUsageDescription</key> 
<string>App需要您的同意,才能使用蓝牙模块</string> 
  <!-- 位置 --> 
<key>NSLocationUsageDescription</key> 
<string>App需要您的同意,才能访问位置信息</string> 
<!-- 在使用期间访问位置 --> 
<key>NSLocationWhenInUseUsageDescription</key> 
<string>App需要您的同意,才能在使用期间访问位置信息</string> 
  
 如果需要持续的后台扫描,那么还需要添加如下配置:
<!-- 始终访问位置 --> 
<key>NSLocationAlwaysUsageDescription</key> 
<string>App需要您的同意,才能始终访问位置信息</string> 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

同时按如下步骤打开后台相关权限:

Target -> Your Project -> Capabilities -> Background Modes 打开 Location updates和 Uses Bluetooth LE accessories

以上我们就完成了项目的初始配置工作。

特别提醒:目前iOS10.2版本中存在一个蓝牙状态的Bug,当用户手动关闭蓝牙时,系统总是回调蓝牙处于开启状态,请知悉。

开始使用

设备管理

MinewDeviceManager(以下简称Manager)类是一个单例管理类,用来管理扫描/连接/绑定设备以及设备的状态更新等,当然,如果设备有诸如连接状态改变之类的事件,也可以从此类获取到回调。

1.初始化Manager,配置代理:

MinewDeviceManager *manager = [MinewDeviceManager sharedInstance];
manager.delegate = self;
1
2

2.发起扫描,检索周围的设备:

[manager startScan];	
1

发起扫描后,当Manager检测到周围的设备,会为这些设备依次创建一个MinewDevice实例,同时通过以下三个代理方法回调。

// 只要Manager发现周围的设备此方法即进行回调,devices参数包括所有被扫描过的设备
- (void)manager:(MinewDeviceManager *)manager didScanDevices:(NSArray <MinewDevice *>*)devices;

// 此方法仅当设备消失时才进行回调(PS:我们规定,如果被扫描的设备10秒内没有再次被扫描到,那就是消失了。)
- (void)manager:(MinewDeviceManager *)manager disappearDevices:(NSArray<MinewDevice *> *)devices;

// 此方法仅当新出现设备时才进行回调(PS:我们规定,如果设备第一次被扫描到或者之前消失过再次被扫描到都将当作新出现设备。)
- (void)manager:(MinewDeviceManager *)manager appearDevices:(NSArray <MinewDevice *> *)devices;
1
2
3
4
5
6
7
8

当然,开发者也可以使用如下方式主动获取当前扫描到的所有设备:

NSArray *devices = manager.scannedDevices;
1

3.绑定设备:

只有设备被绑定后,我们才对设备的状态进行持续更新,特别是设备与手机之间的连接状态更新。

[manager bind:aDevice];
1

同时,开发者还可以用以下方式获取到之前绑定过的所有设备:

NSArray *bindDevices = manager.bindDevices;
1

4.连接到设备:

我们提供了主动连接的API,同时通过代理方法监听设备的连接状态改变:

[manager connect:aDevice];
1

如果设备发生连接状态的改变,将通过以下代理方法回调给开发者:

// 当设备的连接状态发生改变,此方法将会回调
- (void)manager:(MinewDeviceManager *)manager didDevice:(MinewDevice *)device updateLinkState:(DeviceLinkState)state;
1
2

针对已经绑定的设备,我们提供了持续更新设备数据的回调

// 当绑定的设备发生数据改变时,此方法将会回调。
- (void)manager:(MinewDeviceManager *)manager didUpdateBindDevice:(NSArray <MinewDevice *>*)devices;
1
2

工作开关

2.1.1版本加入的控制开关,由于iOS10收紧了电源策略,我们调整了重连以及后台唤醒逻辑,这部分操作将唤醒应用(无论应用是否运行过),所以提供了一个手动开关来控制是否进行自动重连等操作。

@property (nonatomic, assign) BOOL disableAutoProcessing;
1

此属性默认为NO,如果需要停止自动工作,需要设置为YES,只要对此属性进行Set操作,相关工作状态将会立即生效。另外值得注意的是,在取值为YES的状态下,是不能进行绑定设备操作的(Demo中有示例)。

警告:如果您不清晰此属性所带来的影响,请不要随意修改。

更多详情请见Demo。

单个设备

对于单个设备,我们为每个设备生成一个MinewDevice(以下简称Device)实例,每个实例包含了设备的信息,以及对设备的操作方法和相关回调。

关于设备信息,目前采用键值对的方式获取。比如获取Device的mac地址:

// 获取MAC地址的value
MinewValue *value = [aDevice getValue:ValueIndex_MacAddress];

// 获取MAC地址
NSString *macString = value.stringValue;
1
2
3
4
5

你可能注意到了,这里的 -(MinewDeviceValue *)getValue:(ValueIndex)index方法返回的是一个MinewValue(以下简称value)类实例,value实例是对多种数据类型的进一步封装,比如bool/integer/string/float等。关于Device信息的对照,后文有更详细的说明。

对于Device实例某项数据进行修改参见如下代码:

// 生成一个MinewValue实例
MinewValue *value = [MinewValue index:ValueIndex_Name value:@"Awesome"];
// 配置设备名称
[aDevice setValue:value];
1
2
3
4

如果要修改的数据是布尔型/整型/浮点型,请按照如下示例进行:

// 配置设备断开报警的延迟时间
MinewValue *delayValue = [MinewValue index:ValueIndex_AlarmDelay value:@(5.f)];
[aDevice setValue:delayValue];

// 配置设备断开是否报警
MinewValue *loseAlertValue = [MinewValue index:ValueIndex_DeviceLoseAlert value:@(YES)] ;
[aDevice setValue:loseAlertValue];
1
2
3
4
5
6
7

我们提供了一些指令,用来控制设备上的一些特性,比如,查找设备,指令发送成功后设备将会响铃

[aDevice sendInstruction:InstrucIndex_Search];
1

当指令发送完成后,同样能从回调中获取指令是否成功发送的回调

// index参数是对应的指令枚举,device是某个设备对应的实例,success是布尔值,标注是否成功。
- (void)didSendInstruction:(InstrucIndex)index toDevice:(MinewDevice *)device result:(BOOL)success;
1
2

当然,还有一些事件不是主动触发的,比如设备向手机发送了一个指令,我们可以使用以下方式监听来自设备端的指令:

// index参数是设备发来的指令枚举
- (void)didReceiveInstruction:(InstrucIndex)index fromDevice:(MinewDevice *)device;
1
2

OK,至此你已经可以着手开发了,我们提供了一份Demo代码,你可以对MinewDeviceManager和MinewDevice进行二次封装,用来保证准确接受到每一次的事件回调,当然,这样的示例在Demo里也是有的。

##关于MinewDeviceValue的附加说明 通过设备的属性可以获取到对应类型的值,比如

 设备名称: NSString *name = aDeviceValue.stringValue
 电池电量:NSInteger battery = aDeviceValue.intValue;
 是否绑定:BOOL bind = aDeviceValue.boolValue;

DeviceValue实例共有如下几种属性,可以获取到对应类型的数据,

// 数据对应的枚举
@property (nonatomic, readonly, assign) ValueIndex index;

// 获取整形数据
@property (nonatomic, readonly, assign) NSInteger intValue;

// 获取浮点型数据
@property (nonatomic, readonly, assign) float floatValue;

// 获取字符串型数据
@property (nonatomic, readonly, copy) NSString *stringValue;

// 获取16进制data型数据
@property (nonatomic, readonly, strong) NSData  *dataValue;

// 获取bool类型数据
@property (nonatomic, readonly, assign) BOOL boolValue;

如果需要修改设备的某项信息,可以自行生成一个Value实例

 // 生成一个MinewDeviceValue实例
+ (MinewDeviceValue *)index:(ValueIndex)index value:(id)value;

 比如创建名字实例
 MinewDeviceValue *nameValue = [MinewDeviceValue index:ValueIndex_Name value:@"手机"];
 
 创建设备模式实例 
 MinewDeviceValue *modeValue = [MinewDeviceValue index:ValueIndex_Mode value:@2];
  
 PS:由于基础数据类型在Objective C中不可以以范型方式传递,所以整型、浮点型、布尔型在赋值时必须转换成NSNumber类型,例如:@(10),@(12.3),@(YES)
 
 另外需要注意的是,所有的数据在获取以及生成时,必须严格按照以下对应关系进行。另外并非全部信息都可以被修改,请看下表:
设备属性 说明 数据类型 读写权限 备注
ValueIndex_Name 自定义的设备名 stringValue 可读写
ValueIndex_HeadImage 设备头像 dataValue 可读写
ValueIndex_DeviceId 从设备读取到的名称 stringValue 只读 蓝牙返回的设备名
ValueIndex_MacAddress Mac地址 stringValue 只读
ValueIndex_Rssi 信号强度 intValue 只读
ValueIndex_Mode 设备模式 intValue 可读写
ValueIndex_Distance 设备距离 floatValue 只读
ValueIndex_Battery 电池电量 intValue 只读
ValueIndex_Bind 绑定状态 boolValue 只读
ValueIndex_DisappearTime 断开时间 stringValue 只读 格式:yyyy-MM-dd hh:mm:ss
ValueIndex_DisappearLong 断开经度 floatValue 只读
ValueIndex_DisappearLati 断开纬度 floatValue 只读
ValueIndex_Connected 连接状态 boolValue 只读
ValueIndex_DeviceLoseAlert 断开报警 boolValue 可读写 标记设备断开时是否响铃
ValueIndex_Search 查找状态 boolValue 可读写 用于UI更新,设备是否被查找
ValueIndex_AppLoseAlert 断开通知 boolValue 可读写 用于标记设备断开时手机端是否需要反馈
ValueIndex_FeatureSupport 设备是否支持参数调整 boolValue 只读 如果设备支持距离调节或者延迟报警调节,这里的值为YES
ValueIndex_AlarmDistance 调节设备的报警距离 intValue 可读写 一共有1-8,8个档位,距离由近到远(仅针对支持的设备)
ValueIndex_AlarmDelay 调节设备断开时的报警延迟 intValue 可读写 0-8秒可调范围

ChangeLog

2017.4.24   ver 2.1.2 更新部分文本描述;
2017.4.19   ver 2.1.1 添加工作开关。;
2017.1.3    ver 2.0 添加权限说明以及新特性说明;
2016.9.12   Ver 1.0

上次更新:: 2018/9/5 下午4:58:02