Tasmota Interface

class shc.interfaces.tasmota.TasmotaInterface(mqtt_interface: MQTTClientInterface, device_topic: str, topic_template: str = '{prefix}/{topic}/', telemetry_interval: float = 300)

SHC interface to connect with ESP8266-based IoT devices, running the Tasmota firmware, via MQTT.

Requires a MQTTClientInterface which is connected to the MQTT broker to which your Tasmota device(s) connect. Each instance of TasmotaInterface connects with a single Tasmota device. It identifies the individual Tasmota device via its MQTT “Topic” (by default something like “tasmota_A0B1C2”).

The TasmotaInterface provides subscribable and (mostly) writable connector objects to receive state updates from the Tasmota device and send commands. Currently, only PWM-dimmed lights and IR receivers are fully supported. Please file a GitHub issue if you are interested in other Tasmota functionality.

Parameters:

  • mqtt_interface – The MQTTClientInterface to use for MQTT communication

  • device_topic – The Tasmota devices individual “Topic”, used to address the device, as it is configured on the Tasmota web UI at Configuration → MQTT or using Tasmota’s Topic command. By default it should look like “tasmota_A0B1C2”.

  • topic_template – The Tasmota “Full Topic”, used build MQTT topics from the individual device’s topic. Only required if you don’t use the default Full Topic “%prefix%/%topic%/”. In contrast to the Tasmota web UI or “FullTopic” command, the parameter uses Python’s modern formatting syntax: If your Tasmota “Full Topic” is “devices/%topic%/%prefix%/”, you must specify “devices/{topic}/{prefix}/” as topic_tempalate.

  • telemetry_interval – The expected interval of periodic telemetry messages from the Tasmota device in seconds. This is used by the status monitoring to detect device failures. Use 0 to disable telemetry monitoring.

online() → TasmotaOnlineConnector

Returns a readable and subscribable bool-typed Connector that will indicate the online-state of the Tasmota device, using its MQTT “Last Will Topic”.

You can also use the subscribable monitoring_connector() of this interface to receive more status information.

telemetry() → TasmotaTelemetryConnector

Returns a subscribable TasmotaTelemetry-typed Connector that will publish the general telemetry information as received from the Tasmota device.

power() → TasmotaPowerConnector

Returns a subscribable and writable bool-typed Connector to monitor and control the POWER state of the Tasmota device.

dimmer() → TasmotaDimmerConnector

Returns a subscribable and writable Connector to monitor and control the Dimmer state of the Tasmota device.

The dimmer value is an integer between 0 and 100, represented as shc.datatypes.RangeInt0To100 in SHC.

color_cct() → TasmotaColorCCTConnector

Returns a subscribable and writable Connector to monitor and control two channel (cold-white, white-white) dimmable lamps attached to the Tasmota device. The value is represented as shc.datatypes.CCTUInt8 (composed of two 8-bit shc.datatypes.RangeUInt8 integer values).

Note, that this connector is only sensible if the Tasmota device has two PWM pins for cold white and warm white configured. It will also work with different numbers of PWM channels configured, but the channel mapping will not be sensible.

See https://tasmota.github.io/docs/Lights/ for more information on Tasmota light controls.

color_rgb() → TasmotaColorRGBConnector

Returns a subscribable and writable Connector to monitor and control three channel (red, green, blue) dimmable lamps attached to the Tasmota device. The value is represented as shc.datatypes.RGBUInt8 (composed of three 8-bit shc.datatypes.RangeUInt8 integer values).

Note, that this connector is only sensible if the Tasmota device has at least three PWM pins for red, green and blue configured. It will also work with less PWM channels configured, but the channel mapping will not be sensible.

See https://tasmota.github.io/docs/Lights/ for more information on Tasmota light controls.

color_rgbw() → TasmotaColorRGBWConnector

Returns a subscribable and writable Connector to monitor and control four channel (red, green, blue, white) dimmable lamps attached to the Tasmota device. The value is represented as shc.datatypes.RGBWUInt8 (composed of three 8-bit shc.datatypes.RangeUInt8 integer values for RGB in an shc.datatypes.RGBUInt8 and an additional shc.datatypes.RangeUInt8 value for the white channel).

Note, that this connector is only sensible if the Tasmota device has four PWM pins for red, green, blue and white configured. It will also work with a different number PWM channels configured, but the channel mapping will not always be sensible.

See https://tasmota.github.io/docs/Lights/ for more information on Tasmota light controls.

color_rgbcct() → TasmotaColorRGBCCTConnector

Returns a subscribable and writable Connector to monitor and control five channel (red, green, blue, cold white, warm white) dimmable lamps attached to the Tasmota device. The value is represented as shc.datatypes.RGBCCTUInt8 (composed of three 8-bit shc.datatypes.RangeUInt8 integer values for RGB in an shc.datatypes.RGBUInt8 and two additional shc.datatypes.RangeUInt8 values in an class:shc.datatypes.CCTUInt8).

Note, that this connector is only sensible if the Tasmota device has five PWM pins configured. It will also work less PWM channels configured, but the channel mapping will not always be sensible.

See https://tasmota.github.io/docs/Lights/ for more information on Tasmota light controls.

ir_receiver() → TasmotaIRReceiverConnector

Returns a subscribable bytes-typed Connector that publishes the data/hash of each IR command received by the Tasmota device (via an IR receiver, attatched to a pin configured as IRrecv).

See https://tasmota.github.io/docs/Tasmota-IR/#receiving-ir-commands for more information about receiving IR commands.

energy() → TasmotaEnergyConnector

Returns a subscribable float-typed Connector, publishing the currently measured power consumption values in from the Tasmota device.

Unavailable power/energy values are set to NaN.

energy_power() → TasmotaEnergyPowerConnector

Returns a subscribable float-typed Connector, publishing the currently measured power consumption in watts from the Tasmota device, if available.

Deprecated since version 0.8.0: The TasmotaInterface.energy_power() method is deprecated. Use energy() with a connected shc.misc.UpdateExchange instead.

energy_voltage() → TasmotaEnergyVoltageConnector

Returns a subscribable float-typed Connector, publishing the currently measured mains voltage in volts from the Tasmota device, if available.

Deprecated since version 0.8.0: The TasmotaInterface.energy_voltage() method is deprecated. Use energy() with a connected shc.misc.UpdateExchange instead.

energy_current() → TasmotaEnergyCurrentConnector

Returns a subscribable float-typed Connector, publishing the currently measured current flow in amperes from the Tasmota device, if available.

Deprecated since version 0.8.0: The TasmotaInterface.energy_current() method is deprecated. Use energy() with a connected shc.misc.UpdateExchange instead.

energy_total() → TasmotaEnergyTotalConnector

Returns a subscribable float-typed Connector, publishing the total energy consumption measured by the Tasmota device since its last reboot in kWh.

Deprecated since version 0.8.0: The TasmotaInterface.energy_total() method is deprecated. Use energy() with a connected shc.misc.UpdateExchange instead.

energy_power_factor() → TasmotaEnergyFactorConnector

Returns a subscribable float-typed Connector, publishing the currently measured power factor from the Tasmota device.

Deprecated since version 0.8.0: The TasmotaInterface.energy_power_factor() method is deprecated. Use energy() with a connected shc.misc.UpdateExchange instead.

energy_reactive_power() → TasmotaEnergyReactivePowerConnector

Returns a subscribable float-typed Connector, publishing the currently measured reactive power in VAr from the Tasmota device.

Deprecated since version 0.8.0: The TasmotaInterface.energy_reactive_power() method is deprecated. Use energy() with a connected shc.misc.UpdateExchange instead.

energy_apparent_power() → TasmotaEnergyApparentPowerConnector

Returns a subscribable float-typed Connector, publishing the currently measured apparent power in VA from the Tasmota device.

Deprecated since version 0.8.0: The TasmotaInterface.energy_apparent_power() method is deprecated. Use energy() with a connected shc.misc.UpdateExchange instead.

namedtuple shc.interfaces.tasmota.TasmotaEnergyMeasurement(power, voltage, current, apparent_power, reactive_power, power_factor, frequency, total_energy, total_energy_today, total_energy_yesterday)

TasmotaEnergyMeasurement(power, voltage, current, apparent_power, reactive_power, power_factor, frequency, total_energy, total_energy_today, total_energy_yesterday)

Fields:

  1.  power (float) – the currently measured power consumption in W

  2.  voltage (float) – the currently measured mains voltage in V

  3.  current (float) – the currently measured current flow in A

  4.  apparent_power (float) – the currently measured apparent power in VA

  5.  reactive_power (float) – the currently measured reactive power in VAr

  6.  power_factor (float) – the currently measured power factor

  7.  frequency (float) – the currently measured mains frequency in Hz

  8.  total_energy (float) – the total energy consumption in kWh

  9.  total_energy_today (float) – today’s energy consumption in kWh

  10.  total_energy_yesterday (float) – yesterday’s energy consumption in kWh

namedtuple shc.interfaces.tasmota.TasmotaTelemetry(telemetry_timestamp: datetime, uptime: timedelta, voltage: float, heap: int, load_avg: int, wifi_ssid: str, wifi_bssid: str, wifi_channel: int, wifi_rssi: int, wifi_signal: int, wifi_downtime: timedelta)

Generic Tasmota telemetry information.

Values of this type are published by the TasmotaInterface.telemetry() connector

Fields:

  1.  telemetry_timestamp (datetime) – Alias for field number 0

  2.  uptime (timedelta) – Alias for field number 1

  3.  voltage (float) – Alias for field number 2

  4.  heap (int) – Alias for field number 3

  5.  load_avg (int) – Alias for field number 4

  6.  wifi_ssid (str) – Alias for field number 5

  7.  wifi_bssid (str) – Alias for field number 6

  8.  wifi_channel (int) – Alias for field number 7

  9.  wifi_rssi (int) – Alias for field number 8

  10.  wifi_signal (int) – Alias for field number 9

  11.  wifi_downtime (timedelta) – Alias for field number 10