Migrate Waterfurnace to UI based config

Modernize the existing waterfurnace integration and allow
a UI based configuration option.

This initial implementation includes unit testing for the config flow.

For codeowners I have included myself, and the original author
of the integration (and owner of the waterfurnace python library).

Co-authored-by: Claude Sonnet 4.5 [email protected]

Author: masterkoppa

CODEOWNERS

@@ -1,11 +1,12 @@
-"""Support for Waterfurnaces."""
+"""Support for WaterFurnace geothermal systems."""
+
+from __future__ import annotations
 
 from datetime import timedelta
 import logging
 import threading
 import time
 
-import voluptuous as vol
 from waterfurnace.waterfurnace import WaterFurnace, WFCredentialError, WFException
 
 from homeassistant.components import persistent_notification
@@ -16,12 +17,16 @@
     Platform,
 )
 from homeassistant.core import HomeAssistant, callback
-from homeassistant.helpers import config_validation as cv, discovery
+from homeassistant.exceptions import ConfigEntryAuthFailed, ConfigEntryNotReady
+from homeassistant.helpers import discovery
 from homeassistant.helpers.dispatcher import dispatcher_send
-from homeassistant.helpers.typing import ConfigType
+
+from .models import WaterFurnaceConfigEntry
 
 _LOGGER = logging.getLogger(__name__)
 
+PLATFORMS = [Platform.SENSOR]
+
 DOMAIN = "waterfurnace"
 UPDATE_TOPIC = f"{DOMAIN}_update"
 SCAN_INTERVAL = timedelta(seconds=10)
@@ -31,40 +36,36 @@
 NOTIFICATION_TITLE = "WaterFurnace website status"
 
 
-CONFIG_SCHEMA = vol.Schema(
-    {
-        DOMAIN: vol.Schema(
-            {
-                vol.Required(CONF_PASSWORD): cv.string,
-                vol.Required(CONF_USERNAME): cv.string,
-            }
-        )
-    },
-    extra=vol.ALLOW_EXTRA,
-)
-
+async def async_setup_entry(
+    hass: HomeAssistant, entry: WaterFurnaceConfigEntry
+) -> bool:
+    """Set up WaterFurnace from a config entry."""
+    username = entry.data[CONF_USERNAME]
+    password = entry.data[CONF_PASSWORD]
 
-def setup(hass: HomeAssistant, base_config: ConfigType) -> bool:
-    """Set up waterfurnace platform."""
+    client = WaterFurnace(username, password)
 
-    config = base_config[DOMAIN]
-
-    username = config[CONF_USERNAME]
-    password = config[CONF_PASSWORD]
-
-    wfconn = WaterFurnace(username, password)
-    # NOTE(sdague): login will throw an exception if this doesn't
-    # work, which will abort the setup.
     try:
-        wfconn.login()
-    except WFCredentialError:
-        _LOGGER.error("Invalid credentials for waterfurnace login")
-        return False
-
-    hass.data[DOMAIN] = WaterFurnaceData(hass, wfconn)
+        await hass.async_add_executor_job(client.login)
+    except WFCredentialError as err:
+        _LOGGER.error("Invalid credentials for WaterFurnace device")
+        raise ConfigEntryAuthFailed(
+            "Authentication failed. Please update your credentials."
+        ) from err
+    except WFException as err:
+        _LOGGER.error("Failed to connect to WaterFurnace service: %s", err)
+        raise ConfigEntryNotReady(
+            f"Failed to connect to WaterFurnace service: {err}"
+        ) from err
+    except Exception as err:
+        _LOGGER.exception("Unexpected error during WaterFurnace setup")
+        raise ConfigEntryNotReady(f"Unexpected error during setup: {err}") from err
+
+    hass.data[DOMAIN] = WaterFurnaceData(hass, client)
     hass.data[DOMAIN].start()
 
-    discovery.load_platform(hass, Platform.SENSOR, DOMAIN, {}, config)
+    discovery.load_platform(hass, Platform.SENSOR, DOMAIN, {}, entry.as_dict())
+
     return True
 
 
@@ -79,7 +80,7 @@ class WaterFurnaceData(threading.Thread):
     to do.
     """
 
-    def __init__(self, hass, client):
+    def __init__(self, hass: HomeAssistant, client) -> None:
         """Initialize the data object."""
         super().__init__()
         self.hass = hass

homeassistant/components/waterfurnace/__init__.py

@@ -0,0 +1,161 @@
+"""Config flow for WaterFurnace integration."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import logging
+from typing import Any
+
+import voluptuous as vol
+from waterfurnace.waterfurnace import WaterFurnace, WFCredentialError, WFException
+
+from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
+from homeassistant.const import CONF_PASSWORD, CONF_USERNAME
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import HomeAssistantError
+
+from .const import DOMAIN
+
+_LOGGER = logging.getLogger(__name__)
+
+STEP_USER_DATA_SCHEMA = vol.Schema(
+    {
+        vol.Required(CONF_USERNAME): str,
+        vol.Required(CONF_PASSWORD): str,
+    }
+)
+
+
+async def validate_input(hass: HomeAssistant, data: dict[str, Any]) -> dict[str, Any]:
+    """Validate the user input allows us to connect.
+
+    Data has the keys from STEP_USER_DATA_SCHEMA with values provided by the user.
+    """
+    username = data[CONF_USERNAME]
+    password = data[CONF_PASSWORD]
+
+    client = WaterFurnace(username, password)
+
+    try:
+        # Login is a blocking call, run in executor
+        await hass.async_add_executor_job(client.login)
+    except WFCredentialError as err:
+        _LOGGER.error("Invalid credentials for WaterFurnace login")
+        raise InvalidAuth from err
+    except WFException as err:
+        _LOGGER.error("Failed to connect to WaterFurnace service: %s", err)
+        raise CannotConnect from err
+    except Exception as err:
+        _LOGGER.exception("Unexpected error connecting to WaterFurnace")
+        raise CannotConnect from err
+
+    gwid = client.gwid
+    if not gwid:
+        _LOGGER.error("No GWID found for device")
+        raise CannotConnect
+
+    return {
+        "title": f"WaterFurnace {gwid}",
+        "gwid": gwid,
+    }
+
+
+class WaterFurnaceConfigFlow(ConfigFlow, domain=DOMAIN):
+    """Handle a config flow for WaterFurnace."""
+
+    VERSION = 1
+    MINOR_VERSION = 1
+
+    def __init__(self) -> None:
+        """Initialize the config flow."""
+        self._username: str | None = None
+
+    async def async_step_user(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Handle the initial step."""
+        errors: dict[str, str] = {}
+
+        if user_input is not None:
+            try:
+                info = await validate_input(self.hass, user_input)
+            except CannotConnect:
+                errors["base"] = "cannot_connect"
+            except InvalidAuth:
+                errors["base"] = "invalid_auth"
+            except Exception:
+                _LOGGER.exception("Unexpected exception")
+                errors["base"] = "unknown"
+            else:
+                # Set unique ID based on GWID
+                await self.async_set_unique_id(info["gwid"])
+                self._abort_if_unique_id_configured()
+
+                return self.async_create_entry(
+                    title=info["title"],
+                    data=user_input,
+                )
+
+        return self.async_show_form(
+            step_id="user",
+            data_schema=STEP_USER_DATA_SCHEMA,
+            errors=errors,
+        )
+
+    async def async_step_reauth(
+        self, entry_data: Mapping[str, Any]
+    ) -> ConfigFlowResult:
+        """Handle reauth flow when credentials expire."""
+        self._username = entry_data.get(CONF_USERNAME)
+        return await self.async_step_reauth_confirm()
+
+    async def async_step_reauth_confirm(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Handle reauth confirmation step."""
+        errors: dict[str, str] = {}
+
+        if user_input is not None:
+            # Get the existing entry
+            entry = self._get_reauth_entry()
+
+            # Merge existing entry data with new credentials
+            full_input = {**entry.data, **user_input}
+
+            try:
+                info = await validate_input(self.hass, full_input)
+            except CannotConnect:
+                errors["base"] = "cannot_connect"
+            except InvalidAuth:
+                errors["base"] = "invalid_auth"
+            except Exception:
+                _LOGGER.exception("Unexpected exception")
+                errors["base"] = "unknown"
+            else:
+                # Verify the GWID matches the existing entry
+                await self.async_set_unique_id(info["gwid"])
+                self._abort_if_unique_id_mismatch(reason="wrong_account")
+
+                return self.async_update_reload_and_abort(
+                    entry,
+                    data_updates=user_input,
+                )
+
+        return self.async_show_form(
+            step_id="reauth_confirm",
+            data_schema=vol.Schema(
+                {
+                    vol.Required(CONF_USERNAME, default=self._username): str,
+                    vol.Required(CONF_PASSWORD): str,
+                }
+            ),
+            errors=errors,
+        )
+
+
+class CannotConnect(HomeAssistantError):
+    """Error to indicate we cannot connect."""
+
+
+class InvalidAuth(HomeAssistantError):
+    """Error to indicate there is invalid auth."""

homeassistant/components/waterfurnace/config_flow.py

@@ -0,0 +1,13 @@
+"""Constants for the WaterFurnace integration."""
+
+from datetime import timedelta
+from typing import Final
+
+DOMAIN: Final = "waterfurnace"
+
+# Update intervals
+SCAN_INTERVAL: Final = timedelta(seconds=10)
+ERROR_INTERVAL: Final = timedelta(seconds=300)
+
+# Connection settings
+MAX_FAILS: Final = 10

homeassistant/components/waterfurnace/const.py

@@ -1,8 +1,10 @@
 {
   "domain": "waterfurnace",
   "name": "WaterFurnace",
-  "codeowners": [],
+  "codeowners": ["@sdague", "@masterkoppa"],
+  "config_flow": true,
   "documentation": "https://www.home-assistant.io/integrations/waterfurnace",
+  "integration_type": "device",
   "iot_class": "cloud_polling",
   "loggers": ["waterfurnace"],
   "quality_scale": "legacy",

homeassistant/components/waterfurnace/manifest.json

@@ -0,0 +1,20 @@
+"""Models for the WaterFurnace integration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from waterfurnace.waterfurnace import WaterFurnace
+
+from homeassistant.config_entries import ConfigEntry
+
+
+@dataclass
+class WaterFurnaceData:
+    """Data for the WaterFurnace integration."""
+
+    client: WaterFurnace
+    gwid: str
+
+
+type WaterFurnaceConfigEntry = ConfigEntry[WaterFurnaceData]

homeassistant/components/waterfurnace/models.py

@@ -0,0 +1,41 @@
+{
+  "config": {
+    "abort": {
+      "already_configured": "This device is already configured",
+      "no_devices": "No devices found on this account",
+      "reauth_successful": "Reauthentication successful",
+      "wrong_account": "The credentials provided are for a different account"
+    },
+    "error": {
+      "cannot_connect": "Failed to connect to WaterFurnace service",
+      "invalid_auth": "Invalid username or password",
+      "unknown": "An unexpected error occurred"
+    },
+    "step": {
+      "reauth_confirm": {
+        "data": {
+          "password": "Password",
+          "username": "Username"
+        },
+        "data_description": {
+          "password": "Your new WaterFurnace Symphony account password",
+          "username": "Your WaterFurnace Symphony account username"
+        },
+        "description": "The credentials for your WaterFurnace account need to be updated.",
+        "title": "Reauthenticate WaterFurnace"
+      },
+      "user": {
+        "data": {
+          "password": "Password",
+          "username": "Username"
+        },
+        "data_description": {
+          "password": "Your WaterFurnace Symphony account password",
+          "username": "Your WaterFurnace Symphony account username"
+        },
+        "description": "Enter your WaterFurnace Symphony account credentials.",
+        "title": "Connect to WaterFurnace"
+      }
+    }
+  }
+}

homeassistant/components/waterfurnace/strings.json

@@ -7462,8 +7462,8 @@
     },
     "waterfurnace": {
       "name": "WaterFurnace",
-      "integration_type": "hub",
-      "config_flow": false,
+      "integration_type": "device",
+      "config_flow": true,
       "iot_class": "cloud_polling"
     },
     "watergate": {