fix: prevent stale HA values from overwriting writable entities

HA's MQTT Number entity defaulted to optimistic mode in the discovery
payload, so HA treated its locally cached value as authoritative and
republished it as a command on restart - the gateway then forwarded that
to the vehicle, resetting target SoC and total battery capacity (#375).
The same gap existed in select and text discovery payloads.

Mark every writable discovery payload (number, select, text) with
`optimistic: false` so HA reads state from `state_topic`, and route
number-entity commands through an eager-echo + rollback path in the
command dispatcher: capture the prior value, echo the new value to the
state topic on receipt for instant UX feedback, and republish the prior
value on failure so the UI reflects rejections.

Closes #375

Author: nanomad

src/handlers/command/base.py

@@ -53,6 +53,27 @@ def topic(cls) -> str:
     async def handle(self, payload: str) -> CommandProcessingResult:
         raise NotImplementedError
 
+    def echo_state_topic(self) -> str | None:
+        """State topic for eager echo and rollback.
+
+        Return None to disable eager echo (default).
+        """
+        return None
+
+    def capture_current_state(self) -> object | None:
+        """Snapshot the current state value for rollback on failure.
+
+        Return None to skip the rollback publish.
+        """
+        return None
+
+    def echo_payload(self, raw_payload: str) -> object | None:
+        """Convert the raw MQTT command payload to a state-topic echo value.
+
+        Return None to skip the eager publish for this call (e.g. invalid payload).
+        """
+        return raw_payload
+
     @property
     def saic_api(self) -> SaicApi:
         return self.__saic_api

src/handlers/command/drivetrain/drivetrain_soc_target.py

@@ -22,6 +22,24 @@ class DrivetrainSoCTargetCommand(PayloadConvertingCommandHandler[TargetBatteryCo
     def topic(cls) -> str:
         return mqtt_topics.DRIVETRAIN_SOC_TARGET_SET
 
+    @override
+    def echo_state_topic(self) -> str:
+        return mqtt_topics.DRIVETRAIN_SOC_TARGET
+
+    @override
+    def capture_current_state(self) -> int | None:
+        target = self.vehicle_state.target_soc
+        return None if target is None else target.percentage
+
+    @override
+    def echo_payload(self, raw_payload: str) -> int | None:
+        try:
+            return TargetBatteryCode.from_percentage(
+                int(raw_payload.strip())
+            ).percentage
+        except (ValueError, KeyError):
+            return None
+
     @staticmethod
     @override
     def convert_payload(payload: str) -> TargetBatteryCode:

src/handlers/command/drivetrain/drivetrain_total_battery_capacity.py

@@ -19,6 +19,21 @@ class DrivetrainTotalBatteryCapacitySetCommand(FloatCommandHandler):
     def topic(cls) -> str:
         return mqtt_topics.DRIVETRAIN_TOTAL_BATTERY_CAPACITY_SET
 
+    @override
+    def echo_state_topic(self) -> str:
+        return mqtt_topics.DRIVETRAIN_TOTAL_BATTERY_CAPACITY
+
+    @override
+    def capture_current_state(self) -> float | None:
+        return self.vehicle_state.vehicle.custom_battery_capacity
+
+    @override
+    def echo_payload(self, raw_payload: str) -> float | None:
+        try:
+            return float(raw_payload.strip())
+        except ValueError:
+            return None
+
     @override
     async def handle_typed_payload(self, payload: float) -> CommandProcessingResult:
         LOG.info("Setting Total Battery Capacity to %f", payload)

src/handlers/command/gateway/refresh_period.py

@@ -10,12 +10,32 @@
 import mqtt_topics
 
 
+def _safe_int_payload(raw_payload: str) -> int | None:
+    try:
+        return int(raw_payload.strip())
+    except ValueError:
+        return None
+
+
 class RefreshPeriodActiveCommand(IntCommandHandler):
     @classmethod
     @override
     def topic(cls) -> str:
         return mqtt_topics.REFRESH_PERIOD_ACTIVE_SET
 
+    @override
+    def echo_state_topic(self) -> str:
+        return mqtt_topics.REFRESH_PERIOD_ACTIVE
+
+    @override
+    def capture_current_state(self) -> int | None:
+        value = self.vehicle_state.refresh_period_active
+        return None if value < 0 else value
+
+    @override
+    def echo_payload(self, raw_payload: str) -> int | None:
+        return _safe_int_payload(raw_payload)
+
     @override
     async def handle_typed_payload(self, payload: int) -> CommandProcessingResult:
         self.vehicle_state.set_refresh_period_active(payload)
@@ -28,6 +48,19 @@ class RefreshPeriodInactiveCommand(IntCommandHandler):
     def topic(cls) -> str:
         return mqtt_topics.REFRESH_PERIOD_INACTIVE_SET
 
+    @override
+    def echo_state_topic(self) -> str:
+        return mqtt_topics.REFRESH_PERIOD_INACTIVE
+
+    @override
+    def capture_current_state(self) -> int | None:
+        value = self.vehicle_state.refresh_period_inactive
+        return None if value < 0 else value
+
+    @override
+    def echo_payload(self, raw_payload: str) -> int | None:
+        return _safe_int_payload(raw_payload)
+
     @override
     async def handle_typed_payload(self, payload: int) -> CommandProcessingResult:
         self.vehicle_state.set_refresh_period_inactive(payload)
@@ -40,6 +73,19 @@ class RefreshPeriodInactiveGraceCommand(IntCommandHandler):
     def topic(cls) -> str:
         return mqtt_topics.REFRESH_PERIOD_INACTIVE_GRACE_SET
 
+    @override
+    def echo_state_topic(self) -> str:
+        return mqtt_topics.REFRESH_PERIOD_INACTIVE_GRACE
+
+    @override
+    def capture_current_state(self) -> int | None:
+        value = self.vehicle_state.refresh_period_inactive_grace
+        return None if value < 0 else value
+
+    @override
+    def echo_payload(self, raw_payload: str) -> int | None:
+        return _safe_int_payload(raw_payload)
+
     @override
     async def handle_typed_payload(self, payload: int) -> CommandProcessingResult:
         self.vehicle_state.set_refresh_period_inactive_grace(payload)
@@ -52,6 +98,19 @@ class RefreshPeriodAfterShutdownCommand(IntCommandHandler):
     def topic(cls) -> str:
         return mqtt_topics.REFRESH_PERIOD_AFTER_SHUTDOWN_SET
 
+    @override
+    def echo_state_topic(self) -> str:
+        return mqtt_topics.REFRESH_PERIOD_AFTER_SHUTDOWN
+
+    @override
+    def capture_current_state(self) -> int | None:
+        value = self.vehicle_state.refresh_period_after_shutdown
+        return None if value < 0 else value
+
+    @override
+    def echo_payload(self, raw_payload: str) -> int | None:
+        return _safe_int_payload(raw_payload)
+
     @override
     async def handle_typed_payload(self, payload: int) -> CommandProcessingResult:
         self.vehicle_state.set_refresh_period_after_shutdown(payload)

src/handlers/vehicle_command.py

@@ -57,6 +57,26 @@ def __init__(
     def publisher(self) -> Publisher:
         return self.vehicle_state.publisher
 
+    def __publish_state_echo(self, *, topic: str, value: object | None) -> None:
+        if value is None:
+            return
+        full_topic = self.vehicle_state.get_topic(topic)
+        try:
+            if isinstance(value, bool):
+                self.publisher.publish_bool(full_topic, value)
+            elif isinstance(value, int):
+                self.publisher.publish_int(full_topic, value)
+            elif isinstance(value, float):
+                self.publisher.publish_float(full_topic, value)
+            else:
+                self.publisher.publish_str(full_topic, str(value))
+        except Exception:
+            LOG.warning(
+                "Failed to publish state echo for topic %s",
+                full_topic,
+                exc_info=True,
+            )
+
     def __report_command_failure(
         self,
         *,
@@ -106,6 +126,23 @@ async def handle_mqtt_command(self, *, topic: str, payload: str) -> None:
                 handler=handler, payload=payload, analyzed_topic=analyzed_topic
             )
 
+    async def __run_handler_and_report_success(
+        self,
+        *,
+        handler: CommandHandlerBase,
+        payload: str,
+        analyzed_topic: _MqttCommandTopic,
+    ) -> None:
+        execution_result = await handler.handle(payload)
+        self.publisher.publish_str(analyzed_topic.response_no_global, "Success")
+        if execution_result.force_refresh:
+            self.vehicle_state.set_refresh_mode(
+                RefreshMode.FORCE,
+                f"after command execution on topic {analyzed_topic.command_no_vin}",
+            )
+        if execution_result.clear_command:
+            self.publisher.clear_topic(analyzed_topic.command_no_global)
+
     async def __execute_mqtt_command_handler(
         self,
         *,
@@ -114,65 +151,87 @@ async def __execute_mqtt_command_handler(
         analyzed_topic: _MqttCommandTopic,
     ) -> None:
         topic = analyzed_topic.command_no_vin
-        topic_no_global = analyzed_topic.command_no_global
         result_topic = analyzed_topic.response_no_global
 
+        echo_topic = handler.echo_state_topic()
+        prior_state: object | None = None
+        echoed = False
+        if echo_topic is not None:
+            prior_state = handler.capture_current_state()
+            echoed_value = handler.echo_payload(payload)
+            if echoed_value is not None:
+                self.__publish_state_echo(topic=echo_topic, value=echoed_value)
+                echoed = True
+
+        def rollback_state_echo() -> None:
+            if echoed and echo_topic is not None and prior_state is not None:
+                self.__publish_state_echo(topic=echo_topic, value=prior_state)
+
         try:
-            execution_result = await handler.handle(payload)
-            self.publisher.publish_str(result_topic, "Success")
-            if execution_result.force_refresh:
-                self.vehicle_state.set_refresh_mode(
-                    RefreshMode.FORCE, f"after command execution on topic {topic}"
-                )
-            if execution_result.clear_command:
-                self.publisher.clear_topic(topic_no_global)
+            await self.__run_handler_and_report_success(
+                handler=handler, payload=payload, analyzed_topic=analyzed_topic
+            )
         except MqttGatewayException as e:
+            rollback_state_echo()
             self.__report_command_failure(
                 command=topic, result_topic=result_topic, detail=e.message, exc=e
             )
         except SaicLogoutException:
-            LOG.warning(
-                "API Client was logged out, attempting immediate relogin and retry"
+            await self.__handle_logout_and_retry(
+                handler=handler,
+                payload=payload,
+                analyzed_topic=analyzed_topic,
+                rollback_state_echo=rollback_state_echo,
             )
-            try:
-                await self.relogin_handler.force_login()
-            except Exception as login_err:
-                self.__report_command_failure(
-                    command=topic,
-                    result_topic=result_topic,
-                    detail=f"relogin failed ({login_err})",
-                    exc=login_err,
-                )
-                return
-            try:
-                execution_result = await handler.handle(payload)
-                self.publisher.publish_str(result_topic, "Success")
-                if execution_result.force_refresh:
-                    self.vehicle_state.set_refresh_mode(
-                        RefreshMode.FORCE,
-                        f"after command execution on topic {topic}",
-                    )
-                if execution_result.clear_command:
-                    self.publisher.clear_topic(topic_no_global)
-            except Exception as retry_err:
-                self.__report_command_failure(
-                    command=topic,
-                    result_topic=result_topic,
-                    detail=str(retry_err),
-                    exc=retry_err,
-                )
         except SaicApiException as se:
+            rollback_state_echo()
             self.__report_command_failure(
                 command=topic, result_topic=result_topic, detail=se.message, exc=se
             )
         except Exception as e:
+            rollback_state_echo()
             self.__report_command_failure(
                 command=topic,
                 result_topic=result_topic,
                 detail="unexpected error",
                 exc=e,
             )
 
+    async def __handle_logout_and_retry(
+        self,
+        *,
+        handler: CommandHandlerBase,
+        payload: str,
+        analyzed_topic: _MqttCommandTopic,
+        rollback_state_echo: Callable[[], None],
+    ) -> None:
+        topic = analyzed_topic.command_no_vin
+        result_topic = analyzed_topic.response_no_global
+        LOG.warning("API Client was logged out, attempting immediate relogin and retry")
+        try:
+            await self.relogin_handler.force_login()
+        except Exception as login_err:
+            rollback_state_echo()
+            self.__report_command_failure(
+                command=topic,
+                result_topic=result_topic,
+                detail=f"relogin failed ({login_err})",
+                exc=login_err,
+            )
+            return
+        try:
+            await self.__run_handler_and_report_success(
+                handler=handler, payload=payload, analyzed_topic=analyzed_topic
+            )
+        except Exception as retry_err:
+            rollback_state_echo()
+            self.__report_command_failure(
+                command=topic,
+                result_topic=result_topic,
+                detail=str(retry_err),
+                exc=retry_err,
+            )
+
     def __get_command_topics(self, topic: str) -> _MqttCommandTopic:
         global_topic_removed = topic.removeprefix(self.global_mqtt_topic).removeprefix(
             "/"

src/integrations/home_assistant/base.py

@@ -55,6 +55,7 @@ def _publish_select(
             "value_template": value_template,
             "command_template": command_template,
             "options": options,
+            "optimistic": False,
             "enabled_by_default": enabled,
         }
         if entity_category is not None:
@@ -86,6 +87,7 @@ def _publish_text(
             "value_template": value_template,
             "command_template": command_template,
             "retain": str(retain).lower(),
+            "optimistic": False,
             "enabled_by_default": enabled,
         }
         if min_value is not None:
@@ -152,6 +154,7 @@ def _publish_number(
             "command_topic": self._get_command_topic(topic),
             "value_template": value_template,
             "retain": str(retain).lower(),
+            "optimistic": False,
             "mode": mode,
             "min": min_value,
             "max": max_value,