mirror of https://github.com/arendst/Tasmota.git
Updated openHAB (markdown)
Thomas Dietrich
parent
4bbe00429e
commit
7cd14157f8
91
openHAB.md
91
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
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
*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
|
||||
|
||||
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*)
|
||||
|
||||
**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
|
||||
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/ENERGY:state:JSONPATH($.Power)]" }
|
||||
```
|
||||
* Sonoff Basic / Sonoff S20 Smart Socket (Read the current power state, switch power on and off)
|
||||
```java
|
||||
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]" }
|
||||
|
||||
Number BA_Washingmachine_Power "Washingmachine Power [%.1f W]" (BA,gPower)
|
||||
{ mqtt="<[broker:tele/sonoff-E8A6E4/ENERGY:state:JSONPATH($.Power)]" }
|
||||
```
|
||||
|
||||
### Status Topics / Items
|
||||
|
||||
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:**
|
||||
```java
|
||||
// A switch being 'ON' as long as the device is reachable 💬
|
||||
Switch LivingRoom_Light_Reachable "Living Room Light: reachable" (gReachable)
|
||||
{ mqtt="<[broker:tele/sonoff-A00F9D/LWT:state:MAP(reachable.map)]" }
|
||||
|
||||
// Wifi Signal Strength in Percent
|
||||
Number LivingRoom_Light_RSSI "Living Room Light: RSSI [%d %%]" (gRSSI)
|
||||
{ mqtt="<[broker:tele/sonoff-A00F9D/STATE:state:JSONPATH($.Wifi.RSSI)]" }
|
||||
* A switch being 'ON' as long as the device is reachable 💬
|
||||
```java
|
||||
Switch LivingRoom_Light_Reachable "Living Room Light: reachable" (gReachable)
|
||||
{ mqtt="<[broker:tele/sonoff-A00F9D/LWT:state:MAP(reachable.map)]" }
|
||||
```
|
||||
|
||||
// Optional! A collection of return messages by the Sonoff module
|
||||
// Recommended: 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-A00F9D/INFO1:state:default],
|
||||
<[broker:stat/sonoff-A00F9D/STATUS2:state:default],
|
||||
<[broker:stat/sonoff-A00F9D/RESULT:state:default]" }
|
||||
```
|
||||
* Wifi Signal Strength in Percent
|
||||
```java
|
||||
Number LivingRoom_Light_RSSI "Living Room Light: RSSI [%d %%]" (gRSSI)
|
||||
{ mqtt="<[broker:tele/sonoff-A00F9D/STATE:state:JSONPATH($.Wifi.RSSI)]" }
|
||||
```
|
||||
|
||||
💬 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.
|
||||
* Optional! A collection of return messages by the Sonoff module
|
||||
<br />Recommendation: Define specific items for what you really need on a regular basis, use standalone MQTT client for troubleshooting
|
||||
```java
|
||||
String LivingRoom_Light_Verbose "Living Room Light: MQTT return message [%s]"
|
||||
{ mqtt="<[broker:tele/sonoff-A00F9D/INFO1:state:default],
|
||||
<[broker:stat/sonoff-A00F9D/STATUS2: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](http://docs.openhab.org/addons/transformations/map/readme.html) transformation. The following transformation file is needed:
|
||||
|
||||
**reachable.map:**
|
||||
```java
|
||||
|
|
@ -66,6 +81,10 @@ Offline=OFF
|
|||
|
||||
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
|
||||
|
||||
A home automation system setup would not be complete without a certain maintenance automation!
|
||||
|
|
|
|||
Loading…
Reference in New Issue