I-快速开始 | 文档中心

一、概述

在此部分主要是介绍如何最快速使用XLinkSDK,包括了以下几部分内容

SDK的导入与配置
SDK的简单初始化
基本流程任务的使用

通过以下的几个简单的步骤，就可以完成基础的设备连接并控制操作，然后就可以开始体验智能互联的力量了！

更多详细信息和使用请参考进阶篇-SDK高级配置，相关API使用请参考API，常见的问题解答请参考FAQ。

1、SDK的导入与配置

方式一、通过 Cocoapods 集成

在您当前工程的 Podfile 文件中添加如下一行。
```
`pod ``'XLinkSDK'`
```
执行pod install 或pod update。
首次导入的话需要把工程中其中一个导入XLinkSDK.h代码文件的**.m后缀修改为.mm**后缀。例如在”AppDelegate.m”中导入了XLinkSDK.h，就需要把”AppDelegate.m”改”AppDelegate.mm”。

方式二、手动集成 XLinkSDK

您可以到XLinkSDK下载地址下载XLinkSDK。
把下载到 XLinkSDK解压，并把解压后的源文件添加（拖放）到您的工程中。
导入SDK后，您的工程需要做以下的配置：
- 进入Build Phases ,点击打开”Link Binary With Library“,添加”libz.tbd“。
- Build Settings --> Linking --> Other Liker Fliags 添加 -ObjC
- 首次导入的话需要把工程中其中一个导入**XLinkSDK.h** 代码文件的**.m后缀修改为.mm**后缀。例如在”AppDelegate.m”中导入了XLinkSDK.h，就需要把”AppDelegate.m”改”AppDelegate.mm”。

2、SDK简单初始化

SDK初始化的参数有相对较多的可选参数，可以根据需要设置使用。这里介绍最简单的初始化过程（使用默认参数初始化使用）。

//使用默认参数启动并运行SDK
[[XLinkSDK share] start];

SDK启动后即可进行相关功能使用。

3、基本流程任务使用

SDK中提供了多个模块与功能，以下仅从最常见的使用流程进行基本介绍。最常见的使用流程为：

用户授权->扫描设备->添加订阅设备->设备控制->移除设备（->同步设备列表）

3.1、用户授权

用户授权即用户的登录操作，登陆成功之后SDK会维护和云端的连接，并且维护Access-Token的有效性，该操作需要使用XLinkUserAuthorizeTask。

XLinkUserAuthorizeTask *userAuthTask = [XLinkUserAuthorizeTask userAuthorizeTaskWithAccount:account
                             password:password
                             cropId:cropID
                             timeout:20
                   completionHandler:^(id result, NSError *error) {
    if (error) {
        //登录失败
    }else {
        //登录成功，在result中含有授权信息，SDK内部自动进行云端连接
    }
}];
[userAuthTask start];

3.2、扫描设备

扫描设备指的是在局域网中发现所需要的设备，需要使用XLinkScanDeviceTask。扫描设备需要使用到设备的 ProductId，即产品ID，获取方式请参考资源准备。

//新建扫描设备任务
XLinkScanDeviceTask *scanTask = [XLinkScanDeviceTask scanDeviceTaskWithProductIdArray:@[@"123456789",@"987654321"]
                                                                              timeout:90
                                                           didDiscoveredDeviceHandler:^(XDevice *device) {
    //扫描到设备回调,同一设备仅会回调一次
}
                                                                    completionHandler:^(id result, NSError *error) {
    //无论搜不搜索到设备都会回调这个方法。返回的错误是任务超时
}];
 
[scanTask start];

3.3、添加订阅设备

添加订阅设备时会通过云端建立当前用户与设备的绑定关系，需要使用XLinkAddDeviceTask。

XLinkAddDeviceTask *addDeviceTask = [XLinkAddDeviceTask addDeviceTaskWithDevice:device
                                                                        pinCode:pingCode //pingCode需要硬件设备支持，一般情况下可以为nil
                                                                        timeout:60
                                                              completionHandler:^(id result, NSError *error) {
    if (!error) {
        //设备添加成功
    }else{
        //设备添加失败
    }
}];
[addDeviceTask start];

3.4、设备控制

设备控制分为三个操作，分别是获取获取设备物模型属性、设置设备物模型属性、以及调用设备物模型服务操作，三个操作分别对应了三个任务。其中设备物模型属性的详细说明可查阅附录，此处可以先理解为获取设备的控制属性。

获取设备物模型属性

对设备的控制实际上就是对设备的物模型属性进行操作，从而达到设备状态或行为变化。其中获取设备物模型属性使用 XLinkTMLProbeAttributeTask

XLinkTMLProbeAttributeTask *task = [XLinkTMLProbeAttributeTask probeAttributeTaskWithDevice:device dataPayload:dataPayload timeout:10 completionHandler:^(id  _Nullable result, NSError * _Nullable error) {
    if (!error) {
        //任务执行成功,物模型属性列表会通过result返回
    }else{
        //任务执行失败
    }
}];

//执行查询物模型属性任务
[task start];

设置设备物模型属性

对设备的控制实际上就是对设备的物模型属性进行操作，从而达到设备状态或行为变化。其中设置设备物模型属性使用 XLinkTMLSetAttributeTask

//修改物模型属性，控制设备
NSDictionary *dataPayload = @{
    @"v" : @"2",
    @"input" : @{
        @"PowerSwitch" : @(YES),
        @"key2" : @"value2"
    }
};
XLinkTMLSetAttributeTask *task = [XLinkTMLSetAttributeTask setAttributeTaskWithDevice:device dataPayload:dataPayload timeout:10 completionHandler:^(id  _Nullable result, NSError * _Nullable error) {
    if (error) {
        NSLog(@"服务调用失败了");
    } else {
        NSLog(@"服务调用成功了");
    }
}];
[task start];

调用设备物模型服务
相比于属性，服务可通过一条指令实现更复杂的业务逻辑。其中调用设备物模型服务使用 XLinkTMLInvokeServiceTask。

//修改物模型属性，控制设备
NSDictionary *dataPayload = @{
    @"v" : @"2",
    @"input" : @{
        // 这里根据实际填入参数
    }
};
NSString *serviceName = @"name"; // 这里根据实际填入服务名
XLinkTMLInvokeServiceTask *invokeServiceTask = [XLinkTMLInvokeServiceTask invokeServiceTaskWithDevice:device serviceName:serviceName dataPayload:dataPayload timeout:10 completionHandler:^(id  _Nullable result, NSError * _Nullable error) {
    if (error) {
        NSLog(@"服务调用失败了");
    } else {
        NSLog(@"服务调用成功了");
    }     
}];
[invokeServiceTask start];

3.5、移除设备

移除设备会将设备从设备维护列表中移除并取消用户与设备之间的绑定关系，使用XLinkRemoveDeviceTask。

//新建删除设备任务
XLinkRemoveDeviceTask *removeDeviceTask = [XLinkRemoveDeviceTask removeDeviceTaskWithDevice:device
                                                                                    timeout:10
                                                                          completionHandler:^(id result, NSError *error) {
    if (!error) {
        //删除成功
    }else{
        //删除失败
    }
}];
[removeDeviceTask start];

3.6、同步设备列表

在添加订阅成功设备之后，当前用户会与该设备存在绑定关系，在任何时候都可以从云端同步到该设备并进行设备的控制操作，使用XLinkSyncDeviceListTask。

XLinkSyncDeviceListTask *syncTask = [XLinkSyncDeviceListTask syncDeviceListTaskWithVersion:0 //目前只需要填入0即可
                                                                                   timeout:10
                                                                              connectLocal:YES //同步设备列表后是否需要和设备建立本地连接
                                                                         completionHandler:^(id result, NSError *error)  {
    if (!error) {
        //同步设备列表成功，设备列表会通过result返回
    }else{
        //同步设备列表失败
    }
}];
[syncTask start];

上次更新：2023-02-02