如何使用iOS物模型SDK_生活物联网平台（飞燕平台）-阿里云帮助中心

物模型SDK提供了App端的物模型（属性、事件、服务），用来开发设备界面，实现手机对设备的查看和控制。

依赖 SDK	概述
日志	基础依赖SDK，提供客户端统一日志打印，日志等级控制，分模块日志隔离等能力
API通道SDK	API通道SDK，提供IoT业务协议封装的HTTPS请求能力，并通过整合安全组件来提升通道的安全性。
长连接通道SDK	长连接通道SDK，提供IoT业务协议封装的云端数据下行能力，为App提供订阅、发布消息的能力和支持请求响应模型。

初始化

初始化前需确保已集成安全图片，初始化的操作请参见SDK初始化。

使用说明

获取本地发现且支持本地控制的设备列表
本地通信功能是物模型SDK提供的一项基础能力，它提供了在外网断连的情况下，局域网内设备控制的特性。当外网断连的情况下，本地通信模块会去搜寻当前局域网内的设备，如果被发现的设备是之前用户控制过的设备，那么此时可以通过本地通信链路去控制设备。
在外网断连时，如向云端拉取用户账号下的设备列表会失败，此时可以使用以下接口获取当前可以本地通信控制的设备列表。由于本地发现设备是一个较长的过程，所以第一次调用此接口时有可能返回为空，此时需要允许用户刷新设备列表。
```
#import <IMSThingCapability/IMSThingCapability.h>

(NSArray<NSDictionary *> *)  devices = [kIMSThingManager getLocalAuthedDeviceDataList];
//其中 NSDictionary 保存了设备的详细信息。               
```

创建设备

设备抽象类IMSThing封装了设备对外提供的所有接口，包括获取设备的模型、设备的操作方法、设备的基础信息等。

#import <IMSThingCapability/IMSThingCapability.h>
/**
APP端可以使用 API 通道 SDK，请求接口 '/uc/listByAccount'，可以拿到当前账号下所有绑定的设备列表，返回的设备信息中有设备的 iotId。

*/
_thingShell = [kIMSThingManager buildThing:_iotId];// _iotId为云端给设备颁发的唯一标识
// 当不再需要使用时，请记得销毁，如下所示：
// [kIMSThingManager destroyThing:_thingShell];
// 如果需要获取设备的 iotId
// NSString * iotId = [_thingShell iotId];

设备解绑

App上用户主动解绑一台设备或者在设备端reset，云端会主动向App发送通知。App收到推送通知后，SDK内部会自动清除相关缓存数据，且发出onDeviceUnbind通知。

/**
设备被解绑通知，具体参见`IMSThingObserver`
@param iotId：物的iotId
@param params：云端推送下来的原始数据
*/
- (void)onDeviceUnbind:(NSString *)iotId params:(NSDictionary *)params;

设备控制

App端需要控制设备时，SDK会根据当前的实际情况来决定控制请求是通过本地还是通过云端发送至设备。设备控制的接口协议为IMSThingActions。

该协议定义了几个接口，用来对设备做控制，内部逻辑会实现通道选择。设备控制是基于物的模型对设备定义的属性、事件、服务进行操作。关于属性、事件、服务的描述，请参见：物的模型TSL介绍。

方法调用时的入参、出参，请参见物的模型服务。

获取设备状态

[[_thingShell getThingActions] getStatus:^(IMSThingActionsResponse * _Nullable response) {
     NSDictionary * properties = [response.dataObject valueForKey:@"data"];
     //格式如下：  
     /* {
            "status":1 //
            "time":1232341455
        }
       说明：status表示设备生命周期，目前有以下几个状态，
        0:未激活；1：上线；3：离线；8：禁用；time表示当前状态的开始时间；
     */
}];

获取设备属性

[[_thingShell getThingActions] getPropertiesFull:^(IMSThingActionsResponse * _Nullable response) {
     NSDictionary * properties = [response.dataObject valueForKey:@"data"];
     //格式如下：  
     /* {
           "_sys_device_mid": {
             "time": 1516356290173,
             "value": "example.demo.module-id"
            },
           "WorkMode": {
             "time": 1516347450295,
             "value": 0
            },
           "_sys_device_pid": {
             "time": 1516356290173,
             "value": "example.demo.partner-id"
           }
        }
     */
}];

设置设备属性

NSDictionary * items = @{@"power":@"on", @"temperature":25};
//items 为key-value对，具体的值请参考物的模型 TSL-属性以及其 datatype
[[_thingShell getThingActions] setProperties:items
                             responseHandler:^(IMSThingActionsResponse * _Nullable response) {
                                           if (response.success) { 
                                               dispatch_async(dispatch_get_main_queue(), ^{
                                                   [UiUtils showTip:[NSString stringWithFormat:@"设置属性 %@成功", [property name]]];
                                               });
                                           } else {
                                               dispatch_async(dispatch_get_main_queue(), ^{
                                                   [UiUtils showTip:[NSString stringWithFormat:@"设置属性 %@失败", [property name]]];

                                               });
                                           }
                                       }];

调用服务

// identifier 请参见物的模型 TSL 中 Service 描述
// 调用服务时的入参，请参见物的模型 TSL 中 Service 的 inputData
// 调用服务时的出参，请参见物的模型 TSL 中 Service 的 outputData
[[ _thingShell getThingActions] invokeService:[service identifier] 
                                       params:valueDict 
                              responseHandler:^(IMSThingActionsResponse * _Nullable response) {
                                             if (response.success) {
                                                 dispatch_async(dispatch_get_main_queue(), ^{ 
                                                         [UiUtils showTip:[NSString stringWithFormat:@"调用服务 %@成功", [service name]]];
                                                          });
                                             } else {
                                                dispatch_async(dispatch_get_main_queue(), ^{
                                                          [UiUtils showTip:[NSString stringWithFormat:@"调用服务 %@失败", [service name]]];
                                                          });
                                                     } }];

订阅所有事件

[_thingShell registerThingObserver:self];  //注册设备状态、属性变化、以及事件触发的观察者。
// 具体参见 `IMSThingObserver`，并请注意注册的Observer的生命周期
// SDK只会Weak reference其实例,请开发者自己保证Observer的生命周期。
// 不需要监听时，请注销[_thingShell unregisterThingObserver:self];

清理缓存
SDK 在使用过程中会保存本地通信加速的相关数据到手机沙盒目录，当手机账号登出时记得清理这些缓存。
```
[kIMSThingManager clearLocalCache];
```

获取物的模型

物模型是对设备是什么、能做什么的描述，包括设备身份标识、连接状态、描述信息，以及设备的属性（properties）、服务（services）、事件（events），后三者构成了设备的功能定义。阿里云IoT平台通过定义一种物的描述语言来描述物模型，称之为 TSL（即 Thing Specification Language）。

当IMSThingObserver didThingTslLoad方法被回调时，可以获得解析完成的物的模型。

IMSThingProfile * Profile = [thingShell getThingProfile];
//其中物的三要素，保存在 IMSThingProfile 中。
_thingProperties = [[_thingShell getThingProfile] allPropertiesOfModel];
_thingEvents =  [[_thingShell getThingProfile] allEventsOfModel];
_thingServices =  [[_thingShell getThingProfile] allServicesOfModel];
// 注意，此处拿到的 properties，events，services 是物的模型中的物的三要素。
// 具体请参见 IoT-TSL 规范

开发者也可以使用云端接口来获取原始的物的模型，参见获取物的模板。

蓝牙功能API介绍

蓝牙设备受连接特性的约束，往往无法直接跟生活物联网云端平台连接，因而需要借助一个网关设备来实现蓝牙设备与生活物联网云端平台的连接通道。而手机在这一过程中也可以充当网关的角色。

此 SDK 额外提供以下几方面的能力如下。

提供发现蓝牙设备/连接蓝牙设备的能力
提供连云通道，可以供蓝牙设备数据上下云
提供蓝牙设备控制与数据获取的能力

接入蓝牙设备需要引入相关依赖如下。

依赖 SDK	概述
蓝牙Breeze SDK	Breeze SDK是按照规范实现的手机端蓝牙 SDK，方便合作厂商在手机端快速接入蓝牙功能。Breeze SDK包含的主要功能有：设备发现连接，设备通信，加密传输，大数据传输等。
移动端设备网关SDK	移动端设备网关SDK，运行于App上的子设备网关，对于无法直连网络的子设备，如蓝牙设备，提供子设备的管理功能，如子设备添加拓扑，删除拓扑，上线，下线以及数据上下行等。

初始化移动端设备网关SDK
此功能模块依赖移动端设备网关SDK。使用前请先初始化该SDK。

蓝牙设备的发现

#import <IMSThingCapability/IMSThingCapability.h>

[[IMSThingDiscoveryRegistry sharedRegistry] startDiscoveryWithFilter:filterParams
                                                           didFoundBlock:^(NSArray * _Nullable result, NSError * _Nullable error) {
                                                               if ([result count]) {
                                                                   [result enumerateObjectsUsingBlock:^(id<IMSLocalDevice> item, NSUInteger idx, BOOL * _Nonnull stop) {
                                                                       NSString * productKey = item.productKey;
                                                                       NSString * bleMac = item.deviceName;//对于Breeze 蓝牙设备，这里得到的是设备的MAC地址

                                                                   }];
                                                               }
    }];

蓝牙设备的添加绑定流程

启动蓝牙连接，需要在使用蓝牙设备前调用。

#import <IMSThingCapability/IMSThingCapability.h>

IMSThing * thing = [[IMSThingManager sharedManager] buildThing:iotId];
[thing startLocalConnect];

断开蓝牙连接，需要在不需要使用蓝牙设备时调用。

#import <IMSThingCapability/IMSThingCapability.h>

IMSThing * thing = [[IMSThingManager sharedManager] buildThing:iotId];
[thing stopLocalConnect];

蓝牙连接状态变化需要传入Delegate。

IMSThing * thing = [[IMSThingManager sharedManager] buildThing:iotId];
[thing registerThingObserver:self];//请参见IMSThingObserver

蓝牙设备的控制
蓝牙设备的控制以及信息获取跟WiFi设备的API是一致的，可以参考本文档前述章节。