Protocols

• Conventions
• MQTT
• MQTT commands
• MQTT state
• Weather & clock
• Zigbee
• Zigbee endpoints
• Matter

What nestlocal, the service unfr0zen installs on the thermostat, speaks on MQTT, Zigbee and Matter: enough to write an integration for any home automation system. To set the integrations up with Home Assistant, see Integrations.

All three protocols read the same state and run the same commands, though raw/, eco_mode, fan_timer_end, rssi, local_ip, hot_water_boiling_state and heatpump_ready are MQTT's alone, and Matter takes neither the weather nor the time. A command changes the unit's settings; the state then shows what the unit did, not what was asked. A setpoint the unit adjusts or refuses comes back as the unit has it.

Conventions

• Temperatures are °C on every protocol, whatever the unit displays. MQTT carries degrees; Zigbee and Matter carry hundredths of a degree (2150 is 21.5 °C).
• Temperatures read as the display shows them: to 0.5 °C, or, when the unit displays °F, to the whole °F converted back to °C. The raw/ MQTT topics keep the unit's exact values.
• Setpoints written are rounded to 0.5 °C. The unit keeps a range's low and high at least 1.5 °C apart.
• The equipment decides what is offered. Cooling, the fan, an air filter, a humidifier and so on appear only when the unit's wiring has them (can_heat, can_cool, has_fan, has_air_filter, has_humidifier, has_dehumidifier, has_hot_water_control), and each HVAC stage when its wire is (has_x2_heat, has_x3_heat, has_aux_heat, has_alt_heat, has_x2_alt_heat, has_emer_heat, has_x2_cool, has_x3_cool), the first heat or cool stage beside any other of its kind. A Heat Link model installed with the Works With Nest boiler option (which needs Zigbee or Thread) offers heat with nothing on W1, though the unit's can_heat in raw/shared stays false.
• Nothing is offered before the unit has reported its settings to nestlocal, a few seconds after it starts.
• The serial is the unit's serial number, which is also its hostname.

MQTT

nestlocal is an MQTT 3.1.1 client of your broker: tcp:// or mqtt:// in the clear, ssl://, tls:// or mqtts:// over TLS. WebSockets are not supported.

Every topic starts with nestlocal/<serial>/.

Outgoing publishes are QoS 0 unless stated, and the empty discovery configs of a root change are QoS 1. Incoming ones may be QoS 0 or 1.

Watch everything, and set a temperature:

mosquitto_sub -h broker.lan -t 'nestlocal/#' -v
mosquitto_pub -h broker.lan -t 'nestlocal/<serial>/set/target' -m 21.5

Home Assistant discovery

nestlocal publishes retained discovery configs to homeassistant/<component>/nestlocal_<serial in lowercase>/<key>/config on each connection, again when a config changes (equipment, firmware version, °C/°F) and whenever online arrives on homeassistant/status.

• Removal. An entity the equipment stops offering during a connection gets an empty retained payload.
• Names. Each config's default_entity_id is <component>.<root>_<key>, the root nestlocal_<serial in lowercase> unless the install named another, and its device is named Nest Thermostat unless named otherwise; unique_id and the device's identifier keep nestlocal_<serial in lowercase>.
• A new root. When the root changes, nestlocal publishes an empty retained payload to every config, waits 2 seconds, and publishes them again: Home Assistant restores each removed entity under its new default_entity_id. It does so once more at the next online on homeassistant/status, for a Home Assistant that wasn't running the first time.
• Without Home Assistant. Every config reads state and names its availability topic, so a system that isn't Home Assistant can ignore discovery and use the topics above.

Components: one climate (key thermostat), and sensor, binary_sensor, switch, number, select and button entities whose key is the state field they read or the command they send (sensor hvac_action reads action).

MQTT commands

Publish to nestlocal/<serial>/set/<command>, and watch state for the result.

• Payload. Plain text, surrounding whitespace ignored.
• On/off. ON, OFF, true, false, 1 or 0, in any case, as are the ON and OFF of hot_water_boost and filter_reset. Other words are case-sensitive.
• Errors. A payload out of range or unknown, or a command for a bucket the unit hasn't reported, is logged on the unit and ignored: there is no error topic.
• Retain. Don't retain commands, the weather's aside (set/outdoor_temperature, set/outdoor_humidity, set/weather): nestlocal gets every retained one again each time it connects.

MQTT state

The state topic's JSON. A number or string the unit hasn't reported is null, and a bool false. mode and action read off, fan_mode auto, preset none, hot_water_boost off and hot_water_schedule true.

Weather & clock

The unit's weather screen and its clock came from Google. Over MQTT, anything can supply them; the Home Assistant blueprints on the Integrations page are one implementation.

Weather. Publish set/outdoor_temperature and set/outdoor_humidity; without both the unit shows no weather. Retain them so a restarted nestlocal gets them back, as the Home Assistant blueprint does. Optionally publish set/weather, retained too, as JSON in Home Assistant's own names:

{
  "condition": "partlycloudy",
  "next_rising": "2026-10-31T07:12:00+00:00",
  "next_setting": "2026-10-31T17:40:00+00:00",
  "hourly": [{"datetime": "2026-10-30T15:00:00+00:00", "temperature": 12.5, "humidity": 70}],
  "daily":  [{"datetime": "2026-10-31T00:00:00+00:00", "temperature": 14, "templow": 6, "humidity": 65}]
}

• Every field is optional, and each publish replaces the last, so a field left out is cleared. Times are ISO 8601 with an offset; temperatures °C.
• condition is a Home Assistant weather condition: sunny, clear-night, partlycloudy, cloudy, fog, rainy, pouring, lightning, lightning-rainy, snowy, snowy-rainy, hail, windy-variant. Others show the unit's default image.
• next_rising and next_setting together choose the day or night image; one alone is ignored.
• hourly: up to 48 hours. daily: up to 6 days. A twice-daily list (day and night halves, each with is_daytime) is folded into days, the night's temperature as the low.

Clock. nestlocal sets the unit's clock from NTP. Over MQTT it also asks, whether or not NTP works: it publishes an empty message on time/request on each connection and every minute until answered, then every 6 hours. Answer on set/time with the current time in seconds since 1970 (decimals allowed; a value under 1,000,000,000 is refused). An answer more than 5 seconds after the request is ignored.

mosquitto_sub -h broker.lan -t 'nestlocal/+/time/request' -v | while read -r topic _; do
  mosquitto_pub -h broker.lan -t "${topic%/time/request}/set/time" -m "$(date +%s)"
done

Zigbee

The thermostat is a Zigbee 3.0 router on the Home Automation profile (0x0104), in standard ZCL clusters, plus one manufacturer-specific cluster, Weather, for what Zigbee has no standard for. Zigbee2MQTT has a ready-made converter, which is also a working reference for a converter or quirk elsewhere.

Reports

The thermostat reports every change, and everything every 10 minutes (the first 10 s after joining), to the coordinator (0x0000), endpoint 1. OutdoorTemperature and endpoint 5's seconds left trigger no report of their own: they go out with the next one. It does so whatever bindings and reporting configuration exist: Configure Reporting is accepted and changes nothing. Bind and configure reporting anyway if your stack expects it; the converter does.

Reported attributes: Thermostat 0x0000–0x0002, 0x0011–0x0014, 0x001B, 0x001C, 0x0025, 0x0029; Power Configuration 0x0020; 0x0000 of Fan Control, Thermostat UI Configuration, Relative Humidity and Temperature Measurement; PresentValue (0x0055) of Analog Output, Analog Input, Binary Input and Binary Output.

Commands

Read Attributes, Write Attributes (with and without response), Configure Reporting and Discover Attributes are answered.

• Writes. A write is a command (see MQTT commands, with the same ranges, but 9–32 °C for the occupied setpoints): out of range gives INVALID_VALUE, read-only READ_ONLY, the wrong type INVALID_DATA_TYPE, an attribute the cluster lacks UNSUPPORTED_ATTRIBUTE.
• Reads with no value yet. A read of an attribute with no value yet gives ZCL's "none" for its type (0x8000 for LocalTemperature, OutdoorTemperature and MeasuredValue, 0xFFFF for humidity, 0xFF for battery voltage).
• Defaults. Occupied and unoccupied setpoints read defaults instead (cooling 2400 and 3200, heating 2000 and 900), the fan timer 15, the fan schedule's run time 60, its start and end 0, and the target humidity 35.
• Manufacturer-specific frames. Served for the Weather cluster with Nest Labs' code; any other gets UNSUP_MANUF_*_COMMAND.

Time

Endpoint 1 is a Time cluster (0x000A) client: 10 s after joining, then every 6 hours, the thermostat reads Time (0x0000, UTCTime) from the coordinator's endpoint 1 and sets its clock from it when the two differ by more than 2 s; a read that brings no time is retried every minute. Zigbee2MQTT and ZHA answer it by themselves. An answer is trusted only within 5 s of the request.

Zigbee endpoints

Each endpoint has a fixed number, present when the unit's equipment, as of nestlocal's start, calls for it.

Thermostat cluster (0x0201), endpoint 1

Commands: SetpointRaiseLower (0x00; mode 0 heat, 1 cool, 2 both; amount int8 in 0.1 °C, clamped to the limits; in heat or cool, a mode naming only the other side does nothing) and ClearWeeklySchedule (0x03; as clear_schedule).

Other clusters

Weather cluster (0xFC00, manufacturer-specific), endpoint 1

What the thermostat used to get from Google: MQTT's set/outdoor_temperature, set/outdoor_humidity and set/weather as attributes, all read/write, written by the coordinator with manufacturer code 0x10D6 in the frame and kept in memory until written again.

• None. Each kind of value has one "none": 0x8000 for an int16, 0xFF for a uint8, 0xFFFFFFFF for a UTCTime (seconds since 2000-01-01 UTC), the empty string for the condition.
• Range. Any int16 outside −60 to 60 °C, or uint8 above 100, gets INVALID_VALUE.
• Forecast slots. The forecast is in slots, hour hh (0–23, in hex: hour 23's time is 0x1170) at 0x1hhf and day dd (0–5) at 0x2ddf, f the field; a slot whose time is none is left out of the forecast, so write every slot.
• Frame size. A frame holds about 12 attributes (4 hours, or 3 days); Zigbee2MQTT's converter does the splitting, from the weather blueprint for Zigbee.

Matter

A Matter node on UDP port 5540, over Wi-Fi and, with Thread support, Thread. Any Matter controller commissions it over IP or, on a 3rd generation with the supported Bluetooth firmware, Bluetooth, with the pairing code from Integrations; the discriminator is 512 with the default code, and a custom code sets its top 4 bits, the rest zero.

On the thermostat, UNFR0ZEN → Matter → Enable pairing → Forget and pair confirms removal of every existing Matter fabric and its sessions before a fresh pairing window opens. Failed re-pairing does not restore the removed controllers. Wi-Fi and Zigbee settings are retained.

Switches are numbered from 10 in this order, skipping those the equipment lacks: Auto-Schedule, Home/Away Assist, Sunblock, Early-On, Eco heat limit (can heat), Eco cool limit (can cool), Humidity control (with a humidifier or dehumidifier), Hot water boost, 30 minutes when on, and Hot water schedule (with hot water control), Filter reminder and Filter reset (with an air filter; Filter reset always reads off, and turning it on resets the filter as filter_reset), and last, Fan schedule (with a fan).

The numbers therefore differ between units: identify each by its Fixed Label, ha_entitylabel, whose value is the name above. Endpoints 2–7 are labelled Backplate temperature, Battery, Fan, Fan timer duration, External temperature and Temperature source; 40–42 Fan schedule run time, Fan schedule start and Fan schedule end.

The equipment is read once, at start, as on Zigbee.

Thermostat cluster

• Features: Heating, Cooling, AutoMode, Occupancy, Presets. What the unit can do is in ControlSequenceOfOperation (read-only): heating only, cooling only, or cooling and heating.
• SystemMode: Off, Heat, Cool, Auto (heat_cool). A mode the equipment can't do is refused with a constraint error.
• Occupied setpoints: the range in Auto; otherwise either one sets the single target. Limits 9–32 °C, dead band 1.5 °C. In Auto, a write closer than the dead band to the other setpoint is refused with a constraint error.
• Unoccupied setpoints are the eco temperatures. Writes: heating 9–21 °C, cooling 24–32 °C. Matter refuses the 4.5–9 °C that MQTT and Zigbee accept, but reads it, there and in the preset, when set that way.
• Occupancy (as MQTT's occupancy), OutdoorTemperature (from MQTT or Zigbee's Weather cluster; subscribers get it with the next other change), ThermostatRunningState (heat, cool, fan, heat stage 2, cool stage 2).
• Presets: one, handle eco (the eco temperatures). SetActivePresetRequest with eco turns eco on, with null back to the schedule. ActivePresetHandle is eco or null.
• Commands: SetpointRaiseLower and SetActivePresetRequest. No weekly schedule. SetpointRaiseLower stops at the limits and the dead band; outside Auto it moves the target whichever side it names.

Not on Matter: the indicators (Leaf, Early-On and Sunblock active, safety shutoff, filter replacement, hot water, humidifier and dehumidifier running), which of the other HVAC stages runs (W3, aux, alt and emergency heat, Y3), the target humidity, time to temperature, filter runtime, clearing the schedule, and sending the weather or the time: OutdoorTemperature only reads what MQTT or Zigbee supplied. Use MQTT or Zigbee for those.