  sidebar: auto

## MinewESLKit说明文档

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

### 前期工作

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

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

**MTPeripheral**：设备实例类，当MTCentralManager发现一个物理设备时，MTCentralManager会生成一个MTPeripheral实例，这个实例就对应一个物理设备。

**MTBroadcastHandler**：设备广播类，可以获取设备广播时的数据。

**MTConnectionHandler**：设备连接类，进行设备的接发数据。

**MTUtils**：设备验证，以及数据处理。

### 开始上手

##### 开发环境：

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

##### 导入到工程：

1. 将开发套件的三个framework文件：MinewESLKit.framework, iOSDFULibrary.framework, Zip.framework拷贝到项目工程目录下，然后添加到项目中。
2. 如果添加SDK之后，运行显示无法找到路径，可以在 General -> Frameworks,Libraries,and Embedded Content ，把包删除再重新添加一次即可。

PS:

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

#### 开始开发

##### 扫描设备

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

```objective-c
// 获取Manager单例
MTCentralManager *manager = [MTCentralManager sharedInstance];

dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
    // 手机端当前的蓝牙开关状态
    if(self->manager.status == PowerStatePoweredOn) {
        // 开始进行设备扫描
        [manager startScan:^(NSArray<MTPeripheral *> *devices) {
        	self->deviceAry = devices;
    	}];
    }
});
//扫描到的设备也可以使用manager.scannedPeris获得

// 如果你需要对手机的蓝牙状态作出响应。请监听回调。
[manager didChangesBluetoothStatus:^(PowerState status){
    
    switch(status) {
        case PowerStatePoweredOn:
            NSLog(@"bluetooth status change to poweron");
            break;
        case PowerStatePoweredOff:
            NSLog(@"bluetooth status change to poweroff");
            break;
        case PowerStateUnknown:
            NSLog(@"bluetooth status change to unknown");
    }
}];
```

**PS: 只有手机蓝牙状态处于Poweron时，整个SDK才能够正常工作。**

##### 连接到设备

```objective-c
// 从上一步能够获取到扫描到的设备
MTPeripheral *device = deviceAry[0];
//连接设备
[manager connectToPeriperal:device];
// 监听设备连接状态。
[p.connector didChangeConnection:^(Connection connection) {
    if (connection == Vaildated) {
      	//验证成功，成功连接设备
        NSLog(@"vaildated");
    }
    if (connection == Disconnected) {
        NSLog(@"device has disconnected.");
    }
}];
```

##### 向设备写入数据

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

1. 写入数据

   ```objective-c
   [self->_per.connector writeData:data completion:^(BOOL success, NSError * _Nonnull error) {
       if (error) {
           NSLog(@"write data failed:%@",error);
       }
       else {
           NSLog(@"write data success");
       }
   }];
   ```
   
2. 接收数据

   ```objective-c
   [_per.connector didReceiveData:^(NSData * _Nonnull data) {
       if (data) {
           NSLog(@"receive data success:%@",data);
        }
        else {
           NSLog(@"receive data failed");
        }
       }
   }];
   ```


### 附表

##### MTCentralManager 属性说明

|     名称     |    类型    |        备注        |
| :----------: | :--------: | :----------------: |
|    status    | PowerState | 当前的手机蓝牙状态 |
| scannedPeris |  NSArray   |    扫描到的设备    |

##### MTPeripheral属性说明

|    名称    |        类型         |       备注       |
| :--------: | :-----------------: | :--------------: |
| identifier |      NSString       | 设备的Identifier |
| broadcast  | MTBroadcastHandler  |  广播类实例对象  |
| connector  | MTConnectionHandler |  连接类实例对象  |

##### MTBroadcastHanler属性说明

|       名称        |   类型    |       备注       |
| :---------------: | :-------: | :--------------: |
|       name        | NSString  |  设备的蓝牙名称  |
|       rssi        | NSInteger |    设备的RSSI    |
|        mac        | NSString  |  设备的Mac地址   |
|    identifier     | NSString  |   设备的识别码   |
|    firmVersion    | NSString  |  设备固件版本号  |
|  hardwareVersion  | NSString  |  设备硬件版本号  |
|    screenInfo     | NSString  |  设备的屏幕信息  |
|      battery      | NSString  |    设备的电压    |
|     chipTemp      |  double   |   设备芯片温度   |
|     heartbeat     | NSString  |     设备心跳     |
|      tagRssi      | NSString  |     设备RSSI     |
|     chipInfo      | NSString  |   设备芯片信息   |
|    imageIdData    |  NSData   | 设备的刷图数据ID |
|     errorCode     | NSInteger |    设备错误码    |
| peripheralSupport | NSString  | 设备广播触发类型 |

##### MTConnectionHandler属性说明

|    名称    |    类型    |     备注     |
| :--------: | :--------: | :----------: |
| macString  |  NSString  | 设备Mac地址  |
| connection | Connection | 设备连接状态 |



# 注意事项：

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

2. MinewESLKit包含双版本，如下图：
   其中，文件中包含x86&ARM字样的（以下简称x86&ARM，也就是上图中的第二个zip文件）表示此开发包同时支持在模拟器和物理真机情况下调试，文件中仅仅包含ARM字样的（以下简称"ARM",也就是上图中的第一个zip文件）表示此开发包仅仅支持物理真机调试及发布。

   !!! 当发布基于此开发套件的APP时，必须使用"ARM"。

   此次更新是因为苹果更新了APPStore的接收策略，可能导致开发者无法上传含有x86_64二进制代码的应用。所以保险起见，在上传至APPStore时请使用"ARM"打包。

![image-20200825100526893](/Users/minew/Library/Application Support/typora-user-images/image-20200825100526893.png)

# 文档版本记录

* 2020.03.03  v1.0 初版；
* 2020.08.25  v1.01 