简体中文
简体中文
English
联系我们
注册
登录
layout空间导航

涂鸦商用照明移动应用 SDK 开发入门教程安卓版

更新时间:2022-02-17 05:43:44下载pdf

涂鸦商用照明 App SDK 是专为照明行业的物联网应用提供的移动端开发工具。基于该 SDK,您可以快速实现商用照明及关联场景的安卓 App 功能开发。它适用于新装和存量的商用照明市场,多协议兼容,通过设备管理、能源管控、人因照明等实现绿色建筑与健康建筑。

您可以通过本教程在两小时内快速开发一款自己的 IoT App,并实现如下功能:

  • 在涂鸦商照管理平台上注册商户账号,并在 App 端管理该账号。
  • 在该账号下新建并管理项目和区域。
  • 在该区域下连接并控制设备。

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

前往 App 工作台 点击查看 GitHub Sample

准备工作

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

  1. 在涂鸦 IoT 平台,注册账号并创建 App 应用,拿到 SDK 的 AppKey,AppSecret。参考 准备工作

    准备工作中,您需要额外申请一个商照账号。账号类型不限:

    • 类型一:体验版账号。
      • 您可以在 准备工作 中获取 SDK 选项时,在顶部点击 申请体验版,获得 30 天的体验账号。
      • 测试版账号在体验期间,您使用 SDK 开发的 App 可正常登录,到期后 App 无法登录,且无法再次申请,您需要购买正式版后继续使用。
    • 类型二:正式账号。
      • 您可以在 增值服务 开通。
      • 正式版账号的有效期则根据您购买的套餐时长来匹配,且需搭配商照 SaaS 或开放 API 进行使用。使用商用照明 PaaS 对接前,请联系您的涂鸦客户经理提供相应的域名与域名证书,协助您配置。
  2. 使用 Android Studio ,参考 Sample,将涂鸦商业照明 SDK 集成到您的项目中 。参考 快速集成

    如果您需要本地调试,需要在 app 模块下 Android 闭包中进行您自己的签名配置。

    signingConfigs {
    	debug {
    		storeFile file('../xxx.jks')
    		storePassword 'xxx'
    		keyAlias 'xxx'
    		keyPassword 'xxx'
    	}
    }
    

账号管理

账号类型分为品牌商账号、企业主账号、企业子账号。品牌商账号下只创建一个商户账号,属于单一 SaaS 商户模式。您可以通过准备工作中开通的账号,登录 涂鸦商照平台

第一步:开通账号

目前涂鸦商照 SDK 暂不支持 App 账号注册的功能。您需要前往 涂鸦商照管理平台,购买商户账号并开通企业主账号。

第二步:使用账号密码登录

接下来,您可以调用 登录接口 登录在上一步中申请的企业主账号。

public void loginWithPwd(View view) {
    String username = etUsername.getText().toString();
    String merchantCode = etMerchant.getText().toString();
    String password = etPwd.getText().toString();
    TuyaUserLoginWithPwdReqBean reqBean = new TuyaUserLoginWithPwdReqBean();
    reqBean.setPassword(password);
    reqBean.setUsername(username);
    reqBean.setCountryCode("86");
    reqBean.setMerchantCode(merchantCode);

    TuyaOSUser.getUserInstance().loginWithPassword(reqBean, new ITuyaUserLoginCallback<User>() {
        @Override
        public void onPreLogin(List<TuyaMerchantBean> merchantBeanList) {
                    }

        @Override
        public void onSuccess(User data) {

        }

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

        }
    });
}

目前,商业照明限制一个账号仅对应一个唯一商户。所以,在登录账号时,自动匹配商户到账号,您无需传入参数商户的 merchantCode

除了账号密码,您还可以使用 验证码登录,或者 提交工单 申请 第三方授权登录

第三步:账号管理

您可以对当前账号进行信息修改,如密码和昵称等。

public void modifyPwd(View view) {
  String oldPwd = etPwd.getText().toString();
  String newPwd = etNewPwd.getText().toString();
  TuyaUserModifyPwdReqBean reqBean = new
  TuyaUserModifyPwdReqBean();
  reqBean.setOldPassword(oldPwd);
  reqBean.setNewPassword(newPwd);

  TuyaOSUser.getUserInstance().modifyPassword(reqBean, new IResultCallback() {
    @Override
    public void onError(String code, String error) {
      toast(error);
      L.e(TAG, error);
    }

    @Override
    public void onSuccess() {
      toast("modify success");
    }
  });
}

账号管理还支持找回或重置密码、退出账号、修改账号头像、同步更新用户信息等。对应的详细内容,请参考 账号管理

项目管理

项目为账号下的可独立操作的单元,一个账号下可创建的项目数量,不同套餐的账号可配置不同数量的项目。

新账号登录是没有默认项目的,需要您自行创建。目前项目分为室内项目和户外项目。更多详细内容,请参考 项目介绍

本章节代码示例和方法说明均为室内项目。

第一步:创建一个室内项目

在登录账号后,您首先需要 创建一个项目

TuyaCommercialLightingProject.getLightingProjectManager()
.createProject(projectType, projectName, leaderName, leaderMobile, detailAddress, regionId, new ITuyaHomeResultCallback() {
    @Override
    public void onSuccess(HomeBean homeBean) {

    }

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

    }
});
  • 对于室内项目,参数 regionId 可以根据 查询数据区国家列表 接口返回的 locationId 字段。
  • 对于户外项目,参数 regionLocationId 可置为空。

第二步:查询账号下的项目

您可以通过调用 查询项目列表 接口查询到该账号下的所有项目。

TuyaCommercialLightingProject.getLightingProjectManager().getProjectList(new ITuyaGetHomeListCallback() {
    @Override
    public void onSuccess(List<HomeBean> list) {
        Log.i(TAG, "queryProjectList onSuccess: " + JSON.toJSONString(list));
        if (null == iProjectIndexView.getContext()) {
            return;
        }
        if (CollectionUtils.isEmpty(list)) {
            iProjectIndexView.showProjectEmptyView();
        } else {
            iProjectIndexView.setProjectList(list);
        }
    }

    @Override
    public void onError(String s, String s1) {
        Log.e(TAG, "queryProjectList onError: errorCode=" + s);
    }
});

对项目的信息修改和删除等其他操作可参考 更新项目信息

区域管理

区域也称为空间,它是是挂载在某一项目下的可独立操作的单元。详细介绍,请参考 名词解释

  • 区域有不定数量的子区域,最小的区域无法创建子区域。
  • 区域下可以挂载不定数量的设备或群组。

第一步:创建一个室内区域

创建区域分为室内项目和户外项目,方法不一样,在室内项目下只能创建室内区域,户外项目同理。详情可以参考 创建区域

本章节代码示例和方法说明均为室内项目。

TuyaCommercialLightingArea.getLightingAreaManager().createArea(projectId, currentAreaId, name, roomLevel, new ITuyaResultCallback<SimpleAreaBean>() {
            @Override
            public void onSuccess(SimpleAreaBean result) {
                //success callback
            }

            @Override
            public void onError(String errorCode, String errorMessage) {
            		//error callback
            }
        });

室内项目和户外项目下的区域,可以创建对应的子区域,也可以创建父区域。最小子区域不能创建下级区域。

参数说明

  • projectId:当前项目 ID

  • currentAreaId:当前区域 ID。

    • 若当前您还未创建区域或需要创建一级区域,该参数可为任意值。为防止冲突,建议设置为 0 或负数。
    • 若您想在一个已有区域的基础上创建父区域或子区域,则需要通过 查询子区域列表 查询对应的区域 ID。
  • roomLevel:区域等级,其中 1 为最高。

    • currentAreaId0 时,无论 roomLevel 为多少,该区域都是独立区域。
    • 若为一个已知的区域 ID,则根据该值大小创建一个子区域或父区域。

第二步:查询区域

创建好区域后,您可以查询区域列表,查询区域的详细信息,包括区域下的设备列表等信息。

查询区域信息

TuyaCommercialLightingArea.newAreaInstance(projectId, areaId).getAreaInfo(new ITuyaResultCallback<SimpleAreaBean>() {
            @Override
            public void onSuccess(SimpleAreaBean result) {
                //success callback
            }

            @Override
            public void onError(String errorCode, String errorMessage) {
            	//error callback
            }
        });

查询区域下的设备信息

TuyaCommercialLightingArea.newAreaInstance(mProjectId, mAreaId).queryDeviceListInArea("", 20,
                "1", new ITuyaResultCallback<LightingDeviceListBean>() {
                    @Override
                    public void onSuccess(LightingDeviceListBean result) {
                        //success callback0
                    }

                    @Override
                    public void onError(String errorCode, String errorMessage) {
                    		//error callback
                    }
                });

更多的查询区域相关的信息,请参考 查询区域相关数据。拿到区域相关的信息后,您就可以对区域以及区域下的设备进行管理。例如,修改区域设备转移区域对区域下的设备进行群控 等。

设备配网

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

配网方式介绍

本文以 Wi-Fi 配网为例,介绍如何使用 SDK 将设备配置到云端。

Wi-Fi 配网方式包括 快连模式(即 EZ 模式)热点模式(即 AP 模式)、扫 App 二维码三种方式。

相比快连模式,热点模式成功率高、可靠性好,对手机和路由器有兼容性要求小。热点模式配网成功率高于快连模式。因此,推荐您使用 热点模式 代替 快连模式

获取配网 Token

开始配网之前,SDK 需要在联网状态下从涂鸦获取配网 Token,然后才可以开始热点模式配网。

  • Token 的有效期为 10 分钟,且配置成功后就会失效,再次配网需要重新获取。
  • 获取 Token 需要上传当前的项目ID(projectId),因此您需要确保账号处于登录状态并至少创建了一个 项目。通过 查询项目列表 接口,您可以在返回的 HomeBean 中查询到 projectId

下文示例代码中涉及到的 homeId 就是 projectId

TuyaOSActivator.deviceActivator().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 = TuyaOSActivator.deviceActivator().newMultiActivator(builder);
//开始配网
mTuyaActivator.start();

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

使用热点模式配网时,您需要将 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 会持续广播配网信息,直到配网成功或是超时才停止。如果需要中途取消操作或配网完成,需要调用 停止配网 接口。

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

设备控制

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

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

查询设备列表

设备成功配网后,您可以在对应的区域下查看对应的 设备列表

您必须先调用 查询项目详细信息 接口。否则即使配网成功也无法成功查询。

        TuyaCommercialLightingArea.newAreaInstance(mProjectId, mAreaId).queryDeviceListInArea("", 20,
                "1", new ITuyaResultCallback<LightingDeviceListBean>() {
                    @Override
                    public void onSuccess(LightingDeviceListBean result) {
                        //success callback0
                    }

                    @Override
                    public void onError(String errorCode, String errorMessage) {
                    		//error callback
                    }
                });

查看设备信息

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

TuyaOSDevice.newDeviceInstance(devId).getDp(dpId, new IResultCallback() {
    @Override
    public void onError(String code, String error) {

    }

    @Override
    public void onSuccess() {

    }
});

查询 DP 数据后,查询后的数据会通过 IDevListener.onDpUpdate() 接口进行异步回调。

设备控制

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

参数 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() {
	}
});

下一步

在商用照明的业务场景中,设备更多以群组的形式出现。群组是一个或多个设备按照一定规则的聚合体,通过对群组的控制可以便捷地控制群组中设备。

具体的使用可参考章节 群组管理,或在本文文首下载 Sample 体验开发流程。