mirrors
/
Tasmota
mirror of https://github.com/arendst/Tasmota.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated openHAB (markdown)

Thomas Dietrich 2017-05-31 20:05:54 +02:00
parent 4bbe00429e
commit 7cd14157f8
1 changed files with 55 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
openHAB.md

@ -1,62 +1,77 @@
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 150 other add-ons for all kinds of technologies, openHAB provides an [MQTT add-on](http://docs.openhab.org/addons/bindings/mqtt1/readme.html) ("binding") to interface with systems like Sonoff-Tasmota. 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 150 other add-ons for all kinds of technologies, openHAB provides an MQTT add-on ("binding") to interface with systems like Sonoff-Tasmota.
## openHAB Integration ## openHAB Integration
After activating the MQTT binding and MQTT action, simply set up items for all Sonoff-Tasmota MQTT topics you are interested in. Examples are given below. Some Sonoff-Tasmota topics are JSON encoded. The `JSONPATH` transformation can be used to extract this data. 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 openHAB sitemap](https://community-openhab-org.s3-eu-central-1.amazonaws.com/original/2X/5/57750c6c7b6d9f18e75424fcb87ec093f70c6211.png) ![example openHAB sitemap](https://community-openhab-org.s3-eu-central-1.amazonaws.com/original/2X/5/57750c6c7b6d9f18e75424fcb87ec093f70c6211.png "openHAB example of the end result shown in BasicUI")
*Preparation:* Install the MQTT Binding and MQTT Action, e.g. through openHAB Paper UI. ### Requirements
* Working openHAB installation (http://docs.openhab.org)
* Configured Sonoff-Tasmota module (i.e. Sonoff-Tasmota webpage accessible from your local network)
* MQTT broker available (e.g. Eclipse Mosquitto via [openHABian](http://docs.openhab.org/installation/openhabian.html)), a [basic understanding of MQTT](http://www.hivemq.com/blog/mqtt-essentials)
* Working and tested connection between openHAB and the MQTT broker
* (optional) Standalone [MQTT client](http://www.hivemq.com/blog/seven-best-mqtt-client-tools) (e.g. [mqtt-spy](https://kamilfb.github.io/mqtt-spy)) to observe and identify messages on the MQTT broker
Before continuing, please make sure you assigned unique MQTT topics in the configuration interface of each Sonoff module. The default MQTT topic is "sonoff", in the examples below we will use names like "sonoff-A00F9D". To better understand what's going on behind the scene and to be able to troubleshoot, use an [MQTT client](http://www.hivemq.com/blog/seven-best-mqtt-client-tools) in parallel. 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-A00F9D".
If not done yet, you first need to **install and activate** the [MQTT binding](http://docs.openhab.org/addons/bindings/mqtt1/readme.html), the [MQTT action](http://docs.openhab.org/addons/actions/mqtt/readme.html) and the [JsonPath transformation](http://docs.openhab.org/addons/transformations/jsonpath/readme.html), e.g. via the openHAB Paper UI Add-ons section.
### Integration
Simply **set up items** for all Sonoff-Tasmota [MQTT topics](https://github.com/arendst/Sonoff-Tasmota/wiki/MQTT-Features) 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.
### Mandatory Topics / Items ### Mandatory Topics / Items
This it the minimal set of items for the basic functionality of different Sonoff modules. 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-A00F9D") by the one chosen for your module.
<br /> (*Note: Lines have been wrapped for better presentation*) <br /> (*Note: Lines have been wrapped for better presentation*)
**sonoff.items:** **sonoff.items:**
```java
//Sonoff Basic / Sonoff S20 Smart Socket
Switch LivingRoom_Light "Living Room Light" <light> (LR,gLight)
{ mqtt=">[broker:cmnd/sonoff-A00F9D/power:command:*:default],
<[broker:stat/sonoff-A00F9D/POWER:state:default]" }
// Sonoff Pow * Sonoff Basic / Sonoff S20 Smart Socket (Read the current power state, switch power on and off)
Switch BA_Washingmachine "Washingmachine" <washer> (BA) ```java
{ mqtt=">[broker:cmnd/sonoff-E8A6E4/power:command:*:default], Switch LivingRoom_Light "Living Room Light" <light> (LR,gLight)
{ mqtt=">[broker:cmnd/sonoff-A00F9D/POWER:command:*:default],
<[broker:stat/sonoff-A00F9D/POWER:state:default]" }
```
* Sonoff Pow (Read and switch power, read current wattage)
```java
Switch BA_Washingmachine "Washingmachine" <washer> (BA)
{ mqtt=">[broker:cmnd/sonoff-E8A6E4/POWER:command:*:default],
<[broker:stat/sonoff-E8A6E4/POWER:state:default]" } <[broker:stat/sonoff-E8A6E4/POWER:state:default]" }
Number BA_Washingmachine_Power "Washingmachine Power [%.1f W]" (BA,gPower)
Number BA_Washingmachine_Power "Washingmachine Power [%.1f W]" (BA,gPower)
{ mqtt="<[broker:tele/sonoff-E8A6E4/ENERGY:state:JSONPATH($.Power)]" } { mqtt="<[broker:tele/sonoff-E8A6E4/ENERGY:state:JSONPATH($.Power)]" }
``` ```
### Status Topics / Items ### Status Topics / Items
It is furthermore recommended, to add the following status items for every Sonoff-Tasmota device. It is furthermore recommended, to add the following status items for every Sonoff-Tasmota device.
Other Sonoff modules are configured similarly, additional items are easily identified by reading up on the Sonoff-Tasmota documentation and by subscribing to the modules topics. Subscribe to `+/sonoff-XYZ/#` to receive all related messages.
**sonoff.items:** **sonoff.items:**
```java
// A switch being 'ON' as long as the device is reachable 💬 * A switch being 'ON' as long as the device is reachable 💬
Switch LivingRoom_Light_Reachable "Living Room Light: reachable" (gReachable) ```java
Switch LivingRoom_Light_Reachable "Living Room Light: reachable" (gReachable)
{ mqtt="<[broker:tele/sonoff-A00F9D/LWT:state:MAP(reachable.map)]" } { mqtt="<[broker:tele/sonoff-A00F9D/LWT:state:MAP(reachable.map)]" }
```
// Wifi Signal Strength in Percent * Wifi Signal Strength in Percent
Number LivingRoom_Light_RSSI "Living Room Light: RSSI [%d %%]" (gRSSI) ```java
Number LivingRoom_Light_RSSI "Living Room Light: RSSI [%d %%]" (gRSSI)
{ mqtt="<[broker:tele/sonoff-A00F9D/STATE:state:JSONPATH($.Wifi.RSSI)]" } { mqtt="<[broker:tele/sonoff-A00F9D/STATE:state:JSONPATH($.Wifi.RSSI)]" }
```
// Optional! A collection of return messages by the Sonoff module * Optional! A collection of return messages by the Sonoff module
// Recommended: Define specific items for what you really need on a regular basis, <br />Recommendation: Define specific items for what you really need on a regular basis, use standalone MQTT client for troubleshooting
// use standalone MQTT client for troubleshooting ```java
String LivingRoom_Light_Verbose "Living Room Light: MQTT return message [%s]" String LivingRoom_Light_Verbose "Living Room Light: MQTT return message [%s]"
{ mqtt="<[broker:tele/sonoff-A00F9D/INFO1:state:default], { mqtt="<[broker:tele/sonoff-A00F9D/INFO1:state:default],
<[broker:stat/sonoff-A00F9D/STATUS2:state:default], <[broker:stat/sonoff-A00F9D/STATUS2:state:default],
<[broker:stat/sonoff-A00F9D/RESULT:state:default]" } <[broker:stat/sonoff-A00F9D/RESULT:state:default]" }
``` ```
💬 The "LWT" topic (["Last Will and Testament"](http://www.hivemq.com/blog/mqtt-essentials-part-9-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. The following transformation file is needed. 💬 The "LWT" topic (["Last Will and Testament"](http://www.hivemq.com/blog/mqtt-essentials-part-9-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](http://docs.openhab.org/addons/transformations/map/readme.html) transformation. The following transformation file is needed:
**reachable.map:** **reachable.map:**
```java ```java
@ -66,6 +81,10 @@ Offline=OFF
Of course you can implement `Unreachable` instead of `Reachable` if you prefer. Of course you can implement `Unreachable` instead of `Reachable` if you prefer.
### Further Topics / Items, Special Functions
Other Sonoff modules are configured similarly, additional items are easily identified by reading up on the Sonoff-Tasmota documentation and by subscribing to the modules topics. Subscribe to all topics of one module with the MQTT topic string `+/sonoff-XYZ/#`.
## Maintenance Actions ## Maintenance Actions
A home automation system setup would not be complete without a certain maintenance automation! A home automation system setup would not be complete without a certain maintenance automation!