更新时间:2022-02-17 05:18:35下载pdf
涂鸦商用照明 App SDK 是专为照明行业的物联网应用提供的移动端开发工具。基于该 SDK,您可以快速实现商用照明及关联场景的 iOS App 功能开发。它适用于新装和存量的商用照明市场,多协议兼容,通过设备管理、能源管控、人因照明等实现绿色建筑与健康建筑。
您可以通过本教程在两小时内快速开发一款自己的 IoT App,并实现如下功能:
您可以点击下方按钮下载 Sample 查看本教程中的示例代码。本次教程按功能模块进行分类,您可以快速找到对应的代码参考学习。
前往 App 开发平台 点击查看 GitHub Sample
在您开始本教程前,请先确保您已经 :
在涂鸦 IoT 平台,注册账号并创建 App 应用,拿到 SDK 的 AppKey,AppSecret。参考 准备工作。
使用 CocoaPods 将涂鸦商业照明 SDK 集成到您的项目中。参考 快速集成。
账号类型分为品牌商账号、企业主账号、企业子账号。品牌商账号下只创建一个商户账号,属于单一的 SaaS 商户模式。
开始之前,请在 Podfile 文件中添加以下内容:
platform :ios, '9.0'
target 'Your_Project_Name' do
pod "TuyaSmartUserToBKit"
end
目前涂鸦商照 SDK 暂不支持 App 账号注册的功能。您需要前往 涂鸦商照管理平台,购买商户账号并开通企业主账号。
接下来,您可以调用 登录接口 登录在上一步中注册的企业主账号。
[[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");
}
];
目前,商业照明限制一个账号仅对应一个唯一商户。所以,在登录账号时,自动匹配商户到账号,您无需传入参数商户的 merchantCode
。
除了账号密码,您还可以使用 验证码登录,或者 提交工单 申请进行 第三方授权登录。
您可以对当前账号进行信息修改,如密码和昵称等。
修改密码
[[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");
}
];
账号管理还支持找回或重置密码、退出账号、修改账号头像、同步更新用户信息等。对应的详细内容,请参考 账号管理。
项目:项目为挂载在某一账号下的可独立操作的单元,也是照明 SDK 中可操作的最大单位。
TuyaLightingProjectManager
类提供。TuyaLightingProject
类提供。TuyaLightingProjectModel
类查询。区域:区域是挂载在某一项目下的可独立操作的单元,区域可以有不定数量的子区域。与项目类似,区域也分为室内和户外区域。
区域的相关类如下:
TuyaLightingAreaManager
类用于创建新的区域。TuyaLightingArea
用于存储修改区域的相关信息,操作区域中的设备等。本章节代码示例和方法说明均为室内项目和区域。
在登录账号后,您首先需要 创建一个项目。
// 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
可置为空。86
、01
等)和 查询一级行政区码 组合,以 ,
拼接。您可以通过调用 查询项目列表 接口查询到商照账号下的所有项目。
TuyaLightingProjectManager *manager = [[TuyaLightingProjectManager alloc] init];
[manager getProjectListWithSuccess:^(NSArray<TuyaLightingProjectModel *> * _Nonnull projectList) {
// self.projectArray = [projectList mutableCopy];
} failure:^(NSError * _Nonnull error) {
}];
对项目的信息修改和删除等其他操作可参考 更新项目信息。
您可以在当前项目下创建区域,创建 室内区域 和 户外区域 为不同接口。在室内项目下,只能创建室内区域,户外项目同理。
[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");
}
];
参数说明
ProjectId
:当前项目 ID。currentAreaId
:当前区域 ID。
roomLevel
:区域等级。
currentAreaId
为 0
时,无论 roomLevel
为多少,该区域都是一级区域。下面的方法会在已有的区域上创建一个子区域。
[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");
}
];
创建区域后您就可以在该区域下连接和管理设备了。
简单来说,配网就是将设备连接并注册到云端,使其拥有与云端远程通信的能力。涂鸦商用照明 App SDK 提供了丰富的配网方式以支持大部分智能设备。如 Wi-Fi 连接,蓝牙连接等。详情请参考 设备配网 和 蓝牙体系。
本文以 Wi-Fi 配网为例,介绍如何使用 SDK 将设备配置到云端。
Wi-Fi 配网方式包括 快连模式(即 EZ 模式)、热点模式(即 AP 模式)、扫 App 二维码三种方式。在之后的 iOS 版本 SDK 中,推荐使用 热点模式 代替 快连模式。主要原因如下:
开始配网之前,SDK 需要在联网状态下从涂鸦 获取配网 Token,然后才可以开始热点模式配网。
projectId
),因此您需要确保账号处于登录状态并至少创建了一个 项目。//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 版本适配
从 iOS 14 版本开始,在设备配网、局域网本地控制时会触发 本地网络 权限弹窗。
目前苹果没有提供任何 API 对此权限进行判断,建议您在相关功能无法正常使用时提示、引导用户检查 系统设置 中的 app设置,确认是否开启了 本地网络 权限。
iOS 13 版本适配
从 iOS 13 版本开始,如果用户没有开启地理位置权限,在已开启 Wi-Fi 权限的前提下,[[TuyaSmartActivator sharedInstance] currentWifiSSID]
将查询不到有效的 Wi-Fi SSID 或 BSSID。在此情况下,iOS 会返回下列默认值:
开始配网前,请确保设备处于待配网状态。操作方法,请参考设备本身提供的使用说明书。
调用 配网接口,需要提供路由器的 SSID(即 Wi-Fi 名称)、密码、从云端获取的 Token 等。
[TuyaSmartActivator sharedInstance].delegate = self;
[[TuyaSmartActivator sharedInstance] startConfigWiFi:TYActivatorModeAP
ssid:ssid
password:password
token:token
timeout:100];
timeout
单位为秒,默认为 100
,您可以设置为任意值。但不建议将此值设置得过小,否则将影响配网结果。
使用热点模式配网时,您需要实现 TuyaSmartActivatorDelegate
协议,以监听配网结果的回调。
@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
}
开始配网操作后,App 会持续广播配网信息,直到配网成功或是超时才停止。如果需要中途取消操作或配网完成,需要调用 停止配网 接口。
[TuyaSmartActivator sharedInstance].delegate = nil;
[[TuyaSmartActivator sharedInstance] stopConfigWiFi];
本章节主要操作对象包含 TuyaSmartDeviceModel
和 TuyaSmartDevice
。
对象 | 说明 | 参考链接 |
---|---|---|
TuyaSmartDeviceModel |
|
设备功能点 |
TuyaSmartDevice | TuyaSmartDevice 存放了设备相关的所有功能,如功能控制,设备固件管理等。您需要用正确的 deviceId 初始化一个 TuyaSmartDevice 。 |
设备管理 |
请确保 ViewController
或其他对象中持有的 TuyaSmartDevice
为全局变量(@property
)。临时的 TuyaSmartDevice
变量可能会因为作用域问题,在初始化时被提前释放,而返回 nil
。
设备成功配网后,您可以在对应的区域下查看 设备列表。
您必须先调用 查询项目详细信息 接口。否则即使配网成功也无法成功查询。
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];
设备的功能点信息存放在 deviceModel
的 schemaArray
中。
TuyaSmartDevice *device = self.device;
NSArray *schemas = device.deviceModel.schemaArray;
schemaArray
存放了该设备的所有功能点信息,每个功能点被封装成一个TuyaSmartSchemaModel
对象。
对于部分功能信息复杂的设备,涂鸦将功能再一次封装在 TuyaSmartSchemaModel
的 property
属性中。具体判断方式如下:
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"]) {
//...
}
//...
在上述代码中,以灯泡为例将其功能点信息展示在 TableView
上。其中:
type
为 bool 的 cell
展示了开关的信息。type
为 value 的 cell
展示了其亮度的信息。控制设备需要将对应的 DP 以 NSDictionary
形式,通过 设备控制 接口改变设备状态或功能。
参数 dps
中可以包含多个功能点,您可以一次同时改变设备的多个状态。
同样以灯泡为例,以下代码分别修改了其开关状态和亮度值。
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
}];
}
如果您需要监听设备状态的改变,如在线状态、移除通知、功能点状态改变等。需要实现 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 {
}
在商用照明的业务场景中,设备更多以群组的形式出现。群组是一个或多个设备按照一定规则的聚合体,通过对群组的控制可以便捷地控制群组中设备。
具体的使用可参考章节 群组管理,或在本文文首下载 Sample 体验开发流程。
该内容对您有帮助吗?
是意见反馈该内容对您有帮助吗?
是意见反馈