设备控制 UI 业务包

功能介绍

设备控制 UI 业务包 是涂鸦智能设备控制面板的核心容器。在涂鸦 智能生活 App SDK iOS 版的基础上，UI 业务包提供设备控制面板的加载和控制的接口封装，加速应用开发过程。主要包括以下功能：

• 面板加载：加载多种设备类型，支持：Wi-Fi、Zigbee、Mesh、Bluetooth LE
• 设备控制：支持单设备和群组的控制，不支持群组管理
• 设备定时

接入组件

在工程的 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
  # TuyaSmart SDK
  pod "TuyaSmartHomeKit"
  # 添加设备控制 UI 业务包
  pod 'TuyaSmartPanelBizBundle'
  # 若需要 IPC 功能，请依赖 IPC 相关插件
  # pod 'TuyaSmartCameraRNPanelBizBundle'
  # pod 'TuyaSmartCameraRNPanelBizBundle'

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

  # 若需要音响面板功能，请依赖相关插件
  # pod 'TuyaRNApi/Speak'

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

注意

• 设备控制 UI 业务包包含开源框架 ReactNative，ReactNatve 版本为 v0.59.11。
  1. 若您的 iOS 工程未集成 ReactNative，请按文档步骤集成涂鸦设备控制 UI 业务包。
  2. 若您的 iOS 工程已集成 ReactNative，需按下面步骤操作，以确定是否可集成涂鸦设备控制 UI 业务包：
     1. 若已集成 ReactNative，且版本 > v0.59.11, 因版本兼容性问题，无法集成涂鸦设备控制 UI 业务包。
     2. 若已集成 ReactNative，且版本 > v0.51, <= v0.59.11, 因 ReactNative 库冲突，不保证能够正常接入涂鸦面板。按下面两种方式进行操作：
        1. 移除您 iOS 工程中的 ReactNative，使用涂鸦设备控制 UI 业务包依赖的 ReactNative v0.59.11。
        2. 将您 iOS 工程中集成的 ReactNative 进行更名，从而避免与涂鸦集成的 ReactNative 冲突。
           若均无法集成成功，则无法接入集成涂鸦设备控制 UI 业务包。

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

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

  NSPhotoLibraryAddUsageDescription
  

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

  NSCameraUsageDescription
  

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

  NSLocationWhenInUseUsageDescription
  

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

  NSMicrophoneUsageDescription
  

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

  NSBluetoothAlwaysUsageDescription
  NSBluetoothPeripheralUsageDescription
  

服务协议

提供服务

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

@protocol TYPanelProtocol <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:(TuyaSmartDeviceModel *)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:(TuyaSmartGroupModel *)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 业务包主要功能为加载设备，针对不同设备会有不同的一些功能，为保证这些功能正常运行，会依赖如下几个协议： TYFamilyProtocol、 TYDeviceDetailProtocol、 TYSettingsProtocol、 TYOTAGeneralProtocol、 TYGroupHandleProtocol、 TYRNCameraProtocol、 TYCameraProtocol。

TYFamilyProtocol

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

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

TYDeviceDetailProtocol

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

/**
 导航栏右边按钮点击事件，跳转到设备详情页

 @param device 设备
 @param group 群组，若有就传
 */
- (void)gotoDeviceDetailDetailViewControllerWithDevice:(TuyaSmartDeviceModel *)device group:(TuyaSmartGroupModel *)group;

TYSettingsProtocol

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

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

TYOTAGeneralProtocol

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

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

TYGroupHandleProtocol

Bluetooth LE 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 ;

TYRNCameraProtocol

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

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

TYCameraProtocol

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

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

使用指南

注意事项

1、任何接口调用之前，务必确认用户已登录。

2、调用设备控制 UI 业务包逻辑前，要先实现 TYFamilyProtocol 中的协议方法getCurrentHome。

Objective-C

#import <TuyaSmartBizCore/TuyaSmartBizCore.h>
#import <TYModuleServices/TYFamilyProtocol.h>

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

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

Swift

import TuyaSmartDeviceKit

class TYActivatorTest: NSObject,TYFamilyProtocol{
  	
    func test() {
        TuyaSmartBizCore.sharedInstance().registerService(TYFamilyProtocol.self, withInstance: self)
    }
    
    func getCurrentHome() -> TuyaSmartHome! {
        let home = TuyaSmartHome.init(homeId: 111)
        return home
    }
    
}

清除面板缓存

Objective-C

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

Swift

let impl = TuyaSmartBizCore.sharedInstance().service(of: TYPanelProtocol.self) as? TYPanelProtocol
impl?.cleanPanelCache()

打开面板

Objective-C

id<TYPanelProtocol> impl = [[TuyaSmartBizCore sharedInstance] serviceOfProtocol:@protocol(TYPanelProtocol)];
// 获取面板视图控制器，自行跳转
if (deviceModel) {
    [impl getPanelViewControllerWithDeviceModel:deviceModel initialProps:nil contextProps:nil completionHandler:^(__kindof UIViewController * _Nullable panelViewController, NSError * _Nullable error) {
    }];
} else if (groupModel) {
    [impl getPanelViewControllerWithGroupModel:groupModel initialProps:nil contextProps:nil completionHandler:^(__kindof UIViewController * _Nullable panelViewController, NSError * _Nullable error) {
    }];
}

Swift

let impl = TuyaSmartBizCore.sharedInstance().service(of: TYPanelProtocol.self) as? TYPanelProtocol
// 获取面板视图控制器，自行跳转
impl?.getPanelViewController(with: deviceModel, initialProps: nil, contextProps: nil, completionHandler: { (vc, err) in

})
impl?.getPanelViewController(with: groupModel, initialProps: nil, contextProps: nil, completionHandler: { (vc, err) in

})