Foreword
This tutorial is for openHAB3. If you are on openHAB2 you will need to use my older tutorial.
This tutorial was written with openHAB3 running on a headless Raspberry Pi 3B with Raspberry Pi OS, with SSH access.
Overview
This tutorial assumes you have openHAB3 installed.
This tutorial will show you how to:
- Install an MQTT broker, install the MQTT binding, and connect the two
- Setup device to read the DHT22 temperature sensor
- Setup device to connect to the MQTT broker
- Configure openHAB3 to connect to the relay
- Configure openHAB3 to control the relay
- Configure openHAB3 to read temperature and humidity values
Hardware
- Sonoff Basic R2 , flashed with Tasmota
-
DHT22 temperature sensors
- Also known as AM2302.
The hardware is setup as described on this page, with the main differences being:
- I used DuPont wires.
- The DHT22 was pre-soldered to a board which already had its own resistor
Method
1. Install an MQTT broker, install the MQTT binding, and connect the two
In order to use MQTT devices, the following is required:
- An MQTT broker installed
- MQTT Binding installed in openHAB
- MQTT Bridge Thing configured in openHAB
Follow the steps in this tutorial to achieve the above three goals.
2. Setup device to read the DHT22 temperature sensor
In a browser navigate to the Tasmota Module parameters configuration page of your device, normally at:
- http://<sonoff-ip-address>/md
- device home -> Configuration -> Configure Module
I connected the DHT22 data pin to the Sonoff GPIO3 pin (Serial In). If you used a different sensor, or a different pin, make the required changes here.
Back on the device home page (http://<sonoff-ip-address>), check that the temperature and humidity are displayed (may take a little while to show real values).
3. Setup device to connect to the MQTT broker
In a browser navigate to the Tasmota MQTT parameters configuration page of your device, normally at:
- http://<sonoff-ip-address>/mq
- device home -> Configuration -> Configure MQTT
Configure the following. Leave everything else as default:
- Host: IP address of the device running the Mosquitto MQTT broker.
- Port: Only change if you have changed the default port for the Mosquitto MQTT broker.
- User: Give your device a unique name. Mine switches on a short light in the living room.
- Topic: Give your device a unique topic. I match mine to the User.
4. Configure openHAB3 to connect to the relay
To control the relay, we need to configure a Generic MQTT Thing
- Settings -> Things -> Blue + -> MQTT Binding -> Generic MQTT Thing
Enter the initial configuration information:
- Unique ID: You can leave this default, or provide a more convenient ID. Once created, the ID cannot be changed. I usually use the same name as used for the Tasmota User.
- Label: Friendly name for your device
- Location: Physical location of your device
Connect this Generic MQTT Thing to your MQTT broker via your Bridge Thing:
- Bridge -> Select Bridge Thing previously created
Configure the availability topics - this ensure that openHAB knows whether the device is online.
Click on Show advanced. For Tasmota devices, the Availability Topic is usually tele/<TOPIC>/LWT
, where <TOPIC>
is as configured in the Tasmota MQTT parameters page. Messages that are published are either Online
or Offline
.
Click Create Thing. Your Generic MQTT Thing will be created and appear in your list of Things. After a couple of seconds, it will appear as ONLINE.
YAML Code
You can view the YAML code for you Generic MQTT Thing by opening the Code tab within your Generic MQTT Thing.
The code for this example is below:
UID: mqtt:topic:MosquittoMqttBroker:swLivingRoomShort
label: Living room short light
thingTypeUID: mqtt:topic
configuration:
payloadNotAvailable: Offline
availabilityTopic: tele/swLivingRoomShortLight/LWT
payloadAvailable: Online
bridgeUID: mqtt:broker:MosquittoMqttBroker
location: Living Room
5. Configure openHAB3 to control the relay
We now need to create a Channel to control the relay. Click the Channels tab in your Generic MQTT Thing, followed by Add Channel.
Configure the Channel:
- Channel Identifier: Channel ID used internally by openHAB. No spaces allowed.
- Label: Friendly name for the Channel. Spaces allowed.
- Channel type: On/Off Switch
Continue the configuration of the Channel:
-
MQTT State Topic: If you left Full topic default in the Tasmota MQTT parameters, the State Topic will be
stat/<TOPIC>/POWER
. -
MQTT Command Topic: If you left Full topic default in the Tasmota MQTT parameters, the State Topic will be
cmnd/<TOPIC>/POWER
. -
Custom On/Open Value:
ON
-
Custom Off/Closed Value:
OFF
Click Create. The Channel will appear in the Channels tab of your Generic MQTT Thing.
YAML Code
UID: mqtt:topic:MosquittoMqttBroker:swLivingRoomShort
label: Living room short light
thingTypeUID: mqtt:topic
configuration:
payloadNotAvailable: Offline
availabilityTopic: tele/swLivingRoomShortLight/LWT
payloadAvailable: Online
bridgeUID: mqtt:broker:MosquittoMqttBroker
location: Living Room
channels:
- id: power
channelTypeUID: mqtt:switch
label: Power
description: ""
configuration:
commandTopic: cmnd/swLivingRoomShortLight/POWER
stateTopic: stat/swLivingRoomShortLight/POWER
off: OFF
on: ON
Within the Channels tab, click Add Equipment to Model.
You are now creating an Item. If you have your Model setup, choose the Parent Group. Configure the Item:
- Name: Item ID used internally by openHAB. No spaces allowed.
- Label: Friendly name for the Item. Spaces allowed.
- Category: lightbulb. This is used for the icon.
- Semantic Class: Lightbulb
Link the previously created Power
Channel to the Item by selecting it. Configure the link:
- Name: Link ID used internally by openHAB. No spaces allowed.
- Label: Friendly name for the Link. Spaces allowed.
- Type: Switch
- Category: Select the category to use for the icon.
- Semantic Class: Switch
- Semantic Property: Light
Click Add to Model. You can now control the switch from your Item.
- When you click the switch On, openHAB will send
ON
tocmnd/<TOPIC>/POWER
. - When you click the switch Off, openHAB will send
OFF
tocmnd/<TOPIC>/POWER
.
6. Configure openHAB3 to read temperature and humidity values
To read the temperature and humidity values we need to do three specific things:
- Install the JSONPath Transformation Service
- Create two new Number Channels to read the temperature and humidity values published by Tasmota
- Create Items linked to the Channels
6.1 Install the JSONPath Transformation Service
Settings -> Transformations -> Blue + -> JSONPath Transformation -> Install
6.2 Create two new Number Channels
Click Add Channel within the Channels tab of your Generic MQTT Thing.
Configure as follows. YAML Code is below the images. Only fields which need modification are shown in the screenshots. Note that Show advanced is selected.
6.2.1 Temperature Channel
YAML Code
- id: temperature
channelTypeUID: mqtt:number
label: Temperature
description: ""
configuration:
stateTopic: tele/swLivingRoomShortLight/SENSOR
transformationPattern: JSONPATH:$.AM2301.Temperature
unit: °C
6.2.2 Humidity Channel
YAML Code
- id: humidity
channelTypeUID: mqtt:number
label: Humidity
description: ""
configuration:
stateTopic: tele/swLivingRoomShortLight/SENSOR
transformationPattern: JSONPATH:$.AM2301.Humidity
unit: "%"
6.3 Create Items linked to the Channels
Within the Channels tab, click Add Points to Model. Select the Temperature and Humidity Channels.
Configure the Items:
Click Add to Model
Within Model you will find the Temperature and Humidity Items (Points).
Summary
openHAB is now connected to the Tasmota device, and can operate the relay and read the temperature and humidity values. Things and Items have been created, which can be added to the Model to suite.