Flatten the learning curve

Hello everyone,

I am totally new to the DIY home automation community. Nevertheless, I quickly came across OMG. While reading through the documentation I got a brief understanding of how everything works and already set up my own ESP32-Gateway which is now happily broadcasting some messages to my HiveMQ-Instance. Quick feedback: I love it! - And I am really looking forward to get deeper into the topic.

Nevertheless, I found it hard to understand the overall architecture and concepts behind OMG just by reading the documentation.
For me, the following things are missing

  • A general overview of the system architecture, explaining the components and core concepts behind the system ( I do like the Prerequisites section but I think it still takes too much knowledge for granted)
  • An explanation of the flow of data (how is OMG reading messages from BLE(&others) devices, how are they decoded and transformed
  • A section of further topics like; writing your own decoder, message deduplication or examples and reasons on how and why I should compile my own ESP32 binary

I would love to hear your opinions or even places of documentation I am missing so far.



Hi @twinbrother,

Welcome, and happy to hear that you enjoy using OpenMQTTGaetway so much as well.

Let me answer the parts of your questions which I know most about …

I’m starting with this, as using the OpenMQTTGateway source with Platformio helped me a lot in understanding more about its workings and the various customisation options available when I first encountered OMG.

While initially it might sound daunting, installing and using the tools to work on the source code and create your own builds with it, it’s just a quick download and install routine really, nicely documented at

After VSC ihas been downloaded and the Platformio extension installed, all that is needed is to download the OpenMQTTGateway source from GitHub

unzip it and open its directory in VSC.

What are the advantages of being able to create your own environment builds like that? For me it’s
• being able to combine different gateways together in one build, e.g. IR and RF
• being able to highly customise all the different define options for all the different gateway setups, defined in all the conf_xx.h files. As an example this is the configuration file for the BT gateway

• Among my other favourite custom defines is the possibility to manually set the WiFi and MQTT broker credentials for all the gateways, to avoid the WiFiManager setup for each.
• Being able to do Over The Air WiFi updates to all gateways. So whenever a new version of OMG is released I don’t need to run around the house, collecting all the gateways for a physical connection to update them, but I just send out the update to all of them over WiFi.

For BLE OpenMQTTGateway uses the Theengs Decoder library, which has its own documentation at

The documentation also includes an extensive section on how to create your own decoder for new devices for submission into Theengs Decoder for integration into future releases.

For RF, RTL_433, IR and the other decoders/libraries, generally a submission to the included library (defined in the library section of the Platformio.ini file) is the way to go forward for adding devices there.

As you can see on the above page, the BLE info is outdated, so I have already submitted a pull request with changed up-to-date information about Theengs Decoder.

Anyone and everyone if very welcome to join in in changing, correcting and extending the documentation, source code and decoders.

I hope the above helped a bit in understanding more about the workings of OpenMQTTGateway and others might chip in with more information on other parts.

Also the forum here is a great source for a lot of questions which have been asked and answered in the past, admittedly not always summarised and consolidated in the best and easiest to find way :wink: So maybe you want to join in and possibly add to the documentation while finding out more - in a way that you think can benefit other new users.