Skriptumgebung

Skriptumgebung

Der CCU-Historian besitzt eine Skriptumgebung, die direkten Zugriff auf die Datenbank besitzt. Dadurch eröffnen sich vielfältige Anwendungen: Automatisierte Massenkonfiguration, Erstellung von Statistiken und Analysen, Manipulation von Zeitreihen, usw.. Skripte können über Werkzeuge → Skriptumgebung eingegeben und ausgeführt werden. Beispielskripte sind in einem eigenen Abschnitt zu finden.

Neben Skripten mit einzelnen Anweisungen können auch umfangreiche Berechnungen, Kombinationen und Analysen von Zeitreihen mit Hilfe von Ausdrücken bzw. Formeln/Termen erfolgen. Beispielausdrücke dazu sind in einem eigenen Abschnitt zu finden.

Die Skriptumgebung verwendet die Programmiersprache Groovy für die Ausführung der Skripte. Der gesamte Sprachumfang kann genutzt werden, allerdings kann absichtlich nur auf bestimmte Klassen bzw. Objekte zugegriffen werden.

Skriptausgabe

Mit den Befehlen print und println (mit Zeilenvorschub) können Skriptausgaben erzeugt werden.

Skript:

print "Hallo "
println "Welt!"
println "Dies erscheint in der nächsten Zeile."

Ausgabe:

Hallo Welt!
Dies erscheint in der nächsten Zeile.

Wenn in einem Skript die Befehle print und println nicht verwendet werden, dann wird als Ausgabe das Ergebnis des letzten Skriptausdrucks angezeigt (ab V3.4.0). Dadurch kann beispielsweise das Ergebnis von Rechenausdrücken direkt angezeigt werden.

Skript:

5+6

Ausgabe:

11

Interessanter ist natürlich die Ausgabe von berechneten Zeitreihen (ab V3.4.0):

Skript:

dataPoint(63).average(daily()).read(parseDate("1.1.2023"), parseDate("4.1.2023"))

Ausgabe:

2023-01-01 00:00:00.000, 13.557506101983593, 2
2023-01-02 00:00:00.000, 10.666991404360811, 2
2023-01-03 00:00:00.000, 7.557838434259367, 2

Vordefinierte Variablen

version (ab V3.4.0)

In der Variablen version ist die Versionsnummer des CCU-Historians zu finden.

database

In der Variable database ist ein Datenbankobjekt zu finden, das den lesenden und schreibenden Zugriff auf die Zeitreihen-Datenbank ermöglicht. Der schreibende Zugriff muss in der Skriptumgebung explizit freigeschaltet werden. Zeitbereiche werden immer als halboffenes Intervall angegeben (begin <= Zeitstempel < end).

// Liste aller Datenpunkte
List<DataPoint> dataPoints

// Datenpunkt mit der angegebenen Historian-ID
// Rückgabe: null, wenn nicht gefunden
DataPoint getDataPoint(int idx) 

// Datenpunkt mit dem angegebenen DataPointIdentifier
// Rückgabe: null, wenn nicht gefunden
DataPoint getDataPoint(DataPointIdentifier id)

// Datenpunkt anlegen
void createDataPoint(DataPoint dp)

// Geänderte Eigenschaften eines Datenpunktes speichern
void updateDataPoint(DataPoint dp)

// Datenpunkt löschen
void deleteDataPoint(DataPoint dp) 

// Zeitstempel des ersten Eintrags
// Rückgabe: null, wenn nicht vorhanden
Date getFirstTimestamp(DataPoint dp)

// Prozesswert des letzten Eintrags
// Rückgabe: null, wenn nicht vorhanden
ProcessValue getLast(DataPoint dp)

// Tatsächliche Zeitreiheneinträge eines Datenpunktes
TimeSeries getTimeSeriesRaw(DataPoint dp, Date begin, Date end)

// Zeitreihe eines Datenpunktes mit interpolierten Einträgen am Beginn und Ende
// des Zeitbereichs
TimeSeries getTimeSeries(DataPoint dp, Date begin, Date end)

// Anzahl der Einträge in einem Zeitbereich
int getCount(DataPoint dp, Date startTime, Date endTime)

// Zeitbereich löschen
int deleteTimeSeries(DataPoint dp, Date startTime, Date endTime)

// Zeitreihe kopieren
int copyTimeSeries(DataPoint dstDp, DataPoint srcDp, Date startTime, Date endTime, Date newStartTime)

// Zeitreihe ersetzen
int replaceTimeSeries(DataPoint dstDp, Iterable<ProcessValue> srcSeries, Date startTime, Date endTime)

// Zeitreiheneintrag zur Datenbank hinzufügen
void consume(Event t) 

// Mehrere Aufrufe transaktional ausführen
Object transactional(Closure cl)

// Persistente Variable lesen
String getConfig(String name)

// Persistente Variable schreiben
void setConfig(String name, String value)

// Backup der Datenbank in Datei schreiben
void createBackup(String fileName)

Vordefinierte Klassen

DataPoint

Ein DataPoint-Objekt wird vom Database-Objekt zurückgegeben und enthält alle Eigenschaften zu einem bestimmten Datenpunkt. Damit geänderte Eigenschaften vom CCU-Historian übernommen werden, müssen diese mit database.updateDataPoint() gespeichert werden. println mit einem DataPoint-Objekt zeigt alle Eigenschaften an.

// Datenpunkt erscheint nicht in der Datenpunktliste
boolean historyHidden

// Datenpunkt wird nicht aufgezeichnet
boolean historyDisabled

// Werte sind vom Typ Zeichenkette
boolean historyString

// Werte sind stetig (z.B. Temperatur im Gegensatz zu einem Schließerkontakt)
boolean continuous

// Datenpunkteigenschaften sollen nicht (erneut) aus der CCU ausgelesen werden (z.B. bei manuellen Anpassungen)
boolean noSynchronization

// Datenpunkteigenschaften wurde einmal aus der CCU ausgelesen
boolean synced

// abgeleiteter Anzeigename des Datenpunktes (nur lesbar)
String displayName

// Allgemeine Datenpunkteigenschaften
// Aus der ReGaHss: displayName, room, function, comment
// Vom Gerät: paramSet, tabOrder, maximum, unit, minimum, control, operations, flags, type, defaultValue
// Vom Historian: preprocType, preprocParam
Map attributes

DataPointIdentifier

Durch ein DataPointIdentifier-Objekt wird ein Datenpunkt eindeutig identifiziert. Es kann für den Aufruf von database.getDataPoint() verwendet werden.

Erstellen:

// Erstellen eines DataPointIdentifier's
new DataPointIdentifier(interfaceId, address, identifier)

Eigenschaften:

// Schnittstelle (z.B. "HmIP")
String interfaceId

// Adresse (z.B. "ABC000000")
String address

// Bezeichner (z.B. "TEMPERATURE")
String identifier

TimeSeries

In einem TimeSeries-Objekt wird eine Zeitreihe gespeichert. Es wird z.B. von database.getTimeSeries() zurückgegeben. Zum Einfügen von Zeitreihen kann es auch manuell erstellt werden.

Erstellen:

// Erstellen einer TimeSeries mit dem dazugehörigen Datenpunkt
new TimeSeries(dataPoint)

Eigenschaften:

// Zugehöriger Datenpunkt
DataPoint dataPoint

// Anzahl der Einträge
int size

Funktionen:

// Iterator über die Zeitreiheneinträge (dadurch kann TimeSeries z.B. für eine each-Schleife verwendet werden)
Iterator<ProcessValue> iterator()

// Eintrag hinzufügen
void add(ProcessValue pv)

// Eintrag an einem bestimmten Index entfernen (Index startet bei 0!).
void remove(int index)

// Eintrag an einem bestimmten Index lesen (Groovy-Kurzform: [idx])
ProcessValue getAt(int idx)

// Eintrag an einem bestimmten Index schreiben (Groovy-Kurzform: [idx])
void putAt(int idx, ProcessValue pv)

ProcessValue

Zeitreihen bestehen aus einzelnen Prozesswerten. Diese können aus Zeitreihen gelesen werden oder manuell erstellt und dann in Zeitreihen eingefügt werden.

Erstellen:

// Erstellt einen Prozesswert (value kann entweder vom Typ Double oder String sein, state ist eine Bitmaske)
new ProcessValue(Date timestamp, Object value, int state)

Eigenschaften:

// Zeitstempel des Prozesswetes als Java-Date-Objekt
Date timestamp

// Wert (Double oder String)
Object value

// Wert direkt als Double konvertiert
Double doubleValue

// Zustand
int state

Zustand eines Prozesswertes (State) als Bitmaske. Mit den zwei niederwertigsten Bits wird die Qualität kodiert:

STATE_QUALITY_BAD = 0x00000000
STATE_QUALITY_QUESTIONABLE = 0x00000001
STATE_QUALITY_NOT_SUPPORTED = 0x00000002
STATE_QUALITY_GOOD = 0x00000003

STATE_PREPROCESSED = 0x00000004
STATE_FIRST_ARCHIVED = 0x00000008

Date

Für Zeitstempel verwendet der CCU-Historian das Java-Date-Objekt. Es enthält die Anzahl an Millisekunden seit 1.1.1970 UTC. Es ist keiner bestimmten Zeitzone zugeordnet. Die im Betriebsystem eingestellte Zeitzone wird erst bei den Funktionen parseDate() oder formatDate() (siehe unten) berücksichtigt.

Eigenschaften:

// Anzahl an Millisekunden seit 1.1.1970 UTC
Long time

Zeitreihenberechnung (ab V3.4.0)

TODO

Vordefinierte Funktionen

Textformatierung

// Zahl als Zeichenkette formatieren (Ländereinstellung wird beachtet)
String formatNumber(Integer number)

// Zeichenkette in eine Zahl konvertieren (Ländereinstellung wird beachtet)
Number parseNumber(String str)

// Zeitstempel formatieren (dd.MM.yyyy HH:mm:ss)
String formatDate(Date date)

// Zeichenkette in ein Zeitstempel konvertieren
// Unterstützte Formate: dd.MM.yyyy HH:mm:ss, dd.MM.yyyy HH:mm, dd.MM.yyyy HH, dd.MM.yyyy, MM.yyyy, yyyyMMddHHmmss, yyyyMMddHHmm, yyyyMMddHH, yyyyMMdd, yyyyMM, yyyy
Date parseDate(String str) {

// Zahl, Datum oder anderes Objekt als Zeichenkette ausgeben
String format(value) 

// Zeitdauer in Millisekunden formatieren 
String formatDuration(Long dur) {

Vordefinierte berechnete Zeitreihen (ab V3.4.0)

TODO