ESPHome configuration
What is ESPHome?
ESPHome is an open-source project that turns microcontrollers - like the ESP32 inside your CTRL ONE - into smart-home devices. You describe what you want the device to do in a simple YAML text file, and ESPHome compiles it into firmware that runs on the device itself.
It is built to work hand-in-hand with Home Assistant, and it runs entirely locally. Here is why the CTRL ONE is built on it:
- Open source. ESPHome is free and community-driven. You can read, share and modify everything, and you are never locked into a vendor.
- Local by design. Everything runs on the device and your own Home Assistant server. No cloud, no subscription, and your data stays in your home.
- Ultimate flexibility. Because the configuration is text, you can change any behaviour and add sensors, screens, buttons and automations to your exact taste.
- Native Home Assistant integration. ESPHome devices are discovered automatically and appear as normal entities - no plugins or bridges.
- Over-the-air updates. Change the configuration and update the device wirelessly, without opening it up or reaching for a cable.
- A large, well-documented ecosystem. Hundreds of supported sensors and components, each with its own documentation page.
New to ESPHome? Start with the ESPHome website and the installation guide.
Customising your CTRL ONE
The CTRL ONE is designed to be made your own. It ships with a minimal but fully functional setup that shows its own sensor readings; the fun starts when you add widgets to read and control the rest of your home.
The ESPHome Device Builder
The ESPHome Device Builder is a tool you install on your computer (it can also run as a Home Assistant add-on). It is the primary way to configure the CTRL ONE once it is on your network: adopt the device, edit its configuration, and install updates. Download it from the ESPHome installation page.
Once the CTRL ONE is connected to your WiFi network, it will automatically show up in the Device Builder, with the configuration pre-filled and ready for editing.
ESPHome Web
ESPHome Web is a browser-based tool used only to provision the CTRL ONE over a serial connection. See the setup guide for how to use it.
Do not use ESPHome Web to flash firmware onto the CTRL ONE. Flashing from ESPHome Web overwrites the firmware that ships with the device and installs a blank ESPHome configuration.
Adding widgets
The display is made of widgets arranged on a grid. You add or rearrange widgets by editing the configuration to show the sensors and controls you care about - a thermostat readout, weather, plant status, buttons and sliders for your lights, and more. See the LVGL grid and widgets page for how it works.
Adding add-ons
Hardware add-ons extend what the device can do. The buzzer add-on plays notification sounds, and the 24VAC thermostat add-on turns the CTRL ONE into a heating controller. Each has its own configuration and documentation.
In Home Assistant
Because the CTRL ONE uses the ESPHome native API, Home Assistant discovers it automatically, and everything you configure - sensors, buttons, lights and more - appears there as entities you can use in dashboards and automations.
ESPHome components used
The CTRL ONE configuration is built from standard ESPHome components. Each is linked below with a short description of how the device uses it - follow the links for the full ESPHome documentation.
Component | How the CTRL ONE uses it |
|---|---|
The ESP32-C6 microcontroller the device runs on. | |
Connects the device to your home network. | |
Lets Home Assistant talk to the device directly over the network. | |
Updates the firmware wirelessly, without a cable. | |
Sets up WiFi credentials on first boot during provisioning. | |
Reads temperature, humidity and CO2 from the SCD40 sensor. | |
Reads the ambient light sensor. | |
The graphics engine that draws the display and its widgets. | |
Drives the 300 x 400 ePaper screen. | |
The touch input layer. | |
The screen backlight and the RGB indicator light. | |
The PWM signals that drive the backlight and RGB LED. | |
Restart, safe mode and CO2 calibration buttons. | |
Automation sequences, such as the touch backlight timer. | |
Resets the device to its defaults. | |
Plays tunes through the buzzer add-on. | |
Thermostat control with the 24VAC add-on. |
The repository
The whole configuration is open source (GPLv3) and hosted in the Codeberg repository, under esphome/. It targets ESPHome 2026.7.0 or higher.
Directory | Contents |
|---|---|
| Display setup, LVGL theme, shared styles and fonts, the welcome screen, and extra page layouts. |
| Self-contained LVGL widget YAML files, each configured through substitutions. |
| Reference templates showing how to arrange widgets together (thermostat, weather, plant monitor, test). |
| Hardware add-on configs (24VAC thermostat, buzzer). |
| Hardware validation modules (RGB cycling, touchscreen grid). |
The ctrl-one.yaml file is the production configuration, and ctrl-one-local.yaml is a local development configuration. The repository README documents the build and flashing commands.