安卓版智能生活 App SDK 开发入门教程

更新时间:2023-05-22 06:38:22下载pdf

涂鸦智能生活 App SDK 安卓版提供了即全面又灵活的 IoT App 开发模式。您可以通过本教程在两小时内快速开发一款自己的 IoT App,并实现如下功能:

  • 使用手机号码注册并登录一个用户账号。
  • 在登录状态下创建一个家庭,并查看和修改家庭信息。
  • 使用热点模式为设备配网并连接设备。
  • 使用自己创建的 App 控制该设备。

您可以点击下方按钮下载 Sample 查看本教程中的示例代码。本次教程按功能模块进行分类,您可以快速找到对应的代码参考学习。

前往 App 开发平台 点击查看 GitHub Sample

效果展示

学习完本教程,并且结合一定的面板开发后,您可以创建一个类似以下安卓 App 的 Demo。

安卓版智能生活 App SDK 开发入门教程 安卓版智能生活 App SDK 开发入门教程

准备工作

在您开始本教程前,请先确保您已经 :

  1. 在涂鸦 IoT 平台注册账号并创建 App,获取 SDK 的 AppKey 和 AppSecret。详情请参考 准备工作

  2. 使用 Android Studio 将安卓版智能生活 App SDK 集成到您的项目中。详情请参考 快速集成

    本教程在 macOS 上使用 Android Studio v4.1.2 集成智能生活 App SDK。针对 SDK 版本 v3.26.5,注意项目 build.gradle 中配置的 minSdkVersion 最低为 21,否则会报错。

第一步:注册用户账号

本模块中,仅演示使用手机号注册登录。除此以外,涂鸦智能生活 App SDK 还提供了邮箱、第三方、匿名等多种注册登录方式。详情请参考 用户账户系统

注册用户账号时:

  • 您需要提供 countryCode 参数来区分注册地区,用于就近选择涂鸦 IoT 平台的可用区。如中国大陆为 86,美国为 1。有关可用区相关概念,请参考 涂鸦云平台介绍

    各个可用区的数据是相互独立的,因此在 中国大陆(86) 注册的账号,在 美国(1) 地区无法使用(提示用户不存在)。

  • 您将频繁地调用对象 User。它存储了当前用户的所有信息,通过 TuyaHomeSdk.getUserInstance() 获取到 ITuyaUser,它提供了相关的登录注册方法。详情请参考 User

查询验证码服务可用地区

为了加强用户信息的数据安全,涂鸦优化验证码和添加了账号限制。只有验证码服务可用的地区,才可以发送验证码。您需要先查询您的开发者账号是否已经在从涂鸦 IoT 平台开通验证码服务的可用地区列表。

TuyaHomeSdk.getUserInstance().getWhiteListWhoCanSendMobileCodeSuccess(new IWhiteListCallback() {
			@Override
			public void onSuccess(WhiteList whiteList) {
				Toast.makeText(mContext, "Whitelist Success:" + whiteList.getCountryCodes(), Toast.LENGTH_SHORT).show();
			}

			@Override
			public void onError(String code, String error) {
				Toast.makeText(mContext, "code: " + code + "error:" + error, Toast.LENGTH_SHORT).show();
			}
		});

返回值 whiteList 表示一个或多个国家或地区,以 , 隔开取值,例如 8601。有关可用区编号列表,请参考 涂鸦云平台介绍

目前中国大陆默认已开通验证码服务。若您希望自己的应用发布在其他国家或地区,则必须验证开通地区,并联系您的涂鸦客户经理或 提交工单 开通该服务。

获取注册账号的验证码

与大部分注册流程类似,用户必须先获取验证码。无论是手机或是邮箱,您都可以使用统一的获取验证码接口在注册及后续密码修改,验证码登录,信息完善等操作中获取相应的验证码。

TuyaHomeSdk.getUserInstance().sendVerifyCodeWithUserName(String userName, String region, String countryCode, int type, IResultCallback callback);

参数说明

参数 说明
userName 手机号码/邮箱账号
region 区域,默认填写:“” 即可
countryCode 手机区号:如 “86”
callback 回调
type 发送验证码类型:
1:注册
2:登录
3:重置密码

请确保所传参数 type1,否则将无法正常注册。

TuyaHomeSdk.getUserInstance().sendVerifyCodeWithUserName("xxx6/7825***66@123.com", "", "86", 1/2/3, new IResultCallback() {
			@Override
			public void onError(String code, String error) {
				Toast.makeText(mContext, "code: " + code + "error:" + error, Toast.LENGTH_SHORT).show();
			}

			@Override
			public void onSuccess() {
				Toast.makeText(mContext, "Get code success:", Toast.LENGTH_SHORT).show();
			}
		});

使用手机号码注册账号

使用手机号码注册账号前,您需要调用获取验证码接口,传入相应 type。然后调用号码注册接口,需要上传国家码、手机号码、密码以及获取到的验证码。更多详情,请参考 使用手机账号注册和登录安卓用户账号

TuyaHomeSdk.getUserInstance().registerAccountWithPhone("86","13666666666","123456","124332", new IRegisterCallback() {
	@Override
	public void onSuccess(User user) {
		Toast.makeText(mContext, "Register success", Toast.LENGTH_SHORT).show();
	}
	@Override
	public void onError(String code, String error) {
		Toast.makeText(mContext, "code: " + code + "error:" + error, Toast.LENGTH_SHORT).show();
	}
});

使用手机号码登录账号

在注册成功后,您就可以使用国家码、手机号和密码登录账号。

TuyaHomeSdk.getUserInstance().loginWithPhonePassword("86", "13666666666", "123456", new ILoginCallback() {
	@Override
	public void onSuccess(User user) {
		Toast.makeText(mContext, "Login success:" +TuyaHomeSdk.getUserInstance().getUser().getUsername(), Toast.LENGTH_SHORT).show();
	}

	@Override
	public void onError(String code, String error) {
		Toast.makeText(mContext, "code: " + code + "error:" + error, Toast.LENGTH_SHORT).show();
	}
});

第二步:创建和管理家庭

家庭是智能生活 App SDK 开发下实际场景的最大单位。IoT 设备的添加、编辑、移除、状态变化的监听基于家庭下。您可以在用户账号下创建任意多个家庭。在指定家庭下,您还可以添加并管理多个房间和用户成员。

操作家庭模块时,您将频繁调用对象 ITuyaHomeManagerHomeBean

对象 说明
HomeBean 存放了家庭的基本信息,如 ID、名字、位置等。
TuyaSmartHome 存放了家庭相关的所有功能,如单个家庭信息管理,家庭下的家庭成员管理,房间管理等。ITuyaHomeManager 需要使用正确的 homeIdTuyaHomeSdk.getHomeManagerInstance() 进行初始化。

创建家庭

在登录状态下您可以创建家庭。之后对于房间,成员,设备等对象的管理都基于家庭下。创建家庭需要通过 ITuyaHomeManager 调用 创建家庭 接口。

TuyaHomeSdk.getHomeManagerInstance().createHome(name, lon, lat, geoName, rooms, new ITuyaHomeResultCallback() {
		@Override
		public void onSuccess(HomeBean bean) {
			// do something
		}
		@Override
		public void onError(String errorCode, String errorMsg) {
			// do something
		}
	});

查询家庭列表

在登录状态下您可以直接获取家庭列表。如果您还没创建过家庭,将返回 空数组

TuyaHomeSdk.getHomeManagerInstance().queryHomeList(new ITuyaGetHomeListCallback() {
		@Override
		public void onSuccess(List<HomeBean> homeBeans) {
			// do something
		}
		@Override
		public void onError(String errorCode, String error) {
			// do something
		}
	});

获取家庭详细信息

在获取家庭列表或通过 HomeId 初始化得到的 ITuyaHomeManagerHomeBeanroomListdeviceListgroupListsharedDeviceListsharedGroupList 等属性均为空。您需要调用 家庭的详细信息 接口获取上述属性的具体内容。

TuyaHomeSdk.newHomeInstance(10000).getHomeDetail(new ITuyaHomeResultCallback() {
		@Override
		public void onSuccess(HomeBean bean) {
			// do something
		}
		@Override
		public void onError(String errorCode, String errorMsg) {
			// do something
		}
	});

最佳实践

在创建了家庭后,后续房间成员、用户配网等相关操作均需要基于某一特定家庭。因此建议您将这一特定家庭作为 App 的全局变量存储。当然,您也可以在本地随时切换当前家庭,涂鸦 IoT 平台并不会记录这一信息。在本教程和配套的 Sample 中,默认将列表的第一个家庭设为当前家庭。

第三步:设备配网

简单来说,配网就是将设备连接并注册到云端,使其拥有与云端远程通信的能力。涂鸦智能生活 App SDK 提供了丰富的配网方式以支持大部分智能设备。如 Wi-Fi 连接,蓝牙连接等。详情请参考 设备配网蓝牙体系

配网方式介绍

本模块以 Wi-Fi 配网为例介绍如何使用 SDK 将设备配置到云端。Wi-Fi 配网方式包括 快连模式(EZ)热点模式(AP)、扫 App 二维码三种方式。

相比 EZ 模式,AP 模式成功率高、可靠性好,对手机和路由器有兼容性要求小。配网成功率高于 EZ 模式。因此,在之后的版本中,我们推荐使用 AP 模式 代替 EZ 模式

获取配网 Token

开始配网之前,SDK 需要在联网状态下从涂鸦云获取配网 Token,然后才可以开始热点模式配网。Token 的有效期为 10 分钟,且配置成功后就会失效,再次配网需要重新获取。获取 Token 需要上传当前的 homeId,因此您需要确保账号处于登录状态并至少创建了一个家庭。

TuyaHomeSdk.getActivatorInstance().getActivatorToken(homeId,
		new ITuyaActivatorGetToken() {

			@Override
			public void onSuccess(String token) {

			}

			@Override
			public void onFailure(String s, String s1) {

			}
		});

开始设备配网

调用 配网接口 需要提供 builderbuilder 中需要路由器的 SSID(即 Wi-Fi 名称)、密码、从云端获取的 Token 等。

ActivatorBuilder builder = new ActivatorBuilder()
		.setSsid(ssid)
		.setContext(context)
		.setPassword(password)
		.setActivatorModel(ActivatorModelEnum.TY_EZ)
		.setTimeOut(timeout)
		.setToken(token)
		.setListener(new ITuyaSmartActivatorListener() {

				@Override
				public void onError(String errorCode, String errorMsg) {

				}

				@Override
				public void onActiveSuccess(DeviceBean devResp) {
					//多个设备同时配网,将多次回调
				}

				@Override
				public void onStep(String step, Object data) {

				}
			}
		));
ITuyaActivator mTuyaActivator = TuyaHomeSdk.getActivatorInstance().newMultiActivator(builder);
//开始配网
mTuyaActivator.start();

timeout 单位为秒,默认为 100,您可以设置为任意值。但不建议将此值设置得过小,否则将影响配网结果。

使用 AP 模式 配网时,您需要将 activatorModel 传入为 ActivatorModelEnum.TY_AP 以监听配网结果的回调。

ActivatorBuilder builder = new ActivatorBuilder()
		.setContext(context)
		.setSsid(ssid)
		.setPassword(password)
		.setActivatorModel(ActivatorModelEnum.TY_AP)
		.setTimeOut(timeout)
		.setToken(token)
		.setListener(new ITuyaSmartActivatorListener() {

				@Override
				public void onError(String errorCode, String errorMsg) {

				}

				@Override
				public void onActiveSuccess(DeviceBean devResp) {

				}

				@Override
				public void onStep(String step, Object data) {

				}
			}
		));

(可选)停止配网

开始配网操作后,App 会持续广播配网信息,直到配网成功或是超时才停止。如果需要中途取消操作或配网完成,需要调用停止配网接口。

ITuyaActivator mTuyaActivator = TuyaHomeSdk.getActivatorInstance().newMultiActivator(builder);
//停止配网
mTuyaActivator.stop();
//退出页面销毁一些缓存和监听
mTuyaActivator.onDestroy();

第四步:控制设备

本章节主要操作对象包含 ITuyaDeviceDeviceBean

对象 说明 参考链接
DeviceBean
  • ITuyaHomeManagerHomeBean 类似,DeviceBean 存放了设备的基本信息,如 ID、名字、图标等。
  • DeviceBean 类的 dps 属性定义了当前设备的状态,称作数据点(DP,Data Point)或功能点。每个 DP 都存储了了一个设备的功能信息。如开关(布尔值),灯泡的亮度(数值型)等。对于设备的控制都通过获取和修改 DP 值实现。参考。
设备功能点
ITuyaDevice 存放了设备相关的所有功能,如功能控制,设备固件管理等。您需要用正确的 deviceId 初始化一个 ITuyaDevice 设备管理

查询设备列表

设备成功配网后,您可以在对应的家庭下调用 获取家庭详细信息 接口,在 HomeBeangetDeviceList 中查看对应的设备列表。

TuyaHomeSdk.newHomeInstance(10000).getHomeDetail(new ITuyaHomeResultCallback() {
		@Override
		public void onSuccess(HomeBean bean) {
			List<DeviceBean> deviceList = homeBean.getDeviceList();
            //下文中的deviceBean就是从这里获取
		}
		@Override
		public void onError(String errorCode, String errorMsg) {
			// do something
		}
	});

查看设备信息

设备的功能点信息存放在 dps 中。dps 存放了该设备的所有功能点信息,每个功能点被封装成一个键值对。

List<DeviceBean> deviceList = homeBean.getDeviceList();
Map<String, Object> dps = TuyaHomeSdk.getDataInstance().getDps(deviceBean.getDevId());

控制设备

控制设备需要 初始化设备控制 接口。接口向设备发送功能点,改变设备状态或功能,来达到设备控制的目的。

参数 dps 中可以包含多个功能点,您可以一次同时改变设备的多个状态。

同样以灯泡为例,假设开启一个灯具采用 101 设备功能点,则开灯的代码如下:

mDevice.publishDps("{\"101\": true}", new IResultCallback() {
	@Override
	public void onError(String code, String error) {
		Toast.makeText(mContext, "开灯失败", Toast.LENGTH_SHORT).show();
	}

	@Override
	public void onSuccess() {
		Toast.makeText(mContext, "开灯成功", Toast.LENGTH_SHORT).show();
	}
});

如果您需要监听设备状态的改变,如在线状态、移除通知、功能点状态改变等,需要注册 IDevListener 进行 监听

mDevice.registerDevListener(new IDevListener() {
	/**
	* DP 数据更新
	* devId 设备 ID
	* dpStr 设备发生变动的功能点,为 JSON 字符串,数据格式:{"101": true}
	*/
	@Override
	public void onDpUpdate(String devId, String dpStr){

    };

	/**
	* 设备移除回调
	* devId 设备 ID
	*/
	@Override
	public void onRemoved(String devId){

    };

	/**
	* 设备上下线回调。如果设备断电或断网,服务端将会在3分钟后回调到此方法。
	* devId  设备 ID
	* online 是否在线,在线为 true
	*/
	@Override
	public void onStatusChanged(String devId, boolean online){

    };

	/**
	* 网络状态发生变动时的回调
	*  devId  设备 ID
	*  status 网络状态是否可用,可用为 true
	*/
	@Override
	public void onNetworkStatusChanged(String devId, boolean status){

    };

	/**
	* 设备信息更新回调
	* devId  设备 ID
	*/
	@Override
	public void onDevInfoUpdate(String devId){

    };
}

(可选)移除设备

调用 移除设备 接口将当前设备从对应家庭下移除。

mDevice.removeDevice(new IResultCallback() {
	@Override
	public void onError(String errorCode, String errorMsg) {
	}

	@Override
	public void onSuccess() {
	}
});

实践结果

看到这里,相信您已经创建了一个自己的 App。然而,真正有趣精彩的部分才刚刚开始。我们会在之后推出更多关于智能场景、定时任务、多控关联等功能的介绍。

下一步

为了降低您的开发成本,涂鸦将 SDK 中按模块进行了功能抽离和 UI 封装,为您提供了一整套一键接入的 UI 业务包。您可以根据需要自由选择需要的业务模块。