ESPHome 2026.10 Is Out: What It Means for ratgdo and Other ESPHome Devices

ESPHome 2026.10.0 came out on October 21 (release post). ESPHome is the firmware that runs on a lot of local devices, including the ratgdo board I use for my garage doors (my ratgdo post). The ESPHome Device Builder add-on for Home Assistant, which is where you edit a device’s config and build and install its firmware, is also at 2026.10.0 (add-on config).

If your ratgdo is in Home Assistant and working, this release doesn’t force you to do anything. The device keeps running the firmware it has until you install an update. Most of what’s in 2026.10 is about how updates get built and sent, not about what the garage door does.

I’ve left mine alone so far. I may update at some point.

The short version

If it works, you can leave it alone for now. The one real deadline is ESPHome 2027.3.0 (by ESPHome’s naming, a March 2027 release), which removes unencrypted updates. Before then:

1. In Device Builder, open the ratgdo and click Edit. Look for password: under ota: and for key: under encryption: under api:. OTA means updating the firmware over Wi-Fi. The API encryption key is the key Home Assistant and the device use to encrypt everything between them.
2. While you’re in there, look under packages: for the ref: line. If it says main, you’re on the stock setup. If it’s anything else, you pinned it, and that matters below.
3. Install an update on 2026.9.0 or newer before 2027.3.0. Encrypted updates need an API encryption key, so if step 1 turned up no key:, that’s part of the job: add an encryption: key: under api: (Device Builder can generate one), install the update, then give Home Assistant the same key when it asks to reconfigure the device. Until it has the key, Home Assistant can’t connect to the device. If you have an OTA password, do the two-step move to encryption described further down.

Dates coming up

The encryption change

This came from the September release, 2026.9.0 (release post). Before that, firmware went over your network unencrypted. The firmware image has your Wi-Fi password and API encryption key in it, so someone on your network watching during an update could read them. In practice that means someone untrusted already on your home network, like a compromised device or a guest you shouldn’t have trusted. An OTA password didn’t help, because it only checked who was sending the update. Now, if a device has an API encryption key, updates from 2026.9.0 on are encrypted with it.

In 2027.3.0 the unencrypted path goes away. A device that’s still on firmware older than 2026.9.0 at that point can’t get an update over Wi-Fi the normal way and will need a USB flash or the web server update. 2026.10 added allow_plaintext_upload: true, which goes under encryption: in the ota: block, as a way to do one last migration install after 2027.3.0, but it’s easier to just update before then.

If your config has an OTA password:, moving to encryption takes two updates. First update to 2026.9.0 or newer with the password still in place. Then replace password: with encryption: and update again. Removing the password first makes the update fail. The full steps are in the ESPHome OTA docs.

The stock ratgdo YAML doesn’t set an OTA password, and adopting it in Device Builder doesn’t add one, so you’d only have one if you added it yourself. YAML is the plain text config file ESPHome builds the firmware from. The stock ratgdo ota: block doesn’t set encryption: either. Encrypted updates need an API encryption key, and Device Builder only adds one if you chose encryption when you adopted the device. So the thing to check is whether your config has key: under encryption: under api:.

If it doesn’t, the order matters. Add an encryption: key: under api: in the config first (Device Builder can generate one), then install the update, which puts the key on the device. Once the device has the key, Home Assistant can’t connect to it until it has the same key, so give Home Assistant that key when it asks to reconfigure the device and follow Home Assistant’s prompt. And as above, never put encryption: under ota: on a device that still has an OTA password and hasn’t been updated yet.

This applies to me directly. I have two ratgdo32 boards. According to Home Assistant, one is on ESPHome 2026.4.2 and the other on 2026.3.1, so both are older than 2026.9.0, and neither has an API encryption key set. I don’t know yet whether either has an OTA password. I haven’t done anything about it yet. As I read the steps above, the move is an API encryption key plus an update to 2026.9.0 or newer before 2027.3.0, and the two-step version if an OTA password turns up. If I miss the deadline, allow_plaintext_upload: true is the one-time way back in.

What changes for a ratgdo

Updates are smaller. On ESP32 boards, which includes the ratgdo32, Wi-Fi updates are now compressed and about a third smaller, so they finish faster. This only kicks in once the device is already running 2026.10 and you compile with 2026.10 or newer. Compiling is Device Builder turning the YAML into firmware. The update that gets it to 2026.10 goes the old way. ESP8266 boards, like the older ratgdo v2.5 on a D1 mini, already had compressed updates.

ESP8266 builds use a new toolchain by default. The toolchain is the set of build tools that does the compiling. This only matters for v2.5 boards, so ratgdo32 owners can skip this paragraph. The first time you compile an ESP8266 device on 2026.10, it does a full clean build, so expect that one to take longer. The old toolchain is still available with toolchain: platformio under esp8266:, but it’s deprecated and goes away in 2027.4.0.

The ratgdo project kept up with it. The stock ratgdo YAML uses a package, which is a chunk of config and code pulled in from somewhere else, and its ref: main line means every build pulls the newest ratgdo code from the main branch (v32board.yaml). ratgdo merged changes on October 7 to use a new 2026.10 logging feature that saves memory on ESP8266 (pull request #693), and you get that on your next build without editing anything.

ratgdo also already fixed a compatibility problem with an upcoming ESPHome change. If you’re on the stock config, there’s nothing to do. The detail: on October 9 ESPHome merged a change to how GPIO pins, the board’s input and output connections, are defined in code (pull request #20455). It broke the ratgdo code, and ratgdo fixed it the same night (pull request #695). That ESPHome change isn’t in 2026.10.0. It was merged after the 2026.10 beta started, and comparing it against the 2026.10.0 tag on GitHub shows it isn’t there. ESPHome hasn’t said which release it goes into. If your ratgdo config uses the default ref: main, you already have the fix. If you pinned the ratgdo package to a version from before October 9 (anything older than v1629), it won’t compile once an ESPHome release includes that change.

Pinning is the trade-off. Tracking main gets fixes like that one automatically, but it also means a build can break if ratgdo merges something broken. Pinning avoids that, and then you’re the one who has to move the pin forward.

To check yours, open the config in Device Builder and look under packages: for the ref: value. main means you’re tracking the newest code. A version like v1629 or a commit ID means you pinned it.

Devices on a separate network

The release adds an outgoing_connection option under api:. Normally Home Assistant connects to the ESPHome device. With this option, the device connects out to Home Assistant instead. That helps if your smart home devices are on their own network or VLAN (a separate virtual network on the same equipment) and you don’t want to open firewall rules so Home Assistant can reach in. It only works with API encryption turned on.

Light boot behavior (only if you have ESPHome lights)

This probably doesn’t affect a ratgdo. When an ESPHome device restarts, say after a power cut, each light comes back on or off based on its config. A light set to initial_state: {state: on} with no restore_mode: now actually turns on at boot. Before, it was quietly forced off. restore_mode: is being replaced by a new restore_state: option, and the old key still works for now. If you have ESPHome lights, check what they do after a power cut once you update.

How mine reaches Apple Home and Alexa

Mine reaches Apple Home and Alexa through Hubitat, using Hubitat’s HomeKit Bridge and Amazon Echo Skill. Home Assistant also has both boards through its ESPHome integration.