TemperatureControl

The TemperatureControl trait enables devices to control temperature setpoints for sensors, controllers, and monitoring systems. Unlike TemperatureSetting (which is for thermostats), this trait is used for temperature sensors, controllers, and devices that need to maintain or monitor specific temperature targets.

Supported Attributes

1. `temperatureRange` (Object)

Type: Object with temperature range limits
Description: Defines the valid temperature range for setpoints in Celsius

Structure:

{
  "minThresholdCelsius": -10.0,
  "maxThresholdCelsius": 50.0
}

Usage: Validates temperature setpoint commands

2. `temperatureStepCelsius` (Number)

Type: Float
Description: The minimum step size for temperature adjustments in Celsius
Default: 0.1
Usage: Defines the precision of temperature control

3. `temperatureUnitForUX` (String)

Type: String
Description: The temperature unit to display in user interfaces
Possible Values: "C" (Celsius) or "F" (Fahrenheit)
Default: "C"
Usage: Determines display unit while internal values remain in Celsius

4. `queryOnlyTemperatureControl` (Boolean)

Type: Boolean
Description: When true, the device can only be queried for temperature but cannot accept temperature commands
Default: false
Usage: Set to true for temperature sensors or read-only devices

5. `commandOnlyTemperatureControl` (Boolean)

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

Supported Commands

1. `SetTemperature`

Sets the target temperature for the device or sensor.

Parameters

{
  temperature: number  // Required: Target temperature in Celsius
}

Parameter Validation

temperature: Must be within temperatureRange (minThresholdCelsius to maxThresholdCelsius)
Value is always in Celsius regardless of temperatureUnitForUX
Must align with temperatureStepCelsius if specified

Usage Examples

Temperature Sensor Control

Set Temperature Threshold to 25°C

{
  "sn": "TEMP_SENSOR_SERIAL",
  "iotDevs": ["temp_controller"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 25.0
      }
    }
  ]
}

Set Low Temperature Alert (5°C)

{
  "sn": "FREEZE_SENSOR_SERIAL",
  "iotDevs": ["freeze_monitor"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 5.0
      }
    }
  ]
}

Set High Temperature Alert (35°C)

{
  "sn": "OVERHEAT_SENSOR_SERIAL",
  "iotDevs": ["overheat_monitor"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 35.0
      }
    }
  ]
}

Industrial Temperature Control

Set Process Temperature (80°C)

{
  "sn": "PROCESS_CONTROLLER",
  "iotDevs": ["process_temp"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 80.0
      }
    }
  ]
}

Set Storage Temperature (2°C)

{
  "sn": "COLD_STORAGE_CONTROLLER",
  "iotDevs": ["storage_temp"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 2.0
      }
    }
  ]
}

Greenhouse Temperature Control

Set Optimal Growing Temperature (22°C)

{
  "sn": "GREENHOUSE_CONTROLLER",
  "iotDevs": ["greenhouse_temp"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 22.0
      }
    }
  ]
}

Set Night Temperature (18°C)

{
  "sn": "GREENHOUSE_CONTROLLER",
  "iotDevs": ["greenhouse_temp"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 18.0
      }
    }
  ]
}

Water Temperature Control

Set Pool Temperature (26°C)

{
  "sn": "POOL_HEATER_CONTROLLER",
  "iotDevs": ["pool_temp"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 26.0
      }
    }
  ]
}

Set Hot Water Temperature (55°C)

{
  "sn": "WATER_HEATER_CONTROLLER",
  "iotDevs": ["water_temp"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 55.0
      }
    }
  ]
}

Precision Temperature Control

Set Laboratory Temperature (23.5°C)

{
  "sn": "LAB_TEMP_CONTROLLER",
  "iotDevs": ["lab_chamber"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 23.5
      }
    }
  ]
}

Set Incubator Temperature (37.0°C)

{
  "sn": "INCUBATOR_CONTROLLER",
  "iotDevs": ["incubator_temp"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 37.0
      }
    }
  ]
}

Multi-Zone Temperature Control

Set Different Temperatures for Multiple Zones

{
  "sn": "MULTI_ZONE_CONTROLLER",
  "iotDevs": ["zone1", "zone2", "zone3"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 20.0
      }
    }
  ]
}

Alarm and Safety Systems

Set Fire Detection Temperature (60°C)

{
  "sn": "FIRE_DETECTION_SYSTEM",
  "iotDevs": ["fire_sensor"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": 60.0
      }
    }
  ]
}

Set Freezer Alarm Temperature (-15°C)

{
  "sn": "FREEZER_MONITOR",
  "iotDevs": ["freezer_alarm"],
  "iotCmds": [
    {
      "command": "SetTemperature",
      "params": {
        "temperature": -15.0
      }
    }
  ]
}

Device Types Using TemperatureControl Trait

Temperature Sensors

Environmental sensors
Industrial temperature sensors
Wireless temperature monitors
Data loggers

Process Controllers

Industrial process controllers
Laboratory equipment
Manufacturing systems
Quality control systems

Environmental Control

Greenhouse controllers
Aquarium heaters
Terrarium controllers
Plant growth chambers

Safety Systems

Fire detection systems
Freeze alarms
Overheat protection
Temperature monitoring systems

Food and Beverage

Refrigeration controllers
Wine cellar controllers
Brewing equipment
Food safety monitors

HVAC Components

Zone controllers
Duct temperature sensors
Boiler controllers
Heat exchanger monitors

Temperature Range Examples

Common Applications

{
  "residential": {
    "minThresholdCelsius": 10.0,
    "maxThresholdCelsius": 35.0
  },
  "industrial": {
    "minThresholdCelsius": -40.0,
    "maxThresholdCelsius": 200.0
  },
  "laboratory": {
    "minThresholdCelsius": -20.0,
    "maxThresholdCelsius": 100.0
  },
  "greenhouse": {
    "minThresholdCelsius": 5.0,
    "maxThresholdCelsius": 45.0
  },
  "food_safety": {
    "minThresholdCelsius": -30.0,
    "maxThresholdCelsius": 80.0
  }
}

Device Configuration Examples

Basic Temperature Sensor

{
  "traits": ["TemperatureControl", "SensorState"],
  "attributes": [
    {
      "name": "temperatureRange",
      "value": {
        "minThresholdCelsius": -10.0,
        "maxThresholdCelsius": 50.0
      }
    },
    {
      "name": "temperatureStepCelsius",
      "value": 0.1
    }
  ]
}

Industrial Temperature Controller

{
  "traits": ["TemperatureControl", "OnOff"],
  "attributes": [
    {
      "name": "temperatureRange",
      "value": {
        "minThresholdCelsius": -40.0,
        "maxThresholdCelsius": 200.0
      }
    },
    {
      "name": "temperatureStepCelsius",
      "value": 0.5
    }
  ]
}

Fahrenheit Display Controller

{
  "traits": ["TemperatureControl"],
  "attributes": [
    {
      "name": "temperatureUnitForUX",
      "value": "F"
    },
    {
      "name": "temperatureRange",
      "value": {
        "minThresholdCelsius": 0.0,
        "maxThresholdCelsius": 40.0
      }
    }
  ]
}

Query-Only Temperature Sensor

{
  "traits": ["TemperatureControl", "SensorState"],
  "attributes": [
    {
      "name": "queryOnlyTemperatureControl",
      "value": true
    }
  ]
}

Precision Laboratory Controller

{
  "traits": ["TemperatureControl", "StatusReport"],
  "attributes": [
    {
      "name": "temperatureRange",
      "value": {
        "minThresholdCelsius": -20.0,
        "maxThresholdCelsius": 100.0
      }
    },
    {
      "name": "temperatureStepCelsius",
      "value": 0.01
    }
  ]
}

Best Practices

1. Temperature Range Selection

Choose appropriate ranges for your application
Consider environmental conditions and safety margins
Account for sensor accuracy and drift
Plan for extreme conditions

2. Precision and Accuracy

Select appropriate step sizes for your needs
Consider sensor resolution and accuracy
Implement proper calibration procedures
Monitor for sensor drift over time

3. Safety Considerations

Implement appropriate safety limits
Use redundant sensors for critical applications
Plan for sensor failures and backup systems
Consider fail-safe operating modes

4. Environmental Factors

Account for ambient temperature effects
Consider thermal mass and response times
Plan for seasonal variations
Monitor for external heat sources

5. Maintenance and Calibration

Implement regular calibration schedules
Monitor sensor performance over time
Replace sensors according to manufacturer recommendations
Document calibration and maintenance activities

Related Traits

The TemperatureControl trait is commonly combined with:

SensorState: For temperature monitoring and reporting
OnOff: For basic device power control
StatusReport: For system health monitoring
Timer: For scheduled temperature changes
Modes: For different control modes
HumiditySetting: For complete environmental control

State Reporting

Devices with TemperatureControl trait typically report:

temperatureSetpointCelsius: Current temperature setpoint
temperatureAmbientCelsius: Current measured temperature
online: Device connectivity status

Query current temperature 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", "snList": ["SN1", "SN2"]}'