简体中文
简体中文
English
联系我们
注册
登录
语言
简体中文
简体中文
English
联系我们
登录
注册
返回主站
layout空间导航

行业 App SDK iOS 版快速入门

更新时间:2021-09-03 01:53:12下载pdf

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

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

获取免费的开发者帐户 代码 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 云服务,为世界各地客户提供更稳定的服务。您可以在此选择提供服务的区域,支持多选,并且以后您可以修改此配置。

    • 开发方式下拉框中,选择自定义开发

      行业 App SDK iOS 版快速入门
  5. 单击创建,继续配置项目。

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

    行业 App SDK iOS 版快速入门

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

  7. 单击开通授权

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

    详情参考管理资产

创建应用程序

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

  2. 单击目标项目。

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

    行业 App SDK iOS 版快速入门
  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)

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

登录用户账户

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

SDK 目前不支持注册用户。所有注册过程都在平台上完成。您需要手动添加用户到您的项目中才能成功登录账户。

调用 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 模式

  • 流程

    行业 App SDK iOS 版快速入门
  • 获取令牌

    在执行 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 种令牌:

  • 激活设备

    初始化 TYAPActivator,并调用 start()

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

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

    activator.stop()
    
  • 获取配网结果

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

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

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

有线模式

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

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

行业 App SDK iOS 版快速入门
  • 获取令牌

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

  • 搜索设备

    初始化 TYWiredActivator

    let activator = TYWiredActivator(pairingToken: pairingToken)
    

    调用 start() 来搜索设备:

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

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

  • 获取配网结果

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

子设备模式

行业 App SDK iOS 版快速入门

二维码模式

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

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:) 来查询某资产的绑定设备。

本教程包含了以下文档,帮助您快速了解相关概念和流程: