物模型SDK提供了App端的物模型(屬性、事件、服務),用來開發設備界面,實現手機對設備的查看和控制。
依賴 SDK | 概述 |
日志 | 基礎依賴SDK,提供客戶端統一日志打印,日志等級控制,分模塊日志隔離等能力 |
API通道SDK | API通道SDK,提供IoT業務協議封裝的HTTPS請求能力,并通過整合安全組件來提升通道的安全性。 |
長連接通道SDK | 長連接通道SDK,提供IoT業務協議封裝的云端數據下行能力,為App提供訂閱、發布消息的能力和支持請求響應模型。 |
初始化
使用說明
- 獲取本地發現且支持本地控制的設備列表
本地通信功能是物模型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是一致的,可以參考本文檔前述章節。