MinewModuleKit说明文档 | 移动SDK文档

# MinewModuleKit说明文档

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

# 前期工作

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

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

设计说明

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

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

# 开始上手

# 开发环境：

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

# 导入到工程：

# CocoaPods

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

pod 'MTModuleKit'

# 手动导入

将开发套件的framework文件：MTModuleKit.framework拷贝到项目工程目录下，然后添加到工程中，target为当前的工程，然后点“Add”，如下图所示：
1. 依次找到：“Target” -> General -> Embedded Binaries，点击下面的“+”，继续点击“Add Other”将MTTrackit.framework文件添加进来。同样的，也需要添加到 ”Linked Frameworks and Libraries“，添加完应该如下图：

frameworkadded

*如果使用Swift开发，需要添加一个Objective C BridgingHeader .h文件（此处不再赘述），并且在此文件添加：import ，如果使用Objective C进行开发，在需要的文件的顶端添加：import
!!!在iOS10及以上版本，苹果对蓝牙APi添加了权限限制，你需要在工程的info.plist文件里添加一项字符串：Privacy - Bluetooth Peripheral Usage Description - "你的使用描述"。如下图所示：

bluetoothdescription

!!!在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都是不一样的。

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

# 注意事项

如果添加 SDK 之后，运行显示无法找到路径，可以在 General -> Frameworks,Libraries,and Embedded Content ，把包删除再重新添加一次即可。
如果运行 SDK 之后，项目发生闪退，错误为 **Reason: image not found** , 可在 General -> Frameworks,Libraries,and Embedded Content ，查看设置是否正确。

# 文档版本记录

v1.0 初版；
2021.02.01 v1.1 修复错误的 log 打印 ;