Project: ESP32 + SX1278 433 MHz receiver into MQTT and Home Assistant (OpenMQTTGateway / rtl_433_ESP)

[ZerOne]

This is a receive-only gateway that turns 433 MHz OOK sensors and remotes into MQTT messages, then into Home Assistant entities, using an ESP32 and an SX1278 module. The background is in the thread on LoRa chips and OOK and the parts are compared in the hardware thread.

Untested: I have not built this exact setup. Every pin, setting and command is taken from the project docs linked below, and I mark my own assumptions. Read the docs before you flash anything.

Parts

• ESP32 DOIT DevKit V1 and an Ai-Thinker Ra-01 SX1278 module (433 MHz). This is the combination the OpenMQTTGateway RF docs list. They also list the Heltec WiFi LoRa 32 V2 and LilyGo LoRa32 V2.1, which have the radio built in (buy the 433 MHz variants).
• About 17 cm of wire for the antenna.
• An MQTT broker (for example Mosquitto in Home Assistant) and a user for the gateway.

Step 1: wire it (3.3 V only)
The SX1276/77/78/79 supply range is 1.8 to 3.7 V, so never feed it 5 V. Pins from the OpenMQTTGateway environment for this board:

Code: Select all

Ra-01   ESP32
3.3V -> 3V3      GND  -> GND
NSS  -> GPIO5    RST  -> GPIO17
DIO0 -> GPIO15   DIO1 -> GPIO4
DIO2 -> GPIO16   (raw OOK data used by the decoder)
SCK  -> GPIO18   MISO -> GPIO19   MOSI -> GPIO23

The SPI pins are the ESP32 defaults. The repo's flags for them are commented out in the DOIT environment, and its CC1101 example uses the same numbers, so I think this is right, but check the wiring picture in the rtl_433_ESP README. Connect the antenna wire to the module's ANT pin.

Step 2: flash OpenMQTTGateway
Use the environment esp32doitv1-aithinker-r01-sx1278. It is in the board list on the web install page, and the latest GitHub release I saw (v1.8.1, January 2025) has prebuilt binaries for it on the releases page. The same release has heltec-rtl_433 and lilygo-rtl_433 for those boards. Building it yourself with PlatformIO from the repo is the other route. I have not checked which rtl_433_ESP version each build bundles, so the decoder list in the OMG docs may lag the rtl_433_ESP README.

Step 3: Wi-Fi and MQTT
Per the configuration portal docs: on first boot join the OpenMQTTGateway or OMG_ Wi-Fi network from your phone, choose Configure WiFi, then enter your Wi-Fi, the MQTT server (homeassistant.local works if mDNS is set up), port 1883, and the MQTT user and password. The base topic defaults to home/. Once connected you should see home/OpenMQTTGateway/LWT with the value Online.

Step 4: see messages, then Home Assistant
Watch the broker with:

Code: Select all

mosquitto_sub -t "home/OpenMQTTGateway/#" -v

Press a remote button or trip a sensor. Decoded devices show up under RTL_433toMQTT with the model and ID in the topic. In Home Assistant, the MQTT integration must use the same broker. OMG's Home Assistant page says discovery is on by default, the RTL_433 gateway creates devices and entities automatically, and discovery switches itself off 30 minutes after it starts. Some devices only appear after a button press or motion event. It also warns that changing a sensor's battery can change its ID and create a new entity.

Troubleshooting from the docs

• The decoder list includes "Generic Remote SC226x EV1527" and "Generic wireless motion sensor", which should cover the EV1527 devices from thread 43. I have not confirmed that.
• Signal detection is by RSSI. Adjust the margin by publishing {"rssithreshold": 12} to home/OpenMQTTGateway/commands/MQTTtoRF/config (the default is 9 dB). Publish {"status":1} to the same topic for receiver stats.
• rtl_433_ESP's README covers the SX127x OOK threshold and the PUBLISH_UNPARSED build flag for seeing signals that fail to decode.

Alternative: ESPHome (untested)
The ESPHome sx127x docs describe continuous-mode OOK with DIO2 read by remote_receiver. The sx127x block is their example with my pins, and the spi block is my addition:

Code: Select all

spi:
  clk_pin: GPIO18
  mosi_pin: GPIO23
  miso_pin: GPIO19
sx127x:
  cs_pin: GPIO5
  rst_pin: GPIO17
  bandwidth: 50_0kHz
  frequency: 433.92MHz
  modulation: OOK
  packet_mode: false
  rx_start: true
  rx_floor: -90
remote_receiver:
  pin: GPIO16
  dump: [raw, rc_switch]

Read the codes from the log, then match them with a remote_receiver binary sensor using rc_switch_raw.

Security and rules

• Fixed-code devices such as EV1527 send the same code every time. Anyone who records it can replay it, and a door sensor can be faked. Don't use these for security-critical jobs.
• Rolling-code remotes (KeeLoq) can't simply be replayed, but that does not make them unbreakable. Only decode devices you own.
• This gateway only receives. If you add transmitting, stay within 25 mW EIRP (about 14 dBm). The ESPHome examples use 17 dBm, which is about 50 mW before antenna gain, so don't copy that. See ACMA LIPD. This is not legal advice.

Question for the group: has anyone run this on an SX1278 or SX1276 board, and which devices decoded without any threshold tuning?