Reliability and feature pass: direct commands, discovery, lift detection

Builds on the earlier read-timeout fix with several improvements informed
by other Stagg EKG community projects.

Reliability
- Tighten retry budget in _send_command to 5s × 2 attempts (~10.5s worst
  case) so the executor doesn't fall behind the 5s poll interval.
- Add KettleTransientError parent class with KettleResponseError sibling;
  malformed kettle responses now soft-fail the same way timeouts do.
- Cap stale-state retention at 6 consecutive transient failures so an
  actually-offline kettle eventually shows unavailable in HA.
- Raise instead of silently using mode="Unknown" when the kettle returns
  a truncated state payload.

Features
- Direct temperature setting via `setsetting settempr <F>` as the new
  default, replacing up to 150 dial-step commands with one HTTP call.
  Falls back to dial rotation automatically if the firmware ignores the
  command, and exposes a user-selectable method in the options flow.
- Direct heat/stop via `ss S_Heat` / `ss S_Off` instead of button-2
  toggling — cleaner state transitions, no toggle-direction ambiguity.
- LAN auto-discovery in the config flow: scans the HA host's /24 for
  kettles and presents found IPs as a dropdown, with manual entry as a
  fallback.
- New "Lifted" binary sensor with a 90s cooldown, edge-triggered on
  docked → undocked transitions.

Cosmetic
- Dynamic mdi:kettle ↔ mdi:kettle-steam icon on the Mode sensor while
  heating.
- Move the standalone stagg_ekg_api.py and its examples doc into
  examples/ so the integration root is just the HA component.

Author: rderewianko

README.md

@@ -211,7 +211,7 @@ name: Coffee Kettle
 
 ## Standalone Python API
 
-The repository includes a standalone Python API (`stagg_ekg_api.py`) for use outside Home Assistant.
+The repository includes a standalone Python API in [`examples/stagg_ekg_api.py`](examples/stagg_ekg_api.py) for use outside Home Assistant.
 
 ### Quick Start
 
@@ -229,7 +229,7 @@ state = kettle.get_state()
 print(f"Current: {state.current_temp_c}°C / Target: {state.set_temp_c}°C")
 ```
 
-See [PYTHON_API_EXAMPLES.md](PYTHON_API_EXAMPLES.md) for complete usage examples.
+See [examples/README.md](examples/README.md) for complete usage examples.
 
 ## Technical Details
 

custom_components/fellow/__init__.py

@@ -8,9 +8,22 @@
 from homeassistant.const import Platform
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
+from homeassistant.util import dt as dt_util
 
 from .const import DOMAIN
-from .kettle import KettleTimeoutError, StaggEKGClient
+from .kettle import KettleTransientError, StaggEKGClient
+
+# After this many consecutive transient failures, give up holding the
+# last known state and let HA mark the device unavailable. At a 5s poll
+# interval that's roughly half a minute of staleness — long enough to
+# absorb the "kettle just turned off" window, short enough that a truly
+# offline kettle doesn't show stale data forever.
+MAX_CONSECUTIVE_TRANSIENT_FAILURES = 6
+
+# Lift-detection: once we observe the kettle leaving the base, treat it
+# as "lifted" for at least this long, even if a brief docked reading
+# appears (the kettle can flap as it's set back down).
+LIFT_COOLDOWN_SECONDS = 90
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -19,12 +32,23 @@
 
 async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Set up Stagg EKG from a config entry."""
-    from .const import CONF_TEMPERATURE_UNIT, UNIT_CELSIUS
+    from .const import (
+        CONF_TEMP_SET_METHOD,
+        CONF_TEMPERATURE_UNIT,
+        TEMP_METHOD_DIRECT,
+        UNIT_CELSIUS,
+    )
 
     host = entry.data["host"]
+    # Options take precedence over the original entry data so changes from
+    # the options flow apply without re-adding the integration.
+    temp_method = entry.options.get(
+        CONF_TEMP_SET_METHOD,
+        entry.data.get(CONF_TEMP_SET_METHOD, TEMP_METHOD_DIRECT),
+    )
 
     # Create API client
-    client = StaggEKGClient(host=host)
+    client = StaggEKGClient(host=host, temp_method=temp_method)
 
     # Sync kettle units with configured preference
     configured_unit = entry.data.get(CONF_TEMPERATURE_UNIT, UNIT_CELSIUS)
@@ -49,9 +73,18 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     # Forward setup to platforms
     await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
 
+    # Reload when options change so settings like temp_set_method take
+    # effect without an HA restart.
+    entry.async_on_unload(entry.add_update_listener(_async_update_listener))
+
     return True
 
 
+async def _async_update_listener(hass: HomeAssistant, entry: ConfigEntry) -> None:
+    """Reload the integration when the user changes options."""
+    await hass.config_entries.async_reload(entry.entry_id)
+
+
 async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Unload a config entry."""
     if unload_ok := await hass.config_entries.async_unload_platforms(entry, PLATFORMS):
@@ -66,6 +99,9 @@ class StaggEKGDataUpdateCoordinator(DataUpdateCoordinator):
     def __init__(self, hass: HomeAssistant, client: StaggEKGClient) -> None:
         """Initialize."""
         self.client = client
+        self._consecutive_transient_failures = 0
+        self._was_docked: bool | None = None
+        self._lifted_at = None
 
         super().__init__(
             hass,
@@ -74,21 +110,55 @@ def __init__(self, hass: HomeAssistant, client: StaggEKGClient) -> None:
             update_interval=timedelta(seconds=5),
         )
 
+    @property
+    def recently_lifted(self) -> bool:
+        """Whether the kettle was lifted off the base in the recent past.
+
+        Edge-triggered on docked → undocked, with a cooldown window so a
+        single flapping reading after re-docking doesn't immediately clear
+        the signal.
+        """
+        if self._lifted_at is None:
+            return False
+        return (
+            dt_util.utcnow() - self._lifted_at
+        ).total_seconds() < LIFT_COOLDOWN_SECONDS
+
     async def _async_update_data(self):
         """Fetch data from API."""
         try:
             state = await self.hass.async_add_executor_job(self.client.get_state)
-
-            return {
-                "state": state,
-            }
-        except KettleTimeoutError as err:
-            # The kettle stops answering HTTP for a few seconds when it
-            # transitions to Off. Keep the last known state instead of
-            # surfacing an error every time that happens.
-            if self.data is not None:
-                _LOGGER.debug("Kettle unresponsive, keeping last state: %s", err)
+        except KettleTransientError as err:
+            # The kettle stops answering HTTP (or returns truncated data)
+            # for a few seconds when it transitions to Off. Hold the last
+            # known state for a while instead of surfacing an error every
+            # time that happens — but give up after enough consecutive
+            # failures so HA can mark the device unavailable if it really
+            # is offline.
+            self._consecutive_transient_failures += 1
+            if (
+                self.data is not None
+                and self._consecutive_transient_failures
+                <= MAX_CONSECUTIVE_TRANSIENT_FAILURES
+            ):
+                _LOGGER.debug(
+                    "Kettle transient failure %d/%d, keeping last state: %s",
+                    self._consecutive_transient_failures,
+                    MAX_CONSECUTIVE_TRANSIENT_FAILURES,
+                    err,
+                )
                 return self.data
             raise UpdateFailed(f"Kettle unresponsive: {err}")
         except Exception as err:
             raise UpdateFailed(f"Error communicating with API: {err}")
+
+        self._consecutive_transient_failures = 0
+
+        # Track docked → undocked transition for lift detection. We only
+        # care about the falling edge; the cooldown window in
+        # `recently_lifted` handles re-dock flapping.
+        if self._was_docked and not state.is_docked:
+            self._lifted_at = dt_util.utcnow()
+        self._was_docked = state.is_docked
+
+        return {"state": state}

custom_components/fellow/binary_sensor.py

@@ -25,6 +25,7 @@ async def async_setup_entry(
     entities = [
         StaggEKGPowerBinarySensor(coordinator, entry),
         StaggEKGWaterBinarySensor(coordinator, entry),
+        StaggEKGLiftedBinarySensor(coordinator, entry),
     ]
 
     async_add_entities(entities)
@@ -86,6 +87,26 @@ def extra_state_attributes(self):
         return {}
 
 
+class StaggEKGLiftedBinarySensor(StaggEKGBinarySensorBase):
+    """Binary sensor that fires when the kettle is taken off the base."""
+
+    _attr_device_class = BinarySensorDeviceClass.MOVING
+
+    def __init__(
+        self, coordinator: StaggEKGDataUpdateCoordinator, entry: ConfigEntry
+    ) -> None:
+        """Initialize the binary sensor."""
+        super().__init__(coordinator, entry)
+        self._attr_unique_id = f"{entry.entry_id}_lifted"
+        self._attr_name = "Lifted"
+        self._attr_icon = "mdi:kettle-pour-over"
+
+    @property
+    def is_on(self) -> bool:
+        """Return true if the kettle was recently lifted from the base."""
+        return self.coordinator.recently_lifted
+
+
 class StaggEKGWaterBinarySensor(StaggEKGBinarySensorBase):
     """Binary sensor for water detection."""
 

custom_components/fellow/config_flow.py

@@ -13,14 +13,27 @@
 from homeassistant.exceptions import HomeAssistantError
 import homeassistant.helpers.config_validation as cv
 
-from .const import DOMAIN, CONF_TEMPERATURE_UNIT, UNIT_CELSIUS, UNIT_FAHRENHEIT
+from .const import (
+    CONF_TEMP_SET_METHOD,
+    CONF_TEMPERATURE_UNIT,
+    DOMAIN,
+    TEMP_METHOD_DIAL,
+    TEMP_METHOD_DIRECT,
+    UNIT_CELSIUS,
+    UNIT_FAHRENHEIT,
+)
+from .discovery import discover_kettles
 from .kettle import StaggEKGClient
 
 _LOGGER = logging.getLogger(__name__)
 
-STEP_USER_DATA_SCHEMA = vol.Schema(
+# Sentinel option in the discovery picker that means "skip the list and
+# enter an IP by hand."
+MANUAL_HOST_CHOICE = "manual"
+
+STEP_MANUAL_DATA_SCHEMA = vol.Schema(
     {
-        vol.Required(CONF_HOST, default="10.1.1.177"): str,
+        vol.Required(CONF_HOST): str,
         vol.Required(CONF_TEMPERATURE_UNIT, default=UNIT_CELSIUS): vol.In(
             [UNIT_CELSIUS, UNIT_FAHRENHEIT]
         ),
@@ -51,10 +64,64 @@ class ConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
 
     VERSION = 1
 
+    def __init__(self) -> None:
+        """Initialize config flow state."""
+        self._discovered: list[str] = []
+
     async def async_step_user(
         self, user_input: dict[str, Any] | None = None
     ) -> FlowResult:
-        """Handle the initial step."""
+        """Run discovery first, then route to the picker or manual entry."""
+        self._discovered = await discover_kettles(self.hass)
+        if self._discovered:
+            return await self.async_step_pick()
+        return await self.async_step_manual()
+
+    async def async_step_pick(
+        self, user_input: dict[str, Any] | None = None
+    ) -> FlowResult:
+        """Let the user choose a discovered kettle or fall through to manual entry."""
+        errors: dict[str, str] = {}
+        if user_input is not None:
+            choice = user_input[CONF_HOST]
+            if choice == MANUAL_HOST_CHOICE:
+                return await self.async_step_manual()
+            data = {
+                CONF_HOST: choice,
+                CONF_TEMPERATURE_UNIT: user_input[CONF_TEMPERATURE_UNIT],
+            }
+            try:
+                info = await validate_input(self.hass, data)
+            except CannotConnect:
+                errors["base"] = "cannot_connect"
+            except Exception:  # pylint: disable=broad-except
+                _LOGGER.exception("Unexpected exception")
+                errors["base"] = "unknown"
+            else:
+                return self.async_create_entry(title=info["title"], data=data)
+
+        host_options = {ip: ip for ip in self._discovered}
+        host_options[MANUAL_HOST_CHOICE] = "Enter IP manually"
+
+        return self.async_show_form(
+            step_id="pick",
+            data_schema=vol.Schema(
+                {
+                    vol.Required(CONF_HOST, default=self._discovered[0]): vol.In(
+                        host_options
+                    ),
+                    vol.Required(
+                        CONF_TEMPERATURE_UNIT, default=UNIT_CELSIUS
+                    ): vol.In([UNIT_CELSIUS, UNIT_FAHRENHEIT]),
+                }
+            ),
+            errors=errors,
+        )
+
+    async def async_step_manual(
+        self, user_input: dict[str, Any] | None = None
+    ) -> FlowResult:
+        """Manual host entry (used when discovery finds nothing or user opts out)."""
         errors: dict[str, str] = {}
         if user_input is not None:
             try:
@@ -68,7 +135,7 @@ async def async_step_user(
                 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
+            step_id="manual", data_schema=STEP_MANUAL_DATA_SCHEMA, errors=errors
         )
 
     @staticmethod
@@ -109,6 +176,9 @@ async def async_step_init(
             return self.async_create_entry(title="", data={})
 
         current_unit = self.config_entry.data.get(CONF_TEMPERATURE_UNIT, UNIT_CELSIUS)
+        current_method = self.config_entry.data.get(
+            CONF_TEMP_SET_METHOD, TEMP_METHOD_DIRECT
+        )
 
         return self.async_show_form(
             step_id="init",
@@ -118,6 +188,10 @@ async def async_step_init(
                         CONF_TEMPERATURE_UNIT,
                         default=current_unit
                     ): vol.In([UNIT_CELSIUS, UNIT_FAHRENHEIT]),
+                    vol.Required(
+                        CONF_TEMP_SET_METHOD,
+                        default=current_method,
+                    ): vol.In([TEMP_METHOD_DIRECT, TEMP_METHOD_DIAL]),
                 }
             ),
         )

custom_components/fellow/const.py

@@ -4,11 +4,18 @@
 
 # Configuration
 CONF_TEMPERATURE_UNIT = "temperature_unit"
+CONF_TEMP_SET_METHOD = "temp_set_method"
 
 # Temperature units (matches kettle's internal values)
 UNIT_CELSIUS = "celsius"
 UNIT_FAHRENHEIT = "fahrenheit"
 
+# Temperature-setting methods
+# - direct: single `setsetting settempr <F>` firmware command (fast, preferred)
+# - dial:   emulate physical dial via left/right step commands (compatible fallback)
+TEMP_METHOD_DIRECT = "direct"
+TEMP_METHOD_DIAL = "dial"
+
 # Temperature limits (verified from kettle hardware)
 MIN_TEMP_C = 40  # Minimum kettle can be set to
 MAX_TEMP_C = 100  # Maximum (boiling point)