From 05303b384d94d7822fe7f42e2b5f7a089f821723 Mon Sep 17 00:00:00 2001 From: Tristan Date: Wed, 20 Dec 2023 10:03:23 +0100 Subject: [PATCH 1/4] Update Home-Assistant.md Add link to Tasmota discovery and deprecation notice for SetOption19 --- docs/Home-Assistant.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/Home-Assistant.md b/docs/Home-Assistant.md index f05f69f9c1..eebae8bb19 100644 --- a/docs/Home-Assistant.md +++ b/docs/Home-Assistant.md @@ -11,12 +11,17 @@ Tasmota communicates with Home Assistant using MQTT. Before going any further, m Home Assistant can add Tasmota devices using: 1. Official Tasmota integration - **preferred** and automatic instant discovery of entities -2. Manual configuration by editing configuration.yaml - recommended for marginal use cases, e.g., TuyaMCU fan devices +2. Deprecated legacy discovery format `SetOption19` +3. Manual configuration by editing configuration.yaml - recommended for marginal use cases, e.g., TuyaMCU fan devices ## Tasmota Integration [![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=Tasmota) +## Legacy discovery format + +!!! failure "`SetOption19` is deprecated in favor of [Tasmota discovery format](Auto-Discovery.md). The new format is also used by the Home Assistant integration." + Once you configure the [Home Assistant](https://www.home-assistant.io/integrations/tasmota/) integration every new Tasmota device with `SetOption19 0` set will be discovered automatically. All Tasmota devices will be listed in their own Tasmota card in **Configuration - Integrations** menu in Home Assistant. From 47ead14df9ed894975fd1fa51a4ea85017563f0b Mon Sep 17 00:00:00 2001 From: Tristan Date: Wed, 20 Dec 2023 10:33:36 +0100 Subject: [PATCH 2/4] Create Auto-Discovery.md --- docs/Auto-Discovery.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/Auto-Discovery.md diff --git a/docs/Auto-Discovery.md b/docs/Auto-Discovery.md new file mode 100644 index 0000000000..b71fb54508 --- /dev/null +++ b/docs/Auto-Discovery.md @@ -0,0 +1,41 @@ +description: Device auto discovery + +# Auto discovery +Tasmota auto discovery is meant to replace deprecated [Home Assistant discovery]([Home-Assistant.md](Home-Assistant.md#legacy-discovery-format)) (`SetOption19`) by a custom discovery format better suited for Tasmota. + +> Home Assistant's MQTT discovery protocol includes a lot of redundant information which increases Tasmota's code size, and has some crucial limitations e.g. RGBxx lights flickering when turning on from HA. +> Also, Home Assistant's MQTT discovery protocol is not easy to add new features or make breaking changes to. (https://github.com/arendst/Tasmota/issues/9267) + +## Availability +* Starting `v9.3.1.2` Tasmota ships with its format as an alternative to Home Assistant discovery. +* Since `v11.1.0.2` Home Assistant discovery is considered deprecated. + +## Discovery message format +Topic: `tasmota/discovery/49A3BC` + +Payload: +``` +{ + "ip":"192.168.15.10", // IP address + "dn":"Living Room", // Device name + "fn":["Ceiling Lamp", "Floor Lamp"], // List of friendly names + "hn":"tasmota_49A3BC-0956", // Hostname + "id":"49A3BC", // ChipID + "md":"Sonoff Dual", // Module + "of":"Offline", // D_OFFLINE + "on":"Online", // D_ONLINE + "st":["OFF","ON","TOGGLE","HOLD"], // StateText[0..3] + "bd":"8.4.0.2", // Tasmota SW build version + "t":"tasmota_49A3BC", // Topic + "ft":"%prefix%/%topic%/", // Fulltopic + "tp":["cmnd","stat","tele"], // [SUB_PREFIX, PUB_PREFIX, PUB_PREFIX2] + "li":[0,0,0,0,0,0,0,0], // Lights, 0: disabled, 1: Enabled + "rl":[0,0,0,0,0,0,0,0], // Relays, 0: disabled, 1: relay, 2.. future extension (fan, shutter?) + "sw":[0,0,0,0,0,0,0,0], // Switches, 0: disabled: 1: enabled + "bt":[0,0,0,0], // Buttons, 0: disabled: 1: enabled + "so":{"13":0,"17":1,"30":0,"37":1,"68":0,"73":1}, // SetOption needed by HA to map Tasmota devices to HA entities and triggers + "lt_st":0, // Light subtype + "se":[0], // Sensors, 0: disabled, 0..xx index in kHAssJsonSensorTypes (??) + "ver":1 // Discovery protocol version, must be 1 +} +``` From f412792e17d811ac86b06003cfdd02fe427d2419 Mon Sep 17 00:00:00 2001 From: Tristan Date: Wed, 20 Dec 2023 10:35:32 +0100 Subject: [PATCH 3/4] Update Home-Assistant.md --- docs/Home-Assistant.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Home-Assistant.md b/docs/Home-Assistant.md index eebae8bb19..d4cc2e0d79 100644 --- a/docs/Home-Assistant.md +++ b/docs/Home-Assistant.md @@ -11,7 +11,7 @@ Tasmota communicates with Home Assistant using MQTT. Before going any further, m Home Assistant can add Tasmota devices using: 1. Official Tasmota integration - **preferred** and automatic instant discovery of entities -2. Deprecated legacy discovery format `SetOption19` +2. Legacy Home Assistant discovery format **deprecated** 3. Manual configuration by editing configuration.yaml - recommended for marginal use cases, e.g., TuyaMCU fan devices ## Tasmota Integration From fce63f3e8924fb4454738184130fa3cded10d440 Mon Sep 17 00:00:00 2001 From: Tristan Date: Wed, 20 Dec 2023 10:55:09 +0100 Subject: [PATCH 4/4] Update Auto-Discovery.md --- docs/Auto-Discovery.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/Auto-Discovery.md b/docs/Auto-Discovery.md index b71fb54508..7f6e14f4da 100644 --- a/docs/Auto-Discovery.md +++ b/docs/Auto-Discovery.md @@ -16,26 +16,24 @@ Topic: `tasmota/discovery/49A3BC` Payload: ``` { - "ip":"192.168.15.10", // IP address + "btn":[0,0,0,0], // Buttons, 0: disabled: 1: enabled "dn":"Living Room", // Device name + "ip":"192.168.15.10", // IP address "fn":["Ceiling Lamp", "Floor Lamp"], // List of friendly names + "ft":"%prefix%/%topic%/", // Fulltopic "hn":"tasmota_49A3BC-0956", // Hostname - "id":"49A3BC", // ChipID + "mac":"49A3BC873A78", // MAC address "md":"Sonoff Dual", // Module - "of":"Offline", // D_OFFLINE - "on":"Online", // D_ONLINE - "st":["OFF","ON","TOGGLE","HOLD"], // StateText[0..3] - "bd":"8.4.0.2", // Tasmota SW build version - "t":"tasmota_49A3BC", // Topic - "ft":"%prefix%/%topic%/", // Fulltopic - "tp":["cmnd","stat","tele"], // [SUB_PREFIX, PUB_PREFIX, PUB_PREFIX2] - "li":[0,0,0,0,0,0,0,0], // Lights, 0: disabled, 1: Enabled + "ofln":"Offline", // D_OFFLINE + "onln":"Online", // D_ONLINE "rl":[0,0,0,0,0,0,0,0], // Relays, 0: disabled, 1: relay, 2.. future extension (fan, shutter?) - "sw":[0,0,0,0,0,0,0,0], // Switches, 0: disabled: 1: enabled - "bt":[0,0,0,0], // Buttons, 0: disabled: 1: enabled "so":{"13":0,"17":1,"30":0,"37":1,"68":0,"73":1}, // SetOption needed by HA to map Tasmota devices to HA entities and triggers + "state":["OFF","ON","TOGGLE","HOLD"], // StateText[0..3] + "sw":"13.3.0" // Tasmota SW build version + "swc":[0,0,0,0,0,0,0,0], // Switches, 0: disabled: 1: enabled + "t":"tasmota_49A3BC", // Topic + "tp":["cmnd","stat","tele"], // [SUB_PREFIX, PUB_PREFIX, PUB_PREFIX2] "lt_st":0, // Light subtype - "se":[0], // Sensors, 0: disabled, 0..xx index in kHAssJsonSensorTypes (??) "ver":1 // Discovery protocol version, must be 1 } ```