信标Plus SDK

# BeaconPlus iOS Software Development Kit Guide

**Updating…**

This SDK only support devices based on miniBeaconPlus firmware, 它与以前的设备不兼容, 例如 iBeacon, 涡流石等. BeaconSET+ SDK 支持比 BeaconSET SDK 更多的功能. 我们在开发过程中遇到了一些问题, 所以, please read this document carefully in order to help you get started as soon as possible. 同时, 本文件还将提供说明和问题.

请阅读本文档中您需要的部分, 部分 1 我们将解释这个SDK的架构, 部分 2 将帮助开发人员入门, 部分 3 将解释您开发进度中的注释, 部分 4 您可以获得错误代码和描述.

## Design instructions

We divide the communications between SDK and devices into two stages: 扫描阶段, 连接阶段. 为了便于理解, 我们先看一下相关的类以及它们之间的关系.

**MTCentralManager:** 全球经理, 检查系统的蓝牙状态, 监听状态变化, 最重要的是扫描并连接到设备;

**MTP外设:** 设备实例, MTCentralManager 在找到物理设备时将创建一个 MTPeripheral 实例, 一个设备对应一个实例. 每个 MTPeripheral 实例都有一个 MTFrameHandler 属性和一个 MTConnectionHandler 属性(下面解释这两个属性);

**MT帧处理程序:** 广告框架分析, 它可以分析设备广告数据中的所有帧. 换句话说, 它是扫描阶段的核心;

**MT连接处理程序:** 连接操作员. 该类控制设备在连接阶段的所有操作.

**MT传感器处理器:** 传感器操作员, 该类控制设备在连接阶段的所有传感器操作.

\*\*米新框架:\*\*数据框, 每个我的框架(或子类) 实例对应一个数据框, 通常由 "MT帧处理程序", 如果设备通告多个数据帧(例如 iBeacon, 用户识别码, 网址) "MT帧处理程序" 会创建多个对应的MinewFrame实例.

**MTOTA管理器:** 在线旅行社, 仅使用此类来更新设备的固件.

## 整体结构

![信标SET+](/资源/sdksimg/BeaconSET+.3b64ceba.png)

#### Advertisement Stage

in this stage, **MTCentralManager**将扫描并分析miniBeaconPlus设备的广告数据, **MTCentralManager** 将创建 **"MTP外设"** 每个物理设备的实例, 开发者可以通过其**MTFrameHandler**属性获取所有广告数据.

#### Connection Stage

After a **MTPeripheral** connected, 开发者可以通过**MTConnectionHandler**对设备进行一些更改(**MTPeripheral** 实例的属性).

#### OTA Operations

In general, OTA操作复杂, 所以我们封装**MTOTAManager**来执行固件更新操作, 请注意，开发者只能在连接状态下更新设备.

## 开始使用

### 准备

#### 开发环境:

-   **Xcode9+**， due to the DFU and Zip Framework based on Swift4.0, so please use Xcode9 or high version to develop;
-   **iOS8**, we limit the minimum iOS system version to 8.0;

### 导入到项目

#### Manually

1.  copy the framework files to your project folder，include **"MTBeaconPlus.framework"**, **"iOSDFULibrary.framework"**, **"Zip.framework"**, then add them to your project, make sure the **"target"** is checked. as the screenshot below: ![add frameworks](/resources/sdksimg/add_frameworks.8a932d1c.png)
    
2.  find: **"Target"** -> **General** -> **Embedded Binaries**, click the **"+"** 以下, add that 3 framework files. 同时, make sure add them to **"Linked Frameworks and Librarys"**, as the screenshot blew:
    
    ![make sure frameworks](/resources/sdksimg/make_sure_frameworks.d4466176.png)
    
3.  \*about using swift, the developer should add a **"Objective C BridgingHeader.h"** file to the project(please do this by yourself), 然后添加 **"import < MTBeaconPlus/MTBeaconPlus.h >"** to the file.
    
4.  \*using Objective-C, find: “Target” -> Building Settings -> Always Embed Swift Standard Libraries" ,then set yes
    
5.  !!!on iOS 10 及以上, Apple add authority control of bluetooth, you need add the string to "info.plist" file of your project: _Privacy - Bluetooth Peripheral Usage Description_ - _"your description"_. as the screenshot below.
    
    ![bp_access](/resources/sdksimg/bp_access.795e088e.png)
    
    6.  !!! In iOS13 and above, Apple added permission restrictions on Bluetooth APi. You need to add a string to the project's info.plist file: Privacy-Bluetooth Always Usage Description-"Your usage description".

### 开始开发

##### Get sharedInstance of Manager

First of all, 开发者应该获取Manager的sharedInstance:

```c
// get sharedInstance
MTCentralManager *manager = [MTCentralManager sharedInstance];

// 听听iPhone蓝牙的变化
// *** 也从 "状态" 财产.
// *** 仅当 state == PowerStatePoweredOn 时，此 SDK 才能正常工作!
manager.stateBlock = ^(PowerState state) {
     NSLog("current bluetooth state：%d",状态);
};
````

##### Scan devices

start scanning task to find devices around you, 然后你就可以得到他们的广告内容, connect to device and change parsameters.

```c
/*
  manager: MTCentralManager 的共享实例
*/

// start scanning task
[manager startScan:^(NSArray<MTPeripheral *> *peris){
  
   // Traverse the array，获取每个设备的实例.
   // ** 您还可以在视图上显示它们.
    为了(NSInteger i = 0; 我 < peris.count; 我 ++){
        MTPeripheral *peri = peris[我];
        
        // 获取设备的FrameHandler.
        // **some properties maybe nil
        MTFrameHandler *framer = peri.framer; 
        NSString *name = framer.name;          // name of device, may nil
        NSInteger rssi = framer.rssi;          // rssi
        NSInteger battery = framer.battery;    // 电池,may nil
        NSString *mac = framer.mac;            // mac地址,may nil
        NSArray *frames = framer.advFrames;    // 设备的所有数据帧（如:信标，用户识别码，URL...）
    }
}];

```

at the sometime, 您可以通过这种方式停止扫描任务:

```c
/*
  manager: MTCentralManager 的共享实例
*/

// stop the task.
[manager stopScan];
```

now the developer can get all advertisement data of device in this way. 下一个, 我们将讨论如何获取帧数据, 例如 **iBeacon**, **网址**, **UID**等。.

请参考下面的代码示例.

```c
/*
  aFrameHandler: MTFrameHandler 实例.
*/

NSArray *frames = aFrameHandler.advFrames;
为了 (NSInteger i = 0; 我 < frames.count; 我 ++){
    MinewFrame *frame = frames[我];
    
    转变(frame.frameType){
      案例框架iBeacon:
        {
          MinewiBeacon *bea = (MinewiBeacon *)frame;
          NSLog(@"信标:%@, %ld, %ld, %@",bea.uuid, bea.major, bea.minor, bea.lastUpdate);
        }
           休息;
        
      案例框架UID:
        {
           MinewUID *uid = (MinewUID *)frame;
           NSLog(@"用户识别码:%@, %@, %ld, %@", uid.namespaceId, uid.instanceId, uid.txPower, uid.lastUpdate);
        }
           休息;
        
        case FrameDeviceInfo:
        {
            MinewDeviceInfo *info = (MinewDeviceInfo *)frame;
            NSLog(@"DeviceInfo: %ld, %@, %@, %@", (long)info.battery, info.mac, info.name, info.lastUpdate);
        }
            休息;
        
        案例框架TLM:
        {
            MinewTLM *tlm = (MinewTLM *)frame;
            NSLog(@"TLM: %ld, %f, %ld, %ld, %@", tlm.batteryVol, tlm.temperature, tlm.advCount, (long)tlm.secCount, tlm.lastUpdate);
        }
            休息;
        
        案例框架URL:
        {
            MinewURL *url = (MinewURL *)frame;
            NSLog(@"网址: %ld, %@, %@", url.txPower, url.urlString, url.lastUpdate);
        }
            休息;
        
        案例框架线信标:
        {
            MinewLineBeacon *lineBeacon = (MinewLineBeacon *)frame;
            // If necessary, vendorKey and lotKey can be obtained after the connection by other operations. For details, refer to the section "Getting the data of each channel".
            NSLog(@"LineBeacon:%@, %@, %@, %ld, %@", lineBeacon.hwId, lineBeacon.authenticationCode, lineBeacon.timestamp, lineBeacon.txPower, lineBeacon.lastUpdate);
        }
            休息;
                    
      /*
         You can handle other types of data if you need to. 
      */
    }
}

```

**Important:** 适用于所有类型的传感器值, if it equals to _MTNAValue_（a not available value we defined, in file "MTPublicHeader.h"), 这意味着该值不可用.

请参考下面的代码示例:

```c
/*
    aHT: a MinewHTSensor instance
    aLight: a MinewLightSensor instance
    aAcc：a MinewAccSensor instance
*/

如果 (aHT.temperature == MTNAValue) {
    NSLog(@"该值不可用。")
}

如果 (aLight.luxValue == MTNAValue) {
    NSLog(@"该值不可用。")
}

如果 (aAcc.XAxis == MTNAValue) {
    NSLog(@"该值不可用。")
}
````

##### Connect to device

Connect to the device in order to do more operations(改变参数, 在线旅行社). 你会发现当连接到设备时可能需要密码, so **the "password Validating Block" must not be NULL, otherwise the app will crash!!!!**

请参考下面的代码示例.

```c
/*
  manager： a MTCentralManager sharedInstance
  aMTPeripheral： 一个 MTPeripheral 实例
*/

// listen the change of device connection state
aMTPeripheral.connector.statusChangeHandler = ^(ConnectionStatus status, NSError *error) {
    
    /*
     typedef NS_ENUM(NSInteger, ConnectionStatus) {
         StatusConnectFailed = -2,
         StatusDisconnected = -1,
         StatusUndifined = 0,
         StatusConnecting,
         StatusConnected,
         StatusReadingInfo,
         StatusDeviceValidating,
         StatusPasswordValidating,
         StatusSycingTime,
         StatusReadingConnectable,
         StatusReadingFeature,
         StatusReadingFrames,
         StatusReadingTriggers,
         StatusReadingSensorInfo,
         StatusCompleted,
     };
     */
     
    /*
     连接设备时有多种状态,
     仅有的 "状态 == 状态已完成" 表示连接操作成功.
     如果出现异常, 错误不会为NULL
    */
    
};

// Connect to the device
// the aMTPeripheral is a device instance
// !!!:警告: 密码要求不能为 NULL!!!
[manager connectToPeripheral:aMTPeripheral passwordRequire:^(MTPasswordBlock passwordBlock){
     // 密码字符串的长度必须是 8.
    // !!! read the input content from the UITextField as a password in development.
    NSString *password = @"米尼乌123";
    passwordBlock(密码);
}];

// 断开与设备的连接.
[manager disconnectFromPeriperal:aMTPeripheral];
````

##### Get base information

the developer can get device information and modify parameters when a device connected.

下面的代码示例让开发人员获取设备的基本数据.

```c
/*
   aMTPeripheral：一个 MTPeripheral 实例
*/

MTConnectionHandler *con = aMTPeripheral.connector;

ConnectionStatus conSte = con.status;  // current connection status
NSDictionary *infoDict = con.infoDict; // 设备信息, 例如：（固件版本： 0.9.1）;
NSString *mac = con.macString; // mac地址；
Connectable able = con.connectable; // device connectable，None Unknown，No disable，Yes enable
Version version = con.version; // 固件版本；
PasswordStatus pwdStatus = con.passwordStatus; // 是否需要密码. 没有任何, Require

MTConnectionFeature *feature = con.feature; // device features
NSInteger slotAtitude = feature.slotAtitude; // 槽位角(s), 
FeatureSupported feaSup = feature.featureSupported; // 参数可修改：没有任何，副词,发射功率,adv/txpower
NSArray<NSNumber *> *supFrames = feature.supportedSlots; // frames supported（multiple）
NSArray<NSNumber *> *supTxpower = feature.supportedTxpowers; // Txpower supported（multiple）
```

**PS:** **MTConnectionHandler** 的 _Version_ 属性.

```c
The version value comes form firmware version， 检查版本值以了解设备支持的功能:
 
// init value
VersionUndefined

// 基础版本, 仅基函数.
版本库

// 此版本及以上支持自定义连接密码和设备信息框.
版本0_9_8

// 此版本及以上支持远程关机.
版本0_9_9

// 此版本或以上支持触发器.
版本2_0_0

// 此版本或更高版本支持使用 adv 配置触发.
版本2_2_60

// 理想值, 支持所有功能.
最大版本 = 1000
````

##### Get data of each Slot

Next, 说一下每个槽位的参数数据, 之所以讲这个，是因为所有改变参数的内容都在这里.

**投币口** :在阅读代码之前, 我们来谈谈插槽, 您可以将老虎机视为广告工具, 它甚至对广告数据的内容进行广告 "不知道" 内容是什么. 例如 6 老虎机可能会喜欢这个:

| 槽位号 | 0 | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- | --- |
| 广告内容 | 信标 | TLM | 用户识别码 | 网址 | HT传感器 | 没有任何 |
| 提前间隔（ms） | 1000 | 2000 | 500 | 900 | 3000 | 0 |
| RSSI@0/1m（dbm） | \-1 | 0 | \-4 | \-10 | \-3 | 0 |
| 发射功率（dbm） | 4 | 0 | \-4 | 4 | 0 | 0 |

根据表的含义, **没有.0** 插槽将公布 **iBeacon** 数据, **No.1** 插槽将广告 **TLM** 数据, ……, **No.5** 插槽不会通告任何数据. 他们每个人都有自己的**广告间隔**, **Txpower** 和 **校准 RSSI**. 他们是相互独立的.

聚苯乙烯: **校准RSSI(RSSI@0/1m)** 是设备@ 0/1m时的RSSI(iBeacon 是 1, 其他的 0).

如何获取老虎机广告数据? 请参考下面的代码示例.

```c
/*
    con: MTConnectionHandler 实例
*/

// 每个槽都有一个当前设备的框架.
// atitude of this array is equals to slot atitude(feature.slotAtitude)
// 
// 严格按照槽位顺序，例如：0. -> MinewiBeacon，1. -> MinewUID ...
NSArray<MinewFrame *> *frames = con.allFrames;

/*
   我们假设3号槽有iBeacon数据, 4号槽有UID数据.
   我们来尝试分析一下3号槽位的数据.
*/

// due to the defualt point is MinewFrame(MinewiBeacon 的超类), 所以我们需要进行转换.

// get the frame of No.3 slot
MinewFrame *frame = frames[2];

// 检查此插槽是否有 iBeacon 数据,
// *如果确认其类型则无法检查.
为了 (NSInteger i = 0; 我 < frames.count; 我 ++){
MinewFrame *frame = frames[我];

转变 (frame.frameType) {
案例框架iBeacon:
{
    MinewiBeacon *iBeacon = (MinewiBeacon *)frame;

// iBeacon
    NSString *uuid = iBeacon.uuid;   // uuid
    NSInteger major = iBeacon.major;  // major
    NSInteger minor = iBeacon.minor;  // 次要的

// The parameters of the slot
    NSInteger slotNumber = iBeacon.slotNumber;           // number of the slot
    NSInteger slotAdvInterval = iBeacon.slotAdvInterval; // advertisement interval
    NSInteger slotAdvTxpower = iBeacon.slotAdvTxpower;   // 信标：RSSI@1m others： RSSI@0m
    NSInteger slotRadioTxpower = iBeacon.slotRadioTxpower; // 无线电发射功率  
}
    休息;
    
案例框架URL:
{
    // URL
    MinewURL *url = (MinewURL *)frame;
    NSString *urlStr = url.urlString;
    
    // The parameters of the slot are obtained in the same way
}
    休息;
    
案例框架UID:
{
    // UID
    MinewUID *uid = (MinewUID *)frame;
    NSString *namespaceId = uid.namespaceId;
    NSString *instanceId = uid.instanceId;
    
    // The parameters of the slot are obtained in the same way
}
    休息;

案例框架线信标:
{
    // LineBeacon(The acquisition method is special)
    MTLineBeaconData *lineBeaconData = self.currentPeripheral.connector.slotHandler.slotFrameDataDic[FrameTypeString(帧线信标)];
    NSString *hwid = lineBeaconData.hwId;
    NSString *vendorKey = lineBeaconData.vendorKey;
    NSString *lotKey = lineBeaconData.lotKey;
    
    // The parameters of the slot are obtained in the same way
}
    休息;
/*
   You can handle other types of data if you need to. 
*/
默认:
    休息;
}
```

You can analyze the data of other slots in the same way, 值得注意的是，当**frameType == FrameNone**时表示该槽没有数据: 从另一个角度来说，这意味着这个槽被关闭了.

##### Change slot data

The developer can modify advertisement and parameters of every slot freely via our APi.

我们将数据帧分为**静态帧**和**动态帧**:

-   **静态框架**: 广告数据在广告时不会改变, 例如 **iBeacon**, **UID**, **网址**
-   **动态框架**: 广告数据在广告期间会发生变化, 例如**TLM**, **Sensor**

Please refer to the code example below:

```c
/*
   aConnectionHandler:MTConnectionHandler 实例
*/

// create a uid instance
MinewUID *uid = [[MinewUID alloc]init];

// 放 "命名空间ID" 和 "实例ID" of UID
uid.namespaceId = @"0123456789abdcdcba12";
uid.instanceId = @"0123456789直流电";

// the other parameters of slot
uid.slot = 1;  // The number of slot which you want to modify
uid.slotAdvInterval = 600;  // advertisement interval
uid.slotAdvTxpower = -3;    // RSSI@0m
uid.slotRadioTxpower = 4;   // 无线电发射功率.

// 写入设备.
// 细节: 1.让1号槽广告UID数据, 命名空间ID：0123456789abdcdcba12 实例 ID：0123456789直流电
//         2.设置1号槽位通告间隔为600ms, RSSI@0m 至 -3dbm, radio txpower to 4dbm 
[aConnectionHandler writeFrame:uid completion:^(BOOL success, NSError *error){
     如果 (成功) {
        NSLog(@"write frame to device successfully.");   
     } 
     否则如果(error) {
        NSLog(@"Error:%@", error)
     }
}];
```

Becareful, 槽参数有范围:

-   **广告间隔**: 100 - 5000 (多发性硬化症)
-   **RSSI@0m**: -127 - 0 (数据库管理)

**The most import**: 无线电 txpower 不是一个范围, 这是等级, 例如: -8, -4, 0, 4. 您可以从功能属性中获取所有支持的无线电 Txpowers "MT连接处理程序"

```c
/*
   feature: MTConnectionHandler 的属性.
*/

// 获取当前设备所有支持的Radio txpower.
NSArray<NSNumber *> *supTx = feature.supportedTxpowers
```

OK, 您可以按照上面的方式修改任何插槽, 如果你想关闭一个插槽, 只需要创建一个**MinewFrame**实例并将其**frameType**属性设置为**FrameNone**, 然后将此帧写入设备. 哦，不要忘记为要关闭的插槽设置插槽编号.

##### Set lineBeacon

The LineBeacon frame needs to call writeFrame method, and then the following two methods are called to set the lineBeacon's hwid, 供应商密钥, and lotKey.

```c
// 抽签密钥:Length of 16, 哈维德:Length of 10,vendorKey:Length of 8，include a-f/A-F/0-9.

// set LineBeacon's lotKey
[self.currentPeripheral.connector.slotHandler lineBeaconSetLotkey:@"0011223344556677" completion:^(BOOL success) {
    如果 (成功) {
        NSLog(@"Set LineBeacon's lotKey success");
    } 别的 {
        NSLog(@"Set LineBeacon's lotKey failed");
    }
}];

// set LineBeacon's hwid LineBeacon's vendorKey
[self.currentPeripheral.connector.slotHandler lineBeaconSetHWID:@"0011223344" VendorKey:@"00112233" completion:^(BOOL success) {
    如果 (成功) {
        NSLog(@"Set LineBeacon's hwid and vendorKey success");
    } 别的 {
        NSLog(@"Set LineBeacon's hwid and vendorKey failed");
    }
}];

````

##### Change global parameter

Global parameter of device is a device level feature, 比如可以连接的, 需要密码, 重置为默认值等.

请参考下面的代码示例.

```c
/*
   aConnectionHandler: MTConnectionHandler 实例
*/
// reset the device
[aConnectionHandler resetFactorySettings:^(BOOL success, NSError *error){
    如果(成功){
        NSLog(@"Operation success!");
    }
    别的 {
        NSLog(@"Opertion failed!");
    }
}];

// 更新可连接设置
// ConnectableYES: 应用程序可以连接到设备, ConnectableNO app can't connect to the device.
// if you set connectableNO, 您可以通过按下设备上的按钮来连接到设备，也许下次.
// 危险!!!:if there is no button on device and set ConnectableNO, 该应用程序甚至永远无法连接到设备.
[aConnectionHandler updateConnectable:ConnectableYES completion:^(BOOL success, NSError *error){
    如果(成功){
        NSLog(@"Operation success!");
    }
    别的 {
        NSLog(@"Opertion failed!");
    }
}];

// 修改/添加密码
// !!!: 密码字符串长度必须是 8, 数字或字母；
// 如果设备没有密码，它会添加密码, update password if device has a password
[aConnectinoHandler modifyPassword:@"12345678" completion:^(BOOL success, NSError *error){
    如果(成功){
        NSLog(@"Operation success!");
    }
    别的 {
        NSLog(@"Opertion failed!");
    }
}];

// remove password
[aConnectionHandler removePassword:^(BOOL success, NSError *error){
    如果(成功){
        NSLog(@"Operation success!");
    }
    别的 {
        NSLog(@"Opertion failed!");
    }
}];

// 远程关闭设备.
// 危险!!!: 请确保设备上有按钮, otherwise it may not boot again.if the Model Number String is Beacon Plus-BL,not work.
[aConnectionHandler poweroff^(BOOL success, NSError *error){
    如果(成功){
        NSLog(@"Operation success!");
    }
    别的 {
        NSLog(@"Opertion failed!");
    }
}];
````

##### Sensor data

BeaconPlus devices integrated a variety of sensors: **HT(温度和湿度 )**, **光**, **加速度**等, currently we provide APi for read HT/Sixaxis/Magnetometer/AtmosphericPressure History data and set PIR param data.

Please make sure the device has **HT Sensor**, 否则无法正确获取数据.

请参考下面的代码示例.

```c
/*
   aConnectionHandler: MTConnectionHandler 实例
*/

// read HT History from the device
[aConnectionHandler.sensorHandler readSensorHistory:^(MTSensorData *data){
  
   // a record corresponds to an instance
   NSInteger time = ((MTSensorHTData *)数据).timestamp;   // the Unix timestamp；
   double temp = ((MTSensorHTData *)数据).温度;    // temperature data；
   double humi = ((MTSensorHTData *)数据).湿度;       // humidity data；
   NSInteger index = ((MTSensorHTData *)数据).指数;      // number of this data；
  
   如果 (((MTSensorHTData *)数据).endStatus == EndStatusNone){
       NSLog(@"there is no data.");
   }
   否则如果 (((MTSensorHTData *)数据).endStatus == EndStatusSuccess) {
       NSLog(@"sensor data sync successfully!");
   }
   否则如果 (((MTSensorHTData *)数据).endStatus == EndStatusError) {
       NSLog(@"something wrong in syncing progress.");   
   }
}];
```

you can vividly display these data with the curve, 桌子或其他.

Please make sure the device has **PIR Sensor**, 否则无法正确获取数据.

请参考下面的代码示例.

```c
/*
   aConnectionHandler: a MTConnectionHandler instance
   aRepeat: 一个布尔值,whether to allow repeated triggers
   aTime:触发时间, the infrared sensor can be triggered again after the trigger time
*/

// set PIR param to the device
[aConnectionHandler.sensorHandler pirSet:aRepeat andDelayTime:aTime completion:^(MTSensorData *data){
   
    如果 (data.status) {
        NSLog(@"成功");
    }
    别的 {
        NSLog(@"failed");
    }
}];
````

##### Set triggers

BeaconPlus device has triggers, 您可以为每个插槽设置触发器, 只有满足触发条件，设备才会通告对应的slot.

请参考下面的代码示例.

```c
/*
   aConnectionHandler: MTConnectionHandler 实例
*/

NSInteger sn = 2;                          // 目标槽位：2
TriggerType type = TriggerTypeTempAbove;   // 触发条件：temperature above
NSInteger value = 10;                      // 价值：10

// create a trigger instance
// this trigger means when temperature > 10 meet the condition.
MTTriggerData *trigger = [[MTTriggerData alloc]initWithSlot:sn triggerType:type value:价值];

// write to the device.
[aConnectionHandler writeTrigger:trigger completion:^(BOOL success, NSError){
    如果(成功){
        NSLog(@"write trigger successfully!");
    }
    别的 {
        NSLog(@"write trigger failed!");
    }
}];

NSInteger slotAtitude = 2;                 // 目标槽位：2
TriggerType type = TriggerTypeTempAbove;   // 触发条件：temperature above
NSInteger value = 10;                      // temperature above：10

// create a trigger instance
// this trigger means when temperature > 10 meet the condition.
MTTriggerData *trigger = [[MTTriggerData alloc] initWithSlot:slotAtitude paramSupport:true triggerType:type value:价值];

// Continue broadcasting after triggering if necessary
trigger.always = true;        // Whether to continue broadcasting after triggering
trigger.advInterval = 100;    // The broadcast interval
trigger.radioTxpower = -20;   // The broadcast signal strength

// write to the device.
[self.connectedPeripheral.connector writeTrigger:trigger completion:^(BOOL success) {
    如果(成功){
        NSLog(@"write trigger successfully!");
    }
    别的 {
        NSLog(@"write trigger failed!");
    }
}];

```

Set and query whether the vibration is turned on, the broadcast frame of the vibration sensor will be received when the vibration is turned on, and the broadcast frame of the vibration sensor will not be broadcast when the vibration is turned off.

```c
   
 //    MTVibrationTypeOpen,
//    MTVibrationTypeClose,
//    MTVibrationTypeError,
  [self.currentPeripheral.connector.sensorHandler setVibrationStatus:MTVibrationTypeOpen CompletionHandler:^(BOOL isSuccess) {

}];

[self.currentPeripheral.connector.sensorHandler queryVibrationStatu:^(BOOL isSuccess, MTVibrationType type) {

}];
```

Set and query the sensitivity of the vibration sensor.

```c
    //    MTSensitivityTypeSuperHigh,
    //    MTSensitivityTypeHigh,
    //    MTSensitivityTypeMiddle,
    //    MTSensitivityTypeLow,
    //    MTSensitivityTypeSuperLow,
    [self.currentPeripheral.connector.sensorHandler setSensitivity:MTSensitivityTypeHigh CompletionHandler:^(BOOL isSuccess) {
        
    }];

[self.currentPeripheral.connector.sensorHandler querySensitivity:^(BOOL isSuccess, MTSensitivityType type) {
        
    }];
```

Set and query the vibration sensor warning time interval. The start time must be less than the end time, accurate to the hour and minute. 此外, the parameters need to be calculated. 例如, 从 6:10 in the morning to 10:00 in the evening, startTime = 6 \* 3600 + 10 \* 60 = 22200, endTime = 22 \* 3600 + 0 \* 60 = 79200.

```c
    // timeZone = hours*3600 + minutes*60
    // 22200 = 6*3600 + 10*60 = 6:30
    [self.currentPeripheral.connector.sensorHandler setFirstAlarmTimeIntervalWithAlarmStatus:MTVibrationTypeOpen StartTime:22200 EndTime:79200 CompletionHandler:^(BOOL isSuccess) {
        
    }];
    
    [self.currentPeripheral.connector.sensorHandler queryFirstAlarmTimeInterval:^(BOOL isSuccess, MTVibrationType type, uint32_t startTime, uint32_t endTime) {
        NSLog(@"vibrationType:%@, 开始时间:%dhour %dminute, 结束时间:%dhour %dminute", type == MTVibrationTypeOpen ? @"Open" : @"Close or Error", startTime/3600, startTime%3600/60, endTime/3600, endTime%3600/60);
    }];
    
    [self.currentPeripheral.connector.sensorHandler setSecondAlarmTimeIntervalWithAlarmStatus:MTVibrationTypeOpen StartTime:22200 EndTime:79200 CompletionHandler:^(BOOL isSuccess) {
        
    }];
    
    [self.currentPeripheral.connector.sensorHandler querySecondAlarmTimeInterval:^(BOOL isSuccess, MTVibrationType type, uint32_t startTime, uint32_t endTime) {
        
    }];
    
    [self.currentPeripheral.connector.sensorHandler setThirdAlarmTimeIntervalWithAlarmStatus:MTVibrationTypeOpen StartTime:22200 EndTime:79200 CompletionHandler:^(BOOL isSuccess) {
        
    }];
    
    [self.currentPeripheral.connector.sensorHandler queryThirdAlarmTimeInterval:^(BOOL isSuccess, MTVibrationType type, uint32_t startTime, uint32_t endTime) {
        
    }];
````

### Set broadcast rate

When the model is MBM01 and the firmware version is 2.5.x, you can set the Bluetooth 4.0 1Mbps broadcast rate or Bluetooth 5.0 125Kbps broadcast rate for the frame channel.

Each of the six broadcast channels occupies a value. When the value is set to 0, it represents the Bluetooth 4.2 1Mbps broadcast mode, and when the value is set to 1, it represents the Bluetooth 5.0 125Kbps broadcast mode.

\*\*It should be noted that iOS currently cannot obtain the radio package with a radio frequency of 125Kbps, and Android does not have this problem. 那是, the frame channel of the Bluetooth 5.0 broadcast rate is set to 125Kbps on iOS. After the setting is completed, the frame cannot be scanned on the iPhone, but the frame can be scanned on the Android. \*\*

```c
    [self.currentPeripheral.connector.sensorHandler queryBroadcastSpeed:^(BOOL isSuccess, NSArray * _Nonnull broadcastSpeedOfSlotArray) {
        NSLog(@"The broadcast rate of the first channel is %@", [broadcastSpeedOfSlotArray[0] 整数值] == 1 ? @"Bluetooth5.0 125Kbps" : @"Bluetooth4.0 1Mbps");
    }];
    
    // When setting the broadcast rate, the incoming array has six values, and each value corresponds to six channels. 0 means that the broadcast rate of Bluetooth 4.0 is 1Mbps, 和 1 means that the broadcast rate of Bluetooth 5.0 is 125Kbps. 例如, if the first and second channels are set to 125Kbps broadcast, and the other channels are set to 1Mbps broadcast, then the settings are as follows:
    [self.currentPeripheral.connector.sensorHandler setBroadcastSpeed:@[@1,@1,@0,@0,@0,@0] CompletionHandler:^(BOOL isSuccess) {
        
    }];
````

### Set the parameter configuration items of the configurable firmware of the Acc sensor

This function belongs to the exclusive supporting function of customized firmware, please consult relevant business personnel before using it.

Acc sensor can be configured with firmware and parameter configuration items that can be set.

ODR ( Output rate ) :

| description | 价值 |
| --- | --- |
| 1赫兹 | 0 |
| 10赫兹 | 1 |
| 25赫兹 | 2 |
| 50赫兹 | 3 |
| 100赫兹 | 4 |
| 200赫兹 | 5 |
| 400赫兹 | 6 |
| 1600Hz（low power） | 7 |
| 1344HZ (HR/normal) /5000HZ(低功率) | 8 |

wakeup\_threshold ( mg ) : 0 ～ 2000

wakeup\_duration ( 多发性硬化症 ) : 0 ～ 127000

```c
    [self.currentPeripheral.connector.sensorHandler queryAccSensorParameterWithCompletionHandler:^(BOOL isSuccess, NSInteger odr, NSInteger wakeupThreshold, NSInteger wakeupDuration) {  
      
    }];

[self.currentPeripheral.connector.sensorHandler setAccSensorParameterWithOdr:0 WakeupThreshold:200 WakeupDuration:1000 CompletionHandler:^(BOOL isSuccess) {   
      
    }];
```

At the end of this part, 您可以参考以上所有代码进行开发. 当然我们在SDK中对每一个APi都做了注释, 如果有新的东西, 我们将更新此文档.

## 笔记

1.  In development progress, you may find there are **multiple MTPeripheral instance** correspond to a physical device. On this point, we consulted Apple's engineers. they told us that currently on the iOS platform, CoreBluetooth framework unfriendly to the multiple slot devices(especially the advertisement data in changing). due to that sometimes app can't connect to the device, Google Eddystone solve this issue by **press button on eddystone devices**, our device support this operation too.
    
    iOS11 doesn't has this issue.
    
2.  In scanning stage, some properties may nil, especially MAC address(restriction of iOS),if current device advertise **DeviceInfo** frame, then you can get name, MAC address and battery.
    
3.  后 5 minus the app connected to device, the device will take the initiative to disconnect.
    
4.  If the running display cannot find the path after adding the SDK, remove the package and add it again at General-> Frameworks,图书馆,and Embedded Content

## Other

BeaconPlus SDK is also used in our BeaconSET+ app. If you need a more intuitive understanding of our beaconPlus equipment and the corresponding functions of the SDK, you can also download the BeaconSET+ app to learn more. (Reminder: BeaconSET+ app and BeaconPlus SDK need to be used with equipment produced by our company)

## 变更日志

-   2017.10.11 v1.0 第一版;
-   2019.01.07 v1.1 第二版;
-   2019.07.11 v1.2 change the poweroff;
-   2020.03.27 v1.10.0 add LineBeacon;
-   2020.07.27 v1.10.1 Optimize getting and setting of LineBeacon frame
-   2020.10.27 v1.10.2 Added lastUpdate property for each broadcast frame
-   2021.4.21 v1.11.0 Added Sixaxis/Magnetometer/AtmosphericPressure sensor
-   2021.4.28 v1.11.1 Added vibration sensor
-   2021.09.16 v1.13.0 Added pir sensor
-   2021.10.9 v1.14.0 Newly set Bluetooth 5.0 broadcast rate
-   2021.12.27 v1.14.1 Added new parameter configuration items for adaptable acceleration sensor configurable firmware
-   2022.5.10 Support parameter modification of ACC frame
-   2022.6.1 v1.16.0 Added IN100 broadcast frame MinewMBeaconInfo
-   2023.11.13 v1.17.0 Fixed WriteFrame crash; support background scanning