ESPEasy: firmware for the sensors you already own

A project that opens by arguing against a trend

The first line of the ESPEasy README is a position rather than a feature list: Automate (using) Common Sense, No AI. It expands on that in one paragraph. The stated objective is to make people realize they can control appliances and act on sensor data themselves, and the README insists that the only requirements are common sense and the satisfaction of seeing something just work.

The second paragraph is an ownership argument. If you cannot build it yourself, the README says, you do not own it. That framing explains a lot about how the project is organised: everything runs on the microcontroller, there is no company account to register for, and the forum is offered as the place where maintainers will help you assemble it.

GitHub reports 3,606 stars and 2,222 forks for letscontrolit/ESPEasy, which is an unusually high fork count for firmware and a reasonable signal that people build their own boards on it rather than only installing a binary. There are 386 open issues. The last push recorded was 2026-09-21, and the default branch is `mega`.

GitHub reports the license field as NOASSERTION, which usually means the license could not be classified automatically, yet a `License.txt` file does sit at the root of the tree. If licensing matters for your use, read that file directly rather than trusting the badge.

The branch that is both the development branch and the stable one

The README heads its main section with a single word, MEGA, and then says two things that pull in opposite directions. It calls `mega` the development branch, notes that all new features go there, and in the same breath says it has become the current stable branch. The next sentence settles the intent: if you want to do a bugfix, do it on this branch.

That is a deliberate choice rather than sloppy documentation. Projects with a separate stable line end up maintaining two sets of plugin definitions, and a sensor firmware that lags by a year is rarely worth running. ESPEasy instead ships one line and asks users to back up before upgrading. You can read the tradeoff in the release notes, where the maintainer explicitly warns about a settings conversion that may not cover every configuration in the field.

The rest of the repository supports the single-line approach. There is a `docs/` tree that feeds a Read the Docs build, a Gitpod configuration and a `.theia/` directory for cloud workspaces, and a `preflight.sh` plus `uncrustify.cfg` that suggest formatting is checked rather than left to taste. Local development is documented separately in a PlatformIO starter guide rather than assumed.

One structural detail matters if you intend to contribute: `.gitmodules` is present, so the `lib/` directory is almost certainly a set of submodules rather than vendored copies. A plain clone without recursive initialisation will build differently from a release, which is the kind of thing the starter guide exists to explain.

Reading a release filename like a specification

Binary releases are produced on demand by a build bot rather than on a fixed schedule, and each one is named for its build date in a form like `mega-20220626`. The README then documents how to decode the filename, which is the single most useful piece of information on the page.

The pattern is ESPEasy_mega, then the release date, the build type, an optional Arduino library variant, the hardware type with its flash and filesystem sizes, and finally optional build features. Every component is a decision you make, which is the point: the project ships dozens of images so that you download the one that matches your board instead of a universal binary that leaves half the flash unused.

The build type table is the interesting half. A `normal` build carries the stable plugin set. A `max` build carries everything available, and a `max32` variant trades some of that for a large file system on 32MB flash. Then there are targeted ones: `energy` for energy measurement plugins, `display A` and `display B` for display plugins, `climate A` and `climate B` for climate measurement, `neopixel`, `IRext` for infrared hardware, and eight collection builds that add a defined plugin set on top of normal. Two entries exist for different reasons rather than features: `minimal` for switch and controller use cases, and `spec_*` for specialised technical builds the README says are not intended for regular use.

The Arduino library column lets you pin the core version, with options for core 2.7.4, core 3.1.2, their SDK v.3 combinations, the Arduino Beta release, and `alt_wifi` for an alternative WiFi configuration.

That table also has a small formatting error worth noting, since it is easy to misread. The `safeboot` row, described as an experimental build enabling most or all plugins on 4MB flash boards, has a stray pipe that shifts its columns out of line. The intended reading is the obvious one: no plugins included, at least in the way the other rows count them.

Nine Espressif targets and a build matrix to match

The hardware type column is a second decision you have to make, and the list has grown a lot. It runs from `ESP8266` for generic ESP8266 and ESP8285 boards and `WROOM02` for WRoom02, through `ESP32`, `ESP32solo1`, `ESP32s2`, `ESP32s3`, `ESP32c2`, `ESP32c3`, `ESP32c6` and `ESP32c61`.

The repository tree shows how much work that variety represents. Instead of one PlatformIO configuration, there are separate files per family: `platformio.ini` and `platformio_core_defs.ini` at the root, then `platformio_esp32_envs.ini`, `platformio_esp32_solo1.ini`, `platformio_esp32c2_envs.ini`, `platformio_esp32c3_envs.ini`, `platformio_esp32c5_envs.ini`, `platformio_esp32c61_envs.ini`, `platformio_esp32c6_envs.ini`, `platformio_esp32p4_envs.ini`, `platformio_esp32p4r3_envs.ini`, `platformio_esp32s2_envs.ini`, `platformio_esp32s3_envs.ini`, `platformio_esp82xx_base.ini`, `platformio_esp82xx_envs.ini`, and `platformio_special_envs.ini`.

One gap is visible if you compare the two lists. There is a PlatformIO environment file for the ESP32-C5 and one for the P4 variants, but the hardware type table in the README stops at C61 and does not yet name the C5 or P4. The 2026 release announcement says support for the ESP32-P4 and C5 was added, so the build system knows about them before the naming documentation does.

Supporting tooling sits alongside the configuration files. `crc2.py` and `memanalyzer.py` handle binary packaging concerns, `before_deploy`, `release`, `releasebot` and `embed_files.sh` cover the delivery path, and a `test/` directory alongside `tools/` and `misc/` suggests the build is exercised rather than only cross-compiled. The pinned Python dependencies in `requirements.txt` are the host side of that pipeline: `pioarduino` at 6.2.0, `cryptography` at 50.0.0, plus `pygit2`, `setuptools` and `uv`.

Flashing from a browser, and calling it experimental

The single best thing the README does for a newcomer is describe a browser-based flasher and immediately label it experimental.

The idea is straightforward: rather than installing a toolchain, you open a flash page, let it talk to the chip over WebSerial from the browser, and write a build you downloaded from the releases page directly to the device. The README states the current limitation plainly, saying only Chrome and Edge are supported.

The implementation is borrowed rather than built. The flasher uses ESP Web Tools, the project made by the people behind ESPHome and Home Assistant. That is worth noting for two reasons. It means the security model and the serial handling have already been reviewed by a much larger ecosystem, and it also means this part of ESPEasy will follow upstream decisions rather than the project's own roadmap.

For local builds the documentation points at PlatformIO, with a starter guide for local development linked from the Read the Docs site and a Gitpod configuration available if you would rather not configure anything on your own machine.

So there are two reasonable starting points. Flash a binary from the releases page if you just want running hardware, or set up PlatformIO if you intend to change a plugin definition.

The 2026 release that rewrote the network layer

The most recent release, `mega-20260720`, is described by its own author as a massive one. The two headline changes are that networking has been reworked and that a large number of new Espressif parts are supported, with the ESP32-P4, C5 and C61 named explicitly. The release points to the opening post of a long test build issue as the detailed summary of changes, which is an unusually honest admission that the release notes themselves are a summary of a summary.

What the maintainers fixed is more useful for a sense of the project's texture. The MFRC522 RFID reader plugin got faster at reading tags. The `wifi#connected` and `wifi#disconnected` events were fixed. An AT command for writing to a PPP modem was added, which suggests people are using these boards with cellular hardware. That kind of change, an event name that was subtly wrong, is the sort of thing only shows up after thousands of nodes run the firmware for years.

The warning attached to that release is the part to take seriously. The maintainer advises backing up the settings of an older node before updating, and stresses that you should have access to the device while you do it, because the network settings conversion may not cover every configuration found in the field. Some nodes may need a power cycle after the update. This is what the single stable branch costs, and the maintainer is upfront about it rather than burying it.

Release notes with some rough edges

The release history is short and shows the project mid-flight. After `mega-20260720` and `mega-20260125` comes `mega-20260108`, all published in 2026, with a gap of roughly six months between the January and July builds.

The middle release is where the metadata gets untidy. The tag is `mega-20260125` but its display name reads mega-20260121 (20260108-hotfix). So the date in the tag, the date in the title, and the date of the build it hotfixes are three different values. If you are pinning to a specific build in an automated deployment, use the tag rather than the title.

The substance of that hotfix is four fixes found since the 20260108 build, and they are small and specific. An OLED display of 128x64 showed only its left half in display_A builds. The P135 plugin had wrong discovery value types. MQTT import was not initiated and handled correctly. And a display stayed blank after an upgrade if settings were not saved, which is the kind of failure that looks like a hardware problem and is not.

The `mega-20260108` entry has its own editorial issue: it explains that the 20260107 build failed, so its own change list covers two commits and then carries the release notes for the failed build underneath. Reading it is fine once you know. It is a fair illustration of how much of the release process is handled by the tooling in that tree rather than by hand.

Editorial conclusion

ESPEasy is worth understanding as a distribution strategy rather than a codebase. The plugin is the unit of value, the release filename is the unit of choice, and the project accepts that no single build fits every board and sensor combination. The parts most likely to reach you quickly are the normal and max builds, the dated release naming, and the browser flasher, which removes the usual first obstacle of getting a toolchain onto a laptop. What deserves more caution is the rate of change: the 2026 network rewrite came with a maintainer asking every user to back up settings first and expect a power cycle, which tells you how much movement is happening under the stable label. If you already own ESP hardware and would rather not hand your measurements to someone else's server, this is a mature and unusually well documented place to start.

Frequently asked questions

Official sources

1. Issues
2. letscontrolit/ESPEasy on GitHub
3. Project website
4. README
5. Releases