Update documentation for new config flow.

README.md

@@ -57,57 +57,99 @@ Installation is via the [Home Assistant Community Store (HACS)](https://hacs.xyz
 
 ## Configuration
 
-You can easily configure your devices using the Integrations UI at `Home Assistant > Configuration > Integrations > +`. This is the preferred method as the configuration can be migrated as this integration evovles.  You will need to provide your device's IP address, device ID and local key; the last two can be found using [the instructions below](#finding-your-device-id-and-local-key).
+You can easily configure your devices using the Integrations UI at `Home Assistant > Configuration > Integrations > +`.
 
+### Configuration
 
-### Configuration variables
+#### Stage One
 
-#### name
+The first stage of configuration is to provide the information needed to
+connect to the device.
 
-    _(string) (Required)_ Any unique name for the device; required because the Tuya API doesn't provide the one you set in the app.
+You will need to provide your device's IP address or hostname, device ID and local key; the last two can be found using [the instructions below](#finding-your-device-id-and-local-key).
 
-#### host
+##### host
 
     _(string) (Required)_ IP or hostname of the device.
 
-#### device_id
+##### device_id
 
     _(string) (Required)_ Device ID retrieved
 [as per the instructions below](#finding-your-device-id-and-local-key).
 
-#### local_key
+##### local_key
 
     _(string) (Required)_ Local key retrieved
 [as per the instructions below](#finding-your-device-id-and-local-key).
 
-#### type
+At the end of this step, an attempt is made to connect to the device and see if
+it returns any data. For tuya protocol version 3.3 devices, success
+at this point indicates that all settings you have supplied are correct, but
+for protocol version 3.1 devices, the local key is only used for sending
+commands to the device, so if your local key is incorrect the setup will
+appear to work, and you will not see any problems until you try to control
+your device.  Note that each time you pair the device, the local key changes,
+so if you obtained the local key using the instructions linked above, then
+repaired with your manufacturer's app, then the key will have changed already.
 
-    _(string) (Optional)_ The type of Tuya device. `auto` to automatically detect the device type, or if that doesn't work, select from the available options.
+#### Stage Two
 
-#### climate
+The second stage of configuration is to select which device you are connecting.
+The list of devices offered will be limited to devices which appear to be
+at least a partial match to the data returned by the device.
 
-    _(boolean) (Optional)_ Whether to surface this appliance as a climate device. (supported for heaters, heatpumps, deprecated for fans, dehumidifiers and humidifiers which should use the fan and humidifier entities instead)
+##### type
 
-#### display_light
+    _(string) (Optional)_ The type of Tuya device.
+Select from the available options.
 
-    _(boolean) (Optional)_ Whether to surface this appliance's LED display control as a light (not supported for Kogan, Andersson, Eurom, GECO or GPCV Heaters, or switches).  This is likely to change in future to `light`, to make way for lights which are not secondary lighting on another device.
+If you pick the wrong type, you will need to delete the device and set it up
+again.
 
-#### child_lock
+#### Stage Three
 
-    _(boolean) (Optional)_ Whether to surface this appliances's child lock as a lock device (not supported for fans, switches, or Andersson ,Eurom, Purline heaters or Garden PAC heatpumps). This is likely to change in future to `lock`, to make way for locks which are not secondary child locks on another device.
+The final stage is to choose a name for the device in Home Assistant, and
+select which entities you want to enable.  The options availble will depend
+on the capabilities of the device you selected in the previous step.
 
-#### switch
+Usually you will want to accept the defaults at this step.  Entities are
+selected by default, unless they are a deprecated alternative way of
+controlling the device (such as a climate entity for dehumidifiers as an
+alternative to humidifier and fan entities).  If you have multiple devices
+of the same type, you may want to change the name to make it easier to
+distinguish them.
 
-    _(boolean) (Optional)_ Whether to surface this device as a switch device (supported only for switches, Purline heaters for the Open Window Detection and Eanons humidifiers for the UV Sterilzation)
+##### name
 
-#### humidifier
+    _(string) (Required)_ Any unique name for the device.
+This will be used as the base for the entitiy names in Home Assistant.
+Although Home Assistant allows you to change the name later, it will only
+change the name used in the UI, not the name of the entities.
+
+##### climate
+
+    _(boolean) (Optional)_ Whether to surface this device as a climate device. (supported for heaters, heatpumps, deprecated for fans, dehumidifiers and humidifiers which should use the fan and humidifier entities instead)
+
+##### humidifier
 
     _(boolean) (Optional)_ Whether to surface this device as a humidifier device (supported only for humidifiers and dehumidifiers)
 
-#### fan
+##### fan
 
     _(boolean) (Optional)_ Whether to surface this device as a fan device (supported for fans, humidifiers and dehumidifiers)
 
+##### light
+
+    _(boolean) (Optional)_ Whether to surface this device as a light.  This may be an auxiliary display light control on devices such as heaters.
+
+##### lock
+
+    _(boolean) (Optional)_ Whether to surface this device as a lock device. This may be an auxiliary lock such as a child lock for devices such as heaters.
+
+##### switch
+
+    _(boolean) (Optional)_ Whether to surface this device as a switch device. This may be a switch for an auxiliary function or a master switch for multi-function devices.
+
 ## Heater gotchas
 
 Goldair GPPH heaters have individual target temperatures for their Comfort and Eco modes, whereas Home Assistant only supports a single target temperature. Therefore, when you're in Comfort mode you will set the Comfort temperature (`5`-`35`), and when you're in Eco mode you will set the Eco temperature (`5`-`21`), just like you were using the heater's own control panel. Bear this in mind when writing automations that change the operation mode and set a temperature at the same time: you must change the operation mode _before_ setting the new target temperature, otherwise you will set the current thermostat rather than the new one.