openHAB - seurat-atreides/Sonoff-Tasmota GitHub Wiki

openHAB Integration

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 200 other add-ons for all kinds of technologies, openHAB provides an MQTT add-on ("binding") to interface with systems like Sonoff-Tasmota.

By following the guide below you'll be able to observe, control and manage your Sonoff 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 Sonoff-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

Highly recommended: If you are new to openHAB + MQTT, go through this tutorial:
⇨ MQTT Binding - Getting Started 101

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

* MQTTv1 vs. MQTTv2 Binding Info:

This article currently applies to the openHAB 1 version of the MQTT Binding (mqtt1). The openHAB community has just release a new native openHAB 2 MQTT Binding, which complies with enhancements and significantly changes.

Be aware that if you update your openHAB instance, the new MQTT binding will be installed and mqtt1 will be uninstalled! This means that any MQTT openHAB automations in your openHAB environment will exhibit odd behavior or not operate at all.

Fortunately, the mqtt1 Binding can be reinstalled. To do so, turn on "Include Legacy 1.x Bindings" via PaperUI (Configuration > System) or set legacy = true in addons.cfg. Then reinstall the mqttv1 Binding. Please note that now that mqttv1 is a legacy binding, it will no longer receive updates or fixes. Installing both versions of the binding will allow you to migrate over time to be ready for the eventuality of mqttv1 end of life.

For users that intend to migrate to the new MQTT Binding some examples for the integration have been added at the end of this article.

Before continuing, please make sure you assigned unique MQTT "Topics" in the Sonoff-Tasmota configuration interface of each Sonoff module. The default MQTT topic is "sonoff", in the examples below we will use names like "sonoff-A00EEA".

Example Sonoff-Tasmota MQTT settings

In the example configuration you can see a non-default Full Topic definition, which is not used in the following examples (but which can be recommended).

Integration

Simply set up items for all Sonoff-Tasmota MQTT topics you are interested in. Examples for most needed topics are given below. Some Sonoff-Tasmota topics are JSON encoded, the JSONPATH transformation can be used to extract this data.

Additional or further interesting topics are easily identified by reading up on the Sonoff-Tasmota wiki and by subscribing to the modules topics. Subscribe to all topics of one module with the MQTT wildcard topic string +/sonoff-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 "+/sonoff-E8A6E4/#" -v

tele/sonoff-E8A6E4/LWT Online
tele/sonoff-E8A6E4/UPTIME {"Time":"2017-07-25T12:02:00", "Uptime":68}
tele/sonoff-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/sonoff-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/sonoff-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/sonoff-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/sonoff-E8A6E4/POWER OFF
stat/sonoff-E8A6E4/RESULT {"POWER":"OFF"}
stat/sonoff-E8A6E4/POWER OFF

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

Mandatory Topics / Items

This it the minimal set of items for the basic functionality of different Sonoff modules. You'll need to replace the given example dive name (e.g. "sonoff-A00EEA") by the one chosen for your module.
(Note: Lines have been wrapped for better presentation)

sonoff.items:

  • Sonoff Basic / Sonoff S20 Smart Socket (Read and switch on-state)

    Switch LivingRoom_Light "Living Room Light" <light> (LR,gLight)
    { mqtt=">[broker:cmnd/sonoff-A00EEA/POWER:command:*:default],
            <[broker:stat/sonoff-A00EEA/POWER:state:default]" }

  • Sonoff Pow (Read and switch on-state, read current wattage)

    // compare with example message stream above!
Switch BA_Washingmachine "Washingmachine" <washer> (BA)
    { mqtt=">[broker:cmnd/sonoff-E8A6E4/POWER:command:*:default],
            <[broker:stat/sonoff-E8A6E4/POWER:state:default]" }

Number BA_Washingmachine_Power "Washingmachine Power [%.1f W]" (BA,gPower)
    { mqtt="<[broker:tele/sonoff-E8A6E4/SENSOR:state:JSONPATH($.ENERGY.Power)]" }

  • RGB(CW) LED stripes or other devices which support Color command (Read and switch on-state)

    Switch LivingRoom_Light "Living Room Light" <light> (LR,gLight)
    { mqtt=">[broker:cmnd/sonoff-000000/POWER:command:*:default],
            <[broker:stat/sonoff-000000/RESULT:state:JSONPATH($.POWER)]" }

Status Topics / Items

It is furthermore recommended, to add the following status items for every Sonoff-Tasmota device.

sonoff.items:

  • A switch being 'ON' as long as the device is reachable 💬

    Switch LivingRoom_Light_Reachable "Living Room Light: reachable" (gReachable)
    { mqtt="<[broker:tele/sonoff-A00EEA/LWT:state:MAP(reachable.map)]" }

  • Wifi Signal Strength in Percent

    Number LivingRoom_Light_RSSI "Living Room Light: RSSI [%d %%]" (gRSSI)
    { mqtt="<[broker:tele/sonoff-A00EEA/STATE:state:JSONPATH($.Wifi.RSSI)]" }

  • Optional! A collection of return messages by the Sonoff module
    Recommendation: Define specific items for what you really need on a regular basis, use standalone MQTT client for troubleshooting

    String LivingRoom_Light_Verbose "Living Room Light: MQTT return message [%s]"
    { mqtt="<[broker:tele/sonoff-A00EEA/INFO1:state:default],
            <[broker:stat/sonoff-A00EEA/STATUS2:state:default],
            <[broker:stat/sonoff-A00EEA/RESULT:state:default]" }

💬 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:

reachable.map:

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 Sonoff modules by the press of a simple sitemap button.

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

Sonoff Maintenance Actions

sonoff.items:

//... all the above

//Maintenance
String  Sonoff_Action "Sonoff Action" <sonoff_basic>

yourhome.sitemap:

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

sonoff.rules:

// Work with a list of selected Sonoff modules
val sonoff_device_ids = newArrayList(
    "sonoff-A00EEA",
    //... add all your modules here!
    "sonoff-E8A6E4"
)
// OR
// Work with the grouptopic, addressing ALL modules at once
//val sonoff_device_ids = newArrayList("sonoffs")

rule "Sonoff Maintenance"
when
    Item Sonoff_Action received command
then 
    logInfo("sonoff.rules", "Sonoff Maintenance on all devices: " + receivedCommand)
    for (String device_id : sonoff_device_ids) {
        switch (receivedCommand) {
            case "restart" :
                publish("broker", "cmnd/" + device_id + "/restart", "1") 
            case "queryFW" :
                publish("broker", "cmnd/" + device_id + "/status", "2")
            case "upgrade" : {
                publish("broker", "cmnd/" + device_id + "/otaurl", "http://sonoff.maddox.co.uk/tasmota/sonoff.bin")
                publish("broker", "cmnd/" + device_id + "/upgrade", "1")
            }
        }
    }
    Sonoff_Action.postUpdate(NULL)
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 archive 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:

http.cfg:

# Tasmota Release Status (cached twice a day)
tasmotaRelease.url=https://api.github.com/repos/arendst/Sonoff-Tasmota/tags
tasmotaRelease.updateInterval=43200000

sonoff.items:

String Sonoff_Current_FW_Available "Current Release [%s]" <sonoff_basic> (Sonoff_Maintenance) { http="<[tasmotaRelease:10000:JSONPATH($[0].name)]"}

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

Examples for integration with MQTTv2

.things File:

Bridge mqtt:broker:myMQTTBroker [ host="IPofBroker", secure=false, username="myUser", password="myPassword" , clientID="myMQTTClient" ]
{
    Thing topic sonoff_TH_Thing "Light_TH" {
    Channels:
        Type switch : PowerSwitch  [ stateTopic="stat/sonoff_TH/POWER" , transformationPattern="JSONPATH:$.POWER" , commandTopic="cmnd/sonoff_TH/POWER", on="ON", off="OFF" ]
        Type string : Version [stateTopic="stat/sonoff_TH/STATUS2", transformationPattern="JSONPATH:$.StatusFWR.Version"]
        Type string : Temperature [stateTopic="tele/sonoff_TH/SENSOR", transformationPattern="JSONPATH:$.AM2301.Temperature"]
      }
}

.items File:

Switch Switch_TH "Switch_TH"  { channel="mqtt:topic:myMQTTBroker:sonoff_TH_Thing:PowerSwitch" }

String  Switch_TH_Temperatur "Temperatur [%s °C]" <temperature> {channel="mqtt:topic:myMQTTBroker:sonoff_TH_Thing:Temperature"}
String  Sonoff_Version "Sonoff Version: [%s]" <sonoff_basic> { channel="mqtt:topic:myMQTTBroker:sonoff_6_Thing:Version"}

.rules File for the Maintenance Action:

// Work with a list of selected Sonoff modules
val sonoff_device_ids = newArrayList(
    "sonoff-A00EEA",
    //… add all your modules here!
    "sonoff-E8A6E4"
)
// OR
// Work with the grouptopic, addressing ALL modules at once
//val sonoff_device_ids = newArrayList("sonoffs")

rule "Sonoff Maintenance"
when
    Item Sonoff_Action received command
then
    logInfo("sonoff.rules", "Sonoff Maintenance on all devices: " + receivedCommand)
    val actionsBroker = getActions("mqtt","mqtt:broker:MyMQTTBroker") // change to your broker name!
    for (String device_id : sonoff_device_ids) {
        switch (receivedCommand) {
            case "restart" :
                actionsBroker.publishMQTT( "cmnd/" + device_id + "/restart", "1")
            case "queryFW" :
                actionsBroker.publishMQTT( "cmnd/" + device_id + "/status", "2")
            case "upgrade" : {
                actionsBroker.publishMQTT( "cmnd/" + device_id + "/otaurl", "http://sonoff.maddox.co.uk/tasmota/sonoff-DE.bin")  // Replace DE with your country code or use sonoff.bin or other tasmota specialized firmware
                actionsBroker.publishMQTT( "cmnd/" + device_id + "/upgrade", "1")
            }
        }
    }
    Sonoff_Action.postUpdate(NULL)
end

Community Forum

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

GitHub | Wiki | What's new | Devices | Commands | Rules | Templates | FAQ

⚠️ **GitHub.com Fallback** ⚠️