# MinewTrackerKit Development Guide

This SDK only support Minew Trackers base on nordic52 chips, it incompatible with previous trackers based on nordic51 chips. please read this document carefully in order to start developing as soon as possible.

Compatibility instructions: If you have used "MinewFinderSDK" before, the MinewFinder and MinewTrackerKit are not compatible with each other, please don't use them in the same project.

# Preparations

This SDK is similar to the MinewFinde. We update a new encryption and Increased stability, The performance is much higher than trackers based on nordic51 chips.

MTTrackerManager is a class for device managing, it's a shared instance in the APP run time, this SDK will create a MTTracker instance for every device, you can use them for operating and listening devices.

The design ideas:

设计说明

*MTTrackerManager：*device managing class, it can scan devices around and connect to them, validate trackers.

MTTracker：the tracker class, the manager will generate a instance for every physical tracker device.

# Get started

# environment:

  • Xcode9+, the SDK is compiled by xcode9, please use Xcode9 or high to develop APPs.
  • iOS8, the lowest iOS version is 8.

# import the framework：

# CocoaPods

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

pod 'MTTrackKit'
1
# Manually

  1. import the framework file "MTTrackit.framework" to your project, the target is current project.

    添加framework

"Target" -> General -> Embedded Binaries, click the "+" button below, then click "Add Other", choose "MTTrackit.framework"(as the screenshot above). at the same time, you should add the file to "Linked Frameworks and Libraries", as the screenshot below.

frameworkadded

  1. The APP should handle the tracker's event , so we should switch on the background ble permission. as the screenshot below:

  1. *if you use the swift programming language, you need add an Objective C BridgingHead .h file (please solve it by yourself) , import framework in this .h file. if you use Objective C, add "import" at the beginning of the code.
  2. !!! on the iOS10 and above version, we should add a bluetooth description for using iPhone bluetooth module. In your info.plist file, add key-value: Privacy - Bluetooth Peripheral Usage Description - "your description", as the screenshot below:

bluetoothdescription

# Starting Development

# Scan devices

Get the sharedinstance of MTTrackerManager, then you can check the bluetooth state of iPhone or start scanning devices.

// get sharedinstance of Manager
MTTrackerManager *manager = [MTTrackerManager sharedInstance];

// the bluetooth status of iPhone
if(manager.bleState == Poweron) {
   NSLog(@"the state is power on.");
}

// start scanning task.
[manager startScan:^(NSArray<MTTracker *> *trackers){
    // if manager found devices, this block will call back.
}];
1
2
3
4
5
6
7
8
9
10
11
12

PS: the "trackers" array only contains Unbind devices (The following will explain "binding").

# Bind validating

Only bind trackers will work normally, we suggest that the users should keep 10cm between the tracker and iPhone.

Based on previous experience, we create a new encryption for the communication between iPhone and trackers. on the other hand, the trackers' password is null, every tracker needs a password when the user bind it, when is it bind, this tracker will only accept connections from the owner's phone.

/*
  manager: MTTrackerManager sharedInstance
*/
//  set the password, the length must be 8.
//  the password consists of uppercase and lowercase letters, numbers, special symbols.
manager.password = @"********";

// start validating tracker bind operation.
[manager bindingVerify:aTracker completion:^(BOOL success, NSError *error) {
     // the tracker will be add to the "bindTrackers" array of the manager when it's validated.
     // success == NO means validate failed.
}];
1
2
3
4
5
6
7
8
9
10
11
12

PS: the unbind trackers will not work normally, we suggest that using the webserver for different bind passwords of the users.

# Unbind Trackers

if a user lose the tracker or he/she wants to give it others, the user should unbind the tracker. Strictly speaking, the user should keep connection of iPhone and trackers for the unbind operation unless the tracker is lost. The Tracker keeps bind password, unbind operations will delete the password for the next time work normally.

/*
  manager: MTTrackerManager shared instance.
*/
// unbind tracker

// the mac of the tracker
NSString *mac = @"acd498765432";

// unbind the tracker
[manager unbindTracker:mac completion:^(BOOL success, NSError *error) {
    // success YES means operate success, else NO.
}];
1
2
3
4
5
6
7
8
9
10
11
12
13
# Get the information

You can get the information of physical devices via the MTTracker instance, such as the mac address, rssi and so on.

// aTracker MTTracker instance

NSString *mac = aTracker.mac; // mac address
NSString *name = aTracker.name; // bluetooth name
NSInteger rssi = aTraker.rssi;   // RSSI
NSInteger battery = aTracker.battery; // battery 0～100
Connection status = aTracker.connection; // current connection status
ModelType model = aTracker.model;    // the tracker's model
Distance dis = aTracker.distance;    // distance information.
1
2
3
4
5
6
7
8
9
# Ring the Tracker

you can ring the tracker via our APi. Of course, the device remains connected.

// aTracker MTTracker instance

// ring == YES means ring the tracker, NO will stop the ring.
BOOL ring = YES;

// switch the bell status of the tracker
[aTracker switchBellStatus:ring completion:^(BOOL success, NSError *error) {
    if (success) {
       NSLog(@"switch the ring status successfully!");   
    }
}];
1
2
3
4
5
6
7
8
9
10
11
# The disconnection of the trackers.

The tracker device have disconnection event, such as alert when disconnected.

// aTracker MTTracker instance

// YES means the tracker will rings when disconnected, else Not.
BOOL alert = YES;

// set the disconnection alert
[aTracker writeLossAlert:alert completion:^(BOOL success, NSError *error) {
   
    if (success) {
       NSLog(@"config the disconnection alert successfully!");   
    }
}];]
1
2
3
4
5
6
7
8
9
10
11
12
# Receive the events of the trackers

The iPhone accepts the devices events, listen them and handle the events.

// aTracker MTTracker instance
[aTracker didReceive:^(Receiving rec) {
    
    // button pressed，
    // handle the button pressed event
    if(rec == ReceivingButtonPushed) {
       NSLog(@"The button on the device is pressed"); 
    }
}];

// listen the event changes of the device
[aTracker didConnectionChange:^(Connection con){
    switch(con){
        case ConnectionConnecting:
            NSLog(@"Connection to the Tracker");
            break;
        case ConnectionConnected:
            NSLog(@"Tracker is connected");
            break;
        case ConnectionDisconnected:
            NSLog(@"Tracker is disconnected");
            break;
    }; 
}];

// listen the data changes
[aTracker didValueUpdate:^(){
    /*
      the trackers status updated, you may want to refresh the UI.
    */
}];
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
# After the APP restarted

You may find the SDK operate the memory data only, if the APP is been killed, the Bind trackers will lose. so you should make the perpetual storage all by yourself, such as the current bind password, the MAC address of every tracker.

We also provide some APi for related operations after APP recovery.

// get a bind tracker instance
/*
  The SDK will handle the given mac address and generate a MTTracker instance intelligently, if the tracker is working around, the SDK will handle the connection and configuration automatically.
  
  The only thing that needs attention is the need to ensure that the provided mac address is bound， it means that you have used the method “- (void)bindingVerify:(MTTracker *)tracker completion:(void(^)(BOOL success, NSError *error))handler;” and got a success callback.
  
  at the same time, the devices correspond to Mac addresses will be added to the bindTrackers array by the manager.
*/
MTTracker *bindTracker = [aManager addTracker:@"xxxxxxxxxxxx"];
1
2
3
4
5
6
7
8
9
# About the user switching

sometimes the user may sign out the current account and sign in another account. At this point, we should remove the current bind trackers and load the new user's bind trackers.

// remove the bind trackers of current user.
[aMTTrackerManager removeAllTrackers];

// set the bind password of the new user
aMTTrackerManager.password = @"********"; 

/*
    load the bind trackers' mac addresses, assuming the array is bindMacs
*/
for(NSinteger i = 0; i < bindMacs.count; i ++) {
    // tracker is the bind tracker of the new user
   MTTracker *tracker = [aMTTrackerManager addTracker:bindMacs[i]]; 
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# !!!Advanced operations

This part is Advanced APi, we provide it to the Advanced developers. Unless you understand the results of what these operations will lead to, don't try it lightly.

// aTracker MTTracker instance

// modify the delay of disconnected alert

// it means the tracker will alert after "delay" seconds since the tracker is disconnected.
// please note: the range is 1s-7s, Too small value may cause false alert.
NSInteger delay = 7;

// set the disconnect alert delay.
[aTracker writeLossDelay:delay completion:^(BOOL success, NSError *error) {
    
    if(success) {  // write successfully.
        
    }
}];

// this parameter is the disconnect distance, the tracker will disconnect at that distance.
// For example: is the level is "Far", the tracker will disconnect at 30m, "Middle": 20m,
// "Near": 10m;
// Please note the 30m/20m/10m above is not a real value, Because the actual environment is very complicated.
// Three values: Far/Middle/Near for choosen, the default is "Far".
DistanceLevel level = DistanceLevelFar;
[aTracker writeLossDistance:level completion:^(BOOL success, NSError *error) {
    if (success) {   // write successfully.
    }
}];
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

# New features in F5

Added the ability to modify device ringtones and query device ringtones in F5 devices.

NSInteger type = 0;//type ：0/1/2/3/4
//Write device ringtone
[aTracker writeLossDeviceSound:type com:^(BOOL status) {
        if (status) {//write success
            
        }
}];

//Read device ringtones
[aTracker writeSelectLossDeviceSound:^(uint8_t type) {
        
}];
1
2
3
4
5
6
7
8
9
10
11
12

# New features in F6

Added mobile alarm switch and mobile alarm sensitivity gear settings in the F6 device and provided queries.

Bool isMoving = YES;
//Write mobile alarm switch data，isMoving = YES:ON，isMoving = NO:OFF
[aTracker writeMovingAlert:isMoving completion:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"write moving alert success");
        }
        else {
            NSLog(@"write moving alert error:%@",error);
        }
}];

//Read mobile alarm switch data
[aTracker writeSelectMovingAlert:^(uint8_t type) {//type=1:ON，type=0:OFF

}];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
NSInteger level = 0//0:Low，1:Middle，2:High，If the value is not 0/1/2, the default is to select the low gear.
//Write mobile alarm sensitivity gear setting
[aTracker writeMovingAlertLevelSetting:level completion:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"write moving alert success");
        }
        else {
            NSLog(@"write moving alert error:%@",error);
        }
}];
//Read mobile alarm sensitivity gear setting
[aTracker writeSelectMovingAlertLevel:^(uint8_t type) {//type=0:Low，type=1:Middle，type=2:High
        self->_deviceACCLevel = type;
}];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Last Updated:: 1/12/2024, 2:37:29 PM