# MinewBeaconScan 开发套件说明

# 安装

# CocoaPods

MinewBeaconScan可通过CocoaPods获得 (opens new window)。要安装它，只需将以下行添加到您的Podfile中，然后导入 <MinewBeaconScan/MinewBeaconScan.h>：

pod 'MinewBeaconScan'
1

# 手动添加

下载项目，并将MinewBeaconScan.framework拷贝到项目工程目录下，添加到工程中，然后导入<MinewBeaconScan/MinewBeaconScan.h>。

#import <MinewBeaconScan/MinewBeaconScan.h>
1

# 要求

限制最低系统版本为 iOS 9.0；

# 使用前的配置工作

当前SDK结合Location与Bluetooth两种框架编写。

为了符合苹果的审核规范，需要为是否需求后台支持做一些区分。

针对不需求后台支持的开发者： 1、执行扫描方法时：[aManager startScan:uuids backgroundSupport :NO]; 请按这里将backgroundSupport置为NO。 2、关闭项目工程中的 Location update 和 Uses Bluetooth LE accessories 两项配置设定。 PS：由于iOS系统限制，对于某些不支持在后台被检测的蓝牙设备，一旦应用进入后台，数据回调将会终止，尽管此时应用的进程并未处于挂起状态。

针对需求后台支持的开发者： 1、执行扫描方法时：[aManager startScan:uuids backgroundSupport :YES];请按这里将backgroundSupport置为YES。 2、需要配置项目工程的后台权限： Location update和 Uses Bluetooth LE accessories。同时在项目plist文件中加入“NSLocationAlwaysUsageDescription”项。 PS：当应用进入后台时，SDK将切换至后台模式继续扫描，如果周围有可以在后台模式下被检测到的设备，所有代理方法将会正常回调。

针对iOS10系统：

在iOS10系统中，苹果进一步收紧权限控制，我们的SDK使用了蓝牙和地理位置模块，因此需要在工程项目的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
15

# 开始使用

MinewBeaconManager（以下简称Manager）类用来发起和停止扫描周边的蓝牙设备，它将为每一个蓝牙设备生成一个对应的Minewbeacon（以下简称Beacon）实例。当Manager扫描到蓝牙设备时，它会持续监听蓝牙设备的数据更新以及这些设备的进出状态（十秒内没有数据更新的设备被认为是消失设备，第一次扫描到或者消失后再次扫描到的设备被认为是出现设备），同时，Manager类还可以监听蓝牙状态的改变并且回调给对应的代理实例。以下是相关代码。

1.获取设备实例，配置代理:

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

2.扫描设备

[manager startScan:@[@"uuid1", @"uuid2",...] backgroundSupport:NO];
1

3.通过回调获取设备数据更新

// 获取持续的设备数据更新，此方法每1秒回调一次，当且仅当扫描到设备时才会回调。
- (void)minewBeaconManager:(MinewBeaconManager *)manager didRangeBeacons:(NSArray<MinewBeacon *> *)beacons
{
    NSLog(@"current beacons:%@", beacons);
}
1
2
3
4
5
6

4.获取beacon实例的数据

​ 通过-(MinewBeaconValue *)getBeaconValue:(BeaconValueIndex)index方法来获取设备数据，为了数据通用性，我们使用了MinewBeaconValue类（以下简称value）来统一所有的数据类型，value可以对应字符串、整型、浮点型、布尔型数据。每一个index对应一个值，如下示例：

MinewBeacon *beacon = beacons[0];

// 获取uuid
NSString *uuid = [beacon getBeaconValue:BeaconValueIndex_UUID].stringValue; 
// 获取major
NSInteger major = (long)[beacon getBeaconValue:BeaconValueIndex_Major].intValue;
// 获取minor
NSInteger minor = (long)[beacon getBeaconValue:BeaconValueIndex_Minor].intValue;
1
2
3
4
5
6
7
8

附表：ValueIndex以及对应数据类型

index 数据名 类型 备注
BeaconValueIndex_UUID uuid stringValue
BeaconValueIndex_Name 设备名 stringValue
BeaconValueIndex_Major major intValue
BeaconValueIndex_Minor minor intValue
BeaconValueIndex_WechatId 微信设备id intValue 部分支持
BeaconValueIndex_Mac mac地址 stringValue 部分支持
BeaconValueIndex_RSSI rssi intValue
BeaconValueIndex_BatteryLevel 电池电量 intValue
BeaconValueIndex_Temperature 温度 floatValue 部分支持
BeaconValueIndex_Humidity 湿度 floatValue 部分支持
BeaconValueIndex_Txpower txPower intValue
BeaconValueIndex_InRange 是否在范围内 boolValue
BeaconValueIndex_Connectable 是否可连接 boolValue

你只需要按照对应的index来获取想要的数据就可以了。

至此，就完成了SDK的基础使用，如果需要更多支持可以参照如下示例：

监听设备的进出状态：

// 如果设备8秒内没有数据更新，此设备被认为是已经消失，消失的设备将会在此回调，此方法每5秒一个周期，
- (void)minewBeaconManager:(MinewBeaconManager *)manager disappearBeacons:(NSArray<MinewBeacon *> *)beacons
{
    NSLog(@"---disappear beacons:%@", beacons);
}

// 第一次被扫描到的或者消失后重新被扫描到的设备被认为是新出现设备，新出现的设备将会在此回调，此方法每3秒一个周期。
- (void)minewBeaconManager:(MinewBeaconManager *)manager appearBeacons:(NSArray<MinewBeacon *> *)beacons
{
    NSLog(@"appear beacons:%@", beacons);
}
1
2
3
4
5
6
7
8
9
10
11

监听蓝牙模块状态更新

蓝牙状态一共有三种：

BluetoothState：BluetoothStatePowerOn（蓝牙开启），BluetoothStatePowerOff（蓝牙关闭），BluetoothStateUnknown（蓝牙状态未知）

// 因用户或者系统改变的蓝牙开关，都能在以下方法监听到：
- (void)minewBeaconManager:(MinewBeaconManager *)manager didUpdateState:(BluetoothState)state
{
    NSLog(@"Bluetooth state:%ld", (long)state);
}
1
2
3
4
5

当然，你也可以手动检查蓝牙状态：

BluetoothState state = [aManager checkBluetoothState];

if(state == BluetoothStatePowerOn)
  NSLog(@"Bluetooth is PowerOn now.");
else if ...
1
2
3
4
5

# 类说明

# MinewBeacon

设备类，每一个设备对应一个此类实例，此类仅有一个方法，通过对应的Index来获取设备的信息：

 -(MinewBeaconValue *)getBeaconValue:(BeaconValueIndex)index;

例如获取某个设备实例的UUID：
  [aBeacon getBeaconValue:BeaconValueIndex_UUID].stringValue;

// 这里是设备数据的对应枚举；
 // !!!:必须按照每个设备的数据类型来获取数据。
typedef NS_ENUM(NSInteger, BeaconValueIndex) {
     // UUID      
    BeaconValueIndex_UUID = 1,  // stringValue
    // Major 
    BeaconValueIndex_Major,   // intValue
    // Minor
    BeaconValueIndex_Minor,   // intValue
    // Name
    BeaconValueIndex_Name,   // stringValue
    // RSSI
    BeaconValueIndex_RSSI,   //  intValue
    // 电池电量
    BeaconValueIndex_BatteryLevel,  // intValue
    // 温度，暂时不提供数据
    BeaconValueIndex_Temperature, 
    // 湿度 ，暂时不提供数据
    BeaconValueIndex_Humidity, 
    // TxPower
    BeaconValueIndex_TxPower,  // intValue
    // 设备当前是否在可扫描的范围内
    BeaconValueIndex_InRage,  // boolValue
    // 微信设备Id，（部分设备可获取）
    BeaconValueIndex_WechatId, // intValue
};
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
30
31

# MinewBeaconValue

// 设备数据类：MinewBeaconValue，从设备获取的所有数据均得到此类实例，请严格按照对应数据类型获取数据

// 获取整形数据
@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;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# MinewBeaconManager

设备管理类，用来扫描设备以及更新设备状态等。

// 设备管理类代理
@protocol MinewBeaconManagerDelegate <NSObject>
@optional

// 发现了新的设备，目前以3秒周期，如果没有发现新设备将不会回调
- (void)minewBeaconManager:(MinewBeaconManager * )manager appearBeacons:(NSArray<MinewBeacon *> *)beacons;

// 如果设备在10秒内没有正常的数据更新，则被视为已经离开扫描范围，此方法会回调。
- (void)minewBeaconManager:(MinewBeaconManager * )manager disappearBeacons:(NSArray<MinewBeacon *> *)beacons;

// 每1秒回调一次，当前发现的所有设备，如果周围没有Beacon则不会回调
- (void)minewBeaconManager:(MinewBeaconManager * )manager didRangeBeacons:(NSArray<MinewBeacon *> * )beacons;

@end

// 设备管理类
@interface MinewBeaconManager : NSObject

// 单例
+ (MinewBeaconManager  *)sharedInstance;

// 开始扫描设备，uuids参数是设备的UUID字符串数组，enable参数提供后台支持，如果为NO，则当应用进入后台时停止扫描，反之，应用进入后台将切换至后台模式继续扫描。
- (void)startScan:(NSArray<NSString *> *)uuids backgroundSupport :(BOOL)enable;

// 停止扫描设备
- (void)stopScan;

// 代理指针
@property (nonatomic, strong) id <MinewBeaconManagerDelegate> delegate;

@property (nonatomic, readonly, assign) BluetoothState

// 扫描到的所有设备
@property (nonatomic, readonly, copy) NSArray<MinewBeacon *> *scannedBeacons;

// 当前在范围内的设备
@property (nonatomic, readonly, copy) NSArray<MinewBeacon *> *inRangeBeacons;

@end
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
30
31
32
33
34
35
36
37
38
39

# Change log

  • 2016.12.22 流程梳理更明确，针对iOS10规范适配。

  • 2016.11.29 添加对新固件的Mac地址数据、温湿度传感器数据的支持。

  • 2016.9.18 针对苹果审核规范修正。

  • 2020.09.18 优化扫描v3设备。

上次更新:: 2024/1/12 14:37:29