# 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:

  • Android Studio
# import the framework：

  1. import the jar file "MTTrackerKit.jar" to your project,Then add the dependency in build.gradle.

    添加 jar包

  2. Add Bluetooth permissions and corresponding component registration under AndroidManifest.xml file. As follows:

       <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
   <uses-permission android:name="android.permission.BLUETOOTH"/>
   <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
    1
    2
    3
    4

    In Android-6.0 or later versions, Bluetooth scanning requires dynamic application for geographic permission, as follows:

    if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_COARSE_LOCATION)
                != PackageManager.PERMISSION_GRANTED) {
            ActivityCompat.requestPermissions(this,
                    new String[]{Manifest.permission.ACCESS_COARSE_LOCATION}, PERMISSION_COARSE_LOCATION);
        }
    1
    2
    3
    4
    5

# Starting Development

# Scan devices

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

// get sharedinstance of Manager
MTTrackerManager manager = MTTrackerManager.getInstance(context);

// the bluetooth status of Phone
if(manager.checkBluetoothState == BluetoothStatePowerOn) {
  // start scanning task.
  // if manager found devices, this block will call back.
  manager.startScan(scanTrackerCallback); 
}
1
2
3
4
5
6
7
8
9

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 Phone 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.setPassword("********");

// start validating tracker bind operation.
manager.bindingVerify(mtTracker,connectionStateCallback);
// the tracker will be add to the "bindTrackers" array of the manager when it's validated.
// success == false means validate failed.
1
2
3
4
5
6
7
8
9
10
11

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 Phone 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
String mac = "acd498765432";

// unbind the tracker
manager.unBindMTTracker(mac , operationCallback);
// success true means operate success, else false.
1
2
3
4
5
6
7
8
9
10
11
# 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
String mac = mtTracker.getMacAddress(); // mac address
int rssi = mtTracker.getRssi();   // Rssi
int battery = mtTracker.getBattery(); // battery 0～100
ConnectionState connectionState = mtTracker.getConnectionState(); // current connection status
TrackerModel name = mtTracker.getName();    // the tracker's model
1
2
3
4
5
6
# Ring the Tracker

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

// mtTracker MTTracker instance

// ring == true means ring the tracker, false will stop the ring.
boolean ring = true;
// switch the bell status of the tracker
mtTracker.switchBellStatus(ring, new OperationCallback() {
                        @Override
                        public void onOperation(boolean success, TrackerException mtException){
                            if (success) {
                                Log("tracker","switch the ring status successfully!");  
                            }
                        }
                    });
1
2
3
4
5
6
7
8
9
10
11
12
13
# The disconnection of the trackers.

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

// mtTracker MTTracker instance

// true means the tracker will rings when disconnected, else Not.
boolean alert = true;
mtTracker.setLoseAlert(alert, new OperationCallback() {
                    @Override
                    public void onOperation(boolean success, TrackerException mtException) {
                        if (success) {
                            Log.e("tag", "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.

// mtTracker MTTracker instance

mtTracker.setReceiveListener(new ReceiveListener() {
            @Override
            public void onReceive(ReceiveIndex receiveIndex) {
                // button pressed，
                // handle the button pressed event
                if(receiveIndex == InstrucIndex_ButtonPushed) {
                   Log.v("tracker","The button on the device is pressed"); 
                }
            }
        });

mtTracker.setTrackerListener(new MTTrackerListener() {
            @Override
            public void onUpdateTracker(MTTracker mtTracker) {
                /*
                 the trackers status updated, you may want to refresh the UI.
                */
            }

            @Override
            public void onUpdateConnectionState(ConnectionState connectionState) {
				// listen the event changes of the device
              	
            }
        });
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
# 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 “bindingVerify(MTTracker mtTracker, ConnectionStateCallback connectionStateCallback)” 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 = manager.bindMTTracker(macAddress);
1
2
3
4
5
6
7
8
9
10
# 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.
manager.unBindMTTracker(String macAddress, OperationCallback operationCallback) 
  
// set the bind password of the new user
manager.setPassword("********");

/*
      load the bind trackers' mac addresses, assuming the array is bindMacs
*/
for(int i = 0; i < bindMacs.length; i ++) {
   // tracker is the bind tracker of the new user
   MTTracker bindTracker = manager.bindMTTracker(bindMacs[i]);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# F5 New Features

F5 adds a new device ringtone instruction, which provides 5 optional ringtones. After the connection is successful, use MTTracker.getFirmwareVersion () to determine the version, as follows:

FinderVersionEnum firmwareVersion = .mMTracker.getFirmwareVersion();
if (firmwareVersion == null || firmwareVersion.getVersionCode() < 		FinderVersionEnum.VERSION1_0_71.getVersionCode()) {
    //Description is below F5
} else {
    //F5 and above
}
1
2
3
4
5
6
7

If it is F5 and above, then there is a function to modify the device ringtone

  1. You can get the ringtone currently selected by F5 through the getDeviceRing method
  2. Device ringtone can be modified through MTracker.setDeviceAlarmRing
/**
 * The position value is 0 to 4. If the incoming value is out of range, it will fail. It will report: The value of the device alarm value is invalid.
 */
mMTracker.setDeviceAlarmRing(position, new OperationCallback() {
    @Override
    public void onOperation(boolean success, TrackerException mtException) {
        //success indicates that the modification was successful, otherwise the modification failed
    }
});
1
2
3
4
5
6
7
8
9
10
# F6 new features

F6 has added a mobile trigger alarm function. The version is determined by MTTracker.getFirmwareVersion (), as follows:

FinderVersionEnum firmwareVersion = .mMTracker.getFirmwareVersion();
if (firmwareVersion == null || firmwareVersion.getVersionCode() < 		FinderVersionEnum.VERSION1_0_72.getVersionCode()) {
    //Description is below F6
} else {
    //F6 and above
}
1
2
3
4
5
6
7

If it is F6 and above, there is mobile alarm function

  1. The current sensitivity of the device can be obtained through mMTracker.getSensitivity ()
  2. You can query whether the mobile alarm function is enabled by mMTracker.isOpenSensitivity (). If it is true, it is enabled, and false is disabled. Mobile alarm function can set sensitivity, there are three selectable values
mMTracker.setMoveSensitivity(currentIndex, new OperationCallback() {
    @Override
    public void onOperation(boolean success, TrackerException mtException) {
        if (success) {
           //Setting sensitivity is successful
        }else {
            //Setting sensitivity failed
        }
    }
});
1
2
3
4
5
6
7
8
9
10
11

# !!!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.
int delay = 7;

// set the disconnect alert delay.
mtTracker.setDisAlarmDelay(delay, new OperationCallback() {
            @Override
            public void onOperation(boolean success, TrackerException mtException) {
                if (!success) {
                    Log.e("mtag", "sendDisAlarmDelaytoDeviceFail");
                }
            }
        });

// 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 = PowerLevel_Far;
mtTracker.setDisAlarmDistance(level, new OperationCallback() {
                @Override
                public void onOperation(final boolean success, TrackerException mtException) {
                    if (!success) {
                        Log.e("mtag", "sendDisAlarmDistancetoDeviceFail");
                    }
                }
            });
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

# Change log

  • 2019.02.20 Fixed a bug that had the probability of not being able to connect; Fix connection status return exception problem;
  • 2018.05.21 v1.0 first version;
  • 2019.11.27 Added F5, F6 new function description, MTTracker added some attributes;
Last Updated:: 11/27/2019, 2:07:16 PM