API Reference
Start typing to search…

Brightness

Overview

The Brightness trait enables devices to control light intensity levels. This trait is commonly used for dimmable lights, LED strips, and other lighting devices that support variable brightness control beyond simple on/off functionality.

Supported Attributes

1. commandOnlyBrightness (Boolean)

  • Type: Boolean
  • Description: When true, the device only accepts brightness commands and cannot be queried for its current brightness level
  • Default: false
  • Usage: Set to true for devices that can receive brightness commands but don't report their brightness state back

2. availableDimmingTypes (Array)

  • Type: Array of strings
  • Description: Specifies the dimming control methods supported by the device
  • Possible Values: ["0-10V", "1-10V"]
  • Usage: Indicates the electrical dimming method used by the device

3. fade (Object)

  • Type: Object containing fade configuration
  • Description: Defines fade effect capabilities and constraints
  • Structure: 
    {
  "durationRange": {
    "min": 1,
    "max": 60
  }
}
  • Usage: Enables smooth brightness transitions with configurable duration

4. colorProfile (Object)

  • Type: Object defining color characteristics
  • Description: Specifies color rendering and profile information for the lighting device
  • Usage: Used for advanced color management and calibration

5. brightnessRangeConfigurable (Boolean)

  • Type: Boolean
  • Description: When true, the device allows configuration of its minimum and maximum brightness range
  • Default: false
  • Usage: Enables custom brightness range settings for specific installations

Supported Commands

1. BrightnessAbsolute

Sets the device to a specific brightness level.

Parameters

{
  brightness: number  // Required: Brightness level (0-100)
}

Parameter Validation

  • brightness: Must be between 0 and 100 (inclusive)
  • For devices with availableDimmingTypes, brightness cannot be 0 (minimum is 1)
  • Value represents percentage of maximum brightness

2. BrightnessRelative

Adjusts the current brightness by a relative amount.

Parameters

{
  brightnessRelativePercent: number  // Required: Relative brightness change (-100 to +100)
}

Parameter Validation

  • brightnessRelativePercent: Must be between -100 and +100
  • Positive values increase brightness, negative values decrease
  • Final brightness is clamped to valid range (0-100 or 1-100 depending on dimming type)

Usage Examples

Basic Brightness Control

Set Brightness to 75%

{
  "sn": "DIMMER_SERIAL_NUMBER",
  "iotDevs": ["dimmer_ch1"],
  "iotCmds": [
    {
      "command": "BrightnessAbsolute",
      "params": {
        "brightness": 75
      }
    }
  ]
}

Set Minimum Brightness

{
  "sn": "DIMMER_SERIAL_NUMBER",
  "iotDevs": ["dimmer_ch1"],
  "iotCmds": [
    {
      "command": "BrightnessAbsolute",
      "params": {
        "brightness": 1
      }
    }
  ]
}

Set Maximum Brightness

{
  "sn": "DIMMER_SERIAL_NUMBER",
  "iotDevs": ["dimmer_ch1"],
  "iotCmds": [
    {
      "command": "BrightnessAbsolute",
      "params": {
        "brightness": 100
      }
    }
  ]
}

Relative Brightness Adjustments

Increase Brightness by 20%

{
  "sn": "DIMMER_SERIAL_NUMBER",
  "iotDevs": ["dimmer_ch1"],
  "iotCmds": [
    {
      "command": "BrightnessRelative",
      "params": {
        "brightnessRelativePercent": 20
      }
    }
  ]
}

Decrease Brightness by 30%

{
  "sn": "DIMMER_SERIAL_NUMBER",
  "iotDevs": ["dimmer_ch1"],
  "iotCmds": [
    {
      "command": "BrightnessRelative",
      "params": {
        "brightnessRelativePercent": -30
      }
    }
  ]
}

Dim to Minimum (Relative)

{
  "sn": "DIMMER_SERIAL_NUMBER",
  "iotDevs": ["dimmer_ch1"],
  "iotCmds": [
    {
      "command": "BrightnessRelative",
      "params": {
        "brightnessRelativePercent": -100
      }
    }
  ]
}

Combined with OnOff Commands

Turn On and Set Brightness

{
  "sn": "DIMMER_SERIAL_NUMBER",
  "iotDevs": ["dimmer_ch1"],
  "iotCmds": [
    {
      "command": "OnOff",
      "params": {
        "on": true
      }
    },
    {
      "command": "BrightnessAbsolute",
      "params": {
        "brightness": 60
      }
    }
  ]
}

Fade On with Brightness (using OnOff fade)

{
  "sn": "DIMMER_SERIAL_NUMBER",
  "iotDevs": ["dimmer_ch1"],
  "iotCmds": [
    {
      "command": "OnOff",
      "params": {
        "on": true,
        "fadeSetting": {
          "fadeType": "withFade",
          "fade": {
            "brightnessStart": 0,
            "brightnessEnd": 80,
            "duration": 3
          }
        }
      }
    }
  ]
}

Multi-Channel Devices

Set Different Brightness for Multiple Channels

{
  "sn": "MULTI_DIMMER_SERIAL",
  "iotDevs": ["ch1", "ch2", "ch3"],
  "iotCmds": [
    {
      "command": "BrightnessAbsolute",
      "params": {
        "brightness": 80
      }
    }
  ]
}

Individual Channel Control

{
  "sn": "MULTI_DIMMER_SERIAL",
  "iotDevs": ["ch1"],
  "iotCmds": [
    {
      "command": "BrightnessAbsolute",
      "params": {
        "brightness": 50
      }
    }
  ]
}

Device Types Using Brightness Trait

Dimmable Lights

  • LED bulbs
  • Incandescent dimmers
  • Fluorescent dimmers
  • Halogen dimmers

LED Controllers

  • LED strip controllers
  • RGB controllers (brightness channel)
  • RGBW controllers
  • Addressable LED controllers

Architectural Lighting

  • Recessed lights
  • Track lighting
  • Under-cabinet lighting
  • Accent lighting

Professional Lighting

  • Stage lighting
  • Studio lighting
  • Photography lighting
  • Architectural fixtures

Attribute Combinations

Basic Dimmable Light

{
  "traits": ["OnOff", "Brightness"],
  "attributes": [
    {
      "name": "availableDimmingTypes",
      "value": ["TRIAC"]
    }
  ]
}

Professional Dimmer with Fade

{
  "traits": ["OnOff", "Brightness"],
  "attributes": [
    {
      "name": "availableDimmingTypes",
      "value": ["0-10V", "1-10V"]
    },
    {
      "name": "fade",
      "value": {
        "durationRange": {
          "min": 1,
          "max": 30
        }
      }
    }
  ]
}

Command-Only Dimmer

{
  "traits": ["OnOff", "Brightness"],
  "attributes": [
    {
      "name": "commandOnlyBrightness",
      "value": true
    },
    {
      "name": "commandOnlyOnOff",
      "value": true
    }
  ]
}

Configurable Range Dimmer

{
  "traits": ["OnOff", "Brightness"],
  "attributes": [
    {
      "name": "brightnessRangeConfigurable",
      "value": true
    },
    {
      "name": "availableDimmingTypes",
      "value": ["0-10V"]
    }
  ]
}

Dimming Types Explained

TRIAC Dimming

  • Description: Phase-cut dimming for AC loads
  • Usage: Traditional incandescent and some LED bulbs
  • Characteristics: May have minimum brightness limitations

0-10V Dimming

  • Description: Analog voltage control (0V = off, 10V = full brightness)
  • Usage: Professional LED fixtures
  • Characteristics: Smooth dimming, wide compatibility

1-10V Dimming

  • Description: Analog voltage control (1V = minimum, 10V = full brightness)
  • Usage: Commercial lighting systems
  • Characteristics: Cannot turn completely off via dimming signal

PWM Dimming

  • Description: Pulse Width Modulation
  • Usage: LED strips, DC lighting
  • Characteristics: Precise control, no minimum brightness

DALI Dimming

  • Description: Digital Addressable Lighting Interface
  • Usage: Professional building automation
  • Characteristics: Digital protocol, advanced features

Best Practices

1. Understand Dimming Limitations

  • Check availableDimmingTypes to understand device capabilities
  • Respect minimum brightness requirements for certain dimming types
  • Consider electrical compatibility when selecting dimming methods

2. Use Appropriate Brightness Levels

  • Start with moderate levels (40-60%) for general use
  • Use higher levels (80-100%) for task lighting
  • Use lower levels (10-30%) for ambient or mood lighting

3. Combine with Other Traits

  • Use with OnOff for complete lighting control
  • Combine with ColorSetting for full-featured color lights
  • Integrate with Timer for scheduled brightness changes

4. Handle Fade Effects

  • Use fade effects for smooth transitions
  • Respect fade duration limits from device attributes
  • Consider user experience when setting fade durations

5. Optimize for User Experience

  • Use relative adjustments for user-friendly controls
  • Provide visual feedback during brightness changes
  • Remember user preferences for different scenarios

Related Traits

The Brightness trait is commonly combined with:

  • OnOff: Essential for complete lighting control
  • ColorSetting: For color temperature and RGB control
  • LightEffects: For dynamic lighting effects
  • Timer: For scheduled brightness changes
  • Scene: For preset lighting configurations

State Reporting

Devices with the Brightness trait typically report:

  • brightness: Current brightness level (0-100)
  • on: Current on/off state
  • online: Device connectivity status

Query current brightness:

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"]}'

Technical Considerations

Electrical Compatibility

  • Verify load compatibility with the dimming type
  • Consider minimum load requirements for TRIAC dimmers
  • Check voltage requirements for 0-10V/1-10V systems

Performance Optimization

  • Use absolute commands for direct brightness setting
  • Use relative commands for incremental adjustments
  • Batch brightness commands with other operations when possible

Safety Considerations

  • Respect maximum brightness limits for heat-sensitive applications
  • Consider flicker-free dimming for video/photography applications
  • Ensure proper electrical installation for high-power dimmers