MinewModuleKit说明文档

本套SDK仅支持Minew公司出品的蓝牙模块设备。通过SDK可以帮助开发者处理手机和蓝牙模块之间的一切工作,包括:扫描设备,连接设备,向设备写入数据,从设备接收数据等。

前期工作

整体框架如下图所示:MTModuleManager为设备管理类,在APP运行时始终是单例。MTModule是设备实例类,此套件会为每一个设备生成一个MTModule实例以便于对监听设备和操作设备。

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

设计说明

*MTModuleManager:*设备管理类,可以扫描周围的Module设备,并且可以连接它们,校验它们等。

MTModule:设备实例类,当Manager发现一个物理设备时,Manager会生成一个Module实例,这个实例就对应一个物理设备。

开始上手

开发环境:

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

导入到工程:

CocoaPods

MTModuleKit可通过CocoaPods获得。要安装它,只需将以下行添加到您的Podfile中,然后导入 <MTModuleKit/MTModuleKit.h>:

pod 'MTModuleKit'
1
手动导入
  1. 将开发套件的framework文件:MTModuleKit.framework拷贝到项目工程目录下,然后添加到工程中,target为当前的工程,然后点“Add”,如下图所示:

    添加framework

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

frameworkadded

  1. *如果使用Swift开发,需要添加一个Objective C BridgingHeader .h文件(此处不再赘述),并且在此文件添加:import ,如果使用Objective C进行开发,在需要的文件的顶端添加:import

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

bluetoothdescription

  1. !!!在iOS13及以上版本,苹果对蓝牙APi添加了权限限制,你需要在工程的info.plist文件里添加一项字符串:Privacy - Bluetooth Always Usage Description - "你的使用描述"。

开始开发

初始化及扫描设备

首先需要获取到MTModuleManager的单例,此时,SDK将会调用系统蓝牙模组并进行核心初始化,需要注意的是,唤醒系统的蓝牙模组需要一定的时间,如果一切正常,唤醒后蓝牙工作状态为Poweron,需要注意的是,所有的操作都必须且只能在Poweron状态下进行。监听系统蓝牙变化及扫描设备请参考下述代码:

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

// 如果你需要对手机的蓝牙状态作出响应。请监听回调。
[manager didChangesBluetoothStatus:^(BluetoothStatus status){
    
    switch(status) {
        case Poweron:   // !!! SDK只能工作在Poweron状态下
        {
            NSLog(@"bluetooth status change to poweron");
            // 开始进行设备扫描
            [manager startScan:^(NSArray<MTModule *> *Modules){
            // 当检测到周围的设备后,此block会回调。
            }];      
            break;
         }
        case Poweroff:
            NSLog(@"bluetooth status change to poweroff");
            break;
        case Unknown:
            NSLog(@"bluetooth status change to unknown");
    }
}];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
单独获取手机蓝牙状态

如果你想在某些情况下检查当前手机的蓝牙状态,请参考如下代码,需要注意,此代码获取的是即时状态,若需要监听变化请参见上一项。

if(manager.status == Poweron) {
   NSLog(@"the bluetooth status is Poweron."); 
}
1
2
3
连接到设备
// 从上一步能够获取到扫描到的设备
MTModule *module = modules[0];

// 监听设备连接状态。
// !!!只有在连接状态为Connected的时候,这个设备才是可以写入数据的
[module didChangeConnection:^(Connection con){
    if(con == Connected) {
        NSLog(@"设备已经建立连接");
    }
}];

// 连接到一个模块设备
[manager connect:module];
1
2
3
4
5
6
7
8
9
10
11
12
13
向设备写入数据

接上一步,当手机成功与某个设备建立连接后,就可以对设备进行读写操作了。

// 对设备写入数据
// 首先要构造你想写入的数据,这里构造了一组四个字节的数据 0x01,0x02,0x03,0x04.
uint8_t bytes[4] = {0x01, 0x02, 0x03, 0x04};
NSData *data = [NSData dataWithBytes:&bytes length:4];

// 然后可以直接执行一下方法,将上述构造的数据写入到设备中。
// 同时你可以在block中获取到写入是否成功的结果。
[module writeData:data completion:^(BOOL success, NSError *error){
    if(success) {
        NSLog(@"write data successfully.");
    }
    else {
        NSLog(@"write data failed.");
    }
}];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
从设备接收数据

由于手机并不知道什么时候设备会发送数据过来,所以在这里使用监听block的方式来实现数据接收。

// 配置block等待接收数据
[module didReceiveData:^(NSData *data){
    NSLog(@"从设备端接收到数据:%@",data);
}];
1
2
3
4
从设备读取系统信息

如果固件带有系统信息,可进行获取,方法如下

/*
  infos属性为设备的BLE DIS字典,包含当前设备的所有基本信息
  
*/
NSDictionary<String *, String *> *disDict = aMTModule.infos;

1
2
3
4
5
6

infos如果为空,表示此设备不支持。关于支持DIS的固件版本,请见下表:

固件版本(Verison) 是否支持
Version < 1.6.0
1.6.0 <= Version < 2.0.0
2.0.0 <= Version < 2.3.0
2.3.0 <= Version < 3.0.0
3.0.0 <= Version < 3.1.0
3.1.0 <= Version

附表

MTModuleManager 属性说明
名称 类型 备注
status BluetoothStatus 当前的手机蓝牙状态
scannedModules NSArray 扫描到的设备
connectedModules NSArray 当前连接中的设备
MTModule
名称 类型 备注
name NSString 设备的蓝牙名称
identifier NSString 设备的识别码*
advertisingData NSData 设备的广播数据
lastUpdate NSDate 设备最后一次被扫描到的时间戳
connection Connection 设备的连接状态
rssi NSInteger 设备的RSSI
uuids NSDictionary 设备的读写服务UUID
infos NSDictionary 设备信息**

*:由于iOS系统限制,应用层无法获取到设备的Mac地址,所以只能以此id来代替mac地址作为识别码,需要注意的是,即使是同一个设备,每次重新扫描数据时,它的identifier都是不一样的。

**:仅部分设备支持获取设备信息,为空即为不支持。

注意事项

  1. 如果添加 SDK 之后,运行显示无法找到路径,可以在 General -> Frameworks,Libraries,and Embedded Content ,把包删除再重新添加一次即可。

  2. 如果运行 SDK 之后,项目发生闪退,错误为 **Reason: image not found** , 可在 General -> Frameworks,Libraries,and Embedded Content ,查看设置是否正确。

    Tips_1

文档版本记录

  • v1.0 初版;
  • 2021.02.01 v1.1 修复错误的 log 打印 ;
上次更新:: 2021/2/2 下午4:04:41