OnOff

Overview

The OnOff trait provides basic on/off control functionality for IoT devices. This is one of the most fundamental traits, enabling devices to be turned on or off, with optional advanced features like fade effects, intermittent operation, and delegation support.

Supported Attributes

1. `commandOnlyOnOff` (Boolean)

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

2. `queryOnlyOnOff` (Boolean)

Type: Boolean
Description: When true, The device can only be queried for its state, but cannot accept on/off commands
Default: false
Usage: Set to true for read-only devices or sensors that report on/off status but cannot be controlled

3. `intermittent` (Boolean)

Type: Boolean
Description: When true, The device supports intermittent operation (blinking, pulsing, etc.)
Default: false
Usage: Enables onInterval and offInterval parameters in commands

4. `timeStepRange` (Object)

Type: Object with min and max properties
Description: Defines the valid range for time intervals in milliseconds when using intermittent operation
Structure:
```
{
  "min": 100,
  "max": 10000
}
```
Usage: Validates onInterval and offInterval parameter values

5. `supportOnOffDelegated` (Boolean)

Type: Boolean
Description: When true, he on/off functionality is delegated to another device
Default: false
Usage: Typically used with queryOnlyOnOff: true for devices that control other devices

6. `detectFunctions` (Array)

Type: Array of strings
Description: Specifies detection functions supported by the device
Possible Values: ["LowToHigh", "HighToLow", "Disabled"]
Usage: Used for devices that can detect and report various conditions

Supported Commands

1. `OnOff`

The primary command for controlling devices' on/off state.

Parameters

{
  on: boolean,                    // Required: true to turn on, false to turn off
  onInterval?: number,           // Optional: On duration in milliseconds (for intermittent)
  offInterval?: number,          // Optional: Off duration in milliseconds (for intermittent)
  fadeSetting?: {                // Optional: Fade effect settings
    fadeType: "noFade" | "withFade",
    fade?: {
      brightnessStart?: number,  // Starting brightness (0-100)
      brightnessEnd?: number,    // Ending brightness (0-100)
      duration?: number,         // Fade duration in seconds
      temperature?: number,      // Color temperature in Kelvin
      spectrumRGB?: number,      // RGB color value
      spectrumHSV?: {           // HSV color object
        hue: number,            // Hue (0-360)
        saturation: number,     // Saturation (0-1)
        value: number          // Value/Brightness (0-1)
      }
    }
  }
}

Parameter Validation

on: Required boolean value
onInterval and offInterval: Only valid if intermittent attribute is true
Time intervals must be within timeStepRange if specified
fadeSetting: Only valid for devices that support the Brightness trait with fade attribute
Commands are rejected if queryOnlyOnOff is true

Usage Examples

Basic On/Off Control

Turn Device On

{
  "sn": "DEVICE_SERIAL_NUMBER",
  "iotDevs": ["main_endpoint"],
  "iotCmds": [
    {
      "command": "OnOff",
      "params": {
        "on": true
      }
    }
  ]
}

Turn Device Off

{
  "sn": "DEVICE_SERIAL_NUMBER",
  "iotDevs": ["main_endpoint"],
  "iotCmds": [
    {
      "command": "OnOff",
      "params": {
        "on": false
      }
    }
  ]
}

Intermittent Operation (Blinking)

Blinking Light (1 second on, 0.5 seconds off)

{
  "sn": "LIGHT_SERIAL_NUMBER",
  "iotDevs": ["light_main"],
  "iotCmds": [
    {
      "command": "OnOff",
      "params": {
        "on": true,
        "onInterval": 1000,
        "offInterval": 500
      }
    }
  ]
}

Stop Blinking (Solid On)

{
  "sn": "LIGHT_SERIAL_NUMBER",
  "iotDevs": ["light_main"],
  "iotCmds": [
    {
      "command": "OnOff",
      "params": {
        "on": true
      }
    }
  ]
}

Fade Effects (for devices with Brightness trait)

Turn On with Fade Effect

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

Turn Off with Fade Effect

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

Turn On with Color Fade (RGB)

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

Turn On with Color Temperature Fade

{
  "sn": "COLOR_LIGHT_SERIAL",
  "iotDevs": ["color_main"],
  "iotCmds": [
    {
      "command": "OnOff",
      "params": {
        "on": true,
        "fadeSetting": {
          "fadeType": "withFade",
          "fade": {
            "brightnessStart": 10,
            "brightnessEnd": 90,
            "duration": 4,
            "temperature": 3000
          }
        }
      }
    }
  ]
}

Device Types Using OnOff Trait

Smart Lights

Basic on/off lights
Dimmable lights (with fade support)
Color lights (with color fade support)
LED strips

Smart Switches

Wall switches
Smart plugs
Power outlets
Relay modules

Appliances

Fans (basic on/off)
Heaters
Air purifiers
Humidifiers

Attribute Combinations

Command-Only Device

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

Query-Only Device (Sensor)

{
  "traits": ["OnOff"],
  "attributes": [
    {
      "name": "queryOnlyOnOff",
      "value": true
    }
  ]
}

Intermittent Support

{
  "traits": ["OnOff"],
  "attributes": [
    {
      "name": "intermittent",
      "value": true
    },
    {
      "name": "timeStepRange",
      "value": {
        "min": 100,
        "max": 5000
      }
    }
  ]
}

Delegated Control

{
  "traits": ["OnOff"],
  "attributes": [
    {
      "name": "supportOnOffDelegated",
      "value": true
    },
    {
      "name": "queryOnlyOnOff",
      "value": true
    }
  ]
}

Best Practices

1. Check Device Capabilities

Always verify device attributes before using advanced features:

Check intermittent before using interval parameters
Verify Brightness trait and fade attribute before using fade effects
Respect queryOnlyOnOff and commandOnlyOnOff restrictions

2. Validate Parameters

Ensure interval values are within timeStepRange
Validate fade parameters against color and brightness capabilities
Use appropriate fade durations (typically 1-10 seconds)

3. Handle State Changes

Allow time for device state changes to complete
Monitor device state through sensor data APIs
Handle offline devices gracefully

4. Optimize Performance

Combine OnOff with other commands when possible
Use fade effects to create smooth transitions
Consider the user experience when using intermittent operation

Related Traits

The OnOff trait is often combined with other traits:

Brightness: Enables fade effects and dimming control
ColorSetting: Allows color fade effects
Timer: Provides scheduled on/off operations
Scene: Includes on/off state in scene configurations
Toggles: May include on/off as one of multiple toggles

State Reporting

Devices with the OnOff trait typically report the following states:

on: Current on/off state (boolean)

Query the current state using:

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