Overview
This tutorial follows the setup and installation of a Sonoff Basic. However, many Tasmota flashed devices have an on/off capability, so this tutorial is relevant for other Tasmota flashed devices.
A Sonoff Basic is a simple mains relay, which can be flashed with Tasmota firmware and controlled from openHAB using the the MQTT binding. You can splice the Basic into anything mains powered (check the power rating first!) that you wish to switch on or off.
Ingredients
You will need:
1. Sonoff Basic flashed with Tasmota
Configuration is described below. I bought my Basics from here, and I used this USB programmer.
There are lots of tutorials on how to flash the Basic. Consult the Tasmota documentation to start.
Click to see my notes on flashing Tasmota
I flash the device using esptool.py. There are a number of options available, with Tasmotizer probably the most user friendly. If you have a Tuya device, flashing is even easier and you can ignore the rest of this step.
-
Get device into programming mode
a. Disconnect USB programmer from PC
b. Connect all cables to USB programmer and device
c. Short IO0 to GND
d. Connect USB programmer to PC
e. Wait a few seconds, then disconnect IO0 from GND -
Flash device
a. Erase, then flash.
sudo esptool.py -p /dev/ttyUSB0 erase_flash
sudo esptool.py -p /dev/ttyUSB0 write_flash -fs 1MB -fm dout 0x0 /home/mypc/Downloads/tasmota.bin`
2. openHAB with MQTT binding
- Navigate to PaperUI, usually at http://<openhab-ip-address>:8080/paperui/
- Go to Add-ons -> Bindings -> MQTT Binding and click Install
3. MQTT broker
Install Mosquitto. Don’t use openHAB’s built-in broker. Install Mosquitto.
Click to see my installation notes
On many distributions, Mosquitto is available from the standard repositories, so something as simple as the following might work.
sudo apt install mosquitto
Mosquitto will be installed as a service, which means it will start automatically and just continue running in the background. If you restart your device, Mosquitto will also restart.
There is usually no need to change the default configuration.
Click here if you don't think Mosquitto is working
To check if it’s running, just type the following into a terminal:
sudo systemctl status mosquitto
If all is running well, you should get something like the following:
mosquitto.service - LSB: mosquitto MQTT v3.1 message broker
Loaded: loaded (/etc/init.d/mosquitto; generated; vendor preset: enabled)
Active: active (running) since Wed 2020-07-15 22:28:39 BST; 1 months 9 days ago
Docs: man:systemd-sysv-generator(8)
Process: 370 ExecStart=/etc/init.d/mosquitto start (code=exited, status=0/SUCCESS)
Tasks: 1 (limit: 4915)
CGroup: /system.slice/mosquitto.service
└─457 /usr/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf
Jul 15 22:28:38 raspberrypi systemd[1]: Starting LSB: mosquitto MQTT v3.1 message broker...
Jul 15 22:28:39 raspberrypi mosquitto[370]: Starting network daemon:: mosquitto.
Jul 15 22:28:39 raspberrypi systemd[1]: Started LSB: mosquitto MQTT v3.1 message broker.
If you don’t, a common issue is that something else is already using the standard MQTT port of 1883. Perhaps you have previously installed another MQTT broker (maybe the one that comes with openHAB)? Either way, whatever it is, must be stopped before mosquitto can run!
Method
We’ll split the method into two: configuration of the Tasmota flashed Sonoff Basic, and configuration of openHAB.
1. Configure Tasmota
You will already have connected your Sonoff Basic to your WiFi network.
a. Configure module
In a browser:
- Navigate to your Tasmota device’s configuration page: http://<tasmota-ip-address>/md
- Change the Module type to Sonoff Basic (1).
- Click Save. The device will re-start, and kick you back to the Main Menu.
The Main Menu will now have a button called Toggle. Click this, and your Sonoff Basic will switch ON and OFF!
b. Configure MQTT
In a browser:
- Navigate to your Tasmota device’s MQTT configuration page: http://<tasmota-ip-address>/mq
- In Host, enter the IP address of the device which is running Mosquitto.
- In User, enter a unique name for this device.
- In Topic, enter the same name as you did for User.
- Leaving everything else as it is.
- Click Save. The device will re-start, and kick you back to the Main Menu.
2. Configure openHAB
openHAB can be configured via PaperUI, or via files. The method below uses files, as it is far easier to share textual configurations than screenshots of a user interface - just copy, paste and save!
Files are saved in specific folders within your openHAB Site configuration folder. Find where yours might be for Linux or Windows installations by checking the tables.
a. Things
We will create two Things files. The first will point to Mosquitto, connecting openHAB and Mosquitto together. The second will point to the Sonoff Basic, via Mosquitto, connecting openHAB to the Sonoff Basic.
i. mqttbridge.things
Create an empty text file called mqttbridge.things
inside the things folder in the openHAB Site configuration folder. Make sure the file ends with .things
, and not .txt
or something similar. openHAB keeps a continuous watch on these folders, and will read any files with the correct filetype!
Inside mqttbridge.things
copy and paste the following, and save:
Bridge mqtt:broker:MosquittoMqttBroker "Mosquitto MQTT Broker" [
host="192.168.1.92",
secure=false,
port=1883,
clientID="OpenHAB2",
username="",
password=""
]
Change the IP address for that of the device which is running Mosquitto. If you configured a username and password, add those details too. For a full list of options when it comes to configuring an MQTT bridge, check the documentation.
ii. mqttdevices.things
Create an empty text file called mqttdevices.things
inside the things folder in the openHAB Site configuration folder. Copy and paste the following into that file, and save:
Thing mqtt:topic:swBedroomSideLight "Switch Bedroom Side Light" (mqtt:broker:MosquittoMqttBroker) {
Channels:
Type switch : power "Power Switch" [
commandTopic="cmnd/swBedroomSideLight/POWER",
stateTopic="stat/swBedroomSideLight/POWER",
on="ON",
off="OFF"
]
}
Click here for a wordy explanation of the above configuration
First, we define the Thing
-
Thing mqtt:topic:swBedroomSideLight
- We have created a Thing…
- …using the
mqtt
binding… - …this Thing is a
topic
type (as opposed to thebridge
type created earlier to connect (‘bridge’) to Mosquitto) - …this Thing is called
swBedroomSideLight
. I have given it the same name as that configured in the Tasmota MQTT configuration, although it doesn’t have to be - it just has to be unique to openHAB.
-
"Switch Bedroom Side Light"
- This is a friendly label for the Thing, useful sometimes when using PaperUI.
-
(mqtt:broker:MosquittoMqttBroker)
- This defines our Thing as something which connects through our MQTT bridge to Mosquitto.
Then, we define its Channel
-
Type switch : power "Power Switch"
- We have created a
switch
type Channel (other channels are available)… - …which openHAB now calls the
power
Channel. This is a unique name that you give to the Channel, and must not be repeated for any other Channel in the same Thing… - …and has the friendly description of
"Power Switch"
.
- We have created a
Then, we configure the Channel
-
commandTopic="cmnd/swBedroomSideLight/POWER"
- This is the topic that openHAB will send a message to when the Channel receives an ON or OFF command from openHAB.
- Note that this is standard syntax for a default Tasmota:
-
cmnd
- All commands to the device are sent to thecmnd
topic. -
swBedroomSideLight
- We want the command to be routed to our device. Specifically, we want the command to be routed to the exact name that we specified in Topic during Tasmota MQTT configuration, which wasswBedroomSideLight
. -
POWER
- This is the command or function that will be run on theswBedroomSideLight
device itself.
-
-
stateTopic="stat/swBedroomSideLight/POWER"
- Very similar to the
commandTopic
, but this time we’re setting openHAB up to listen on this specific topic, because Tasmota will send messages on this specific topic any time thePOWER
command is run on the device.
- Very similar to the
-
on="ON", off="OFF"
- Because this is a
switch
type Channel, we can sendon
oroff
values to thecommandTopic
. In this bit, we’re saying:- When sending an
on
message, send the wordON
. - When sending an
off
message, send the wordOFF
.
- When sending an
- So now our Tasmota device will receive either the word ON or OFF to the POWER command, which is what it would expect.
- Additionally, this bit of the configuration also works in the other direction: whatever comes through the
stateTopic
is also sent through this transformation, but in reverse. So if an “ON” message is sent from the Tasmota device on thestat/swBedroomSideLight/POWER
topic, openHAB will correctly interpret that ason
.
- Because this is a
b. Item
After definining a Thing, which is a link to a physical object, we now define an Item, which openHAB can use in rules and sitemaps, and which connects to a Thing Channel.
Create an empty text file called mqtt.items
inside the items folder in the openHAB Site configuration folder. Copy and paste the following into that file, and save:
Switch sBedroomSideLight "Bedroom Side Light" { channel="mqtt:topic:swBedroomSideLight:power" }
Click here for an explanation of the above configuration
- We have created a
Switch
type Item… - …with the name of
sBedroomSideLight
. This name is unique - no other Item may be called the same… - …with a friendly label
"Bedroom Side Light"
… - …and it is connected to the
power
channel of theswBedroomSideLight
MQTT Thing.
c. Sitemap
The Sitemap is your personal, configurable user interface. You can access the user interface through http://<openhab-ip-address>:8080/basicui/ or via mobile applications, but configuration is via files only.
Create an empty text file called myHome.sitemap
inside the sitemaps folder in the openHAB Site configuration folder. Copy and paste the following into that file, and save:
sitemap myHome label="My Home" {
Switch item=sBedroomSideLight label="Bedroom Side Light"
}
Click here for an explanation of the above configuration
-
sitemap myHome label="myHome"
- We’ve created a
sitemap
… - …which openHAB knows as
myHome
. Note that the name of the file and the name of the sitemap (this name) must be the same… - …which has a friendly label
My Home
.
- We’ve created a
-
Switch item=sBedroomSideLight label="Bedroom Side Light"
- The sitemap includes a
Switch
widget… - …which is connected to the
sBedroomSideLight
Item… - …and has a friendly label
"Bedroom Side Light"
. In fact, we could leavelabel="Bedroom Side Light"
out of this configuration completely, and openHAB will use the friendly label of the Item itself when displaying on a user interface.
- The sitemap includes a
Which will give you something which looks like this in BasicUI:
You now have working switch which you can toggle on and off!
Summary
We’ve now:
- Setup an MQTT broker.
- Configured a Tasmota device to talk to and receive messages through the MQTT broker.
- Configured openHAB to talk to and receive messages through the MQTT broker.
- Subscribed openHAB to the POWER command and state topics of our Tasmota device, via the
power
Channel of our Thing. - Connected a Switch Item to the
power
Channel. - Displayed the Switch Item via a Sitemap.
Everything is connected: the Sitemap Switch connects to the Switch Item, which connects to the Thing Channel, which is bridged to the MQTT broker and subscribed to the topics defined by the Tasmota device.
Common issues
- Everything to do with MQTT, and openHAB, is case sensitive.
sBedroomSideLight
is not the same assbedroomsidelight
. Be especially careful with MQTT topics! - The names of the Things and Items files can be anything you want. However, the name of the Sitemap file must match the name of the sitemap itself (the word after
Sitemap
in the file itself). - The filetypes (end of the filename) are important.
-
.things
for Things files. -
.items
for Items files. -
.sitemap
for Sitemap files. Note that there is nos
(or plural) at the end of this one, as each file only has the configuration for a single Sitemap.
-
- Mind your brackets (), curly brackets {}, square brackets [] and commas, especially in the Thing configuration.