Skip to content

openHAB

The "open Home Automation Bus" (openHAB) is an open source, technology agnostic home automation platform which runs as the center of your smart home. Besides more than 400 other add-ons for all kinds of technologies, openHAB provides an MQTT add-on ("binding") to interface with systems like Tasmota.

By following the guide below you'll be able to observe, control and manage your Tasmota modules from your openHAB system. If you are new to openHAB, please learn about the basic concepts and the initial setup. The below article will not cover any basics which are out of scope to the Tasmota integration.

Example Result: The screenshot of an openHAB Sitemap below features a few Sonoff modules for lighting, two modified Sonoff Basic with sensors for temperature and humidity readings and two Sonoff Pow for power measurements of a washing machine and dishwasher:

example openHAB sitemap

Requirements~

If not done yet, you first need to install and activate the MQTT and the JsonPath transformation, e.g. via the openHAB Paper UI Add-ons section.

MQTTv1 vs. MQTTv2 Binding Information

Please note that since mqtt1 is a legacy binding for years now, it will no longer receive updates or fixes. See older version of this tutorial on how to integrate Tasmota using this binding if you are using mqtt1 - but be advised that it's not recommended anymore, it's better to upgrade to MQTTv2 binding. See openHAB announcement of MQTTv2 for details on how to change your configuration.

MQTTv2 Integration~

Configuration is split throughout some openHAB configuration files. First we need to set up a MQTT connection and Tasmota things - you will need a separate thing for every Tasmota device you use.

In the example configuration you can see a non-default Full Topic definition. For your real world device simply set up items for all Tasmota MQTT topics you are interested in. Examples for most needed topics are given below, see section Discovering Interesting Topics below on how to watch the raw MQTT data. Some Tasmota topics are JSON encoded, the JSONPATH transformation can be used to extract this data.

You'll need to replace the given example device topic name (e.g. "Tasmota_TH") by the one chosen for your module.

.things File:

Bridge mqtt:broker:myMQTTBroker "My only one and best MQTT server"
[
    host="IPofBroker",
    username="myUser",
    password="myPassword",
    clientID="myopenHABMQTTClient"
]

Thing mqtt:topic:tasmota:tasmota_TH "Light_TH" (mqtt:broker:myMQTTBroker) [ availabilityTopic="tele/tasmota_TH/LWT", payloadAvailable="Online", payloadNotAvailable="Offline" ] {
    Channels:
        // Sonoff Basic / Sonoff S20 Smart Socket (Read and switch on-state)
        Type switch : PowerSwitch  [stateTopic="stat/tasmota_TH/POWER",   commandTopic="cmnd/tasmota_TH/POWER", on="ON", off="OFF"]

        // Sonoff Pow (read current wattage; for read and switch on-state see above)
        Type number : Power                 [stateTopic="tele/tasmota_TH/SENSOR", transformationPattern="JSONPATH:$.ENERGY.Power"]
        // More power readouts
        Type number : ApparentPower         [stateTopic="tele/tasmota_TH/SENSOR", transformationPattern="JSONPATH:$.ENERGY.ApparentPower"]
        Type number : ReactivePower         [stateTopic="tele/tasmota_TH/SENSOR", transformationPattern="JSONPATH:$.ENERGY.ReactivePower"]
        Type number : PowerFactor           [stateTopic="tele/tasmota_TH/SENSOR", transformationPattern="JSONPATH:$.ENERGY.Factor"]
        Type number : Voltage               [stateTopic="tele/tasmota_TH/SENSOR", transformationPattern="JSONPATH:$.ENERGY.Voltage"]
        Type number : Current               [stateTopic="tele/tasmota_TH/SENSOR", transformationPattern="JSONPATH:$.ENERGY.Current"]

        // devices including AM2301 temperature sensor
        Type number : Temperature  [stateTopic="tele/tasmota_TH/SENSOR",  transformationPattern="JSONPATH:$.AM2301.Temperature"]

        // Tasmota Status
        Type string : Version      [stateTopic="stat/tasmota_TH/STATUS2", transformationPattern="JSONPATH:$.StatusFWR.Version"]
        Type switch : Reachable    [stateTopic="tele/tasmota_TH/LWT",     transformationPattern="MAP:tasmota-reachable.map"]

        // Diagnostics: Define specific for what you really need on a regular basis, use standalone MQTT client for troubleshooting
        Type string : RestartReason [stateTopic="tele/tasmota_TH/INFO3", transformationPattern="JSONPATH:$.Info3.RestartReason"]
        // old one, have to query it
        Type string : Version2      [stateTopic="stat/tasmota_TH/STATUS2", transformationPattern="JSONPATH:$.StatusFWR.Version"]
        // new one - comes for free at startup
        Type string : Version       [stateTopic="tele/tasmota_TH/INFO1", transformationPattern="JSONPATH:$.Info1.Version"]
        Type number : RSSI          [stateTopic="tele/tasmota_TH/STATE", transformationPattern="JSONPATH:$.Wifi.RSSI"]
        Type string : WifiDowntime  [stateTopic="tele/tasmota_TH/STATE", transformationPattern="JSONPATH:$.Wifi.Downtime"]
        Type number : LoadAvg       [stateTopic="tele/tasmota_TH/STATE", transformationPattern="JSONPATH:$.LoadAvg"]
        Type number : Uptime        [stateTopic="tele/tasmota_TH/STATE", transformationPattern="JSONPATH:$.UptimeSec"]
        Type string : Result        [stateTopic="stat/tasmota_TH/RESULT"]
}

.items File:

For every property your device exposes, you need to define an item, linked to corresponding channel of your Tasmota thing.

// device specific properties
// replace "TH" with device ID from MQTT topic
// replace "My Socket" to desirecd name
// Comment out items/links that are not used/needed

Switch             Tasmota_TH_Switch      "My Socket: Switch" <switch>                  {channel="mqtt:topic:tasmota:tasmota_TH:PowerSwitch"}

Number:Power                 Tasmota_TH_Power               "My Socket: Power [%.1f W]" <energy>           {channel="mqtt:topic:tasmota:tasmota_TH:Power"}
Number:Power                 Tasmota_TH_ApparentPower       "My Socket: Apparent Power [%.1f VA]" <energy>           {channel="mqtt:topic:tasmota:tasmota_TH:ApparentPower"}
Number:Power                 Tasmota_TH_ReactivePower       "My Socket: Reactive Power [%.1f VAr]" <energy>           {channel="mqtt:topic:tasmota:tasmota_TH:ReactivePower"}
Number:Dimensionless         Tasmota_TH_PowerFactir         "My Socket: Power Factor [%.2f]" <energy>           {channel="mqtt:topic:tasmota:tasmota_TH:PowerFactor"}
Number:ElectricPotential     Tasmota_TH_Voltage             "My Socket: Voltage [%.0f V]" <energy>           {channel="mqtt:topic:tasmota:tasmota_TH:Voltage"}
Number:ElectricCurrent       Tasmota_TH_Current             "My Socket: Current [%.2f A]" <energy>           {channel="mqtt:topic:tasmota:tasmota_TH:Current"}
Number:Temperature           Tasmota_TH_Temp                "My Socket: Temperature [%.1f °C]" <temperature> {channel="mqtt:topic:tasmota:tasmota_TH:Temperature"}

// Tasmota Status
String             Tasmota_TH_Version   "My Socket: Tasmota Version [%s]" {channel="mqtt:topic:tasmota:tasmota_TH:Version", channel="mqtt:topic:tasmota:tasmota_TH:Version2"}
Switch             Tasmota_TH_Reachable "My Socket: Reachable"            {channel="mqtt:topic:tasmota:tasmota_TH:Reachable"}

// Diagnostics
String               Tasmota_TH_RestartReason "My Socket: Restart Reason [%s]"  {channel="mqtt:topic:tasmota:tasmota_TH:RestartReason"}
Number:Dimensionless Tasmota_TH_RSSI          "My Socket: Signal [%d %%]"  <qualityofservice>     {channel="mqtt:topic:tasmota:tasmota_TH:RSSI"}
String               Tasmota_TH_WifiDowntime  "My Socket: Wifi Downtime [%s]"   {channel="mqtt:topic:tasmota:tasmota_TH:WifiDowntime"}
Number:Dimensionless Tasmota_TH_LoadAvg       "My Socket: Load [%d %%]"         {channel="mqtt:topic:tasmota:tasmota_TH:LoadAvg"}
String               Tasmota_TH_Result        "My Socket: Result [%s]"          {channel="mqtt:topic:tasmota:tasmota_TH:Result"}
Number:Time          Tasmota_TH_Uptime        "My Socket: Uptime [%.1f s]"      {channel="mqtt:topic:tasmota:tasmota_TH:Uptime"}

// Maintenance (described below)
String Tasmota_TH_Action "My Socket: Tasmota Action"

.sitemap File:

// device specific properties
Switch item=Switch_TH
Text   item=Switch_TH_Temp
Text   item=Power

// Maintenance
Switch item=Tasmota_Action mappings=[restart="Restart", queryFW="Query FW", upgrade="Upgrade FW"]

// Tasmota Status
Text item=Tasmota_Version
Text item=Tasmota_Reachable

// Diagnostics
Text item=Tasmota_RestartReason
Text item=Tasmota_RSSI
Text item=Tasmota_WifiDowntime
Text item=Tasmota_LoadAvg
Text item=Tasmota_Uptime label="Uptime [%.1f d]"
Text item=Tasmota_Result

The "LWT" topic ("Last Will and Testament") will receive regular "Online" messages by the module and an "Offline" message a short time after the module is disconnected, generated by the MQTT broker. These messages are transformed to a valid ON/OFF state by the MAP transformation. Of course you can implement Unreachable instead of Reachable if you prefer. The following transformation file is needed:

tasmota-reachable.map Fíle:

Online=ON
Offline=OFF

Maintenance Actions~

A home automation system setup would not be complete without a certain maintenance automation!

Add the following elements to your openHAB setup to be able to perform actions on your Tasmota devices by the press of a simple sitemap button.

The example below includes upgrading the firmware of all devices. A shoutout to @evilgreen for the idea and a big thanks to @smadds for providing the idea of a public firmware server.

Tasmota Maintenance Actions

tasmota_maintenance.rules File for Maintenance Actions:

// Work with grouptopic, addressing ALL modules at once, easiest solution
val tasmota_device_ids = newArrayList("tasmotas")
// OR
// Work with a list of selected Tasmota modules
//val tasmota_device_ids = newArrayList(
//    "tasmota_A00EEA",
//    //… add all your modules here, don't forget some!
//    "tasmota_E8A6E4"
//)

rule "Tasmota Maintenance"
when
    Item Tasmota_Action received command
then
    logInfo("tasmota_maintenance.rules", "Tasmota Maintenance on all devices: " + receivedCommand)
    val actionsBroker = getActions("mqtt","mqtt:broker:MyMQTTBroker") // change to your broker name!
    for (String device_id : tasmota_device_ids) {
        switch (receivedCommand) {
            case "restart" :
                actionsBroker.publishMQTT( "cmnd/" + device_id + "/restart", "1")
            case "queryFW" :
                actionsBroker.publishMQTT( "cmnd/" + device_id + "/status", "2")
            case "upgrade" : {
                // one could change OTA URL using MQTT but if you use different breeds (basic, ir, sensor, ...) of Tasmota, you would lose them
                // it's better to configure OTA url at each device (default) and just trigger upgrade - they will use OTA URL saved in your device.
                //actionsBroker.publishMQTT( "cmnd/" + device_id + "/otaurl", "http://ota.tasmota.com/tasmota/release/tasmota.bin")
                actionsBroker.publishMQTT( "cmnd/" + device_id + "/upgrade", "1")
            }
        }
    }
    createTimer(now.plusSeconds(1))[|Tasmota_Action.postUpdate(UNDEF)]
end

Comparing your device firmware with the current Tasmota GitHub Release~

Knowing your devices firmware version(s) is good. Being able to compare it with the current release directly, is even better. You can achieve this by combining the maintenance actions with the openHAB http binding, the JsonPath transformation and the GitHub API.

Just extend the maintenance setup with the following Item and config (make sure you have the binding addon http and transformation addon jsonpath installed):

tasmota.things:

Thing http:url:TasmotaVersion [
    baseURL="https://api.github.com/repos/arendst/Tasmota/tags",
    refresh=86400] { // refresh once a day
        Channels:
            Type string : Version "Version" [ stateTransformation="JSONPATH:$[0].name" ]
}

tasmota.items:

String Tasmota_Current_FW_Available "Current Release [%s]" {channel="http:url:TasmotaVersion:Version"}

With this item in your sitemap, you will now see the latest release/tag from Tasmota repository.

Discovering Interesting Topics~

Additional or further interesting topics are easily identified by reading up on the Tasmota wiki and by subscribing to the modules topics. Subscribe to all topics of one module using MQTT wildcard topic string +/tasmota_XYZ/# (string depends on your user-configured Topic/FullTopic). Configure items for the identified topics similar to the ones below.

Example: MQTT messages published by a Sonoff Pow module are shown below (using mosquitto_sub). The module reports its device state and energy readings periodically. In the second half of the example the module relay was switched into the OFF position.

$ mosquitto_sub -h localhost -t "+/tasmota_E8A6E4/#" -v

tele/tasmota-E8A6E4/LWT Online
tele/tasmota-E8A6E4/UPTIME {"Time":"2017-07-25T12:02:00", "Uptime":68}
tele/tasmota-E8A6E4/STATE {"Time":"2017-07-25T12:06:28", "Uptime":68, "Vcc":3.122, "POWER":"POWER", "Wifi":{"AP":1, "SSID":"HotelZurBirke", "RSSI":100, "APMac":"24:65:11:BF:12:D8"}}
tele/tasmota-E8A6E4/ENERGY {"Time":"2017-07-25T12:06:28", "Total":0.640, "Yesterday":0.007, "Today":0.003, "Period":0, "Power":0, "Factor":0.00, "Voltage":0, "Current":0.000}
tele/tasmota-E8A6E4/STATE {"Time":"2017-07-25T12:11:28", "Uptime":68, "Vcc":3.122, "POWER":"POWER", "Wifi":{"AP":1, "SSID":"HotelZurBirke", "RSSI":100, "APMac":"24:65:11:BF:12:D8"}}
tele/tasmota-E8A6E4/ENERGY {"Time":"2017-07-25T12:11:28", "Total":0.640, "Yesterday":0.007, "Today":0.003, "Period":0, "Power":0, "Factor":0.00, "Voltage":0, "Current":0.000}
cmnd/tasmota-E8A6E4/POWER OFF
stat/tasmota-E8A6E4/RESULT {"POWER":"OFF"}
stat/tasmota-E8A6E4/POWER OFF

Following this method, the behavior-linked messages can be identified and bound to openHAB items.

Community Forum~

For more openHAB related details and questions, please visit the openHAB community forum thread on Sonoff and Tasmota.