The TemperatureSetting trait enables devices to control temperature setpoints and thermostat modes. This trait is primarily used for HVAC systems, smart thermostats, and climate control devices that can maintain specific temperature targets.

Supported Attributes

1. `availableThermostatModes` (Array)

Type: Array of strings
Description: Specifies the thermostat operating modes supported by the device
Possible Values: ["off", "heat", "cool", "auto", "fan-only", "purifier", "eco", "dry"]
Usage: Defines which operating modes can be set via commands

2. `thermostatTemperatureUnit` (String)

Type: String
Description: The temperature unit used by the device
Possible Values: "C" (Celsius) or "F" (Fahrenheit)
Default: "C"
Usage: Determines the unit for all temperature values

3. `bufferRangeCelsius` (Number)

Type: Float
Description: The minimum temperature difference between heating and cooling setpoints in auto mode
Unit: Degrees Celsius
Default: 2.0
Usage: Prevents rapid switching between heating and cooling

4. `commandOnlyTemperatureSetting` (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 their state

5. `queryOnlyTemperatureSetting` (Boolean)

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

6. `thermostatTemperatureRange` (Object)

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

Structure:

{
  "minThresholdCelsius": 10.0,
  "maxThresholdCelsius": 35.0
}

Usage: Validates temperature setpoint commands

Supported Commands

1. `ThermostatTemperatureSetpoint`

Sets a single temperature setpoint (for heat, cool, or single-point control).

Parameters

{
  thermostatTemperatureSetpoint: number  // Required: Target temperature
}

Parameter Validation

Temperature must be within thermostatTemperatureRange
Value is in the unit specified by thermostatTemperatureUnit

2. `ThermostatTemperatureSetRange`

Sets both heating and cooling setpoints for auto mode.

Parameters

{
  thermostatTemperatureSetpointHigh: number,  // Required: Cooling setpoint
  thermostatTemperatureSetpointLow: number    // Required: Heating setpoint
}

Parameter Validation

Both temperatures must be within thermostatTemperatureRange
The difference between high and low must be at least bufferRangeCelsius
thermostatTemperatureSetpointHigh must be greater than thermostatTemperatureSetpointLow

3. `ThermostatSetMode`

Sets the thermostat operating mode.

Parameters

{
  thermostatMode: string  // Required: Operating mode
}

Parameter Validation

Mode must be in availableThermostatModes array
Common modes: "off", "heat", "cool", "auto", "fan-only", "eco", "dry", "purifier"

4. `TemperatureRelative`

Adjusts the current temperature setpoint by a relative amount.

Parameters

{
  thermostatTemperatureRelativeDegree: number  // Required: Relative temperature change
}

Parameter Validation

Final temperature must be within thermostatTemperatureRange
Value is in the unit specified by thermostatTemperatureUnit
Can be positive (increase) or negative (decrease)

Usage Examples

Basic Temperature Control

Set Heating Temperature to 22°C

{
  "sn": "THERMOSTAT_SERIAL_NUMBER",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "ThermostatTemperatureSetpoint",
      "params": {
        "thermostatTemperatureSetpoint": 22.0
      }
    }
  ]
}

Set Cooling Temperature to 24°C

{
  "sn": "THERMOSTAT_SERIAL_NUMBER",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "ThermostatTemperatureSetpoint",
      "params": {
        "thermostatTemperatureSetpoint": 24.0
      }
    }
  ]
}

Thermostat Mode Control

Set to Heating Mode

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

Set to Cooling Mode

{
  "sn": "THERMOSTAT_SERIAL_NUMBER",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "ThermostatSetMode",
      "params": {
        "thermostatMode": "cool"
      }
    }
  ]
}

Set to Auto Mode

{
  "sn": "THERMOSTAT_SERIAL_NUMBER",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "ThermostatSetMode",
      "params": {
        "thermostatMode": "auto"
      }
    }
  ]
}

Turn Off Thermostat

{
  "sn": "THERMOSTAT_SERIAL_NUMBER",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "ThermostatSetMode",
      "params": {
        "thermostatMode": "off"
      }
    }
  ]
}

Auto Mode Temperature Range

Set Temperature Range for Auto Mode

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

Set Narrow Temperature Range

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

Relative Temperature Adjustments

Increase Temperature by 2°C

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

Decrease Temperature by 1.5°C

{
  "sn": "THERMOSTAT_SERIAL_NUMBER",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "TemperatureRelative",
      "params": {
        "thermostatTemperatureRelativeDegree": -1.5
      }
    }
  ]
}

Combined Operations

Set Mode and Temperature Together

{
  "sn": "THERMOSTAT_SERIAL_NUMBER",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "ThermostatSetMode",
      "params": {
        "thermostatMode": "heat"
      }
    },
    {
      "command": "ThermostatTemperatureSetpoint",
      "params": {
        "thermostatTemperatureSetpoint": 21.0
      }
    }
  ]
}

Switch to Auto Mode with Range

{
  "sn": "THERMOSTAT_SERIAL_NUMBER",
  "iotDevs": ["thermostat_main"],
  "iotCmds": [
    {
      "command": "ThermostatSetMode",
      "params": {
        "thermostatMode": "auto"
      }
    },
    {
      "command": "ThermostatTemperatureSetRange",
      "params": {
        "thermostatTemperatureSetpointLow": 20.0,
        "thermostatTemperatureSetpointHigh": 25.0
      }
    }
  ]
}

Device Types Using TemperatureSetting Trait

Smart Thermostats

Residential HVAC thermostats
Commercial building thermostats
Programmable thermostats
Learning thermostats

Climate Control Systems

Heat pumps
Air conditioning units
Radiant heating systems
Hydronic heating systems

Specialized HVAC

Fan coil units
Variable refrigerant flow (VRF) systems
Rooftop units
Chiller systems

Portable Climate Devices

Portable air conditioners
Space heaters
Dehumidifiers with temperature control
Evaporative coolers

Thermostat Modes Explained

`off`

Description: Thermostat is completely off
Usage: No heating or cooling operation
Fan: Usually off (unless fan-only mode is separate)

`heat`

Description: Heating only mode
Usage: Maintains temperature at or above setpoint
Setpoint: Single heating setpoint

`cool`

Description: Cooling only mode
Usage: Maintains temperature at or below setpoint
Setpoint: Single cooling setpoint

`auto`

Description: Automatic heating and cooling
Usage: Maintains temperature within a range
Setpoints: Both heating and cooling setpoints required

`fan-only`

Description: Fan operation without heating/cooling
Usage: Air circulation only
Temperature: No temperature control

`eco`

Description: Energy-saving mode
Usage: Optimized for energy efficiency
Setpoints: May use wider temperature ranges

`dry`

Description: Dehumidification mode
Usage: Removes humidity while maintaining temperature
Common: Air conditioning systems in humid climates

`purifier`

Description: Air purification mode
Usage: Focus on air quality rather than temperature
Features: May include filtration or ionization

Attribute Combinations

Basic Thermostat

{
  "traits": ["TemperatureSetting"],
  "attributes": [
    {
      "name": "availableThermostatModes",
      "value": ["off", "heat", "cool", "auto"]
    },
    {
      "name": "thermostatTemperatureUnit",
      "value": "C"
    },
    {
      "name": "thermostatTemperatureRange",
      "value": {
        "minThresholdCelsius": 10.0,
        "maxThresholdCelsius": 35.0
      }
    }
  ]
}

Advanced HVAC System

{
  "traits": ["TemperatureSetting"],
  "attributes": [
    {
      "name": "availableThermostatModes",
      "value": ["off", "heat", "cool", "auto", "fan-only", "eco", "dry"]
    },
    {
      "name": "bufferRangeCelsius",
      "value": 1.5
    },
    {
      "name": "thermostatTemperatureRange",
      "value": {
        "minThresholdCelsius": 5.0,
        "maxThresholdCelsius": 40.0
      }
    }
  ]
}

Fahrenheit Thermostat

{
  "traits": ["TemperatureSetting"],
  "attributes": [
    {
      "name": "thermostatTemperatureUnit",
      "value": "F"
    },
    {
      "name": "thermostatTemperatureRange",
      "value": {
        "minThresholdCelsius": 10.0,
        "maxThresholdCelsius": 35.0
      }
    }
  ]
}

Read-Only Temperature Sensor

{
  "traits": ["TemperatureSetting"],
  "attributes": [
    {
      "name": "queryOnlyTemperatureSetting",
      "value": true
    }
  ]
}

Best Practices

1. Understand Device Capabilities

Check availableThermostatModes before setting modes
Respect thermostatTemperatureRange limits
Consider bufferRangeCelsius for auto mode

2. Use Appropriate Temperature Units

Always use the unit specified by thermostatTemperatureUnit
Convert between Celsius and Fahrenheit when necessary
Be consistent with temperature precision

3. Optimize for Energy Efficiency

Use eco mode when available for energy savings
Set reasonable temperature ranges in auto mode
Avoid frequent temperature changes

4. Handle Mode Transitions

Allow time for mode changes to take effect
Consider system startup delays
Monitor actual temperature vs. setpoint

5. User Experience Considerations

Use relative adjustments for user-friendly controls
Provide clear feedback on temperature changes
Consider seasonal temperature preferences

Related Traits

The TemperatureSetting trait is often combined with:

FanSpeed: For fan control in HVAC systems
HumiditySetting: For complete climate control
Timer: For scheduled temperature changes
Modes: For additional HVAC operating modes
SensorState: For temperature and humidity monitoring

State Reporting

Devices with TemperatureSetting trait typically report:

thermostatMode: Current operating mode
thermostatTemperatureSetpoint: Current setpoint temperature
thermostatTemperatureSetpointHigh: Cooling setpoint (auto mode)
thermostatTemperatureSetpointLow: Heating setpoint (auto mode)
thermostatTemperatureAmbient: Current ambient temperature
thermostatHumidityAmbient: Current humidity (if available)

Query current thermostat 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]}'

Temperature Unit Conversion

When working with Fahrenheit devices:

Celsius to Fahrenheit

°F = (°C × 9/5) + 32

Fahrenheit to Celsius

°C = (°F - 32) × 5/9

Example Conversions

20°C = 68°F
22°C = 71.6°F
24°C = 75.2°F
26°C = 78.8°F