Retrieving Device Models and Capabilities

Before sending commands to devices, you should retrieve their models, traits, and attributes using the GetGroupDevices API to understand what commands and parameters are supported.

API Endpoint

POST /usr/v5/GetGroupDevices

Request Structure

{
  "groupId": "YOUR_LOCATION_ID"
}

Example Request

curl -X POST "https://api.ultroncloud.com/usr/v5/GetGroupDevices" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "YOUR_LOCATION_ID"
  }'

Response Structure

The response includes device models with traits, attributes, and IoT endpoints. The models field is a map where keys are IoT endpoint names:

{
  "result": 0,
  "devices": {
    "SMART_LIGHT_001": {
      "sn": "SMART_LIGHT_001",
      "displayName": "Living Room Light",
      "activated": true,
      "models": {
        "light_main": {
          "type": "LIGHT",
          "traits": ["OnOff", "Brightness", "ColorSetting"],
          "nickname": "Main Light",
          "disabled": false,
          "attrs": [
            {
              "name": "commandOnlyOnOff",
              "value": false
            },
            {
              "name": "availableDimmingTypes",
              "value": ["PWM"]
            },
            {
              "name": "colorModel",
              "value": "rgb"
            }
          ]
        }
      },
      "createdTime": "2023-01-01T00:00:00Z"
    },
    "MULTI_ENDPOINT_DEVICE": {
      "sn": "MULTI_ENDPOINT_DEVICE",
      "displayName": "Multi-Function Device",
      "activated": true,
      "models": {
        "light_ch1": {
          "type": "LIGHT",
          "traits": ["OnOff", "Brightness"],
          "nickname": "Channel 1",
          "disabled": false,
          "attrs": [...]
        },
        "temp_sensor": {
          "type": "SENSOR",
          "traits": ["SensorState"],
          "nickname": "Temperature Sensor",
          "disabled": false,
          "attrs": [...]
        }
      },
      "createdTime": "2023-01-01T00:00:00Z"
    }
  }
}

Request Body Structure

{
  "sn": "TARGET_DEVICE_SERIAL_NUMBER",
  "iotDevs": [
    "TARGET_ENDPOINT_OF_DEVICE"
  ],
  "iotCmds": [
    {
      "command": "COMMAND_NAME",
      "params": {
        // Command-specific parameters
      }
    }
  ]
}

Parameters Explained

sn: The serial number of the target device
iotDevs: Array of device endpoints to send commands to (usually contains one endpoint)
iotCmds: Array of command objects, each containing:
- command: The command name
- params: Command-specific parameters object

Basic API Call

curl -X POST "https://api.ultroncloud.com/usr/v5/SendCommand" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sn": "DEVICE_SERIAL_NUMBER",
    "iotDevs": ["endpoint1"],
    "iotCmds": [
      {
        "command": "OnOff",
        "params": {
          "on": true
        }
      }
    ]
  }'

Device Control Examples by Type

1. Smart Light (Basic On/Off)

Turn Light On:

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

Turn Light Off:

{
  "sn": "SL001234567890",
  "iotDevs": ["light_main"],
  "iotCmds": [
    {
      "command": "OnOff",
      "params": {
        "on": false
      }
    }
  ]
}

2. Dimmable Light

Set Brightness to 75%:

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

Turn On with Fade Effect:

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

Adjust Brightness Relatively (+20%):

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

3. Color Light (RGB/HSV)

Set RGB Color (Red):

{
  "sn": "CL001234567890",
  "iotDevs": ["color_light"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumRGB": 16711680
        }
      }
    }
  ]
}

Set Color Temperature (Warm White):

{
  "sn": "CL001234567890",
  "iotDevs": ["color_light"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "temperature": 3000
        }
      }
    }
  ]
}

Set HSV Color (Blue):

{
  "sn": "CL001234567890",
  "iotDevs": ["color_light"],
  "iotCmds": [
    {
      "command": "ColorAbsolute",
      "params": {
        "color": {
          "spectrumHSV": {
            "hue": 240,
            "saturation": 1.0,
            "value": 1.0
          }
        }
      }
    }
  ]
}

4. Smart Thermostat

Set Target Temperature:

{
  "sn": "TH001234567890",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "ThermostatTemperatureSetpoint",
      "params": {
        "thermostatTemperatureSetpoint": 22.5
      }
    }
  ]
}

Set Thermostat Mode:

{
  "sn": "TH001234567890",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "ThermostatSetMode",
      "params": {
        "thermostatMode": "heat"
      }
    }
  ]
}

Set Temperature Range (Heat/Cool):

{
  "sn": "TH001234567890",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "ThermostatTemperatureSetRange",
      "params": {
        "thermostatTemperatureSetpointHigh": 24.0,
        "thermostatTemperatureSetpointLow": 20.0
      }
    }
  ]
}

Adjust Temperature Relatively (+2°C):

{
  "sn": "TH001234567890",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "TemperatureRelative",
      "params": {
        "thermostatTemperatureRelativeDegree": 2.0
      }
    }
  ]
}

5. Smart Fan

Set Fan Speed (Named Speed):

{
  "sn": "FN001234567890",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeed": "medium"
      }
    }
  ]
}

Set Fan Speed (Percentage):

{
  "sn": "FN001234567890",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeedPercent": 75
      }
    }
  ]
}

Reverse Fan Direction:

{
  "sn": "FN001234567890",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "Reverse",
      "params": {}
    }
  ]
}

6. Smart Lock

Lock Door:

{
  "sn": "LK001234567890",
  "iotDevs": ["lock_mechanism"],
  "iotCmds": [
    {
      "command": "LockUnlock",
      "params": {
        "lock": true
      }
    }
  ]
}

Unlock Door:

{
  "sn": "LK001234567890",
  "iotDevs": ["lock_mechanism"],
  "iotCmds": [
    {
      "command": "LockUnlock",
      "params": {
        "lock": false
      }
    }
  ]
}

7. Smart Curtains/Blinds

Open to 50%:

{
  "sn": "CT001234567890",
  "iotDevs": ["curtain_motor"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 50
      }
    }
  ]
}

Fully Close:

{
  "sn": "CT001234567890",
  "iotDevs": ["curtain_motor"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 0
      }
    }
  ]
}

Fully Open:

{
  "sn": "CT001234567890",
  "iotDevs": ["curtain_motor"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 100
      }
    }
  ]
}

8. Multi-Function Device (Toggles & Modes)

Set Multiple Toggles:

{
  "sn": "MF001234567890",
  "iotDevs": ["main_controller"],
  "iotCmds": [
    {
      "command": "SetToggles",
      "params": {
        "updateToggleSettings": {
          "nightMode": true,
          "ecoMode": false,
          "childLock": true
        }
      }
    }
  ]
}

Set Device Modes:

{
  "sn": "MF001234567890",
  "iotDevs": ["main_controller"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "operationMode": "auto",
          "fanMode": "quiet"
        }
      }
    }
  ]
}

9. Temperature Sensor/Controller

Set Target Temperature:

{
  "sn": "TS001234567890",
  "iotDevs": ["temp_sensor"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 25.0
      }
    }
  ]
}

10. Scene Controller

Activate Scene:

{
  "sn": "SC001234567890",
  "iotDevs": ["scene_controller"],
  "iotCmds": [
    {
      "command": "ActivateScene",
      "params": {
        "scene": "movie_night"
      }
    }
  ]
}

11. Humidity Controller

Set Humidity Level:

{
  "sn": "HM001234567890",
  "iotDevs": ["humidity_controller"],
  "iotCmds": [
    {
      "command": "SetHumidity",
      "params": {
        "humidity": 60
      }
    }
  ]
}

Adjust Humidity Relatively (+10%):

{
  "sn": "HM001234567890",
  "iotDevs": ["humidity_controller"],
  "iotCmds": [
    {
      "command": "HumidityRelative",
      "params": {
        "humidityRelativePercent": 10
      }
    }
  ]
}

{
  "sn": "SS001234567890",
  "iotDevs": ["motor_unit"],
  "iotCmds": [
    {
      "command": "PauseUnpause",
      "params": {
        "pause": true
      }
    }
  ]
}

Getting Device Information

1. Find Device Serial Number and Endpoints

curl -X POST "https://api.ultroncloud.com/usr/v5/GetGroupDevices" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "YOUR_LOCATION_ID"
  }'

The response contains a map of devices where keys are device serial numbers:

devices[SERIAL_NUMBER].sn: Device serial number
devices[SERIAL_NUMBER].models[iotName]: Available endpoints are the key part of the model map
devices[SERIAL_NUMBER].models.traits: Supported device capabilities
devices[SERIAL_NUMBER].models.attributes: Device-specific attributes and limitations

2. Get Device Current State

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

3. Get Product Information

curl -X POST "https://api.ultroncloud.com/usr/v5/GetSKUInfo" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "skuList": ["UTU400", "UT3M0F", "UT3M10"]
  }'