API Endpoint

POST /usr/v5/SetDeviceConfigs

Request Structure

{
  "sn": "DEVICE_SERIAL_NUMBER",
  "configs": [
    {
      "config": "CONFIG_NAME",
      "iotName": "OPTIONAL_IOT_ENDPOINT_NAME",
      "items": {
        // Configuration-specific structure
      }
    }
  ]
}

Parameters

sn: Device serial number (required)
configs: Array of configuration objects (required)
- config: Configuration type name (required)
- iotName: Optional IoT endpoint name for multi-endpoint devices
- items: Configuration-specific data structure (required), or null to reset/clear the configuration

Retrieving Current Device Configurations

Before setting or modifying device configurations, you can retrieve the current configuration state using the GetGroupDevices API.

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 information with current configurations in the configs field. The devices field is a map where keys are ProductSN (device serial numbers), and the models field is a map where keys are IoT endpoint names:

{
  "result": 0,
  "devices": {
    "DEVICE_SERIAL_NUMBER_1": {
      "sn": "DEVICE_SERIAL_NUMBER_1",
      "displayName": "Smart Light",
      "activated": true,
      "models": {
        "light_main": {
          "type": "LIGHT",
          "traits": ["OnOff", "Brightness"],
          "nickname": "Main Light",
          "disabled": false,
          "attrs": [
            {
              "name": "commandOnlyOnOff",
              "value": false
            },
            {
              "name": "availableDimmingTypes",
              "value": ["0-10V", "1-10V"]
            }
          ]
        }
      },
      "configs": [
        {
          "config": "BrightnessRange",
          "items": {
            "min": 10,
            "max": 100
          }
        },
        {
          "config": "Scheduler",
          "items": [
            {
              "taskId": 1001,
              "name": "Morning Light",
              "iot": "light_main",
              "firstShot": 1640995200,
              "interval": 86400,
              "cmd": {
                "command": "OnOff",
                "params": {
                  "on": true
                }
              }
            }
          ]
        }
      ],
      "createdTime": "2023-01-01T00:00:00Z"
    },
    "DEVICE_SERIAL_NUMBER_2": {
      "sn": "DEVICE_SERIAL_NUMBER_2",
      "displayName": "Temperature Sensor",
      "activated": true,
      "models": {
        "temp_sensor": {
          "type": "SENSOR",
          "traits": ["TemperatureControl", "SensorState"],
          "nickname": "Temperature Sensor",
          "disabled": false,
          "attrs": [
            {
              "name": "temperatureRange",
              "value": {
                "min": -40,
                "max": 85
              }
            }
          ]
        }
      },
      "configs": [
        {
          "config": "IotIntervals",
          "items": {
            "reportStates": 1800,
            "sensor": {
              "temp_sensor": {
                "temperature": {
                  "tolerance": 0.5,
                  "report": 300
                }
              }
            }
          }
        }
      ],
      "createdTime": "2023-01-01T00:00:00Z"
    }
  }
}

Configuration Management Workflow

1. Retrieve Current Configurations

# Get current device configurations
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"
  }'

2. Modify Specific Configuration

# Update brightness range based on current settings
curl -X POST "https://api.ultroncloud.com/usr/v5/SetDeviceConfigs" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sn": "SMART_LIGHT_001",
    "configs": [
      {
        "config": "BrightnessRange",
        "items": {
          "min": 5,
          "max": 95
        }
      }
    ]
  }'

3. Verify Configuration Changes

# Retrieve updated configurations to verify changes
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"
  }'

Configuration Reset/Clear

To reset or clear a specific configuration, set the items field to null. This will remove the configuration and restore the device to its default settings for that configuration type.

Reset Structure

{
  "config": "CONFIG_NAME",
  "iotName": "optional_endpoint",
  "items": null
}

Reset Examples

Reset Brightness Range to Default

{
  "sn": "DIMMABLE_LIGHT_SERIAL",
  "configs": [
    {
      "config": "BrightnessRange",
      "items": null
    }
  ]
}

Clear All Scheduled Tasks

{
  "sn": "SMART_DEVICE_SERIAL",
  "configs": [
    {
      "config": "Scheduler",
      "items": null
    }
  ]
}

Reset IoT Communication Intervals

{
  "sn": "SENSOR_DEVICE_SERIAL",
  "configs": [
    {
      "config": "IotIntervals",
      "items": null
    }
  ]
}

Multiple Configuration Reset

You can reset multiple configurations in a single request:

curl -X POST "https://api.ultroncloud.com/usr/v5/SetDeviceConfigs" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sn": "MULTI_CONFIG_DEVICE",
    "configs": [
      {
        "config": "BrightnessRange",
        "items": null
      },
      {
        "config": "Scheduler",
        "items": null
      },
      {
        "config": "Fade",
        "items": null
      }
    ]
  }'

Reset Specific Endpoint Configuration

For multi-endpoint devices, you can reset the configuration for a specific endpoint:

{
  "sn": "MULTI_ENDPOINT_DEVICE",
  "configs": [
    {
      "config": "IotIntervals",
      "iotName": "sensor_endpoint_1",
      "items": null
    }
  ]
}

Reset Behavior

When a configuration is reset (items: null):

Device Default Restoration: The device returns to its factory default settings for that configuration type
Memory Cleanup: Any stored configuration data is cleared from device memory
Immediate Effect: The reset takes effect immediately (no restart required)
Validation Bypass: No validation is performed since the configuration is being removed
Dependency Handling: Dependent configurations may also be affected

Reset Use Cases

Troubleshooting

Clear problematic configurations that cause device issues
Reset to known good state during debugging
Remove conflicting configuration settings

Maintenance

Clear temporary configurations after testing
Reset devices before reassignment or relocation
Prepare devices for firmware updates

Security

Reset access control configurations

Configuration Types

1. Scheduler - Timer Task Configuration

Configure scheduled tasks and automation for devices.

Structure

{
  "config": "Scheduler",
  "items": [
    {
      "taskId": 1001,
      "name": "Morning Light On",
      "iot": "light_main",
      "firstShot": 1640995200,
      "interval": 86400,
      "validBefore": 1672531200,
      "disabled": false,
      "cmd": {
        "command": "OnOff",
        "params": {
          "on": true
        }
      }
    }
  ]
}

Example

{
  "sn": "SMART_LIGHT_SERIAL",
  "configs": [
    {
      "config": "Scheduler",
      "items": [
        {
          "taskId": 1001,
          "name": "Evening Dim",
          "iot": "light_main",
          "firstShot": 1640995200,
          "interval": 86400,
          "cmd": {
            "command": "BrightnessAbsolute",
            "params": {
              "brightness": 30
            }
          }
        }
      ]
    }
  ]
}

2. BrightnessRange - Brightness Range Configuration

Configure custom brightness ranges for dimmable lights.

Structure

{
  "config": "BrightnessRange",
  "items": {
    "min": 10,
    "max": 100
  }
}

Example

{
  "sn": "DIMMABLE_LIGHT_SERIAL",
  "configs": [
    {
      "config": "BrightnessRange",
      "items": {
        "min": 5,
        "max": 95
      }
    }
  ]
}

3. IotIntervals - Device Communication Intervals

Configure communication intervals, retry policies, and sensor reporting settings.

Structure

{
  "config": "IotIntervals",
  "items": {
    "reportStates": 3600,
    "bleTopology": 600,
    "retry": {
      "activate": {
        "value": 60,
        "max": 300,
        "backoff": "exponential"
      },
      "mqttConnect": {
        "value": 30,
        "max": 120
      },
      "asyncApi": {
        "value": 10,
        "max": 60
      }
    },
    "mqttConfig": {
      "keepAlive": 290,
      "connTimeout": 30,
      "connectAuthFail": 40
    },
    "sensor": {
      "iot_endpoint_name": {
        "temperature": {
          "tolerance": 0.5,
          "report": 300,
          "sampling": 60
        },
        "humidity": {
          "tolerance": 2.0,
          "report": 300,
          "sampling": 60
        }
      }
    }
  }
}

Example

{
  "sn": "SENSOR_DEVICE_SERIAL",
  "configs": [
    {
      "config": "IotIntervals",
      "items": {
        "reportStates": 1800,
        "bleTopology": 300,
        "retry": {
          "activate": {
            "value": 30,
            "max": 180
          },
          "mqttConnect": {
            "value": 15,
            "max": 60
          }
        },
        "mqttConfig": {
          "keepAlive": 240,
          "connTimeout": 20
        },
        "sensor": {
          "temp_sensor": {
            "temperature": {
              "tolerance": 0.3,
              "report": 600,
              "sampling": 120
            }
          }
        }
      }
    }
  ]
}

Complete API Examples

Configure Smart Light with Multiple Settings

curl -X POST "https://api.ultroncloud.com/usr/v5/SetDeviceConfigs" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sn": "SMART_LIGHT_001",
    "configs": [
      {
        "config": "BrightnessRange",
        "items": {
          "min": 1,
          "max": 100
        }
      },
      {
        "config": "Fade",
        "items": {
          "durationRange": {
            "min": 0.5,
            "max": 10
          },
          "defaultDuration": 2
        }
      },
      {
        "config": "Scheduler",
        "items": [
          {
            "taskId": 1001,
            "name": "Morning On",
            "iot": "light_main",
            "firstShot": 1640995200,
            "interval": 86400,
            "cmd": {
              "command": "OnOff",
              "params": {
                "on": true
              }
            }
          }
        ]
      }
    ]
  }'

Configure Sensor Intervals

curl -X POST "https://api.ultroncloud.com/usr/v5/SetDeviceConfigs" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sn": "TEMP_SENSOR_001",
    "configs": [
      {
        "config": "IotIntervals",
        "items": {
          "reportStates": 1800,
          "retry": {
            "activate": {
              "value": 30,
              "max": 120
            }
          },
          "sensor": {
            "temp_main": {
              "temperature": {
                "tolerance": 0.2,
                "report": 300,
                "sampling": 60
              }
            }
          }
        }
      }
    ]
  }'

Configuration Dependencies

Some configurations depend on device attributes or other configurations:

Attribute Dependencies

BrightnessRange: Requires brightnessRangeConfigurable attribute
Scheduler: Requires schedulable attribute
IotIntervals: Requires iotConfigurableIntervals attribute

Configuration Interactions

Scheduler tasks reference IoT endpoints
IotIntervals impact all device communications
Fade settings affect lighting transitions

Name	Required Attribute	Example
ArbitraryRadioGroups	arbitraryRadioGroupDevices	`{ "name": "arbitraryRadioGroupDevices", "value": ["1", "2", "3", "4"] }`
BrightnessRange	brightnessRangeConfigurable	`{ "name": "brightnessRangeConfigurable", "value": true }`
CircuitDetector	detectDirection	`{ "name": "detectDirection", "value": ["OpenToClose", "CloseToOpen"] }`
ColorPreset	colorProfile	`{ "name": "colorProfile", "value": { "enabled": true, "brightnessStart": 0, "brightnessEnd": 50, "temperature": 4600, "spectrumRGB": null, "spectrumHSV": null } }`
DefaultActions	supportDefaultActions	`{ "name": "supportDefaultActions", "value": { "1": { "cmdNames": [ "OnOff" ], "situations": [ "power", "network" ] }, "2": { "cmdNames": [ "OnOff" ], "situations": [ "power", "network" ] } } }`
Dimmer	availableDimmingTypes	`{ "name": "availableDimmingTypes", "value": ["0-10V", "1-10V"] }`
DisableGateway	supportGatewayOff	`{ "name": "supportGatewayOff", "value": true }`
Fade	fade	`{ "name": "fade", "value": { "enabled": true, "duration": 2, "durationRange": { "min": 1, "max": 10 } } }`
FadePreset	fade	`{ "name": "fade", "value": { "enabled": true, "duration": 2, "durationRange": { "min": 1, "max": 10 } } }`
IotIntervals	iotConfigurableIntervals	`{ "name": "iotConfigurableIntervals", "value": true }`
MotorRotation	motorReversible	`{ "name": "motorReversible", "value": true }`
Periodicity	schedulable, periodicity, aperiodicity(if support oneShot)	`[ { "name": "schedulable", "value": true }, { "name": "periodicity", "value": true }, { "name": "aperiodicity", "value": true } ]`
Scheduler	schedulable	`{ "name": "schedulable", "value": { "1": ["OnOff"], "2": ["OnOff"], "3": ["OnOff"], "4": ["OnOff"] } }`
TimeStep	timeStepRange	`{ "name": "timeStepRange", "value": { "max": 84600, "min": 1, "step": 1 } }`