设备控制 UI 业务包

设备控制 UI 业务包 是涂鸦智能设备控制面板的核心容器。在涂鸦 智能生活 App SDK iOS 版的基础上，UI 业务包提供设备控制面板的加载和控制的接口封装，加速应用开发过程。此业务包同时包含了 RN 面板和小程序面板，如果想单独接入小程序面板，参考 小程序 SDK 文档。

功能介绍

UI 业务包主要包括以下功能：

• 面板加载：加载多种设备类型，包括 Wi-Fi、Zigbee、低功耗蓝牙、蓝牙 Mesh 等。
• 设备控制：支持单设备和群组的控制，但不支持群组管理。
• 设备定时：支持设备下发定时任务。

接入组件

在工程的 Podfile 文件中添加设备控制 UI 业务包组件，并执行 pod update 命令。

source "https://github.com/TuyaInc/TuyaPublicSpecs.git"
source "https://github.com/tuya/tuya-pod-specs"
source 'https://cdn.cocoapods.org/'
platform :ios, '11.0'

target 'your_target_name' do
  # ThingSmart SDK
  pod "ThingSmartHomeKit"
  # 添加设备控制 UI 业务包
  pod 'ThingSmartPanelBizBundle'
  # 若需要 IPC 功能，请依赖 IPC 相关插件
  # pod 'ThingSmartCameraRNPanelBizBundle'

  # 若需要健康功能，请依赖健康相关插件。注意，健康插件需要明确在 App 中使用健康授权能力，不然容易引发上架被拒
  # pod 'ThingSmartHealthExtendBizBundle'

  # 若需要扫地机功能，请依赖扫地机相关插件
  # pod 'ThingSmartSweeperExtendBizBundle'

  # 若需要音响面板功能，请依赖相关插件
  # pod 'ThingSmartSpeakExtendBizBundle'
  # pod 'AFNetworking', '~> 4.0.0' 

  # 若需要小程序的家庭相关能力，请依赖相关插件
  # pod 'TUNIHomeKit'

  # 面板调试功能 ⚠️⚠️ 以下组件只用于调试，请勿上线
  # pod 'ThingRNPanelTool', :configurations => ['Debug']
  # pod 'React', :podspec => './localPath/React.podspec.json' # 调试包链接https://images.tuyacn.com/rnpanel/React.podspec.json 
  # pod 'ThingSmartPanelBizBundle', '5.1x.x.x' # 固定设备控制 UI 业务包 
end

注意事项

设备控制 UI 业务包包含了开源框架 RN（React Native），版本为 0.59.11。

• 若您的 iOS 工程未集成 ReactNative，请按文档步骤集成涂鸦设备控制 UI 业务包。

• 若您的 iOS 工程已集成 ReactNative，需按下面步骤操作，以确定是否可集成设备控制业务包：

  • 若已集成 ReactNative，且版本 > 0.59.11，因版本兼容性问题，则无法集成设备控制业务包。
  • 若已集成 ReactNative，且 0.59.11 ≥ 版本 > 0.51，因 ReactNative 库冲突，不保证能够正常接入涂鸦面板。按下面两种方式进行操作：
    1. 移除您 iOS 工程中的 ReactNative，使用设备控制业务包依赖的 ReactNative 0.59.11。
    2. 将您 iOS 工程中集成的 ReactNative 进行更名，从而避免与业务包集成的 ReactNative 冲突。

  若均无法集成成功，则您无法接入集成设备控制业务包。

权限要求

设备控制 UI 业务包中封装一系列 RN 接口供面板调用，其中会涉及到部分苹果隐私权限的声明。

• 如果接入的设备面板有使用相册相关的（例如：云相册），则需要在工程的 info.plist 中添加如下权限声明：

  NSPhotoLibraryAddUsageDescription
  

• 如果接入的设备面板有使用照相机相关的（例如：云相册），则需要在工程的 info.plist 中添加如下权限声明：

  NSCameraUsageDescription
  

• 如果接入的设备面板有使用位置信息相关的，则需要在工程的 info.plist 中添加如下权限声明：

  NSLocationWhenInUseUsageDescription
  

• 如果接入的设备面板有使用到麦克风（例如：音乐灯面板），则需要在工程的 info.plist 中添加如下权限声明：

  NSMicrophoneUsageDescription
  

• 如果接入的设备面板是蓝牙相关的，则需要在工程的 info.plist 中添加如下权限声明：

  NSBluetoothAlwaysUsageDescription
  NSBluetoothPeripheralUsageDescription
  

服务协议

提供服务

设备控制 UI 业务包实现 ThingPanelProtocol 协议以提供服务。在 ThingModuleServices 组件中查看 ThingPanelProtocol.h 协议文件内容为：

@protocol ThingPanelProtocol <NSObject>
NS_ASSUME_NONNULL_BEGIN

// 清除面板缓存
- (void)cleanPanelCache;

/**
 * 获取设备面板控制器
 *
 * @param deviceModel 设备模型
 * @param initialProps  自定义初始化参数，会以 'extraInfo' 为 key 设置进 RN 应用的 initialProps 中
 * @param contextProps  自定义面板上下文，会以 'extraInfo' 为 key 设置进 Panel Context 中
 * @param completionHandler 回调返回视图控制器
 */
- (void)getPanelViewControllerWithDeviceModel:(ThingSmartDeviceModel *)deviceModel
                                 initialProps:(nullable NSDictionary *)initialProps
                                 contextProps:(nullable NSDictionary *)contextProps
                            completionHandler:(void (^ _Nullable)(__kindof UIViewController * _Nullable panelViewController, NSError * _Nullable error))completionHandler;

/**
 * 获取群组面板控制器
 *
 * @param groupModel 群组模型
 * @param initialProps  自定义初始化参数，会以 'extraInfo' 为 key 设置进 RN 应用的 initialProps 中
 * @param contextProps  自定义面板上下文，会以 'extraInfo' 为 key 设置进 Panel Context 中
 * @param completionHandler 回调返回视图控制器
 */
- (void)getPanelViewControllerWithGroupModel:(ThingSmartGroupModel *)groupModel
                                initialProps:(nullable NSDictionary *)initialProps
                                contextProps:(nullable NSDictionary *)contextProps
                           completionHandler:(void (^ _Nullable)(__kindof UIViewController * _Nullable panelViewController, NSError * _Nullable error))completionHandler;

// RN 版本号
- (NSString *_Nonnull)rnVersionForApp;

NS_ASSUME_NONNULL_END
@end

依赖服务

设备控制 UI 业务包主要功能为加载设备，针对不同设备会有不同的一些功能，为保证这些功能正常运行，会依赖如下七个协议：

• ThingFamilyProtocol
• ThingDeviceDetailProtocol
• ThingSettingsProtocol
• ThingOTAGeneralProtocol
• ThingGroupHandleProtocol
• ThingRNCameraProtocol
• ThingCameraProtocol。

各协议的介绍如下：

• ThingFamilyProtocol

  提供加载设备面板所需的当前家庭信息，本协议 必须实现。

  /**
  获取当前的家庭，当前没有家庭的时候，返回 nil。
  
  @return ThingSmartHome
  */
  - (ThingSmartHome *)getCurrentHome;
  

• ThingDeviceDetailProtocol

  设备面板界面右上角单击跳转事件。

  /**
  导航栏右边按钮单击事件，跳转到设备详情页
  
  @param device 设备
  @param group 群组，若有就传
  */
  - (void)gotoDeviceDetailDetailViewControllerWithDevice:(ThingSmartDeviceModel *)device group:(ThingSmartGroupModel *)group;
  

• ThingSettingsProtocol

  面板内触发下发 DP 控制设备时，提供可选开关供 App 发出音效。实现如下方法返回是否开启音效：

  /**
  * 检查是否开启音效
  */
  - (BOOL)soundEnabled;
  

• ThingOTAGeneralProtocol

  进入设备面板时，提供检查设备固件更新的事件。实现如下方法用于检查固件升级：

  /**
  检查设备固件更新，如果有更新会显示展示出固件更新提示
  
  @param deviceModel 需要检查固件升级的设备
  @param isManual 是否手动检测升级
  @param theme 主题色
  YES: 手动检测升级，检测时弹出 loading 框。当有固件新版本时(检测升级、强制升级、提醒升级)，显示 OTA VC。
  NO: 自动检测升级, 检测时不弹出 loading 框。当有强制升级时、提醒升级时，弹出固件升级提示，点确定后显示 OTA VC。
  */
  - (void)checkFirmwareUpgrade:(ThingSmartDeviceModel *)deviceModel isManual:(BOOL)isManual theme:(ThingOTAControllerTheme)theme;
  

• ThingGroupHandleProtocol

  蓝牙 Mesh 品类的设备，面板内有需要跳转到 Mesh 群组界面的事件，若需要跳转 Mesh 群组，实现如下方法：

  /**
  跳转本地 mesh 群组
  
  @available 1.0.0
  @param params
  @param success
  @param failure
  */
  - (void)impl_jumpToMeshLocalGroup:(NSDictionary*)params success:(RCTResponseSenderBlock)success failure:(RCTResponseErrorBlock)failure ;
  

• ThingRNCameraProtocol

  加载摄像头设备 RN 面板的跳转事件。若同时接入摄像头面板业务包 ThingSmartCameraRNPanelBizBundle，则不需要实现。

  /**
  获取摄像头 RN 面板
  @param devId 摄像头设备的 devId
  */
  - (UIViewController *)cameraRNPanelViewControllerWithDeviceId:(NSString *)devId;
  

• ThingCameraProtocol

  加载摄像头设备原生面板的跳转事件。若同时接入摄像头面板业务包 ThingSmartCameraPanelBizBundle，则不需要实现。

  /**
  获取摄像头 Native 面板
  @param devId 摄像头设备的 devId
  @param uiName 摄像头设备的 uiName，不同的 uiName 对应不同版本的面板
  */
  - (UIViewController *)viewControllerWithDeviceId:(NSString *)devId uiName:(NSString *)uiName;
  

使用指南

Objective-C 示例

#import <ThingSmartBizCore/ThingSmartBizCore.h>
#import <ThingModuleServices/ThingFamilyProtocol.h>

- (void)initCurrentHome {
    // 注册要实现的协议
    [[ThingSmartBizCore sharedInstance] registerService:@protocol(ThingFamilyProtocol) withInstance:self];
}

// 实现对应的协议方法
- (ThingSmartHome *)getCurrentHome {
    ThingSmartHome *home = [ThingSmartHome homeWithHomeId:@"当前家庭 ID"];
    return home;
}

Swift 示例

import ThingSmartDeviceKit

class ThingActivatorTest: NSObject,ThingFamilyProtocol{

    func test() {
        ThingSmartBizCore.sharedInstance().registerService(ThingFamilyProtocol.self, withInstance: self)
    }

    func getCurrentHome() -> ThingSmartHome! {
        let home = ThingSmartHome.init(homeId: 111)
        return home
    }

}

清除面板缓存

Objective-C 示例

id<ThingPanelProtocol> impl = [[ThingSmartBizCore sharedInstance] serviceOfProtocol:@protocol(ThingPanelProtocol)];
[impl cleanPanelCache];

Swift 示例

let impl = ThingSmartBizCore.sharedInstance().service(of: ThingPanelProtocol.self) as? ThingPanelProtocol
impl?.cleanPanelCache()

打开面板

Objective-C 示例

id<ThingPanelProtocol> impl = [[ThingSmartBizCore sharedInstance] serviceOfProtocol:@protocol(ThingPanelProtocol)];
// 获取面板视图控制器，自动跳转
if (deviceModel) {
    [impl gotoPanelViewControllerWithDevice:deviceModel group:nil initialProps:nil contextProps:nil completion:^(NSError * _Nullable error) {
    }];
} else if (groupModel) {
    [impl gotoPanelViewControllerWithDevice:nil group:groupModel initialProps:nil contextProps:nil completion:^(NSError * _Nullable error) {
    }];
}

Swift 示例

let impl = ThingSmartBizCore.sharedInstance().service(of: ThingPanelProtocol.self) as? ThingPanelProtocol
// 获取面板视图控制器，自动跳转
impl?.gotoPanelViewController(withDevice: deviceModel, group: nil, initialProps: nil, contextProps: nil, completion: { (error: Error?) in
})

impl?.gotoPanelViewController(withDevice: nil, group: groupModel, initialProps: nil, contextProps: nil, completion: { (error: Error?) in
})

面板调试

成功集成 ThingRNPanelTool 和本地调试版本的React 组件后，通过配网页面扫码功能，扫描以下二维码。

或者通过代码，打开调试页面：

Objective-C

// objc
#import <ThingModuleManager/ThingModule.h>
static NSString *const debugConfig = @"openRNDebugConfig";
[ThingModule.routeService openRoute:debugConfig withParams:nil];

Swift

// swift
import ThingModuleManager
let debugConfig = "openRNDebugConfig"
ThingModule.routeService.openRoute(debugConfig, withParams: nil)

开启调试功能。

1. 单击顶部的滑块，开启 RN 调试功能。
2. 配置调试信息。
   • 产品 ID：调试产品的 PID。请在涂鸦开发者平台的 产品详情 页面，查看产品的 PID 信息。
   • 调试 IP 地址：调试设备所连接网络的 IP 地址。
   • 调试端口：调试设备端口号，默认为 8081。
   • Bundle 名称：本地 Bundle 的名称，默认为 index.ios.bundle。

通过设备列表页面，进入配置的 PID 设备，即可进入调试模式。