BMW CarData for Home Assistant

The integration automatically creates entities based on the VIN provided by CarData.

Entity Types and Device Classes

• Devices: Each VIN is treated as a unique device in Home Assistant.
• Windows/Sunroof: These use the window device class (reporting open or closed). A hidden raw string sensor (reporting CLOSED, INTERMEDIATE, OPEN) is available if you need intermediate positions.
• Energy Counters: Cumulative meters like Charging EV Energy supplied total use the energy device class with total_increasing. These can be used in the Home Assistant Energy Dashboard.
• Fuel Consumption (OBFCM): Cumulative meters (e.g., OBFCM Fuel consumption total) use total_increasing. Note that changing from measurement to total_increasing may cause historical statistics to appear non-linear.
• Battery Energy: Readings like installed size or current energy content use the energy_storage device class. Note: These cannot be used as a source in the Energy Dashboard because they represent a stored level rather than a continuous consumption/production value.

Display and Precision

• Precision: Numeric sensors mapping to known device classes (distance, energy, power, etc.) use suggested_display_precision for clean rounded values in standard cards.
• Units: You can override display units per entity via the entity settings gear icon, or change the global unit system in Home Assistant.

To display leasing information, provide a sensor to the leasing_entity option. The card displays tiles based on the attributes provided by that sensor.

Recommended Setup: Use the Lease Mileage Tracker blueprint to create a conforming sensor.

Sensor Contract: The sensor's state must be the projected over/under mileage at lease end (positive = over). The card reads the following attributes for its tiles:

Example YAML Configuration:

type: custom:bmw-cardata-vehicle-card
device_id: abcdef1234567890abcdef1234567890
leasing_entity: sensor.lease_my_bmw
leasing_tiles:
  - lease_remaining
  - monthly_budget
  - projected
  - cost

The integration provides a predicted SOC (State of Charge) sensor that estimates battery charge during charging sessions using real-time accumulated energy (trapezoidal integration of charging power minus auxiliary consumption). This allows for more frequent updates than BMW's native SOC updates.

Efficiency Learning

The sensor automatically learns vehicle charging efficiency using an Exponential Moving Average (EMA) with an adaptive learning rate.

• AC charging efficiency: Starts at 90%.
• DC charging efficiency: Starts at 93%.
• Persistence: Learning data and active/pending sessions persist across Home Assistant restarts.
• Learning Criteria: For a session to contribute to learning, it must have a minimum 5% SOC gain, a calculated efficiency between 40% and 98%, and valid power data.
• Session Finalization: Learning is triggered when a charge ends. If the target is reached (within 2%), it happens immediately. If interrupted, the integration waits for a grace period (5 minutes for DC, 15 minutes for AC) for BMW SOC confirmation.

AC charging efficiency: Starts at 90%
DC charging efficiency: Starts at 93%

The integration handles Plug-in Hybrid Electric Vehicles (PHEVs) and Battery Electric Vehicles (BEVs) differently to ensure accuracy.

PHEV Behavior

• Automatic Detection: Detected if the vehicle has both an HV battery and a fuel system (unless identified as a known BEV like i4, iX, etc.).
• Sync Down: If the actual BMW SOC is lower than the predicted value (e.g., due to battery recovery mode or engine-priority driving), the prediction syncs down immediately.
• Header Filtering: During charging, batteryManagement.header updates are only allowed if they sync UP (above the prediction). This prevents stale pre-charge values from causing incorrect re-anchoring.

BEV Behavior

• No Sync Down during charge: For pure electric vehicles, the prediction never syncs downward while a charge is active. It only syncs UP when BMW's reported SOC is higher than the prediction to correct for efficiency losses or missed updates.

BMW imposes a 50 calls/day limit on the CarData API. This integration manages this limit through several mechanisms:

• MQTT Stream (Real-time): Provides unlimited real-time updates for events like door locks, motion, and charging power. GPS coordinates are paired using BMW payload timestamps to ensure accuracy even if latitude and longitude arrive in separate messages.
• Trip-end Polling: When a vehicle stops moving, the integration triggers an API poll to capture post-trip battery state (SOC). This is subject to a configurable per-VIN cooldown (default 10 minutes) to prevent API exhaustion from frequent short trips.
• Charge-end/start Polling: Triggers API calls to capture actual SOC for calibration or to retrieve AC phase counts that are only reported during specific charge events.
• Fallback Polling: Periodic polling occurs if the MQTT stream fails or after Home Assistant restarts.
• Daily Features: Enabling Charging History or Tyre Diagnosis adds exactly 1 API call per vehicle per day.
• Rate Limiting: If BMW returns a 429 (Too Many Requests) or 403 (Forbidden with CU-429), the integration uses exponential backoff (1h, 2h, 4h, 8h, up to 24h). It intelligently shortens the backoff to align with the midnight UTC quota reset.

Tip: For users with many vehicles, the 50-call limit is shared across all VINs. You can disable trip-end polling via Settings → Devices & Services → BMW CarData → Configure → Settings to save quota if you have vehicles making many short trips.

Before installing the integration via HACS, you must complete these steps in the BMW/Mini CarData portal. Do not skip any steps.

1. Access the Portal: Use the appropriate regional link (e.g., BMW UK or BMW DE).
2. Select Vehicle: Choose the vehicle you want to stream and select BMW CarData or Mini CarData.
3. Generate Client ID: Follow the technical registration steps to generate a Client ID. Copy this ID; you will need it for the Home Assistant configuration.
   • CRITICAL: Never press the "Authenticate device" button in the BMW portal.
4. Request CarData API Access: Click "Request access to CarData API" and wait at least 60 seconds for propagation.
5. Request CarData Stream Access: Click "Request access to CarData Stream" and wait at least 60 seconds.
6. Configure Data Stream:
   • Scroll to CARDATA STREAMING and click Configure data stream.
   • Load all descriptors by clicking "Load more".
   • Select the descriptors you want to stream. To automate selection, use the browser console script provided in the documentation.
   • For Predicted SOC: Ensure you include vehicle.drivetrain.batteryManagement.header, vehicle.drivetrain.batteryManagement.maxEnergy, vehicle.powertrain.electric.battery.charging.power, and vehicle.drivetrain.electricEngine.charging.status.
7. Save Selection.
8. Home Assistant Setup: Install via HACS and follow the configuration flow. When prompted, paste your Client ID and complete the verification. Wait for the BMW page to confirm "Device authenticated successfully" before clicking Submit in Home Assistant.