ESPHome component for controlling Elero wireless blinds and lights via an ESP32 with a CC1101, SX1262, or SX1276 868 MHz RF transceiver. Bidirectional -- sends commands and receives status feedback.
Requires ESPHome 2026.9.0 or newer. Local development uses Python 3.12;
install the pinned tools with mise install, then dependencies with mise exec -- uv sync.
Native API devices continue to come from NVS; existing device backups and configuration
remain supported. See ESPHome compatibility for migration details.
The web UI is bundled with the component. GitHub installations do not require
Node.js, pnpm, or a separate frontend download. Frontend contributors must rebuild
and commit components/elero_web/elero_web_ui.h alongside source changes;
CI verifies that the generated header matches the source.
In components/elero_web/frontend/app, run mise exec node pnpm -- pnpm mock
and mise exec node pnpm -- pnpm dev in separate terminals. Open
http://localhost:3000; Vite proxies /elero/ws to the mock on port 8080.
The mock validates commands and outgoing events against asyncapi.yaml and shares
one device model across clients. CRUD, groups, backup/restore, learn-in, movement,
dimming, errors, and restart are simulated. Configuration survives a simulated
restart and resets when the mock process exits. RF raw bytes are diagnostic
placeholders; motor timing and radio reliability still require hardware testing.
For remote activity and fault scenarios, enter newline-delimited JSON in the mock
terminal, for example {"address":"0x333238","action":"up"} or
{"address":"0x333238","state":"blocking","rssi":-85}. The state field accepts
any documented RF state name. Learn-in normally completes each transmission step
in 300 ms; start the mock with MOCK_LEARN_IN_FAILURE=1 to simulate failure, or
send a short session_timeout_ms to exercise timeout. MOCK_PORT changes the
standalone server port; the default Vite proxy expects 8080.
Pick a device config for your board:
- ESP32 + CC1101 -- generic ESP32 with external CC1101 module
- ESP32-C6 + CC1101 -- ESP32-C6 with external CC1101 module
- Heltec WiFi LoRa 32 V4 -- onboard SX1262 (experimental)
- LILYGO LoRa32 V2.1 -- onboard SX1276 (experimental); native API + ESP-IDF setup
- LilyGO T-Embed -- onboard CC1101
Devices always live in NVS and are managed at runtime through the web UI. The adapter only decides how Home Assistant sees them:
elero_nvs: -- ESPHome native API. Recommended for HA-only setups.
external_components:
- source: github://manuschillerdev/esphome-elero
# ... board + SPI + elero config from your device page ...
api:
elero_nvs:
elero_web:elero_mqtt: -- MQTT HA discovery. Use when you already run an MQTT broker, or when you want device CRUD to apply without rebooting.
external_components:
- source: github://manuschillerdev/esphome-elero
# ... board + SPI + elero config from your device page ...
mqtt:
broker: !secret mqtt_broker
elero_mqtt:
topic_prefix: elero
discovery_prefix: homeassistant
device_name: "Elero Gateway"
elero_web:- Flash your config (
uv run esphome run your-config.yaml). - Open
http://<device-ip>/elero. - Press buttons on your physical Elero remote -- RF packets appear in real time and remotes/blinds are auto-discovered.
- Save discovered devices in the web UI.
- (Optional) Backup: Hub → Backup & Restore → Download. Keep this JSON safe -- it's how you recover devices after flashing a replacement chip.
If you're upgrading from a version where devices were defined under cover: - platform: elero / light: - platform: elero, see docs/MIGRATION-yaml-to-nvs.md. The TL;DR: run uv run scripts/migrate_yaml_to_json.py old.yaml -o backup.json, remove the cover: / light: blocks from YAML, flash, then upload the backup via the web UI.
Group transmissions support up to 31 destination channels per source address on CC1101, SX1262, and SX1276. See radio framing and limits.
Cover groups expose member-derived state and position through MQTT and the native
API. Motors with different command variants can coexist: each cover supports
command_up, command_down, command_stop, command_check, and command_tilt
overrides. For example, Raffstore motors may need command_up: "0x21" and
command_down: "0x44". Existing NVS devices and backups retain their defaults.
See the per-device fields.
- Configuration Reference -- full parameter tables for all modes
- Installation Guide -- step-by-step hardware setup
- Backup & Restore -- exporting/importing your NVS device list
- Migration from YAML devices -- upgrading from pre-0.11.0
- Device Configs -- board-specific wiring and config
- example.yaml -- minimal working config
Based on protocol research by QuadCorei8085/elero_protocol (MIT), stanleypa/eleropy (GPLv3), and andyboeh/esphome-elero.