Function Definition of Lighting Products

Last Updated on : 2024-06-21 04:04:30download

Types of data point (DP)

The Tuya Developer Platform allows you to define functions with six data types, including Boolean, value, enum, fault, string, and raw. For more information, see Data Types.

Standard DP

DP	Identifier	Data transfer type	Data type	Property
On/Off	switch_led	Send and report (read-write)	Boolean	/
Mode	work_mode	Send and report (read-write)	Enum	Enum values: white color scene music
Brightness	bright_value	Send and report (read-write)	Value	Value range: 10 to 1000 Pitch: 1 Scale: 0
Color temperature	temp_value	Send and report (read-write)	Value	Value range: 10 to 1000 Pitch: 1 Scale: 0
Colorful	colour_data	Send and report (read-write)	String	/
Scene	scene_data	Send and report (read-write)	String	/
Timer	countdown	Send and report (read-write)	Value	Value range: 0 to 86400 Pitch: 1 Scale: 0
Music sync	music_data	Send only (write-only)	String	/
Real-time adjustment	control_data	Send only (write-only)	String	/
Gamma debug	debug_data	Send only (write-only)	String	/
Biorhythm	rhythm_mode	Send and report (read-write)	Raw	/
Light to sleep	sleep_mode	Send and report (read-write)	Raw	/
Light to wake	wakeup_mode	Send and report (read-write)	Raw	/
Power-off memory	power_memory	Send and report (read-write)	Raw	/
Do not disturb	do_not_disturb	Send and report (read-write)	Boolean	/
Cycle timing	cycle_timing	Send and report (read-write)	Raw	/
Vacation timing	random_timing	Send and report (read-write)	Raw	/

Description of DPs

DP20: on/off (required)

Data type	Valid values	Example
Boolean	true: Turn on light. false: Turn off light.	{“20”:true}

DP21: mode (required)

Data type	Valid values	Example
Enum	white: white light. color: colored light. scene: scene. music: music light.	{“21”:“scene”}

The presence of the in-app menu bars for white light, colored light, scene, and music light depends on if you have added the required DPs for your product.

Menus	Determinants
White	Required DPs: mode and brightness
Color	Required DPs: mode and color
Scene	Required DPs: mode and scene
Music	Required DPs: mode and music
Timer	Required DPs: timer
Schedule	Cloud timing provided by the advanced functions.

DP22: brightness

Data type	Valid values	Example
Value	10 to 1000 The brightness range of 10 to 1000 corresponds to the value range of 1% to 100% on the mobile app. The minimum value is 1%.	{"22":670 "}

DP23: color temperature

Data type	Valid values	Example
Value	0 to 1000 The color temperature range of 0 to 1000 corresponds to the value range of 0% to 100% on the mobile app. The color temperature range is defined between the coolest white and warmest white. The actual color temperature depends on the bead specifications, such as 2700K to 6500K.	{"23":797"}

DP24: color

Data type	Valid values	Example
String	000011112222 0000: indicates hue. It ranges from 0 to 360, corresponding to 0x0000 to 0x0168. 1111: indicates saturation. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8. 2222: indicates value. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8.	{"24":"00DC004B004E"} HSV value is 00DC, 004B, 004E in hex format. After converting them to the decimal format, you will get 220°, 75%, 78%.

Color values are output in HSV format. Alternatively, you can convert values to the RGB format. For more information, visit color conversion.

DP25: scene

Data type	Valid values	Example
Value	0011223344445555666677778888 00: scene ID. 11: transition interval between lighting modes (0 to 100). 22: lighting mode duration (0 to 100). 33: lighting mode (0: static. 1: jumping. 2: gradient) 4444: H (hue: 0 to 360, 0X0000 to 0X0168) 5555: S (saturation: 0 to 1000, 0X0000 to 0X03E8) 6666: V (value: 0 to 1000, 0X0000 to 0X03E8) 7777: brightness (0 to 1000) 8888: color temperature (0 to 1000) Except for the scene ID, the data in this string represents one color data unit. If multiple colors are used, you will get multiple color data units accordingly.	{"25":"010b0a02000003e803e800000000 0b0a02007603e803e800000000..."} 01: indicates the scene ID is 01. 0b: indicates the transition interval between lighting modes. 0a: indicates the lighting mode duration. 02: indicates the lighting mode is gradient. 0000: indicates the hue is 0. 03e8: indicates the saturation. 03e8: indicates the value. 0000: indicates the brightness. 0000: indicates the color temperature.

Data type

Valid values

Example

Value

0011223344445555666677778888

00: scene ID.
11: transition interval between lighting modes (0 to 100).
22: lighting mode duration (0 to 100).
33: lighting mode (0: static. 1: jumping. 2: gradient)
4444: H (hue: 0 to 360, 0X0000 to 0X0168)
5555: S (saturation: 0 to 1000, 0X0000 to 0X03E8)
6666: V (value: 0 to 1000, 0X0000 to 0X03E8)
7777: brightness (0 to 1000)
8888: color temperature (0 to 1000)

Except for the scene ID, the data in this string represents one color data unit. If multiple colors are used, you will get multiple color data units accordingly.

{"25":"010b0a02000003e803e800000000
0b0a02007603e803e800000000..."}

01: indicates the scene ID is 01.
0b: indicates the transition interval between lighting modes.
0a: indicates the lighting mode duration.
02: indicates the lighting mode is gradient.
0000: indicates the hue is 0.
03e8: indicates the saturation.
03e8: indicates the value.
0000: indicates the brightness.
0000: indicates the color temperature.

DP26: timer

Data type	Valid values	Example
Value	0 to 86400, in seconds. The value of one minute is 60. 86400 represents 23:59.	{"26":"120"}

DP27: music sync

Data type	Valid values	Example
String	011112222333344445555 0 indicates lighting mode. 0: jumping. 1: gradient. 1111: indicates hue. It ranges from 0 to 360, corresponding to 0x0000 to 0x0168. 2222: indicates saturation. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8. 3333: indicates value. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8. 4444: indicates brightness. It ranges from 0 to 1000. 5555: indicates color temperature. It ranges from 0 to 1000.	{“27”:“1007603e803e800120025”} 1: indicates gradient mode. 0076: indicates hue is 0x0076. 03e8: indicates saturation is 0x03E8. 03e8: indicates value is 0x03E8. 0012: indicates brightness is 18%. 0025: indicates color temperature is 37%.

Data type

Valid values

Example

String

011112222333344445555

0 indicates lighting mode. 0: jumping. 1: gradient.
1111: indicates hue. It ranges from 0 to 360, corresponding to 0x0000 to 0x0168.
2222: indicates saturation. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8.
3333: indicates value. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8.
4444: indicates brightness. It ranges from 0 to 1000.
5555: indicates color temperature. It ranges from 0 to 1000.

{“27”:“1007603e803e800120025”}

1: indicates gradient mode.
0076: indicates hue is 0x0076.
03e8: indicates saturation is 0x03E8.
03e8: indicates value is 0x03E8.
0012: indicates brightness is 18%.
0025: indicates color temperature is 37%.

This DP and the DP mode together determine whether the music light is available for users.

DP28: real-time adjustment

Data type	Valid values	Example
String	011112222333344445555 0 indicates lighting mode. 0: jumping. 1: gradient. 1111: indicates hue. It ranges from 0 to 360, corresponding to 0x0000 to 0x0168. 2222: indicates saturation. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8. 3333: indicates value. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8. 4444: indicates brightness. It ranges from 0 to 1000. 5555: indicates color temperature. It ranges from 0 to 1000.	{“28”:“1007603e803e800120025”} 1: indicates gradient mode. 0076: indicates hue is 0x0076. 03e8: indicates saturation is 0x03E8. 03e8: indicates value is 0x03E8. 0012: indicates brightness is 18%. 0025: indicates color temperature is 37%.

Data type

Valid values

Example

String

011112222333344445555

0 indicates lighting mode. 0: jumping. 1: gradient.
1111: indicates hue. It ranges from 0 to 360, corresponding to 0x0000 to 0x0168.
2222: indicates saturation. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8.
3333: indicates value. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8.
4444: indicates brightness. It ranges from 0 to 1000.
5555: indicates color temperature. It ranges from 0 to 1000.

{“28”:“1007603e803e800120025”}

1: indicates gradient mode.
0076: indicates hue is 0x0076.
03e8: indicates saturation is 0x03E8.
03e8: indicates value is 0x03E8.
0012: indicates brightness is 18%.
0025: indicates color temperature is 37%.

This DP is used to receive commands from the cloud when users control the light on the mobile app.

DP29: gamma debug

Used for gamma calibration only.

Data type	Valid values	Example
String	011112222333344445555 0 indicates lighting mode. 0: jumping. 1: gradient. 1111: indicates hue. It ranges from 0 to 360, corresponding to 0x0000 to 0x0168. 2222: indicates saturation. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8. 3333: indicates value. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8. 4444: indicates brightness. It ranges from 0 to 1000. 5555: indicates color temperature. It ranges from 0 to 1000.	{“29”:“1007603e803e800120025”} 1: indicates gradient mode. 0076: indicates hue is 0x0076. 03e8: indicates saturation is 0x03E8. 03e8: indicates value is 0x03E8. 0012: indicates brightness is 18%. 0025: indicates color temperature is 37%.

Data type

Valid values

Example

String

011112222333344445555

0 indicates lighting mode. 0: jumping. 1: gradient.
1111: indicates hue. It ranges from 0 to 360, corresponding to 0x0000 to 0x0168.
2222: indicates saturation. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8.
3333: indicates value. It ranges from 0 to 1000, corresponding to 0x0000 to 0x03E8.
4444: indicates brightness. It ranges from 0 to 1000.
5555: indicates color temperature. It ranges from 0 to 1000.

{“29”:“1007603e803e800120025”}

1: indicates gradient mode.
0076: indicates hue is 0x0076.
03e8: indicates saturation is 0x03E8.
03e8: indicates value is 0x03E8.
0012: indicates brightness is 18%.
0025: indicates color temperature is 37%.

This DP is used along with a specific debugging panel to perform gamma calibration.

DP30: biorhythm

Data type

Raw data.

Fields

Fields	Length
Version number	1 byte: 0x00
Task on/off	1 byte
Mode	1 byte
Specified date	1 byte
The number of nodes	1 byte
Node 1	9 bytes
...	...
Node N	9 bytes

The field of parameter mode is added in the following version.

Fields	Lengrh
Version number	1 byte: 0x01
Task on/off	1 byte
Mode	1 byte
Specified date	1 byte
Parameter mode	1 byte 0x01: only brightness included. 0x02: only HSV included. 0x03: both brightness and HSV included.
The number of nodes	1 byte
Node 1	5 to 9 bytes
...	...
Node N	5 to 9 bytes

Field description

Field	Sequence number	Node	Length	Description
Version number	1	/	1 byte	0x00: the initial version
Task on/off	2	/	1 byte	0x00: Turn off a task. 0x01: Turn on a task.
Mode selection	3	/	1 byte	0x00: indicates full gradient. The reaction time is the time interval between two time nodes. 0x0F: indicates the duration of the direct gradient. The minimum value is 15 minutes. For example, if you set `0x0F` to 15, the light change happens within 15 minutes after a time node is reached.
Specified date	4	/	1 byte	`1` indicates a day of a week is scheduled to execute the task.
The number of nodes	5	/	1 byte	0x01: one time node Value range: 1 to 8
Time node switch	6	Node 1	1 byte	The biorhythm switch is prioritized over the time node switch. Determining the switch status of the time node is necessary only when the biorhythm switch is on. 0x00: Time node is off. 0x01: Time node is on.
Hour(s)	6	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 23.
Minute(s)	6	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 59.
Hue	6	Node 1	2 bytes	0x03 and 0x10: values in hexadecimal format, big endian. The first byte indicates hundreds. The second byte indicates tens and ones. Value range: 0 to 360.
Saturation (%)	6	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 100.
Value (%)	6	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 1 to 100.
Brightness (%)	6	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 1 to 100.
Color temperature (%)	6	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 100.
/	7	Node 2	/	/
…	…	…	…	…
/	13	Node 8	/	/

Description of schedule setting

If all the bits are 0, it indicates a one-time task. If a bit is set to 1, it indicates the task is enabled on that day of a week.

Reserved	Saturday	Friday	Thursday	Wednesday	Tuesday	Monday	Sunday
bit7	bit6	bit5	bit4	bit3	bit2	bit1	bit0

DP31: light to sleep

Field description

Field	Sequence number	Node	Length	Description
Version number	1	/	1 byte	0x00: the initial version
The number of nodes	2	/	1 byte	0x01: one time node. 0x02: two time nodes. 0x03: three time nodes. 0x04: four time nodes.
Task on/off	3	Node 1	1 byte	0x00: Turn off a task. 0x01: Turn on a task.
Specified date	3	Node 1	1 byte	`1` indicates a day of a week is scheduled to execute the task.
Gradient steps	3	Node 1	1 byte	0x10: a value in hexadecimal format. The step size is five minutes. Value range: 1 to 24.
The start hour	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 23.
The start minute	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 59.
Hue	3	Node 1	2 bytes	0x03 and 0x10: values in hexadecimal format, big endian. The first byte indicates hundreds. The second byte indicates tens and ones. Value range: 0 to 360.
Saturation (%)	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 100.
Value (%)	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 1 to 100.
Brightness (%)	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 1 to 100.
Color temperature (%)	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 100.
/	4	Node 2	/	/
…	…	…	…	…
/	6	Node 4	/	/

Description of schedule setting

If all the bits are 0, it indicates a one-time task. If a bit is set to 1, it indicates the task is enabled on that day of a week.

Reserved	Saturday	Friday	Thursday	Wednesday	Tuesday	Monday	Sunday
bit7	bit6	bit5	bit4	bit3	bit2	bit1	bit0

DP32: light to wake

Field description

Field	Sequence number	Node	Length	Description
Version number	1	/	1 byte	0x00: the initial version
The number of nodes	2	/	1 byte	0x01: one time node 0x02: two time nodes 0x03: three time nodes 0x04: four time nodes
Task on/off	3	Node 1	1 byte	0x00: Turn off a task. 0x01: Turn on a task.
Specified date	3	Node 1	1 byte	`1` indicates a day of a week is scheduled to execute the task.
Gradient steps	3	Node 1	1 byte	0x10: a value in hexadecimal format. The step size is five minutes. Value range: 1 to 24.
The start hour	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 23.
The start minute	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 59.
Hue	3	Node 1	2 bytes	0x03 and 0x10: values in hexadecimal format, big endian. The first byte indicates hundreds. The second byte indicates tens and ones. Value range: 0 to 360.
Saturation (%)	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 100.
Value (%)	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 1 to 100.
Brightness (%)	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 1 to 100.
Color temperature (%)	3	Node 1	1 byte	0x10: a value in hexadecimal format. Value range: 0 to 100.
Time duration	3	Node 1	1 byte	0x10: a value in hexadecimal format. The step size is five minutes. It is used to set how long the light stays on after it reaches full brightness. Value range: 0 to 24. `0` means the light stays on. `24` means the light comes off in 120 minutes.
/	4	Node 2	/	/
…	…	…	…	…
/	6	Node 4	/	/

Description of schedule setting

If all the bits are 0, it indicates a one-time task. If a bit is set to 1, it indicates the task is enabled on that day of a week.

Reserved	Saturday	Friday	Thursday	Wednesday	Tuesday	Monday	Sunday
bit7	bit6	bit5	bit4	bit3	bit2	bit1	bit0

DP33: power-off memory

Used to set the state in which the light comes on.

Fields

Field	Length	Description
Version number	1 byte	0x00: the initial version
Mode	1 byte	0x00: initial mode 0x01: last state 0x02: custom mode
H	2 bytes	Hue
S	2 bytes	Saturation
V	2 bytes	Value
Bright	2 bytes	Brightness
Temperature	2 bytes	Temperature

DP34: do not disturb

Applies to areas where a power outage happens quite often. With this feature enabled, if users have turned off the light by using the mobile app, they need to turn the light on and off twice consecutively to switch it on.

Data type	Valid values	Example
Boolean	true: turn on light. false: turn off light.	{“34”:true}

DP209: cycle timing

Used to schedule lights to switch on and off to automate light routines such as for plant grow lights.

Field description

Sequence number	Field	Node	Length (byte)	Description
1	Version number	/	1	0x00: the initial version.
2	Node length	/	1	The data length of a single node is up to 255 bytes.
3	Switch + channel ID	Node 1	1	bit0: the on/off state of this node. bit1 to bit7: the applied channels.
4	The day of week	Node 1	1	Specifies the recurring days. If a bit is set to `1`, it means that the task will recur on this specified day weekly.
5	The start time	Node 1	2	The value is in minutes. The maximum value is 1439.
6	The end time	Node 1	2	The value is in minutes. The maximum value is 1439.
7	The ON state duration	Node 1	2	The value is in minutes. The maximum value is 1439.
8	The OFF state duration	Node 1	2	The value is in minutes. The maximum value is 1439.
9	Hue	Node 1	2	0x03 and 0x10: values in hexadecimal format, big endian. The first byte indicates hundreds. The second byte indicates tens and ones. Value range: 0 to 360.
10	Saturation (%)	Node 1	1	0x10: a value in hexadecimal format. Value range: 0 to 100.
11	Value (%)	Node 1	1	0x10: a value in hexadecimal format. Value range: 0 to 100.
12	Brightness (%)	Node 1	1	0x10: a value in hexadecimal format. Value range: 0 to 100.
13	Color temperature (%)	Node 1	1	0x10: a value in hexadecimal format. Value range: 0 to 100.
…	…	…	…	…

If multiple time nodes are set, fields from sequence No. 3 to 13 are duplicated.

Description of schedule setting

If all the bits are 0, it indicates a one-time task. If a bit is set to 1, it indicates the task is enabled on that day of a week.

Reserved	Saturday	Friday	Thursday	Wednesday	Tuesday	Monday	Sunday
bit7	bit6	bit5	bit4	bit3	bit2	bit1	bit0

DP210: vacation timing

Used to make smart lights turn on and off at random intervals, creating the illusion that someone is at home while you are away from home.

Field description

Sequence number	Field	Node	Length (byte)	Description
1	Version number	/	1	0x00: the initial version.
2	Node length	/	1	The data length of a single node is up to 255 bytes.
3	Switch + channel ID	Node 1	1	bit0: the on/off state of this node. bit1 to bit7: the applied channels.
4	The day of week	Node 1	1	Specifies the recurring days. If a bit is set to `1`, it means that the task will recur on this specified day weekly.
5	The start time	Node 1	2	The value is in minutes. The maximum value is 1439.
6	The end time	Node 1	2	The value is in minutes. The maximum value is 1439.
7	Hue	Node 1	2	0x03 and 0x10: values in hexadecimal format, big endian. The first byte indicates hundreds. The second byte indicates tens and ones. Value range: 0 to 360.
8	Saturation (%)	Node 1	1	0x10: a value in hexadecimal format. Value range: 0 to 100.
9	Value (%)	Node 1	1	0x10: a value in hexadecimal format. Value range: 0 to 100.
10	Brightness (%)	Node 1	1	0x10: a value in hexadecimal format. Value range: 0 to 100.
11	Color temperature (%)	Node 1	1	0x10: a value in hexadecimal format. Value range: 0 to 100.
…	…	…	…	…

If multiple time nodes are set, fields from sequence No. 3 to 13 are duplicated.

Description of schedule setting

If all the bits are 0, it indicates a one-time task. If a bit is set to 1, it indicates the task is enabled on that day of a week.

Reserved	Saturday	Friday	Thursday	Wednesday	Tuesday	Monday	Sunday
bit7	bit6	bit5	bit4	bit3	bit2	bit1	bit0

Custom functions

You can add custom functions that are not supported by standard functions. For more information, see Custom Functions.

Cloud functions

Cloud function supports cloud timing and jumping page. For more information, see Cloud Functions.

Cloud timing: allows you to implement the schedule feature without embedded development.
Jumping page: enables navigating to another web page, such as an online store and user guide.

Prev DocCustom Solution

Next DocEuropean Style Panel for Lighting Products