Add charging history and tyre diagnosis daily-poll sensors

Fetch charging session history and tyre health data from BMW API,
disabled by default with API quota warnings. Poll budget automatically
adjusts to account for daily calls, keeping total scheduled usage
within budget.

Each feature adds a diagnostic sensor per vehicle, a settings toggle,
and a manual service trigger. Null-safety guards handle missing or
malformed API responses gracefully.

Author: renaudallard

README.md

@@ -247,13 +247,35 @@ Each EV/PHEV vehicle gets two button entities to reset learned efficiency:
 
 These buttons appear in the vehicle's device page under Configuration entities.
 
+## 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 +285,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 +341,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

custom_components/cardata/sensor.py

@@ -66,7 +66,13 @@
 from .coordinator import CardataCoordinator
 from .entity import CardataEntity
 from .runtime import CardataRuntimeData
-from .sensor_diagnostics import CardataDiagnosticsSensor, CardataEfficiencyLearningSensor, CardataVehicleMetadataSensor
+from .sensor_diagnostics import (
+    CardataChargingHistorySensor,
+    CardataDiagnosticsSensor,
+    CardataEfficiencyLearningSensor,
+    CardataTyreDiagnosisSensor,
+    CardataVehicleMetadataSensor,
+)
 from .sensor_helpers import (
     convert_value_for_unit,
     get_device_class_for_unit,
@@ -304,6 +310,26 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry, async_add_e
     entities: dict[tuple[str, str], CardataSensor] = {}
     metadata_entities: dict[str, CardataVehicleMetadataSensor] = {}
     efficiency_entities: dict[str, CardataEfficiencyLearningSensor] = {}
+    charging_history_entities: dict[str, CardataChargingHistorySensor] = {}
+    tyre_diagnosis_entities: dict[str, CardataTyreDiagnosisSensor] = {}
+
+    def ensure_charging_history_sensor(vin: str) -> None:
+        """Ensure charging history sensor exists for VIN when option is enabled."""
+        if vin in charging_history_entities:
+            return
+        if not coordinator.enable_charging_history:
+            return
+        charging_history_entities[vin] = CardataChargingHistorySensor(coordinator, vin)
+        async_add_entities([charging_history_entities[vin]], True)
+
+    def ensure_tyre_diagnosis_sensor(vin: str) -> None:
+        """Ensure tyre diagnosis sensor exists for VIN when option is enabled."""
+        if vin in tyre_diagnosis_entities:
+            return
+        if not coordinator.enable_tyre_diagnosis:
+            return
+        tyre_diagnosis_entities[vin] = CardataTyreDiagnosisSensor(coordinator, vin)
+        async_add_entities([tyre_diagnosis_entities[vin]], True)
 
     def ensure_efficiency_learning_sensor(vin: str) -> None:
         """Ensure efficiency learning sensor exists for EVs/PHEVs with battery management."""
@@ -413,9 +439,25 @@ async def async_handle_update_for_creation(vin: str, descriptor: str) -> None:
     async def async_handle_metadata_update(vin: str) -> None:
         ensure_metadata_sensor(vin)
         ensure_efficiency_learning_sensor(vin)
+        ensure_charging_history_sensor(vin)
+        ensure_tyre_diagnosis_sensor(vin)
 
     entry.async_on_unload(async_dispatcher_connect(hass, coordinator.signal_metadata, async_handle_metadata_update))
 
+    async def async_handle_charging_history(vin: str) -> None:
+        ensure_charging_history_sensor(vin)
+
+    entry.async_on_unload(
+        async_dispatcher_connect(hass, coordinator.signal_charging_history, async_handle_charging_history)
+    )
+
+    async def async_handle_tyre_diagnosis(vin: str) -> None:
+        ensure_tyre_diagnosis_sensor(vin)
+
+    entry.async_on_unload(
+        async_dispatcher_connect(hass, coordinator.signal_tyre_diagnosis, async_handle_tyre_diagnosis)
+    )
+
     # Restore enabled sensors from entity registry
     # Wrap in try/except to ensure diagnostic sensors are always created even if restoration fails
     try:
@@ -444,6 +486,14 @@ async def async_handle_metadata_update(vin: str) -> None:
                 ensure_efficiency_learning_sensor(vin)
                 continue
 
+            if descriptor == "diagnostics_charging_history":
+                ensure_charging_history_sensor(vin)
+                continue
+
+            if descriptor == "diagnostics_tyre_diagnosis":
+                ensure_tyre_diagnosis_sensor(vin)
+                continue
+
             ensure_entity(vin, descriptor, assume_sensor=True)
     except Exception as err:
         _LOGGER.warning("Error restoring sensors from entity registry: %s", err)
@@ -466,6 +516,8 @@ async def async_handle_metadata_update(vin: str) -> None:
         for vin in all_vins:
             ensure_metadata_sensor(vin)
             ensure_efficiency_learning_sensor(vin)
+            ensure_charging_history_sensor(vin)
+            ensure_tyre_diagnosis_sensor(vin)
     except Exception as err:
         _LOGGER.warning("Error creating metadata sensors: %s", err)