简体中文
简体中文
English
联系我们
注册
登录

行业 App SDK iOS 版快速入门

更新时间:2022-11-28 02:34:22下载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 或更高版本。

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