ColorSetting

The ColorSetting trait enables devices to control color properties, including RGB colors, HSV colors, and color temperature. This trait is essential for color-changing lights, LED strips, and other devices that support full-spectrum color control.

Supported Attributes

1. `colorModel` (String)

Type: String
Description: Specifies the color model supported by the device
Possible Values: "rgb", "hsv"
Usage: Determines which color parameters are valid for the device

2. `colorTemperatureRange` (Object)

Type: Object with temperature range
Description: Defines the valid color temperature range in Kelvin

Structure:

{
  "temperatureMinK": 2000,
  "temperatureMaxK": 6500
}

Usage: Validates color temperature commands

3. `commandOnlyColorSetting` (Boolean)

Type: Boolean
Description: When true, The device only accepts color commands and cannot be queried
Default: false
Usage: Set to true for devices that can receive commands but don't report their color state

Supported Commands

1. `ColorAbsolute`

Sets the device to a specific color or color temperature.

Parameters

{
  color: {
    spectrumRGB?: number,        // RGB color value (0-16777215)
    spectrumHSV?: {             // HSV color object
      hue: number,              // Hue (0-360 degrees)
      saturation: number,       // Saturation (0.0-1.0)
      value: number            // Value/Brightness (0.0-1.0)
    },
    temperature?: number        // Color temperature in Kelvin
  }
}

Parameter Validation

Only one color parameter should be provided (RGB, HSV, or temperature)
spectrumRGB: Must be between 0 and 16777215 (0x000000 to 0xFFFFFF)
spectrumHSV: Only valid if colorModel is "hsv"
temperature: Must be within colorTemperatureRange
RGB colors are only valid if colorModel is "rgb"

Usage Examples

RGB Color Control

Set Red Color

{
  "sn": "COLOR_LIGHT_SERIAL",
  "iotDevs": ["color_main"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumRGB": 16711680
        }
      }
    }
  ]
}

Set Green Color

{
  "sn": "COLOR_LIGHT_SERIAL",
  "iotDevs": ["color_main"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumRGB": 65280
        }
      }
    }
  ]
}

Set Blue Color

{
  "sn": "COLOR_LIGHT_SERIAL",
  "iotDevs": ["color_main"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumRGB": 255
        }
      }
    }
  ]
}

Set Purple Color

{
  "sn": "COLOR_LIGHT_SERIAL",
  "iotDevs": ["color_main"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumRGB": 8388736
        }
      }
    }
  ]
}

HSV Color Control

Set Red Color (HSV)

{
  "sn": "HSV_LIGHT_SERIAL",
  "iotDevs": ["color_main"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumHSV": {
            "hue": 0,
            "saturation": 1.0,
            "value": 1.0
          }
        }
      }
    }
  ]
}

Set Blue Color (HSV)

{
  "sn": "HSV_LIGHT_SERIAL",
  "iotDevs": ["color_main"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumHSV": {
            "hue": 240,
            "saturation": 1.0,
            "value": 1.0
          }
        }
      }
    }
  ]
}

Set Pastel Pink (HSV)

{
  "sn": "HSV_LIGHT_SERIAL",
  "iotDevs": ["color_main"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumHSV": {
            "hue": 330,
            "saturation": 0.3,
            "value": 0.9
          }
        }
      }
    }
  ]
}

Color Temperature Control

Set Warm White (2700K)

{
  "sn": "TUNABLE_WHITE_SERIAL",
  "iotDevs": ["white_main"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "temperature": 2700
        }
      }
    }
  ]
}

Set Cool White (5000K)

{
  "sn": "TUNABLE_WHITE_SERIAL",
  "iotDevs": ["white_main"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "temperature": 5000
        }
      }
    }
  ]
}

Set Daylight (6500K)

{
  "sn": "TUNABLE_WHITE_SERIAL",
  "iotDevs": ["white_main"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "temperature": 6500
        }
      }
    }
  ]
}

Combined with Other Commands

Turn On with Color

{
  "sn": "COLOR_LIGHT_SERIAL",
  "iotDevs": ["color_main"],
  "iotCmds": [
    {
      "command": "OnOff",
      "params": {
        "on": true
      }
    },
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumRGB": 16776960
        }
      }
    }
  ]
}

Set Color and Brightness

{
  "sn": "COLOR_LIGHT_SERIAL",
  "iotDevs": ["color_main"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumRGB": 65535
        }
      }
    },
    {
      "command": "BrightnessAbsolute",
      "params": {
        "brightness": 75
      }
    }
  ]
}

Color Fade Effect (using OnOff fade)

{
  "sn": "COLOR_LIGHT_SERIAL",
  "iotDevs": ["color_main"],
  "iotCmds": [
    {
      "command": "OnOff",
      "params": {
        "on": true,
        "fadeSetting": {
          "fadeType": "withFade",
          "fade": {
            "brightnessStart": 0,
            "brightnessEnd": 100,
            "duration": 3,
            "spectrumRGB": 16711935
          }
        }
      }
    }
  ]
}

Device Types Using ColorSetting Trait

RGB/RGBW Lights

Smart bulbs with color-changing
LED strip controllers
RGB spotlights
Color-changing ceiling lights

Tunable White Lights

CCT (Correlated Color Temperature) bulbs
Tunable white LED strips
Professional photography lights
Circadian rhythm lights

Entertainment Lighting

Gaming lights
TV backlighting
Party/mood lighting
Stage lighting

Architectural Lighting

Building facade lighting
Landscape lighting
Accent lighting
Art installation lighting

Color Model Configurations

RGB Color Light

{
  "traits": ["OnOff", "Brightness", "ColorSetting"],
  "attributes": [
    {
      "name": "colorModel",
      "value": "rgb"
    }
  ]
}

HSV Color Light

{
  "traits": ["OnOff", "Brightness", "ColorSetting"],
  "attributes": [
    {
      "name": "colorModel",
      "value": "hsv"
    }
  ]
}

Tunable White Light

{
  "traits": ["OnOff", "Brightness", "ColorSetting"],
  "attributes": [
    {
      "name": "colorTemperatureRange",
      "value": {
        "temperatureMinK": 2700,
        "temperatureMaxK": 6500
      }
    }
  ]
}

Full-Feature Color Light

{
  "traits": ["OnOff", "Brightness", "ColorSetting"],
  "attributes": [
    {
      "name": "colorModel",
      "value": "rgb"
    },
    {
      "name": "colorTemperatureRange",
      "value": {
        "temperatureMinK": 2000,
        "temperatureMaxK": 6500
      }
    }
  ]
}

Color Reference

Common RGB Values

Color	RGB Value	Hex
Red	16711680	#FF0000
Green	65280	#00FF00
Blue	255	#0000FF
Yellow	16776960	#FFFF00
Cyan	65535	#00FFFF
Magenta	16711935	#FF00FF
White	16777215	#FFFFFF
Orange	16753920	#FFA500
Purple	8388736	#800080
Pink	16761035	#FFC0CB

Color Temperature Reference

Temperature	Description	Usage
2000K	Candlelight	Very warm, relaxing
2700K	Warm White	Home lighting, evening
3000K	Soft White	Living areas
4000K	Cool White	Offices, kitchens
5000K	Daylight	Task lighting
6500K	Cool Daylight	Photography, detailed work

HSV Color Examples

Color	Hue	Saturation	Value
Red	0°	1.0	1.0
Orange	30°	1.0	1.0
Yellow	60°	1.0	1.0
Green	120°	1.0	1.0
Cyan	180°	1.0	1.0
Blue	240°	1.0	1.0
Magenta	300°	1.0	1.0

Best Practices

1. Understand Color Models

Check device colorModel attribute before sending RGB/HSV commands
Use an appropriate color space for the device capabilities
Consider color accuracy requirements for the application

2. Color Temperature Usage

Use warm temperatures (2700K-3000K) for relaxation and evening
Use cool temperatures (4000K-6500K) for productivity and task lighting
Consider circadian rhythm effects when automating color temperature

3. RGB Color Conversion

Convert between color spaces when necessary
Use standard color conversion formulas
Test colors on actual devices for accuracy

4. Performance Optimization

Combine color commands with brightness and on/off for efficiency
Use fade effects for smooth color transitions
Cache frequently used colors

5. User Experience

Provide color presets for common scenarios
Allow custom color saving and recall
Consider accessibility for color-blind users

Related Traits

The ColorSetting trait is commonly combined with:

OnOff: Essential for complete lighting control
Brightness: For intensity control with color
LightEffects: For dynamic color effects
Timer: For scheduled color changes
Scene: For preset color configurations

State Reporting

Devices with the ColorSetting trait typically report:

color: Current color settings
- spectrumRGB: Current RGB value (if RGB model)
- spectrumHSV: Current HSV values (if HSV model)
- temperature: Current color temperature (if supported)
on: Current on/off state
brightness: Current brightness level
online: Device connectivity status

Query current color state:

curl -X POST "https://api.ultroncloud.com/usr/v5/GetGroupDeviceStates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{"groupId": "YOUR_LOCATION_ID", "snList": ["SN1", "SN2"]}'

Advanced Features

Color Scenes

Create color-based scenes:

{
  "command": "ActivateScene",
  "params": {
    "scene": "sunset_mode",
    "sceneSettings": {
      "color": {
        "temperature": 2200
      },
      "brightness": 40
    }
  }
}

Scheduled Color Changes

Use with Timer for automated color transitions:

{
  "command": "TimerStart",
  "params": {
    "timerTimeSec": 1800,
    "scheduledCommands": [
      {
        "command": "ColorAbsolute",
        "params": {
          "color": {
            "temperature": 2700
          }
        }
      }
    ]
  }
}

Multi-Zone Color Control

Control multiple color zones:

{
  "sn": "MULTI_ZONE_LIGHT_SERIAL",
  "iotDevs": ["zone1", "zone2", "zone3"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumRGB": 16711680
        }
      }
    }
  ]
}

Technical Considerations

Color Accuracy

Different devices may render colors differently
Consider color calibration for critical applications
Test color reproduction across device types

Power Consumption

Full brightness white typically consumes the most power
Colored light may consume less power than white light
Consider energy efficiency in color selection

Heat Generation

High brightness and certain colors generate more heat
Consider thermal management for enclosed fixtures
Monitor device temperature in intensive applications