Gate offline-tolerant startup behind an "Allow offline startup" option

Add a boolean option (default off) to the options flow so the
offline-tolerant startup is opt-in. When disabled, setup keeps the
standard ConfigEntryNotReady behavior; when enabled, an unreachable
device with cached capabilities starts unavailable instead of showing a
setup error. Capabilities are still cached unconditionally so the option
works immediately once enabled.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: st03psn

custom_components/midea_ac/__init__.py

@@ -17,8 +17,8 @@
 from msmart.device import CommercialAirConditioner as CC
 from msmart.lan import AuthenticationError
 
-from .const import (CONF_ADDITIONAL_OPERATION_MODES, CONF_CACHED_CAPS,
-                    CONF_CAPABILITY_OVERRIDES,
+from .const import (CONF_ADDITIONAL_OPERATION_MODES, CONF_ALLOW_OFFLINE_STARTUP,
+                    CONF_CACHED_CAPS, CONF_CAPABILITY_OVERRIDES,
                     CONF_DEVICE_TYPE, CONF_ENERGY_DATA_FORMAT,
                     CONF_ENERGY_DATA_SCALE, CONF_ENERGY_SENSOR, CONF_KEY,
                     CONF_MAX_CONNECTION_LIFETIME,
@@ -80,9 +80,11 @@ async def async_setup_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> b
             "Setting maximum connection lifetime to %s seconds for device ID %s.", lifetime, device.id)
         device.set_max_connection_lifetime(lifetime)
 
-    # Capabilities cached from a previous successful setup. Lets the entry start
-    # while the device is offline instead of raising ConfigEntryNotReady.
+    # Capabilities cached from a previous successful setup. When "Allow offline
+    # startup" is enabled, they let the entry start while the device is offline
+    # instead of raising ConfigEntryNotReady.
     cached_caps = config_entry.data.get(CONF_CACHED_CAPS)
+    allow_offline = config_entry.options.get(CONF_ALLOW_OFFLINE_STARTUP, False)
     reachable = True
 
     # Configure token and k1 as needed
@@ -92,9 +94,9 @@ async def async_setup_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> b
         try:
             await device.authenticate(token, key)
         except AuthenticationError as e:
-            # Without cached capabilities we cannot build entities, so keep HA's
-            # standard "retry setup" behavior.
-            if not cached_caps:
+            # Keep HA's standard "retry setup" behavior unless offline startup is
+            # allowed and we have cached capabilities to build entities from.
+            if not (allow_offline and cached_caps):
                 raise ConfigEntryNotReady(
                     "Failed to authenticate with device.") from e
             _LOGGER.warning(
@@ -117,7 +119,7 @@ async def async_setup_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> b
                     config_entry,
                     data={**config_entry.data, CONF_CACHED_CAPS: caps})
         except Exception as e:  # noqa: BLE001 - fall back to cache on any query failure
-            if not cached_caps:
+            if not (allow_offline and cached_caps):
                 raise ConfigEntryNotReady(
                     f"Failed to query device capabilities: {e}") from e
             _LOGGER.warning(

custom_components/midea_ac/config_flow.py

@@ -31,7 +31,8 @@
 from msmart.discover import CloudError, Discover
 from msmart.lan import AuthenticationError
 
-from .const import (CONF_BEEP, CONF_CAPABILITY_OVERRIDES,
+from .const import (CONF_ALLOW_OFFLINE_STARTUP, CONF_BEEP,
+                    CONF_CAPABILITY_OVERRIDES,
                     CONF_CLOUD_COUNTRY_CODES, CONF_DEFAULT_CLOUD_COUNTRY,
                     CONF_DEVICE_TYPE, CONF_ENERGY_DATA_FORMAT,
                     CONF_ENERGY_DATA_SCALE, CONF_ENERGY_SENSOR,
@@ -49,7 +50,8 @@
     CONF_MAX_CONNECTION_LIFETIME: None,
     CONF_SWING_ANGLE_RTL: False,
     CONF_CAPABILITY_OVERRIDES: "",
-    CONF_MERGE_CAPABILITY_OVERRIDES: True
+    CONF_MERGE_CAPABILITY_OVERRIDES: True,
+    CONF_ALLOW_OFFLINE_STARTUP: False
 }
 
 _DEFAULT_AC_OPTIONS = {
@@ -471,6 +473,7 @@ class MideaOptionsFlow(OptionsFlow):
                 )
             ),
             vol.Optional(CONF_MERGE_CAPABILITY_OVERRIDES): cv.boolean,
+            vol.Optional(CONF_ALLOW_OFFLINE_STARTUP): cv.boolean,
         }
     )
 

custom_components/midea_ac/const.py

@@ -27,6 +27,7 @@
 CONF_CAPABILITY_OVERRIDES = "capability_overrides"
 CONF_MERGE_CAPABILITY_OVERRIDES = "merge_capability_overrides"
 CONF_CACHED_CAPS = "cached_capabilities"
+CONF_ALLOW_OFFLINE_STARTUP = "allow_offline_startup"
 
 PRESET_IECO = "ieco"
 PRESET_SILENT = "silent"

custom_components/midea_ac/translations/de.json

@@ -78,12 +78,14 @@
           "temp_step": "Temperaturschritte",
           "fan_speed_step": "Lüftergeschwindigkeitsschritte",
           "max_connection_lifetime": "Maximale Verbindungsdauer",
-          "swing_angle_rtl": "Horizontalen Schwenkwinkel umkehren"
+          "swing_angle_rtl": "Horizontalen Schwenkwinkel umkehren",
+          "allow_offline_startup": "Offline-Start erlauben"
         },
         "data_description": {
           "temp_step": "Schrittgröße für Temperatureinstellung",
           "fan_speed_step": "Schrittgröße für Lüftergeschwindigkeit",
-          "max_connection_lifetime": "Maximale Zeit in Sekunden, die eine Verbindung verwendet wird (mindestens 15 Sekunden)"
+          "max_connection_lifetime": "Maximale Zeit in Sekunden, die eine Verbindung verwendet wird (mindestens 15 Sekunden)",
+          "allow_offline_startup": "Beim Start aus zwischengespeicherten Fähigkeiten laden, wenn das Gerät offline ist, statt einen Einrichtungsfehler anzuzeigen. Entitäten bleiben nicht verfügbar, bis das Gerät wieder verbunden ist."
         },
         "sections": {
           "energy_sensor": {

custom_components/midea_ac/translations/en.json

@@ -80,14 +80,16 @@
           "max_connection_lifetime": "Maximum Connection Lifetime",
           "swing_angle_rtl": "Reverse Horizontal Swing Angle",
           "capability_overrides": "Capability Overrides",
-          "merge_capability_overrides": "Merge Overrides"
+          "merge_capability_overrides": "Merge Overrides",
+          "allow_offline_startup": "Allow offline startup"
         },
         "data_description": {
           "temp_step": "Step size for temperature set point",
           "fan_speed_step": "Step size for custom fan speeds",
           "max_connection_lifetime": "Maximum time in seconds a connection will be used (15 second minimum)",
           "capability_overrides": "Device capability overrides in YAML format",
-          "merge_capability_overrides": "Merge overrides with existing device capabilities"
+          "merge_capability_overrides": "Merge overrides with existing device capabilities",
+          "allow_offline_startup": "Start from previously cached capabilities when the device is offline, instead of showing a setup error. Entities remain unavailable until the device reconnects."
         },
         "sections": {
           "energy_sensor": {