Device Control UI BizBundle

Device Control UI BizBundle for iOS is the core container of the control panel for each smart device within Tuya’s ecosystem. Based on Tuya Smart Life App SDK for iOS, the UI BizBundle encapsulates the APIs to load and control panels and accelerates the application development process. This UI BizBundle includes both the RN panel and the miniapp panel. If you want to integrate only the miniapp panel, see the MiniApp SDK documentation.

Functional Introduction

The following features are supported:

• Panel loading: supports device panels of multiple protocols, such as Wi-Fi, Zigbee, Bluetooth Low Energy (LE), and Bluetooth mesh.
• Device control: controls a single device and device groups. Device groups cannot be managed.
• Scheduled tasks: configures scheduled tasks for specific devices.

Integrate with the UI BizBundle

Add the components of the Device Control UI BizBundle to the Podfile and run the command 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"
  # Adds the UI BizBundle.
  pod 'ThingSmartPanelBizBundle'
  # Depends on the IPC plug-ins to integrate with their features if needed.
  # pod 'ThingSmartCameraRNPanelBizBundle'

  # Depends on the health and fitness plug-ins to integrate with their capabilities if needed. Note that you must declare the permissions for the app to access the health and fitness capabilities. Otherwise, the request for launching the app on the App Store might be rejected.
  # pod 'ThingSmartHealthExtendBizBundle'

  # Depends on the robot vacuum plug-ins to integrate with their features if needed.
  # pod 'ThingSmartSweeperExtendBizBundle'

  # Depends on the smart speaker plug-ins to integrate with their features if needed.
  # pod 'ThingSmartSpeakExtendBizBundle'
  # pod 'AFNetworking', '~> 4.0.0' 

  # Depends on the home plug-ins provided by mini programs to integrate with their features if needed.
  # pod 'TUNIHomeKit'

  # Panel debugging functionality ⚠️⚠️ The following components are for debugging only and should not be used in production.
  # pod 'ThingRNPanelTool', :configurations => ['Debug']
  # pod 'React', :podspec => './localPath/React.podspec.json' # Debug package link: https://images.tuyacn.com/rnpanel/React.podspec.json 
  # pod 'ThingSmartPanelBizBundle', '5.1x.x.x' # Fixed device control UI business package

end

Things to note

The UI BizBundle includes the open source React Native framework (v0.59.11).

• If your iOS project does not integrate with React Native, follow the procedure in this topic to integrate with the UI BizBundle.

• If your iOS project has integrated with React Native, perform the following steps to check whether the UI BizBundle can be integrated:

  • If React Native has been integrated and its version is later than v0.59.11, the UI BizBundle cannot be integrated due to version incompatibility.
  • If React Native has been integrated and its version is later than v0.51 and equal to or earlier than v0.59.11, the Tuya panels cannot be accessed as expected due to the repeated uses of the React Native library. Use either of the following methods to troubleshoot the problem:
    1. Remove React Native from your iOS project and use React Native v0.59.11 that the UI BizBundle depends on.
    2. Rename React Native that is integrated with your iOS project to avoid the repeated React Native library.

  If both methods failed, the UI BizBundle cannot be integrated.

Permissions

The UI BizBundle encapsulates a series of React Native API methods for panels. This requires specific declarations of privacy and permissions from Apple.

• If a device panel supports album features such as the cloud album, add the following permission declaration to info.plist of your project:

  NSPhotoLibraryAddUsageDescription
  

• If a device panel supports camera features such as the cloud album, add the following permission declaration to info.plist of your project:

  NSCameraUsageDescription
  

• If a device panel supports location features, add the following permission declaration to info.plist of your project:

  NSLocationWhenInUseUsageDescription
  

• If a device panel supports microphone features such as the music light panel, add the following permission declaration to info.plist of your project:

  NSMicrophoneUsageDescription
  

• If a device panel supports Bluetooth features, add the following permission declaration to info.plist of your project:

  NSBluetoothAlwaysUsageDescription
  NSBluetoothPeripheralUsageDescription
  

Service protocols

Provide services

The UI BizBundle relies on the implementation of the protocol ThingPanelProtocol to provide services. You can view the ThingPanelProtocol.h file in the ThingModuleServices component.

@protocol ThingPanelProtocol <NSObject>
NS_ASSUME_NONNULL_BEGIN

// Clears cached data of the panel.
- (void)cleanPanelCache;

/**
 * Returns the device panel controller.
 *
 * @param deviceModel  The device model.
 * @param initialProps  The custom initialization parameter to be set in `initialProps` of the RN application with the key 'extraInfo'.
 * @param contextProps  The context of the custom panel to be set in `Panel Context` with the key 'extraInfo'.
 * @param completionHandler The callback returns the view controller.
 */
- (void)getPanelViewControllerWithDeviceModel:(ThingSmartDeviceModel *)deviceModel
                                 initialProps:(nullable NSDictionary *)initialProps
                                 contextProps:(nullable NSDictionary *)contextProps
                            completionHandler:(void (^ _Nullable)(__kindof UIViewController * _Nullable panelViewController, NSError * _Nullable error))completionHandler;

/**
 * Returns the group panel controller.
 *
 * @param groupModel The group model.
 * @param initialProps  The custom initialization parameter to be set in `initialProps` of the RN application with the key 'extraInfo'.
 * @param contextProps  The context of the custom panel to be set in `Panel Context` with the key 'extraInfo'.
 * @param completionHandler The callback returns the view controller.
 */
- (void)getPanelViewControllerWithGroupModel:(ThingSmartGroupModel *)groupModel
                                initialProps:(nullable NSDictionary *)initialProps
                                contextProps:(nullable NSDictionary *)contextProps
                           completionHandler:(void (^ _Nullable)(__kindof UIViewController * _Nullable panelViewController, NSError * _Nullable error))completionHandler;

// The RN version number.
- (NSString *_Nonnull)rnVersionForApp;

NS_ASSUME_NONNULL_END
@end

Depend on services

This UI BizBundle is used to load devices and implement features of different devices. For this purpose, implement the following dependent protocols:

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

These protocols are described in the following sections:

• ThingFamilyProtocol

  Provides current home information required by the UI BizBundle. This protocol must be implemented.

  /**
  Returns the current home. If the current user does not have a home, `nil` is returned.
  
  @return ThingSmartHome
  */
  - (ThingSmartHome *)getCurrentHome;
  

• ThingDeviceDetailProtocol

  Implements the activity of tapping and navigation in the top right corner of the device panel.

  /**
  Tap the button in the top right corner of the device panel to navigate to the device details page.
  
  @param device The device.
  @param group The group if any. It is optional.
  */
  - (void)gotoDeviceDetailDetailViewControllerWithDevice:(ThingSmartDeviceModel *)device group:(ThingSmartGroupModel *)group;
  

• ThingSettingsProtocol

  Provides the optional switch to enable a certain sound effect on the app when device control DPs are sent. The following API method is implemented to return whether the sound effect is enabled:

  /**
  * Indicates whether the sound effect is enabled.
  */
  - (BOOL)soundEnabled;
  

• ThingOTAGeneralProtocol

  Enters the device panel and checks for device firmware updates. The following API method is implemented to check for device firmware updates:

  /**
  Checks for device firmware updates, and if any, shows the update prompt.
  
  @param deviceModel The device that checks for firmware updates.
  @param isManual Specifies whether to enable manual checks for firmware updates.
  @param theme The theme color.
  `YES`: Manually check for updates. A loading dialog box appears during the check. If a new update is found (check for updates, forced updates, and update notifications), OTA VC is displayed.
  `NO`: Automatically check for updates. A loading dialog box does not appear during the check. When forced updates and update notifications are enabled, the firmware update prompt appears. Click **OK** to show OTA VC.
  */
  - (void)checkFirmwareUpgrade:(ThingSmartDeviceModel *)deviceModel isManual:(BOOL)isManual theme:(ThingOTAControllerTheme)theme;
  

• ThingGroupHandleProtocol

  Implements the activity of navigation to a mesh group page on the panel for a Bluetooth mesh device. The following API method is implemented:

  /**
  Navigates to a local mesh group.
  
  @available 1.0.0
  @param params
  @param success
  @param failure
  */
  - (void)impl_jumpToMeshLocalGroup:(NSDictionary*)params success:(RCTResponseSenderBlock)success failure:(RCTResponseErrorBlock)failure ;
  

• ThingRNCameraProtocol

  Navigates to and loads the RN panel for an IPC. If the BizBundle ThingSmartCameraRNPanelBizBundle is integrated, this protocol is not required.

  /**
  Returns the IPC RN panel.
  @param devId The device ID of the IPC.
  */
  - (UIViewController *)cameraRNPanelViewControllerWithDeviceId:(NSString *)devId;
  

• ThingCameraProtocol

  Navigates to and loads the native panel for an IPC. If the BizBundle ThingSmartCameraPanelBizBundle is integrated, this protocol is not required.

  /**
  Returns the IPC native panel.
  @param devId The device ID of the IPC.
  @param uiName The UI name of the IPC. The value varies depending on different panel versions.
  */
  - (UIViewController *)viewControllerWithDeviceId:(NSString *)devId uiName:(NSString *)uiName;
  

Usage instruction

Objective-C:

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

- (void)initCurrentHome {
    // Registers the protocol to be implemented.
    [[ThingSmartBizCore sharedInstance] registerService:@protocol(ThingFamilyProtocol) withInstance:self];
}

// Implements the protocol method.
- (ThingSmartHome *)getCurrentHome {
    ThingSmartHome *home = [ThingSmartHome homeWithHomeId:@"Current home 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
    }

}

Clear cached data of the panel

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()

Open a device panel

Objective-C:

id<ThingPanelProtocol> impl = [[ThingSmartBizCore sharedInstance] serviceOfProtocol:@protocol(ThingPanelProtocol)];
// Returns the panel view controller and enables automatic navigation.
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
// Returns the panel view controller and enables automatic navigation.
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
})

Panel debugging

After successfully integrating ThingRNPanelTool and the local debugging version of the React component, scan the following QR code using the scanning feature on the pairing page:

Alternatively, run the following code to open the debugging page:

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)

To enable the debugging feature:

1. Tap the switch button at the top to enable the RN debugging mode.

2. Configure debugging information.

   • Product ID: The PID of the product to be debugged. View the PID information on the Product Development page of the Tuya Developer Platform.
   • Debugging IP address: The IP address of the network to which the device for debugging is connected.
   • Debugging port: The port number of the device for debugging. The port number is 8081 by default.
   • Bundle name: The name of the local Bundle. The name is index.ios.bundle by default.

   On the device list page, find the device with the configured PID to enter the debugging mode.