A comprehensive solution for integrating 433MHz RF remote controls with Home Assistant. This project combines an ESPHome-based RF sniffer with a powerful learning interface in Home Assistant, allowing you to easily map RF signals to Home Assistant actions.
- QUICKSTART.md - Get started in 5 minutes
- README.md - This file: installation and overview
- RF433 mapping editor reference.md - Detailed editor features and usage
- HELPERS.md - Helper entity setup
- WIRING.md - Hardware wiring guide
- README_dimmer_control.md - RF433 dimmer control scripts and usage
- 3D Printable Enclosure - Parametric case for ESP32 and CC1101 on Printables.com
- Re-use existing 433 MHz remotes (Intertechno, Elro, Brennenstuhl, A-Trust) to control modern Wi-Fi/ZigBee plugs via Home Assistant
- Oldschool household members with reluctance to use home automation features, apps or voice control can keep using the 433MHz remotes
- Use existing 433 MHz remotes as generic actuators for all potential HomeAssistant actions
- No cloud dependency - works locally even without internet
- One button, multiple actions - trigger scenes/automations with a single press
- Cost-effective - repurpose old remotes instead of buying new smart ones
- ESPHome RF Sniffer: Reliable 433MHz signal reception using ESP32 hardware
- Learning Mode: Interactive UI for mapping RF signals to Home Assistant entities
- Visual Editor: User-friendly interface for creating and editing RF mappings
- Backup & Undo: Session and step-level backups with undo functionality
- Import/Export: Save and share your RF mappings as JSON
- Debouncing: Built-in protection against duplicate signals
- Status LED: Visual WiFi connection and remote action feedback
- Event Blocking: Option to temporarily disable RF event processing during learning
- Zigbee Button Mapping: Use the same mapping editor to define actions for Zigbee devices — trigger automations or scenes in Home Assistant from Zigbee button presses, just like with RF433 remotes.
- ESP32 development board (ESP32-DevKit or similar)
- 433MHz RF receiver module (CC1101 sub-GHz RF transceiver - tested)
- WS2812/WS2811 LED for status indication (optional but recommended)
- Jumper wires and breakout board or custom PCB
- 3D-printable enclosure (optional, recommended for easy installation)
- Home Assistant 2024.1 or newer (tested with 2026.1)
- ESPHome 2025.12 or newer (required for CC1101 support)
- MQTT Broker (Mosquitto recommended)
- Modern web browser (for the learning interface)
Performance Note: ESPHome compilation can be very slow on Raspberry Pi. For better performance, consider installing ESPHome on a Windows or Linux PC instead of using the Home Assistant add-on. See the ESPHome Installation Guide for platform-specific instructions.
Note: The RF signal handler logic is now moved to an extra file: rf_handlers.h
- Copy the contents of the
esphome/directory to your ESPHome configuration folder (includingrf_handlers.h) - Edit
esphome/secrets.yaml:wifi_ssid: "YourWiFiSSID" wifi_password: "YourWiFiPassword" api_encryption_key: "generate-with-openssl-rand-base64-32" ota_password: "generate-with-openssl-rand-hex-16"
- Customize
esphome/hardware-config.yamlfor your hardware:- GPIO pins for LED and RF receiver
- LED chipset and configuration
- RF receiver parameters
- Flash the ESP32:
esphome run 433mhz-sniffer.yaml
Add to your configuration.yaml:
mqtt:
sensor: !include mqtt_sensors.yamlOr copy the sensor definitions from homeassistant/mqtt_sensors.yaml to your existing MQTT configuration.
RF433 + Zigbee Button Mapping:
A single automation now handles both RF433 and Zigbee button events. This unified automation stores event data and executes mapped actions for both types of remotes, using the same mapping editor workflow. See homeassistant/automations.yaml for details and customization.
Method A: Direct File Include (Recommended)
Add to your configuration.yaml:
automation: !include automations.yamlThen copy the file: (or add to your existing automations.yaml)
cp homeassistant/automations.yaml /config/Method B: Using UI Automation Editor
- Go to Settings → Automations & Scenes → Create Automation
- Click the ⋮ menu → Edit in YAML
- Copy the content from
homeassistant/automations.yamlstarting fromalias: RF433 + Zigbee Remotes Button Handler - Save the automation
Copy the scripts from homeassistant/scripts.yaml to your scripts configuration.
Copy all files from homeassistant/www/ to your /config/www/ directory:
cp -r homeassistant/www/* /config/www/Create two helper entities in Home Assistant. See HELPERS.md for detailed instructions:
- Text Input:
input_text.rf433_last_event_store(stores RF event data) - Toggle:
input_boolean.rf433_block_events(controls event blocking)
Add the RF433 Learning Card to your dashboard:
type: custom:rf433-learning-cardSet the dashboard view to Panel (single card view). The RF433 Learning Card is designed to be used as a panel view.
You'll need to add it as a resource first:
- Go to Settings → Dashboards → Resources
- Add resource:
- URL:
/local/rf433/rf433-learning-card.js - Type: JavaScript Module
- URL:
See QUICKSTART.md for a streamlined getting started guide.
Before mapping buttons, verify that RF signals are being received:
-
Check ESPHome Logs:
esphome logs 433mhz-sniffer.yaml
Press an RF button - you should see:
[remote_receiver:xxx] Received RC Switch: protocol=X code='XXXXXX' -
Check Home Assistant Events:
- Go to Developer Tools → Events
- Click "Listen to Events"
- Event type:
esphome.rf433 - Press an RF button
- You should see event data with
protocolandcodefields
If events appear, you're ready to start mapping!
On top of checking incoming events via Developer Tools → Events, you can see check the ESPHome logs (if you installed the sniffer via ESPHome in HA directly) or via ´esphome logs 433mhz-sniffer.yaml´ (if you used ESPHome cli). If you see too many dulplicate events firing on pressing a key consider using a higher debounce setting.
For detailed instructions on using the learning interface, editor features, backup/restore, and advanced configuration options, see RF433 mapping editor reference.md.
Basic workflow:
- Enable Learning Mode in the RF433 card
- Press an RF remote button
- Configure the mapping in the editor (entity, service, optional parameters)
- Save and test
Edit esphome/hardware-config.yaml to customize:
- GPIO pin assignments
- LED settings (chipset, RGB order, brightness)
- RF receiver parameters (idle time, filter, tolerance, buffer size)
- Debounce timing
- Fallback AP credentials
- RF logging mode (
rf_dump_mode):rc_switch- Show only RC Switch signals (recommended for initial setup/debugging)all- Show all protocols + raw data (very verbose, for troubleshooting)none- No RF logging (recommended for production/day-to-day use to reduce log spam)
Edit homeassistant/www/rf433/rf433-config.js to customize:
- Supported entity domains
- MQTT sensor names and topics
- Helper entity names
- Default blocking duration
- Logging level (0=off, 1=error, 2=warn, 3=info, 4=debug)
- Check ESP32 is connected to Home Assistant (check status LED)
- Verify ESPHome logs:
esphome logs 433mhz-sniffer.yaml - Check RF receiver wiring and power
- Verify GPIO pin configuration in
hardware-config.yaml - Try different receiver placement (away from interference)
- Check helper entities exist (
input_text.rf433_last_event_store,input_boolean.rf433_block_events) - Verify MQTT sensors are created and receiving data
- Check browser console for JavaScript errors
- Verify automation is enabled and running
- Check RF events are being received (enable logging in
rf433-config.js) - Verify automation is triggered (Home Assistant → Settings → Automations & Scenes)
- Check event blocking is disabled
- Verify mapped entities still exist and are available
rf433-remote-ha-mapper/
├── esphome/
│ ├── 433mhz-sniffer.yaml # Main ESPHome configuration
│ ├── hardware-config.yaml # Hardware-specific settings
│ ├── rf_handlers.h # RF handler
│ └── secrets.yaml # WiFi and API credentials
├── homeassistant/
│ ├── automations.yaml # RF event processing automation
│ ├── mqtt_sensors.yaml # MQTT sensor definitions
│ ├── scripts.yaml # Helper scripts
│ └── www/
│ ├── rf433/
│ │ ├── rf433-learning-card.js # Main card component
│ │ ├── rf433-editor.js # Mapping editor component
│ │ ├── rf433-config.js # Configuration constants
│ │ └── styles/ # CSS styling modules
│ ├── utils/
│ │ ├── rf433-utils.js # Logging utilities
│ │ └── format.js # Date/time formatting
│ └── mixins/
│ ├── confirm.js # Confirmation dialogs
│ └── busy_overlay_mixin.js # Busy state overlay
├── pictures/
│ └── ....
└── README.md
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
This project is open source and available under the MIT License.
- ESPHome community for the excellent ESP32 platform
- Home Assistant community for inspiration and support
- All contributors and users of this project
Note: This is a personal project maintained on a best-effort basis in my spare time. Support is limited but I'll do my best to help!
If you encounter issues or have questions:
- Check the Troubleshooting section above
- Search existing GitHub issues
- Create a new issue with detailed information about your setup and problem
Tip: You can test the RF433 Learning Card and editor UI without hardware. See the Editor Reference for a step-by-step guide to simulating RF events.