Toggles

The Toggles trait enables devices to control multiple independent toggle switches or boolean settings. This trait is used for devices with multiple on/off controls, feature toggles, or binary configuration options that can be controlled independently.

Supported Attributes

1. `availableToggles` (Array)

Type: Array of toggle objects
Description: Defines all available toggle switches for the device

Structure:

[
  {
    "name": "night_mode",
    "name_values": [
      {
        "name_synonym": ["night mode", "sleep mode", "quiet"],
        "lang": "en"
      }
    ]
  },
  {
    "name": "eco_mode",
    "name_values": [
      {
        "name_synonym": ["eco mode", "energy saver", "efficient"],
        "lang": "en"
      }
    ]
  },
  {
    "name": "child_lock",
    "name_values": [
      {
        "name_synonym": ["child lock", "safety lock", "parental control"],
        "lang": "en"
      }
    ]
  }
]

Usage: Defines which toggles are available and their synonyms

2. `commandOnlyToggles` (Boolean)

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

Supported Commands

1. `SetToggles`

Sets the state of one or more toggle switches.

Parameters

{
  updateToggleSettings: {
    [toggleName: string]: boolean  // Toggle name to boolean state mapping
  }
}

Parameter Validation

updateToggleSettings: Object with toggle names as keys and boolean values
Toggle names must exist in availableToggles
Values must be boolean (true or false)
Multiple toggles can be set simultaneously

Usage Examples

Smart Appliance Toggles

Enable Night Mode

{
  "sn": "SMART_APPLIANCE_SERIAL",
  "iotDevs": ["main_controller"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "night_mode": true
        }
      }
    }
  ]
}

Disable Eco Mode

{
  "sn": "SMART_APPLIANCE_SERIAL",
  "iotDevs": ["main_controller"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "eco_mode": false
        }
      }
    }
  ]
}

Enable Multiple Features

{
  "sn": "SMART_APPLIANCE_SERIAL",
  "iotDevs": ["main_controller"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "night_mode": true,
          "eco_mode": true,
          "child_lock": true
        }
      }
    }
  ]
}

Air Purifier Toggles

Enable Auto Mode and Quiet Operation

{
  "sn": "AIR_PURIFIER_SERIAL",
  "iotDevs": ["purifier_main"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "auto_mode": true,
          "quiet_operation": true,
          "display_lights": false
        }
      }
    }
  ]
}

Reset to Default Settings

{
  "sn": "AIR_PURIFIER_SERIAL",
  "iotDevs": ["purifier_main"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "auto_mode": false,
          "quiet_operation": false,
          "display_lights": true,
          "filter_reminder": true
        }
      }
    }
  ]
}

Smart TV Toggles

Configure Display Settings

{
  "sn": "SMART_TV_SERIAL",
  "iotDevs": ["tv_main"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "motion_smoothing": false,
          "hdr_mode": true,
          "game_mode": true,
          "voice_control": false
        }
      }
    }
  ]
}

Robot Vacuum Toggles

Set Cleaning Preferences

{
  "sn": "ROBOT_VACUUM_SERIAL",
  "iotDevs": ["vacuum_main"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "edge_cleaning": true,
          "carpet_boost": true,
          "do_not_disturb": false,
          "return_to_dock": true
        }
      }
    }
  ]
}

Smart Thermostat Toggles

Configure Thermostat Features

{
  "sn": "SMART_THERMOSTAT_SERIAL",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "learning_mode": true,
          "geofencing": true,
          "humidity_control": false,
          "energy_reports": true
        }
      }
    }
  ]
}

Smart Speaker Toggles

Configure Audio Settings

{
  "sn": "SMART_SPEAKER_SERIAL",
  "iotDevs": ["speaker_main"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "voice_activation": true,
          "bass_boost": false,
          "noise_cancellation": true,
          "privacy_mode": false
        }
      }
    }
  ]
}

Security System Toggles

Configure Security Features

{
  "sn": "SECURITY_SYSTEM_SERIAL",
  "iotDevs": ["security_panel"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "motion_detection": true,
          "door_chime": true,
          "silent_alarm": false,
          "mobile_alerts": true
        }
      }
    }
  ]
}

Smart Light Toggles

Configure Light Features

{
  "sn": "SMART_LIGHT_SERIAL",
  "iotDevs": ["light_controller"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "circadian_rhythm": true,
          "motion_sensor": true,
          "fade_transitions": true,
          "power_memory": false
        }
      }
    }
  ]
}

Device Types Using Toggles Trait

Home Appliances

Smart refrigerators
Washing machines
Dishwashers
Microwave ovens

Climate Control

Air conditioners
Air purifiers
Dehumidifiers
Smart thermostats

Entertainment Systems

Smart TVs
Audio systems
Gaming consoles
Streaming devices

Security Devices

Security panels
Smart cameras
Door locks
Motion sensors

Lighting Systems

Smart lights
Light switches
Dimmer controls
Lighting controllers

Common Toggle Categories

Power Management Toggles

[
  {"name": "eco_mode"},
  {"name": "power_save"},
  {"name": "standby_mode"},
  {"name": "auto_shutdown"}
]

User Interface Toggles

[
  {"name": "display_lights"},
  {"name": "sound_alerts"},
  {"name": "voice_prompts"},
  {"name": "button_lock"}
]

Safety and Security Toggles

[
  {"name": "child_lock"},
  {"name": "safety_mode"},
  {"name": "tamper_alert"},
  {"name": "emergency_mode"}
]

Automation Toggles

[
  {"name": "auto_mode"},
  {"name": "learning_mode"},
  {"name": "schedule_enabled"},
  {"name": "sensor_control"}
]

Connectivity Toggles

[
  {"name": "wifi_enabled"},
  {"name": "bluetooth_pairing"},
  {"name": "remote_access"},
  {"name": "cloud_sync"}
]

Device Configuration Examples

Smart Air Conditioner

{
  "traits": ["OnOff", "TemperatureSetting", "FanSpeed", "Toggles"],
  "attributes": [
    {
      "name": "availableToggles",
      "value": [
        {"name": "eco_mode"},
        {"name": "quiet_operation"},
        {"name": "swing_mode"},
        {"name": "sleep_mode"},
        {"name": "display_lights"},
        {"name": "wifi_control"}
      ]
    }
  ]
}

Smart Washing Machine

{
  "traits": ["OnOff", "StartStop", "Modes", "Toggles", "Timer"],
  "attributes": [
    {
      "name": "availableToggles",
      "value": [
        {"name": "extra_rinse"},
        {"name": "pre_wash"},
        {"name": "child_lock"},
        {"name": "delay_start"},
        {"name": "end_of_cycle_alert"},
        {"name": "steam_option"}
      ]
    }
  ]
}

Smart Security Camera

{
  "traits": ["OnOff", "CameraStream", "Toggles"],
  "attributes": [
    {
      "name": "availableToggles",
      "value": [
        {"name": "motion_detection"},
        {"name": "night_vision"},
        {"name": "audio_recording"},
        {"name": "privacy_mode"},
        {"name": "cloud_storage"},
        {"name": "mobile_alerts"}
      ]
    }
  ]
}

Best Practices

1. Understand Toggle Dependencies

Some toggles may be mutually exclusive
Check device documentation for toggle interactions
Validate toggle combinations before sending commands

2. Toggle State Management

Keep track of current toggle states in your application
Handle toggle state persistence across device power cycles
Provide clear feedback on toggle state changes

3. User Experience

Group-related toggles logically in user interfaces
Provide clear descriptions of what each toggle does
Use consistent naming and terminology

4. Error Prevention

Validate toggle combinations before sending commands
Provide warnings for conflicting settings
Implement toggle presets for common configurations

5. Performance Optimization

Batch toggle changes when possible
Cache current toggle states to avoid unnecessary queries
Use appropriate timeouts for toggle operations

Related Traits

The Toggles trait is commonly combined with:

OnOff: For basic device power control
Modes: For operational mode settings
Scene: For preset toggle configurations
Timer: For scheduled toggle changes
StatusReport: For toggle state monitoring

State Reporting

Devices with the Toggles trait typically report:

currentToggleSettings: Current state of all toggles
availableToggles: Supported toggles (from attributes)
toggleLockStatus: Which toggles are currently locked
lastToggleChange: Timestamp of last toggle change
online: Device connectivity status

Query current toggle states:

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