Configure your remote online → Pick the modes, add your Home Assistant entities and quick actions, and watch every change on a live emulator of the remote. Then download a ready-to-build ESPHome project, WiFi or ESP-NOW. No YAML editing needed.
ESP32-based wireless remote with a 128×64 OLED display. Controls AC units, lights, covers, and automations via Home Assistant. All display and interaction logic lives in C++ header files under src/; ESPHome YAML handles connectivity, sensors, and button wiring.
Two firmware flavours share the same code: the original WiFi remote (remote.yaml, talks to Home Assistant directly) and the ESP-NOW remote (remote_espnow.yaml, talks to a small always-on hub for sub-second wake and much longer battery life). See ESP-NOW variant.
- Full project write-up: tech.lugowski.dev/guides/smart-oled-remote
- 3D-printed case: MakerWorld
- ESPHome docs: esphome.io
The UI was redesigned in October 2026: same calm screens, but every screen now says where you are and works the same way. The write-up with the reasoning behind each decision is at tech.lugowski.dev/projects/smart-oled-remote-ui.
- Context strip on every screen: screen name, position dots (or
3/12when they don't fit), the room, battery. - One navigation rule: left / right moves between items, up / down changes the value. Quick actions are one press away from anywhere in the menu (up / down).
- Soft buttons over the round keys, like an ATM: a filled chip is a round key and says what it does on this screen; the outlined chip with three dots is the menu key.
- Cards for lights, covers and automations (lists still available), with a vertical slider for brightness and cover position.
- Room filter: hold the menu key to pick a room; entities without a room show everywhere.
- Toasts for a low battery and for a sent action; Settings one per page, editable values in a box with up / down arrows.
The images are rendered with the firmware's own layout and fonts.
| Menu | Screen | ||
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
| Climate | cool / heat | off | fan only |
![]() |
![]() |
![]() |
![]() |
| Lights | card | card, light off | list |
![]() |
![]() |
![]() |
|
| Covers | at rest | opening to its target | |
![]() |
![]() |
![]() |
|
| Automations | card, two shortcut keys | list | |
![]() |
![]() |
![]() |
![]() |
| Settings | contrast | sleep timeout | system |
| Quick action (up / down in the menu) | Action sent | Low battery |
|---|---|---|
![]() |
![]() |
![]() |
| Contrast | Sleep timeout | Read-only value | System |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
Left / right (and the round keys) move between settings, up / down changes the value in the box. Read-only values have no box.
HISTORY shows the battery level over the last 24 hours (hourly bars), 7 days (2 h columns) or 30 days (6 h columns); up / down switch the range. The remote stores nothing itself: the samples come from Home Assistant's Recorder, so the battery sensor must be recorded there. A sample Home Assistant has no value for is a gap in the graph, never 0 %. The WiFi remote fetches them from the history REST API by itself; the ESP-NOW remote asks the hub. Both need a long-lived access token, see Battery history.
| 24 hours | 7 days | 30 days |
|---|---|---|
![]() |
![]() |
![]() |
| hourly bars | 2 h columns, today inverted, a gap while HA was offline | 6 h columns, a date every week, charged 18 days ago |
| No samples yet | Waiting for the data |
|---|---|
![]() |
![]() |
| Hold the menu key | The room in the badge | Nothing in that room |
|---|---|---|
![]() |
![]() |
![]() |
esphome_remote/
├── README.md ← this file
├── tools/
│ └── screenshot.py ← OLED framebuffer → PNG converter
└── devices/
├── espnow_hub/ ← ESP-NOW hub (always-on ESP32, bridges remotes ↔ HA)
│ ├── hub.yaml ← hub firmware (reuses the remote's src/*_entities.h)
│ └── components/remote_hub/ ← ESPHome external component (state cache + relay)
├── multi_function_remote/ ← current device (v2 hardware, 6-button pad)
│ ├── remote.yaml ← production firmware, WiFi (edit substitutions at the top)
│ ├── remote_espnow.yaml ← production firmware, ESP-NOW (needs espnow_hub)
│ ├── remote_demo.yaml ← offline demo firmware (no HA/WiFi required)
│ ├── secrets.yaml ← WiFi credentials
│ ├── Makefile ← CLI build targets
│ ├── fonts/
│ │ ├── arial.ttf ← bundled into every generated config ZIP
│ │ └── arial_bold.ttf ← referenced by every font: entry in remote.yaml
│ ├── packages/ ← ESPHome YAML sub-packages (one per controller mode)
│ │ ├── menu.yaml
│ │ ├── mode_ac.yaml
│ │ ├── mode_lights.yaml
│ │ ├── mode_covers.yaml
│ │ ├── mode_automations.yaml
│ │ ├── mode_settings.yaml
│ │ ├── buttons.yaml ← abstract btn_* dispatcher (v2 layout)
│ │ ├── espnow/ ← ESP-NOW counterparts of the mode packages
│ │ │ ├── transport.yaml ← HELLO / channel scan / command sending
│ │ │ └── mode_*.yaml ← same scripts, state from hub instead of HA
│ │ ├── boards/ ← one file per PCB: chip, key pins, OLED power, battery
│ │ │ ├── pcb_v3.yaml ← LOLIN32 (ESP32) carrier board (default)
│ │ │ ├── pcb_v4.yaml ← PCB v4.0, ESP32-C3 module board
│ │ │ └── pcb_v4_1.yaml ← ESP32-S3 module board, PCB v4.1
│ │ └── layouts/
│ │ ├── layout_v1.yaml ← original AC board pinout (self-contained)
│ │ └── layout_v2.yaml ← 6-button generic layout (default)
│ └── src/ ← C++ controller classes and entity lists
│ ├── menu_entities.h ← ★ configure menu order / enabled controllers
│ ├── ac_entities.h ← ★ configure AC units
│ ├── light_entities.h ← ★ configure lights
│ ├── cover_entities.h ← ★ configure covers
│ ├── automation_entities.h ← ★ configure automations
│ ├── *_controller.h ← logic for each mode (no need to be modified!)
│ ├── espnow_protocol.h ← packet format shared by remote and hub
│ ├── espnow_remote.h ← remote-side packet ↔ controller glue
│ ├── history_core.h ← history buckets: HA JSON scanner + resampler (remote and hub)
│ ├── history_fetch.h ← history REST fetch (WiFi remote and hub)
│ ├── battery_history.h ← Settings > HISTORY page
│ ├── display_utils.h
│ └── remote_core.h
└── oled_remote/ ← legacy device (v1 hardware, original AC board)
└── README.md ← legacy notes
Files marked ★ are the ones you edit to match your Home Assistant setup.
The same firmware runs on three PCB generations. Pick yours with the PCB
substitution at the top of remote.yaml / remote_espnow.yaml, or per build
with make … PCB=v4_1 (esphome -s PCB v4_1 …). Each board's pins live in
packages/boards/pcb_<PCB>.yaml; the button layouts refer to keys by their
PCB switch name, so they work unchanged on every board.
| PCB v3 | PCB v4.0 | PCB v4.1 | |
|---|---|---|---|
PCB value |
v3 (default) |
v4 |
v4_1 |
| MCU | ESP32, WEMOS LOLIN32 board (esp32dev) |
ESP32-C3-MINI-1 module | ESP32-S3-MINI-1-N8 module |
| Charging / 3.3 V | LOLIN32's own charger and LDO | BQ24075 charger, LDO | BQ24075 charger, buck converter |
| Battery reading | resistor divider on GPIO32 (ADC) | MAX17048 fuel gauge, on the OLED bus | MAX17048 fuel gauge, own always-on bus |
| USB plugged-in sense | – | – | yes (USB Power entity) |
| OLED I2C | SDA GPIO27 · SCL GPIO25 | SDA GPIO6 · SCL GPIO7 | SDA GPIO8 · SCL GPIO9 |
| OLED power switch | GPIO15 | GPIO10 | GPIO14 |
| Wake key | POWER, GPIO0 | POWER, GPIO0 | POWER, GPIO0 |
Common to all: SH1106 128×64 OLED at 0x3C, ten keys to GND with pull-ups,
deep sleep with a timer wake for battery reports. On PCB v4.0 the ROM download
mode is entered by holding SELECT (GPIO9) during reset instead of POWER.
| v1 (left) | v2 (right) | |
|---|---|---|
| Buttons | AC, Power, +, − | ↑ ↓ ← → ● ■ |
| Use case | AC-only | Multi-mode (AC, lights, covers, automations) |
| Layout file | layouts/layout_v1.yaml |
layouts/layout_v2.yaml (default) |
Swap the layout: package line in remote.yaml to match your hardware revision.
Fill in devices/multi_function_remote/secrets.yaml:
wifi_ssid: "YourSSID"
wifi_password: "YourPassword"ESPHome uses a 32-byte base64 key (not a HA long-lived access token) to secure the native API. Each device should have its own unique key.
Generate one:
python3 -c "import os, base64; print(base64.b64encode(os.urandom(32)).decode())"Add it to devices/multi_function_remote/secrets.yaml (remote.yaml reads it via !secret api_key, so the key itself never has to touch a file you might share for support):
api_key: "paste_your_base64_key_here"The Settings → HISTORY page reads the battery's past values back from Home Assistant, through its REST API (the native API has no history call). Create a long-lived access token in Home Assistant (your profile → Security → Long-lived access tokens) and add, to devices/multi_function_remote/secrets.yaml for the WiFi remote or devices/espnow_hub/secrets.yaml for the hub:
ha_url: "http://homeassistant.local:8123"
ha_token: "paste_the_long_lived_token_here"BATTERY_HISTORY_ENTITY in remote.yaml / remote_espnow.yaml is the entity Home Assistant gave the battery sensor (the device name plus the sensor name: sensor.oled_remote_battery for the WiFi remote, sensor.espnow_hub_remote_battery for the hub's Remote Battery); change it if you renamed either. Without a token the page shows HISTORY NOT SET UP and everything else works as before.
After flashing, HA will auto-discover the device. Go to Settings → Devices & Services → ESPHome → Configure and enter the same key — HA stores it for all future connections.
remote.yaml's substitutions: block has USE_LIGHT_SLEEP — the generator's "Light Sleep" toggle sets it "true" (default "false", Deep Sleep). Deep Sleep deep-sleeps on the idle timeout and reboots (WiFi/API reconnect) on every wake; Light Sleep only blanks the display on that same timeout — WiFi and the API connection stay up, so the next press is instant with no reboot — and falls back to a real deep sleep after DEEP_SLEEP_FALLBACK_MIN (default 60) minutes of continued inactivity as a safety net. WIFI_POWER_SAVE_MODE (LIGHT/NONE) also moves with the toggle — NONE for Light Sleep keeps the radio fully powered for maximum responsiveness while connected. Edit these by hand if you're building straight from this repo instead of the generator.
Light Sleep is purely the software strategy above (blank display, WiFi/API stay associated) — the CPU stays at full clock the whole time. CONFIG_PM_ENABLE/tickless idle was tried for real automatic light sleep and reverted: on real hardware it destabilized WiFi/API and crashed (StoreProhibited) when combined with deep_sleep, so esp32.framework.sdkconfig_options no longer sets it.
For a static IP, add a manual_ip: block under wifi: in remote.yaml (values from secrets.yaml, not hardcoded — see the comment already there) and mdns: { disabled: true } at the top level; DHCP/mDNS is the default when neither is set.
logger: uses baud_rate: ${LOGGER_BAUD_RATE}, which defaults to 0 (no UART output — nothing to power on a device with no console attached). The generator's "Enable debug logging (UART)" toggle sets it to 115200; edit LOGGER_BAUD_RATE by hand if you're building straight from this repo instead. make logs-ota/esphome logs --device <ip> still work at baud_rate: 0 since remote logging goes over the API, not the UART — a real baud rate is only needed for USB-serial development logs or tools/screenshot.py's serial capture (see below).
Edit the src/*_entities.h files to match your Home Assistant setup (see Entity configuration below).
See Building and flashing below.
# Python 3.10+ required
python3 -m venv esphome-venv
source esphome-venv/bin/activate
pip install esphome
# Verify
esphome versionIf esphome is not on your $PATH, edit the ESPHOME variable at the top of Makefile.
All make targets run from the devices/multi_function_remote/ directory.
| Command | What it does |
|---|---|
make |
Compile production firmware |
make demo |
Compile demo firmware (no HA needed) |
make flash |
Compile + flash over USB (auto-detects port) |
make flash PORT=/dev/cu.usbserial-XXXX |
Flash to a specific USB port |
make ota IP=192.168.1.42 |
Compile + flash over WiFi (OTA) |
make logs |
Open serial monitor |
make logs-ota IP=192.168.1.42 |
Stream logs over WiFi |
make clean |
Remove build artefacts |
make espnow / make flash-espnow |
Compile / flash the ESP-NOW remote (USB only, no OTA) |
make hub / make flash-hub / make ota-hub IP=… |
Compile / flash the ESP-NOW hub |
make logs-espnow / make logs-hub IP=… |
Serial monitor for the ESP-NOW remote / hub logs over WiFi |
Hold the BOOT button while pressing RESET to enter flash mode, then:
cd devices/multi_function_remote
make flash
# or with an explicit port:
make flash PORT=/dev/cu.usbserial-0001After the first flash, subsequent updates can be done wirelessly:
make ota IP=<device-ip>- Copy the
multi_function_remote/folder into/config/esphome/on your HA instance:rsync -av devices/multi_function_remote/ ha:/config/esphome/multi_function_remote/
- In the ESPHome dashboard click + New device → Import from file and point it at
remote.yaml. - Fill in
secrets.yaml(wifi_ssid,wifi_password,api_key). - Hit Install.
All firmwares can dump the current OLED framebuffer as hex lines over the logger, which tools/screenshot.py converts to a monochromatic PNG.
Demo firmware (remote_demo.yaml, always logs over serial — no toggle needed): while the device is connected over USB, navigate to the screen you want to capture and hold the ■ stop button for 3 seconds. The device logs the raw framebuffer (1024 bytes, 128×64) as hex lines and immediately returns to normal operation.
Product firmware (remote.yaml, generator-built): press the Screenshot button — it's a plain HA button entity (no internal: flag), so it shows up under the device in Home Assistant automatically and can be pressed there, called from an automation/script (button.press), or pressed on demand from the ESPHome dashboard. To capture the output over USB serial (rather than just watching HA's log viewer), turn on the generator's "Enable debug logging (UART)" toggle first — the raw hex lines only reach the serial port when LOGGER_BAUD_RATE is a real baud rate, not the power-optimized default of 0.
ESP-NOW firmware (remote_espnow.yaml): the remote has no Home Assistant connection, so the button lives on the hub — press Remote Screenshot on the hub device in HA. If the remote is awake it answers within about a second; if it is asleep (its radio doesn't acknowledge the request), the hub logs Remote is asleep, screenshot will be taken on its next wake and sends the request again when the remote next wakes or sends a command. The remote sends its framebuffer to the hub over ESP-NOW and the hub logs it, so capture the hub's log (USB serial or over WiFi, below), not the remote's. Flash the hub and the remote together after updating, since both need the new protocol packets.
# Install dependencies (one-time)
pip install pyserial pillow
# Live mode — stays connected, saves screenshot_<timestamp>.png on every capture
python3 tools/screenshot.py /dev/tty.usbserial-XXXX
# Live mode from any log stream on stdin — e.g. the ESP-NOW hub over WiFi
# (PYTHONUNBUFFERED stops esphome from holding the log back when piped)
PYTHONUNBUFFERED=1 esphome logs devices/espnow_hub/hub.yaml | python3 tools/screenshot.py -
# Or parse a previously saved serial log (single capture, then exit)
python3 tools/screenshot.py --file dump.log
# Custom upscale factor (default: 4× → 512×256 px)
python3 tools/screenshot.py /dev/tty.usbserial-XXXX --scale 6| Flag | Default | Description |
|---|---|---|
--file / -f |
— | Parse a saved log file instead of opening a serial port (single capture, then exit) |
--baud / -b |
115200 |
Serial baud rate |
--output / -o |
screenshot_<ts>.png |
Output path (file mode only; live mode always uses the timestamp name) |
--scale / -s |
4 |
Pixel upscale factor (4 → 512×256 px) |
The display driver is components/oled_failover, a drop-in for ssd1306_i2c. At boot it probes the panel on I2C; if nothing answers, the remote keeps running with a virtual screen (every screen, key and radio path still works, nothing is drawn anywhere) instead of marking the display failed. The log says No OLED answered on I2C 0x3C: running with a virtual screen.
With the substitution SCREEN_PREVIEW: "true" (the generator's "Screen preview over USB" toggle) every changed frame is streamed over USB as oledfb lines, for a real or a virtual display alike. With no OLED the stream is always on, whatever the toggle says. The lines go through the logger when it is on and, when it is off (the default), straight to the USB-Serial-JTAG port (v4.0, v4.1) and only while a computer is connected, or to UART0 at 115200 on v3, which has no USB-Serial-JTAG and whose USB bridge listens on UART0, so no logger is needed:
[I][oledfb:20]: <frame> <part 0-7> <base64 of 128 bytes> # 8 parts = the 1024-byte framebuffer
The Live screen preview on the website's firmware page (Chrome/Edge, Web Serial) and tools/oled_monitor.py read those lines and draw the screen as a dot matrix next to the battery and USB readings and the log:
python3 tools/oled_monitor.py /dev/cu.usbmodemXXXX # http://127.0.0.1:8706
python3 tools/oled_console.py /dev/cu.usbmodemXXXX # the same in the terminal (quick look)While streaming, every board package also prints the battery readings every 5 seconds (usb is always 0 on v3 and v4.0, which have no USB sense; v3 has no fuel gauge, so gauge_v / gauge_pct repeat its ADC reading) as [I][oledbat:0]: usb=1 mv=3881 pct=37 gauge_v=3.881 gauge_pct=37.6 (mv=0 pct=-1 means no battery connected); the viewers draw them as tiles and a graph. Notes: the remote disappears from USB while it sleeps and comes back on wake, so the viewers reconnect by themselves; only one program can hold the serial port, so close the monitor before flashing; with a real OLED the stream is off by default because it adds a little work while a computer is connected.
Open src/menu_entities.h. The MENU_LIST array controls which controllers appear in the carousel and in what order:
static const MenuEntry MENU_LIST[] = {
{ APP_AC, "\ueb3b", "AC" },
{ APP_COVERS, "\uec12", "COVERS" },
{ APP_LIGHTS, "\ue0f0", "LIGHTS" },
{ APP_AUTOMATIONS, "\uea0b", "AUTOMATIONS" },
{ APP_SETTINGS, "\ue8b8", "SETTINGS" },
};- Remove a row — that controller disappears from the carousel. Its button handlers stay silent (
app_mode == APP_Xcan never be reached). - Reorder rows — carousel order changes; routing follows automatically.
- Single controller — the menu button is suppressed (nothing to switch to).
The APP_* constants are stable — YAML conditions never need changing regardless of which controllers are enabled.
One entry per physical air-conditioner unit.
static const char* AC_MODES_0[] = { "cool", "fan_only" };
static const char* AC_FAN_0[] = { "low", "high" };
static const ACEntity AC_LIST[] = {
{
"Living", // display name (≤8 chars)
"climate.living_room_ac", // HA entity_id
"living_room_ac_temp", // ESPHome sensor id — current temperature
"living_room_ac_mode", // ESPHome text_sensor id — hvac_mode
"living_room_fan_mode", // ESPHome text_sensor id — fan_mode
AC_MODES_0, 2, // modes array + count
AC_FAN_0, 2 // fan_modes array + count
},
// add more units…
};The sensor id: values must match entries in packages/mode_ac.yaml.
Supported modes: cool, heat, dry, fan_only, heat_cool, off.
One entry per light or light group.
static const LightEntity LIGHTS_LIST[] = {
// name entity_id state_sensor_id brightness_sensor_id dimmable
{ "Sofa", "light.sofa", "sofa_light", "sofa_brightness", true },
{ "Table", "light.table", "table_light", nullptr, false },
};Set dimmable: true and provide a brightness_sensor_id for lights that support brightness. Use nullptr for on/off-only lights.
One entry per cover (blind, curtain, roller shutter, etc.).
static const CoverEntity COVER_LIST[] = {
// name entity_id state_sensor_id position_sensor_id
{ "Living", "cover.living_room_curtain", "living_curtain_state", "living_curtain_pos" },
};state_sensor_id— text_sensor:open,closed,opening,closing, orstoppedposition_sensor_id— sensor: 0–100 % (0 = fully closed, 100 = fully open)
Both must match entries in packages/mode_covers.yaml.
One entry per automation, scene, script, or any triggerable HA entity.
static const AutomationEntity AUTOMATION_LIST[] = {
// name short entity_id service slot
{ "Good Night", "NIGHT", "scene.good_night", "scene.turn_on", "L" },
{ "Movie Time", "MOVIE", "scene.movie_time", "scene.turn_on", "R" },
{ "Away Mode", "AWAY", "automation.away_mode", "automation.trigger", nullptr },
};service— HA service to call (scene.turn_on,automation.trigger,script.turn_on, etc.)slot—"L"or"R"pins the entry as a one-press bottom-bar shortcut;nullptrfor list-onlyshort_name— bottom-bar label for slotted entries (≤5 chars)
The WiFi remote has to boot, associate with WiFi, open the Home Assistant API connection and wait for entity states on every wake. That takes several seconds and costs battery. The ESP-NOW variant moves all of that to a small always-on hub:
┌──────────────┐ ESP-NOW (no WiFi association) ┌─────────────┐ WiFi + native API ┌────────────────┐
│ Remote(s) │ ───── HELLO / CMD / BATTERY ───▶ │ espnow_hub │ ◀─────────────────▶ │ Home Assistant │
│ deep sleep │ ◀──── STATE_* snapshot ───────── │ state cache │ │ │
└──────────────┘ └─────────────┘ └────────────────┘
- Wake: the remote broadcasts
HELLO; the hub answers from its cache with the full state within a few milliseconds and the UI draws. No WiFi stack is started on the remote. - Commands: every button action becomes one small
CMDpacket; the hub turns it into the Home Assistant service call. - Live updates: while the remote is awake the hub broadcasts changes, so external changes still show up.
- Sleep: idle timeout defaults to 1 minute (Settings → SLEEP). Timer wakes only send a
BATTERYpacket and go back to sleep; the hub exposes it assensor.remote_battery. - History: Settings → HISTORY sends a
HIST_REQ(entity, bucket length, sample count); the hub fetches the entity's history from Home Assistant's REST API, resamples it into those buckets and answers withHIST_DATA. The request is generic, so other sensors can use it later. - Several remotes can share one hub.
The remote-side code is the same as the WiFi remote: all src/*_controller.h logic, the menu, button layouts and the src/*_entities.h lists are reused unchanged. Only the transport differs (packages/espnow/).
- Any ESP32 board on permanent power.
secrets.yaml→ WiFi credentials plusha_url/ha_tokenfor the battery history (see Battery history; remove thehistory:block fromhub.yamlto build without it),hub.yaml→API_KEYandNETWORK_KEY(anyuint32, shared with the remote; it keeps other ESP-NOW traffic from being interpreted).- Flash:
make flash-hubfromdevices/multi_function_remote/, latermake ota-hub IP=…. - Add the hub to Home Assistant like any ESPHome device. It exposes Remote Battery, Remote Battery Voltage, Last Remote (MAC of the last remote that talked) and a Resync Remotes button.
The hub includes the same src/*_entities.h files as the remote, so entities are configured once. Entity indices are what travel over the air: rebuild and flash both the hub and the remote(s) after changing a list.
NETWORK_KEY→ same value as the hub.ESPNOW_CHANNEL→ your router's 2.4 GHz channel. This is only the first guess: the remote remembers the channel on which the hub last answered and scans all 13 channels if it gets no reply (about 250 ms per channel). Pin the router to a fixed channel for the fastest wake.- Flash over USB:
make flash-espnow. There is no OTA without WiFi.
On the Settings screen the two network rows show ESPNOW CH <n> and the hub's MAC (or NO HUB). If the hub cannot be reached the remote shows NO HUB and retries every 5 seconds.
Documented in src/espnow_protocol.h. Every packet starts with R N <version> <type> <key>; state packets carry per-entity records (index + values), commands carry domain / index / action / value. Packets are plain ESP-NOW frames, so treat the key as a filter, not as encryption.
Device won't connect to WiFi
- Verify credentials in
secrets.yaml - Try increasing
output_powerinremote.yaml
Display not working
- Check that
PCBmatches your board (pins inpackages/boards/pcb_<PCB>.yaml) - Verify the display model (
SH1106vsSSD1306) and I2C address (0x3C)
Buttons not responding
- Check that
PCBmatches your board and the layout matches your keypad (v1 vs v2 layout) - Pins use internal pull-ups — button should connect GPIO to GND
ESP-NOW remote shows NO HUB
- Hub powered and connected to WiFi? (
make logs-hub IP=…) NETWORK_KEYidentical on both sides- The remote scans all channels; a hub on a 5 GHz-only network cannot be reached (ESP-NOW is 2.4 GHz)
HISTORY page shows an error
HISTORY NOT SET UP: noha_url/ha_tokeninsecrets.yaml(hub for the ESP-NOW remote, the remote itself for WiFi)HOME ASSISTANT NOT REACHED: wrong URL, expired token or the entity does not exist — the hub / remote log says which (History: HTTP 401 …)NO HISTORY YETwith a flat graph: the battery sensor is not recorded in Home Assistant (check the Recorder'sexclude), or the remote was only just set upWAITING FOR THE CLOCK: the hub has no time from Home Assistant yet; try again in a few seconds
ESP-NOW remote shows stale or missing entity state
- Both firmwares must be built from the same
src/*_entities.h; reflash the hub after editing a list - Press Resync Remotes on the hub (or wake the remote again)
API connection fails after flashing
- Make sure
api_keyinsecrets.yamlmatches what you entered in HA - HA must be reachable from the ESP32 subnet
The original single-purpose AC remote (devices/oled_remote/) uses a different board layout and an older single-file YAML approach. It is no longer actively developed.
→ See devices/oled_remote/README.md for notes on that configuration.













































