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获得。要安装它,只需将以下行添加到您的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
上次更新:: 2020/12/29 上午10:50:07