Add adapter for devices running Tasmota

amotl commented 5 years ago

Tasmota is an alternative firmware for ESP8266 based devices like iTead Sonoff, which - besides other things - is able to do control and telemetry using MQTT.

People recently asked about respective data ingest support for the Tasmota MQTT communication style.

[EDIT]: The documentation is available at Tasmota Decoder.

amotl commented 5 years ago

Sources:

Tasmota Telemetry

The documentation referenced above says about the telemetry feature of the Sonoff-Tasmota firmware...

Some Sonoff devices like temperature measuring devices report unsolicited telemetry info at periodic intervals.

Telemetry data will be sent to an MQTT topic prefixed with tele like tele/sonoff/SENSOR and a respective payload might look like

{
  "Time": "2017-02-16T10:13:52",
  "DS18B20": {
    "Temperature": 20.6
  }
}

An appropriate dispatcher which listens to just telemetry messages would eventually start with

if last_topic.startswith("tele/") and last_topic.endswith("STATE"):
    decode_tasmota_telemetry_message(payload)

amotl commented 5 years ago

Source: https://github.com/arendst/Sonoff-Tasmota/wiki/MQTT#mqtt-topic-definition

MQTT Topic definition

Until version 5.0.5 the MQTT topic was defined rigidly by using the commands Prefix<x> and Topic resulting in a command topic string like cmnd/sonoff/Power.

Starting with version 5.0.5 the MQTT topic is more flexible using command FullTopic and tokens to be placed within the user definable string up to 100 characters in size. The provided tokens are:

%prefix% to be dynamically substituted by one of three prefixes as defined by commands Prefix1 (default: "cmnd"), Prefix2 (default: "stat") and Prefix3 (default: "tele").
%topic% to be dynamically substituted by one of five topics as defined by commands Topic, GroupTopic, ButtonTopic, SwitchTopic and MqttClient.

Using the tokens the following example topics can be made:

FullTopic %prefix%/%topic%/ being the legacy situation up to version 5.0.5
FullTopic tasmota/%topic%/%prefix%/
FullTopic tasmota/bedroom/%topic%/%prefix%/
FullTopic penthouse/bedroom1/bathroom2/%topic%/%prefix%/

%prefix%

Tasmota uses 3 prefixes for forming a FullTopic:

cmnd - prefix to issue commands; ask for status
stat - reports back status or configuration message
tele - reports telemetry info at specified intervals

Theo's note:

To solve possible MQTT topic loops I strongly suggest to use the %prefix% token in all of your FullTopics. It may work without %prefix% as I implemented some validation by forcing the use of a prefix in commands sent to the device but status and telemetry do not need a prefix. Just play with it and report strange problems I might solve in the future.

The use of the %topic% token is also mandatory in case you want to use ButtonTopic and/or SwitchTopic. It also provides for grouptopic and fallback topic functionality.

Recommendation: Use both tokens at all time within your FullTopic string

amotl commented 5 years ago

Two more payload examples from the wild.

`sonoffSC/tele/STATE`

{
  "Time": "2019-06-02T22:13:07",
  "Uptime": "1T18:10:35",
  "Vcc": 3.182,
  "SleepMode": "Dynamic",
  "Sleep": 50,
  "LoadAvg": 19,
  "Wifi": {
    "AP": 1,
    "SSId": "{redacted}",
    "BSSId": "A0:F3:C1:{redacted}",
    "Channel": 1,
    "RSSI": 100,
    "LinkCount": 1,
    "Downtime": "0T00:00:07"
  }
}

`sonoffSC/tele/SENSOR`

{
  "Time": "2019-06-02T22:13:07",
  "SonoffSC": {
    "Temperature": 25,
    "Humidity": 15,
    "Light": 20,
    "Noise": 10,
    "AirQuality": 90
  },
  "TempUnit": "C"
}

amotl commented 5 years ago

[Proposal] Tasmota MQTT Telemetry Adapter for Kotori

By staying as close to the vanilla documentation examples as possible, newcomers should have an easy way getting their telemetry data ingested. Kotori will need a special handler to unfold the nested payload structure anyway, so twisting it around yet another MQTT topic style/format should not be a problem at all.

Introduction

Source: https://github.com/arendst/Sonoff-Tasmota/wiki/MQTT#configure-mqtt

Topic

Unique identifier of your device (e.g. hallswitch, kitchen-light). Referenced elsewhere as %topic%.

FullTopic

A full topic definition where %topic% and %prefix% can be interpolated into.

By example

Let's call our device "node-42" and bind it to the communication channel "acme/milky-way/earth-one", essentially meaning:

realm: acme
universe: milky-way
location: earth-one
node: node-42

The appropriate settings for Tasmota would then be

Topic: node-42
Full Topic: acme/milky-way/earth-one/%topic%/%prefix%/

which will most probably yield topics like

acme/milky-way/earth-one/node-42/tele/SENSOR

amotl commented 5 years ago

Kotori will need a special handler to unfold the nested payload structure anyway, so twisting it around yet another MQTT topic style/format should not be a problem at all.

This part is not implemented yet. We will drop a note here when it's finished.

amotl commented 5 years ago

We added basic support with 77b94fa1 and 5f5d9511 but haven't issued a new release yet. Also, the "Time" field from the telemetry message is not honored yet.

amotl commented 4 years ago

The decoder for Tasmota devices is available through the recent releases of Kotori.

amotl commented 4 years ago

Reading the "Time" field from the message is finally supported through 4097e402.

amotl commented 4 years ago

Dear @rohlan,

we just added the missing bit for completing the implementation 4097e402 and updated the Tasmota decoder documentation. Now, we are wondering whether everything will still work with the latest and greatest Tasmota 8.1.

Will you have a chance to check this?

Thanks already and with kind regards, Andreas.

daq-tools / kotori