Add Auto discovery

docs/Auto-Discovery.md

@@ -0,0 +1,39 @@
+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:/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:
+```
+{
+ "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
+ "mac":"49A3BC873A78", // MAC address
+ "md":"Sonoff Dual", // Module
+ "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?)
+ "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
+ "ver":1 // Discovery protocol version, must be 1
+}
+```

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. 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
 
 [![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.