# ESPurna firmware: flashing ESP8266 smart switches without the vendor cloud

> ESPurna is a GPL-3.0 firmware for ESP8285 and ESP8266 smart switches, lights and sensors, built on the Arduino Core for ESP8266. It replaces the stock firmware in devices such as Sonoff relays, and the trade-off is that you build and flash it yourself.

**xoseperez/espurna** — Home automation firmware for ESP8266-based devices

- Repository: https://github.com/xoseperez/espurna
- Website: http://tinkerman.cat
- Stars: 3,054 · Forks: 625
- Language: C++
- License: GPL-3.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/xoseperez-espurna

## The problem ESPurna solves for ESP8266 owners

Cheap Wi-Fi relays usually ship with firmware that talks to one vendor's server. You get an app, and you also get a dependency. ESPurna replaces that firmware with one you control. The README describes it as a custom firmware for ESP8285 and ESP8266 based smart switches, lights and sensors, and the supported board list lives in the wiki rather than the repository root. The audience is narrow and specific: people who already own Sonoff-style devices or similar ESP8266 boards, are comfortable flashing them over serial, and want the device to speak MQTT to a broker they run. If you want a device that works out of the box with a phone app, this is the wrong layer of the stack. The project itself points questions at a Gitter channel and asks that GitHub issues be reserved for bugs and enhancement requests, which tells you the maintainers expect users to arrive with some embedded experience.

## How the firmware is put together

ESPurna is C++ built on the Arduino Core for ESP8266, with third-party libraries pulled in through PlatformIO. The repository splits into code/, dist/ and images/, and the README credits Max Prokhorov as a collaborator since November 2018 alongside the original author. Functionally the firmware is a set of subsystems that share one configuration store and one web UI: switch and relay management, MQTT with group topics, a scheduler, sensor drivers, and integrations for Home Assistant, Domoticz, InfluxDB, Prometheus and ThingSpeak. The network side supports AP mode and STA mode, static IP, up to five defined networks with scanning for the strongest, mDNS, NetBIOS and LLMNR. The data flow that matters to most users is the MQTT path: the device publishes state and subscribes to command topics, and Home Assistant can pick those up through MQTT auto-discovery rather than hand-written configuration. Relay behaviour is configurable per switch, including pulse mode with a set duration, delayed on and off, and relay synchronization modes such as all equal or only one on. That last group is where ESPurna goes beyond a simple on/off bridge, and it is also where the configuration surface gets wide enough that a wrong setting is easy to make and hard to notice.

## Building and flashing with PlatformIO

The README does not put build instructions in the repository root. It redirects to the wiki, with three documented paths: PlatformIO IDE for VS Code, the PlatformIO CLI, and the Arduino IDE. The README's own advice is blunt: use PlatformIO. The CLI route is the one that fits a headless machine or a CI job. PlatformIO reads the project's platformio.ini, so a build selects an environment rather than a bare board name, and the environment determines which features are compiled in. That distinction matters because several capabilities are build-time options, not runtime toggles. The README states that WPS and Smart Config are not available in default builds, that SSL/TLS for MQTT is not on regular builds, and that NetBIOS and LLMNR require Arduino Core 2.4.0 or later. If you need any of those, you are editing the build configuration, not clicking a checkbox in the web UI. The repository root also carries ci_install.sh and ci_script.sh, which are the scripts the project's own continuous integration runs, so they are the closest thing to a canonical build invocation that ships with the source.

## A first real use: MQTT and Home Assistant discovery

After flashing, the device boots into AP mode by default, and the README notes you can also return to AP mode by double clicking the main button. You join its access point, open the web UI, and enter your Wi-Fi credentials there. From that point the device is reachable on your network and the rest of the setup happens in the same UI. The MQTT section is fully configurable from the web UI: broker, user, password, QoS, keep alive time, retain flag and client ID, which are the field names the README lists. Once the broker connection is up, Home Assistant can consume the device through MQTT discovery, which the README lists as supported for switches, lights and sensors. There is no configuration file to paste for this step, because the settings are entered as form fields in the device's own web UI rather than as a YAML block. If you would rather not use auto-discovery, the README says the alternative is copying and pasting configuration code into Home Assistant by hand, which is more work but gives you explicit control over entity names. Either way, confirm the device appears in the broker before touching Home Assistant, because a broker that never receives a publish will make the discovery step look broken when it is not.

## Where ESPurna gets awkward

The build-time feature gating is the first real limitation. You cannot enable WPS, Smart Config or MQTT over TLS from the web UI, because the README says those are absent from default and regular builds. The README links two GitHub issues, #64 and #1465, when discussing TLS, which is a signal that this has been a long-running constraint rather than a temporary gap. The second limitation is hardware scope. ESPurna targets ESP8285 and ESP8266 boards, and the supported list is a wiki page, not a promise that any ESP8266 device will work. A board with an unusual relay pin, a different LED wiring or an unsupported sensor will need a custom build and probably a look at the code. The third is release cadence. The most recent release listed is a snapshot build dated 2025-06-01, and the repository's last push was on 2026-04-15, so the dev branch carries changes that no snapshot captures. If you need reproducible firmware for a fleet, pinning to a snapshot is safer than tracking dev, but the snapshot is then your ceiling until the next one is published.

## ESPurna against Tasmota and ESPHome

The two comparisons people actually search for are ESPurna versus Tasmota and ESPurna versus ESPHome, and the difference is architectural rather than cosmetic. Tasmota is also firmware for ESP8266 devices and also speaks MQTT, but its configuration model centres on console commands and a rule engine, and it is distributed as prebuilt binaries for a large set of devices. ESPurna is built from source with PlatformIO, and its configuration lives in a web UI backed by a settings store, with per-switch options such as pulse mode, delayed on/off and relay synchronization expressed as structured settings rather than console commands. ESPHome takes a third position: you describe the device in YAML, and the toolchain compiles firmware from that description. That makes ESPHome more reproducible and more explicit about pins and sensors, at the cost of writing a YAML file per device instead of clicking through a UI. ESPurna sits between the two: more structured than a command console, less declarative than a YAML device description. For a handful of Sonoff relays where you want a web UI and MQTT groups, that middle position is reasonable. For dozens of heterogeneous boards, the YAML approach is easier to keep in version control.

## Licence, maintenance and upgrade cost

ESPurna is licensed under GPL-3.0. The practical implication of a copyleft licence at this layer is that if you distribute a device running modified ESPurna firmware, the source for your modifications has to be available under the same terms. Running it on your own hardware in your own home does not trigger distribution, so personal use is unaffected. If you build a product around it, that obligation is worth reading the licence text for rather than taking a summary from an article. On maintenance, the repository is not archived, and the last push was on 2026-04-15. The release history shows snapshot builds at roughly irregular intervals: 2024-08-30, 2025-01-14 and 2025-06-01. Upgrading means flashing again, and the README does not document a rollback path or a settings migration procedure, so treat a firmware upgrade as a change that may require re-entering configuration. The CHANGELOG.md file at the repository root is where the project records what changed between builds, and it is the first thing to read before moving a working device to a newer snapshot.

## Conclusion

Adopt ESPurna if you own ESP8266 hardware, already run an MQTT broker, and want local control with a web UI, a scheduler and Home Assistant auto-discovery. Do not adopt it if you want a vendor-supported cloud app, or if your hardware is not on the supported boards list, or if you cannot build from source or use a snapshot release. Before flashing anything, verify three things: that your exact board appears in the wiki hardware list, that you have a way to recover the device over serial if the flash goes wrong, and that the snapshot release you download matches the branch you intend to track. Note that the last push to the repository was on 2026-04-15, so the dev branch has moved since the 2025-06-01 snapshot build.

## FAQ

### How does ESPurna compare with Tasmota?

Both are firmware for ESP8266 devices and both support MQTT, but Tasmota is distributed as prebuilt binaries and configured largely through console commands, while ESPurna is built from source with PlatformIO and configured through a web UI backed by a settings store. ESPurna expresses per-switch options such as pulse mode, delayed on/off and relay synchronization as structured settings.

### How does ESPurna compare with ESPHome?

ESPHome has you describe each device in YAML and compiles firmware from that description, which makes pins and sensors explicit and keeps device definitions in version control. ESPurna is configured through a web UI after flashing, which is faster for a few devices and harder to reproduce across many.

### Where do I download ESPurna firmware?

The project publishes snapshot builds on its GitHub releases page, with the most recent listed release dated 2025-06-01. The README also documents building from source through the wiki, using PlatformIO IDE for VS Code, the PlatformIO CLI, or the Arduino IDE.

### Does ESPurna work with Home Assistant?

Yes. The README lists Home Assistant integration with support for switches, lights with colour and brightness, and MQTT auto-discovery for switches, lights and sensors. The alternative it describes is copying and pasting configuration code into Home Assistant manually.

### Which boards does ESPurna support?

ESPurna targets ESP8285 and ESP8266 based smart switches, lights and sensors, and the README points to a hardware list in the project wiki rather than listing boards in the repository. Sonoff RF Bridge support is documented separately, including multiple virtual switches.

## Sources

- [License: GPL-3.0](https://github.com/xoseperez/espurna/blob/dev/LICENSE)
- [Project website](http://tinkerman.cat)
- [README](https://github.com/xoseperez/espurna/blob/dev/README.md)
- [Releases](https://github.com/xoseperez/espurna/releases)
- [xoseperez/espurna on GitHub](https://github.com/xoseperez/espurna)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xoseperez-espurna