# MinewToolsKit Documentation

​ This set of SDK only supports the Bluetooth SmartLock device produced by Minew. The SDK can help developers handle all the work between mobile phones and SmarkLock, including: scanning devices, connecting devices, writing data to devices, receiving data from devices, etc.

# Preliminary work

​ Overall framework: MTLLCentralManager is a device management class, which is always a singleton when the APP is running. MTLPeripheral is a device instance class. This suite will generate a MTLPeripheral instance for each device to facilitate monitoring and operating devices.

MTLCentralManager : Device management class, which can scan the surrounding SmartLock devices, and can connect them, verify them, etc.

MTLPeripheral : Device instance class. When MTLCentralManager discovers a physical device, MTLCentralManager will generate a MTLPeripheral instance, which corresponds to a physical device.

MTLBroadcastHandler : Device broadcast class, which can get the data when the device broadcasts.

MTLConnectionHandler : Device connection class for receiving and sending data from the device.

MTLUtils : Write data instruction.

# Get started

# Development environment:

-Xcode10 +, the current SDK is compiled with Xcode11, please use Xcode10 and above for development; -iOS11, the minimum system version is iOS11;

# Import into the project:

# CocoaPods

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

pod 'MinewToolsKit'
1
# Manually
  1. Copy the development kit files: MinewToolsKit.framework files to the project project directory, and then add them to the project.

PS:

  1. !!! In iOS10 and above, Apple added permission restrictions on Bluetooth APi. You need to add a string to the project's info.plist file: Privacy-Bluetooth Peripheral Usage Description-"Your usage description".
  2. !!! In iOS13 and above, Apple added permission restrictions on Bluetooth APi. You need to add a string to the project's info.plist file: Privacy-Bluetooth Always Usage Description-"Your usage description".

# Start development

# Scanning equipment

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

// Get Manager singleton
MTLCentralManager *manager = [MTLCentralManager sharedInstance];

dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
    // The current state of the Bluetooth switch on the mobile phone
    if(self->manager.status == PowerStatePoweredOn) {
        // start device scan
        [self->manager startScan:^(NSArray<MTLPeripheral *> *peripherals) {
        //According to the type of broadcast attribute, the required sensor type can be filtered.
          	self->scanPeripherals = peripherals;
    		}];
    }
});
// Scanned devices can also be obtained using manager.scannedPeris
// If you need to respond to the Bluetooth status of your phone. Please listen for the callback.
[manager didChangesBluetoothStatus:^(MTLPowerState statues) {

    switch(statues) {
        case PowerStatePoweredOn:
            NSLog(@"bluetooth status change to poweron");
            break;
        case PowerStatePoweredOff:
            NSLog(@"bluetooth status change to poweroff");
            break;
        case PowerStateUnknown:
            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: The entire SDK works only when the Bluetooth state of the phone is in Poweron.

# Connect to device
// The scanned device can be obtained from the previous step
MTLPeripheral *peripheral = scanPeripherals[0];
// Connect the device
[manager connectToPeriperal:peripheral];
// Listen for device connection status.
[peripheral.connector didChangeConnection:^(MTLConnection connection) {
    if (connection == Vaildated) {
      // Successful verification, successfully connected to the device
        NSLog (@ "vaildated");
      //Need to write a password, perform other operations after the password is verified successfully
    }
    if (connection == Disconnected) {
        NSLog (@ "device has disconnected.");
    }
}];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Unlock

Take the next step, when the mobile phone successfully establishes a connection with a device and the authentication is successful, the device can unlock.

  1. Write unlock command to the device

    // The scanned device can be obtained from the previous step
MTLPeripheral *peripheral = scanPeripherals[0];
// Unlock
[peripheral.connector writeData:UnLockWrited];
    1
    2
    3
    4

  2. The mobile phone receives the device's response to the unlock command

    // The scanned device can be obtained from the previous step
MTLPeripheral *peripheral = scanPeripherals[0];
// Receive Unlock Notify
[peripheral.connector didUnlock:^(BOOL isSuccess, NSError * _Nonnull error) {
    if(isSuccess) {
        NSLog(@"Unlock Success");
    } else {
        NSLog(@"Unlock Failed");
    }
}];
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
# Read Device Information

When the mobile phone successfully establishes a connection with a device and the authentication is successful, the device can read device information.

  1. When the mobile phone successfully establishes a connection with a device and the authentication is successful, the device can read device information.

    // The scanned device can be obtained from the previous step
MTLPeripheral *peripheral = scanPeripherals[0];
// Read Deveice Info
[peripheral.connector writeData:ReadDeviceInfoWrited];
    1
    2
    3
    4

  2. The mobile phone receives the device's reply to the instruction to read the device information

    // The scanned device can be obtained from the previous step
MTLPeripheral *peripheral = scanPeripherals[0];
// Read Device Info Notify
[peripheral.connector didReadDeviceInfo:^(MTLDeviceInfo * _Nonnull deviceInfo, BOOL isSuccess, NSError * _Nonnull error) {
  if(isSuccess) {
      NSLog(@"ReadDeviceInfo Success: deviceType:%ld, firmVersion:%@, deviceState:%ld", deviceInfo.deviceType, deviceInfo.firmwareVersion, deviceInfo.deviceState);
  } else {
      NSLog(@"ReadDeviceInfo Failed");
  }
}];
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
# OTA

When the mobile phone successfully establishes a connection with a device and the authentication is successful, the device can update packet.

  1. OTA

    // The scanned device can be obtained from the previous step
MTLPeripheral *peripheral = scanPeripherals[0];
// Get the upgrade package data
NSData *data = [NSData dataWithContentsOfURL:url];
// OTA
[MTLOTAManager startOTAUpdate:peripheral.connector OTAData:data progressHandler:^(float progress) {
	NSLog(@"ota progress: %f", progress);
} completionHandler:^(BOOL isSuccess, NSError * _Nonnull error) {
  NSLog(@"ota success:%@", isSuccess ? @"Yes" : @"NO");
}];
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

# Notes

  1. In scanning stage, some properties may nil, especially MAC address(restriction of iOS),if current device advertise DeviceInfo frame, then you can get name, MAC address and battery.
  2. If the running display cannot find the path after adding the SDK, remove the package and add it again at General-> Frameworks,Libraries,and Embedded Content

# Change log

  • 2020.10.15 v1.0 first version;

# Schedule

# MTLCentralManager Property Description
Name Type Description
status PowerState phone's bluetooth status
scannedPeris NSArray scanned devices
# MTLPeripheral Property Description
Name Type Description
identifier NSString device Identifier
broadcast MTLBroadcastHandler obejct of MTLBroadcastHandler
connector MTLConnectionHandler obejct of MTLConnectionHandler
# MTLBroadcastHanler Property Description
Name Type Description
name NSString device name
rssi NSInteger device RSSI
battery NSString device battery
mac NSString device Mac
identifier NSString device identifier
firmVersion NSString firm version
hardwareVersion NSString hardware version
smartLockState NSString smart lock state
# MTLConnectionHandler Property Description
Name Type Description
macString NSString device Mac
connection Connection device connect state
# MTLDeviceInfo Property Description
Name Type Description
deviceType MTLDeviceType device type
firmwareVersion NSString firmware version
deviceState MTLDeviceState device state
Last Updated:: 1/12/2024, 6:46:52 PM