Python-Skripte schreiben

Python-Skripte schreiben

Mit der Einführung von BuildingPro Suites Version 12.2 wurden wichtige Änderungen vorgenommen, die eine Anpassung der Skripte an das neue API-Design erfordern.

Skriptdefinition

Wenn im BuildingPro-Suites-System ein neues Skript erstellt wird, wird automatisch ein Funktionskopf generiert. Dieser Kopf enthält zwei Parameter:

• id: Die eindeutige ID des Skripts.

• eliona: Ein Objekt, über das der Benutzer mit dem BuildingPro-Suites-System interagieren kann.

Die Funktionsdeklaration sieht so aus:

# Imports dürfen nur innerhalb der Funktion hinzugefügt werden
# Die Funktionsdefinition nicht ändern oder löschen
def UserFunction(id, eliona):
	# füge hier deinen Code ein

Module importieren

Alle erforderlichen Module müssen innerhalb der Funktion importiert werden. Es ist wichtig, dass Module nur innerhalb der Funktion importiert werden und keine globalen Importe verwendet werden.

Beispiel:

def UserFunction(id, eliona):
    import random
    # Weitere Codezeilen folgen

---

Methoden des BuildingPro-Suites-Objekts

Das eliona Objekt stellt eine Reihe von Methoden bereit, mit denen Benutzer mit dem BuildingPro-Suites-System interagieren können. Hier sind die wichtigsten Methoden zusammen mit ihren Parametern und Beschreibungen:

Methode	Parameter	Beschreibung
GetHeap	gai: str, subtype: str, attribute: str	Ruft den aktuellen Wert eines Attributs oder das gesamte Daten-JSON eines Assets aus dem Heap ab.
SetHeap	gai: str, subtype: str, data: dict, source: str	Sendet Daten an den Rechner, damit sie verarbeitet und im Heap gespeichert werden.
GetAssetIDByGAI	gai: str	Gibt die numerische Asset-ID für die angegebene GAI zurück.
GetAll	`ids: list[int	str], `subtype: str`	Ruft alle Datenpunkte eines bestimmten Subtyps für eine Liste von Assets ab und gibt sie als Dictionary zurück (GAI → Daten).
SQLQuery	query: str	Führt eine beliebige SQL-Abfrage aus und gibt die Ergebnisse als Liste von Tupeln zurück.
MakeSource	id: int	Erzeugt eine Quellzeichenfolge für Heap-Operationen basierend auf der Funktions-ID.
OpenFile	name: str, mode: str	Öffnet eine Datei im Arbeitsverzeichnis von BuildingPro Suites (analog zu Python’s open()).
AddAssetTag	gai: str, tag: str	Fügt einem Asset ein Tag hinzu (falls noch nicht vorhanden).
RemoveAssetTag	gai: str, tag: str	Entfernt ein Tag von einem Asset (falls vorhanden).
GetTrendRecords	asset_id: int, subtype: str, attr: str, begin: datetime	Ruft historische Messwerte als Liste von TrendRecord(ts, value) ab dem angegebenen Zeitpunkt ab.
WriteTrendRecords	asset_id: int, subtype: str, attr: str, `recs: TrendRecord	Schreibt ein oder mehrere TrendRecord Datensätze in das System.
GetAggregate	agg: Aggregate, asset_id: int, subtype: str, attr: str,raster: str, start: datetime,end: datetime = now()	Berechnet aggregierte Werte (Avg, Sum, Cusum) in einem festen Raster über einen Zeitraum.
GetLastAggregate	agg: Aggregate, asset_id: int, subtype: str, attr: str, raster: str	Gibt das zuletzt kumulierte Aggregat im ausgewählten Raster zurück (einschl. last_ts).

---

Beispielskripte

GetHeap

Beschreibung: Ruft den aktuellen Wert eines Attributs oder das gesamte JSON eines Assets aus dem Heap ab.

Parameter:

• gai: str (erforderlich) – GAI des Assets, z. B., "K86_WP01"

• subtype: str (erforderlich) – Datensubtyp, z. B., "input"

• attribute: str (erforderlich) – Attributname, z. B., "Aussentemperatur"

Beispielcode:

value = eliona.GetHeap("K86_WP01", "input", "Aussentemperatur")

Beispielausgabe:

23.5

---

SetHeap

Beschreibung: Sendet ein Dictionary von Werten an den Rechner, um es zu verarbeiten und im Heap zu speichern.

Parameter:

• gai: str (erforderlich)

• subtype: str (erforderlich)

• data: dict (erforderlich) – z. B., {"Aussentemperatur": 23.5}

• source: str (erforderlich) – typischerweise eliona.MakeSource(id)

Code-Beispiel:

data   = {"Aussentemperatur": 23.5}
source = eliona.MakeSource(id)
eliona.SetHeap("K86_WP01", "input", data, source)

---

GetAssetIDByGAI

Beschreibung: Gibt die numerische Asset-ID für die angegebene GAI zurück.

Parameter:

• gai: str (erforderlich)

Code-Beispiel:

asset_id = eliona.GetAssetIDByGAI("K86_WP01")

---

GetAll

Beschreibung: Ruft alle Datenpunkte eines bestimmten Subtyps für eine Liste von Assets ab und gibt sie als Dictionary zurück (GAI → Daten).

Parameter:

• ids: list[int|str] (erforderlich) – z. B., ["K86_WP01", 1073]

• subtype: str (erforderlich)

Code-Beispiel:

all_data = eliona.GetAll(["K86_WP01"], "input")

---

SQLQuery

Beschreibung: Führt eine beliebige SQL-Abfrage aus und gibt die Ergebnisse als Liste von Tupeln zurück.

Parameter:

• query: str (erforderlich)

Code-Beispiel:

res = eliona.SQLQuery(
    "SELECT data->>'Aussentemperatur' "
    "FROM public.heap "
    "WHERE gai='K86_WP01' AND subtype='input' "
    "ORDER BY timestamp DESC LIMIT 1;"
)

Beispielausgabe:

[('23.5',)]

---

MakeSource

Beschreibung: Generiert eine Quellzeichenfolge (z. B. "ssr:123") für Heap-Operationen basierend auf der Funktions-ID.

Parameter:

• id: int (erforderlich)

Code-Beispiel:

src = eliona.MakeSource(id)

---

OpenFile

Beschreibung: Öffnet eine Datei im Arbeitsverzeichnis von BuildingPro Suites (analog zu Python’s open()).

Parameter:

• name: str (erforderlich) – Dateiname, z. B., "log.txt"

• mode: str (erforderlich) – z. B., "w", "r"

Code-Beispiel:

f = eliona.OpenFile("aussentemp_log.txt", "w")
f.write("Temperatur: 23.5\n")
f.close()

---

AddAssetTag

Beschreibung: Fügt einem Asset ein Tag hinzu, wenn es noch nicht zugewiesen ist.

Parameter:

• gai: str (erforderlich)

• tag: str (erforderlich)

Code-Beispiel:

eliona.AddAssetTag("K86_WP01", "has-aussentemp")

---

RemoveAssetTag

Beschreibung: Entfernt ein Tag von einem Asset, falls vorhanden.

Parameter:

• gai: str (erforderlich)

• tag: str (erforderlich)

Code-Beispiel:

eliona.RemoveAssetTag("K86_WP01", "has-aussentemp")

---

GetTrendRecords

Beschreibung: Lädt eine Liste historischer Messwerte (TrendRecord(ts, value)) ab der angegebenen Startzeit.

Parameter:

• asset_id: int (erforderlich)

• subtype: str (erforderlich)

• attr: str (erforderlich)

• begin: datetime (erforderlich)

Code-Beispiel:

from datetime import datetime, timedelta

aid   = eliona.GetAssetIDByGAI("K86_WP01")
begin = datetime.now() - timedelta(hours=1)
records = eliona.GetTrendRecords(aid, "input", "Aussentemperatur", begin)

---

WriteTrendRecords

Beschreibung: Schreibt ein oder mehrere TrendRecord Datensätze in das System.

Parameter:

• asset_id: int (erforderlich)

• subtype: str (erforderlich)

• attr: str (erforderlich)

• recs: TrendRecord | list[TrendRecord] (erforderlich)

Code-Beispiel:

from datetime import datetime, timedelta
import eliona_types

aid = eliona.GetAssetIDByGAI("K86_WP01")
now = datetime.now()
r1  = eliona_types.TrendRecord(now, 18.7)
r2  = eliona_types.TrendRecord(now + timedelta(minutes=30), 19.2)
eliona.WriteTrendRecords(aid, "input", "Aussentemperatur", [r1, r2])

---

GetAggregate

Beschreibung: Berechnet aggregierte Werte (Durchschnitt, Summe, kumulative Summe) in einem festen Raster über einen Zeitraum.

Parameter:

• agg: Aggregate (erforderlich) – z. B., eliona_types.Aggregate.Avg

• asset_id: int (erforderlich)

• subtype: str (erforderlich)

• attr: str (erforderlich)

• raster: str (erforderlich) – ISO-8601-Dauer, z. B., "PT1H" für stündlich

• start: datetime (erforderlich)

• end: datetime (optional, Standard: now())

• recs: TrendRecord | list[TrendRecord] (erforderlich)

Code-Beispiel:

from datetime import datetime, timedelta
import eliona_types

aid   = eliona.GetAssetIDByGAI("K86_WP01")
end   = datetime.now()
start = end - timedelta(days=1)
aggs  = eliona.GetAggregate(
    eliona_types.Aggregate.Avg,
    aid, "input", "Aussentemperatur",
    "PT1H", start, end
)

Beispielausgabe-Struktur:

[
  TrendAggregate(ts=<datetime>, cnt=<int>, avg=<float>,
                 sum=<float>, first=<float>,
                 min=<float>, max=<float>, last=<float>),
  ...
]

---

GetLastAggregate

Beschreibung: Gibt das zuletzt kumulierte Aggregat im ausgewählten Raster zurück (einschließlich last_ts).

Parameter:

• agg: Aggregate (erforderlich)

• asset_id: int (erforderlich)

• subtype: str (erforderlich)

• attr: str (erforderlich)

• raster: str (erforderlich)

Code-Beispiel:

import eliona_types

aid  = eliona.GetAssetIDByGAI("K86_WP01")
last = eliona.GetLastAggregate(
    eliona_types.Aggregate.Cusum,
    aid, "input", "Aussentemperatur", "P1D"
)

Beispielausgabe-Struktur:

RunningAggregate(
  ts=<datetime>, cnt=<int>, avg=<float>,
  sum=<float>, first=<float>,
  min=<float>, max=<float>, last=<float>,
  last_ts=<datetime>
)

---

Einfaches Skript zur Datenmanipulation

Dieses Beispiel zeigt, wie ein Skript einen Zufallswert erzeugt und in den Heap eines Assets schreibt:

def UserFunction(id, eliona):
    import random

    data = {
        "power_val": random.randint(10, 100)
    }

    eliona.SetHeap("TestInactIn", "input", data, eliona.MakeSource(id))

Beschreibung:

• Das Skript importiert das random Modul.

• Ein Dictionary data wird erstellt, das einen Schlüssel power_val enthält, dem ein Zufallswert zwischen 10 und 100 zugewiesen wird.

• Der erzeugte Wert wird in den Heap des TestInactIn Assets mit der SetHeap Methode geschrieben.

---

Daten abrufen und ändern

In diesem Beispiel wird der Wert eines Attributs von einem Asset abgerufen, geändert und in einem anderen Asset gespeichert:

def UserFunction(id, eliona):
    from datetime import datetime

    heap = eliona.GetHeap("TestInactIn", "input")

    data = {
        "energy_val": heap["power_val"] * 3
    }

    eliona.SetHeap("TestInactIn", "input", data, eliona.MakeSource(id))

Beschreibung:

• Das Skript importiert das datetime Modul.

• Der aktuelle Wert des power_val Attributs wird aus dem Heap des TestInactIn Assets abgerufen.

• Dieser Wert wird verdreifacht und als energy_val.

---

Erweiterte Funktionen und SQL-Abfragen

Mit der SQLQuery Methode können beliebige SQL-Abfragen direkt aus dem Skript ausgeführt werden:

def UserFunction(id, eliona):
    result = eliona.SQLQuery("SELECT * FROM public.asset WHERE gai = 'TestInactIn';")
    # Weitere Verarbeitung des Ergebnisses

Beschreibung:

• Die SQL-Abfrage ruft alle Informationen über das Asset mit der GAI TestInactIn.

• Das Ergebnis kann dann weiterverarbeitet werden.