MQTT433gateway

This Project implements a MQTT 433.92MHz radio-frequency device gateway. This is a IoT bridge to couple popular RF devices like RC power-socket switches or weather stations to internet capable devices like smartphone and tables. In this way they can be integrated into a home automation system.

The Software runs on a ESP8266 micro controller/WiFi chip and process many 433.92MHz radio-protocols themselves. The protocols are processed utilizing the ESPiLight Arduino library which is a port of the pilight 433.92MHz protocols to the Arduino platform. The aim is to transmit, receive and parse many 433.92MHz protocols directly on the device and publish the results via MQTT.

A list of supported protocols can be found in the pilight manual: https://manual.pilight.org/protocols/433.92/index.html

Installation

Firmware binary are provided under releases. If you want to build from source please have a look at Development. For the first flash you have multiple possibilities, some of them are:

• Build and flash with PlatformIO (see Development)
• Flash with esptool.py

  $ esptool.py --port <serialport> write_flash 0 mqtt433gateway_<env>-<version>.bin
  

• Flashing the WebUpdater example from Arduino (File -> Examples -> ESP8266HTTPUpdateServer) and uploading the MQTT433gateway binary via browser.

At the moment two binaries are provided:

• mqtt433gateway_esp12e-*.bin generic ESP8266 module with cpu clock = 80 MHz (recommend)
• mqtt433gateway_esp12e_160-*.bin generic ESP8266 module with cpu clock = 160 MHz

The platformio.ini provides more environments, but the main different between these are the way how they are flashed via serial connector and how additional components (like LEDs) are connected. Since MQTT433gateway can be fully configured by the web frontend and provided over-the-air programming, these binaries should be sufficient.

Hardware

The Software is primarily written for ESP8266 devices. It is tested with an Adafruit HUZZAH ESP8266, but any other ESP8266 board should be fine too. The circuitry can be found in the hardware folder. The circuitry utilizes a separate 5V voltage regulator. This way it is possible to supply the MQTT433gateway with up to 12V. The 434MHz transmitter is directly connected to the power-supply input, thus it can be driven with 12V which enhances the transmitting range. But powering with 12V also means that the voltage regulator dissipates much power and a heat sink is highly recommended.

For transmitting and receiving you need 434MHz-RF modules. More information can be found here:

• https://wiki.pilight.org/receivers
• https://wiki.pilight.org/senders
• https://github.com/sui77/rc-switch/wiki/List_TransmitterReceiverModules

If you are interested in a good receiving range, then I can not recommend a WRL-10532 module. I only achieved a range of about 5m with it, after changing it against a RXB6 receiver, the range increases to over 30m (including walls).

For the transmitter and receiver module you need separate antennas. 1/4 lambda (17cm) antennas are sufficient, but you may want to try coil loaded antennas.

LED status

The MQTT433gateway indicates its status by a LED:

• Connecting to WiFi/startup: Flashing at 1 Hz
• WiFiManager require WiFi configuration: Flashing at 5 Hz
• Device require configuration: Flashing at 0.5 Hz
• Normal operation: Heartbeat pulsing
• OTA Update: on during upload

Configuration

The device is fully configurable through a web browser. If you boot it for the first time, it will create a WiFi access point (default ssid is rf434) where you can connect to. If you type in any url in your browser, you will get directed to the WiFi configuration of the device. You can select your network here and fill in the credentials.

After that it will stop the access point and connect to your network. There you can either discover it via mDNS (default is rf434.local), ask your router for the address of the device or check the serial console output. If you type this address in your browser, you'll see the main configuration frontend. The default username is admin, the default password is MQTT433gateway.

Please fill here your MQTT connection details. You can also change the topics the device will subscribe and publish to. In addition, all hardware related settings, like connection pins of transmitter and receiver are configurable.

Please note: you have to change the configuration password! For security reasons the device will not start working before this password is changed.

MQTT/Automation

The MQTT433gateway communicates via MQTT, therefore a MQTT broker is needed, e.g., Mosquitto. The topics for receiving and transmitting can be configured with the mqttReceiveTopic and mqttSendTopic settings. They default to rf434/recv/ and rf434/send/, respectively. It is possible to use a common topic for multiple gateways in one network and thus to expand the radio range.

After (re)connecting to the MQTT broker, the gateway sends the message {"version":"<git tag or hash>","chipId":"<chipId>"} to the version topic that is set in mqttVersionTopic as well as the message online to the state topic that is set in mqttStateTopic. In addition, it registered with the last will set to the message offline for the state topic. This allows to check the status of the MQTT433gateway, e.g. as a availability topic in Home Assistant.

MQTT subscription is done to the topic <mqttSendTopic><protocol>. The messages to be transmitted must be a valid pilight JSON messages. The setting mqttSendTopic should end with a /. <protocol> is the pilight protocol name. Additionally, <protocol> can be RAW to transmit a RAW signal similar as used with the pilight USB Nano.

Received and decoded RF signals are published in the <mqttReceiveTopic><protocol>[/<id>] topic as pilight JSON message. To avoid receiving errors, a message must be received at least twice before it is published. <protocol> is the pilight protocol name and the optional <id> will be used if the pilight JSON message contains an id attribute.

Integration in Home Assistant

Here are some examples how to integrate the MQTT433gateway into Home Assistant.

Status of the MQTT433gateway:

binary_sensor:
  - platform: mqtt
    state_topic: "rf434/state"
    name: "rf434"
    payload_on: "online"
    payload_off: "offline"
    device_class: connectivity

The message of a TCM 218943 weather station sensor looks like this: rf434/recv/tcm/108 {"id":108,"temperature":22.7,"humidity":50,"battery":1,"button":0}. A corresponding Home Assistant configuration is:

sensor:
  - platform: mqtt
    state_topic: "rf434/recv/tcm/108"
    unit_of_measurement: "°C"
    name: "tcm_a_temp"
    value_template: '{{ value_json.temperature }}'
    device_class: temperature
    availability_topic: "rf434/state"
  - platform: mqtt
    state_topic: "rf434/recv/tcm/108"
    unit_of_measurement: "%"
    name: "tcm_a_humidity"
    value_template: '{{ value_json.humidity }}
    device_class: humidity
    availability_topic: "rf434/state"

binary_sensor:
  - platform: mqtt
    state_topic: "rf434/recv/tcm/108"
    name: "tcm_a_battery"
    sensor_class: power
    payload_on: 0
    payload_off: 1
    value_template: '{{ value_json.battery }}'
    device_class: battery
    availability_topic: "rf434/state"

Impulse RC socket switches, like many RC socket switches with DIP switches:

switch:
  - platform: mqtt
    name: "impuls_24_1"
    command_topic: "rf434/send/impuls"
    payload_on: '{"systemcode":24,"programcode":1,"on":1}'
    payload_off: '{"systemcode":24,"programcode":1,"off":1}'
    availability_topic: "rf434/state"
  - platform: mqtt
    name: "impuls_24_2"
    command_topic: "rf434/send/impuls"
    payload_on: '{"systemcode":24,"programcode":2,"on":1}'
    payload_off: '{"systemcode":24,"programcode":2,"off":1}'
    availability_topic: "rf434/state"
  - platform: mqtt
    name: "impuls_24_3"
    command_topic: "rf434/send/impuls"
    payload_on: '{"systemcode":24,"programcode":4,"on":1}'
    payload_off: '{"systemcode":24,"programcode":4,"off":1}'
    availability_topic: "rf434/state"

Elro 800 based RC socket switches:

switch:
  - platform: mqtt
    name: "elro800_13_A"
    command_topic: "rf434/send/elro_800_switch"
    payload_on: '{"systemcode":13,"unitcode":1,"on":1}'
    payload_off: '{"systemcode":13,"unitcode":1,"off":1}'
    availability_topic: "rf434/state"
  - platform: mqtt
    name: "elro800_13_B"
    command_topic: "rf434/send/elro_800_switch"
    payload_on: '{"systemcode":13,"unitcode":2,"on":1}'
    payload_off: '{"systemcode":13,"unitcode":2,"off":1}'
    availability_topic: "rf434/state"
  - platform: mqtt
    name: "elro800_13_C"
    command_topic: "rf434/send/elro_800_switch"
    payload_on: '{"systemcode":13,"unitcode":4,"on":1}'
    payload_off: '{"systemcode":13,"unitcode":4,"off":1}'
    availability_topic: "rf434/state"
  - platform: mqtt
    name: "elro800_13_D"
    command_topic: "rf434/send/elro_800_switch"
    payload_on: '{"systemcode":13,"unitcode":8,"on":1}'
    payload_off: '{"systemcode":13,"unitcode":8,"off":1}'
    availability_topic: "rf434/state"

Quigg GT9000 based RC socket switches, e.g., Tevion GT-9000, SilverCrest 91210 or Intertek Unitec 48110:

switch:
  - platform: mqtt
    name: "gt9000_590715_0"
    command_topic: "rf434/send/quigg_gt9000"
    payload_on: '{"id":590715,"unit":0,"on":1}'
    payload_off: '{"id":590715,"unit":0,"off":1}'
    availability_topic: "rf434/state"
  - platform: mqtt
    name: "gt9000_590715_2"
    command_topic: "rf434/send/quigg_gt9000"
    payload_on: '{"id":590715,"unit":2,"on":1}'
    payload_off: '{"id":590715,"unit":2,"off":1}'
    availability_topic: "rf434/state"
  - platform: mqtt
    name: "gt9000_590715_3"
    command_topic: "rf434/send/quigg_gt9000"
    payload_on: '{"id":590715,"unit":3,"on":1}'
    payload_off: '{"id":590715,"unit":3,"off":1}'
    availability_topic: "rf434/state"

OTA Update

Updates of the MQTT433gateway can be preformed by OTA (Over-the-air programming) via the web frontend. To do this, you need the binary file that can be found under releases or, if you build with PlatformIO, at <BUILD_DIR>/firmware.bin, e.g. .pio/build/esp12e/firmware.bin.

Debugging/RF-protocol analyzing

The MQTT433gateway has a powerful logging system based on ArduinoSimpleLogging. Messages for different log levels can be logged to serial interface, websocket (web frontend) and syslog server. The configuration can be done via web frontend. The log messages could be very helpful for debugging. In addition, RF-protocol analyzing can be enabled with the protocolRaw debug flag.

Protocol limitation

If you have the situation that there is a lot of noise in the air and/or your device matches multiple protocols, you can limit the available protocols. This is easily possible with via the web frontend.

Development

The software is using the PlatformIO ecosystem. See their install instructions or get their IDE to get the software. More information can be found in their documentation.

1. Open a terminal and go to the MQTT433Gateway project folder.

2. After that, decide for which board to create the firmware and give this as --environment to the platformio run command:

   $ platformio run --environment <board>
   

   The available boards are defined in platformio.ini. Currently, this are

   • esp12e for ESP8266-12e/f models,
   • esp12e_160 for ESP8266-12e/f models with cpu clock set to 160MHz,
   • nodemcu for NodeMCU 0.9 boards,
   • nodemcuv2 for NodeMCU 1.0 boards,
   • d1_minifor D1 Mini boards,
   • huzzah for the Huzzah boards.

3. To flash the firmware to the board, connect the board to the PC via USB or a serial adapter. Make sure, it is the only device currently connected, as otherwise you might flash the wrong unit accidentally. Some boards need to be set manually into a programming mode, please check the manual of the board to get more details about how to do that. The platformio run has the upload target to initialize flashing:

   $ platformio run --environment <board> --target upload
   

   this will try to autodetect the serial port. If this is not successful, try

   $ platformio run --environment <board> --target upload --upload-port <path-to-serial-port>
   

Older versions of MQTT433gateway were developed with the Arduino IDE. You can find the old sources in the departed arduino branch.

Contributions

If you find any bug, please feel free to fill an issue. Also, pull request are welcome. More information can be found in the contributing guide.

Acknowledgement

Big thanks goes to the pilight community, which implemented all the 434MHz protocols. If you want to integrate more protocols, please contribute directly to pilight.

Many thanks goes to @janLo, who developed the web configuration interface.