Bosch eBike Smart System – Home Assistant Integration

Deutsch | English | Nederlands | Français | Italiano | Español | Čeština

Bosch eBike Smart System & eBike System 2 (BES2) für Home Assistant – liest Fahrrad- und Fahrtdaten direkt von der offiziellen Bosch Data Act API: Kilometerstand, Akkuzustand, letzte Fahrten mit GPS-Track und mehr. Mit Custom-Lovelace-Karten (2D, 3D, Heatmap, Kalender, Routenplaner, Dashboard) und optionalen Live-Daten per Bluetooth.

> Bosch eBike Smart System & eBike System 2 (BES2) for Home Assistant – reads bike and ride data directly from the official Bosch Data Act API, with custom Lovelace cards and optional live data over Bluetooth.

⚠️ Update-Hinweis (ab v1.17.6): Der Integrationsordner heißt jetzt ha_bosch_ebike (vorher bosch_ebike). Deine Einrichtung, Geräte und Einstellungen bleiben unverändert. Falls nach dem HACS-Update beide Ordner in config/custom_components/ liegen, lösche den alten bosch_ebike einmalig und starte Home Assistant neu.

### ⚠️ Regionale Voraussetzung

Diese Integration funktioniert ausschließlich mit einem Bosch SingleKey-ID-Konto, das innerhalb der EU registriert ist. Sie nutzt die offizielle Bosch Data Act API, deren Verfügbarkeit auf EU-Konten beschränkt ist. Konten aus anderen Regionen werden vom API-Endpoint abgelehnt und die Integration kann sich nicht anmelden.

### 🔌 Echte Live-Daten per Bluetooth (smart system v19+)

Dieses Repo enthält neben der HACS-Integration auch eine ESPHome-BLE-Bridge, die einen ESP32 zur Brücke zum Bosch eBike Live Data Interface macht. Damit fließen Akku-SoC, Speed, Tachostand & Co. in Echtzeit nach Home Assistant. Seit Kurzem gibt es dafür auch eine Dual-Bridge: Ein einzelner ESP32 verbindet sich damit gleichzeitig mit zwei Bosch eBikes.

> 🚀 Flashen ohne ESPHome-Setup: ESP32 (oder ESP32-C3, z. B. "C3 Mini") per USB anstecken und in Chrome / Edge https://xunil99.github.io/ha-bosch-ebike/ öffnen, Install klicken. Der Installer erkennt den Chip automatisch und flasht die passende Firmware (auch die Dual-Bridge-Variante). WLAN-Setup läuft im selben Browser-Schritt. Vollständige Anleitung (DE/EN) inkl. Pairing über die Flow App: esphome/.

> Ganz herzlichen Dank an PEPITO82 für die unermüdlichen Tests der Dual-Bridge – ohne diese Tests würde die Dual-Bridge bis heute nicht laufen, und ich hätte das Projekt längst aufgegeben.

> Real live data via Bluetooth: ESP32 firmware can be flashed directly from your browser at the link above, no ESPHome installation required, including a new dual bridge that connects one ESP32 to two Bosch eBikes at once. Bilingual guide in esphome/. Heartfelt thanks to PEPITO82, whose tireless testing made the dual bridge possible.

### 🖥️ Optional: 4,3"-Display für Datum, Wetter und Live-Daten

Zusätzlich zur Bridge gibt es jetzt eine zweite Firmware für das Guition/Sunton JC4827W543 (ESP32-S3 mit 4,3" IPS-Touch). Sie liest die Bridge-Sensoren aus Home Assistant, zeigt Datum, Uhrzeit, Wetter und bis zu zwei eBikes parallel an. Bestehende Bridge-Nutzer müssen nichts ändern, das Display ist rein additiv. Setup-Anleitung: esphome/DISPLAY.md.

> Optional 4.3" companion display (JC4827W543) renders date, time, weather, and up to two bikes from your HA data. Read-only, no impact on existing bridge users. Setup: esphome/DISPLAY.md.

Deutsch

Inhalt: Beschreibung · eBike System 2 (BES2) · Funktionen · Setup-Anleitung · Mehrere Bikes/Konten · Karten & Cards · Laden · Wartung · Reichweiten-Schätzung · Fehlerbehebung · Verfügbare Sensoren

Beschreibung

Diese Custom Integration verbindet dein Bosch eBike Smart System mit Home Assistant. Sie liest Fahrraddaten (Kilometerstand, Motorstunden, Batterie-Ladezyklen) und Aktivitätsdaten (letzte Fahrt, Geschwindigkeit, Trittfrequenz, Leistung) direkt von der offiziellen Bosch Data Act API aus.

Unterstützt werden ausschließlich eBikes mit Bosch Smart System (nicht das Classic Line System).

🆕 eBike System 2 (BES2) – NEU, in Erprobung (Alpha)

Die Integration unterstützt jetzt zusätzlich das ältere eBike System 2 (BES2) – nicht mehr nur das Smart System. Bestehende Smart-System-Nutzer sind davon nicht betroffen: Das System wird pro Integrations-Eintrag gewählt, deine vorhandene Einrichtung bleibt unverändert.

⚠️ Hinweis: Die BES2-Unterstützung ist neu und befindet sich aktuell in der Erprobung (Alpha).

Einrichtung (Unterschied zum Smart System): Im Bosch Data Act Portal (portal.bosch-ebike.com/data-act) melden sich BES2-Besitzer über „Bosch eBike Connect user? Log in here" an (die eBike-Connect-Identität), nicht über die SingleKey ID, und legen wie gewohnt eine App / Client-ID an. Beim Hinzufügen der Integration in Home Assistant wählst du im ersten Schritt (Systemauswahl) eBike System 2 und gibst anschließend die Client-ID ein. Für die Datenfreigabe reicht der normale Einstieg über flow.bosch-ebike.com bei eBike-Connect-Konten oft nicht aus - dafür brauchst du einen speziellen Link, siehe Abschnitt „eBike System 2 (BES2) einrichten" weiter unten.

Unterschiede Smart System ↔ eBike System 2 (BES2). BES2 liefert über die Bosch Data Act API einen kleineren Datenumfang. Welche Funktionen pro System verfügbar sind:

| Funktion | Smart System | eBike System 2 (BES2) | |----------|:---:|:---:| | Fahrten / letzte Fahrt (Distanz, Dauer, Ø-/Max-Geschwindigkeit, Trittfrequenz, Fahrerleistung, Höhenmeter, Kalorien, optional Herzfrequenz) | ✅ | ✅ | | GPS-Track auf der Karte + GPX-Export | ✅ | ✅ | | Gesamtstatistiken (Distanz, Fahrzeit, Kalorien, Höhenmeter, Ø-Werte) | ✅ | ✅ | | Gesamt-Kilometerstand (Tachostand) | ✅ | ✅ ¹ | | Gesamt-Höhenmeter | ✅ | ✅ ¹ | | Motorstunden (gesamt / mit Unterstützung) | ✅ | ❌ | | Max. Unterstützungsgeschwindigkeit | ✅ | ❌ | | Aktive Unterstützungsmodi + Reichweite je Modus | ✅ | ❌ | | Schiebehilfe-Geschwindigkeit | ✅ | ❌ | | Nächster Service (Kilometerstand / Datum) | ✅ | ❌ | | Akku: State of Health / Ladezyklen / Wh über Lebensdauer | ✅ | ❌ | | Diebstahl-Status + letzter Standort | ✅ | ❌ | | Komponenten-Inventar / Software-Update | ✅ | ❌ | | Verbrauchs- & Reichweiten-Schätzung | ✅ | ❌ | | Live-Daten per BLE-Bridge (ESPHome) | ✅ | ❌ |

¹ Bei BES2 stammen Tachostand und Gesamt-Höhenmeter aus den Gesamtstatistiken (kein separater Live-Tachostand).

Nicht verfügbare Funktionen erzeugen für BES2-Bikes gar keine Entitäten — sie fehlen einfach, statt „unbekannt" anzuzeigen.

Ohne die ausdauernden und genauen Beta-Tests von Habanatz (pedelecforum.de) wäre die Unterstützung für eBike System 2 (BES2) nicht möglich gewesen. Ganz herzlichen Dank dafür!

Funktionen

• Bike-Daten: Kilometerstand, Motorstunden (gesamt & mit Unterstützung), maximale Unterstützungsgeschwindigkeit, aktive Unterstützungsmodi, Schiebehilfe-Geschwindigkeit, nächster Service-Kilometerstand
• Batterie-Daten: Gelieferte Wh über Lebensdauer, Ladezyklen (gesamt, am Rad, extern)
• Letzte Fahrt: Distanz, Dauer, Durchschnitts-/Maximalgeschwindigkeit, Trittfrequenz (avg/max), Fahrerleistung in Watt (avg/max), Kalorienverbrauch, Höhenmeter (Anstieg/Abstieg), Titel, Datum
• Gesamtstatistiken: Anzahl aller Fahrten, Gesamtdistanz, Gesamtfahrzeit, Gesamtkalorien, Gesamthöhenmeter, Durchschnittswerte für Geschwindigkeit/Leistung/Trittfrequenz über alle Fahrten
• GPS-Track-Export: Export aller Fahrten als GPX-Dateien (mit Speed, Cadence, Power als Garmin TrackPointExtension)
• Interaktive Kartendarstellung: Custom Lovelace Card mit GPS-Tracks, geschwindigkeitsabhängiger Farbcodierung, Date-Picker und Prev/Next-Navigation
• 3D-Karte mit Chase-Cam, Zeit-Slider und Gebäudeschatten: Custom Lovelace Card (bosch-ebike-3d-map-card) für die Tour-Detailansicht mit 3D-Gebäuden, einer Kamera, die dem Bike von hinten folgt, proportionaler Play-Geschwindigkeit (Default 60× Echtzeit) und Cast-Shadows nach Sonnenstand zur Tour-Zeit (MapLibre + OpenFreeMap, kostenlos und ohne API-Key)
• Dashboard-Card mit Bike-Bild, Live-Daten und Ladesteuerung: Custom Lovelace Card (bosch-ebike-dashboard-card) mit eigenem Bike-Foto, Tachostand, Akkustand, Lade-Status, optionalem Ladeleistungssensor, Ziel-SoC-Schieberegler sowie Start-/Stop-Buttons über eine smarte Steckdose. Optional zeigt die Karte die Reichweite je Fahrmodus als farbige Pills (ECO/TOUR/TURBO/eMTB+ …); die Farbe pro Modus lässt sich im Karten-Editor passend zur Bosch Flow App zuordnen
• Automatische Token-Aktualisierung über Refresh-Token
• 10-Minuten-Polling-Intervall (beim ersten Start werden alle Fahrten importiert)

🆕 Live-Daten über Bluetooth (ESPHome-Bridge)

Zusätzlich zur Cloud-Integration findest du im Unterordner esphome/ eine ESPHome-External-Component, die einen ESP32 als Brücke zum Bosch eBike Live Data Interface (LDI) (BLE, smart system v19+) macht. Damit fließen Echtzeit-Werte (Speed, Akku-SoC, Tritt­frequenz, Fahrer­leistung, Tachostand, Lichtstatus, Lock-Status, …) als ESPHome-Sensoren in HA - ergänzend zur Cloud-basierten Tour-History.

🚀 Schnellster Weg ohne ESPHome-Kenntnisse: ESP32 anstecken, in Chrome / Edge auf https://xunil99.github.io/ha-bosch-ebike/ klicken und auf Install tippen. Firmware-Flash und WLAN-Setup laufen komplett im Browser - keine ESPHome-Installation nötig.

Komplette Anleitung: esphome/README.md

Verwandte Projekte: Kein ESP32 zur Hand, aber ein Raspberry Pi? ha-bosch-ebike-pibridge von @possm ist eine Community-Portierung in Python (BlueZ + MQTT), die direkt auf dem Pi läuft, zwei Bikes gleichzeitig unterstützt und ein eigenes Web-Dashboard mitbringt.

Live-Werte für exakte Tour-Berechnung verwenden (optional, ab v1.10.0)

Wenn die Bridge läuft, kannst du in den Integrations-Einstellungen (HA → Einstellungen → Geräte & Dienste → Bosch eBike → Konfigurieren) zwei Sensoren hinterlegen:

• Live-Tachostand-Sensor (z. B. sensor.ebike_odometer_live)
• Live-Akkustand-Sensor (z. B. sensor.ebike_battery_soc_live)

• Exakte Tour-Distanz (Tachostand-Differenz statt Cloud-GPS-Berechnung).
• Exakter Akkuverbrauch in Wh ((SoC-Start − SoC-Ende) × Akkukapazität / 100).

🆕 Kilometerstand-Sicherung gegen Cloud-Dips + Live-Boost (ab v1.19.28, ab v1.19.31 sofort reaktiv)

Der Odometer-Sensor zeigt niemals einen niedrigeren Wert als zuvor, selbst wenn ein einzelner Cloud-Poll kurzzeitig einen veralteten oder zu niedrigen Wert liefert - dafür merkt sich die Integration intern den bisher höchsten bestätigten Kilometerstand pro Bike (rein anzeigeseitig, ohne die zugrunde liegenden Bosch-Rohdaten zu verändern).

Ist zusätzlich ein Live-Tachostand-Sensor (siehe oben) für das Bike hinterlegt, fließt dessen aktueller Wert ebenfalls in diese Untergrenze ein, mit zwei Schutzmechanismen: der Live-Wert zählt nur, wenn er sich kürzlich geändert hat (innerhalb der letzten 2 Stunden) und nicht unplausibel weit über dem bisherigen Wert liegt (max. 500 km Vorsprung). So zeigt der Kilometerstand sofort den korrekten, aktuellen Wert, wenn das Bike zuhause andockt, statt Stunden auf den nächsten Bosch-Cloud-Sync zu warten. Ab v1.19.31 wirkt sich eine Änderung des Live-Sensors sofort auf die Anzeige aus (vorher erst beim nächsten planmäßigen 30-Minuten-Cloud-Poll).

Voraussetzungen

1. Ein eBike mit Bosch Smart System (z. B. Performance Line CX, SX, etc.) - für eBike System 2 (BES2) siehe Hinweis direkt unten
2. Ein Bosch SingleKey ID Account - falls noch nicht vorhanden, erstelle einen unter singlekey-id.com
3. Dein eBike ist mit der Bosch eBike Flow App (iOS / Android) verknüpft
4. Zugang zum Bosch eBike Flow Portal (portal.bosch-ebike.com)

Schritt-für-Schritt-Anleitung

Zwei Systeme: Die folgenden Schritte beschreiben die Einrichtung für das Smart System. Für eBike System 2 (BES2) sind die Schritte fast gleich — die wenigen Unterschiede (u. a. ein eBike-Connect-Konto statt der SingleKey ID) stehen im Abschnitt „eBike System 2 (BES2) einrichten" weiter unten.

Schritt 1: App im Bosch Data Act Portal registrieren

Home Assistant muss sich gegenüber der Bosch-API als „App" ausweisen - dafür registrierst du hier eine solche App und erhältst eine Kennung (Client-ID), die du in Schritt 4 einträgst.

1. Gehe zu portal.bosch-ebike.com/data-act/app
2. Melde dich mit deiner SingleKey ID an
3. Klicke auf "App erstellen"
4. Fülle das Formular aus:

> Achtung, Verwechslungsgefahr: Die folgenden zwei Felder sind beides my.home-assistant.io-Adressen und sehen auf den ersten Blick ähnlich aus. Die Reihenfolge im Bosch-Formular kann von dieser Tabelle abweichen - trage jeden Wert exakt in das Feld mit dem passenden Namen ein, nicht nach Position. Vertauscht bekommst du beim Klick auf „Service aktivieren" die Meldung „Invalid parameters are given", bzw. beim Autorisieren in Home Assistant „Invalid parameter: redirect_uri" von Bosch.

| Feld im Bosch-Formular | Wert | Wofür | |---|---|---| | Redirect URI | https://my.home-assistant.io/redirect/oauth | Rücksprung-Adresse nach dem Bosch-Login (OAuth-Callback) - muss exakt so lauten, das ist die offizielle „My Home Assistant"-Weiterleitung, über die Home Assistant den Login automatisch abschließt. | | Login URL | https://my.home-assistant.io/redirect/config_flow_start/?domain=ha_bosch_ebike | Link, den „Service aktivieren" im eBike Manager öffnet, um den Einrichtungs-Flow direkt in deiner Home-Assistant-Instanz zu starten. |

!Bosch-Portal-Formular „Create your Client application" mit Login URL und Redirect URI(s)

> Hinweis: Die „My Home Assistant"-Integration muss in HA aktiviert sein (Standard). Falls du sie deaktiviert hast, trage bei Redirect URI stattdessen https:///auth/external/callback ein.

1. Nach dem Erstellen erhältst du eine Client-ID (Format euda-xxxxxxxx-...), die im Portal in der App-Übersicht angezeigt wird.

Schritt 2: Client-ID sichern

Kopiere die Client-ID - du brauchst sie gleich.

Schritt 3: Integration in Home Assistant installieren

Installiere die Integration über HACS (Detailschritte im Abschnitt „HACS-Installation" weiter unten) und starte Home Assistant neu. Erst danach kann der Freigabe-Link aus dem eBike Manager den Einrichtungs-Flow öffnen.

Schritt 4: Integration einrichten (über „Service aktivieren")

Im eBike Manager:

1. Öffne Mein eBike → eBike Manager und dort den Bereich Data Act (erreichbar über flow.bosch-ebike.com).
2. Klicke beim Eintrag für deine in Schritt 1 angelegte App auf „Service aktivieren". Daraufhin öffnet sich automatisch deine Home-Assistant-Instanz (über die in Schritt 1 hinterlegte Login-URL).

1. Der Einrichtungs-Flow öffnet sich: Client-ID einfügen, Autorisieren, bei Bosch anmelden und bestätigen.
2. Die Integration ist jetzt eingerichtet - aber die Entitäten fehlen noch, weil die Datenfreigabe pro Bike noch nicht aktiviert ist. Das erledigst du in Schritt 5.

Hinweis: Alternativ kannst du die Integration auch manuell hinzufügen (Einstellungen → Geräte & Dienste → Integration hinzufügen → "Bosch eBike", Client-ID einfügen, Autorisieren). Kein localhost und kein Copy & Paste: Home Assistant übernimmt den Login-Rücksprung über die "My Home Assistant"-Weiterleitung, Access- und Refresh-Token werden danach automatisch erneuert.

Schritt 5: Datenfreigabe pro Bike aktivieren

Ohne aktivierte Freigabe antwortet die API mit 403 Forbidden und es erscheinen keine Entitäten.

1. Gehe zurück zu Mein eBike → eBike Manager → Data Act.
2. Aktiviere dort den Schalter (Toggle) für den in Schritt 1 angelegten Client - die Freigabe gilt pro Bike. Das ist ein separater Schalter, nicht derselbe Link „Service aktivieren" aus Schritt 4. Bei aktiver Freigabe wechselt die Anzeige auf „Service deaktivieren".
3. Lade in Home Assistant die Bosch eBike Integration neu (⋮ → Neu laden). Danach sind alle Entitäten da.

Kommt direkt nach dem Aktivieren noch ein 403 oder fehlen Entitäten: ein paar Minuten warten (die Freigabe propagiert serverseitig) und erneut neu laden. Weitere Fehlerbilder siehe Abschnitt „Fehlerbehebung" weiter unten.

Schritt 6: Kartenansicht einrichten (optional)

Die Integration enthält eine interaktive Lovelace-Karte zur Anzeige deiner GPS-Tracks.

Schritt A: Ressource registrieren

Hinweis: Ab Version 1.16.27 registriert sich diese Ressource automatisch, sobald Home Assistant vollständig gestartet ist - sicher, ohne andere vorhandene Ressourcen zu verändern (die fehlerhafte, datenverlust-anfällige Variante aus früheren Versionen wurde ersetzt). In der Regel musst du hier also nichts tun. Nur falls die Karte trotzdem als „Custom element doesn't exist" erscheint (z. B. weil du Ressourcen im YAML-Modus verwaltest), trage sie einmalig manuell wie folgt ein.

1. Gehe zu Einstellungen → Dashboards
2. Klicke oben rechts auf das ⋮ Drei-Punkte-Menü → Ressourcen
3. Klicke auf + Ressource hinzufügen (unten rechts)
4. Gib folgende Daten ein:

1. Klicke auf Erstellen

1. Öffne dein gewünschtes Dashboard
2. Klicke oben rechts auf den Stift ✏️ (Bearbeiten-Modus)
3. Klicke auf + Karte hinzufügen
4. Scrolle ganz nach unten und wähle Manuell (YAML-Eingabe)
5. Füge folgenden Code ein:

type: custom:bosch-ebike-map-card
   height: 400

1. Klicke auf Speichern

Tipp: Die Höhe (height) kannst du anpassen (200–1000 Pixel). Empfehlung: 400 für Smartphones, 500 für Desktops.

Wer mehr Platz für die Karte selbst braucht, kann Kopfzeile, Datums-Navigator und Sortier-Dropdown einzeln per Editor oder YAML ausblenden:

type: custom:bosch-ebike-map-card
height: 400
show_header: true
show_nav: true
show_sort: true

Alle drei show_*-Flags sind standardmäßig aktiv (sichtbar); einzeln auf false setzen blendet Kopfzeile, Datums-Navigator bzw. Sortier-Dropdown aus. show_nav steuert sowohl die eingebettete als auch die Vollbild-Navigationsleiste.

Hinweis: Bei show_nav: false erscheinen als Ersatz kompakte ◀▶-Pfeile im Statistikbereich unterhalb der Karte, damit weiterhin zwischen Fahrten gewechselt werden kann.

Die Karte zeigt:

• GPS-Track mit geschwindigkeitsabhängiger Farbcodierung (blau → grün → gelb → rot)
• Start-Marker (grün) und Ziel-Marker (rot)
• Fahrtinformationen (Distanz, Dauer, Ø/Max Speed, Höhenmeter, Kalorien)
• ◀ Prev / Next ▶ Buttons und Date-Picker zum Durchblättern aller Fahrten
• ▶ Chase-Cam-Button öffnet die aktuell sichtbare Tour in einem Vollbild-Overlay mit der kompletten 3D-Card-Wiedergabe (2D / 3D / Satellit, Slider, Nord-Fix-Toggle, Vollbild). Schließen via X-Button oder Escape.

Hinweis: Wenn die Karte nach einem Update nicht korrekt angezeigt wird, leere den Browser-Cache mit Ctrl+Shift+R (Hard Reload).

HACS-Update für die Karten: Alle vier Lovelace-Karten (Map, Heatmap, Calendar, Dashboard) liegen in einer einzigen JS-Datei (bosch-ebike-map-card.js) und werden automatisch mit der Integration aktualisiert. Nach einem Versions-Update von HACS ein Hard Reload des Browser-Caches durchführen, sonst kann der Card-Picker eine neue Karte noch nicht anzeigen.

eBike System 2 (BES2) einrichten

Für eBike System 2 ist die Einrichtung nahezu identisch zur obigen Smart-System-Anleitung. Es gibt genau zwei Unterschiede:

1. Anmeldung im Data Act Portal (Schritt 1): BES2-Besitzer melden sich unter portal.bosch-ebike.com/data-act/app über „Bosch eBike Connect user? Log in here" an (die eBike-Connect-Identität), nicht über die SingleKey ID. App-Name, Redirect URI, Login URL und „Confidential client" werden genauso ausgefüllt wie beim Smart System (Schritt 1).
2. Systemauswahl in Home Assistant (Schritt 4): Sobald sich der Einrichtungs-Flow öffnet, wähle im ersten Schritt eBike System 2 und gib anschließend die Client-ID ein. Autorisieren und die optionale Karte (Schritt 6) sind identisch zum Smart System.

Datenfreigabe pro Bike (Schritt 5) – abweichend für BES2: Der normale Einstieg „Mein eBike → eBike Manager" bei flow.bosch-ebike.com ist auf die SingleKey-ID zugeschnitten und zeigt eBike-Connect-Konten keine passende Data-Act-Seite. Nutze stattdessen diesen direkten Link, der dich als eBike-Connect-Nutzer anmeldet und auf die Data-Act-Seite bringt: flow.bosch-ebike.com/login?returnTo=%2Fdata-act&kc_idp_hint=ebike-connect. Aktiviere dort wie in Schritt 5 oben beschrieben den Schalter (Toggle) für deinen in Schritt 1 angelegten Client, lade danach die Integration in Home Assistant neu.

Voraussetzung für BES2: ein eBike-Connect-Konto (ebike-connect.com) statt der SingleKey ID. Die Data-Act-Verfügbarkeit ist weiterhin auf EU-Konten beschränkt.

Integration meldet Erfolg, aber 0 Bikes? Anders als beim Smart System (dort kommt bei fehlender Freigabe ein 403 Forbidden) antwortet die BES2-API bei fehlender Freigabe oft einfach mit einer leeren Bike-Liste, ohne Fehler. last_update_success: true bei bike_count: 0 in den Diagnose-Daten ist also kein Zeichen eines Integrations-Fehlers, sondern fast immer, dass die Datenfreigabe über den obigen Link noch nicht aktiviert wurde.

Welche Daten BES2 liefert (und welche nicht), zeigt die Vergleichstabelle im Abschnitt eBike System 2 (BES2) weiter oben.

HACS-Installation (Detailanleitung zu Schritt 3)

Mehrere Bikes oder Konten

Die Integration unterstützt sowohl mehrere Konten als auch mehrere Bikes pro Konto.

Mehrere Bosch-Konten (z. B. ein Bike pro Familienmitglied mit eigener SingleKey ID):

1. Erstelle für jedes Konto im Bosch Data Act Portal eine eigene App-Registrierung mit eigener Client-ID
2. Füge die Integration mehrfach hinzu (Einstellungen → Geräte & Dienste → + Integration hinzufügen → Bosch eBike) und gib dabei jeweils die andere Client-ID ein
3. Jede Instanz hat ihre eigenen Sensoren und Touren

• Die Integration legt automatisch eigene Sensoren pro Bike an (Drive Unit, Akku, Service usw.).
• Touren werden über eine Heuristik (Abgleich des bike-spezifischen odometer-Stands mit startOdometer + distance der jeweiligen Tour) automatisch dem richtigen Bike zugeordnet.

• Konto (nur sichtbar bei mehreren Konten)
• Bike (nur sichtbar bei mehreren Bikes)

Bei "Alle Bikes" und mehr als einem Bike wird dem Tour-Titel zusätzlich der Name des jeweiligen Bikes vorangestellt (z. B. "Trekking Rad — Bike Fahrt"), da Bosch selbst oft nur generische Titel liefert und man sonst beim Durchblättern nicht sieht, zu welchem Bike eine Tour gehört.

Zuordnung direkt in der Karte korrigieren: Ein Klick auf diesen Bike-Namen öffnet eine Auswahlliste mit allen Bikes des jeweiligen Kontos. Damit lässt sich eine falsch zugeordnete Tour direkt im Dashboard dem richtigen Bike zuweisen, ohne den Umweg über die Integrations-Einstellungen. Die Korrektur wird gespeichert und hat dauerhaft Vorrang vor der automatischen Kilometerstand-Heuristik. Touren, die gar nicht zugeordnet werden konnten (oder einem inzwischen entfernten Bike zugeordnet waren), erscheinen als "Nicht zugeordnet" und lassen sich genauso zuweisen. Hinweis: Der Akku-Verbrauchswert einer Tour wird beim Umzuordnen verworfen, da er aus dem Kilometerstand-Verlauf des ursprünglich zugeordneten Bikes stammt und nicht nachträglich neu berechnet werden kann.

Karte fest einem Konto oder Bike zuordnen

Soll eine Karte dauerhaft genau ein Konto oder Bike zeigen (z. B. um zwei Karten nebeneinander für Vergleichsansichten zu haben), trägst Du in der Card-Konfiguration account_id und/oder bike_id ein. Das gewählte Dropdown wird dann ausgeblendet und der Filter ist gelockt.

Die IDs kannst Du im Editor (oben rechts in der Karten-Bearbeitung) bequem aus Dropdowns auswählen - manuelles Heraussuchen ist nicht nötig. Optional kann title den Karten-Header überschreiben:

type: horizontal-stack
cards:
  - type: custom:bosch-ebike-map-card
    height: 400
    title: "Mein Bike"
    account_id: <config_entry_id_konto_a>
  - type: custom:bosch-ebike-map-card
    height: 400
    title: "Partner-Bike"
    account_id: <config_entry_id_konto_b>

Beide Karten zeigen dann immer Touren des jeweils gelockten Kontos und können mit der Datums-/Sortierauswahl unabhängig voneinander durch die Touren-Historie geblättert werden - ideal um z. B. zwei am selben Tag gefahrene Touren direkt zu vergleichen. Die gleichen Optionen funktionieren auch in der bosch-ebike-heatmap-card.

Trick Check (Jump/Manual/Stoppie/Wheelie)

Erkennt Bosch bei einer Tour einen Trick (automatische Erkennung seit Flow-App 1.34), zeigt die Karte einen kleinen grünen Punkt neben dem Tourennamen und zusätzliche Kacheln in der Statistik-Übersicht, z. B. "1×" mit Beschriftung "Jump". Ein Hover über die Kachel zeigt maximale Weite, Dauer und Höhe (bei Sprüngen) bzw. Winkel (bei Manual/Stoppie/Wheelie). Ohne Trick auf der Tour erscheint weder Punkt noch Kachel.

Trick-Sensoren (ab v1.19.36): Für Räder, deren Touren tatsächlich Trick-Daten liefern, entstehen zusätzlich fünf Sensoren zur letzten Fahrt: Letzte Fahrt: Sprünge, Letzte Fahrt: Manuals, Letzte Fahrt: Stoppies, Letzte Fahrt: Wheelies (Zustand = Anzahl) und Letzte Fahrt: Max. Sprunghöhe in Metern, damit sich die Sprunghöhe über die Zeit auftragen lässt. Die vier Zähl-Sensoren führen maximale Weite, Dauer und Höhe bzw. Winkel als Attribute mit.

Meldet dein Rad überhaupt keine Trick-Daten, werden die Sensoren gar nicht erst angelegt — statt dauerhaft „unbekannt" anzuzeigen. Fängt Bosch später damit an, erscheinen sie nach einem Neuladen der Integration. Ein Zähler von 0 heißt „auf dieser Fahrt kein Trick", unbekannt heißt „dafür liefert Bosch nichts" — das ist bewusst unterschieden.

Ladevorgangs-Zusammenfassung

Die Bosch-Cloud kennt „Laden" gar nicht — sie meldet nur den Ladestand zum Zeitpunkt der letzten Synchronisierung. Wer die ESPHome-LDI-Bridge betreibt, hat aber einen Live-Ladestand, und daraus lässt sich der komplette Ladevorgang rekonstruieren.

Ist in den Optionen ein Live-SoC-Sensor für ein Rad hinterlegt, entsteht dafür der Sensor Letzte Ladung: Energie (Wh). Sein Zustand ist die im letzten abgeschlossenen Ladevorgang zugeführte Energie, berechnet aus dem Ladestand-Zuwachs und der eingestellten Akkukapazität. Als Attribute stehen zur Verfügung:

| Attribut | Inhalt | |---|---| | start_soc, end_soc, soc_delta | Ladestand am Anfang und Ende sowie die Differenz (%) | | energy_wh | Zugeführte Energie in Wh (null, wenn keine Kapazität bekannt ist) | | duration_min | Dauer des Ladevorgangs in Minuten | | started_at, ended_at | Beginn und Ende als ISO-8601-Zeitstempel | | signal_gaps | Wie oft der Live-Sensor während des Ladens ausgefallen ist | | in_progress | true, solange gerade geladen wird |

Warum das robust gegen Verbindungsabbrüche ist: Eine BLE-Bridge verliert das Rad zwischendurch — das ist der Normalfall, nicht die Ausnahme (siehe Issue #68). Ein Ausfall des Sensors beendet einen Ladevorgang deshalb nie; er wird nur in signal_gaps mitgezählt. Sonst würde jedes kurze Wegrollen aus der Funkreichweite als abgeschlossene Ladung von 20 % gemeldet.

Ein Ladevorgang gilt als beendet, wenn der Ladestand entweder um mindestens 1 % fällt (Rad wird wieder gefahren) oder 30 Minuten lang nicht mehr steigt (Ladegerät fertig oder abgezogen). Gemeldet wird immer der Höchststand, nicht der letzte Messwert — ein Akku, der 100 % erreicht und danach durch Selbstentladung auf 99 % rutscht, wurde auf 100 % geladen. Aufladungen unter 3 % werden gar nicht erst veröffentlicht, damit das kurze Nachladen im Flur nicht die echte Ladung von letzter Nacht überschreibt.

Der Sensor überlebt einen Neustart von Home Assistant: die letzte abgeschlossene Ladung wird wiederhergestellt. Ein zum Neustart-Zeitpunkt laufender Ladevorgang wird bewusst nicht rekonstruiert. Funktioniert auch mit eBike System 2, da ausschließlich das Live-Signal ausgewertet wird.

Im Energie-Dashboard

Zusätzlich entsteht der Sensor Total Charged Energy, ein fortlaufend steigender Zähler über alle abgeschlossenen Ladungen. Er lässt sich unter Einstellungen → Dashboards → Energie → Einzelne Geräte hinzufügen, danach taucht das eBike mit eigenen Kosten neben dem Hausverbrauch auf.

⚠️ Das ist die Energie, die in den Akku geht, nicht die aus der Steckdose. Sie wird aus dem Ladestand-Zuwachs und der eingestellten Akkukapazität berechnet. Ein Ladegerät verliert grob 10 bis 15 Prozent, der tatsächlich bezahlte Strom liegt also höher. Wer eine messende Zwischensteckdose am Ladegerät hat, sollte diese ins Energie-Dashboard eintragen statt dieses Sensors, denn sie misst genau das, was abgerechnet wird.

Der vorhandene Sensor Wh Lifetime eignet sich dafür übrigens nicht, obwohl Home Assistant ihn anbietet: er zählt die vom Akku abgegebene Energie, also die Fahrleistung, nicht das Laden.

🆕 Restzeit- und Fertig-Zeitpunkt-Schätzung

Mit demselben Live-SoC-Sensor stehen zusätzlich vier weitere Sensoren zur Verfügung, die abschätzen, wie lange der laufende Ladevorgang noch dauert:

• Restzeit bis 80% / Restzeit bis 100% — verbleibende Ladezeit in Minuten bis zum jeweiligen Ladestand
• Voraussichtlich fertig bei 80% / Voraussichtlich fertig bei 100% — der voraussichtliche Uhrzeit-Zeitpunkt (Zeitstempel), zu dem dieser Ladestand erreicht wird

Li-Ionen-Akkus laden nicht linear: unterhalb von 80 % geht es zügig voran, danach (Konstantspannungsphase) spürbar langsamer. Die Schätzung lernt deshalb zwei getrennte Laderaten aus der eigenen Ladehistorie des Rads — eine für 0–80 %, eine für 80–100 % — statt eine einzige Rate über den gesamten Bereich anzunehmen.

Das braucht etwas Ladehistorie: Eine Phasen-Rate gilt erst als vertrauenswürdig, wenn dazu mindestens 3 abgeschlossene Ladevorgänge beigetragen haben und diese zusammen mindestens 10 Prozentpunkte Ladestand-Zuwachs in dieser Phase abgedeckt haben. Bis dahin bleiben die betroffenen Sensoren „nicht verfügbar" — bei einem neuen Rad oder kurz nachdem ein Live-SoC-Sensor erstmals eingerichtet wurde, ist das der Normalfall, kein Fehler. Nach ein paar vollständigen Ladungen füllt sich die Historie automatisch und die Werte erscheinen von selbst. Eine Schätzung bis 100 % ausgehend von unter 80 % braucht dabei beide Phasen-Raten gleichzeitig.

🆕 Live Activity beim Laden (optionaler Blueprint)

Wer den Ladefortschritt zusätzlich auf dem Sperrbildschirm sehen möchte, findet dafür einen optionalen Automations-Blueprint, der eine iOS Live Activity bzw. ein Android Live Update anzeigt: aktueller Ladestand, ein Fortschrittsbalken und ein live mitlaufender Countdown bis 80 % bzw. 100 %. Das läuft vollständig über Home Assistants eigenen notify.mobile_app_*-Mechanismus für Live Activities — eine ganz normale, integrationsunabhängige Companion-App-Funktion. Die Integration selbst bringt dafür nichts Eigenes mit, sie liefert nur die Sensoren, die der Blueprint ausliest.

Das ist optional und wird nicht automatisch mit der Integration installiert. Der fertige Blueprint liegt unter blueprints/automation/ha_bosch_ebike/charge_live_activity.yaml und muss manuell importiert werden:

1. Einstellungen → Automatisierungen & Szenen → Blueprints → Blueprint importieren
2. Als URL einfügen (oder den Button in der Tabelle unten benutzen):

1. Import bestätigen, daraus eine neue Automation anlegen und die Eingaben ausfüllen: ein oder mehrere Smartphones, der Ladevorgangs-Sensor (Letzte Ladung: Energie), der Live-SoC-Sensor sowie die vier Restzeit-/Fertig-Sensoren von oben.

Genau wie die vier Restzeit-Sensoren selbst startet auch die Live Activity bei einem neuen Rad oder kurz nach dem erstmaligen Einrichten eines Live-SoC-Sensors zunächst ohne Countdown — Ladestand und Fortschrittsbalken werden trotzdem angezeigt, der Countdown erscheint von selbst, sobald genug Ladehistorie vorliegt.

POIs entlang der Route

Auf der Karte gibt es einen 📍-Toggle in den Steuerelementen. Aktiviert er, wird im Hintergrund eine Overpass-API-Abfrage gestartet, die folgende Punkte entlang der Route findet (max. ~500 m vom befahrenen Pfad entfernt):

• 🔌 Ladestationen (amenity=charging_station)
• 🛠️ Fahrradgeschäfte und Reparaturstationen (shop=bicycle, amenity=bicycle_repair_station)
• 💧 Trinkwasser (amenity=drinking_water)
• 🚻 Toiletten (amenity=toilets)
• 🍽️ Gastronomie (Restaurants, Cafés, Biergärten, Imbisse — amenity=restaurant/cafe/biergarten/fast_food)

Wartungs-Erinnerungen

Service-Termin selbst setzen

Pro Bike gibt es zwei editierbare Entitäten:

• date._service_due_date - Datum, an dem der nächste Kundendienst fällig ist
• number._service_due_odometer - Kilometerstand, bei dem der nächste Kundendienst fällig ist

Zum Zurücksetzen gibt es pro Bike einen Button button._reset_service_due ("Reset Service Due"): Er verwirft beide manuellen Werte, danach gilt wieder der Bosch-Wert (bzw. nichts, wenn Bosch keinen liefert). Beim Kilometerstand reicht alternativ die Eingabe 0. Der Button ist nötig, weil Home Assistants Datumsauswahl kein "leer" kennt.

Eigene Wartungsposten

Neben dem von Bosch gelieferten Service-Termin (Next Service Date/Next Service Odometer) kannst Du beliebige eigene Wartungsposten anlegen - z. B. Kettenwechsel alle 3000 km, Inspektion alle 365 Tage. Pro Bike wird ein Sensor Maintenance Items Due angelegt; sein Wert ist die Anzahl bald fälliger oder überfälliger Posten, das Attribut items listet alle Details (Restkilometer, Resttage).

Posten anlegen: Entwicklerwerkzeuge → Dienste, Dienst bosch_ebike.add_maintenance aufrufen mit:

• bike_id (aus dem Sensor-Attribut)
• name (z. B. "Kettenwechsel")
• interval_km und/oder interval_days

Posten löschen: Dienst bosch_ebike.remove_maintenance.

Events für Automationen: Bei Erreichen der Schwelle (Standard: 30 Tage / 200 km vor Fälligkeit) werden HA-Events ausgelöst:

• ha_bosch_ebike_service_due_soon / ha_bosch_ebike_service_overdue (für den Bosch-Service)
• ha_bosch_ebike_maintenance_due_soon / ha_bosch_ebike_maintenance_overdue (für eigene Posten)

Event bei neuer Fahrt (ab v1.19.36): Sobald eine abgeschlossene Tour zum ersten Mal in einer Abfrage auftaucht, wird ha_bosch_ebike_new_activity ausgelöst — genau einmal pro Fahrt. Beim ersten Einrichten der Integration passiert das bewusst nicht für die bereits vorhandene Historie, eine neue Automation wird also nicht von hunderten Alt-Fahrten überflutet.

Die Nutzdaten sind flach und bereits in den Einheiten der Sensoren, ein Template muss also nicht rechnen:

| Feld | Einheit | Inhalt | |---|---|---| | bike_id | - | Rad, dem die Fahrt zugeordnet wurde (kann bei Mehr-Rad-Konten null sein) | | activity_id, title, start_time | - | Kennung, Name und Startzeitpunkt der Tour | | distance_km | km | Strecke | | duration_min | min | Fahrzeit ohne Pausen | | average_speed, max_speed | km/h | Durchschnitts- und Höchstgeschwindigkeit | | elevation_gain | m | Höhenmeter aufwärts | | calories | kcal | Verbrannte Kalorien | | has_tricks | - | true, wenn Bosch für die Tour Trick-Check-Daten liefert | | tricks | - | Die vollständigen Trick-Check-Werte (siehe oben), sonst null |

Jedes Feld kann null sein, wenn Bosch es für die Tour nicht liefert. Wichtig: Bosch veröffentlicht eine Tour erst, wenn die App sie hochgeladen hat — das Event kommt also an, wenn die Fahrt in der Cloud ankommt, nicht in dem Moment, in dem du absteigst.

🆕 Fertige Blueprints (ab v1.19.31)

Für die gängigsten Benachrichtigungen liegen im Repo unter blueprints/automation/ha_bosch_ebike/ sechs fertige Automations-Blueprints. Button klicken öffnet direkt den Import-Dialog in deiner eigenen Home-Assistant-Instanz (setzt eine verknüpfte "My Home Assistant"-Instanz voraus); alternativ die Raw-URL der jeweiligen Datei manuell unter Einstellungen → Automatisierungen → Blueprints → Blueprint importieren einfügen.

| Blueprint | Reagiert auf | Import | |---|---|---| | service_due_reminder.yaml | ha_bosch_ebike_service_due_soon / _service_overdue | | | maintenance_reminder.yaml | ha_bosch_ebike_maintenance_due_soon / _maintenance_overdue | | | theft_alert.yaml | Theft Reported-Sensor (Zustand „ein") | | | software_update_available.yaml | Software Update Available-Sensor (Zustand „ein") | | | new_activity.yaml | ha_bosch_ebike_new_activity | | | 🆕 charge_live_activity.yaml | Live-SoC + Ladevorgangs-Sensor (siehe „🆕 Live Activity beim Laden" weiter oben im Abschnitt Laden) | |

Reichweiten-Schätzung

Pro Bike gibt es zwei Sensoren, die die Reichweite schätzen — auf Basis deines tatsächlichen Verbrauchs (distanzgewichteter Durchschnitt über die letzten ~500 km Tour-Historie):

• Estimated Range (Full Battery) — geschätzte Reichweite mit vollem Akku

• Estimated Range (Current) — geschätzte Restreichweite

⚠️ Das ist eine Schätzung, keine Garantie. Die tatsächliche Reichweite

hängt stark von Unterstützungsmodus, Topografie, Wind, Temperatur und

Akkuzustand ab. Die Berechnungsgrundlage ist in den Sensor-Attributen

einsehbar (wh_per_km, tours_used, window_km). Solange weniger als

3 Touren bzw. 30 km Verbrauchsdaten vorliegen, bleiben die Sensoren leer.

Routenplaner-Card (BRouter)

Die Card bosch-ebike-routeplanner-card plant Fahrrad-Routen direkt im Dashboard — auf Basis des Open-Source-Routers BRouter:

type: custom:bosch-ebike-routeplanner-card
height: 480

• Wegpunkte per Klick auf die Karte (Start, Ziel, beliebige Zwischenpunkte;

• Profile: Trekking, Rennrad, MTB, Kürzeste
• POIs entlang der Route (📍-Schalter): Ladestationen, Fahrradläden/Werkstätten,

• Ergebnis: Distanz, Anstieg/Abstieg, Fahrzeit, geschätzter Verbrauch

• Akku-Check: Ampel-Anzeige, ob die Route mit dem aktuellen Akkustand

• Höhenprofil als Diagramm unter der Karte
• GPX-Export der geplanten Route (importierbar in Garmin Connect,

• Routen speichern & laden: geplante Routen unter eigenem Namen ablegen

Optionen: title, height, brouter_url (eigene BRouter-Instanz statt brouter.de), entity (Reichweiten-Sensor), soc_entity (Live-Akkustand).

Datenschutz: Die Wegpunkt-Koordinaten werden zur Routenberechnung an den

konfigurierten BRouter-Server gesendet — standardmäßig der spendenfinanzierte

öffentliche Server brouter.de. Wer das nicht möchte, betreibt BRouter selbst

(Docker) und trägt die URL unter brouter_url ein.

Heatmap-Card - alle Touren auf einer Karte

Eine zweite Card-Variante bosch-ebike-heatmap-card legt alle Touren einer Auswahl als halbtransparente Linien übereinander. Filter-Dropdowns für Zeitraum (30 Tage / 3 Monate / 12 Monate / Alle), Konto und Bike. Darunter eine Statuszeile mit Tour- und Kilometeranzahl der Auswahl.

type: custom:bosch-ebike-heatmap-card
height: 600

Die erste Anzeige kann etwas dauern - bei jeder bisher nicht abgerufenen Tour wird ein zusätzlicher API-Call gemacht (mit Concurrency-Limit). Die Tracks werden serverseitig im Speicher gecacht, weitere Aufrufe sind sofort.

![

... (README truncated for length)