device bucket

Overview

The device 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)

If you push a device-only field, the device compares it against its local value. If different, the device marks the field dirty and re-sends its own value in the next PUT — the device always wins. Accept these re-PUTs normally.

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 the value object of a device.{serial} bucket.

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

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

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

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

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

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

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)

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.

Overview

Transport Mechanism

Bucket System

Device State

For Developers

Overview

Field Access Modes

Key Read-Only Fields

Cloud-Writable Fields

Safety Fields Behavior

​Overview

​Field Access Modes

​Key Read-Only Fields

​Cloud-Writable Fields

​Safety Fields Behavior

Overview

Field Access Modes

Key Read-Only Fields

Cloud-Writable Fields

Safety Fields Behavior