Zustandsdaten aus BMS und Service

Dynamische Batteriedaten (Gesundheitszustand, Kapazitätsverlust, Vollzyklen, Temperaturen) kommen aus dem Batteriemanagementsystem (BMS), einer Monitoring-Plattform oder einem Servicewerkzeug, manchmal über das Servicemodul des ERP. In diesem Ablauf meldet die Middleware sie je Einheit mit updateCondition. Die Einzelheiten der Operation stehen in Zustandsdaten senden; diese Seite zeigt den Ablauf drumherum.

sequenceDiagram
  participant BMS as BMS oder Servicewerkzeug
  participant MW as Middleware
  participant BP as BatteryPass-API
  BMS->>MW: neue Messwerte je Seriennummer
  MW->>MW: BatteryPass-ID in der eigenen Zuordnung nachschlagen
  alt Seriennummer noch nicht zugeordnet
    MW->>BP: listBatteries mit serial_prefix (Scope read)
    BP-->>MW: die Einheit
  end
  MW->>BP: updateCondition mit measured_at (Scope condition)
  BP-->>MW: accepted, skipped, publication
  BP->>BP: Ereignis condition_update mit dem Schlüssel, Neuveröffentlichung nach Richtlinie

Der SchlüsselLink zum Abschnitt kopieren

Ein Schlüssel je BMS-Plattform oder Servicepartner, mit den Scopes condition (zum Melden) und read (zum Finden der Einheiten). Zwei Schlüssel mit je einem Scope gehen genauso. Ein condition-Schlüssel kann für jede Einheit Ihrer Organisation melden; geben Sie einem Servicepartner also nur dann einen Schlüssel, wenn Sie ihm das zutrauen.

Die Einheit einmal findenLink zum Abschnitt kopieren

Die Middleware führt eine Zuordnungstabelle von Seriennummer zu BatteryPass-ID. Für eine Seriennummer, die sie noch nicht kennt, fragt sie listBatteries mit serial_prefix und wählt die Einheit, deren serial_number genau passt (Seriennummern sind je Modell eindeutig; geben Sie battery_model_id mit, wenn zwei Modelle dasselbe Nummernschema teilen):

curl -sS "$BATTERYPASS_URL/api/v1/batteries?serial_prefix=SV2027-000184&limit=10" \
  -H "Authorization: Bearer $BATTERYPASS_BMS_KEY" | jq '.items[] | select(.serial_number == "SV2027-000184") | .id'

Messwerte meldenLink zum Abschnitt kopieren

curl -sS -X PATCH "$BATTERYPASS_URL/api/v1/batteries/0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f/condition" \
  -H "Authorization: Bearer $BATTERYPASS_BMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"measured_at": "2026-10-24T06:00:00Z", "note": "BMS-Tagesbericht",
       "values": [{"field_key": "condition.capacity_fade", "value": 3.5},
                  {"field_key": "condition.number_of_full_cycles", "value": 412}]}'

Weil eine gleich alte oder ältere Messung als die gespeicherte übersprungen wird, ändert derselbe Messwert nach einer Zeitüberschreitung nichts mehr: Deshalb ist die Wiederholung oben sicher. Senden Sie die Messungen einer Einheit in der Reihenfolge, in der sie entstanden sind.

Was BatteryPass damit machtLink zum Abschnitt kopieren

• Angenommene Werte werden als freigegebene Messungen ohne Prüfer gespeichert (Messdaten haben keinen Prüfschritt), mit ihrem measured_at.
• Die Meldung legt ein Lebenszyklus-Ereignis condition_update an; dieses Ereignis nennt den Schlüssel (api_key) und hat die Quelle api. Die Werte selbst tragen den Schlüssel nicht. Das Audit-Log nennt den Schlüssel als Handelnden.
• Ein veröffentlichter Pass wird so neu veröffentlicht, wie Ihre Organisation es eingestellt hat: sofort (publication.outcome ist published oder unchanged) oder durch den täglichen Auftrag (scheduled). blocked heißt, dass jetzt eine Pflichtangabe fehlt; der Pass steht auf update_needed, und ein Mitglied muss handeln.

Was nie fließtLink zum Abschnitt kopieren

Nur die dynamischen Felder der Einheit (Registerabschnitt condition). Keine Standort- oder GPS-Daten, keine Fahrzeug- oder Halterdaten, keine Namen von Bedienpersonal. Eine Notiz ist Freitext, der in der Historie der Einheit landet: Füllen Sie sie aus einer festen Vorlage.

FehlerbehandlungLink zum Abschnitt kopieren