Quick Start with Commercial Lighting App SDK for iOS

Tuya Commercial Lighting App SDK is a mobile development tool specifically for IoT applications in the lighting industry. With the Commercial Lighting App SDK, you can quickly implement app functionality suitable for commercial lighting and scene linkage. This SDK is compatible with multiple protocols and can meet existing and new commercial lighting demands. Green buildings and healthy buildings can be implemented with smart features, such as device management, energy management, and human-centric lighting.

This tutorial walks you through a few steps to get started with the SDK and develop a preferred IoT app within two hours. You will learn how to implement the following features:

• Register a merchant account on the Tuya Commercial Lighting Console and manage this account on the app.
• Create and manage a project and an area for the merchant account.
• Connect to and control devices in the area.

You can go to GitHub and download the sample code for the different features mentioned in this tutorial. Then, you can integrate the required sample code into your SDK development on the Tuya IoT Platform.

App SDK Development GitHub Sample

Preparation

Before you start, the following requirements must be met:

1. An account of the Tuya IoT Platform is registered, an app is built on the platform, and the values of AppKey and AppSecret of the SDK are obtained. For more information, see Preparation.

   Before you start, you must request a commercial lighting account that can be either of the following types:

   • Type 1: Trial account
     • Follow the instructions in Preparation to open the Get SDK tab, and click subscribe to the trial version at the top of the page to get a 30-day trial account.
     • During the trial, you can log in to the app developed by the SDK. After the app expires, login to the app is disabled. In this case, you cannot subscribe to the trial version again. You must subscribe to the official version to continue using the app.
   • Type 2: Standard account
     • You can subscribe to the value-added service Commercial Lighting PaaS.
     • The validity of the standard version depends on your purchased service plan, and the official app SDK needs to be coupled with Commercial Lighting SaaS or open APIs. To integrate Commercial Lighting PaaS, you must provide Tuya’s account manager with the domain name and domain certificate that are required for the configuration.

2. Tuya Commercial Lighting App SDK for iOS is integrated into your project with CocoaPods. For more information, see Fast Integration with Commercial Lighting App SDK for iOS.

User management

Users are classified into brand owner accounts, enterprise main accounts, and enterprise sub-accounts. A typical service mode is the single SaaS merchant mode, where only one merchant account is created for a brand owner account.

Before you get started, add the following code block to the Podfile:

platform :ios, '9.0'

target 'Your_Project_Name' do
	pod "TuyaSmartUserToBKit"
end

Step 1: Register an enterprise main account

Currently, Tuya Commercial Lighting App SDK does not support registration on the app. You must go to the Tuya Commercial Lighting Console to purchase a merchant account plan and enable an enterprise main account.

Step 2: Log in to the account with the password

You can call the API method loginMerchantByPassword to implement login to the enterprise main account.

 [[TuyaSmartUser sharedInstance]loginMerchantByPassword:@"your_password"
                                            countryCode:@"your_countryCode"
                                               username:@"your_username"
                                           merchantCode:nil
                                   multiMerchantHanlder:nil
                                                success:^{
                                                       NSLog(@"login success");
                                             } failure:^(NSError *error) {
                                                      NSLog(@"login error");
                                              }
];

In addition to the account and password, you can also implement login with a verification code, or submit a ticket to enable third-party login.

Step 3: Manage the account

The account information, such as the password and nickname, can be modified.

Change the password

[[TuyaSmartUser sharedInstance]resetMerchantPasswordWithUsername:@"your_user_name"
                                                     countryCode:@"country_code"
                                                     oldPassword:@"old_password"
                                                     newPassword:@"new_password"
                                                         success:^{
                                                                     NSLog(@"reset password success");
                                                                  } failure:^(NSError *error) {
                                                                     NSLog(@"reset password failure");
                                                       }
];

Account management supports additional features. For example, reset the password, exit the account, change the avatar, and synchronize and update user information. For more information, see Merchant Account Information.

Project and area management

Concepts

• A project is an independent unit that is managed by a user. It is also the maximum unit used to manage resources based on the Commercial Light SDK.

  • A user can manage one or more projects.
  • Projects are classified into indoor and outdoor projects. For more information, see Project Management.
  • A newly created user is not assigned projects. Projects must be created after login to enable follow-up operations, such as device pairing and control.
    The following project classes provide a bunch of features:
    • TuyaLightingProjectManager: query project configurations and projects and create projects.
    • TuyaLightingProject: query, update, and delete project information.
    • TuyaLightingProjectModel](https://developer.tuya.com/en/docs/app-development/ios-saas-lighting-project?id=Kaoea3fnfh8ii#title-13-TuyaLightingProjectModel): query project information, such as the project name, area, and person in charge of the project.

• An area is an independent unit that is managed in a specific project. An area can be configured with one or more sub-areas. Similar to projects, areas are classified into indoor and outdoor areas.
  The following area classes provide a bunch of features:

  • TuyaLightingAreaManager: create a new area.
  • TuyaLightingArea: store and modify area information and manage devices in an area.

Step 1: Create an indoor project

After login, a project must be created.

// Create an indoor project
   [[TuyaLightingProjectManager new] createProjectWithProjectType:TuyaLightingProjectTypeIndoor
                                                      projectName:@"your projectName"
                                                       leaderName:@"your leaderName"
                                                     leaderMobile:@"your leaderMobile"
                                                    detailAddress:@"your detailAddress"
                                                 regionLocationId:nil
                                                          success:^(id result) {
                                                          NSLog(@"create success");
                                                          // you can get
                                                        } failure:^(NSError *error) {
                                                          NSLog(@"create failure: %@", error);
                                                        }];

Step 2: Query projects for a user

You can call the API method getProjectListWithSuccess to query all projects for a user.

TuyaLightingProjectManager *manager = [[TuyaLightingProjectManager alloc] init];
[manager getProjectListWithSuccess:^(NSArray<TuyaLightingProjectModel *> * _Nonnull projectList) {

		//  self.projectArray = [projectList  mutableCopy];

	} failure:^(NSError * _Nonnull error) {

	}];

Step 3: Create an indoor area

You can call different API methods to create indoor and outdoor areas for the current project. For more information, see Create an indoor area and Create an outdoor area. Only indoor areas can be created for indoor projects, and only outdoor areas can be created for outdoor projects.

[TuyaLightingAreaManager createAreaWithProjectId:@" the current ID"
                                   currentAreaId:0
                                            name:@"area name"
                                       roomLevel:1
                                         success:^(id result) {
                                                     NSLog(@"success");
                                                   // you can get the new area id here
                                       } failure:^(NSError *error) {
                                                   NSLog(@"failure");
                                      }
];

Parameters

• ProjectId: the current project ID.
• currentAreaId: the current area ID.
  • If no areas are created or a level-1 area is required, this parameter can be any value. To avoid conflict, we recommend that you set the value to 0 or a negative number.
  • To create a parent area or sub-area based on an existing area, set the value to the existing area ID.
    
    You can also call an API method to create a parent area or a sub-area. For more information, see Create a parent area and Create a sub-area.
• roomLevel: the area level.
  • When currentAreaIdis0, the target area is a level-1 area, no matter what the value of roomLevel` is.
  • `If an existing area ID is specified, a sub-area or parent ara is created based on the existing area ID.

The following example shows how to create a sub-area for an existing area.

[TuyaLightingAreaManager createAreaWithProjectId:@" the current ID"
                                   currentAreaId:  self.area.areaId
                                            name:@"area name"
                                       roomLevel:self.area.roomLevel+1
                                         success:^(id result) {
                                                     NSLog(@"success");
                                                   // you can get the new area id here
                                       } failure:^(NSError *error) {
                                                   NSLog(@"failure");
                                      }
];

Then, devices in the area can be connected to and managed.

Device pairing

After users pair a device with the app, the device is connected and registered to the cloud and can communicate with the cloud. The Commercial Lighting App SDK empowers smart devices to be paired in multiple pairing modes. For example, they can be paired over Wi-Fi and Bluetooth. For more information, see Device Pairing (iOS) and Bluetooth Series.

Pairing modes

In this section, the Wi-Fi pairing modes are used as an example to describe how to integrate the SDK and register a device to the cloud.

Wi-Fi pairing modes include: Wi-Fi Easy Connect (EZ), Access Point (AP), and QR code. In the later versions of the Commercial Lighting App SDK for iOS, we recommend that you use the AP mode instead of the Wi-Fi EZ mode. The former trumps the latter when it comes to the following aspects:

• Compared with the Wi-Fi EZ mode, the AP mode results in a higher success rate, optimal reliability, and fewer compatibility requirements for mobile phones and routers.
• The app built with Xcode 12.5 cannot send the EZ pairing data packets from iPhone that runs iOS 14.5 or later. In this case, the permission com.apple.developer.networking.multicast must be enabled for the app. This permission must be approved by Apple before it can be enabled. As a temporary solution, you can use an earlier Xcode version, but the AP mode is still recommended.

Get the pairing token

Before the AP pairing process, the SDK must get a pairing token from the cloud in the networked state.

• The token is valid for 10 minutes and expires immediately after the device is paired. A new token must be generated if the device needs to be paired again.
• To get a token, the current value of projectId must be provided. Therefore, during this process, the account must be in the logged-in state and at least one project is created for the account.

//The following parameter HomeId equals to the projectId.
[[TuyaSmartActivator sharedInstance] getTokenWithHomeId:projectId
                                                success:^(NSString *token) {
		                                    //  NSLog(@"getToken success: %@", token);
		                                   // You could start ConfigWiFi now.
	                                      } failure:^(NSError *error) {
		                                 //NSLog(@"getToken failure: %@", error.localizedDescription);
	                                     }
];

Compatibility with iOS

iOS 14

Starting from iOS 14, when users implement device pairing or control over a local area network (LAN), the local network privacy setting dialog box is triggered.

• The app can send data to the LAN only after users tap OK.
• Otherwise, if users tap Don’t Allow, the app cannot access the LAN.

Currently, Apple does not provide APIs to process this privacy setting. We recommend that you guide users to allow the app to access LAN data when features that require LAN connection cannot work. Specifically, go to Settings, choose Privacy > Local Network, and then allow the app to access the LAN.

iOS 13

Starting from iOS 13, if users do not allow the app to access location data, when the Wi-Fi feature is enabled, [[TuyaSmartActivator sharedInstance] currentWifiSSID] cannot return a valid Wi-Fi service set identifier (SSID) or basic service set identifier (BSSID). In this case, iOS returns the following default values:

• SSID: WLAN or Wi-Fi. WLAN is returned for users in mainland China.
• BSSID: 00:00:00:00:00:00.

Start pairing

Before the pairing process is started, the device must keep a state pending pairing. To set the device to this state, you can guide users to follow the device user manual.

To call the API method startConfigWiFi, you must provide the SSID of the router (the Wi-Fi name), password, and the token obtained from the cloud.

[TuyaSmartActivator sharedInstance].delegate = self;
[[TuyaSmartActivator sharedInstance] startConfigWiFi:TYActivatorModeAP
                                                ssid:ssid
                                            password:password
                                               token:token
                                             timeout:100];

In AP pairing mode, you must implement the protocol TuyaSmartActivatorDelegate and listen for the callback of the pairing result.

@interface xxxViewController () <TuyaSmartActivatorDelegate>

- (void)activator:(TuyaSmartActivator *)activator didReceiveDevice:(TuyaSmartDeviceModel *)deviceModel error:(NSError *)error {
    if (deviceModel && error == nil) {
             //success
            // NSLog(@"connected success: %@", deviceModel.name);
    }

    if (error) {
        //fail
    }

   // stop config
}

(Optional) Stop pairing

After the pairing process is started, the app continuously broadcasts the pairing data until a device is paired or the process times out. To allow users to cancel or complete pairing during the process, you must call the API method that supports pairing.

[TuyaSmartActivator sharedInstance].delegate = nil;
[[TuyaSmartActivator sharedInstance] stopConfigWiFi];

Device control

In this section, the objects TuyaSmartDeviceModel and TuyaSmartDevice are used.

Object	Description	Reference
TuyaSmartDeviceModel	Similar to TuyaSmartHomeModel and TuyaSmartHome, TuyaSmartDeviceModel stores the basic information about a device, such as the ID, name, and icon. The dps property of NSDictionary type for the class TuyaSmartDeviceModel defines the current device status. The status is known as one or more data points (DPs). Each DP stores the features of a device. A DP can define a switch of Boolean type or the brightness of Value type. To enable device control, the DPs can be queried and modified.	DPs
TuyaSmartDevice	TuyaSmartDevice stores all data of device features, such as device control and firmware management. You must use the correct value of deviceId to initialize TuyaSmartDevice.	Device Management (iOS)

Query paired devices

After a device is paired, users can query a list of devices that are created for a specific area.

long long projectId = TYCacheManager.sharedInstance.projectId;
 TuyaLightingArea *area = [[TuyaLightingArea alloc] initWithAreaId:self.areaId projectId:projectId];

[area getDeviceListWithOffsetKey:@"1"
                                 tag:@""
                             success:^(NSArray<TuyaSmartDeviceModel *> * _Nonnull devices, NSString * _Nonnull nextOffsetKey, BOOL end) {

                           self.deviveList = devices ;

    } failure:NULL];

View device information

• DP data is stored in schemaArray of deviceModel.

  TuyaSmartDevice *device = self.device;
  NSArray *schemas = device.deviceModel.schemaArray;
  

• All DP data is stored in schemaArray. Each DP is encapsulated as the TuyaSmartSchemaModel object.

  

• Certain complex DPs are further encapsulated in property of TuyaSmartSchemaModel. Example:

  NSString *type = [schema.type isEqualToString:@"obj"] ? schema.property.type : schema.type;
  
  	if ([type isEqualToString:@"bool"]) {
  
  		SwitchTableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"switchCell"];
  		if (cell == nil){
  			cell = [[[NSBundle mainBundle] loadNibNamed:@"SwitchTableViewCell" owner:self options:nil] lastObject];
  
  			cell.label.text = schema.name;
  			[cell.switchButton setOn:[dps[schema.dpId] boolValue]];
  
  			};
  
  		}
  		return cell;
  
  	}
  
  else if ([type isEqualToString:@"value"]) {
  
  		SliderTableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"valueCell"];
  		if (cell == nil){
  			cell = [[[NSBundle mainBundle] loadNibNamed:@"SliderTableViewCell" owner:self options:nil] lastObject];
  
  			cell.label.text = schema.name;
  			cell.detailLabel.text = [dps[schema.dpId] stringValue];
  			cell.slider.minimumValue = schema.property.min;
  			cell.slider.maximumValue = schema.property.max;
  			cell.slider.value = [dps[schema.dpId] floatValue];
  
  			};
  		};
  		return cell;
  
  	}
  
  	else if ([type isEqualToString:@"enum"]) {
  		//...
  	}
  
  	//...
  

In the preceding code block, the DPs of a smart light are displayed in TableView. The following settings are applied:

• The switch data is displayed in cell for which type is set to bool.
• The brightness data is displayed in cell for which type is set to value.

Control a device

To enable device control, you must call the device control API method and send DPs in the NSDictionary format to change device status or features.

In the following code block, a smart light is used as an example to change its switch status and brightness value.

if ([type isEqualToString:@"bool"]) {

        SwitchTableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"switchCell"];
        if (cell == nil){
            cell = [[[NSBundle mainBundle] loadNibNamed:@"SwitchTableViewCell" owner:self options:nil] lastObject];

            cell.label.text = schema.name;
            [cell.switchButton setOn:[dps[schema.dpId] boolValue]];
            cell.isReadOnly = isReadOnly;
           // turn on/off when click the UISwitch
            cell.switchAction = ^(UISwitch *switchButton) {
                [weakSelf publishMessage:@{schema.dpId: [NSNumber numberWithBool:switchButton.isOn]}];
            };

        }
        return cell;

    }

else if ([type isEqualToString:@"value"]) {

        SliderTableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"valueCell"];
        if (cell == nil){
            cell = [[[NSBundle mainBundle] loadNibNamed:@"SliderTableViewCell" owner:self options:nil] lastObject];

            cell.label.text = schema.name;
            cell.detailLabel.text = [dps[schema.dpId] stringValue];
            cell.slider.minimumValue = schema.property.min;
            cell.slider.maximumValue = schema.property.max;
            [cell.slider setContinuous:NO];
            cell.slider.value = [dps[schema.dpId] floatValue];

            // change the value when tap the UISlider
            cell.sliderAction = ^(UISlider * _Nonnull slider) {
                float step = schema.property.step;
                float roundedValue = round(slider.value / step) * step;
                [weakSelf publishMessage:@{schema.dpId : [NSNumber numberWithInt:(int)roundedValue]}];
            };
         };
        return cell;

    }

- (void)publishMessage:(NSDictionary *) dps {
    [self.device publishDps:dps success:^{
            // change success
    }
    failure:^(NSError *error) {
         // change failed
    }];
}

To listen for changes in device status, such as getting online, removal notifications, and DP data changes, you must implement the protocol TuyaSmartDeviceDelegate.

self.device = [TuyaSmartDevice deviceWithDeviceId:## your deviceId];
self.device.delegate = self;

#pragma mark - TuyaSmartDeviceDelegate

- (void)device:(TuyaSmartDevice *)device dpsUpdate:(NSDictionary *)dps {
	// The DPS status of the device has changed, refresh UI
}

- (void)deviceInfoUpdate:(TuyaSmartDevice *)device {
	//The other status of the device has changed(like name , online status), refresh UI
}

- (void)deviceRemoved:(TuyaSmartDevice *)device {
	//the current device had been removed
}

- (void)device:(TuyaSmartDevice *)device signal:(NSString *)signal {

}

- (void)device:(TuyaSmartDevice *)device firmwareUpgradeProgress:(NSInteger)type progress:(double)progress {

}

- (void)device:(TuyaSmartDevice *)device firmwareUpgradeStatusModel:(TuyaSmartFirmwareUpgradeStatusModel *)upgradeStatusModel {

}

Next step

In most commercial lighting scenarios, devices are managed in groups. A group is an aggregation of one or more devices that follow certain rules. This way, devices can be easily controlled by group.

For more information, see Group Management. You can also download the GitHub sample as mentioned at the beginning of this tutorial to get your development up and running.