# MinewTrackerKit开发套件说明文档

本套SDK仅支持基于的nordic52芯片寻物器，与过去的51芯片不兼容。请仔细阅读此文档以便尽快上手开发。

兼容性说明：过去用过MinewFinderSDK的开发者请注意：MinewFinder与MTTrackerKit互相不兼容，切不可用于同一个项目。

# 前期工作

此开发套件和过去的MinewFinder有些类似。我们在之前的基础上全面更新了加密算法和设备端稳定性，性能实际表现远远高于51版本的Tracker。

MTTrackerManager为设备管理类，在APP运行时始终是单例。MTTracker是设备实例类，此套件会为每一个设备生成一个MTTracker实例以便于对监听设备和操作设备。

整体设计思路如下图所示：

设计说明

为了区分设备，我们

*MTTrackerManager：*设备管理类，可以扫描周围的Tracker设备，并且可以连接它们，校验它们等。

MTTracker：设备实例类，当Manager发现一个物理设备时，Manager会生成一个Tracker实例，这个实例就对应一个物理设备。

# 开始上手

# 开发环境：
  • Android Studio
# 导入到工程：

  1. 将开发套件MTTrackerKit.jar文件拷贝到libs目录下，然后在build.gradle中添加依赖。如下图所示：

    添加 jar包

  2. AndroidManifest.xml 文件下添加蓝牙权限和相应的组件注册。如下所示：

       <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

    在Android-6.0以上版本蓝牙扫描需要动态申请地理位置权限，具体如下：

    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

# 开始开发

# 扫描设备

首先需要获取到MTTrackerManager的单例，然后检查手机当前的蓝牙状态，接着就可以进行设备扫描了。

// 获取Manager单例 Context 
MTTrackerManager manager = MTTrackerManager.getInstance(context);

// 手机端当前的蓝牙开关状态
if(manager.checkBluetoothState == BluetoothStatePowerOn) {
     // 开始进行设备扫描 扫描到设备后会通过接口回调数据。
   manager.startScan(scanTrackerCallback); 
	
}
1
2
3
4
5
6
7
8
9

PS：trackers集合里包含的只有未绑定的设备（下文将会提供绑定相关说明）。

# 绑定校验

某个Tracker只有被绑定了才能正常使用，我们建议进行绑定操作时，Tracker与手机的距离不要超过10cm。

基于以前的经验，我们使用了全新的加密算法来保证手机和设备之间通信的安全性。另外，Tracker在出厂时默认密码为空，每个设备在绑定时都需要一个密码，一旦绑定成功，这个Tracker将只接受来自主人手机的连接。

/*
  manager: MTTrackerManager单例
*/
// 设置密码,长度必须是8位,可以是大小写字母，数字，特殊符号。
manager.setPassword("********");

// 开始进行设备绑定验证操作
manager.bindingVerify(mtTracker,connectionStateCallback);
// 如果绑定验证成功了，tracker将会被自动添加到manager的bindTrackers数组里，
// 否则说明此设备因为种种原因无法成功绑定。
1
2
3
4
5
6
7
8
9
10

PS：无法绑定的设备是不能正常使用的。

# 解绑设备

如果用户丢失了某个Tracker，或者想把Tracker送给别人。就需要进行解绑操作，严格的来说，除非Tracker丢失了。其它情况下都应该在保持设备与手机连接的状态下进行解绑操作。这是由于Tracker内部记录了当前主人的密码，解绑时需要擦除密码才能保证下一次的正常使用。

/*
  manager: MTTrackerManager单例
*/
// 解除设备绑定

// 你想要解除绑定设备的mac地址
String mac = "acd498765432";

// 解除设备绑定
manager.unBindMTTracker(mac , operationCallback);
// 同样的，操作成功后 回调success为YES，否则为NO。
1
2
3
4
5
6
7
8
9
10
11
# 获取设备信息

你可以通过MTTracker实例获取到对应物理设备的信息，例如蓝牙名称，mac地址，rssi等数据。

// aTracker MTTracker实例
String mac = mtTracker.getMacAddress(); // mac 地址
int rssi = mtTracker.getRssi();   // 信号强度
int battery = mtTracker.getBattery(); // 电池 0～100
ConnectionState connectionState = mtTracker.getConnectionState(); // 设备当前的连接状态
TrackerModel name = mtTracker.getName();    // 设备型号
1
2
3
4
5
6
# 呼叫设备

通过我们提供的APi，可以对设备进行呼叫，当然是在设备保持连接的状态下。

// mtTracker MTTracker实例

// 当ring 为true的时候是让设备响铃，为false的时候是停止设备响铃。
boolean ring = true;
// 切换设备响铃状态
mtTracker.switchBellStatus(ring, new OperationCallback() {
                        @Override
                        public void onOperation(boolean success, TrackerException mtException){
                            if (success) {
                                Log("tracker","响铃状态切换成功。");  
                            }
                        }
                    });
1
2
3
4
5
6
7
8
9
10
11
12
13
# 配置设备断开时的事件处理

Tracker在断开时会有相应的事件处理，比如断开响铃以告知用户等。

// mtTracker MTTracker实例

// 为true表示Tracker断开时将会响铃，否则不响铃
boolean alert = true;
mtTracker.setLoseAlert(alert, new OperationCallback() {
                    @Override
                    public void onOperation(boolean success, TrackerException mtException) {
                        if (!success) {
                            Log.e("tag", "发送设备响铃命令失败");
                        }
                    }
                });
1
2
3
4
5
6
7
8
9
10
11
12
# 接受来自设备的事件

手机可以接受来自设备的事件，需要做好相关监听。

// mtTracker MTTracker实例

mtTracker.setReceiveListener(new ReceiveListener() {
            @Override
            public void onReceive(ReceiveIndex receiveIndex) {
                 // Tracker上的按钮被按下，
                // 你可以在这里处理拍照，手机端报警等操作。
                if(receiveIndex == InstrucIndex_ButtonPushed) {
                   Log.v("tracker","按下了设备上的按钮。"); 
                }
            }
        });

mtTracker.setTrackerListener(new MTTrackerListener() {
            @Override
            public void onUpdateTracker(MTTracker mtTracker) {
                /*
                  设备的属性或状态更新了，你可以刷新UI界面了。
                */
            }

            @Override
            public void onUpdateConnectionState(ConnectionState connectionState) {
				// 监听设备连接状态变化
              	
            }
        });
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
# 重启APP后的相关处理

你可能会发现，SDK的操作只涉及到内存数据，如果APP被Kill掉，之前的绑定数据什么的就失效了。所以需要你自行做数据永久化存储，比如当前用户的绑定密码，每个已绑定设备的Mac地址等。

当然，我们也提供了一些APi用于APP恢复后的相关操作。

以下代码均在APP重新运行时处理的。

// 获取一个已绑定Tracker的实例
/*
  SDK会智能解析mac地址并生成一个MTTracker实例，如果Tracker在手机附近正常工作。SDK会自动处理连接配置等的相关操作。
  唯一需要注意的就是需要保证所提供的mac地址是已绑定的，就是使用过 “bindingVerify(MTTracker mtTracker, ConnectionStateCallback connectionStateCallback)” 方法并且获得了成功的回调。
  在获取到MTTracker实例的同时，此Tracker实例也被添加到BindTrackers数组里。
*/
MTTracker bindTracker = manager.bindMTTracker(macAddress);
1
2
3
4
5
6
7
8
# 关于用户切换

有的时候可能出现当前用户注销自己的登录，然后登入另外一个账号，此时就需要从Manager中移除已经绑定的设备，然后加载新用户的已绑定设备。

// 移除当前用户的绑定设备
manager.unBindMTTracker(String macAddress, OperationCallback operationCallback) 

// 设置密码
manager.setPassword("********");
  
/*
     此处加载新用户的绑定设备Mac地址，假设为数组：bindMacs
*/
for(int i = 0; i < bindMacs.length; i ++) {
   // tracker就是新用户的已绑定设备
   MTTracker bindTracker = manager.bindMTTracker(bindMacs[i]);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# F5新增功能

F5新增修改设备铃声指令，提供了5中可选铃声，连接成功后，通过MTTracker.getFirmwareVersion()判断版本，如下：

FinderVersionEnum firmwareVersion = .mMTracker.getFirmwareVersion();
if (firmwareVersion == null || firmwareVersion.getVersionCode() < 		FinderVersionEnum.VERSION1_0_71.getVersionCode()) {
    //说明是F5以下版本
} else {
    //是F5
}
1
2
3
4
5
6
7

如果是F5及以上版本，那么就有可修改设备铃声功能

  1. 通过getDeviceRing方法可以获取F5当前选择的铃声
  2. 可通过MTracker.setDeviceAlarmRing修改设备铃声
/**
 * position值为0到4，传入值超出范围，会失败，报出：The value of the device alarm value is invalid错误
 */
mMTracker.setDeviceAlarmRing(position, new OperationCallback() {
    @Override
    public void onOperation(boolean success, TrackerException mtException) {
        //success说明修改成功，否则修改失败
    }
});
1
2
3
4
5
6
7
8
9
10
# F6新增功能

F6新增了移动触发报警功能，通过MTTracker.getFirmwareVersion()判断版本，如下：

FinderVersionEnum firmwareVersion = .mMTracker.getFirmwareVersion();
if (firmwareVersion == null || firmwareVersion.getVersionCode() < 		FinderVersionEnum.VERSION1_0_72.getVersionCode()) {
    //说明是F6以下版本
} else {
    //是F6
}
1
2
3
4
5
6
7

如果是F6及以上版本，那么就有移动报警功能

  1. 可通过mMTracker.getSensitivity()获取设备当前灵敏度
  2. 可通过mMTracker.isOpenSensitivity()查询是否已经开启移动报警功能，如果为true，则已打开，false则是关闭状态。移动报警功能可以设置灵敏度，有三个可选值
mMTracker.setMoveSensitivity(currentIndex, new OperationCallback() {
    @Override
    public void onOperation(boolean success, TrackerException mtException) {
        if (success) {
           //设置灵敏度成功
        }else {
            //设置灵敏度失败
        }
    }
});
1
2
3
4
5
6
7
8
9
10
11

# !!!高级操作

此部分APi属于高级APi，我们把这部分开放给高级开发。除非你明白这些操作的将会导致什么样子的结果，否则不要轻易尝试。

// mtTracker MTTracker实例

// 修改设备的断开延迟。

// 这个参数指的是在断开响铃的状态下，设备端将等待delay秒后开始发出声音。
// 需要注意，它的范围是1s-7s，如果设置的数据太小将会出现误报的问题。
int delay = 7;

// 写入断开延迟
mtTracker.setDisAlarmDelay(delay, new OperationCallback() {
            @Override
            public void onOperation(boolean success, TrackerException mtException) {
                if (!success) {
                    Log.e("mtag", "sendDisAlarmDelaytoDeviceFail");
                }
            }
        });

// 这个参数指的是设备的断开距离，设备将在配置的距离断开连接。
// 例如：如果配置的是“远”，设备将在30米左右断开连接。“中”：将在20米左右，“近”，将在10米左右。
// 需要注意的是，上述30米/20米/10米是举例值，实际使用中受限于环境
// 有远/中/近三档可选，默认情况下是“远”。
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

# 文档版本：

  • 20190220 修复有概率导致连接不上的bug；修复连接状态返回异常的问题；
  • 20180521 初版；
  • 20191127 增加F5、F6新增功能说明，MTTracker新增若干属性
上次更新:: 2019/11/27 14:07:16