# MinewBeacon Scan Software Development Kit Guide

# Installation

# CocoaPods

MinewBeaconScan is available through CocoaPods (opens new window). To install it, simply add the following line to your Podfile, and then import <MinewBeaconScan/MinewBeaconScan>:

pod "MinewBeaconScan"
1

# Manually

  1. Download the project and drop MinewBeaconScan.framework folder into your project.
  2. Import file <MinewBeaconScan/MinewBeaconScan.h>.
#import <MinewBeaconScan/MinewBeaconScan.h>
1

# Requirements

This library requires iOS 9.0+.

# Configs before development

The SDK used CoreLocation and CoreBluetooth.

In order to comply with Apple's audit specifications, we need to some distinction for using background task or not.

for the developer not require background task:

  // 1. set backgroundSupport to NO 
    [aManager startScan:uuids backgroundSupport: NO];

 // 2. disable Location update and Uses Bluetooth LE accessories in your project. 

 //  PS: Because of the iOS restrictions, if some device don't support background scanning, you will not get these data for the device when the App enter background, although the application process is not in a suspended state.
1
2
3
4
5
6

for the developer require background task：

  // 1. set backgroundSupport to YES
  [aManager startScan:uuids backgroundSupport :YES];
   
  // 2、enable Location update and Uses Bluetooth LE accessories.at the same time, you need add "NSLocationAlwaysUsageDescription" item to your project's info.plist file. 

  // PS：SDK will change to background mode and continue to scan,if there are devices support background mode, all delegate methods will be execute normally.
1
2
3
4
5
6

Configs for "info.plist"

  <!-- Bluetooth --> 
<key>NSBluetoothPeripheralUsageDescription</key> 
<string>App will use bluetooth to communication with devices.</string> 
  <!-- Location --> 
<key>NSLocationUsageDescription</key> 
<string>App will record your location</string> 
<!-- use location while app in use --> 
<key>NSLocationWhenInUseUsageDescription</key> 
<string>App will record your location</string> 
  
<!-- if you need background scanning, you should add configs below -->
<!-- always use location--> 
<key>NSLocationAlwaysUsageDescription</key> 
<string>App will record your location</string>
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Get Started

MinewBeaconManager (as Manager below) can scan or stop scan devices around, it will create Minewbeacon(as Beacon below) instance for every device. it will listen the data update and appear(we think a device disappeared if it doesn't update data in seconds, we think a device appeared if it is scanned at first time or scanned from "disappear" ) state of devices, at the same time, Manager will listen the changes of cellphone's Bluetooth state. Here is the code below:

  1. Get Manager shared instance, set delegate:
MinewBeaconManager *manager = [MinewBeaconManager sharedInstance];
manager.delegate = self;
1
2
  1. Start scan for devices.
[manager startScan:@[@"uuid1", @"uuid2",...] backgroundSupport:NO];
1
  1. get data of devices from delegate method.
// if the manager found devices, this method will be executed every second, 
- (void)minewBeaconManager:(MinewBeaconManager *)manager didRangeBeacons:(NSArray<MinewBeacon *> *)beacons
{
    NSLog(@"current beacons:%@", beacons);
}
1
2
3
4
5

  1. get data of beacon instance.

    Via method "-(MinewBeaconValue *)getBeaconValue:(BeaconValueIndex)index". for data versatility, we use MinewBeaconValue to handle all types of data, BeaconValue instance can be a string, int, float or bool, every "index" correspond to a value, as the code below:

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

Table for ValueIndex and data types

index Data name Type Detail
BeaconValueIndex_UUID uuid stringValue
BeaconValueIndex_Name Name stringValue
BeaconValueIndex_Major major intValue
BeaconValueIndex_Minor minor intValue
BeaconValueIndex_WechatId wechatId intValue Partial device
BeaconValueIndex_Mac MAC address stringValue Partial device
BeaconValueIndex_RSSI rssi intValue
BeaconValueIndex_BatteryLevel Battery intValue
BeaconValueIndex_Temperature Temperature floatValue Partial device
BeaconValueIndex_Humidity Humidity floatValue
BeaconValueIndex_Txpower txPower intValue
BeaconValueIndex_InRange in range boolValue
BeaconValueIndex_Connectable Connectable boolValue

you just need get the data you want via indexs above.

Now, we finish the basic use of SDK, more codes below:

listen to the device appear and disappear changes.

// disappear devices.
- (void)minewBeaconManager:(MinewBeaconManager *)manager disappearBeacons:(NSArray<MinewBeacon *> *)beacons
{
    NSLog(@"---disappear beacons:%@", beacons);
}

// appear devices.
- (void)minewBeaconManager:(MinewBeaconManager *)manager appearBeacons:(NSArray<MinewBeacon *> *)beacons
{
    NSLog(@"appear beacons:%@", beacons);
}
1
2
3
4
5
6
7
8
9
10
11

Listen to the Bluetooth state of cellphone.

Three Bluetooth state:

BluetoothState：BluetoothStatePowerOn（poweron），BluetoothStatePowerOff（power off），BluetoothStateUnknown（unknown）

// listen to the changes of bluetooth state
- (void)minewBeaconManager:(MinewBeaconManager *)manager didUpdateState:(BluetoothState)state
{
    NSLog(@"Bluetooth state:%ld", (long)state);
}
1
2
3
4
5

you can also check bluetooth state like this:

BluetoothState state = [aManager checkBluetoothState];

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

# Class reference

# MinewBeacon

Device instance Class,

// get data of device
 -(MinewBeaconValue *)getBeaconValue:(BeaconValueIndex)index;

// such as get UUID：
  [aBeacon getBeaconValue:BeaconValueIndex_UUID].stringValue;

// index from "BeaconValueIndex"；
 // !!!:you should get data by its type
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
    // battery
    BeaconValueIndex_BatteryLevel,  // intValue
    // temperature
    BeaconValueIndex_Temperature, 
    // humidity
    BeaconValueIndex_Humidity, 
    // TxPower
    BeaconValueIndex_TxPower,  // intValue
    // in scanning range or not
    BeaconValueIndex_InRage,  // boolValue
    // wechatId，（Partial device）
    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
32

# MinewBeaconValue

Device value instance class

// get int value
@property (nonatomic, readonly, assign) NSInteger intValue;

// get float value
@property (nonatomic, readonly, assign) float floatValue;

// get string value
@property (nonatomic, readonly, copy) NSString *stringValue;

// get data value
@property (nonatomic, readonly, strong) NSData  *dataValue;

// get bool value
@property (nonatomic, readonly, assign) BOOL boolValue;
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# MinewBeaconManager

Global Manager class.

// delegate
@protocol MinewBeaconManagerDelegate <NSObject>
@optional

// scanned new devices, callback every 3 seconds, 
- (void)minewBeaconManager:(MinewBeaconManager * )manager appearBeacons:(NSArray<MinewBeacon *> *)beacons;

// listen the disappear devices (doesn't update data in 10 second.)
- (void)minewBeaconManager:(MinewBeaconManager * )manager disappearBeacons:(NSArray<MinewBeacon *> *)beacons;

// listen the appear devices (scanned first time.)
- (void)minewBeaconManager:(MinewBeaconManager * )manager didRangeBeacons:(NSArray<MinewBeacon *> * )beacons;

@end

// 
@interface MinewBeaconManager : NSObject

// sharedinstance
- (MinewBeaconManager  *)sharedInstance;

// start scan devices, "uuids" is a uuid string array, "enable" is a switch for background scanning support 
- (void)startScan:(NSArray<NSString *> *)uuids backgroundSupport :(BOOL)enable;

// stop scan for device.
- (void)stopScan;

// delegate
@property (nonatomic, strong) id <MinewBeaconManagerDelegate> delegate;

@property (nonatomic, readonly, assign) BluetoothState

// all devices scanned.
@property (nonatomic, readonly, copy) NSArray<MinewBeacon *> *scannedBeacons;

// all devices in range.
@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
40

#Change log

  • 2017.10.16 English version
  • 2016.12.22 update for iOS 10
  • 2016.11.29 update for new firmware.
  • 2016.9.18 update for Apple's review
  • 2020.09.18 update for scan v3 device。
Last Updated:: 1/12/2024, 2:37:29 PM