行业 App SDK iOS 版快速入门

本教程为您介绍涂鸦 行业 App SDK iOS 版，您在本教程中学习的技术是使用此 SDK 构建 IoT 应用程序的基础。在教程的实践方法中，使用 Swift 的示例代码来描述该构建过程。

在本教程中，您将学习以下内容：

• 什么是行业 App SDK：为您概述SDK的概念及其优势。
• 添加 SDK 至 iOS 项目：教您如何将 SDK 导入您的 iOS 项目。
• 登录用户账户：向您展示了如何创建用户帐户，如何为用户授予资产权限，以及其他基本的用户管理知识。
• 设备配网：帮助您熟悉设备配对过程以及如何使用代码配对设备。
• 设备管理：介绍实用的设备管理方法。
• 资产管理：指导您如何添加、查询、修改或删除您创建的资产。

获取免费的开发者帐户 代码 Sample GitHub

注意事项

涂鸦行业 App SDK版属于 iOS 库。因此，使用本教程前，您已经基本了解 iOS 开发，包括 Objective-C 和 Swift，并且您已熟悉 Xcode。

此 SDK 使用 Swift 编写，但相关概念和 API 适用于 Objective-C。在本教程中，Swift 用作编程语言。

什么是行业 App SDK？

涂鸦行业 App SDK 是涂鸦 SaaS 开发框架产品系列的重要组成部分。本教程提供了基于涂鸦 OpenAPI 的多种功能示例，例如，设备配对、用户登录注册、资产管理等。

添加 SDK 至 iOS 项目

如需使用此 SDK 和涂鸦 IoT 平台的能力，您必须先将您的应用注册到涂鸦 IoT 平台，然后安装此 SDK。

前提条件

• 安装以下软件：
  • Xcode 12.0 或更高版本。
  • CocoaPods 1.10.0 或更高版本。
• 您的项目必须面向 iOS 10.0 或更高版本。

注册应用到涂鸦 IoT 平台

创建项目

1. 登录涂鸦 IoT 平台。

2. 在左侧导航栏中，选择云开发 > 项目管理。

3. 单击立即创建。

4. 在创建项目对话框中：

   • 设置项目名称、项目描述、服务行业和可用区域。

     涂鸦在全球部署了六大数据中心提供 IoT 云服务，为世界各地客户提供更稳定的服务。您可以在此选择提供服务的区域，支持多选，并且以后您可以修改此配置。

   • 在开发方式下拉框中，选择自定义开发。

     

5. 单击创建，继续配置项目。

6. 在配置向导中，选择设备状态通知 API 产品。

   
   默认选择的 API 产品包括行业通用 API 产品和授权管理 API 产品。

7. 单击开通授权。

8. 填写资产和账户信息，资产自动创建并授权给该账户。

   详情参考管理资产。

创建应用程序

1. 选择云开发 > 项目管理，跳转到我的项目列表页面。

2. 单击目标项目。

3. 在该项目的项目管理页面，选择应用 > App 应用，点击添加应用。

   

4. 在添加应用程序弹框中，选择 iOS 应用类型。

   确保包标识符与您创建的 Xcode 项目相同。

导入 SDK

1. （可选）如果您还没有 Podfile，请创建一个。

   $ cd your-project-directory
   

   $ pod init
   

2. 在您的 Podfile 中，添加涂鸦行业 App SDK 和源。

   source 'https://cdn.cocoapods.org/'
   source 'https://github.com/TuyaInc/TuyaPublicSpecs.git'
   
   target 'your-project' do
   pod 'TuyaIoTAppSDK'
   end
   

3. 安装 pod，然后打开 .xcworkspace 文件，在 Xcode 中查看项目。

   $ pod install
   

   $ open your-project.xcworkspace
   

4. 导入 SDK。

   Swift：

   import TuyaIoTAppSDK
   

   Objective-C:

   #import <TuyaIoTAppSDK/TuyaIoTAppSDK-Swift.h>
   

Objective-C 项目

涂鸦行业 App SDK是一个 Swift 闭源库。为了在纯 Objective-C 项目中使用该库，您需要在您的项目中添加一个空的 Swift 文件。Xcode 会询问你是否创建桥接头，请选择创建。

初始化 SDK

在 AppDelegate.swift 中，将以下代码添加到 didFinishLaunchingWithOptions：

TYSDK.initialize(clientID: "YourClientID",
					  clientSecret: "YourClientSecret",
					  hostRegion: .US)

代码中的 clientID 和 clientSecret 可从您创建应用程序时使用的 Authorization Key 字段中获取。

登录用户账户

TYUserManager 类提供了登录用户账户并保持会话的方法。

调用 login(userName:password:completionHandle:) 来登录用户账户：

let manager = TYUserManager()

manager.login(userName: account, password: password) { (isSuccess, error) in
	// Check whether the login operation is successful.
	if isSuccess{
		// Success handle
	} else {
		// Faliure handle
		print(error?.localizedDescription)
	}
}

设备配网

涂鸦行业 App SDK针对不同条件提供多种配网模式，如热点（AP）模式、有线模式、NB-IoT 模式、二维码模式和子设备模式。

• AP 模式：也称为热点模式。该模式下，手机连接智能设备的热点，双方建立 Socket 连接，通过协议端口交换数据。

• 有线模式：设备通过有线网络连接到路由器。Zigbee 有线网关、有线摄像头均属于此类设备。

• 子设备模式：蓝牙子设备和 Zigbee 子设备均属于此类设备。这些设备通过网关与 app 和云端进行交互。

• 二维码方式：摄像头设备通过扫描 app 上的二维码获取配网信息。

AP 模式

• 流程：

  

• 获取令牌：

  在执行 AP 模式的配网操作之前，SDK 需要从涂鸦 IoT 云端获取配网令牌。此令牌有效期为 10 分钟。配网成功后，此令牌立即失效。如果您需要重新配网，必须重新获取令牌。

  如需获取令牌，调用 TYDeviceRegistrationManager` 中的 generateToken(for:uid:timeZoneID:assetID:deviceUUID:completionHandle:)。

  let manager = TYDeviceRegistrationManager()
  
  manager.generateToken(for: .AP, uid: TYUserInfo.uid, assetID: assetID) { [weak self] (deviceRegistrationToken, error) in
  	// Check error first, then retrieve the token from deviceRegistrationToken
  }
  

  TYDeviceRegistrationToken 包括下列 2 种令牌:

  • pairingToken：可发送给设备。
  • token：用于云端轮询注册结果。

• 激活设备：

  初始化 TYAPActivator，并调用 start()。

  let activator = TYAPActivator(SSID: ssid, password: password, pairingToken: pairingToken)
  activator.start()
  

  配网后，无论操作成功或失败，调用 stop()。

  activator.stop()
  

• 获取配网结果：

  如需获取配网结果，调用 TYDeviceRegistrationManager中的 queryRegistrationResult(of:completionHandle:)。

  设备配网属于异步过程。设备配网的耗时取决于网络质量。您必须调用 API 来检查设备配网结果。当系统返回配网设备列表或配网任务超时后，轮询任务停止。

  建议轮询任务设置为每隔 1 秒运行一次。配对任务的超时值建议设置为 100 秒。

有线模式

在该模式下，有线设备已连接到网络。配网时，您不需要提供路由器的名称和密码。

下图以 Zigbee 有线网关为例，描述有线网关组网过程。

• 获取令牌：

  此过程与 AP 模式过程完全一致。

• 搜索设备：

  初始化 TYWiredActivator：

  let activator = TYWiredActivator(pairingToken: pairingToken)
  

  调用 start() 来搜索设备：

  activator.start(timeout: 120) { error in
  	print(error.localizedDescription)
  }
  

  如果扫描过程超时且未找到任何设备，则调用 failureHandle。

• 获取配网结果：

  该过程与 AP 模式完全一致。

子设备模式

• 搜索设备：

  如需完成子设备与网关的配网，首先要启用网关来发现子设备。为此，您可以调用 TYDeviceRegistrationManager 中的 discoverSubDevices(gatewayDeviceID:duration:completionHandle:) 来实现。

  deviceRegistrationManager.discoverSubDevices(gatewayDeviceID: gateway.id) { success, error in
  	guard success else {
  		print(error?.localizedDescription)
  		return
  	}
  
  	// Polling for the result
  	// ...
  }
  

• 获取配网结果：

  该过程与 AP 模式完全一致。

• 停止搜索设备：

  在获取配网结果或搜索超时后，需要在 TYDeviceRegistrationManager 中调用 stopDiscoveringSubDevice(gatewayDeviceID:completionHandle:)，使网关停止搜索子设备。

二维码模式

在该模式下，您可以使用智能摄像头等设备扫描二维码，完成设备配网。生成的二维码图像必须显示在智能手机上。

TYQRCodeActivator 为您提供了实现此配网模式的方法。初始化设备实例，在实例中调用 generateQRCodeData() 或 generateQRCodeUIImage()。前者调用可返回生成二维码的数据，此时，您必须自行生成二维码图片。后者可通过 UIImageView 的渲染返回 UIImage，直接获取二维码图片。

设备管理

TYDeviceManager 提供设备管理方法。

如需获取单个设备的详细信息，调用 queryDeviceInfo(of:completionHandle:)。如需获取多个设备的详细信息，调用 queryDevicesInfo(of:completionHandle:)。

如需控制设备，调用 queryCommandSetFromCategory(category:completionHandle:) 可基于某类别返回设备指令集，调用 queryCommandSetFromDeviceID(deviceID:completionHandle:) 可基于设备 ID 返回设备指令集。TYStandardCommand 提供命令相关信息，具体如下：

• code：用于发送命令。
• value：表示命令的范围。
• type：表示命令的值类型。

在发送设备控制命令前，您需要构造 TYDeviceCommand，其中包含 code 及其对应的 value。例如，若要控制一个灯泡的开或关，您需要在 TYStandardCommand 中，将 code 设置为 switch，将 type 设置为 boolean。您必须构造 TYDeviceCommand，类似的构造方式如下：

let command = TYDeviceCommand(code: "switch", value: true)

然后，调用 sendCommands(commands:to:completionHandle:) 发送命令。

如需获取设备的最新状态，可采用 queryDeviceStatus(of:completionHandle:) 或 queryDevicesStatus(of:completionHandle:)。

资产管理

TYAssetManager 提供资产交互相关的方法。目前，SDK 无法用于添加、修改或删除资产。您只能在涂鸦 IoT 平台上完成此类操作。详情参考管理资产。

您可以通过调用 queryAssets(parentAssetID:pageNumber:pageSize:completionHandle:) 来查询某用户的所有授权资产。您也可以通过调用 queryDevices(in:pageSize:lastRowKey:completionHandle:) 来查询某资产的绑定设备。