Improve config flow UX for clarity and reduced cognitive load

rsnodgrass · rsnodgrass · commit a14ab5eede48 · 2026-01-10T12:40:51.000-08:00
diff --git a/custom_components/lunos/config_flow.py b/custom_components/lunos/config_flow.py
@@ -120,17 +120,13 @@ def __init__(self) -> None:
         """Initialize the config flow."""
         self._coding_config: dict[str, Any] = {}
 
-    async def async_step_user(
-        self, user_input: dict[str, Any] | None = None
-    ) -> FlowResult:
+    async def async_step_user(self, user_input: dict[str, Any] | None = None) -> FlowResult:
         """Handle the initial step."""
         errors: dict[str, str] = {}
 
         # load coding configurations
         if not self._coding_config:
-            self._coding_config = await self.hass.async_add_executor_job(
-                load_lunos_codings
-            )
+            self._coding_config = await self.hass.async_add_executor_job(load_lunos_codings)
 
         coding_options = get_coding_options(self._coding_config)
 
@@ -159,9 +155,7 @@ async def async_step_user(
             errors=errors,
         )
 
-    async def async_step_import(
-        self, import_data: dict[str, Any]
-    ) -> FlowResult:
+    async def async_step_import(self, import_data: dict[str, Any]) -> FlowResult:
         """Handle import from YAML configuration."""
         # convert old LUNOS_DOMAIN to DOMAIN if needed
         name = import_data.get(CONF_NAME, DEFAULT_NAME)
@@ -206,17 +200,13 @@ def __init__(self, config_entry: ConfigEntry) -> None:
         self._config_entry = config_entry
         self._coding_config: dict[str, Any] = {}
 
-    async def async_step_init(
-        self, user_input: dict[str, Any] | None = None
-    ) -> FlowResult:
+    async def async_step_init(self, user_input: dict[str, Any] | None = None) -> FlowResult:
         """Manage the options."""
         errors: dict[str, str] = {}
 
         # load coding configurations
         if not self._coding_config:
-            self._coding_config = await self.hass.async_add_executor_job(
-                load_lunos_codings
-            )
+            self._coding_config = await self.hass.async_add_executor_job(load_lunos_codings)
 
         coding_options = get_coding_options(self._coding_config)
 
diff --git a/custom_components/lunos/coordinator.py b/custom_components/lunos/coordinator.py
@@ -145,9 +145,7 @@ def _determine_speed_from_states(
         current_state = [w1_state, w2_state]
         for speed, relay_states in self._relay_state_map.items():
             if current_state == relay_states:
-                LOG.debug(
-                    'Determined LUNOS speed=%s from W1/W2=%s', speed, current_state
-                )
+                LOG.debug('Determined LUNOS speed=%s from W1/W2=%s', speed, current_state)
                 return speed
 
         LOG.warning(
diff --git a/custom_components/lunos/fan.py b/custom_components/lunos/fan.py
@@ -200,9 +200,7 @@ def __init__(
         self._vent_modes: list[str] = []
         self._init_vent_modes(model_config)
 
-        self._default_speed = (
-            default_speed if default_speed in self._fan_speeds else DEFAULT_SPEED
-        )
+        self._default_speed = default_speed if default_speed in self._fan_speeds else DEFAULT_SPEED
 
         self._preset_modes: list[str] = []
         self._preset_mode: str | None = None
@@ -524,7 +522,7 @@ def _determine_current_relay_speed(self) -> str | None:
         w1 = self.hass.states.get(self._relay_w1)
         if not w1:
             LOG.warning(
-                "W1 entity %s not found, cannot determine %s LUNOS speed.",
+                'W1 entity %s not found, cannot determine %s LUNOS speed.',
                 self._relay_w1,
                 self._name,
             )
@@ -533,7 +531,7 @@ def _determine_current_relay_speed(self) -> str | None:
         w2 = self.hass.states.get(self._relay_w2)
         if not w2:
             LOG.warning(
-                "W2 entity %s not found, cannot determine %s LUNOS speed.",
+                'W2 entity %s not found, cannot determine %s LUNOS speed.',
                 self._relay_w2,
                 self._name,
             )
@@ -589,7 +587,7 @@ async def _throttle_state_changes(self, required_delay: float) -> bool:
             delay = max(0, required_delay - time_passed)
             LOG.warning(
                 "To avoid LUNOS '%s' controller race conditions, "
-                "sleeping %s seconds before changing relay.",
+                'sleeping %s seconds before changing relay.',
                 self._name,
                 delay,
             )
@@ -652,9 +650,7 @@ async def async_update(self) -> None:
         LOG.debug('%s async_update() = %s', self._name, actual_speed)
         self._update_speed(actual_speed)
 
-    async def async_call_switch_service(
-        self, method: str, relay_entity_id: str
-    ) -> None:
+    async def async_call_switch_service(self, method: str, relay_entity_id: str) -> None:
         """Call the appropriate service for the relay entity."""
         domain = relay_entity_id.split('.', 1)[0]
         # Backward-compatible: original versions assumed relays were always switch entities.
diff --git a/custom_components/lunos/strings.json b/custom_components/lunos/strings.json
@@ -2,81 +2,81 @@
   "config": {
     "step": {
       "user": {
-        "title": "Configure LUNOS Ventilation Fan",
-        "description": "Set up your LUNOS Heat Recovery Ventilation fan control.",
+        "title": "Add LUNOS Fan",
+        "description": "Connect your LUNOS ventilation fan to Home Assistant.",
         "data": {
           "name": "Name",
-          "relay_w1": "W1 Relay Switch",
-          "relay_w2": "W2 Relay Switch",
-          "controller_coding": "Controller Coding",
-          "fan_count": "Number of Fans",
-          "default_speed": "Default Speed"
+          "relay_w1": "First Relay (W1)",
+          "relay_w2": "Second Relay (W2)",
+          "controller_coding": "Fan Model",
+          "fan_count": "Fan Count",
+          "default_speed": "Startup Speed"
         },
         "data_description": {
-          "relay_w1": "Switch entity connected to the W1 terminal on the LUNOS controller",
-          "relay_w2": "Switch entity connected to the W2 terminal on the LUNOS controller",
-          "controller_coding": "The coding setting configured on your LUNOS controller hardware",
-          "fan_count": "Number of LUNOS fans connected to this controller",
-          "default_speed": "Default fan speed when turned on without specifying a speed"
+          "relay_w1": "Select the switch entity controlling your first LUNOS relay.",
+          "relay_w2": "Select the switch entity controlling your second LUNOS relay.",
+          "controller_coding": "Select your LUNOS fan model. Check your controller's DIP switches if unsure.",
+          "fan_count": "Number of fan units (most installations have 2).",
+          "default_speed": "Speed used when turning on without specifying. Medium works for most homes."
         }
       }
     },
     "error": {
-      "same_relay": "W1 and W2 relays must be different entities",
+      "same_relay": "Both relays must be different switch entities.",
       "unknown": "An unexpected error occurred"
     },
     "abort": {
-      "already_configured": "This LUNOS fan controller is already configured",
+      "already_configured": "A LUNOS fan with these relays already exists.",
       "missing_relays": "YAML configuration must include both relay_w1 and relay_w2"
     }
   },
   "options": {
     "step": {
       "init": {
-        "title": "LUNOS Fan Options",
+        "title": "LUNOS Fan Settings",
         "description": "Adjust your LUNOS fan configuration.",
         "data": {
           "name": "Name",
-          "relay_w1": "W1 Relay Switch",
-          "relay_w2": "W2 Relay Switch",
-          "controller_coding": "Controller Coding",
-          "fan_count": "Number of Fans",
-          "default_speed": "Default Speed"
+          "relay_w1": "First Relay (W1)",
+          "relay_w2": "Second Relay (W2)",
+          "controller_coding": "Fan Model",
+          "fan_count": "Fan Count",
+          "default_speed": "Startup Speed"
         },
         "data_description": {
-          "relay_w1": "Switch entity connected to the W1 terminal on the LUNOS controller",
-          "relay_w2": "Switch entity connected to the W2 terminal on the LUNOS controller",
-          "controller_coding": "The coding setting configured on your LUNOS controller hardware",
-          "fan_count": "Number of LUNOS fans connected to this controller",
-          "default_speed": "Default fan speed when turned on without specifying a speed"
+          "relay_w1": "Select the switch entity controlling your first LUNOS relay.",
+          "relay_w2": "Select the switch entity controlling your second LUNOS relay.",
+          "controller_coding": "Select your LUNOS fan model. Check your controller's DIP switches if unsure.",
+          "fan_count": "Number of fan units (most installations have 2).",
+          "default_speed": "Speed used when turning on without specifying. Medium works for most homes."
         }
       }
     },
     "error": {
-      "same_relay": "W1 and W2 relays must be different entities"
+      "same_relay": "Both relays must be different switch entities."
     }
   },
   "selector": {
     "controller_coding": {
       "options": {
-        "e2": "LUNOS e2 (non-USA)",
-        "e2-4speed": "LUNOS e2 (4-speed)",
-        "e2-short": "LUNOS e2 Short (non-USA)",
-        "e2-usa": "LUNOS e2 (USA)",
-        "e2-usa-v2": "LUNOS e2 v2 (USA)",
-        "e2-short-usa": "LUNOS e2 Short (USA)",
-        "e2-nz": "LUNOS e2 (New Zealand)",
-        "e2-mini": "LUNOS e2 Mini",
-        "e2-60": "LUNOS e2 60",
-        "ego": "LUNOS eGO",
-        "ego-4speed": "LUNOS eGO (4-speed)",
-        "ego-exhaust-4speed": "LUNOS eGO (high=exhaust-only 4-speed)",
-        "ego-exhaust": "LUNOS eGO (high=exhaust-only)",
-        "ra-15-60": "LUNOS RA 15-60 radial duct fan",
-        "ra-15-60-high": "LUNOS RA 15-60 radial duct fan (Extra High)",
-        "ra-15-60-4speed": "LUNOS RA 15-60 radial duct fan (4-speed)",
-        "e2-60-d": "LUNOS e2 60 D",
-        "e2-60-short": "LUNOS e2 60 Short"
+        "e2": "e2 (non-USA)",
+        "e2-4speed": "e2 (4-speed)",
+        "e2-short": "e2 Short (non-USA)",
+        "e2-usa": "e2 (USA)",
+        "e2-usa-v2": "e2 v2 (USA)",
+        "e2-short-usa": "e2 Short (USA)",
+        "e2-nz": "e2 (New Zealand)",
+        "e2-mini": "e2 Mini",
+        "e2-60": "e2 60",
+        "ego": "eGO",
+        "ego-4speed": "eGO (4-speed)",
+        "ego-exhaust-4speed": "eGO (high=exhaust-only 4-speed)",
+        "ego-exhaust": "eGO (high=exhaust-only)",
+        "ra-15-60": "RA 15-60 radial duct fan",
+        "ra-15-60-high": "RA 15-60 radial duct fan (Extra High)",
+        "ra-15-60-4speed": "RA 15-60 radial duct fan (4-speed)",
+        "e2-60-d": "e2 60 D",
+        "e2-60-short": "e2 60 Short"
       }
     },
     "fan_speed": {
diff --git a/custom_components/lunos/translations/en.json b/custom_components/lunos/translations/en.json
@@ -2,81 +2,81 @@
   "config": {
     "step": {
       "user": {
-        "title": "Configure LUNOS Ventilation Fan",
-        "description": "Set up your LUNOS Heat Recovery Ventilation fan control.",
+        "title": "Add LUNOS Fan",
+        "description": "Connect your LUNOS ventilation fan to Home Assistant.",
         "data": {
           "name": "Name",
-          "relay_w1": "W1 Relay Switch",
-          "relay_w2": "W2 Relay Switch",
-          "controller_coding": "Controller Coding",
-          "fan_count": "Number of Fans",
-          "default_speed": "Default Speed"
+          "relay_w1": "First Relay (W1)",
+          "relay_w2": "Second Relay (W2)",
+          "controller_coding": "Fan Model",
+          "fan_count": "Fan Count",
+          "default_speed": "Startup Speed"
         },
         "data_description": {
-          "relay_w1": "Switch entity connected to the W1 terminal on the LUNOS controller",
-          "relay_w2": "Switch entity connected to the W2 terminal on the LUNOS controller",
-          "controller_coding": "The coding setting configured on your LUNOS controller hardware",
-          "fan_count": "Number of LUNOS fans connected to this controller",
-          "default_speed": "Default fan speed when turned on without specifying a speed"
+          "relay_w1": "Select the switch entity controlling your first LUNOS relay.",
+          "relay_w2": "Select the switch entity controlling your second LUNOS relay.",
+          "controller_coding": "Select your LUNOS fan model. Check your controller's DIP switches if unsure.",
+          "fan_count": "Number of fan units (most installations have 2).",
+          "default_speed": "Speed used when turning on without specifying. Medium works for most homes."
         }
       }
     },
     "error": {
-      "same_relay": "W1 and W2 relays must be different entities",
+      "same_relay": "Both relays must be different switch entities.",
       "unknown": "An unexpected error occurred"
     },
     "abort": {
-      "already_configured": "This LUNOS fan controller is already configured",
+      "already_configured": "A LUNOS fan with these relays already exists.",
       "missing_relays": "YAML configuration must include both relay_w1 and relay_w2"
     }
   },
   "options": {
     "step": {
       "init": {
-        "title": "LUNOS Fan Options",
+        "title": "LUNOS Fan Settings",
         "description": "Adjust your LUNOS fan configuration.",
         "data": {
           "name": "Name",
-          "relay_w1": "W1 Relay Switch",
-          "relay_w2": "W2 Relay Switch",
-          "controller_coding": "Controller Coding",
-          "fan_count": "Number of Fans",
-          "default_speed": "Default Speed"
+          "relay_w1": "First Relay (W1)",
+          "relay_w2": "Second Relay (W2)",
+          "controller_coding": "Fan Model",
+          "fan_count": "Fan Count",
+          "default_speed": "Startup Speed"
         },
         "data_description": {
-          "relay_w1": "Switch entity connected to the W1 terminal on the LUNOS controller",
-          "relay_w2": "Switch entity connected to the W2 terminal on the LUNOS controller",
-          "controller_coding": "The coding setting configured on your LUNOS controller hardware",
-          "fan_count": "Number of LUNOS fans connected to this controller",
-          "default_speed": "Default fan speed when turned on without specifying a speed"
+          "relay_w1": "Select the switch entity controlling your first LUNOS relay.",
+          "relay_w2": "Select the switch entity controlling your second LUNOS relay.",
+          "controller_coding": "Select your LUNOS fan model. Check your controller's DIP switches if unsure.",
+          "fan_count": "Number of fan units (most installations have 2).",
+          "default_speed": "Speed used when turning on without specifying. Medium works for most homes."
         }
       }
     },
     "error": {
-      "same_relay": "W1 and W2 relays must be different entities"
+      "same_relay": "Both relays must be different switch entities."
     }
   },
   "selector": {
     "controller_coding": {
       "options": {
-        "e2": "LUNOS e2 (non-USA)",
-        "e2-4speed": "LUNOS e2 (4-speed)",
-        "e2-short": "LUNOS e2 Short (non-USA)",
-        "e2-usa": "LUNOS e2 (USA)",
-        "e2-usa-v2": "LUNOS e2 v2 (USA)",
-        "e2-short-usa": "LUNOS e2 Short (USA)",
-        "e2-nz": "LUNOS e2 (New Zealand)",
-        "e2-mini": "LUNOS e2 Mini",
-        "e2-60": "LUNOS e2 60",
-        "ego": "LUNOS eGO",
-        "ego-4speed": "LUNOS eGO (4-speed)",
-        "ego-exhaust-4speed": "LUNOS eGO (high=exhaust-only 4-speed)",
-        "ego-exhaust": "LUNOS eGO (high=exhaust-only)",
-        "ra-15-60": "LUNOS RA 15-60 radial duct fan",
-        "ra-15-60-high": "LUNOS RA 15-60 radial duct fan (Extra High)",
-        "ra-15-60-4speed": "LUNOS RA 15-60 radial duct fan (4-speed)",
-        "e2-60-d": "LUNOS e2 60 D",
-        "e2-60-short": "LUNOS e2 60 Short"
+        "e2": "e2 (non-USA)",
+        "e2-4speed": "e2 (4-speed)",
+        "e2-short": "e2 Short (non-USA)",
+        "e2-usa": "e2 (USA)",
+        "e2-usa-v2": "e2 v2 (USA)",
+        "e2-short-usa": "e2 Short (USA)",
+        "e2-nz": "e2 (New Zealand)",
+        "e2-mini": "e2 Mini",
+        "e2-60": "e2 60",
+        "ego": "eGO",
+        "ego-4speed": "eGO (4-speed)",
+        "ego-exhaust-4speed": "eGO (high=exhaust-only 4-speed)",
+        "ego-exhaust": "eGO (high=exhaust-only)",
+        "ra-15-60": "RA 15-60 radial duct fan",
+        "ra-15-60-high": "RA 15-60 radial duct fan (Extra High)",
+        "ra-15-60-4speed": "RA 15-60 radial duct fan (4-speed)",
+        "e2-60-d": "e2 60 D",
+        "e2-60-short": "e2 60 Short"
       }
     },
     "fan_speed": {
diff --git a/tests/test_diagnostics.py b/tests/test_diagnostics.py
