Skip to main content

Umsetzung Lastmanagement API

Umsetzung Lastmanagement API

1. Einleitung

Die Lastmanagement API stellt über eine HTTP-Schnittstelle aktuelle Betriebs- und Messdaten des Lastmanagementsystems im JSON-Format bereit. Ziel ist die Integration in externe Systeme wie Energiemanagement-, Monitoring- oder Backend-Lösungen.

Die API ist als lesende Schnittstelle konzipiert und liefert eine strukturierte Übersicht über:

  • Zähler (COUNTER)
  • Ladestationen (STATION)
  • Allgemeine Systeminformationen (GENERAL)

2. Aufbau der JSON-Antwort

Die JSON-Antwort besteht aus mehreren Objekten auf oberster Ebene. Eine Antwort kann mehrere Zähler (COUNTER) sowie mehrere Ladestationen (STATION) enthalten. Zusätzlich wird ein Objekt mit allgemeinen Informationen (GENERAL) bereitgestellt.

2.1 Beispiel

{
  "buscounter_0000000001": {
    "CURRENT_L1": 0.00,
    "CURRENT_L2": 0.00,
    "CURRENT_L3": 0.00,
    "POWER_TOTAL": 0,
    "TYPE": "COUNTER",
    "VALID_CURRENT": "false",
    "VALID_POWER": "false"
  },
  "buscounter_1776089320": {
    "CURRENT_L1": 0.30,
    "CURRENT_L2": -0.10,
    "CURRENT_L3": -0.10,
    "POWER_TOTAL": 20,
    "TYPE": "COUNTER",
    "VALID_CURRENT": "true",
    "VALID_POWER": "true"
  },
  "loadmanagement_0000000001": {
    "CURRENT_L1": 0.00,
    "CURRENT_L2": 0.00,
    "CURRENT_L3": 0.00,
    "CURRENT_LIMIT": 0.00,
    "ENERGY_DIFF": 0,
    "ENERGY_TOTAL": 0,
    "PRIO": 1,
    "SET_CURRENT": -1.00,
    "STATE": "STATE_OFFLINE",
    "SUB_STATE": "SUBSTATE_OK",
    "TIME_CONNECT": 1776156813,
    "TYPE": "STATION",
    "VALID_CURRENT": "true",
    "VALID_ENERGY": "true"
  },
  "loadmanagement_0000000002": {
    "CURRENT_L1": 0.00,
    "CURRENT_L2": 0.00,
    "CURRENT_L3": 0.00,
    "CURRENT_LIMIT": 0.00,
    "ENERGY_DIFF": 0,
    "ENERGY_TOTAL": 0,
    "PRIO": 2,
    "SET_CURRENT": -1.00,
    "STATE": "STATE_OFFLINE",
    "SUB_STATE": "SUBSTATE_OK",
    "TIME_CONNECT": 1776156813,
    "TYPE": "STATION",
    "VALID_CURRENT": "true",
    "VALID_ENERGY": "true"
  },
  "GENERAL": {
    "API_VERSION": 1.0
  }
}

Hinweise

  • Variable Anzahl: Die Anzahl der COUNTER- und STATION-Objekte kann je nach Installation variieren.
  • Eindeutige Schlüssel: Jeder Eintrag ist über seinen Schlüssel eindeutig identifizierbar.
  • Klassifizierung über TYPE: Das Feld TYPE ermöglicht eine einfache Unterscheidung der Objekte.
  • Optionale Felder: Einige Felder können fehlen, wenn die jeweilige Ladestation diese Informationen nicht bereitstellt.

3. Datentypen

3.1 COUNTER – Zählerdaten

Beschreibung

Ein COUNTER repräsentiert die Messwerte eines Energiezählers, beispielsweise eines Haupt- oder Gruppenzählers. Diese Daten sind essenziell für die Regelung des Lastmanagements.

Schlüssel

Der Name des JSON-Objekts entspricht dem eindeutigen Identifikator des Zählers, z. B.:

"buscounter_1776089320"

Felder

Feld Typ Einheit Beschreibung
TYPE String – Kennzeichnung des Datensatzes.
CURRENT_L1 Number A Strom auf Phase L1.
CURRENT_L2 Number A Strom auf Phase L2.
CURRENT_L3 Number A Strom auf Phase L3.
POWER_TOTAL Number W Gesamtleistung des Zählers.
VALID_CURRENT String ("true" / "false") – Gibt an, ob die Stromwerte gültig sind.
VALID_POWER String ("true" / "false") – Gibt an, ob der Leistungswert gültig ist.

Beispiel

{
  "buscounter_1776089320": {
    "TYPE": "COUNTER",
    "CURRENT_L1": 12.5,
    "CURRENT_L2": 11.8,
    "CURRENT_L3": 13.1,
    "POWER_TOTAL": 8200,
    "VALID_CURRENT": "true"
  }
  ...
}

Hinweise

  • Negative Strom- oder Leistungswerte können je nach Messrichtung auftreten.
  • Die Felder VALID_CURRENT und VALID_POWER werden als Strings übertragen und nicht als JSON-Booleans.

3.2 STATION – Ladestationsdaten

Beschreibung

Ein STATION-Eintrag beschreibt den aktuellen Zustand einer Ladestation innerhalb des Lastmanagements. Neben Messwerten enthält er auch Regelungs- und Statusinformationen.

Schlüssel

Der Name des JSON-Objekts entspricht dem configKey der Ladestation, z. B.:

"loadmanagement_0000000001"

Felder

Feld Typ Einheit Beschreibung
TYPE String – Kennzeichnung des Datensatzes.
PRIO Integer – Priorität der Ladestation im Lastmanagement.
SET_CURRENT Number A Vom Lastmanagement vorgegebener Soll-Ladestrom.
CURRENT_LIMIT Number A Aktuelle Strombegrenzung der Ladestation.
CURRENT_L1 Number A Strom auf Phase L1.
CURRENT_L2 Number A Strom auf Phase L2.
CURRENT_L3 Number A Strom auf Phase L3.
VALID_CURRENT String ("true" / "false") – Gibt an, ob die Stromwerte gültig sind.
ENERGY_TOTAL Number Wh Gesamter Energiezählerstand der Ladestation.
VALID_ENERGY String ("true" / "false") – Gibt an, ob der Energiewert gültig ist.
ENERGY_DIFF Number Wh Geladene Energie seit Beginn des aktuellen Ladevorgangs.
TIME_CONNECT Integer Sekunden Unix-Timestamp des Zeitpunkts, zu dem das Fahrzeug angesteckt wurde.
STATE String – Hauptstatus der Ladestation.
SUB_STATE String – Zusätzliche Statusinformation.

Beispiel

{
  "loadmanagement_0000000001": {
    "CURRENT_L1": 0.00,
    "CURRENT_L2": 0.00,
    "CURRENT_L3": 0.00,
    "CURRENT_LIMIT": 0.00,
    "ENERGY_DIFF": 0,
    "ENERGY_TOTAL": 0,
    "PRIO": 1,
    "SET_CURRENT": -1.00,
    "STATE": "STATE_OFFLINE",
    "SUB_STATE": "SUBSTATE_OK",
    "TIME_CONNECT": 1776156813,
    "TYPE": "STATION",
    "VALID_CURRENT": "true",
    "VALID_ENERGY": "true"
  }
  ...
}

Hinweise

  • Einige Felder können optional sein, abhängig von den Fähigkeiten der Ladestation. (Zählerstand, Soc, Ladefreigabe, etc.)
  • TIME_CONNECT ist ein Unix-Timestamp und kann zur Berechnung der Verbindungsdauer verwendet werden.

4. Statuswerte der Ladestation

4.1 Hauptstatus (STATE)

Wert Beschreibung
STATE_OFFLINE Ladestation ist offline oder nicht erreichbar.
STATE_NOT_CONNECTED Kein Fahrzeug verbunden.
STATE_CONNECTED Fahrzeug verbunden, lädt jedoch nicht.
STATE_CHARGING_C Fahrzeug lädt (Status C).
STATE_CHARGING_D Fahrzeug lädt (Status D).
STATE_ERROR_E Fehlerzustand der Ladestation (Status E).
STATE_ERROR_F Fehlerzustand der Ladestation (Status F).

4.2 Zusätzlicher Status (SUB_STATE)

Wert Beschreibung
SUBSTATE_OK Keine zusätzliche Statusinformation.
SUBSTATE_EXTERN_STOP Externe Abschaltung.
SUBSTATE_EVU_STOP Abschaltung durch den Energieversorger.
SUBSTATE_EVU_REDUCTION Reduktion auf Mindeststrom durch den Energieversorger.
SUBSTATE_NO_GROUP Ladestation ist keiner Gruppe zugeordnet.
SUBSTATE_INVALID_COUNTER_MAIN Hauptzähler ist ungültig.
SUBSTATE_INVALID_COUNTER_GROUP Gruppenzähler ist ungültig.

5. GENERAL – Allgemeine Informationen

Beschreibung

Der Bereich GENERAL enthält Metadaten zur Schnittstelle.

Felder

Feld Typ Beschreibung
API_VERSION Number Versionsnummer der JSON-Schnittstelle.

Beispiel

{
  "GENERAL": {
    "API_VERSION": 1.0
  }
}

6. Hinweise zur Verarbeitung

6.1 Datentypen

  • Numerische Werte werden als Zahlen übertragen.
  • Die Felder VALID_* werden als Strings ("true" / "false") übertragen.

6.2 Optionale Felder

Nicht jede Ladestation stellt alle Informationen zur Verfügung. Fehlende Felder bedeuten daher nicht zwangsläufig einen Fehler.

6.3 Interpretation negativer Werte

Negative Strom- oder Leistungswerte können je nach Messrichtung des Zählers auftreten und sind systembedingt möglich.

6.4 Eindeutige Identifikation

Jeder Zähler und jede Ladestation wird über seinen eindeutigen Schlüssel im JSON identifiziert. Das Feld TYPE dient zusätzlich zur Klassifizierung.

Back to top