Install and setup OpenHAB 2.0 with Mosquitto and ESPEasy+HC-SR04

This information was rather difficult for me to locate so I thought I would do a favor for the next newbie. There are no step by step tutorials on this subject so I will be setting one up on this post below.

I will be working though the setup this week. If anyone else would like follow along please let me know.



It would be great if you could make a tutorial for how to install OH2 on RPI(linux).

I would like to make a shell script which get all the packages needed and so on. In OH2 is the user still OpenHab? This is important to know for GPIO and usb dongles as the user need the right to access them. Just got a new SD card for my demoPi, so now I finally can start doing some work again.

I believe there is already some work going on to make an apt-get package for OH2.

See here to track progress.

Unfortunately I don’t have a Pi. I’ll be setting up OH2.0 on Windows 7 and using ESPEasy on my ESP12E

I’ll provide setup tutorial on this setup

So I finally completed setting up my ESP12E with OpenHAB. I started with 1.8.1 and realized that 2.0 was released to devs. 2.0 has been in testing far awhile so I decided to learn OpenHAB 2.0 instead. I did not find everything in one spot so my knowledge has been “pieced” together to help me build a working solution. Some of what I learned was educated guesses so I invite the senior members for feedback on my post. Below is a high level list of what I will be posting. My strategy here is to take baby steps and get pieces of the architecture working before trying to integrate the next layer. I hope this helps someone who enjoys learning as much as I do!

  1. Setting up your ESP8266 with ESPEasy

  2. Installing OpenHAB 2.0 on Windows 7

  3. Installing MQTT (I’ll be using Mosquitto)

  4. Testing MQTT in prep for integration with OH 2.0…The MQTT broker will run on my Mac Mini.

  5. Configuring ESPEasy with a HC-SR04

  6. Configuring OpenHAB for MQTT Broker

  7. Editing demo.items and demo.sitemap

  8. Impressing your peers! :slightly_smiling:

Setting up your ESP8266 with ESPEasy

This step is pretty easy if you just read the pages starting at

Follow along at each link on the bottom of the page to configure the ESP for your wireless network

I have the ESP12E Dev Board and it is great for doing testing and setting up different sensors. It has onboard usb to serial and can be programmed and powered via the usb connection. The board also has two LEDs so that you can immediately start learning how to control devices via GPIO. I did not know how to do it until I found ESPEasy. A great manual for the ESP8266 can be found here:

Its free but its worth paying Kolban for his work. Its pretty much a ESP8266 bible!!!

The ESPEasy devs have created a flash tool and a stable image that works very well. The download of the image includes the flash tool and several bin (images) files for the different ESP hardware models

Below is the input (in bold) and the some of the output after running the flash command.

Comport (example 3, 4, …) :8
Flash Size (example 512, 1024, 4096) :4096
Build (example 71, 72, …) :78
Using com port: 8
Using bin file: ESPEasy_RIng_4096.bin
esptool v0.4.6 - © 2014 Ch. Klippel
setting board to nodemcu
setting baudrate from 115200 to 115200
setting port from COM1 to COM8
setting address from 0x00000000 to 0x00000000
stat ESPEasy_R78_4096.bin success

There is also an option to compile the arduino code and load the code from an Arduino Uno. See the ESPEasy website for instructions on how to do this.

Once you have the image flashed and configured. Setup the ESP to join your wireless network as a client access point (WIFI_STA for ESPEasy)

In the top menu of the ESP web page click on Tools then Logs to make sure the ESP has a wifi connection. Dont worry about the errors on failing to find a mqtt broker

Installing OpenHAB 2.0 on Windows 7

To install OP 2.0 its best if you read the follow file

This is an important read this since things have changed significantly from 1.8.1. Things have been broken up from the single openhab.cfg file into separate cfg files for the difference addons and services. Here are the steps to install the software.

  • Install the offline distro located at the bottom of this page or on the getting started page.

I created an openhab2.0 directory and copied the files into this directory - C:\openhab2.0

  • Choose the standard package to be installed once openhab is started. This is done by uncommenting the “package = standard” line in the C:\openhab2.0\conf\addon.cfg file.

  • Run start.bat from C:\openhab2.0 in a cmd window. The following should be displayed.

My setup complains with a WARNING server mode not available but its not affecting anything that I know of. There are tons of commands in this shell…At this time I have not found a quick reference guide. One is desperately needed…

  • With the OH2.0 running open your browser and enter:

http://“your ip address”:8080

You should get the following page:

Installing MQTT (I’ll be using Mosquitto)

Installing MQTT on Windows is pretty straight forward. The installer will place all of the files for the complete Mosquito MQTT architecture in your C:\Program Files (x86) directory.

There will be three .exe files that you will be working with:

  • mosquitto.exe - a.k.a MQTT server or “the broker”.
  • mosquitto_sub.exe, - MQTT client…that says to the broker "Hello! send me everything you receive from publishers with “this topic”. I’ll explain “this topic” later.
  • mosquitto_pub.exe - MQTT client (yes there are two types)…that says to the broker "Hello! here is some info for “this topic” to send to your subscribers!

Each of the clients are also “pinging” the broker to let him know they are still there. There is also a “Last Will and Testimony” (LWT) that can be setup so that the broker knows how to respond when the client dies. I hope to learn more about this but I thought it was worth mentioning here. MQTT seems to be a really powerful message bus architecture. Check out and click on the Documentation.

Next I will be setting up the broker and two clients (pub and sub) on my laptop

Testing MQTT in prep for integration with OH 2.0

First we need to get the MQTT broker running. I will be setting the broker up so that you can see the log interaction the broker has with the clients. Its pretty cool! I am just doing a basic setup too…I think there are more options available. As I learn more I will add to this post.

Find the mosquitto.conf file and pull it into your favorite editor. The following lines need to be uncommented and you need to add the IP address where the broker service will be running. Its best to start with ‘localhost’ so that you dont need to change it every time you change networks. Also feel free to use a different port number if you feel the need…just remember what it is since 1883 is the default for most MQTT configs.

'#bind_address localhost

'#port 1883

Below is a screenshoot of my mosquitto.conf

Now lets startup the broker with the -v option so that it will tell us what its doing and who its talking to - the publisher(pub) or subscriber(sub)

We are going to have several cmd windows so its best to title them to keep things organized on your screen. From a Windows command prompt enter “Title MQTT BROKER” this will change the title of the cmd window.

Next enter the following command and parameters:

mosquitto -c “c:\Program Files (x86)\mosquitto\mosquitto.conf” -v below is what your cmd session should look like. The -c specifies the conf file your edited in the beginning of this step. If you dont use -c the broker will use its default settings.(“mosquitto --help” with display all of the options)

Next we will setup the subscriber to the MQTT broker. This is done by running mosquitto_sub.exe command. Enter the commands I have listed in the screenshot below:

You should see the following response in the MQTT BROKER window:

The broker and the sub will continue to “handshake” via PINGREQ and PINGRESP. I have not tried any other settings but I think there are configuration options to do much more and adjust the handshaking.

Notice the “-t” option in the SUBSCRIBER window. This sets the topic for the subscription request to the broker. Its basically a unique identifier for message exchange between the broker and the sub. In my example I am setting a specific topic called “/MarksESP8266/Bassfishing” so any data sent to the broker with this topic will in turn be sent to the sub client session (or any other subscriber to the same topic)…now we need a publisher!

Next we will setup the publisher to the MQTT broker. This is done by running mosquitto_pub.exe command. Enter the commands I have listed in the screenshot below:

You should get a return to command prompt since the client is sending data rather then waiting on it. Now take a look at the MQTT BROKER window.

There should be an entry in the logging starting with “Received PUBLISH from…” and “Sending PUBLISH to…” back to back. Along with some other diagnostic info that I still need to understand. But should also see the “topic” for the message exchange in both entries - /MarksESP8266/Bassfishing. Finally the end of each line has the size in bytes of the data being sent.

Now take a look at the SUBSCRIBER window…

You should see the topic and the data you sent…“2 fish caught” (there are two entries in my screenshot because I issued the sub command twice.

Pretty cool ugh! For fun start up another sub command line window with the same topic and you will see both of them receive the publishers data. This example only scratches the surface of MQTT architecture. I recommend visiting and reading through the documentation thoroughly.

1 Like

That’s awesome, thank you. Since I’m interested setting up quite the same setup I’ll follow your posts for sure.
Keep up the good work and thank’s for sharing.

Hi MarkIngle,

at your post: ‘Testing MQTT…’ after configuring mosquitto you wrote: “Now lets startup the broker with the -v option…” is the first part isn’t quite clear for me and from this on… the command and parameters given never made it through the command prompt, and the line given in the post differs from the one on the screenshot compared.

post: "mosquitto -c “c:\Program Files (x86)\mosquitto\mosquitto.conf -v”
scrshot: C:\Program Files (x86)\mosquitto -c “c:\program files (x86)\mosquitto\mosquitto.conf” -v

My cmd prompt begins like: C:\Users\xxx> and I get error messages like the system can’t recognise it as a command or path. (Yes, the path for mosquitto is the same as yours on my PC too.)

Could you clarify it for a noob like me?

Thanks in advance.

Sure. Let me take a look at it. I am building the instructions as I have
time so its easy to get out of sync.

So this is the command (bold below). And at the very top, in the screenshot with MQTT BROKER title:

C:\Program Files (x86)\mosquitto>mosquitto -c “c:\Program Files (x86)\mosquitto\mosquitto.conf” -v

Can you share a copy of the entire command and the directory from which you are trying to run it? Unless you have included the mosquitto directory in your PATH environment variable, you will need to be in the mosquitto directory when you issue the command…hope this makes sense.


Absolutely makes sense, it’s just me not knowing how to get there, as I open a command prompt it starts at C:\Users\xxx>

I think I got it… :confused:

I’ve found this:

I wasn’t aware I have to reinstall mosquitto after adding the required dll.s.

Now it’s done and obviously mosquitto.exe leads me where I wanted to be…

Nope, I can’t write anything there…

email me at if you need my help

Thanks, now it’s fine. Had some issues with the ipv4 listen socket, got some unknown errors, but a complete reinstall solved the problem.

Please keep up the good work, I guess there are other noobs out there like me who need such lead at the beginning at least.

1 Like

Configuring ESPEasy with a HC-SR04

In order to configure the HC-SR04 you need a working ESP8266dev board loaded with the ESPEasy version 78 firmware. After the initial configuration of the firmware you should see the device listed in the available wifi networks

My device is call ESP_123…I think a new device that has not been configured will be ESP or ESPEasy. The password for connecting to the ESP is “configesp”

After connecting to the ESP at the default address of you should see the following web page with welcome message and the name of your device at the top:

Your ESP should be configured to connect to your wifi network. Click on Config and enter the SSID and Password for your wifi network. Leave the WPA AP Mode Key password as it is.

Click on the Submit button on the bottom. Also set the Sensor Delay to something less than 10 so that you do not have to wait for a reading on the log.

You can look on your wireless access point for the IP address assigned to the ESP or you can connect to an Arduino and click on the serial monitor to see the IP address assigned. I use my Arduino.

Now join back to your wifi network and enter the new IP address in your browser.

Click on Devices at the top menu. Click in the first Edit button.

Click on the drop down list to display a list of available device for ESPEasy. Select the HC-SR04 device.

For Name, give the device a unique name of your choosing. My Device name is “MarksHCSR”

Enter a unique number for the IDX/Var. This number should unique to any other device per the MQTT Broker in use.

The 1st GPIO should be GPIO-13 for hardware pin D7 on the ESP8266Dev board. 2nd GPIO should be GPIO-14 for hardware pin D5.

For the “Mode” parameter select Value if you want to receive a distance measurement fof an object in front of the HC-SR04. Select State if you just want to know an object is in front of the HC-SR04. Setting Mode to Value will cause the actual distance to the object to be displayed. Setting the Mode to State will cause a 1 or 0 to be displayed.

The Value Name 1 is just a custom label. This can be anything you want. I labeled mine “Distance”.

I will stop here and take a minute to cover the MQTT topic that will be used. There are three pieces of data entered in the configuration setup that will be used to create the unique topic for each device configured in the firmware. This will be the topic used when the HC-SR04 data is published to the MQTT Broker. The following values will be used based on your setup:

The ESP8266 device name - MarksESP8266
The “Device” name - This is the sensor input/output device you are setting up for control or monitoring. My sensor device name is MarksHCSR
The “Value Name 1:” - This is the unique label you assign to the data coming from your device (sensor). My label is Distance

So for my setup the publish topic identifier is /MarksESP8266/MarksHCSR/Distance

1 Like

Configuring OpenHAB with MQTT Broker

First make sure the OpenHAB application is running and that you can access the setup wizard page:


Just to recap, in the openhab2.0 directory, run startup.bat from the command line and enter youripaddress:8080 in your browser. The following web page should appear:

Click on Extensions:

Scroll down until you see “MQTT Binding” and click on the “Install” button. (My MQTT Bind is already installed in the picture)

Next edit the mqtt.cfg file located in the C:\openhab2.0\conf\services directory and add the IP address of the host where the MQTT BROKER will be running. Remove the hash at the beginning to uncomment the line:


You also need to uncomment the line for the clientID. This will help you track the message exchange with the mqtt broker and the openhab mqtt subscriber.

Now we need to get OpenHAB configured to run mqtt subscriber. In order to do this we need to install an OpenHAB tool called Eclipse SmartHome Designer. The 64-bit Windows version can be downloaded from here:

Other versions are available here:

After installing Eclipse SmartHome Designer (ESD) run SmartHome-Designer.exe. The tool should look like the following:

Click on Sitemaps. Double click on demo.sitemap. Add the line indicated by the red arrow:

Group item=HCSR icon=“temperature”

This entry will give you an item in the group section at the top of the main menu for the OpenHAB2.0 demo

Click on Items. Double click on demo.items. Add the following line as indicated by the red arrow:

Group HCSR “Motion Sensor” < temperature > ***NOTE: No spaces before and after temperature

Find the section label Lights and add the line highlighted by the red arrow:

Here is a line for you to copy/paste into your demo.items files and edit with your ESP settings:

Number HCSR04 “HC-SR04 Distance [%.1f cm]” < slider > (HCSR) {mqtt="<[mosquitto:/MarksESP8266/MarksHCSR/Distance:state:default]"}

***NOTE: Remove the spaces before and after the word “slider”

Next add an entry to the demo.sitemap file so that the reading from the HCSR04 shows up on the webpage dynamically.

In the first “Frame” section at the following line to create a group item:

Group item=HCSR icon=“temperature”

Im using the temperature icon until I can determine how to replace it with something else.

Now you are ready to start testing the communications between OpenHAB, MQTT BROKER, SUB client and the PUB client.

(For some reason I could not get the MQTT BROKER on my Windows OS to communicate with any of the my SUB/PUB clients so I moved the broker to my Mac Mini. It works fine with the MQTT BROKER running on the Mac!)

Start the MQTT BROKER on the host with the IP address you entered in the mqtt.cfg for openhab. Its always a good idea to do a ping test to make sure you can reach the host…otherwise you are wasting time.

Next restart the OpenHAB application by entering “logout” at the openhab2.0 command prompt. Then enter startup.bat. You should see something similar to the screenshot below

There should be several entries of communication from the OpenHAB client subscriber with the clientID you entered in the mutt.cfg file.

Before we setup the HC-SR04 lets make sure that the MQTT software architecture is working. We can do this by setting up a sub and pub client on a separate host. In the MQTT setup above we configured everything on the same host. Hopefully these steps are helping build an understand of MQTT.

Open a Windows command prompt and enter the following command…see picture for command syntax:

This sets up a subscriber for our test.

Now open another Windows command prompt and enter the following command…

This will publish the number 324 to any client subscribing to /MarksESP8266/HCSR04/Distance.

Take a look at the log entries on the MQTT BROKER host (-v displays the activity - verbose mode). you can see the sub client notifying the broker of the topic its subscribing to and the pub client publishing 3 bytes to the same topic

The topic id and the number 324 should now show in the SUBSCRIBE command window.

Now that we have confirmed that the MQTT architecture is working lets setup the HCSR04 sensor in OpenHAB20 to send an email when something passes in front of it.


Hi. Thanks for the great article. You have your SR04 connected to the 3.3V pin on the ESP826-12E but the spec’s I read say the SR04 needs 5V? Can you confirm it worked on 3.3V? Also, do you need to set the trigger GPIO pin to high to get it to work? I’m getting no measurement data with trigger connected to D5 and echo connected to D7.