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.

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%.

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%.

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%.

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.