Tutorial OpenHAB Switch

From Let's Control It
Jump to: navigation, search


Information on this page is based on preliminary development. Beware that functionality may be incomplete, not fully tested and subject to change. It may even be removed in future releases if it turns out be unstable or based on erroneous interpretation of the operation of third-party technology. At this stage, we provide the information to support development and testing.

This tutorial will guide you to connect your first ESP Easy to OpenHAB to control a digital output on the ESP (i.e. to drive a relay). We expect that you have a working OpenHAB setup, a MQTT broker running and have loaded the ESP Easy firmware onto your ESP. In our testlab, we ran OpenHab on Windows and the Mosquitto MQTT broker on a RaspberryPI (it was already there due to some earlier experiments...)

In this tutorial, we use a simple switch demonstration so you don't need a real sensor attached to your ESP. A barebone ESP-01 and a LED + resistor should be sufficient for this tutorial. It will mainly demonstrate the basis steps to connect ESP to OpenHAB by using the ESP Easy firmware.

Get MQTT working

To be able to communicate with devices like the ESP, we have to get MQTT support into OpenHAB. This step has to be done only once in your setup.

We have used the Demo on OpenHAB to develop this support and we will be using that as a start.

In case MQTT is not setup already, please change the openhab.cfg file:


We had our broker service running on, please change to your local situation.

Add the MQTT binding file

If not done already, add the MQTT binding jar to the addon folder. We added this file:


Change sitemap

You need to configure a switch device for this demo, we added the following to the demo sitemap:

Frame label="MQTT Test"{
 Switch item=MQTTLED label="LED"

Change items

And we have to configure how this device will work, in this case MQTT. Add following line to your items file:

Switch MQTTLED {mqtt=">[localbroker:/openhabdemo/gpio/2:command:ON:1],>[localbroker:/openhabdemo/gpio/2:command:OFF:0]"}

We tell openhab to use MQTT for this switch, communicate with the broker named "localbroker" and publish this to /openhabdemo/gpio/2 where "openhabdemo" is the name of the ESP module, "gpio" tells ESP what to do with the state value and "2" is the GPIO pin number that should be switched. And we tell that ON sends value 1 and OFF sends value 0.

Finally launch the OpenHAB gui and it should look like this:

Tutorial OpenHAB GUI.png

Connect the ESP Easy to your network

If you have your ESP board loaded with ESP Easy firmware, powerup the unit and an Access point named "ESP_0" should appear. Connect to this access point and browse to If all went well, the following screen should be shown:

Easy Main.png

Click the "Config" button

Tutorial OpenHAB Switch.png

Configure at least the following settings to get you started:

Protocol OpenHAB MQTT
Controller IP = your MQTT Broker IP
Controller Port = your MQTT broker server port, default should be 1883

Click the "Submit" button

Click the "Tools" button and Click "Connect"

Tutorial Easy Tools.png

Go back to "Main" and chech the status. It should have an IP address:

Tutorial Easy Connected.png

From here on, you should start using to connect to your ESP device.

Since this will be an output device, we do not have to configure any devices on the ESP.


Connect an LED or Relay board to the GPIO-2 pin on the ESP and toggle the LED button in OpenHAB webgui. The LED of Relay should respond almost immediately!