Device DP Parser

A data point (DP) is the smallest unit used to describe a device feature in device information. Each DP has two parts: DP configuration in product information and DP value in device information. Certain types of DP might possess extended properties. Tuya categorizes the DP into three types based on their functionality: quick toggle, display, and operation. This topic describes how to use the device or group model to get DPs for displaying data and operating features on a custom app UI.

Procedure

1. Log in to the Tuya Developer Platform.
2. Select a product in the Developing state, and click Develop in the Operation column.
3. Choose Product Configuration > Quick Toggle > Settings.

You can configure quick toggles and common functions to present them on the device or group card.

Overview

Header file

#import <ThingSmartDeviceCoreKit/ThingSmartDpParser.h>

Class definition

Class name	Description
ThingSmartDpParser	The DP parser.
ThingSmartDp	A specific DP. Some DPs have a subtype, such as ThingSmartLightDp.
ThingSmartSwitchDp	A quick toggle DP.

DP parser

Create the DP parser through the device or group model to quickly get DP data. The DPs in each request are independent of one another.

Initialization method

 + (instancetype)createWithTargetInfo:(id)targetInfo;

Parameter description

Parameters	Type	Description
targetInfo	id	The instance of the target device or group, supporting ThingSmartDeviceModel, ThingSmartDevice, ThingSmartGroupModel, and ThingSmartGroup.

Example

• 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)
  

Property

Field	Type	Description
displayDp	NSArray<_kindof ThingSmartDp *> *	Specifies the display DP. If it is empty, it means that there is no display DP.
operableDp	NSArray<_kindof ThingSmartDp *> *	Specifies the operation DP. If it is empty, it means that there is no operation DP.
switchDp	ThingSmartSwitchDp *	Specifies the quick toggle DP. If it is empty, it means that there is no quick toggle.
allDp	NSArray<_kindof ThingSmartDp *> *	All the DPs of a product.

Get the DP data

Get a specific DP through the DP parser. The DPs in each request are independent of one another.

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

Parameter description

Parameters	Type	Description
dpId	NSInteger	The ID of the target DP.
quickOp	BOOL	Specifies whether the quick toggle applies.

Example

• 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)
  }
  

Get the display text for a DP

Get the display content and control command for a DP. Most DP values are displayed after being concatenated with a unit or converted.

Property

Field	Type	Description
schemaModel	ThingSmartSchemaModel *	The configurations of the respective DP.
dpId	NSInteger	The DP ID.
smartDpType	NS_ENUM	The DP type.
name	NSString *	The name of the DP, for example, time left.
iconname	NSString *	The icon name of the DP, for example, icon-a_nav_timer. You can find the name definition on the Tuya Developer Platform.
unit	NSString *	The unit of the DP, supporting multiple languages, for example, second, °C, and %.
curDpValue	id	The current value of the DP.
titleStatus	NSString *	The display title of the DP, supporting multiple languages, for example, countdown, humidity, and temperature.
valueStatus	NSString *	The display value of the DP, supporting multiple languages, for example, 0 seconds, 20.00°C, and 10.00%.

DP types can be identified by smartDpType.

• Bool type: Indicates the on/off feature, with the value being either true or false.
• Enum type: The command sent to the device is one of the values within schemaModel.property.range.
• Num type: You can set the maximum value, minimum value, step, and scale for this type of DP on the Tuya Developer Platform. For more information, see schemaModel.property.
• String type: The DP value is a string.
• Light source: The colored light described in the HSV format, an application scenario of string type. The extended subtype is provided for the respective DP.

Get the description of the target value

Request the display text of the target value when users operate a DP, allowing them to confirm the operation.

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

Parameter description

Parameters	Type	Description
dpValue	id	The target value of the DP.

Example

• Objective-C:

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

• Swift:

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

Get the reported data

After users change the value of a DP, report the target value to the cloud in a specific format. This method gets the formatted value.

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

Parameter description

Parameters	Type	Description
newDpValue	id	The target value of the DP.

Example

• 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)
  }
  

Light source subtype

The model ThingSmartLightDp is used to parse the DPs for the light source device.

Property

Field	Type	Description
lightHueMin	NSUInteger	The minimum hue.
lightHueMax	NSUInteger	The maximum hue.
currentLightHue	NSUInteger	The current hue.
lightSaturationMin	NSUInteger	The minimum saturation.
lightSaturationMax	NSUInteger	The maximum saturation.
currentLightSaturatio	NSUInteger	The current saturation.
lightValueMin	NSUInteger	The minimum brightness.
lightValueMax	NSUInteger	The maximum brightness.
currentLightValue	NSUInteger	The current brightness.

Get the reported value of a light source DP

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

Parameter description

Parameters	Type	Description
lightHue	NSUInteger	The hue.
lightSaturation	NSUInteger	The saturation.
lightValue	NSUInteger	The brightness.

Quick toggle

A quick toggle can consist of one or more DPs. It can be used to turn on or off multiple Boolean DPs at once.

You can set the data transfer type for a DP to report only, send only, or send and report.

• Report only: The device reports the status when the DP value changes, without receiving the DP control command.
• Send only: The device receives and acts on the DP control command, without reporting the DP status. This leaves you uninformed of the current status of the DP.
• Send and report: The device receives and acts on the DP control command, and then reports the DP status.

A quick toggle is used to control devices, so the report only type does not apply. There are two types of quick toggle:

• With status: corresponds to send and report. The device receives on/off commands and reports on/off status when it changes.
• Without status: corresponds to send only. The device receives and acts on the on/off command, without reporting the on/off status. Therefore, you need to reverse the value of the on/off DP before sending it to the device.

Property

Field	Type	Description
switchStatus	BOOL	The current status of the quick toggle.
writeOnlySwitch	BOOL	Specifies whether the quick toggle is the without status type.

Get the reported value of a quick toggle

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

Parameter description

Parameters	Type	Description
newDpValue	id	The target value, either YES or NO.

Example

• 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)
  }