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 下午2:07:16