# openHASP: an LVGL wall switch firmware for ESP32 and STM32

> openHASP is a re-implementation of the HASwitchPlate sketch as firmware for ESP32 and STM32F4 microcontrollers, and its main departure is that the interface is drawn with LVGL on the microcontroller rather than on a Nextion or TJC display module. The hardware becomes a commodity screen, and the control path is MQTT.

**HASwitchPlate/openHASP** — HomeAutomation Switchplate based on lvgl for ESP32

- Repository: https://github.com/HASwitchPlate/openHASP
- Website: https://www.openhasp.com
- Stars: 1,027 · Forks: 297
- Language: C++
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/haswitchplate-openhasp

## The rewrite that removed a proprietary display

openHASP controls home automation devices from a customizable touchscreen UI connected via MQTT. That summary line is short, but the interesting part is in what the project is a re-implementation of.

The original was the HASwitchPlate sketch created by aderusha, and the related HASPone project used a Wemos D1 mini and required a Nextion or TJC HMI display. This rewrite removes the Nextion and TJC hardware requirement by using the Light and Versatile Graphics Library on the microcontroller to drive a commodity display.

That is the whole design change, and it is a significant one. A Nextion or TJC module is a display with its own microcontroller, its own proprietary command language and its own page format, and the sketch had to draw its interface through that layer. With LVGL running on the ESP32 or the STM32F4, the firmware renders the interface itself, as a normal embedded UI, and the screen becomes a dumb panel with a known controller. That makes the hardware interchangeable, which is the difference between a project tied to one vendor's modules and one tied to a microcontroller family.

The choice of microcontroller is also deliberate. openHASP uses the ESP32 and the STM32F4 to take advantage of the hardware capabilities, so the firmware is a single codebase across two very different chip families rather than a project with a single supported board.

The project is MIT licensed, the site is openhasp.com, and the repository was last pushed to on 2026-10-10.

## MQTT is the contract with the home automation server

The control path is MQTT, and that choice determines what the firmware talks to.

Home Assistant and openHAB both speak MQTT natively, and both are in the repository's topic list alongside mqtt itself, lvgl, m5stack, az-touch and lanbon, which are the boards and screens the project has been run on. The M5Stack and the AZ-Touch are device families with a built in display, which is why they turn up in the topics alongside the more generic homeassistant and openhab.

The consequence of building on MQTT is that the firmware is not tied to one automation server. Anything that publishes and subscribes on topics can drive the interface, and the buttons on the wall are really topics that get published to. That also means the security of your wall switch is the security of your MQTT broker, since the firmware holds the broker credentials and will publish whatever topic a compromised device tells it to.

The interface itself is described as customizable, and the repository layout supports that claim. There is a data/ directory, which is where the interface definition and its assets live, and a user_setups/ directory, which is the place where a user's own configuration and screens go. A device that ships with a fixed English interface and no way to change it would not be much use in a home where the labels matter, so the separation between the shipped data and the user setup is the mechanism that makes the interface yours.

There is also a crowdin.yml in the repository, so the translations of that interface are handled through a translation platform rather than by editing files by hand, which is the kind of infrastructure that appears once a project has users outside the author's language.

## One codebase, two chip families, a hardware abstraction layer

The repository layout describes the firmware architecture, and the directory names do the explaining.

There is a hal/ directory, which is the hardware abstraction layer, and that is the piece that lets the same code run on an ESP32 and an STM32F4. Below that are boards/ for the board definitions, src/ for the application code, include/ for headers, lib/ for bundled libraries, data/ for the interface assets, user_setups/ for the user's own configuration, tools/ for build and flashing helpers, and test/ for the tests.

The build is PlatformIO, which the platformio.ini file and the platformio_override-template.ini file make obvious. The override template is the interesting one, because it is the file a user copies and edits to describe their own board, their own display and their own pin assignments without touching the shared configuration. That is the same pattern the user_setups/ directory follows for the interface, and together they are what makes the project usable on hardware the author does not own.

The editor support is thorough for an embedded project. There is a .clang-format for consistent formatting, a .vscode/ directory, a .devcontainer/ directory, a .gitpod.yml and a .gitpod.Dockerfile, so the environment can be reproduced in a container or in Gitpod, and a GitHub Actions workflow that the README badges point at, which is the build status for the master branch.

For a project that has to compile for two architectures and a range of display drivers, having the environment reproducible matters more than it would in a desktop project, since the difference between a working and a broken build is often one toolchain version.

## Getting started is documentation and a Discord channel

The README is short on purpose, and it points outward twice.

For how-tos, information and frequently asked questions, the project directs you to the documentation at openhasp.com. That is where the flashing instructions, the board wiring and the configuration guide live, and the demo screens in the README come from the same site's assets, which suggests the site is the primary documentation surface rather than the repository.

For support, it asks you to join the openHASP channel on Discord. The Discord link is one of the reference definitions at the bottom of the README, and the community link is in the header next to the badges.

There is no build command in the README, and that is worth being straight about. This is a firmware project rather than a library, so the flow is: you pick a board, you wire a display to it, you copy and edit the platformio override file, you set your MQTT broker in the user setup, you flash it, and you point it at your automation server. The repository gives you the build system, and the site gives you the steps.

The consequence is that the first successful build depends on documentation that lives outside the repository, which is a real dependency for anyone forking the project. The CHANGELOG.md, the CONTRIBUTING.md and the LICENSE file are in the repository, and the git history is public, so the parts of the process that the code encodes are inspectable even when the instructions are not.

## A development branch that outruns its own releases

The release history is the thing to look at before you pick a version.

The most recent tagged release is 0.7.0-rc13, a release candidate from 2024-08-26. Before that comes v0.6.3 from 2022-05-30 and v0.6.2 from 2021-10-20. So the newest stable artefact is more than four years old, and the newest artefact of any kind is a pre-release from more than two years ago.

The repository, meanwhile, was last pushed to on 2026-10-10, and the README's release badge explicitly includes pre-releases. The picture is a project where development continues on master and releases happen infrequently, and where the version you are most likely to want is a release candidate rather than a stable tag.

That is not unusual for firmware, but it has a practical consequence. If you are building a device to sit on a wall for years, you want a known configuration rather than a moving branch, and the 0.7.0 release candidates are the most recent code you can pin. If you are developing, working from master is the sensible choice, and the continuous integration status badge tells you whether the current head builds.

The other thing to check before you commit to a board is the demo screens, which the README links from the 0.6 assets path. They show the interface working on real hardware, and they are a quick way to judge whether the rendering and the touch handling are where you need them.

## What this project is, and what it is not

It helps to be clear about the category, because the name can be misread.

openHASP is firmware that turns a microcontroller and a touchscreen into a control surface for a home automation system. It is not the automation server, it does not replace Home Assistant or openHAB, and it does not contain the logic of your home. It is the panel you touch.

That framing matters for what you can expect. The firmware handles the display, the touch input, the MQTT connection and the publishing of topics, and the server still decides what happens when a topic is published. That is a good separation for reliability: if the server restarts, the wall panel keeps its place in the house, and if the panel reboots, the server state is unaffected.

It also means the project is only as good as the display ecosystem behind it. The rewrite's promise is that any commodity display works, and that promise depends on the LVGL driver set, the board configuration and the physical wiring all lining up. For someone who has a spare ESP32, a resistive or capacitive touch panel and an afternoon, that is a reasonable bet. For someone who needs a certified device with a warranty and a known bill of materials, it is not.

The other limitation is the one every hobby firmware project has, which is that the person who flashed it owns it. The MIT licence means the code can be read and changed, the CHANGELOG is in the repository, and the community channel is where the real support happens.

## Conclusion

openHASP fits a home automation enthusiast with an ESP32 or an STM32F4 board, a commodity display and a running Home Assistant or openHAB instance, who wants a physical switch with a screen instead of a phone app. It does not fit a build that needs a released, stable firmware on a specific board, because the newest tagged artefact is a release candidate from 2024 while the last stable is from 2022, and it does not fit a project that wants the automation server replaced, since the firmware is a control surface, not a controller. Verify three things before you solder: that the board you have is in the boards/ directory with a matching hardware abstraction layer, that your display is one the LVGL driver set in your board configuration supports, since the whole point of the rewrite is that any commodity display can work, and that you are comfortable tracking a development branch, because the code is being pushed to but the tagged releases have not kept up.

## FAQ

### What hardware does openHASP need?

An ESP32 or an STM32F4 board and a touchscreen. The original HASwitchPlate sketch and the HASPone project needed a Nextion or TJC HMI display, and this rewrite removes that requirement by rendering the interface with LVGL on the microcontroller itself, so a commodity display is driven directly.

### How does openHASP talk to my home automation server?

Over MQTT. The project describes itself as controlling home automation devices from a customizable touchscreen UI connected via MQTT, and the repository topics include homeassistant, openhab and mqtt, with the M5Stack and AZ-Touch among the devices it has been run on.

### How do I build the firmware?

With PlatformIO, using platformio.ini for the shared configuration and platformio_override-template.ini as the file you copy and edit for your own board, display and pin assignments. The repository also ships a .clang-format, a .devcontainer, a .gitpod.yml and a .gitpod.Dockerfile, plus a GitHub Actions workflow that reports the build status for master.

### Which version of openHASP should I install?

The most recent tagged artefact is 0.7.0-rc13, a release candidate from 2024-08-26, and the last stable release is v0.6.3 from 2022-05-30, so pin deliberately rather than by habit. The repository itself was last pushed to on 2026-10-10, which means development continues on master ahead of the tags.

### Where do I find the openHASP documentation and support?

The README points to the documentation at openhasp.com for how-tos, information and frequently asked questions, and to the openHASP channel on Discord for support. The interface assets live in the data/ directory and your own configuration in user_setups/, with translations handled through the crowdin.yml configuration in the repository.

## Sources

- [HASwitchPlate/openHASP on GitHub](https://github.com/HASwitchPlate/openHASP)
- [License: MIT](https://github.com/HASwitchPlate/openHASP/blob/master/LICENSE)
- [Project website](https://www.openhasp.com)
- [README](https://github.com/HASwitchPlate/openHASP/blob/master/README.md)
- [Releases](https://github.com/HASwitchPlate/openHASP/releases)

---

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