# MinewTrackerKit说明文档

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

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

# 前期工作

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

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

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

设计说明

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

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

# 开始上手

# 开发环境：

  • Xcode9+，当前SDK使用Xcode9编译，请使用Xcode9及以上版本进行开发；
  • iOS8，限制最低系统版本为iOS8；

# 导入到工程：

# CocoaPods

MTTrackKit可通过CocoaPods获得 (opens new window)。要安装它，只需将以下行添加到您的Podfile中，然后导入 <MTTrackKit/MTTrackKit.h>：

pod 'MTTrackKit'
1
# 手动导入

  1. 将开发套件的framework文件：MTTrackit.framework拷贝到项目工程目录下，然后添加到工程中，target为当前的工程，然后点“Add”，如下图所示：

    添加framework

​ 依次找到：“Target” -> General -> Embedded Binaries，点击下面的“+”，继续点击“Add Other”将MTTrackit.framework文件添加进来。同样的，也需要添加到 ”Linked Frameworks and Libraries“，添加完应该如下图：

frameworkadded

  1. 由于APP需要在后台时也能正常响应Tracker的事件，因此需要开启相关的后台蓝牙权限。如下图：

  2. *如果使用Swift开发，需要添加一个Objective C BridgingHeader .h文件（此处不再赘述），并且在此文件添加：import ，如果使用Objective C进行开发，在需要的文件的顶端添加：import

  3. !!!在iOS10及以上版本，苹果对蓝牙APi添加了权限限制，你需要在工程的info.plist文件里添加一项字符串：Privacy - Bluetooth Peripheral Usage Description - "你的使用描述"。如下图所示：

    bluetoothdescription

# 开始开发

# 扫描设备

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

// 获取Manager单例
MTTrackerManager *manager = [MTTrackerManager sharedInstance];

// 手机端当前的蓝牙开关状态
if(manager.bleState == Poweron) {
     // 开始进行设备扫描
    [manager startScan:^(NSArray<MTTracker *> *trackers){
        // 当检测到周围的设备后，此block会回调。
    }];   
}
1
2
3
4
5
6
7
8
9
10

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

# 绑定校验

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

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

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

// 开始进行设备绑定验证操作
[manager bindingVerify:aTracker completion:^(BOOL success, NSError *error) {
     // 如果绑定验证成功了，tracker将会被自动添加到manager的bindTrackers数组里，
     // 否则说明此设备因为种种原因无法成功绑定。
}];
1
2
3
4
5
6
7
8
9
10
11

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

# 解绑设备

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

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

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

// 解除设备绑定
[manager unbindTracker:mac completion:^(BOOL success, NSError *error) {
    // 同样的，操作成功后 success为YES，否则为NO。
}];
1
2
3
4
5
6
7
8
9
10
11
12
13
# 获取设备信息

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

// aTracker MTTracker实例

NSString *mac = aTracker.mac; // mac 地址
NSString *name = aTracker.name; // 蓝牙名称
NSInteger rssi = aTraker.rssi;   // 信号强度
NSInteger battery = aTracker.battery; // 电池 0～100
Connection status = aTracker.connection; // 设备当前的连接状态
ModelType model = aTracker.model;    // 设备型号
Distance dis = aTracker.distance;    // 距离信息
1
2
3
4
5
6
7
8
9
# 呼叫设备

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

// aTracker MTTracker实例

// 当ring 为YES的时候是让设备响铃，为NO的时候是停止设备响铃。
BOOL ring = YES;

// 切换设备响铃状态
[aTracker switchBellStatus:ring completion:^(BOOL success, NSError *error) {
    if (success) {
       NSLog(@"响铃状态切换成功。");   
    }
}];
1
2
3
4
5
6
7
8
9
10
11
# 配置设备断开时的事件处理

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

// aTracker MTTracker实例

// 为YES表示Tracker断开时将会响铃，否则不响铃
BOOL alert = YES;

[aTracker writeLossAlert:alert completion:^(BOOL success, NSError *error) {
   
    if (success) {
       NSLog(@"成功配置断开事件处理。");   
    }
}];]
1
2
3
4
5
6
7
8
9
10
11
# 接受来自设备的事件

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

// aTracker MTTracker实例
[aTracker didReceive:^(Receiving rec) {
    
    // Tracker上的按钮被按下，
    // 你可以在这里处理拍照，手机端报警等操作。
    if(rec == ReceivingButtonPushed) {
       NSLog(@"按下了设备上的按钮。"); 
    }
}];

// 监听设备连接状态变化
[aTracker didConnectionChange:^(Connection con){
    switch(con){
        case ConnectionConnecting:
            NSLog(@"正在连接到Tracker");
            break;
        case ConnectionConnected:
            NSLog(@"Tracker已经连接");
            break;
        case ConnectionDisconnected:
            NSLog(@"Tracker已经断开连接");
            break;
    }; 
}];

// 监听设备数据更新
[aTracker didValueUpdate:^(){
    /*
      设备的属性或状态更新了，你可以刷新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
# 重启APP后的相关处理

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

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

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

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

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

// 移除当前用户的绑定设备
[aMTTrackerManager removeAllTrackers];

// 设置新用户的绑定密码 
aMTTrackerManager.password = @"********"; 

/*
     此处加载新用户的绑定设备Mac地址，假设为数组：bindMacs
*/
for(NSinteger i = 0; i < bindMacs.count; i ++) {
   // tracker就是新用户的已绑定设备
   MTTracker *tracker = [aMTTrackerManager addTracker:bindMacs[i]]; 
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# !!!高级操作

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

// aTracker MTTracker实例

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

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

// 写入断开延迟
[aTracker writeLossDelay:delay completion:^(BOOL success, NSError *error) {
    
    if(success) {  // 成功写入到设备。
        
    }
}];

// 这个参数指的是设备的断开距离，设备将在配置的距离断开连接。
// 例如：如果配置的是“远”，设备将在30米左右断开连接。“中”：将在20米左右，“近”，将在10米左右。
// 需要注意的是，上述30米/20米/10米是举例值，实际使用中受限于环境
// 有远/中/近三档可选，默认情况下是“远”。
DistanceLevel level = DistanceLevelFar;
[aTracker writeLossDistance:level completion:^(BOOL success, NSError *error) {
    if (success) {   // 成功写入到设备
            
    }
}];
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

#

# F5新特性

在F5设备中新增了修改设备铃声和查询设备铃声的功能。

NSInteger type = 0;//type ：0/1/2/3/4
//写入设备铃声
[aTracker writeLossDeviceSound:type com:^(BOOL status) {
        if (status) {//修改成功
            
        }
}];

//查询设备铃声
[aTracker writeSelectLossDeviceSound:^(uint8_t type) {
        
}];
1
2
3
4
5
6
7
8
9
10
11
12

# F6新特性

在F6设备中新增了移动报警开关和移动报警灵敏度档位设置，并提供查询。

Bool isMoving = YES;
//写入移动报警开关数据，isMoving = YES:开，isMoving = NO:关
[aTracker writeMovingAlert:isMoving completion:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"write moving alert success");
        }
        else {
            NSLog(@"write moving alert error:%@",error);
        }
}];

//查询移动报警开关
[aTracker writeSelectMovingAlert:^(uint8_t type) {//type=1:开，type=0:关

}];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
NSInteger level = 0//0:低，1:中，2:高,如若传值非0/1/2，即默认选择低档位
//写入移动报警灵敏度档位设置
[aTracker writeMovingAlertLevelSetting:level completion:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"write moving alert success");
        }
        else {
            NSLog(@"write moving alert error:%@",error);
        }
}];
//查询移动报警灵敏度档位
[aTracker writeSelectMovingAlertLevel:^(uint8_t type) {//type=0:低，type=1:中，type=2:高
        self->_deviceACCLevel = type;
}];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
上次更新:: 2024/1/12 14:37:29