Skip to main content

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. Kommunikationsübersicht

Eigenschaft Beschreibung
Protokoll HTTP/HTTPS
Datenformat JSON
Methode POST
Conntent-type application/json
Conntent-typ PowerDog 1.0
Zeichensatz UTF-8

2.3. 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.3.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.4. Datentypen

3.4.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.4.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.5. Statuswerte der Ladestation

4.5.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.5.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.6. 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
  }
}
Back to top