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

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

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

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

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

效果展示

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

准备工作

在您开始本教程前，请先确保您已经 ：

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

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

   本教程在 macOS 上使用 Android Studio v4.1.2 集成cube App SDK。注意项目 build.gradle 中配置的 minSdkVersion 最低为 21，否则会报错。

第一步：注册用户账号

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

注册用户账号时：

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

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

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

查询验证码服务可用地区

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

ThingHomeSdk.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 表示一个或多个国家或地区，以 , 隔开取值，例如 86 和 01。有关可用区编号列表，请参考 涂鸦云平台介绍。

获取注册账号的验证码

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

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

参数说明

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

ThingHomeSdk.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。然后调用号码注册接口，需要上传国家码、手机号码、密码以及获取到的验证码。更多详情，请参考 使用手机账号注册和登录安卓用户账号。

ThingHomeSdk.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();
	}
});

使用手机号码登录账号

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

ThingHomeSdk.getUserInstance().loginWithPhonePassword("86", "13666666666", "123456", new ILoginCallback() {
	@Override
	public void onSuccess(User user) {
		Toast.makeText(mContext, "Login success：" +ThingHomeSdk.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();
	}
});

第二步：创建和管理家庭

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

操作家庭模块时，您将频繁调用对象 IThingHomeManager 和 HomeBean。

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

创建家庭

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

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

查询家庭列表

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

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

获取家庭详细信息

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

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

最佳实践

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

第三步：设备配网

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

配网方式介绍

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

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

获取配网 Token

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

ThingHomeSdk.getActivatorInstance().getActivatorToken(homeId,
		new IThingActivatorGetToken() {

			@Override
			public void onSuccess(String token) {

			}

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

			}
		});

开始设备配网

调用 配网接口 需要提供 builder，builder 中需要路由器的 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) {

				}
			}
		));

IThingActivator mTuyaActivator = ThingHomeSdk.getActivatorInstance().newMultiActivator(builder);
//开始配网
mThingActivator.start();

使用 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 IThingSmartActivatorListener() {

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

				}

				@Override
				public void onActiveSuccess(DeviceBean devResp) {

				}

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

				}
			}
		));

（可选）停止配网

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

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

第四步：控制设备

本章节主要操作对象包含 IThingDevice 和 DeviceBean。

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

查询设备列表

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

ThingHomeSdk.newHomeInstance(10000).getHomeDetail(new IThingHomeResultCallback() {
		@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 = ThingHomeSdk.getDataInstance().getDps(deviceBean.getDevId());

控制设备

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

同样以灯泡为例，假设开启一个灯具采用 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 业务包。您可以根据需要自由选择需要的业务模块。