This guide explains how to retrieve the necessary information for devices whose models utilize the CustomToggles and/or CustomModes traits. These traits allow devices to define dynamic sets of on/off states (toggles) or selectable options (modes) that might vary between device models or firmware versions.

API Endpoint

POST /usr/v5/GetCustomControls

Use above endpoint to get definition and description for attributes within availableCustomModes and availableCustomToggles

Examples

Example Models:

{
  "AC_UNIT": {
    "type": "AC_UNIT",
    "traits": ["OnOff", "HumiditySetting", "Setpoints", "CustomToggles", "CustomModes"],
    "attrs": [
      {"name": "commandOnlyOnOff", "value": false},
      { "name": "humiditySetpointRange", "value": {"minPercent": 20, "maxPercent": 90} },
      {
        "name": "availableRanges",
        "value": {
          "ChgOperationTime": {
            "max": 2400, "min": 0, "step": 1, "unit": "minute", "name": "Refresh Operation Time"
          },
          "ChgStopTime"     : {
            "max": 2400, "min": 0, "step": 1, "unit": "minute", "name": "Refresh Stop Time"     
          },
          "HiFanHour"       : {
            "max": 2400, "min": 0, "step": 1, "unit": "hour"  , "name": "Filter Warning Hour"  
          },
          "HumidifierOff"   : {
            "max":   20, "min": 0, "step": 1, "unit": "%"     , "name": "Humidifier Off"       
          },
          "HumidifierOn"    : {
            "max":   20, "min": 0, "step": 1, "unit": "%"     , "name": "Humidifier On"       
          }
        }
      },
      {
        "name": "availableCustomToggles",
        "value": ["AutoMode", "AirConditioner", "Heater", "Dehumidification", "Refresh", "Purification"]
      },
      {
        "name": "availableCustomModes",
        "value": [
          { "name": "FanSpeed", "settings": ["1", "2", "3"], "ordered": true },
          { "name": "Filter", "settings": ["Reset"], "ordered": true },
          {
            "name": "HeaterSlider",
            "settings": [
              "16", "17", "18", "19", "20", "21", "22", "23", "24", 
              "25", "26", "27", "28", "29", "30", "31", "32"
            ],
            "ordered": true
          },
          {
            "name": "AirConditionerSlider", 
            "settings": [
              "16", "17", "18", "19", "20", "21", "22", "23", "24", 
              "25", "26", "27", "28", "29", "30", "31", "32"
            ],
            "ordered": true
          }
        ]
      }
    ]
  },
  "Ultron Device": {
    "type": "ULTRON",
    "traits": ["UltronCommand", "ReportState", "UltronConfig"],
    "attrs": [
      {"name": "rebootTime", "value": 20},
      {"name": "fwUpgradeTime", "value": 60},
      {
        "name": "sensorConfigurable",
        "value": { "Ultron Sensor": ["temp", "rh", "pm2_5", "hcho", "co2", "fan_hour"] }
      },
      {
        "name": "schedulable",
        "value": { "AC_UNIT": ["OnOff"] }
      },
      {"name": "periodicity", "value": true}
    ]
  },
  "Ultron Sensor": {
    "type": "ULTRON_SENSOR",
    "traits": ["Sensor"],
    "attrs": [
      {
        "name": "sensorProfile",
        "value": {
          "co2"     : {"min":   0, "max":  5000, "unit": "ppm"  },
          "fan_hour": {"min":   0, "max": 65535, "unit": "hour" },
          "hcho"    : {"min":   0, "max":  2000, "unit": "μg/m³"},
          "pm2_5"   : {"min":   0, "max":  1000, "unit": "μg/m³"},
          "rh"      : {"min":   0, "max":   100, "unit": "%"    },
          "temp"    : {"min": -10, "max":    50, "unit": "ºC"   }
        }
      }
    ]
  }
}

To get the custom controls for a specific device (AE2G00-ESXXXXX) in English (en) and Traditional Chinese (zh):

{
  "snList":["AE2G00-ESXXXXX"],
  "langs":["en","zh"]
}

Example Response Breakdown

The response contains several key parts relevant to CustomToggles and CustomModes:

 { "valid": true,
   "error": null, 
   // ... --- 1. Control Definitions & Localization --- 
   "controls": { "AE2G00-ESXXXXX": { // ProductSN 
     "AC_UNIT": {       // IotName 
       "Modes": {         // CustomModes definitions 
         "AirConditionerSlider": { // Mode Name 
           "en": {                 // Language Code 
             "NameSynonym": ["AirConditionTemperature"], // Localized Name(s) 
             "SettingSynonym": {   // Localized Option Names 
               "16": ["16"], "17": ["17"], /* ... other temps ... */ "32": ["32"] } }, 
           "zh": { /* ... Chinese localization ... */ } }, 
         "FanSpeed": { /* ... FanSpeed mode definition ... */ }, 
         "Filter": { /* ... Filter mode definition ... */ }, 
         "HeaterSlider": { /* ... HeaterSlider mode definition ... */ } }, 
       "Toggles": {       // CustomToggles definitions 
         "AutoMode": {      // Toggle Name 
           "en": { "NameSynonym": ["Auto"] }, // Localized Name(s) 
           "zh": { "NameSynonym": ["自動"] } }, 
         "AirConditioner": { /* ... AirConditioner toggle definition ... */ }, 
         "Heater": { /* ... Heater toggle definition ... / }, / ... other toggles ... */ } } } }, 
   // --- 2. UI Hints --- 
   "controlSettings": { 
     "AE2G00-ESXXXXX": { // ProductSN 
       "AC_UNIT": {       // IotName 
         "Modes": {         // CustomModes UI Hints 
           "HeaterSlider"        : {"WidgetType": "Slider"     , "WidgetAssetUrl": ""}, 
           "AirConditionerSlider": {"WidgetType": "Slider"     , "WidgetAssetUrl": ""}, 
           "FanSpeed"            : {"WidgetType": "Slider"     , "WidgetAssetUrl": ""}, 
           "Filter"              : {"WidgetType": "FilterReset", "WidgetAssetUrl": ""} }, 
         "Toggles": {       // CustomToggles UI Hints 
           "Heater"          : {"WidgetType": "SliderToggle", "WidgetAssetUrl": ""}, 
           "Dehumidification": {"WidgetType": "SliderToggle", "WidgetAssetUrl": ""}, 
           /* ... other toggles with WidgetType ... */ }
       }
     }
   }
 }

States & Commands are compatible with`Modes` and `Toggles` of trait

CustomModes => SetModes

CustomToggle => SetToggles

`/usr/v5/SendCommand` Example

{
  "sn": "AE2G00-ESXXXXX",
  "iotDevs": ["AC_UNIT"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": { "updateToggleSettings": {"Heater": true} }
    },
    {
      "command": "SetModes",
      "params": { "updateModeSettings": {"AirConditionerSlider": "16"} }
    }
  ]
}

API Endpoint

Examples

Example Response Breakdown

States & Commands are compatible withModes and Toggles of trait

/usr/v5/SendCommand Example

States & Commands are compatible with`Modes` and `Toggles` of trait

`/usr/v5/SendCommand` Example