Skip to main content

​
Overview

The thermostat’s state isn’t a single “mode.” It’s the combination of four independent dimensions, each controlled through different bucket fields.
DimensionControlsBucketKey fieldServer-writable?
HVAC modeHeating, cooling, or bothsharedtarget_temperature_typeYes
Temperature setpointTarget temperaturesharedtarget_temperature (and variants)Yes
Eco modeEnergy-saving statestructuremanual_eco_allYes
HVAC operationWhat hardware is runningsharedhvac_*_state fieldsNo (read-only)
These dimensions are independent — changing one doesn’t reset the others.

​
HVAC Modes

Set the HVAC mode by pushing target_temperature_type in the shared bucket:
ValueBehaviorTemperature fieldsWiring required
"heat"Heating onlytarget_temperaturecan_heat: true
"cool"Cooling onlytarget_temperaturecan_cool: true
"range"Auto heat+cooltarget_temperature_low, target_temperature_highcan_heat and can_cool
"off"All HVAC disabledNone—
"emergency"Emergency/auxiliary heattarget_temperaturehas_emer_heat: true (device bucket)
Values are case-insensitive. The device sends lowercase in PUT requests. Always validate against device capabilities before pushing a mode. If you push an unsupported mode, the device silently falls back to a mode its wiring supports. 
can_heat → check shared bucket
can_cool → check shared bucket
has_emer_heat → check device bucket

​
Temperature Fields

All temperatures are Celsius floats. The device converts for display based on temperature_scale in the device bucket.
Active modeSet these fields
heattarget_temperature
cooltarget_temperature
emergencytarget_temperature
rangetarget_temperature_low AND target_temperature_high
offNone
Valid range: 4.5°C – 32°C (40°F – 90°F). Minimum meaningful increment: ~0.01°C. In range mode, the device heats when the current temperature drops below target_temperature_low and cools when it rises above target_temperature_high.

​
Equipment Capabilities

Check these before offering controls in a UI:
FieldBucketDescription
can_heatsharedHeating wiring detected
can_coolsharedCooling wiring detected
has_emer_heatdeviceEmergency/auxiliary heat wiring
has_fandeviceFan control wiring
has_humidifierdeviceHumidifier wiring
has_dehumidifierdeviceDehumidifier wiring
has_hot_water_controldeviceHot water system (UK/EU)
These are reported by the device via PUT and are read-only on the server side.

​
HVAC Operation State

The device reports what equipment is currently running through boolean fields in the shared bucket:
Currently…Check these fields
Heatinghvac_heater_state, hvac_heat_x2_state, hvac_heat_x3_state
Coolinghvac_ac_state, hvac_cool_x2_state, hvac_cool_x3_state
Emergency heatinghvac_emer_heat_state
Auxiliary heathvac_aux_heater_state, hvac_alt_heat_state
Fan runninghvac_fan_state
Multiple fields can be true simultaneously (e.g., stage 1 and stage 2 heating).

​
Read-Only Sensor Fields

FieldBucketTypeDescription
current_temperaturesharedfloatIndoor temperature (°C)
current_humiditydeviceintegerIndoor relative humidity (%)
backplate_temperaturedevicefloatBackplate sensor temperature (°C)
battery_leveldevicefloatBattery charge level
time_to_targetdeviceintegerEstimated seconds until target temperature
time_to_target_trainingdevicestring"ready", "training", or "not_ready"
auto_awaysharedintegerOccupancy: 0 = home, 1 = away

​
Eco Mode State

The device reports its eco state via the eco_mode field in the device bucket (a JSON string): 
{"mode":"manual-eco","touched_by":3,"mode_update_timestamp":1738800000,"touched_user_id":"userId"}
mode valueMeaning
"schedule"Not in eco mode — following schedule normally
"manual-eco"Server-initiated eco (via manual_eco_all in structure bucket)
"auto-eco"Device-initiated eco (occupancy sensor or away timer)

​
Emergency Heat

Emergency heat bypasses the heat pump compressor and runs auxiliary heat directly. It’s expensive and intended for equipment failure or extreme cold. When emergency heat activates, the device automatically:
  • Saves and disables learning mode
  • Saves and disables auto-away
  • Blocks preconditioning entirely
  • Restores all saved settings when emergency heat is turned off
Do not leave a device in emergency heat long-term.

​
State Interaction Matrix

Server actionHVAC modeTemperature sourceEcoHVAC runs?
Set mode to "heat"→ HeatSchedule or manualUnchangedIf below setpoint
Set mode to "off"→ Off—UnchangedNo
Set manual_eco_all: trueUnchanged→ Eco temperatures→ Manual-ecoOnly outside eco band
Set manual_eco_all: falseUnchanged→ Schedule setpoint→ ScheduleRecalculated
Push new scheduleUnchangedUpdated at transitionsUnchangedRecalculated
Safety threshold crossedOverriddenOverriddenOverriddenForced on
Set emergency mode→ EmergencyManual setpointUnchangedEmergency heat