MinewLockDeviceKit Programming Guide for iOS

This SDK only supports Bluetooth module devices from Minew. The SDK helps developers handle everything between the phone and the Bluetooth module, including: scanning devices, connecting devices, writing data to devices, receiving data from devices, and more.

PreWorks

The overall framework is shown in the following figure: MTLockDeviceManager is a device management class, which is always a singleton when the APP is running. MTLockDevice is a device instance class that generates an instance of MTLockDevice for each device to facilitate listening to and operating the device.

设计说明

MTLockDeviceManager:A device management class that scans surrounding Lock devices and can connect them, verify them, and more.

MTLockDevice:In the device instance class, when the Manager discovers a physical device, the Manager generates a Module instance, which corresponds to a physical device.

Start Developing

Environment:

  • Xcode10+,The current SDK is compiled with Xcode10. Please use Xcode10 and above for development.;
  • iOS10,Limit the minimum system version to iOS10;

Import to project:

CocoaPods

MTLockDeviceKit is available through CocoaPods. To install it, simply add the following line to your Podfile, and then import <MTLockDeviceKit/MTLockDeviceKit.h>:

pod 'MTLockDeviceKit'
1

Manually

  1. Copy the development kit's framework file: MTLockDeviceKit.framework to the project project directory, then add it to the project, the target is the current project, then click "Add", as shown below:

    添加framework

  2. Please Click: "Target" -> General -> Embedded Binaries, click on the "+" below, and continue to click "Add Other" to add the MTTrackit.framework file. Similarly, you need to add to "Linked Frameworks and Libraries":

    frameworkadded

  3. If you are using Swift development, you need to add an Objective C BridgingHeader .h file (not mentioned here), and add: import in this file, if you use Objective C for development, add at the top of the required files:import

  4. !!!On iOS 10 and above, Apple added a permission restriction on Bluetooth APi. You need to add a string to the project's info.plist file: Privacy - Bluetooth Peripheral Usage Description - "Your Usage Description". As shown below:

bluetoothdescription

Start Developing

Scan devices

First, you need to get a singleton of MTLockDeviceManager, then check the current Bluetooth status of the phone, and then you can scan the device.

// get the Manager shared instance.
MTLockDeviceManager *manager = [MTLockDeviceManager sharedInstance];

dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
    // the bluetooth status of iPhone
    if(self->manager.status == Poweron) {
        // start scan for devices.
        [manager startScan:^(NSArray<MTLockDevice *> *devices) {
            // it will callback if the SDK found devices.
        	self->deviceAry = devices;
    	}];
    }
});

// if you need to response for the changes of bluetooth status. please listen to the block
[manager didChangesBluetoothStatus:^(BluetoothStatus status){
    
    switch(status) {
        case Poweron:
            NSLog(@"bluetooth status change to poweron");
            break;
        case Poweroff:
            NSLog(@"bluetooth status change to poweroff");
            break;
        case Unknown:
            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

PS: Only when the Bluetooth status of the mobile phone is in Poweron, the entire SDK can work normally.

connect to the device
// get the module from last step.
MTLockDevice *device = deviceAry[0];

// listen to the changes of device connection
// !!!writing data to device needs connected status.
[((MTLockDevice *)deviceAry[0]) didChangeConnection:^(MTLockDevice *device, Connection connection) {
            
    if (connection == Connected) {
        NSLog(@"connected success.");
        NSData *verficationData = [MTLockCommand verification];
        [device writeData:verficationData completion:^(BOOL success, NSError *error) {
            if (success) {
                NSLog(@"verfication success.");
            }
            else {
                NSLog(@"verfication failed.");
            }
        }];
    }
    else if (connection == Connecting) {
        NSLog(@"connecting...");
    }
    else if (connection == Disconnected) {
        NSLog(@"disconnected");
    }
    else {
        NSLog(@"connected failed");
    }
}];

// connect to a module device.
[manager connect:device connectStyle:search];

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
Write data to device

In the next step, when the mobile phone successfully establishes a connection with a device and successfully authenticates, the device can be read and written.

  1. bind device

    //user : H--->host  S--->guest password:4 digits, it's up to you
    NSData *bindData = [MTLockCommand bindingDeviceWithTheUser:@"H" password:@"0000"];
    [device writeData:bindData completion:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"write data successfully.");
        }
        else {
            NSLog(@"write data failed.");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
  2. unbinding device

    NSData *unbindData = [MTLockCommand unbindDeviceWithTheUser:@"H" password:@"0000"];
    [device writeData:unbindData completion:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"unbinding success");
        }
        else {
            NSLog(@"unbinding failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
  3. verfication the password(Used to reconnect)

    NSData *verficationPasswordData = [MTLockCommand verficationDeviceWithTheUser:@"H"  password:@"0000"];
    
    [device writeData:verficationPasswordData completion:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"verfication success.");
        }
        else {
            NSLog(@"verfication failed.");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
  4. unlock

    NSData *unlockData = [MTLockCommand UnlockWithTheUser:@"H" password:@"0000"];
    
    [device writeData:unlockData completion:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"write data successfully.");
        }
        else {
            NSLog(@"write data failed.");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
  5. read lockRecord

    NSData *readLockRecordData = [MTLockCommand readLockRecord:@""];
    [device writeData:readLockRecordData completion:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"write data successfully.");
        }
        else {
            NSLog(@"write data failed.");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
  6. write lockRecord

    NSData *writeLockRecordData = [MTLockCommand writeLockRecordWithTheUser:@"H"];
    [device writeData:writeLockRecordData completion:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"write data successfully.");
        }
        else {
            NSLog(@"write data failed.");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
Receiving data from device.

Since the mobile phone does not know when the device will send data, the way to monitor the data is used here.

[device didReceiveData:^(NSData *data) {
    NSLog(@"Data received:%@",data);
}];
1
2
3
Get device information.

If the firmware has system information, you can get it by the following method:

/*
  property infos is a Dictionary of BLE DIS, it contains all the information of the current connection device.
  
*/
NSDictionary<String *, String *> *disDict = device.infos;

1
2
3
4
5
6

Tables

MTLockDeviceManager's properties
Name Type Description
status BluetoothStatus the iPhone's bluetooth status
scannedModules NSArray the scanned devices.
connectedModules NSArray the connected devices.
MTLockDevice
Name Type Description
name NSString the device name
mac NSString the device mac
battery NSString the device battery
bindStatus NSString the bind status,@“1”unbinding,@“0”bind
lockStatus NSString the lock status,@“1”unlock,@“0”lock
identifier NSString the id of the device *
advertisingData NSData the advertisement data
lastUpdate NSDate last scanned timestamp
connection Connection the connection status
rssi NSInteger the RSSI
uuids NSDictionary the Service UUID
infos NSDictionary Device informations*

*:only some device can get the device's information, nil value means not supported.

Last Updated:: 12/29/2020, 10:50:07 AM