ESPHome can skip MQTT resubscribing after deep sleep with persist_subscriptions

An ESPHome device that wakes from deep sleep and reconnects to an MQTT broker sends a SUBSCRIBE for every command topic it listens to, even when the broker still remembers them from the last session. A change by Rapsssito, reviewed by bdraco and merged on 25 October 2026 after more than ten months in review, adds an opt-in way to skip that step. The documentation was merged the same day, so the option should ship in ESPHome 2026.11.

The new option

mqtt:
  clean_session: false        # keep the session on the broker (already the default)
  persist_subscriptions: true # new

persist_subscriptions needs clean_session: false. Without the option nothing changes and the code is not compiled in.

How it decides

The device keeps a single 32-bit fingerprint of its subscription set, built from the topics, their QoS levels and the config hash. When the broker answers the connection with "session present" and the fingerprint matches, ESPHome marks the subscriptions as done and sends nothing. In every other case it subscribes to everything, as it does today.

The fingerprint lives in memory that survives deep sleep and restarts but not a power cut: an RTC preference on the ESP8266 and an 8-byte RTC word with a checksum on ESP32 chips that have RTC memory. ESP32-C2, ESP32-C61 and LibreTiny keep it in RAM only, so on those chips any restart means one full subscribe. Nothing is written to flash, on any connection.

The author put some effort into not trusting a half-finished session. Before sending subscriptions, the fingerprint is set to "untrusted", and the new value is stored only after the broker has acknowledged every SUBSCRIBE on that connection. If the link drops halfway, the next connect subscribes again. Unsubscribing from a topic at runtime marks it untrusted too.

What it saves

The PR estimates that a device with 10 subscriptions of about 50 bytes, waking every 15 minutes, saves around 2000 bytes per hour and 100-200 ms per reconnect. That sounds small, but the radio is the expensive part of a battery sensor's wake cycle: Wi-Fi transmission draws 70-100 mA, against under 1 mA in deep sleep. Shorter time online means a longer battery life, though the exact gain depends on how many command topics the device has.

Things to keep in mind

After a power loss or new firmware with a different set of topics, the first connection subscribes to everything once. Topics that only older firmware used stay subscribed on the broker until it drops the session. The saving only appears if the broker actually keeps the session between connections; when it drops it, the device simply subscribes as before.