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.

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.

Umsetzung Lastmanagement API

Umsetzung Lastmanagement API

1. Einleitung

2. Aufbau der JSON-Antwort

2.1 Beispiel

Hinweise

3. Datentypen

3.1 COUNTER – Zählerdaten

Beschreibung

Schlüssel

Felder

Beispiel

Hinweise

3.2 STATION – Ladestationsdaten

Beschreibung

Schlüssel

Felder

Beispiel

Hinweise

4. Statuswerte der Ladestation

4.1 Hauptstatus (STATE)

4.2 Zusätzlicher Status (SUB_STATE)

5. GENERAL – Allgemeine Informationen

Beschreibung

Felder

Beispiel

6. Hinweise zur Verarbeitung

6.1 Datentypen

6.2 Optionale Felder

6.3 Interpretation negativer Werte

6.4 Eindeutige Identifikation

4.1 Hauptstatus (`STATE`)

4.2 Zusätzlicher Status (`SUB_STATE`)