设备 DP 数据解析

设备功能点（Data Point，简称 DP）是设备信息中描述一个设备功能的最小单元，每个 DP 都分为产品信息中的 DP 配置和设备信息中的 DP 值两部分。不同的 DP 类型可能还有拓展属性。
在涂鸦体系中将 DP 在功能上划分为三种：快捷开关、展示型 DP 和 操作型 DP。本文介绍如何通过设备、群组模型，快速获取功能点，方便定制 App UI 展示与操作。

操作步骤

1. 打开涂鸦 IoT 开发平台 产品开发 页面。
2. 选择一个产品，单击 操作 栏的 继续开发。
3. 选择第四步 产品配置 > 快捷开关配置，并单击 设置。

您可以配置 快捷开关 和 常用功能 等功能点，并在 App 设备、群组卡片上体现。

概览

头文件

#import <ThingSmartDeviceCoreKit/ThingSmartDpParser.h>

类定义

类名	说明
ThingSmartDpParser	功能点解析器
ThingSmartDp	DP 功能点，根据不同 DP 类型，还细分出不同子类，比如 `ThingSmartLightDp
ThingSmartSwitchDp	快捷开关功能点

功能点解析器

通过设备、群组模型创建解析器，可以快捷获取功能点。每次获取的功能点间相互独立，互不影响。

初始化方法

 + (instancetype)createWithTargetInfo:(id)targetInfo;

参数说明

参数	类型	说明
targetInfo	id	目标设备、群组实例，支持 ThingSmartDeviceModel、ThingSmartDevice、ThingSmartGroupModel 和 ThingSmartGroup

示例代码

• Objective C：

  ThingSmartGroup * group = [ThingSmartGroup groupWithGroupId: groupId];
  ThingSmartDpParser * groupDpParser = [ThingSmartDpParser createWithTargetInfo: group];
  
  ThingSmartDevice *device = [ThingSmartDevice deviceWithDeviceId: devId];
  ThingSmartDpParser *deviceDpParser = [ThingSmartDpParser createWithTargetInfo: device];
  

• Swift：

  let group = ThingSmartGroup(groupId: groupId)!
  let groupDpParser = ThingSmartDpParser.create(withTargetInfo: group)
      
  let device = ThingSmartDevice(deviceId: deviceId)!
  let deviceDpParser = ThingSmartDpParser.create(withTargetInfo: device)
  

属性

字段	类型	描述
displayDp	NSArray<_kindof ThingSmartDp *> *	对应 展示型 DP 功能点，为空时表示无展示型 DP
operableDp	NSArray<_kindof ThingSmartDp *> *	对应 操作型 DP 功能点，为空时表示无快捷操作型 DP
switchDp	ThingSmartSwitchDp *	对应 快捷开关 功能点，为空时表示无快捷开关
allDp	NSArray<_kindof ThingSmartDp *> *	产品的所有功能点

获取功能点

通过功能点解析器，可以获取指定的功能点。获取的功能点间相互独立，互不影响。

 - (nullable _kindof ThingSmartDp *)smartDpWithDpId:(NSInteger)dpId quickOp:(BOOL)quickOp;

参数说明

参数	类型	说明
dpId	NSInteger	目标功能点 ID
quickOp	BOOL	功能点展示方式，是否是快捷操作功能点

示例代码

• Objective C：

  - (void)setupWithDevId:(NSString *)devId dpId:(NSInteger)dpId
      self.device = [ThingSmartDevice deviceWithDeviceId: devId];
      self.deviceDpParser = [ThingSmartDpParser createWithTargetInfo: self.device];
      self.smartDp = [self.deviceDpParser smartDpWithDpId:dpId quickOp:YES];
  }
  

• Swift：

  func setup(devId : String, dpId: Int) {
      self.device = ThingSmartDevice(deviceId: devId)!
      self.deviceDpParser = ThingSmartDpParser.create(withTargetInfo: self.device)
      self.smartDp = self.deviceDpParser.smartDp(withDpId: dpId, quickOp: true)
  }
  

功能点

获取 DP 的状态值显示内容和控制指令。大多数的 DP 值并不能直接被展示出来，需要拼接单位，或者将值转换成为对应的业务展示内容。

属性

字段	类型	描述
schemaModel	ThingSmartSchemaModel *	关联功能点配置详情
dpId	NSInteger	功能点 ID
smartDpType	NS_ENUM	功能点类型
name	NSString *	功能点名称，例如剩余时间
iconname	NSString *	功能点图标名称，例如：icon-a_nav_timer，名称定义见涂鸦 IoT 开发平台
unit	NSString *	功能点单位，支持多语言，例如：秒、℃、%
curDpValue	id	功能点当前值
titleStatus	NSString *	功能点标题展示文案，支持多语言，例如：倒计时、湿度、温度
valueStatus	NSString *	功能点当前值展示文案，支持多语言，例如：0 秒、20.00℃、10.00%

其中可以通过 smartDpType 区分不同功能点类型：

• Bool 开关类型：状态只有 true 和 false。
• Enum 枚举类型：下发给设备的状态是 schemaModel.property.range 选项之一。
• Num 数值类型：在平台上配置时，可以设置最小值、最大值、步进值和倍率等。见 schemaModel.property。
• String 字符串型：DP 值是一个 String 文案。
• Light 光源类型：使用 HSV 格式描述的彩光类型，是字符串类型的一个应用场景。涂鸦提供对应功能点扩展子类型。

获取目标值描述

功能点操作时，需要获取目标值的展示文案，用于提交前给用户查看与确认。

- (NSString *)valueStatusWithDpValue:(id)dpValue;

参数说明

参数	类型	说明
dpValue	id	功能点的目标值

示例代码

• Objective C：

  - (NSString *)targetDpValueDisplayString:(id)dpValue {
      return [self.smartDp valueStatusWithDpValue: dpValue];
  }
  

• Swift：

  func targetDpValueDisplayString(dpValue : Any) -> String {
      return self.smartDp.valueStatus(withDpValue: dpValue)
  }
  

获取上报数据

功能点操作时，修改 DP 值后，需要把目标 DP 值按特定格式上报给云端。通过本方法，获取上报的格式化数值。

- (nullable NSDictionary *)publishCommands:(id)newDpValue

参数说明

参数	类型	说明
newDpValue	id	修改功能点的目标值

示例代码

• Objective C：

  - (void)changeDpValue:(id)newValue {
      NSDictionary * dps = [self.smartDp publishCommands: newValue];
  
      if (!dps) return;
  
      [self.device publishDps: dps success:nil failure:nil];
  }
  

• Swift：

  func changeDpValue(newValue : Any) {
      guard let dps = self.smartDp.publishCommands(newValue) else {
          return
      }
      self.device.publishDps(dps, success: nil, failure: nil)
  }
  

光源子类

模型为 ThingSmartLightDp，用于光源类 DP 解析。

属性

字段	类型	描述
lightHueMin	NSUInteger	色彩最小值
lightHueMax	NSUInteger	色彩最大值
currentLightHue	NSUInteger	当前色彩值
lightSaturationMin	NSUInteger	饱和度最小值
lightSaturationMax	NSUInteger	饱和度最大值
currentLightSaturatio	NSUInteger	当前饱和度
lightValueMin	NSUInteger	亮度最小值
lightValueMax	NSUInteger	亮度最大值
currentLightValue	NSUInteger	当前亮度

获取光源类功能点上报值

- (nullable NSDictionary *)publishCommandsWithLightHue:(NSUInteger)lightHue
                                       lightSaturation:(NSUInteger)lightSaturation
                                            lightValue:(NSUInteger)lightValue;

参数说明

参数	类型	说明
lightHue	NSUInteger	色彩值
lightSaturation	NSUInteger	饱和度
lightValue	NSUInteger	亮度

快捷开关

快捷开关是由一个或多个 DP 组成，通过一个开关同时控制多个 bool 型 DP。

DP 配置时可以选择 只上报、只下发、上报下发 三种类型：

• 只上报：不接收控制命令，但是 DP 值变化时会上报该状态。
• 只下发：接受控制指令并做出相应的改变，但是不会上报对应的状态，涂鸦无从得知该 DP 的实际状态。
• 上报下发：接受控制指令并做出相应的改变，设备收到后变更对应的状态，然后上报。

快捷开关的作用是控制设备，不接收设备控制的 只上报 类型就不在考虑范围内。快捷开关就分为两种：

• 有状态：即普通类型，可以下发开关状态给设备，同时设备有状态变化也会上报。
• 无状态：即只下发，设备并不会上报状态，无从得知开关的真实状态，因此每次下发给设备的状态是对当前状态取反。

属性

字段	类型	描述
switchStatus	BOOL	快捷开关当前状态
writeOnlySwitch	BOOL	是否无状态类型

获取快捷功能点上报值

- (nullable NSDictionary *)publishSwitchCommands:(BOOL)open;

参数说明

参数	类型	说明
newDpValue	id	修改功能点的目标值：YES 或者 NO

示例代码

• Objective C：

  - (void)changeSwitchStatus:(BOOL)open {
      NSDictionary * dps = [self.deviceDpParser.switchDp publishSwitchCommands: open];
  
      if (!dps) return;
  
      [self.device publishDps: dps success:nil failure:nil];
  }
  

• Swift：

  func changeSwitchStatus(open : Bool) {
      guard let dps = self.deviceDpParser.switchDp?.publishSwitchCommands(open) else {
          return
      }
      self.device.publishDps(dps, success: nil, failure: nil)
  }