MinewKeyfinder Software Development Kit Guide for iOS

Prepare

Cocoa Frameworks this SDK using: CoreLocation(record the location information when device disconnected)/CoreBluetooth(using for communication between iPhone and devices)。

you need to add the code to info.plist of your project:

  <!-- Bluetooth --> 
<key>NSBluetoothPeripheralUsageDescription</key> 
<string>App need bluetooth.</string> 
  <!-- location --> 
<key>NSLocationUsageDescription</key> 
<string>App need location information.</string> 
<!-- get location while using --> 
<key>NSLocationWhenInUseUsageDescription</key> 
<string>App need location information.</string> 
  
<!-- always get location. --> 
<key>NSLocationAlwaysUsageDescription</key> 
<string>App need location information.</string> 
1
2
3
4
5
6
7
8
9
10
11
12
13

open the background permission as follows:

Target -> Your Project -> Capabilities -> Background Modes, check "Location updates" and "Uses Bluetooth LE accessories"

Get Started

Device manager

MinewDeviceManager(as Manager)is a shared instance Manager Class, it can scan / connect to / bind devices, at the same time, it also listen the changes of device connection.

  1. init Manager, set a delegate:

    MinewDeviceManager *manager = [MinewDeviceManager sharedInstance];
    manager.delegate = self;
    
    1
    2
  2. start scan, find devices around:

    [manager startScan];
    
    1

the manager will create instances for every device when it scanned devices around, there are 3 delegate methods call back for events and status.

// when the manager find devices, this method will be executed.
- (void)manager:(MinewDeviceManager *)manager didScanDevices:(NSArray <MinewDevice *>*)devices;

// when device disappear this method will be executed.(PS: if a device doesn't been scanned for 10 seconds, we think it "disappeared".)
- (void)manager:(MinewDeviceManager *)manager disappearDevices:(NSArray<MinewDevice *> *)devices;

// when device appear this method will be executed.(PS: only for the first scanned devices.)
- (void)manager:(MinewDeviceManager *)manager appearDevices:(NSArray <MinewDevice *> *)devices;
1
2
3
4
5
6
7
8

Certainly, the develop can get devices from the "scannedDevices" property of manager.

NSArray *devices = manager.scannedDevices;
1
  1. bind device:

The manger only update data of bind devices, especially in connection stage.you can bind a device like the code below:

[manager bind:aDevice];
1

At same time, the developer can get all bind devices in this way:

NSArray *bindDevices = manager.bindDevices;
1
  1. connect to a device:

Connect to device via manager, you can listen the status or event changes of device from delegate method.

// connect to device
[manager connect:aDevice];
manager.delegate = "you delegate"

// the methond will be executed when device connection state changes.
- (void)manager:(MinewDeviceManager *)manager didDevice:(MinewDevice *)device updateLinkState:(DeviceLinkState)state;
1
2
3
4
5
6

the manager update data of devices by delegate method, it's only for bind devices.

// when data changes of bind devices, this method will be executed.
- (void)manager:(MinewDeviceManager *)manager didUpdateBindDevice:(NSArray <MinewDevice *>*)devices;
1
2

Working switch

from ver2.1.1, the SDK has a switch, you can disable the SDK module for stoping manager's work.

@property (nonatomic, assign) BOOL disableAutoProcessing;
1

the default value of this property is NO, if you need stop the SDK from working, just set it to YES, this will take effect immediately.

the default value of this property is NO, if you want stoping autoProccessing, just set it to YES, it will take effective immediately. It is worth noting that you can't bind devices when disable autoProcessing(there is example code in Demo).

Device

This SDK create MinewDevice instance for every physical device, each instance contains information, operation methods and call backs for device.

Currently, you can get device information by key-value(like dictionary). refer to the code below:

// get value instance of MAC,
MinewValue *value = [aDevice getValue:ValueIndex_MacAddress];

// get MAC address string.
NSString *macString = value.stringValue;
1
2
3
4
5

You may notice that the " -(MinewDeviceValue *)getValue:(ValueIndex)index" method will return a MinewValue (as value below) instance, value isntance is a package of mutilple types, such as int, float, string and etc. more detailed explanation later.

you can refer to the code below about change values of device.

// init a MinewValue instance.
MinewValue *value = [MinewValue index:ValueIndex_Name value:@"Awesome"];
// set device's name
[aDevice setValue:value];
1
2
3
4

if you want to change a bool / int / float type, please refer the code below:

// set the delay alarm property 
MinewValue *delayValue = [MinewValue index:ValueIndex_AlarmDelay value:@(5.f)];
[aDevice setValue:delayValue];

// set alarm or not when disconnected.
MinewValue *loseAlertValue = [MinewValue index:ValueIndex_DeviceLoseAlert value:@(YES)] ;
[aDevice setValue:loseAlertValue];
1
2
3
4
5
6
7

we offer some instructions for control features of device. such as search device(the device will ring when receive the instruction)

[aDevice sendInstruction:InstrucIndex_Search];
1

When instructions sent, you can get the result by call backs.

// this callback tells the instruction is sent successful or not,
- (void)didSendInstruction:(InstrucIndex)index toDevice:(MinewDevice *)device result:(BOOL)success;
1
2

At the same time, some events are passive, such as the device sends a instruction to app, but we don't know when it happens. we can listen these events like this:

// index is a item from "InstrucIndex" list
- (void)didReceiveInstruction:(InstrucIndex)index fromDevice:(MinewDevice *)device;
1
2

OK, Start to develop now, we provided a demo code, you can encapsulate MinewDeviceManager and MinewDevice in order to accept every event callback accurately. More details, please refer to the demo.

##Details about MinewDeviceValue get values like this,

// device name
NSString *name = aDeviceNameValue.stringValue
// device battery
NSInteger battery = aDeviceBatteryValue.intValue;
// bind state
BOOL bind = aDeviceBindValue.boolValue;
1
2
3
4
5
6

DeviceValue contains multiple types, you can refer to the code below.

// index in "ValueIndex" list
@property (nonatomic, readonly, assign) ValueIndex index;

// 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
15
16
17

If you want to change a value, please init a value instance.

 // init a value instance
+ (MinewDeviceValue *)index:(ValueIndex)index value:(id)value;

 // create a name instance
 MinewDeviceValue *nameValue = [MinewDeviceValue index:ValueIndex_Name value:@"手机"];
 
// create a device mode instance
 MinewDeviceValue *modeValue = [MinewDeviceValue index:ValueIndex_Mode value:@2];
  
1
2
3
4
5
6
7
8
9

PS: int / float / bool values should be convert to NSNumber, such as @(10), @(12.3), @(YES)

At the same time, you should to known, not all the properties can be modified, please refer the table below:

Device Properties detail datatype Read/write More
ValueIndex_Name Name stringValue R/W
ValueIndex_HeadImage Head image dataValue R/W
ValueIndex_DeviceId Device id stringValue R Bluetooth name.
ValueIndex_MacAddress MAC address stringValue R
ValueIndex_Rssi RSSI intValue R
ValueIndex_Mode Mode intValue R/W
ValueIndex_Distance Distance floatValue R
ValueIndex_Battery Battery intValue R
ValueIndex_Bind Bind state boolValue R
ValueIndex_DisappearTime Disconnect time stringValue R Format:yyyy-MM-dd hh:mm:ss
ValueIndex_DisappearLong Disconnect longitude floatValue R
ValueIndex_DisappearLati Disconnect latitude floatValue R
ValueIndex_Connected Connection State boolValue R
ValueIndex_DeviceLoseAlert Device Alert boolValue R/W device will alarm or not when disconnect.
ValueIndex_Search Searching boolValue R/W searching this device or not.
ValueIndex_AppLoseAlert App Alert boolValue R/W app will alarm or not when disconnect.
ValueIndex_FeatureSupport feature support boolValue R If the device supports distance adjustment or delayed alarm adjustment, it's YES
ValueIndex_AlarmDistance Alarm distance intValue R/W 1 - 8, 8 levels, from near to far (when featuresupport is YES)
ValueIndex_AlarmDelay Alarm delay. intValue R/W 0 - 8 seconds.(when featuresupport is YES)

ChangeLog

2017.10.16  english version;
2017.4.24   update some text description;
2017.4.19   working switch;
2017.1.3    new feature and permission;
2016.9.12   first version;
1
2
3
4
5

Last Updated:: 9/5/2018, 4:58:02 PM