Last Updated on : 2022-02-17 05:18:35download
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:
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
Before you start, the following requirements must be met:
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:
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.
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
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.
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");
}
];
Each account can be assigned to only one merchant. Therefore, during the login, the account automatically matches the merchant. You do not need to pass in the parameter merchantCode
.
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.
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.
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.
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.All examples and methods in this topic are used to process indoor projects and areas.
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);
}];
regionLocationId
can be set to empty.86
and 01
can be concatenated with a level-1 administrative code using a comma (,
).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) {
}];
Project information can be modified or deleted. For more information, see Update project information.
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.
0
or a negative number.roomLevel
: the area level.
When
currentAreaIdis
0, the target area is a level-1 area, no matter what the value of
roomLevel` is.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.
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.
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:
Before the AP pairing process, the SDK must get a pairing token from the cloud in the networked state.
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);
}
];
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.
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:
WLAN
or Wi-Fi
. WLAN
is returned for users in mainland China.00:00:00:00:00:00
.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];
The timeout
parameter is set to 100
by default. Unit: seconds. You can specify any preferred value. ``However, a small value is not recommended. A proper value can ensure the optimal pairing performance.
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
}
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];
In this section, the objects TuyaSmartDeviceModel
and TuyaSmartDevice
are used.
Object | Description | Reference |
---|---|---|
TuyaSmartDeviceModel |
|
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) |
Make sure that TuyaSmartDevice
in ViewController
or other objects is declared as a global variable (@property
). Otherwise, a temporary variable of TuyaSmartDevice
might be released during initialization due to the scope limit, and thus nil
is returned.
After a device is paired, users can query a list of devices that are created for a specific area.
You must first call the API method that enables the query. Otherwise, the query will fail even after the device is paired.
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];
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:
cell
for which type
is set to bool.cell
for which type
is set to value.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.
The parameter dps
can define one or more DPs. Thus, multiple states of a device can be changed in the same call.
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 {
}
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.
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback