Merge pull request #266 from renaudallard/main

Add charging history and tyre diagnosis daily-poll sensors

Author: kvanbiesen

README.md

@@ -247,13 +247,49 @@ Each EV/PHEV vehicle gets two button entities to reset learned efficiency:
 
 These buttons appear in the vehicle's device page under Configuration entities.
 
+## Magic SOC — Driving Consumption Prediction (Experimental)
+
+Magic SOC predicts battery drain during driving using real-time odometer distance and learned consumption rates. It provides a sub-integer SOC estimate that updates more frequently than BMW's native integer SOC. **Disabled by default** — enable via Settings.
+
+- **Enable via**: Settings → Devices & Services → BMW CarData → Configure → Settings → Enable Magic SOC
+- **Sensor**: `vehicle.magic_soc` per vehicle (BEV only; PHEVs get passthrough BMW SOC)
+- **How it works**: Anchors on BMW's reported SOC at trip start, then subtracts `distance × learned_consumption / capacity` as the vehicle drives. Re-anchors when BMW sends a fresh SOC mid-drive — if the drift is < 0.5pp, keeps the sub-integer prediction for smoother display.
+- **Consumption learning**: Uses EMA (Exponential Moving Average) with adaptive rate. Default 0.21 kWh/km globally, with per-model defaults (e.g. i4 eDrive40 = 0.18 kWh/km). Learns from completed trips where both SOC drop and distance are available. Requires at least 5 trips before the learning rate settles to 20%.
+- **Trip detection**: Combines BMW's `isMoving` signal, GPS-derived motion, and odometer changes. Handles MQTT bursts and GPS gaps gracefully.
+- **Capacity**: Uses live `maxEnergy` from BMW (reflects real degradation), falls back to `batterySizeMax`, then to per-model defaults.
+- **Reset**: A "Reset Consumption Learning" button appears under Configuration entities for each BEV.
+
+**Limitations**: This is experimental. Accuracy depends on BMW sending timely SOC and mileage data. Preheating, extended idle with accessories, and firmware glitches can cause temporary inaccuracy. PHEVs are excluded from prediction (hybrid powertrain makes distance-based estimation unreliable).
+
+## Charging History (Optional)
+
+The integration can fetch your BMW charging session history from the past 30 days. This is **disabled by default** to conserve your API quota.
+
+- **Enable via**: Settings → Devices & Services → BMW CarData → Configure → Settings → Enable Charging History
+- **API cost**: 1 call per vehicle per day (from your 50-call daily quota)
+- **Sensor**: Creates a diagnostic sensor per vehicle showing session count and last charge date
+- **Attributes**: Full session data including start/end SOC, energy consumed, duration, location, and cost information
+- **Manual trigger**: Use `cardata.fetch_charging_history` service in Developer Tools
+
+## Tyre Diagnosis (Optional)
+
+The integration can fetch tyre health and wear data from BMW's Smart Maintenance system. This is **disabled by default** to conserve your API quota.
+
+- **Enable via**: Settings → Devices & Services → BMW CarData → Configure → Settings → Enable Tyre Diagnosis
+- **API cost**: 1 call per vehicle per day (from your 50-call daily quota)
+- **Sensor**: Creates a diagnostic sensor per vehicle showing aggregate tyre status
+- **Attributes**: Per-wheel data including dimension, wear, season, manufacturer, defect status, and production date
+- **Manual trigger**: Use `cardata.fetch_tyre_diagnosis` service in Developer Tools
+
 ## Developer Tools Services
 
 Home Assistant's Developer Tools expose helper services for manual API checks:
 
 - `cardata.fetch_telematic_data` fetches the current contents of the configured telematics container for a VIN and logs the raw payload.
 - `cardata.fetch_vehicle_mappings` calls `GET /customers/vehicles/mappings` and logs the mapping details (including PRIMARY or SECONDARY status). Only primary mappings return data; some vehicles do not support secondary users, in which case the mapped user is considered the primary one.
 - `cardata.fetch_basic_data` calls `GET /customers/vehicles/{vin}/basicData` to retrieve static metadata (model name, series, etc.) for the specified VIN.
+- `cardata.fetch_charging_history` fetches the last 30 days of charging sessions for a VIN. Uses 1 API call per vehicle.
+- `cardata.fetch_tyre_diagnosis` fetches tyre health and wear data for a VIN. Uses 1 API call per vehicle.
 - `migrations` call for proper renaming the sensors from old installations
 
 ## API Quota and MQTT Streaming
@@ -263,8 +299,9 @@ BMW imposes a **50 calls/day** limit on the CarData API. This integration does n
 - **MQTT Stream (real-time)**: The MQTT stream is unlimited and provides real-time updates for events like door locks, motion state, charging power, etc. GPS coordinates are paired using BMW payload timestamps (same GPS fix detection) with an arrival-time fallback, so location updates work even when latitude and longitude arrive in separate MQTT messages. In direct BMW mode, token refresh during MQTT reconnection is lock-free to avoid blocking the connection, and the MQTT connection is proactively reconnected with fresh credentials to prevent session expiry (~1 hour).
 - **Trip-end polling**: When a vehicle stops moving (trip ends), the integration triggers an immediate API poll to capture post-trip battery state. This ensures SOC is updated even when the MQTT stream only delivers GPS/mileage but not SOC (common on some models). A per-VIN 10-minute cooldown prevents GPS burst flapping from burning API quota.
 - **Charge-end polling**: When charging completes or stops, the integration triggers an immediate API poll to get the actual BMW SOC for learning calibration of the predicted SOC sensor, subject to the same per-VIN cooldown.
-- **Fallback polling**: The integration polls every 12 hours as a fallback in case MQTT stream fails or after Home Assistant restarts. VINs with fresh MQTT data are skipped individually, so in multi-car setups only stale VINs consume API calls.
-- **Multi-VIN setups**: All vehicles share the same 50 call/day limit.
+- **Fallback polling**: The integration polls periodically as a fallback in case MQTT stream fails or after Home Assistant restarts. VINs with fresh MQTT data are skipped individually, so in multi-car setups only stale VINs consume API calls.
+- **Daily optional features**: When Charging History and/or Tyre Diagnosis are enabled, each adds 1 API call per vehicle per day. The polling interval automatically increases to compensate — e.g. with both features on 2 cars, polling stretches from 2h to 2.4h per VIN.
+- **Multi-VIN setups**: All vehicles share the same 50 call/day limit. The poll interval scales with VIN count plus any enabled daily features. Each VIN is guaranteed at least 1 poll per day; BMW's 429 backoff handles actual quota enforcement.
 - **Rate limiting**: If BMW returns a 429 (rate limited) response, the integration backs off automatically with exponential delay.
 
 ## Requirements
@@ -318,6 +355,7 @@ The integration is organized into focused modules:
 | `stream_circuit_breaker.py` | Circuit breaker for reconnection rate limiting |
 | `stream_reconnect.py` | Reconnection, unauthorized handling, retry scheduling |
 | `motion_detection.py` | GPS centroid movement detection, parking zone logic |
+| `sensor_diagnostics.py` | Diagnostic sensors: connection, metadata, efficiency, charging history, tyre diagnosis |
 | `sensor.py` / `binary_sensor.py` / `device_tracker.py` | Home Assistant entity platforms |
 | `config_flow.py` | Setup, reauthorization, and options UI flows |
 | `bootstrap.py` | VIN discovery, metadata fetch, container creation |

custom_components/cardata/config_flow.py

@@ -53,7 +53,9 @@
     OPTION_CUSTOM_MQTT_TLS,
     OPTION_CUSTOM_MQTT_TOPIC_PREFIX,
     OPTION_CUSTOM_MQTT_USERNAME,
+    OPTION_ENABLE_CHARGING_HISTORY,
     OPTION_ENABLE_MAGIC_SOC,
+    OPTION_ENABLE_TYRE_DIAGNOSIS,
 )
 from .utils import redact_vin
 
@@ -373,13 +375,14 @@ async def async_step_init(self, user_input: dict[str, Any] | None = None) -> Flo
 
     async def async_step_action_settings(self, user_input: dict[str, Any] | None = None) -> FlowResult:
         if user_input is not None:
-            # If Magic SOC is being disabled, remove its entities from the registry
-            was_enabled = self._config_entry.options.get(OPTION_ENABLE_MAGIC_SOC, False)
-            now_enabled = user_input[OPTION_ENABLE_MAGIC_SOC]
-            if was_enabled and not now_enabled:
-                from homeassistant.helpers import entity_registry as er
+            from homeassistant.helpers import entity_registry as er
+
+            entity_reg = er.async_get(self.hass)
 
-                entity_reg = er.async_get(self.hass)
+            # If Magic SOC is being disabled, remove its entities from the registry
+            was_magic = self._config_entry.options.get(OPTION_ENABLE_MAGIC_SOC, False)
+            now_magic = user_input[OPTION_ENABLE_MAGIC_SOC]
+            if was_magic and not now_magic:
                 for entity in er.async_entries_for_config_entry(entity_reg, self._config_entry.entry_id):
                     if entity.unique_id and (
                         entity.unique_id.endswith("_vehicle.magic_soc")
@@ -388,15 +391,40 @@ async def async_step_action_settings(self, user_input: dict[str, Any] | None = N
                         _LOGGER.info("Removing Magic SOC entity %s", entity.entity_id)
                         entity_reg.async_remove(entity.entity_id)
 
+            # If Charging History is being disabled, remove its entities
+            was_ch = self._config_entry.options.get(OPTION_ENABLE_CHARGING_HISTORY, False)
+            now_ch = user_input[OPTION_ENABLE_CHARGING_HISTORY]
+            if was_ch and not now_ch:
+                for entity in er.async_entries_for_config_entry(entity_reg, self._config_entry.entry_id):
+                    if entity.unique_id and entity.unique_id.endswith("_diagnostics_charging_history"):
+                        _LOGGER.info("Removing Charging History entity %s", entity.entity_id)
+                        entity_reg.async_remove(entity.entity_id)
+
+            # If Tyre Diagnosis is being disabled, remove its entities
+            was_td = self._config_entry.options.get(OPTION_ENABLE_TYRE_DIAGNOSIS, False)
+            now_td = user_input[OPTION_ENABLE_TYRE_DIAGNOSIS]
+            if was_td and not now_td:
+                for entity in er.async_entries_for_config_entry(entity_reg, self._config_entry.entry_id):
+                    if entity.unique_id and entity.unique_id.endswith("_diagnostics_tyre_diagnosis"):
+                        _LOGGER.info("Removing Tyre Diagnosis entity %s", entity.entity_id)
+                        entity_reg.async_remove(entity.entity_id)
+
             options = dict(self._config_entry.options)
-            options[OPTION_ENABLE_MAGIC_SOC] = user_input[OPTION_ENABLE_MAGIC_SOC]
+            options[OPTION_ENABLE_MAGIC_SOC] = now_magic
+            options[OPTION_ENABLE_CHARGING_HISTORY] = now_ch
+            options[OPTION_ENABLE_TYRE_DIAGNOSIS] = now_td
             return self.async_create_entry(title="", data=options)
-        current = self._config_entry.options.get(OPTION_ENABLE_MAGIC_SOC, False)
+
+        current_magic = self._config_entry.options.get(OPTION_ENABLE_MAGIC_SOC, False)
+        current_ch = self._config_entry.options.get(OPTION_ENABLE_CHARGING_HISTORY, False)
+        current_td = self._config_entry.options.get(OPTION_ENABLE_TYRE_DIAGNOSIS, False)
         return self.async_show_form(
             step_id="action_settings",
             data_schema=vol.Schema(
                 {
-                    vol.Optional(OPTION_ENABLE_MAGIC_SOC, default=current): bool,
+                    vol.Optional(OPTION_ENABLE_MAGIC_SOC, default=current_magic): bool,
+                    vol.Optional(OPTION_ENABLE_CHARGING_HISTORY, default=current_ch): bool,
+                    vol.Optional(OPTION_ENABLE_TYRE_DIAGNOSIS, default=current_td): bool,
                 }
             ),
         )

custom_components/cardata/const.py

@@ -90,9 +90,11 @@
 DEBUG_LOG = False
 DIAGNOSTIC_LOG_INTERVAL = 30  # How often we print stream logs in seconds
 BOOTSTRAP_COMPLETE = "bootstrap_complete"
-# Staleness threshold per VIN - scales with number of cars to stay within API quota
-# 1 car = 1h, 2 cars = 2h, etc. → worst case ~24 API calls/day regardless of car count
-STALE_THRESHOLD_PER_VIN = 60 * 60  # 1 hour per VIN
+# Telematic polling budget — target ~24 scheduled API polls/day, leaving headroom
+# for bootstrap, trip-end events, etc. within BMW's 50-call daily quota.
+# When daily optional features (charging history, tyre diagnosis) are enabled,
+# the polling budget is reduced to keep total calls constant.
+TARGET_DAILY_POLLS = 24
 HTTP_TIMEOUT = 30  # Timeout for HTTP API requests in seconds
 TRIP_POLL_COOLDOWN_SECONDS = 600  # Min seconds between trip-end polls per VIN
 VEHICLE_METADATA = "vehicle_metadata"
@@ -111,6 +113,8 @@
 DEFAULT_CUSTOM_MQTT_TOPIC_PREFIX = "bmw/"
 OPTION_DIAGNOSTIC_INTERVAL = "diagnostic_log_interval"
 OPTION_ENABLE_MAGIC_SOC = "enable_magic_soc"
+OPTION_ENABLE_CHARGING_HISTORY = "enable_charging_history"
+OPTION_ENABLE_TYRE_DIAGNOSIS = "enable_tyre_diagnosis"
 
 # Error message constants (for consistent error detection)
 ERR_TOKEN_REFRESH_IN_PROGRESS = "Token refresh already in progress"
@@ -260,5 +264,8 @@
     "i7": 101.7,
 }
 
+# Daily fetch interval for optional endpoints (charging history, tyre diagnosis)
+DAILY_FETCH_INTERVAL = 86400  # 24 hours
+
 # Key for storing deduplicated allowed VINs in entry data
 ALLOWED_VINS_KEY = "allowed_vins"

custom_components/cardata/coordinator.py

@@ -136,6 +136,18 @@ class CardataCoordinator:
     # Whether Magic SOC sensor creation is enabled (off by default)
     enable_magic_soc: bool = field(default=False, init=False)
 
+    # Whether optional daily-poll features are enabled (off by default)
+    enable_charging_history: bool = field(default=False, init=False)
+    enable_tyre_diagnosis: bool = field(default=False, init=False)
+
+    # Storage for daily-poll data (VIN → parsed response)
+    _charging_history: dict[str, list[dict[str, Any]]] = field(default_factory=dict, init=False)
+    _tyre_diagnosis: dict[str, dict[str, Any]] = field(default_factory=dict, init=False)
+
+    # Per-VIN timestamp of last daily fetch (unix time)
+    _last_charging_history_fetch: dict[str, float] = field(default_factory=dict, init=False)
+    _last_tyre_diagnosis_fetch: dict[str, float] = field(default_factory=dict, init=False)
+
     # Callback set by sensor.py to create virtual sensors after platform setup
     _create_sensor_callback: Callable[[str, str], None] | None = field(default=None, init=False, repr=False)
 
@@ -164,6 +176,8 @@ class CardataCoordinator:
     _signal_new_image: str = field(default="", init=False)
     _signal_metadata: str = field(default="", init=False)
     _signal_efficiency_learning: str = field(default="", init=False)
+    _signal_charging_history: str = field(default="", init=False)
+    _signal_tyre_diagnosis: str = field(default="", init=False)
 
     def __post_init__(self) -> None:
         """Initialize cached values after dataclass creation."""
@@ -174,6 +188,8 @@ def __post_init__(self) -> None:
         self._signal_new_image = f"{DOMAIN}_{self.entry_id}_new_image"
         self._signal_metadata = f"{DOMAIN}_{self.entry_id}_metadata"
         self._signal_efficiency_learning = f"{DOMAIN}_{self.entry_id}_efficiency_learning"
+        self._signal_charging_history = f"{DOMAIN}_{self.entry_id}_charging_history"
+        self._signal_tyre_diagnosis = f"{DOMAIN}_{self.entry_id}_tyre_diagnosis"
 
     @property
     def signal_new_sensor(self) -> str:
@@ -203,6 +219,36 @@ def signal_metadata(self) -> str:
     def signal_efficiency_learning(self) -> str:
         return self._signal_efficiency_learning
 
+    @property
+    def signal_charging_history(self) -> str:
+        return self._signal_charging_history
+
+    @property
+    def signal_tyre_diagnosis(self) -> str:
+        return self._signal_tyre_diagnosis
+
+    # --- Daily-poll data access ---
+
+    def update_charging_history(self, vin: str, sessions: list[dict[str, Any]]) -> None:
+        """Store charging history and dispatch signal."""
+        self._charging_history[vin] = sessions
+        self._last_charging_history_fetch[vin] = time.time()
+        self._safe_dispatcher_send(self.signal_charging_history, vin)
+
+    def get_charging_history(self, vin: str) -> list[dict[str, Any]]:
+        """Return stored charging history for a VIN."""
+        return self._charging_history.get(vin, [])
+
+    def update_tyre_diagnosis(self, vin: str, data: dict[str, Any]) -> None:
+        """Store tyre diagnosis and dispatch signal."""
+        self._tyre_diagnosis[vin] = data
+        self._last_tyre_diagnosis_fetch[vin] = time.time()
+        self._safe_dispatcher_send(self.signal_tyre_diagnosis, vin)
+
+    def get_tyre_diagnosis(self, vin: str) -> dict[str, Any]:
+        """Return stored tyre diagnosis for a VIN."""
+        return self._tyre_diagnosis.get(vin, {})
+
     # --- Derived motion detection from GPS ---
 
     def _update_location_tracking(self, vin: str, lat: float, lon: float) -> bool:

custom_components/cardata/lifecycle.py

@@ -66,7 +66,9 @@
     OPTION_CUSTOM_MQTT_USERNAME,
     OPTION_DEBUG_LOG,
     OPTION_DIAGNOSTIC_INTERVAL,
+    OPTION_ENABLE_CHARGING_HISTORY,
     OPTION_ENABLE_MAGIC_SOC,
+    OPTION_ENABLE_TYRE_DIAGNOSIS,
     OPTION_MQTT_KEEPALIVE,
     SOC_LEARNING_STORAGE_KEY,
     SOC_LEARNING_STORAGE_VERSION,
@@ -197,6 +199,8 @@ async def async_setup_cardata(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         coordinator = CardataCoordinator(hass=hass, entry_id=entry.entry_id)
         coordinator.diagnostic_interval = diagnostic_interval
         coordinator.enable_magic_soc = bool(options.get(OPTION_ENABLE_MAGIC_SOC, False))
+        coordinator.enable_charging_history = bool(options.get(OPTION_ENABLE_CHARGING_HISTORY, False))
+        coordinator.enable_tyre_diagnosis = bool(options.get(OPTION_ENABLE_TYRE_DIAGNOSIS, False))
 
         # Store session start time for ghost cleanup
         # This prevents removing devices that existed before this HA restart