Modes

The Modes trait enables devices to operate in different predefined modes. This trait is used for devices that have multiple operating states or configurations, such as air conditioners, washing machines, coffee makers, and other appliances with various operational modes.

Supported Attributes

1. `availableModes` (Array)

Type: Array of mode objects
Description: Defines all available operating modes for the device

Structure:

[
  {
    "name": "operation_mode",
    "name_values": [
      {
        "name_synonym": ["operation", "mode", "setting"],
        "lang": "en"
      }
    ],
    "settings": [
      {
        "setting_name": "auto",
        "setting_values": [
          {
            "setting_synonym": ["auto", "automatic", "smart"],
            "lang": "en"
          }
        ]
      },
      {
        "setting_name": "manual",
        "setting_values": [
          {
            "setting_synonym": ["manual", "custom", "user"],
            "lang": "en"
          }
        ]
      }
    ],
    "ordered": false
  }
]

Usage: Defines mode categories and their possible settings

2. `commandOnlyModes` (Boolean)

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

Supported Commands

1. `SetModes`

Sets one or more operating modes for the device.

Parameters

{
  updateModeSettings: {
    [modeName: string]: string  // Mode name to setting value mapping
  }
}

Parameter Validation

updateModeSettings: Object with mode names as keys and setting values as values
Mode names must exist in availableModes
Setting values must be valid for the specified mode
Multiple modes can be set simultaneously if the device supports it

Usage Examples

Air Conditioner Modes

Set to Cooling Mode

{
  "sn": "AC_UNIT_SERIAL",
  "iotDevs": ["ac_controller"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "operation_mode": "cool"
        }
      }
    }
  ]
}

Set to Auto Mode with Fan Speed

{
  "sn": "AC_UNIT_SERIAL",
  "iotDevs": ["ac_controller"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "operation_mode": "auto",
          "fan_mode": "medium"
        }
      }
    }
  ]
}

Set to Heating Mode

{
  "sn": "HEAT_PUMP_SERIAL",
  "iotDevs": ["heat_pump"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "operation_mode": "heat"
        }
      }
    }
  ]
}

Washing Machine Modes

Set Wash Cycle

{
  "sn": "WASHING_MACHINE_SERIAL",
  "iotDevs": ["washer_control"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "wash_cycle": "delicate",
          "water_temperature": "cold",
          "spin_speed": "low"
        }
      }
    }
  ]
}

Set Heavy Duty Cycle

{
  "sn": "WASHING_MACHINE_SERIAL",
  "iotDevs": ["washer_control"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "wash_cycle": "heavy_duty",
          "water_temperature": "hot",
          "spin_speed": "high"
        }
      }
    }
  ]
}

Coffee Maker Modes

Set Brew Strength and Size

{
  "sn": "COFFEE_MAKER_SERIAL",
  "iotDevs": ["brew_controller"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "brew_strength": "strong",
          "cup_size": "large",
          "brew_temperature": "hot"
        }
      }
    }
  ]
}

Set Espresso Mode

{
  "sn": "ESPRESSO_MACHINE_SERIAL",
  "iotDevs": ["espresso_unit"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "drink_type": "espresso",
          "grind_size": "fine",
          "extraction_pressure": "high"
        }
      }
    }
  ]
}

Robot Vacuum Modes

Set Cleaning Mode

{
  "sn": "ROBOT_VACUUM_SERIAL",
  "iotDevs": ["vacuum_main"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "cleaning_mode": "auto",
          "suction_power": "medium",
          "cleaning_pattern": "spiral"
        }
      }
    }
  ]
}

Set Spot Cleaning

{
  "sn": "ROBOT_VACUUM_SERIAL",
  "iotDevs": ["vacuum_main"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "cleaning_mode": "spot",
          "suction_power": "high"
        }
      }
    }
  ]
}

Air Purifier Modes

Set Auto Mode with Sleep Setting

{
  "sn": "AIR_PURIFIER_SERIAL",
  "iotDevs": ["purifier_main"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "operation_mode": "auto",
          "noise_level": "quiet",
          "light_mode": "dim"
        }
      }
    }
  ]
}

Oven Modes

Set Baking Mode

{
  "sn": "SMART_OVEN_SERIAL",
  "iotDevs": ["oven_controller"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "cooking_mode": "bake",
          "convection": "on",
          "preheat": "enabled"
        }
      }
    }
  ]
}

Set Broil Mode

{
  "sn": "SMART_OVEN_SERIAL",
  "iotDevs": ["oven_controller"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "cooking_mode": "broil",
          "rack_position": "top"
        }
      }
    }
  ]
}

Device Types Using Modes Trait

HVAC Equipment

Air conditioners
Heat pumps
Dehumidifiers
Air purifiers

Kitchen Appliances

Ovens and ranges
Microwave ovens
Coffee makers
Dishwashers

Laundry Appliances

Washing machines
Dryers
Washer-dryer combos

Cleaning Devices

Robot vacuums
Steam cleaners
Carpet cleaners

Entertainment Systems

Audio systems
Projectors
Gaming consoles

Common Mode Categories

Operation Modes

{
  "name": "operation_mode",
  "settings": [
    {"setting_name": "off"},
    {"setting_name": "auto"},
    {"setting_name": "manual"},
    {"setting_name": "eco"},
    {"setting_name": "turbo"}
  ]
}

Fan Modes

{
  "name": "fan_mode",
  "settings": [
    {"setting_name": "auto"},
    {"setting_name": "low"},
    {"setting_name": "medium"},
    {"setting_name": "high"},
    {"setting_name": "quiet"}
  ]
}

Temperature Modes

{
  "name": "temperature_mode",
  "settings": [
    {"setting_name": "cold"},
    {"setting_name": "warm"},
    {"setting_name": "hot"}
  ]
}

Cleaning Modes

{
  "name": "cleaning_mode",
  "settings": [
    {"setting_name": "auto"},
    {"setting_name": "spot"},
    {"setting_name": "edge"},
    {"setting_name": "max"}
  ]
}

Device Configuration Examples

Air Conditioner with Multiple Modes

{
  "traits": ["OnOff", "TemperatureSetting", "FanSpeed", "Modes"],
  "attributes": [
    {
      "name": "availableModes",
      "value": [
        {
          "name": "operation_mode",
          "settings": [
            {"setting_name": "cool"},
            {"setting_name": "heat"},
            {"setting_name": "auto"},
            {"setting_name": "fan_only"},
            {"setting_name": "dry"}
          ]
        },
        {
          "name": "swing_mode",
          "settings": [
            {"setting_name": "off"},
            {"setting_name": "vertical"},
            {"setting_name": "horizontal"},
            {"setting_name": "both"}
          ]
        }
      ]
    }
  ]
}

Washing Machine Configuration

{
  "traits": ["OnOff", "StartStop", "Modes", "Timer"],
  "attributes": [
    {
      "name": "availableModes",
      "value": [
        {
          "name": "wash_cycle",
          "settings": [
            {"setting_name": "normal"},
            {"setting_name": "delicate"},
            {"setting_name": "heavy_duty"},
            {"setting_name": "quick_wash"}
          ]
        },
        {
          "name": "water_temperature",
          "settings": [
            {"setting_name": "cold"},
            {"setting_name": "warm"},
            {"setting_name": "hot"}
          ]
        },
        {
          "name": "spin_speed",
          "settings": [
            {"setting_name": "low"},
            {"setting_name": "medium"},
            {"setting_name": "high"}
          ]
        }
      ]
    }
  ]
}

Coffee Maker Configuration

{
  "traits": ["OnOff", "Modes"],
  "attributes": [
    {
      "name": "availableModes",
      "value": [
        {
          "name": "brew_strength",
          "settings": [
            {"setting_name": "mild"},
            {"setting_name": "medium"},
            {"setting_name": "strong"}
          ]
        },
        {
          "name": "cup_size",
          "settings": [
            {"setting_name": "small"},
            {"setting_name": "medium"},
            {"setting_name": "large"}
          ]
        }
      ]
    }
  ]
}

Best Practices

1. Understand Mode Dependencies

Some modes may require specific combinations of settings
Check device documentation for mode interactions
Validate mode combinations before sending commands

2. Mode Transition Handling

Allow time for mode changes to take effect
Some devices may need to stop current operation before the mode change
Monitor device state during mode transitions

3. User Experience

Provide clear descriptions of what each mode does
Group related modes logically in user interfaces
Remember the user's preferred mode settings

4. Error Prevention

Validate mode combinations before sending commands
Provide feedback on invalid combinations
Implement mode presets for common configurations

5. Performance Optimization

Batch mode changes when possible
Cache current mode states to avoid unnecessary commands
Use appropriate timeouts for mode change operations

Related Traits

The Modes trait is commonly combined with:

OnOff: For basic device power control
StartStop: For operation control
Timer: For scheduled mode changes
TemperatureSetting: For climate control devices
FanSpeed: For devices with fan components
Scene: For preset mode configurations

State Reporting

Devices with the Modes trait typically report:

currentModeSettings: Current mode settings for all modes
availableModes: Supported modes and settings (from attributes)
modeChangeInProgress: Whether a mode change is currently happening
lastModeChange: Timestamp of last mode change
online: Device connectivity status

Query current modes:

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