Change instructions for unlocking Broadlink devices (#42023)

homeassistant/components/broadlink/config_flow.py

@@ -94,23 +94,21 @@ class BroadlinkFlowHandler(config_entries.ConfigFlow, domain=DOMAIN):
             else:
                 device.timeout = timeout
 
-                if self.unique_id is None:
+                if self.source != "reauth":
                     await self.async_set_device(device)
                     self._abort_if_unique_id_configured(
                         updates={CONF_HOST: device.host[0], CONF_TIMEOUT: timeout}
                     )
                     return await self.async_step_auth()
 
-                # The user came from a factory reset.
-                # We need to check whether the host is correct.
                 if device.mac == self.device.mac:
                     await self.async_set_device(device, raise_on_progress=False)
                     return await self.async_step_auth()
 
                 errors["base"] = "invalid_host"
                 err_msg = (
-                    "Invalid host for this configuration flow. The MAC address should be "
-                    f"{format_mac(self.device.mac)}, but {format_mac(device.mac)} was given"
+                    "This is not the device you are looking for. The MAC "
+                    f"address must be {format_mac(self.device.mac)}"
                 )
 
             _LOGGER.error("Failed to connect to the device at %s: %s", host, err_msg)
@@ -161,10 +159,10 @@ class BroadlinkFlowHandler(config_entries.ConfigFlow, domain=DOMAIN):
             await self.async_set_unique_id(device.mac.hex())
             if self.source == config_entries.SOURCE_IMPORT:
                 _LOGGER.warning(
-                    "The %s at %s is ready to be configured. Please "
-                    "click Configuration in the sidebar and click "
-                    "Integrations. Then find the device there and click "
-                    "Configure to finish the setup",
+                    "%s (%s at %s) is ready to be configured. Click "
+                    "Configuration in the sidebar, click Integrations and "
+                    "click Configure on the device to complete the setup",
+                    device.name,
                     device.model,
                     device.host[0],
                 )
@@ -183,14 +181,23 @@ class BroadlinkFlowHandler(config_entries.ConfigFlow, domain=DOMAIN):
         """Guide the user to unlock the device manually.
 
         We are unable to authenticate because the device is locked.
-        The user needs to factory reset the device to make it work
-        with Home Assistant.
+        The user needs to open the Broadlink app and unlock the device.
         """
+        device = self.device
+
         if user_input is None:
-            return self.async_show_form(step_id="reset", errors=errors)
+            return self.async_show_form(
+                step_id="reset",
+                errors=errors,
+                description_placeholders={
+                    "name": device.name,
+                    "model": device.model,
+                    "host": device.host[0],
+                },
+            )
 
         return await self.async_step_user(
-            {CONF_HOST: self.device.host[0], CONF_TIMEOUT: self.device.timeout}
+            {CONF_HOST: device.host[0], CONF_TIMEOUT: device.timeout}
         )
 
     async def async_step_unlock(self, user_input=None):
@@ -237,7 +244,14 @@ class BroadlinkFlowHandler(config_entries.ConfigFlow, domain=DOMAIN):
 
         data_schema = {vol.Required("unlock", default=False): bool}
         return self.async_show_form(
-            step_id="unlock", data_schema=vol.Schema(data_schema), errors=errors
+            step_id="unlock",
+            errors=errors,
+            data_schema=vol.Schema(data_schema),
+            description_placeholders={
+                "name": device.name,
+                "model": device.model,
+                "host": device.host[0],
+            },
         )
 
     async def async_step_finish(self, user_input=None):

homeassistant/components/broadlink/device.py

@@ -74,6 +74,7 @@ class BroadlinkDevice:
             name=config.title,
         )
         api.timeout = config.data[CONF_TIMEOUT]
+        self.api = api
 
         try:
             await self.hass.async_add_executor_job(api.auth)
@@ -91,7 +92,6 @@ class BroadlinkDevice:
             )
             return False
 
-        self.api = api
         self.authorized = True
 
         update_manager = get_update_manager(self)
@@ -165,8 +165,12 @@ class BroadlinkDevice:
         self.authorized = False
 
         _LOGGER.error(
-            "The device at %s is locked for authentication. Follow the configuration flow to unlock it",
-            self.config.data[CONF_HOST],
+            "%s (%s at %s) is locked. Click Configuration in the sidebar, "
+            "click Integrations, click Configure on the device and follow "
+            "the instructions to unlock it",
+            self.name,
+            self.api.model,
+            self.api.host[0],
         )
 
         self.hass.async_create_task(

homeassistant/components/broadlink/strings.json

@@ -14,11 +14,11 @@
       },
       "reset": {
         "title": "Unlock the device",
-        "description": "Your device is locked for authentication. Follow the instructions to unlock it:\n1. Factory reset the device.\n2. Use the official app to add the device to your local network.\n3. Stop. Do not finish the setup. Close the app.\n4. Click Submit."
+        "description": "{name} ({model} at {host}) is locked. You need to unlock the device in order to authenticate and complete the configuration. Instructions:\n1. Open the Broadlink app.\n2. Click on the device.\n3. Click `...` in the upper right.\n4. Scroll to the bottom of the page.\n5. Disable the lock."
       },
       "unlock": {
         "title": "Unlock the device (optional)",
-        "description": "Your device is locked. This can lead to authentication problems in Home Assistant. Would you like to unlock it?",
+        "description": "{name} ({model} at {host}) is locked. This can lead to authentication problems in Home Assistant. Would you like to unlock it?",
         "data": {
           "unlock": "Yes, do it."
         }

homeassistant/components/broadlink/translations/en.json

@@ -25,14 +25,14 @@
                 "title": "Choose a name for the device"
             },
             "reset": {
-                "description": "Your device is locked for authentication. Follow the instructions to unlock it:\n1. Factory reset the device.\n2. Use the official app to add the device to your local network.\n3. Stop. Do not finish the setup. Close the app.\n4. Click Submit.",
+                "description": "{name} ({model} at {host}) is locked. You need to unlock the device in order to authenticate and complete the configuration. Instructions:\n1. Open the Broadlink app.\n2. Click on the device.\n3. Click `...` in the upper right.\n4. Scroll to the bottom of the page.\n5. Disable the lock.",
                 "title": "Unlock the device"
             },
             "unlock": {
                 "data": {
                     "unlock": "Yes, do it."
                 },
-                "description": "Your device is locked. This can lead to authentication problems in Home Assistant. Would you like to unlock it?",
+                "description": "{name} ({model} at {host}) is locked. This can lead to authentication problems in Home Assistant. Would you like to unlock it?",
                 "title": "Unlock the device (optional)"
             },
             "user": {

tests/components/broadlink/test_config_flow.py

@@ -334,7 +334,7 @@ async def test_flow_auth_os_error(hass):
 
 
 async def test_flow_reset_works(hass):
-    """Test we finish a config flow after a factory reset."""
+    """Test we finish a config flow after a manual unlock."""
     device = get_device("Living Room")
     mock_api = device.get_mock_api()
     mock_api.auth.side_effect = blke.AuthenticationError()