快捷功能解析 Android 版

ShortcutParser 是涂鸦 Smart App SDK 的功能拓展包。提供了对设备数据模型（DeviceBean）和群组数据模型（GroupBean）快捷功能相关能力的解析功能。使业务层对设备或群组快捷功能的相关研发更加便捷。

背景信息

在涂鸦的 IoT 体系中，设备侧的功能点使用 DP 来描述。设备的状态和控制，可以通过对 DP 数据在客户端进行解析、渲染和操作。通常设备的 DP 由设备面板部分来实现设备的所有功能，这部分一般是通过 RN 面板来实现的。

所谓快捷功能，即涂鸦提供了一种标记能力，可以把若干 DP 描述为可以在除设备面板之外的部分去展示、控制。一般情况下，会标记用户最感兴趣的设备功能 DP，用在 App 的设备列表页面，免去用户进入控制面板的步骤，更快捷地获取设备的状态或者控制设备。

准备工作

本工具包依赖于 TuyaHomeKitSDK 3.11.0 以上版本。请在模块 build.gradle 文件下添加依赖：

implementation 'com.tuya.smart:tuyasmart-shortcutparser:0.0.1'

在根目录的 build.gradle 文件下 repositories内添加 maven 源：

maven {
  url "https://maven-other.tuya.com/repository/maven-releases/"
}

接口列表

本工具包核心是提供对设备或群组的快捷 DP 信息的解析能力，各接口定义说明如下：

类	说明
IShortcutParserManager	入口工具接口
IClientParser	设备解析工具接口
IDpControl	快捷控制基础接口
IBoolDpControl	布尔型快捷控制接口
IEnumDpControl	枚举型快捷控制接口
INumDpControl	数值型快捷控制接口
IDpStatus	快捷状态接口

各 API 关系如下：

入口工具接口

接口说明

public interface IShortcutParserManager {
	/**
	* 获取设备解析信息
	*
	* @param deviceBean
	* @return
	*/
	IClientParser getDeviceParseData(DeviceBean deviceBean);

	/**
	* 获取群组解析信息
	*
	* @param groupBean
	* @return
	*/
	IClientParser getGroupParseData(GroupBean groupBean, ProductBean productBean);
}

示例代码

//工具初始化
IShortcutParserManager mIShortcutParserManager = new ShortcutParserManager();

快捷控制

根据设备的功能特点，一般指可读写的 DP 功能。在涂鸦开发者平台可以进行配置，详情请参考 设置快捷开关。

配置成功后，从 SDK 拉取到的 DeviceBean 或 GroupBean 数据中就会携带对应的快捷控制 DP 信息。随后，您才可以使用本拓展包，进行快捷控制相关的功能研发。

快捷控制类的 DP 可以分为设备的开关 DP 和普通快捷 DP 两种。

快捷开关

快捷开关即设备的开关 DP。一般标记为设备的快捷开关的 DP 对应的设备功能是该设备的电源开关。

在通过入口工具类获取的设备解析接口 IClientParserBean 中，有三部分跟快捷开关有关：

• 快捷开关状态

  enum SHORTCUT_SWITCH_STATUS{
  	//未配置快捷开关
  	SWITCH_NONE(0),
  	//快捷开关打开状态
  	SWITCH_ON(1),
  	//快捷开关关闭状态
  	SWITCH_OFF(2);
  
  	private int status;
  
  	SHORTCUT_SWITCH_STATUS(int status) {
  		this.status = status;
  	}
  
  	public int getStatus() {
  		return status;
  	}
  }
  

• 获取快捷开关状态

  接口说明

  /**
  * 获取快捷开关的状态
  * @return 状态枚举
  */
  SHORTCUT_SWITCH_STATUS getSwitchStatus();
  

  示例代码

  IClientParser mClientParser = mShortcutParserManager.updateDeviceParseData(mDev);
  Log.d(TAG,mClientParser.getSwitchStatus());
  

• 获取快捷开关的操作

  /**
  * 获取快捷开关的DP解析数据
  * @return 解析接口
  */
  IBoolDpControl getSwitchDpParseBean();
  

普通快捷 DP

您可以通过设备解析工具接口获取快捷 DP 列表。

/**
 * 获取快捷控制的DP解析列表
 * @return
 */
List<IDpControl> getDpShortcutControlList();

其中，可能获取到的 DP 目前支持有枚举、数值、布尔三种。各自接口提供对应的可解析出的数据，具体信息可以参考接口类注释。

数据更新

一般情况下，设备进行控制后，dps 信息会发生改变。此时，您可以通过设备解析工具调用数据更新接口，用于获取最新的状态。

接口说明

/**
 * 设备或群组的状态更新 数据跟进解析
 * @param dps 设备/群组的 dps 值
 * @param dpName 设备/群组的 DP name 值
 */
void update(Map<String, Object> dps, Map<String, String> dpName);

示例代码

//从 SDK 中获取最新的数据缓存
mDev = TuyaHomeSdk.getDataInstance().getDeviceBean(devId);
//更新 dp s和 dpName 信息
mClientParserBean.update(mDev.getDps(),mDev.getDpName());

快捷状态

带有快捷状态标记的 DP，一般是用于类似传感器类型的设备，标记一些只读的设备状态信息。对于产品配置，目前这部分功能还没有开放到开发者平台，您可以 提交工单 联系涂鸦进行配置。

设备解析工具提供了获取当前设备或群组快捷状态列表的接口。

接口说明

/**
 * 获取快捷状态 DP 解析列表
 * @return
 */
List<IDpStatus> getDpShortcutStatusList();

具体快捷状态提供的数据解析能力，请参考接口类注释。