设备控制 UI 业务包

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

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

接入组件

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

source "https://github.com/TuyaInc/TuyaPublicSpecs.git"
source 'https://cdn.cocoapods.org/'

target 'your_target_name' do
  # Commercial Lighting SDK
  pod "ThingCommercialLightingKit"
  # 添加设备控制业务包
  pod 'ThingCommercialLightingPanelBizBundle', '~> 1.11.5.1'
  # 若需要扫地机功能，请依赖扫地机相关插件
  # pod 'RNApi/Sweeper'
end

注意事项

涂鸦设备控制 UI 业务包包含了开源框架 React Native，版本为 0.59.10。

• 若您的 iOS 工程未集成 React Native，按本文步骤集成设备控制业务包。

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

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

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

权限要求

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

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

  NSPhotoLibraryAddUsageDescription
  

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

  NSCameraUsageDescription
  

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

  NSLocationWhenInUseUsageDescription
  

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

  NSMicrophoneUsageDescription
  

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

  NSBluetoothAlwaysUsageDescription
  NSBluetoothPeripheralUsageDescription
  

服务协议

提供服务

设备控制业务包实现 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

依赖服务

设备控制业务包主要功能为加载设备，针对不同设备会有不同的一些功能，为保证这些功能正常运行，会依赖如下几个协议：ThingLampProjectDataProtocol、ThingDeviceDetailProtocol、ThingSettingsProtocol、ThingOTAGeneralProtocol、ThingGroupHandleProtocol、ThingRNCameraProtocol 和 ThingCameraProtocol。

ThingLampProjectDataProtocol

提供加载设备面板所需的当前项目信息，必须实现：

/**
 清除当前项目并清除缓存
 */
- (void)clearCurrentProject;

/**
 要使用该 API 获取当前项目，请务必在更新当前 ID 的时候使用该协议的 ’updateCurrentProjectId:‘ API。
 获取当前的项目，当前没有项目的时候，返回 nil。

 @return ThingSmartProject
 */
- (ThingLightingProject *)getCurrentProject;

/**
 更新当前的项目 ID 并写到 GroupUserDefault 缓存中

 @param projectId 项目 ID
 */
- (void)updateCurrentProjectId:(long long)projectId;

/// 获取当前项目 ID
- (long long)currentProjectId;

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 ;

使用指南

• 任何接口调用之前，务必确认用户已登录。
• 调用设备控制业务包逻辑前，要先实现 ThingLampProjectDataProtocol 中的协议方法 getCurrentProject 和方法 currentProjectId。

Objective-C 示例

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

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

// 实现对应的协议方法
- (ThingLightingProject *)getCurrentProject {
    ThingLightingProject *project = [ThingLightingProject projectWithProjectId:@"当前项目id"];
    return project;
}

- (long long)currentProjectId {
        return 111;
}

Swift 示例

import ThingCommercialLightingKit

class ThingActivatorTest: NSObject,ThingLampProjectDataProtocol{


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

    func getCurrentProject() -> ThingLightingProject! {
        let project = ThingLightingProject.init(projectId: 111)
        return project
    }

    func currentProjectId() -> CLongLong {
            return 111
    }

}

清除面板缓存

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 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 = ThingSmartBizCore.sharedInstance().service(of: ThingPanelProtocol.self) as? ThingPanelProtocol
// 获取面板视图控制器，自行跳转
impl?.getPanelViewController(with: deviceModel, initialProps: nil, contextProps: nil, completionHandler: { (vc, err) in

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

})