Overview
Thedevice bucket is the most complex, with 239 registered fields. It contains a mixture of device telemetry (read-only), cloud-writable configuration, and special-purpose fields.
Object key: device.{serial}Direction: Bidirectional (with per-field restrictions)
Revision type:
base_object_revision (unconditional)
Field Access Modes
Not all fields in the device bucket work the same way:| Mode | Count | Server can write? | Description |
|---|---|---|---|
| Device-only | 113 | No — device overwrites | Hardware state, sensors, computed values |
| Cloud-writable | 103 | Yes | Configuration the server can push |
| Special | 23 | Varies | Custom processing paths (eco, HVAC capacities) |
Key Read-Only Fields
These are the most important device-only fields. The server stores them (from device PUTs) but must not push them back.| Field | Type | Description |
|---|---|---|
current_temperature | float | Indoor temperature in °C (note: actually in shared bucket) |
current_humidity | integer | Relative humidity (%) |
backplate_temperature | float | Backplate sensor temperature (°C) |
battery_level | float | Battery voltage level |
has_fan | boolean | Fan wiring detected |
has_humidifier | boolean | Humidifier wiring detected |
has_dehumidifier | boolean | Dehumidifier wiring detected |
has_emer_heat | boolean | Emergency/auxiliary heat wiring detected |
has_hot_water_control | boolean | Hot water system detected (UK/EU) |
can_heat | boolean | Device can heat (actually in shared bucket) |
can_cool | boolean | Device can cool (actually in shared bucket) |
time_to_target | integer | Estimated seconds until target temperature |
time_to_target_training | string | Training status: "ready", "training", or "not_ready" |
error_code | string | Active error code |
serial_number | string | Device serial number |
current_version | string | Firmware version |
model_version | string | Hardware model |
local_ip | string | Device IP on local network |
mac_address | string | WiFi MAC address |
leaf | boolean | Nest Leaf icon displayed |
auto_away | integer | Occupancy sensor: 0 = home, 1 = away |
Cloud-Writable Fields
These fields accept server writes via subscribe responses. Push them inside thevalue object of a device.{serial} bucket.
Temperature settings
Temperature settings
| Field | Type | Description |
|---|---|---|
away_temperature_high | float | Upper eco temperature (°C) |
away_temperature_high_enabled | boolean | Enable upper eco limit |
away_temperature_low | float | Lower eco temperature (°C) |
away_temperature_low_enabled | boolean | Enable lower eco limit |
temperature_scale | string | Display unit: "F" or "C" (display only — data is always Celsius) |
upper_safety_temp | float | Upper safety limit (°C) |
upper_safety_temp_enabled | boolean | Enable upper safety limit |
lower_safety_temp | float | Lower safety limit (°C) |
lower_safety_temp_enabled | boolean | Enable lower safety limit |
Fan settings
Fan settings
| Field | Type | Description |
|---|---|---|
fan_mode | string | "off", "auto", or "duty-cycle" |
fan_timer_duration | integer | Fan timer length (seconds) |
fan_timer_timeout | integer | Fan timer end time (Unix timestamp) — set to 0 to stop |
fan_duty_cycle | integer | Minutes per hour for duty-cycle mode |
fan_cooling_enabled | boolean | Airwave — runs fan with AC coil residual cold |
fan_duty_start_time | integer | Fan schedule start (seconds from midnight) |
fan_duty_end_time | integer | Fan schedule end (seconds from midnight) |
fan_schedule_speed | string | Fan speed during scheduled runs |
Temperature lock
Temperature lock
| Field | Type | Description |
|---|---|---|
temperature_lock | boolean | Enable temperature lock |
temperature_lock_pin_hash | string | Lock PIN hash |
temperature_lock_high_temp | float | Max allowed temperature when locked (°C) |
temperature_lock_low_temp | float | Min allowed temperature when locked (°C) |
Learning and scheduling
Learning and scheduling
| Field | Type | Description |
|---|---|---|
learning_mode | boolean | Auto-schedule learning enabled |
schedule_learning_reset | boolean | Reset all learned schedule data |
preconditioning_enabled | boolean | Start heating/cooling before schedule transitions |
max_nighttime_preconditioning_seconds | integer | Max preconditioning duration at night |
Humidity control
Humidity control
| Field | Type | Description |
|---|---|---|
target_humidity | float | Target humidity (%) |
target_humidity_enabled | boolean | Enable humidity targeting |
auto_dehum_enabled | boolean | Automatic dehumidification |
humidifier_type | string | Humidifier type |
dehumidifier_type | string | Dehumidifier type |
Heat pump / dual fuel
Heat pump / dual fuel
| Field | Type | Description |
|---|---|---|
dual_fuel_breakpoint | float | Temperature below which aux heat activates (°C) |
dual_fuel_selected | boolean | Dual fuel mode active |
heat_pump_aux_threshold | float | Aux heat lockout temperature (°C) |
heat_pump_aux_threshold_enabled | boolean | Enable aux heat threshold |
heat_pump_comp_threshold | float | Compressor lockout temperature (°C) |
heat_pump_comp_threshold_enabled | boolean | Enable compressor threshold |
heatpump_savings | string | "max-savings", "balanced", or "max-comfort" |
Display and device settings
Display and device settings
| Field | Type | Description |
|---|---|---|
farsight_screen | string | What the display shows on standby |
should_wake_on_approach | boolean | Wake display when someone approaches |
click_sound | boolean | Audible click on dial turn |
sunlight_correction_enabled | boolean | Compensate for direct sunlight on sensor |
radiant_control_enabled | boolean | Optimize for radiant/underfloor heating |
auto_away_enable | boolean | Enable occupancy-based auto-away |
home_away_input | boolean | Enable home/away feature globally |
Hot water (UK/EU Heat Link)
Hot water (UK/EU Heat Link)
| Field | Type | Description |
|---|---|---|
hot_water_mode | string | "schedule" or "off" |
hot_water_boost_time_to_end | integer | Boost timer end (Unix timestamp) |
hot_water_away_enabled | boolean | Allow hot water during eco mode |
hot_water_temperature | float | Hot water target temperature (°C) |
Safety Fields Behavior
When any safety-related field changes, the device forces four additional fields into its next PUT regardless of whether they changed:battery_level, safety_temp_activating_hvac, safety_state, safety_state_time
Accept these extra fields in your normal merge process.