MTWristbandKit Documentation

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

preliminary work

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

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

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

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

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

MTCommand : Equipment verification and data processing.

Get started

Development environment:

-Xcode12 +, the current SDK is compiled with Xcode12, please use Xcode12 and above for development; -iOS12, the minimum system version is iOS12;

Import into the project:

  1. CocoaPods

    • Install the CocoaPods environment;
    • Create a Podfile file in the project root directory;
    • pod search MTWristbandKit;wristbandKit
    • Add pod'MTWristbandKit' in Podfileimage-20201221140541600
    • Finally, run pod install and wait for the download to succeed.
  2. Manually

    • Copy the development kit files: MTWristbandKit.a and .h 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".
  3. If MTWristbandKit cannot be searched by CocoaPods, it is recommended to delete the cache rm ~/Library/Caches/CocoaPods/search_index.json and search again.

Start development

1.Scanning equipment

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

// Get Manager singleton
MTWristbandCentralManager * manager = [MTWristbandCentralManager 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.state == PowerStatePoweredOn) {
        // start device scan
        [manager startScan: ^ (NSArray <MTWristbandPeripheral *> * devices) {
        self-> deviceAry = devices;
    }];
    }
});
// 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: ^ (PowerState status) {
  switch (status) {
    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

PS: The entire SDK works only when the Bluetooth state of the phone is in Poweron.

2.Wakeup the device

// The scanned device can be obtained from the previous step
MTWristbandPeripheral *device = deviceAry[0];
//Wake up the device, that is, the phone starts to broadcast the wake-up data
[manager startAdvertising:device.broadcast.mac];
//When the device's isConnect is YES, it means that the device has been woken up
if (device.broadcast.isConnect) {
    NSLog(@"the device is Awakened");
}
else {
    NSLog(@"the device need to wakeUp");
}
//When the device is awakened, you need to stop the mobile phone broadcast
[manager stopAdvertising];
1
2
3
4
5
6
7
8
9
10
11
12
13

3.Connect to device

// The scanned device can be obtained from the previous step
MTWristbandPeripheral * device = deviceAry [0];
// Connect the device
[manager connectToPeriperal: device];
// Listen for device connection status.
[device.connector didChangeConnection: ^ (Connection connection) {
    if (connection == Vaildating) {
      // Successful verification, successfully connected to the device
    }
    if (connection == Disconnected) {
        NSLog (@ "device has disconnected.");
    }
}];
1
2
3
4
5
6
7
8
9
10
11
12
13

4.Write password to the device

​ Following the previous step, when the mobile phone successfully establishes a connection with a certain device and the verification is successful, it starts to write the password. After the password verification is successful, other operations can be performed.

[MTCommand writePassword:per password:@"minew123" handler:^(bool status) {
    if (status) {
        NSLog(@"password is right");
				//then do what you want to.
    }
    else{
        NSLog(@"password is error");
    }
}];
1
2
3
4
5
6
7
8
9

5.Read historical data records

​ When the password is successfully written, the device is successfully connected, and operations such as reading historical data records can be performed.

  1. Read contact history

    [MTCommand readWarningHistory:per begin:0 end:per.broadcast.totalNum-1 handler:^(NSArray * _Nonnull valueAry) {
    
    }];
    
    1
    2
    3
  2. Read temperature history

    [MTCommand readTempHistory:per begin:0 end:per.broadcast.tempTotalNum-1 handler:^(NSArray * _Nonnull valueAry) {
    
    }];
    
    1
    2
    3

Note ⚠️:

  • device.broadcast.versionType == 1&&device.broadcast.usage == 2,then only OTA function / shutdown function / whether to store settings function;
  • device.broadcast.versionType == 1&&device.broadcast.usage == 3,then add the function of restoring factory settings and setting the alarm distance gear function to the original function;
  • device.broadcast.versionType == 2&&device.broadcast.usage == 3,Then add temperature alarm history record/temperature measurement interval setting function/alarm temperature setting function/current measured temperature to the original function.

You need to pay attention to reading the device contact alarm history and temperature alarm history. The begin and end parameters are the index -1 that you want to read. For example, there are 200 pieces of data. If you want to read 9 to 13 pieces of data, then begin=8, end=12.

6.Set whether to store data

[MTCommand setIsStorageData:per isStorage:isStorage handler:^(bool status) {
    if (status) {
        NSLog(@"setIsStorageData successfully");
    }
    else {
        NSLog(@"setIsStorageData failed");
    }
}];
1
2
3
4
5
6
7
8

7.Set and read the distance gear (0-4)

  1. Read

    [MTCommand readAlarmDistance:per handler:^(int value) {
        if (value != -1) {
            NSLog(@"read success,the level is %d",value);
        }
        else {
            NSLog(@"read failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
  2. Set

    [MTCommand setAlarmDistance:per level:level handler:^(bool status) {
        if (status) {
            NSLog(@"setAlarmDistance successfully");
        } else {
            NSLog(@"setAlarmDistance failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7

8.Set and read the alarm temperature (30-42℃)

  1. Read

    [MTCommand readAlarmTemperature:per handler:^(int value) {
        if (value != -1) {
            NSLog(@"read success,the temperature is %d",value);
        }
        else {
            NSLog(@"read failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
  2. Set

    [MTCommand setAlarmTemperature:per temp:temp handler:^(bool status) {
        if (status) {
            NSLog(@"setAlarmTemperature successfully");
        } else {
            NSLog(@"setAlarmTemperature failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7

9.Set and read the temperature measurement time interval (0-7200s)

  1. Read

    [MTCommand readTemperatureInterval:per handler:^(int value) {
        if (value != -1) {
            NSLog(@"read success,the temperatureInterval is %d",value);
        }
        else {
            NSLog(@"read failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
  2. Set

    [MTCommand setReadTemperatureInterval:per interval:interval handler:^(bool status) {
        if (status) {
            NSLog(@"setReadTemperatureInterval successfully");
        } else {
            NSLog(@"setReadTemperatureInterval failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7

10.Set and read the distance vibration switch

  1. Read

    [MTCommand readDeviceDistanceVibration:per handler:^(bool status) {
        if (status) {
            NSLog(@"the distanceVibration's switch is true");
        }
        else {
            NSLog(@"the distanceVibration's switch is false");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
  2. Set

    [MTCommand setDeviceDistanceVibration:per isOn:isOn handler:^(bool status) {
        if (status) {
            NSLog(@"setDeviceDistanceVibration successfully");
        } else {
            NSLog(@"setDeviceDistanceVibration failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7

11.Set and read temperature vibration switch

  1. Read

    [MTCommand readDeviceTempVibration:per handler:^(bool status) {
        if (status) {
            NSLog(@"the tempVibration's switch is true");
        }
        else {
            NSLog(@"the tempVibration's switch is false");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8
  2. Set

    [MTCommand setDeviceTempVibration:per isOn:isOn handler:^(bool status) {
        if (status) {
            NSLog(@"setDeviceTempVibration successfully");
        }
        else {
            NSLog(@"setDeviceTempVibration failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
    8

12.Set and read the temperature vibration threshold (30-42℃)

  1. Read

    [MTCommand readDeviceTempVibrationThreshold:per handler:^(int value) {
        if (value != -1) {
            NSLog(@"readDeviceTempVibrationThreshold successfully,the tempVibrationThreshold is %d",value);
        } else {
            NSLog(@"readDeviceTempVibrationThreshold failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7
  2. Set

    [MTCommand setDeviceTempVibrationThreshold:per temp:temp handler:^(bool status) {
        if (status) {
            NSLog(@"setDeviceTempVibrationThreshold successfully");
        } else {
            NSLog(@"setDeviceTempVibrationThreshold failed");
        }
    }];
    
    1
    2
    3
    4
    5
    6
    7

The following are advanced operations, please understand clearly before calling the interface.

13.PowerOff

[MTCommand setPowerOff:per handler:^(bool status) {
    if (status) {
        NSLog(@"setPowerOff successfully");
    }
    else {
        NSLog(@"setPowerOff failed");
    }
}];
1
2
3
4
5
6
7
8

14.Reset

[MTCommand reset:per handler:^(bool status) {
    if (status) {
        NSLog(@"reset successfully");
    }
    else {
        NSLog(@"reset failed");
    }
}];
1
2
3
4
5
6
7
8

15.OTA

[MTCommand ota:per fileData:targetData handler:^(bool status, double progress) {
    if (status) {
        if (progress == 1) {
            NSLog(@"ota successfully");
        }
        else {
            NSLog(@"ota loading,progress:%f",progress);
        }
    }
    else {
        NSLog(@"ota  failed");
    }
}];
1
2
3
4
5
6
7
8
9
10
11
12
13

Note⚠️: When upgrading the OTA firmware, you must keep the phone and Wristband device within 50cm, otherwise it will affect the success of the upgrade

More details you can see in the demo:https://github.com/minewdevelop/iOS_Minew_WristbandDemo

Schedule

MTWristbandCentralManager Property Description

Name Type Description
state PowerState phone's bluetooth status
scannedPeris NSArray scanned devices

MTWristbandPeripheral Property Description

Name Type Description
identifier NSString device Identifier
broadcast MTWristbandBroadcast obejct of MTWristbandBroadcast
connector MTWristbandConnection obejct of MTWristbandConnection

MTWristbandBroadcast Property Description

Name Type Description
name NSString device name
rssi NSInteger device RSSI
mac NSString device Mac
identifier NSString device identifier
firmwareVersion NSString firmversion
isConnect Bool Whether the device wakes up
isStorage Bool Whether the device stores data
totalNum int Total number of device contact alarm history records
tempTotalNum int Total number of device temperature alarm history records
versionType int Device hardware version
usage int Device firmware compatible version

MTWristbandConnection Property Description

Name Type Description
macString NSString device Mac
connection Connection device connect status
Last Updated:: 4/1/2021, 10:02:16 AM