Skip to main content

​
Overview

The shared bucket is the primary bucket for thermostat control. It holds the active temperature setpoint, HVAC mode, and current conditions. This is the bucket you read and write most often. Object key: shared.{serial}
Direction: Bidirectional
Revision type: if_object_revision (conditional write — unique among all buckets)

​
Conditional Writes

The shared bucket is the only bucket that uses conditional writes. When the device sends a PUT with if_object_revision, it expects the server to validate that this revision matches the current stored revision before accepting the write. This prevents the device from overwriting a temperature change the server pushed while the device was preparing its own PUT. All other buckets use base_object_revision (unconditional). When a conditional write fails, return 200 OK with the current {object_revision, object_timestamp, object_key} so the device can reconcile. Never include a value field in the response.

​
Fields

FieldTypeServerDescription
target_temperaturefloatRead/writeTarget temperature in °C (single-setpoint modes)
target_temperature_highfloatRead/writeUpper bound in range mode (°C)
target_temperature_lowfloatRead/writeLower bound in range mode (°C)
target_temperature_typestringRead/writeHVAC mode: heat, cool, range, emergency, or off
target_change_pendingbooleanRead/writeDisplay wake flag — see below
schedule_modestringRead/writeActive schedule mode: HEAT, COOL, or RANGE
touched_byobjectRead/writeLast temperature change source — see below
namestringRead/writeDevice display name
current_temperaturefloatRead-onlyCurrent indoor temperature (°C)
auto_awayintegerRead-onlyOccupancy: 0 = home, 1 = away
can_heatbooleanRead-onlyHeating capability
can_coolbooleanRead-onlyCooling capability
hvac_heater_statebooleanRead-onlyPrimary heater running
hvac_heat_x2_statebooleanRead-onlyStage 2 heat running
hvac_heat_x3_statebooleanRead-onlyStage 3 heat running
hvac_aux_heater_statebooleanRead-onlyAuxiliary heater running
hvac_alt_heat_statebooleanRead-onlyAlternate heat source running
hvac_emer_heat_statebooleanRead-onlyEmergency heat running
hvac_ac_statebooleanRead-onlyAir conditioning running
hvac_cool_x2_statebooleanRead-onlyStage 2 cooling running
hvac_cool_x3_statebooleanRead-onlyStage 3 cooling running
hvac_fan_statebooleanRead-onlyFan running

​
target_change_pending — Display Wake

When you push a temperature change to a sleeping device, the device wakes and applies the new setpoint — but the physical display stays off unless you also set target_change_pending: true. Set target_change_pending: true when changing:
  • target_temperature
  • target_temperature_high
  • target_temperature_low
Don’t set it when changing:
  • target_temperature_type (mode changes have separate display handling)
  • schedule_mode
  • Any field in the device or structure buckets
Acknowledgment flow:
  1. Server pushes target_temperature + target_change_pending: true
  2. Device wakes, applies temperature, lights the display
  3. Device sends PUT with target_change_pending: false
  4. Server accepts false and does not push true again
If you keep pushing target_change_pending: true after the device cleared it, the display keeps cycling — never accept the device’s false and you get an update loop.

​
touched_by — Change Source Tracking

The touched_by object tells the device what caused the last temperature change. The device uses it to show “Holding until…” after a manual dial turn. 
{
  "touched_by": {
    "touched_by": 3,
    "touched_at": 1707148800,
    "touched_tzo": -18000,
    "touched_user_id": ""
  }
}
touched_by valueWhen to use
1Server applying a schedule transition
2Device user turned the dial
3External app or API pushed the temperature
Set touched_at to the current Unix timestamp in seconds (not ms). Set touched_tzo to the device’s UTC offset in seconds.
The device does not include touched_by in its own temperature PUTs. Your server is responsible for setting this field when pushing temperature changes.

​
target_temperature vs Schedule Setpoints

target_temperature in the shared bucket can be overwritten by:
  • Schedule transitions (device evaluates schedule locally on its own timer)
  • Manual dial turns
  • Cloud pushes from your server
Critical: If your server pushes a stale target_temperature value that differs from what the device currently has, the device treats it as a new manual override — canceling the current schedule-derived setpoint. Best practice: Only push target_temperature when you have a genuine user-initiated change. Do not echo back the last known value on every subscribe response.

​
Example: Push Temperature Change

{
  "objects": [
    {
      "object_revision": 458,
      "object_timestamp": 1707149000000,
      "object_key": "shared.09AA01AB12345678",
      "value": {
        "target_temperature": 21.5,
        "target_change_pending": true,
        "touched_by": {
          "touched_by": 3,
          "touched_at": 1707149000,
          "touched_tzo": -18000,
          "touched_user_id": ""
        }
      }
    }
  ]
}