Integrate Bluetooth devices into OpenHAB 3 thanks to OpenMQTTGateway without file configuration

This tutorial will show how to integrate the BLE gateway to OpenHAB3 leveraging the auto discovery functionnality. After this tutorial, you should see your Bluetooth Low Energy devices compatible with OpenMQTTGateway in OpenHAB3 without any file-based manual configuration.

Note that this tutorial is also available into OpenMQTTGateway documentation


  • OpenHAB 3.3 or higher
  • MQTT broker installed with or without authentication
  • A location defined in the “Model” section under “Settings”
  • ESP32

IP address (if your broker is installed on the same server as OpenHAB)

The goal is to disable the IPv6 address of the broker server, so that the gateway can connect through IPv4.

  1. From the Administration click on Settings
  2. Click on Network Settings
  3. Click on Show Advanced
  4. Disable IPv6
  5. Click on Save


If the broker is installed on another server you will also need to configure it with an IPv4 address.

Install the MQTT binding

  1. From the Administration click on Settings
  2. Click on Bindings
  3. Install the MQTT binding (you can search at the bottom right)

  1. Once installed click on Things under Settings
  2. Click on the + at the bottom right
  3. Click on MQTT Binding

  1. Click on MQTT broker

  1. Enter for the “Broker Hostname/IP” field, the IP address of your broker, if it is installed on the same server you can enter localhost

  1. Click on “Show Advanced” if your broker has authentication activated, if not you can go to step 11
  2. Enter the broker credentials: username and password

  1. Click on Create Thing at the bottom, you should see your MQTT Broker in the Things list with the status “online”

Bravo👏, second step done! Now let’s add the Jinja transformation service.

Install Jinja Transformation

  1. From the Administration, click on Settings
  2. Click on Bindings
  3. Install Jinja Transformation (you can search at the bottom right)

Second step done!

Upload OpenMQTTGateway to an ESP32

Upload OpenMQTTGateway from the web by selecting esp32dev-ble-openhab

Or use another upload method from the Upload section.

Configure OpenMQTTGateway from the web portal

Wifi and MQTT configuration

Or use another upload method from the Upload section that requires credentials before the build.

You should see the gateway connected to your broker by checking with an MQTT client like MQTT Explorer.

Adding the things

  1. From the Administration click on “Things” under “Settings”, you should see a number in the INBOX button

  1. Click on INBOX, you should see your BLE devices and the gateway

  1. Click on a device, a pop up “Add as Thing” should appear
  2. Rename it if you need, and click OK, repeat for each Thing discovered. The devices should appears as online progressively.

  1. Click on Model
  2. Select the location of where you want to create the Equipment
  3. Click on “Create Equipment from Thing”
  4. Click on Thing
  5. Select a Thing
  6. Rename your Equipment if you need
  7. Select the Channels

  1. Click on “Add to Model”
  2. Go to Model, if you unfold your location and Equipment you should be able to see values

Congratulation🎉! You were able to get data from your BLE sensors into OpenHAB. You can now add the others and use the data to build pages, leverage rules, and enjoy all the function of your Home Automation controller with BLE devices.


Under “Prerequisites”, you might want to add that you need an ESP32 and micro to USB plug.

I purchased three ESP32s from Amazon and plug in the micro to USB into my computer and go to the website above. I picked the ESP32dev-ble-openhab and clicked “INSTALL”. I now get an error message that says “No compatible devices found.”

I tired all three ESP32s in case one was bad and I got the same error each time.

1 Like

I found the issue. I had to update my CP2102 USB to UART Bridge Controller driver (found under Device Manager, Other Devices).

I downloaded the driver from here and installed.

Thanks, added

1 Like

This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.