SIA Connect – Integrationsdokumentation

Inhaltsverzeichnis

Werkzeuge und Zugang
Hardwareinstallation in der IT-Umgebung des Kunden
Allgemeine Konfiguration – SIA zu Yggio
Tag-Konfiguration in SIA
Weiterleitungskonfiguration zu Yggio
Einrichtung für NODA Energy View
Watchdog – Methoden und Fallstricke
Fehlerbehebung
Einschränkungen
Empfehlungen

1. Werkzeuge und Zugang

1.1 VPN

SIA Connect wird innerhalb des Gebäudenetzwerks des Kunden installiert und ist normalerweise nicht direkt aus dem Internet erreichbar. Der Fernzugriff erfolgt über ein VPN, das einen verschlüsselten Peer-to-Peer-Tunnel zum Gerät aufbaut. Es kann jede beliebige VPN-Lösung verwendet werden.

Voraussetzungen:

VPN-Client bei der Inbetriebnahme auf dem SIA-Gerät installiert
Gerät im richtigen VPN-Netzwerk (Organisation/Kunde) hinzugefügt
Zugang zur VPN-Verwaltungsoberfläche, um neue Geräte zu registrieren

Ohne funktionierenden VPN-Zugang ist eine Fernfehlerbehebung praktisch unmöglich. Überprüfen Sie immer, dass das VPN funktioniert, bevor Sie einen Standort verlassen.

1.2 SIA Connect Web-UI

Die Konfigurationsoberfläche von SIA wird über einen Browser unter der IP-Adresse des Geräts aufgerufen, üblicherweise über Port 80 oder 443, je nach Installation.

1.3 Yggio

Yggio ist der IoT-Broker, der als Vermittler zwischen SIA und nachgelagerten Systemen wie NODA Energy View oder Energy Opticon fungiert. Der Zugriff erfolgt über die Yggio-Web-UI oder die REST-API.

2. Hardwareinstallation in der IT-Umgebung des Kunden

SIA Connect benötigt folgenden Netzwerkzugriff:

Richtung	Protokoll	Ziel	Port	Zweck
Ausgehend	MQTTS	mqtt.example1.yggio.net	8883	Daten an Yggio veröffentlichen
Ausgehend	HTTPS	Yggio REST-API	443	Registrierung, Konfiguration
Ausgehend	VPN	VPN-Server	(variiert)	Fernzugriff
Intern	Modbus TCP	DUC/PLC	502 (Standard)	Register lesen/schreiben
Intern	ADS	Beckhoff TwinCAT	48898	Variablen lesen/schreiben
Intern	BACnet/IP	BACnet-Geräte	47808	Objekte lesen/schreiben

Hinweis: Die gesamte Kommunikation von SIA ist ausgehend. SIA muss nicht aus dem Internet erreichbar sein.

Erstinbetriebnahme: Das Gateway wird mit einer werkseitigen statischen Standard-IP für die Erstkonfiguration ausgeliefert (auch über eine direkte USB-C-Verbindung erreichbar). Diese muss vor der Bereitstellung auf eine Adresse im Netzwerk des Kunden geändert werden – siehe die Hardware-Einrichtungsanleitung des Herstellers für die Standard-IP und das USB-C-Verfahren.

3. Allgemeine Konfiguration – SIA zu Yggio

3.1 MQTT-Connector

SIA kommuniziert mit Yggio über MQTTS (MQTT über TLS). Erstellen Sie einen MQTT-Connector in SIA mit folgenden Einstellungen:

Parameter	Wert
Broker	`ssl://<yggio_mqtt_broker>`
Port	`8883`
Topic	`siaconnect/<SIA_UUID>`
Keep Alive	`30` Sekunden (empfohlen)
QoS	0 oder 1, je nach Anforderung

Authentifizierung: Die Broker-Verbindung erfordert einen MQTT-Benutzernamen und ein Passwort. Diese sind weder in der SIA- noch in der Yggio-UI verfügbar – fordern Sie sie beim technischen Support-Team an, wenn Sie den Connector einrichten. Der Broker akzeptiert unabhängig vom Topic-Namen keine Verbindung ohne gültige Zugangsdaten.

Hinweis: Legen Sie den SIA-Connect-Connector in Yggio an, bevor Sie publizieren. Der Connector trägt dieselbe <SIA_UUID>, und erst durch sein Anlegen entstehen die Queue und das Binding, in die siaconnect/<SIA_UUID> liefert. Publizieren Sie auf das Topic, bevor der Connector existiert, kommen die Nachrichten nirgendwo an, ohne dass Yggio etwas davon zeigt. Das Topic ist an die UUID dieses Connectors gebunden und gehört daher nicht zu den Topics, die sich als Reserved MQTT Topic registrieren lassen.

Kommandounterstützung (optional): Damit Yggio Kommandos/Sollwerte an SIA zurückmelden kann (verwendet von Subscribe-Mappings – siehe 5.4 und 6.5), werden separate Zugangsdaten benötigt: die URL der SIA-Weboberfläche sowie ein SIA-API-Benutzername/-Passwort. Ebenfalls nicht in der UI verfügbar – bei Bedarf über das technische Support-Team anfordern.

3.2 SIA/Edge-Gateway-UUID

Jede SIA-Instanz hat eine eindeutige UUID, die als ihr Bezeichner im Yggio-Topic dient – in diesem Dokument SIA UUID genannt, in Yggios eigener Connector-Dokumentation Edge Gateway UUID. Gleicher Wert, zwei Namen. Die UUID findet sich in der SIA-Administrationsoberfläche. Dokumentieren Sie die UUID immer in den Installationsunterlagen des Projekts.

3.3 Keep Alive

Der Keep-Alive-Wert steuert, wie oft SIA einen Heartbeat an den Broker sendet, um die MQTT-Verbindung aufrechtzuerhalten. 30 Sekunden werden basierend auf Erfahrungswerten empfohlen. Ein zu hoher Wert (z. B. 240 s) kann dazu führen, dass der Broker den Client als getrennt betrachtet, was wiederum unnötige Watchdog-Ereignisse und Datenpufferung auslöst.

3.4 Execute on Startup

Die Einstellung Execute on startup auf einem Mapping bewirkt, dass es sofort ausgeführt wird, wenn SIA neu startet, ohne auf die nächste geplante Auslösung zu warten.

Diese Einstellung ist in unseren aktuellen Installationen standardmäßig nicht aktiviert. Aktivieren Sie sie, wenn ein konkreter Bedarf besteht, sicherzustellen, dass veröffentlichte Werte sofort beim Neustart gesendet werden – zum Beispiel für Steuersignale, die andernfalls bis zum nächsten Lesezyklus im falschen Zustand verbleiben könnten.

4. Tag-Konfiguration in SIA

Tags repräsentieren die Datenpunkte, die SIA aus einem Feldsystem liest (oder in dieses schreibt) – zum Beispiel Temperaturen, Durchflussraten oder Steuersignale. Sie können über die Oberfläche von SIA konfiguriert oder als CSV-Datei importiert werden.

4.1 Namenskonventionen

Die Benennung der Tags wird von der Person festgelegt, die die Tag-Liste für die jeweilige Liegenschaft erstellt – ziehen Sie die jeweilige Tag-Liste heran statt einer festen Konvention hier.

⚠️ Das Umbenennen eines Elements in SIA erstellt einen neuen Knoten in Yggio. Das Feld name wird als Knotenbezeichner in Yggio verwendet. Wenn Sie ein bestehendes Element umbenennen, beginnt SIA, unter dem neuen Namen zu veröffentlichen, und in Yggio erscheint ein brandneuer Knoten – der alte Knoten wird nicht automatisch aktualisiert oder entfernt. Der alte Knoten bleibt unter dem vorherigen Namen in Yggio bestehen und muss manuell bereinigt werden.

Stellen Sie die Benennung richtig, bevor Sie sich mit Yggio verbinden, und vermeiden Sie das Umbenennen von Elementen im produktiven Betrieb.

4.2 Trigger Behaviour und Log Condition

Diese beiden Einstellungen steuern, wann SIA einen Wert weiterleitet.

trigger_behaviour

Wert	Bedeutung
`1`	All – sendet bei jedem Lesezyklus, unabhängig von Änderungen
`2`	All changes – sendet nur, wenn sich der Wert geändert hat

Was sollten Sie verwenden?

Das hängt davon ab, wie häufig der Kunde oder das Energiesystem Datenpunkte benötigt:

All changes (trigger_behaviour=2) ist üblich und geeignet, wenn Sie einen Wert nur haben möchten, wenn sich tatsächlich etwas geändert hat – zum Beispiel eine Temperaturmessung. Reduziert unnötigen Datenverkehr.
All (trigger_behaviour=1) wird verwendet, wenn das empfangende System unabhängig von Änderungen regelmäßige Updates erwartet – zum Beispiel gegenüber NODA Energy View, das häufige, periodische Werte für seine Energieanalyse benötigt.

Richten Sie sich immer danach, was das empfangende System benötigt. Besprechen Sie mit dem Kunden oder Systemlieferanten (z. B. NODA, Energy Opticon), welchen Datentakt sie benötigen.

Minimum Trigger Interval

Eine Einstellung, die einen Trigger zwingt, in einem festgelegten Intervall auszulösen, auch wenn die Trigger-Behaviour-Bedingung nicht erfüllt ist – wenn sich der Wert beispielsweise nicht geändert hat und All changes aktiv ist, löst das Mapping trotzdem aus, sobald das Intervall abläuft.

Mit anderen Worten ist es eine Untergrenze (Mindest-Sendefrequenz), keine Obergrenze. Es stellt sicher, dass stabile oder sich langsam ändernde Werte trotzdem periodisch gesendet werden, statt zu verstummen.

Nützlich, wenn:

All changes verwendet wird, das empfangende System aber auch bei stabilen Werten einen regelmäßigen Heartbeat benötigt
Sie sich gegen eingefrorene/veraltete Werte im empfangenden System absichern möchten

Dies ist kein Ratenbegrenzer. Es verhindert nicht, dass ein Mapping häufiger auslöst als das Intervall, wenn die Trigger-Behaviour-Bedingung erfüllt ist.

4.3 Post-Processing

Post-Processing ist ein optionales Skript, das auf dem gelesenen Wert ausgeführt wird, bevor dieser weitergeleitet wird. Es sollte nur verwendet werden, wenn tatsächlich eine Umrechnung erforderlich ist – zum Beispiel, wenn die SPS einen Wert in der falschen Einheit oder Skalierung liefert.

Beispiel 1 – Durchfluss von m³/h zu l/h:

value = value * 1000

Wird verwendet, wenn ein Energiesystem den Volumenstrom in m³/h meldet, das empfangende System aber l/h erwartet.

Beispiel 2 – Skalierungsfaktor für INT16:

value = value / 10

Wird verwendet, wenn eine SPS z. B. 237 liefert, um 23,7 °C darzustellen (Skalierungsfaktor 10 im Quellsystem).

Post-Processing ist nicht erforderlich, wenn der Wert bereits korrekt skaliert und in der richtigen Einheit vorliegt. Prüfen Sie immer die Dokumentation des Quellsystems (DUC-Handbuch, SPS-Registerliste), um festzustellen, ob eine Umrechnung erforderlich ist.

4.4 Modbus TCP

Modbus TCP ist eines der gängigsten Protokolle in Gebäudesystemen. SIA liest und schreibt Register direkt von/zu einer SPS oder DUC über TCP/IP.

Einstellungen pro Tag:

Parameter	Beschreibung
IP-Adresse	Die IP-Adresse der SPS im Netzwerk
Port	Typischerweise `502`, kann aber variieren (z. B. `503` bei manchen Geräten)
Server ID / Unit ID	Typischerweise `1`, hängt aber vom Gerät ab
Registertyp	`3:XXXXX` (Holding Register) oder `4:XXXXX` (Input Register) usw.
Datentyp	`INT16`, `UINT16`, `FLOAT`, `BOOL` usw.

Registerversatz (Offset):
Modbus-Registeradressen in SIA Connect können von denen in der Dokumentation des Geräts abweichen. Häufig gilt ein Offset von ±1, dies ist jedoch nicht universell – er variiert zwischen Herstellern und manchmal zwischen Geräten.

Beispiel: Der Abelko UltraBase20 hat einen Offset von -1, das heißt, Register 01001 in der Dokumentation wird in SIA Connect als 01000 eingegeben.

Überprüfen Sie im Zweifelsfall immer anhand tatsächlicher Lesewerte. Ein falscher Offset liest stillschweigend das falsche Register, statt einen Fehler zu erzeugen.

Praktisches Beispiel – Abelko UltraBase20:

IP: xxx.xx.xx.xxx, Port: 502, Server ID: 1
Datentyp: INT16, Skalierungsfaktor 10 → Post-Processing: value = value / 10
Registeroffset: -1 (Dokumentation zeigt 01001 → in SIA 01000 eingeben)
Hinweis: Einige Register dieses Geräts können FLOAT sein – siehe Handbuch

4.5 Beckhoff / TwinCAT ADS

ADS (Automation Device Specification) ist Beckhoffs proprietäres Kommunikationsprotokoll.

Einstellungen:

Parameter	Wert/Beschreibung
TCP-Port	`48898`
AMS-Port	`851` (TwinCAT 3) oder `801` (TwinCAT 2)
AMS Net ID	IP-Adresse des Geräts + `.1.1`, z. B. `xxx.xx.xx.xxx.1.1`

Voraussetzung: Die eigene AMS Net ID von SIA Connect muss als statische Route in TwinCAT auf der SPS hinzugefügt werden. Ohne dies wird die Verbindung abgelehnt.

⚠️ Instance Timestamp muss auf „Local timestamp“ gesetzt sein (nicht „Server timestamp“) auf allen Beckhoff-TwinCAT-Instanzen. Die Verwendung von Server Timestamp kann im Laufe der Zeit zu einem kritischen Fehler führen. Vom SIA-Connect-Support bestätigt. Details siehe die eingeschränkte Referenz.

Häufiger Fehler: Target port not found – wird üblicherweise verursacht durch:

SIA wurde nicht zu TwinCATs statischen Routen hinzugefügt, oder
die TwinCAT-Runtime läuft nicht auf der SPS

Wichtig – Subscription-/Push-Modus:
Bei Verwendung von ADS arbeitet SIA im Subscription-/Notification-Modus – TwinCAT sendet Änderungsbenachrichtigungen direkt an SIA, statt dass SIA in Intervallen abfragt. Das bedeutet, dass die Einstellung read_interval nicht begrenzt, wie oft SIA Updates von TwinCAT empfängt (und weiterleitet).

In der Praxis kann dies zu sehr häufigen MQTT-Veröffentlichungen führen, unabhängig vom konfigurierten Leseintervall. Verwenden Sie die Einstellung Minimum trigger interval im Mapping (siehe Abschnitt 4.2), um die Veröffentlichungsfrequenz zu begrenzen.

4.6 BACnet

BACnet/IP wird in manchen Installationen verwendet, bei denen das Gebäudeleitsystem Daten über BACnet statt über Modbus oder ADS bereitstellt. Bestätigt funktionierend gegenüber einer Siemens-DUC.

Instanzeinstellungen:

Parameter	Wert/Beschreibung
Adresse	BACnet Device Instance ID des Zielgeräts
Modus	`Gateway`
Leseintervall	Mindestens 60 Sekunden empfohlen – 2 Sekunden erzeugen übermäßigen Datenverkehr

BACnet-IP-Einrichtung:

Parameter	Wert/Beschreibung
Port	`47808` (BACnet-Standard – verwendet UDP, nicht TCP)
Netzwerkschnittstelle	`eth0` oder `eth1`, je nach Installation – wenn eine nicht funktioniert, die andere probieren
Device Id	Die eigene BACnet Device ID von SIA Connect im Netzwerk. Muss eindeutig sein – mit dem DUC-Techniker abklären, welche IDs bereits verwendet werden

Hinweis: BACnet verwendet UDP-Port 47808. Firewall-Regeln müssen UDP ausdrücklich erlauben – TCP-Regeln reichen nicht aus.

Adressformat pro Tag:

(Device Instance ID)(Object Type.Object Instance)

Beispiel: (2100231)(0.43) = Gerät 2100231, Analog Input, Instanz 43.

Bestätigte BACnet-Objekttypen im Einsatz:

Typnummer	Objekttyp	Richtung
`0`	Analog Input	Nur Lesen
`1`	Analog Output	Schreiben
`2`	Analog Value	Lesen + Schreiben (z. B. Sollwerte)
`3`	Binary Input	Nur Lesen
`4`	Binary Output	Schreiben
`5`	Binary Value	Lesen + Schreiben

Herstellerspezifische/proprietäre Objekttypen (z. B. Siemens-spezifische Typen) werden hier nicht behandelt – sie wurden in der Praxis nicht als benötigt bestätigt. Gehen Sie nicht davon aus, dass eine proprietäre Typnummer bei allen Herstellern gleich funktioniert; überprüfen Sie dies am tatsächlichen Gerät, bevor Sie sich darauf verlassen.

Datentyp und Post-Processing: Werte für Siemens-/BACnet-Installationen als REAL bestätigt – kein Post-Processing oder Skalierung erforderlich.

Subnetze und Erkennung: BACnet verlässt sich für die Geräteerkennung auf UDP-Broadcasts, die keine Subnetzgrenzen überschreiten. Wenn sich SIA Connect und das BACnet-Gerät in unterschiedlichen Subnetzen befinden, ist entweder ein BBMD (BACnet Broadcast Management Device) oder eine Foreign-Device-Registrierung erforderlich. Klären Sie mit dem Netzwerk-/DUC-Techniker ab, ob sich die Geräte im selben Subnetz befinden.

4.7 Lese-/Schreibrichtung

Das Feld readwrite steuert, ob SIA einen Punkt liest, in ihn schreibt oder beides. In der SIA-UI erscheint dies als beschreibendes Dropdown; beim CSV-Import ist es ein numerischer Wert.

UI-Bezeichnung	CSV-Wert `readwrite`	Bedeutung
Read only	`1`	SIA liest den Punkt und veröffentlicht ihn an Yggio
Read & Write	`0`	Bidirektional – wird für Sollwert-/Steuer-Tags verwendet, die sowohl ein Publish-Mapping (aktueller Wert raus) als auch ein Subscribe-Mapping (eingehender Befehl rein) benötigen

5. Weiterleitungskonfiguration zu Yggio

5.1 Mapping-Gruppen

In SIA verknüpfen Mappings Tags mit einem MQTT-Connector. Mehrere Tags können Teil derselben Mapping-Gruppe sein und über ein einzelnes MQTT-Item veröffentlicht werden.

Empfehlung: Eine Mapping-Gruppe, die alle relevanten Tags enthält und über ein MQTT-Item veröffentlicht wird, funktioniert in den meisten Fällen gut und vereinfacht die Konfiguration.

5.2 JSON-Vorlage zur Veröffentlichung (Publish)

Die folgende Vorlage wurde als funktionierend für die Veröffentlichung an Yggio bestätigt:

{
  "t": "adstwincat",
  "v": %VALUE%,
  "tag": "%ITEM_SENDER.NAME%",
  "type": "%ITEM_SENDER.TYPE%",
  "ts": "%VALUE.EPOCH_TIME_MS%",
  "unit": "%ITEM_SENDER.UNIT%",
  "d": "%ITEM_SENDER.DESCRIPTION%"
}

Hinweis: Der Wert von "t" (type) muss je nach Quellprotokoll möglicherweise angepasst werden. "adstwincat" ist ein Beispiel aus Beckhoff-Installationen.

⚠️ %ITEM_SENDER.TYPE% löst sich nur für ADS auf – bei BACnet- und Modbus-TCP-Quellen liefert es einen leeren String. Workaround: Den Typwert direkt in der Vorlage fest codieren, z. B. "type":"10", statt sich für Nicht-ADS-Mappings auf %ITEM_SENDER.TYPE% zu verlassen.

Optionen für den Zeitstempel:

%VALUE.EPOCH_TIME_MS% – gibt die Epoch-Zeit in Millisekunden zurück. Funktioniert korrekt mit Live-Daten.
%TIME% – gibt die lokale Zeit des Servers zurück (funktioniert).
%ITEM.VALUE.TIME% – gibt Epoch 0 zurück, wenn der Wert veraltet ist oder sich im Demomodus befindet. In der Produktion vermeiden.

5.3 Bekannter Fehler – `%` im Unit-Feld

⚠️ Temporärer Hinweis – entfernen, sobald der Fehler behoben ist

Setzen Sie niemals ein %-Zeichen in das unit-Feld eines Tags (z. B. für relative Luftfeuchtigkeit) – dies bringt den Vorlagen-Parser von SIA zum Absturz.

Workaround: Setzen Sie die Einheit auf pct oder lassen Sie das Feld leer.
An den SIA-Connect-Support gemeldet. Siehe die eingeschränkte Referenz dafür, warum dies passiert.

Tags, für die SIA Kommandos empfangen soll (z. B. ein Laufsignal oder ein Sollwert von Yggio), werden als Subscribe-Mappings mit readwrite=0 (Read & Write – siehe 4.7) in der CSV konfiguriert.

Ein Steuersignal-Tag benötigt in der Regel zwei Mappings:

Publish – sendet den aktuellen Wert an Yggio (damit das empfangende System den aktuellen Zustand sehen kann)
Subscribe – lauscht auf eingehende Kommandos von Yggio und schreibt sie in die SPS

Beispiel – Sollwertlieferung pro Gebäude (Bastec GT51)

Die Liegenschaftsnamen und Tags unten stammen aus dem Example1-Projekt und dienen als konkretes Arbeitsbeispiel – der zugrunde liegende Mapping-Mechanismus gilt unabhängig von Kunde oder Liegenschaft.

Der folgende Screenshot zeigt eine Reihe von Subscribe-Mappings, bei denen Sollwerte (z. B. Anpassungen der Heizkurve) von Yggio empfangen und in Schreib-Tags in SIA geschrieben werden, die diese wiederum an das Leitsystem jedes Gebäudes weitergeben.

So funktioniert es:

Sender – ein Yggio-Item innerhalb eines Subscribe-Connectors (z. B. SubscribeExample1Yggio). Dies ist der Datenpunkt in Yggio, der den eingehenden Wert enthält.
Receiver – der entsprechende Schreib-Tag in SIA, dessen variable_name auf die tatsächliche SPS-Variable abbildet.
Value: Direct parsing – der Wert wird unverändert durchgereicht, ohne jegliche Vorlagenumwandlung.

Sender (Yggio-Item)	Receiver (SIA-Schreib-Tag / SPS-Variable)
`10001, Example Street 23 5601`	`F10001_EXAMPLE_STREET_23_5601.GT51_curveConf.rAdj`
`10002 Example Hall rad`	`F10002_EXAMPLE_HALL_5602.GT51_curveConf.rAdj`

Jede Zeile ist ein separater Mapping-Eintrag. Sender und Receiver sind eins-zu-eins verknüpft – ein Yggio-Item schreibt in einen SIA-Schreib-Tag pro Liegenschaft/Gebäudesystem.

Jeder Schreib-Tag muss in SIA mit readwrite=0 (Read & Write – siehe 4.7) und dem korrekten variable_name, der zur SPS-Variable passt, vorkonfiguriert sein, bevor das Subscribe-Mapping erstellt werden kann.

Jedes Subscribe-Item benötigt einen Post-Processing-String, damit SIA weiß, welches Feld aus der eingehenden JSON-Nutzlast von Yggio extrahiert werden soll. Ohne diesen empfängt SIA das vollständige JSON-Objekt, kann aber den tatsächlichen Wert nicht herauslesen.

Das Format lautet:

%VALUE.iotnode.<description>%

Wobei <description> dem description-Feld des Tags entspricht – also dem internen NODA-Feldnamen (z. B. supplytemp_sec_offset).

Beispiel:

%VALUE.iotnode.supplytemp_sec_offset%

Dies muss auf jedem Item einer Subscribe-Instanz gesetzt werden.

Das Topic-Format für Subscribe-Items unterscheidet sich von Publish. Es wird von Yggio bereitgestellt und folgt diesem Muster:

yggio/output/v2/<recipient_id>/iotnode/<node_id>

Das vollständige Topic findet sich auf der Konfigurationsseite des Items in SIA, sobald der Yggio-Knoten existiert. Jedes Item hat sein eigenes eindeutiges Topic.

5.5 Store and Forward

Store and Forward ist eine SIA-Einstellung, die Daten lokal puffert, wenn die MQTT-Verbindung ausfällt, und den Puffer leert, sobald die Verbindung wiederhergestellt ist.

Aktiviert: Bei Ausfällen gehen keine Daten verloren, aber Wiederverbindungen können unter bestimmten Bedingungen instabil werden (siehe eingeschränkte Referenz).
Deaktiviert: Während eines Ausfalls verpasste Daten gehen verloren, aber die Wiederverbindungen sind sauber.

Für Sensordaten, die an NODA oder ähnliche Systeme gesendet werden, ist es im Allgemeinen sicher, Store and Forward zu deaktivieren – der aktuelle Wert ist wichtiger, als historische Lücken zu füllen.

Deaktivieren Sie Store and Forward nicht bei Mappings, bei denen Datenkontinuität kritisch ist und das empfangende System keine Lücken tolerieren kann.

6. Einrichtung für NODA Energy View

6.1 Hintergrund

NODA Energy View empfängt Daten über Yggio. In Yggio wird jeder Messpunkt oder jedes Gerät als Knoten (Thing) dargestellt, und der Knotentyp bestimmt, welche Felder, Metadaten und Einrichtungsschritte erforderlich sind.

Die Namen und Werte in den folgenden Beispielen (z. B. 10002, Example Street...) sind nur ein Beispiel dafür, wie es aussehen kann – keine erforderliche Namenskonvention. Die Benennung in Ihrem Projekt wird abweichen.

6.2 Drei Knotentypen

Es gibt drei Knotentypen, die in der NODA-Integration verwendet werden:

Typ	Richtung	Beschreibung
Building	-	Übergeordneter Knoten, der ein Gebäude/einen Kreis darstellt. Enthält die `thingUUID`, auf die alle anderen Knoten verweisen
Kontroll-/Leseknoten	SIA → NODA	Mess- oder Statusdaten, die von SIA an NODA gesendet werden (Temperaturen, Durchflüsse, Statussignale)
Raumsensor	SIA → NODA	Innensensor (Temperatur), der über `newChildren` mit einem Gebäude verknüpft ist

Die Rückschreibung (Sollwerte von NODA → SIA) erfolgt über einen Kanal am Gebäudeknoten – nicht über einen eigenen Knotentyp.

6.3 Gebäudeknoten (Building)

Ein Gebäudeknoten ist der übergeordnete Knoten, auf den alle anderen Knoten eines bestimmten Kreises über thingUUID verweisen.

Manuell zu setzende Felder:

Feld	Wert
`nodaDeviceType`	`building`
`device`	`Kelp-Basic`
`contextMap.connectNODAEnergyView`	`<connectNODAEnergyView_id>` (Example1-Projekt)
`dataif`	Kreisbezeichner, z. B. `10002_AS02`

Ziehen Sie die jeweilige Tag-Liste für die hier zu verwendende Benennung heran.

Nachdem diese Felder gepatcht wurden, generiert NODA innerhalb von ~10 Minuten automatisch eine thingUUID für das Gebäude. Diese UUID wird dann beim Verknüpfen von Kontrollknoten und Raumsensoren verwendet.

Beispielergebnis:

{
  "name": "10002, Example Street 1 F-5601 del2",
  "nodaDeviceType": "building",
  "device": "Kelp-Basic",
  "dataif": "10002_AS02",
  "contextMap": { "connectNODAEnergyView": "<connectNODAEnergyView_id>" },
  "thingUUID": "<building_thingUUID>"
}

6.4 Kontroll-/Leseknoten

Diese Knoten übertragen Messdaten von SIA an NODA (z. B. Außentemperatur, Vorlauftemperatur, Ventilstellung). Sie werden automatisch in Yggio erstellt, sobald SIA mit der Veröffentlichung beginnt, vorausgesetzt der Tag hat ein nicht leeres description-Feld.

Anforderungen an SIA-Tags:

description muss dem internen NODA-Feldnamen entsprechen (z. B. outdoortemp) – dies erscheint als Feldname am Knoten in Yggio und NODA
readwrite=1 (Read only – siehe 4.7)

Sobald der Knoten in Yggio erscheint, aktualisieren Sie ihn mit der thingUUID und contextMap des Gebäudes über PUT /api/iotnodes/<node_id>:

{
  "contextMap": { "connectNODAEnergyView": "<connectNODAEnergyView_id>" },
  "thingUUID": "<building_thingUUID>"
}

Beispiel-Knotenergebnis:

{
  "name": "F10002_EXAMPLE_VS1_GT41_UTE_PV",
  "contextMap": { "connectNODAEnergyView": "<connectNODAEnergyView_id>" },
  "thingUUID": "<building_thingUUID>"
}

6.5 Write-back (Sollwerte von NODA zu SIA)

NODA schreibt Sollwerte (z. B. Offset der Vorlauftemperatur) über den Kanal-Mechanismus am Gebäudeknoten in Yggio zurück an das Gebäude. Dies ist kein separater Knoten – der Wert landet auf dem Gebäudeknoten selbst, und SIA liest ihn über ein Subscribe-Mapping.

⚠️ Schreib-/Sollwertknoten (z. B. supplytemp_sec_offset) dürfen niemals direkt contextMap oder thingUUID gesetzt bekommen. Der Wert wird über den Kanal des Gebäudeknotens geliefert; das Patchen des Schreibknotens selbst zerstört den Mechanismus.

Schritt 1 – Den Tag in SIA konfigurieren

readwrite: Read & Write (CSV-Wert 0 – siehe 4.7)
description: Muss exakt dem NODA-Feldnamen entsprechen (z. B. supplytemp_sec_offset)

Für einen Modbus-Schreib-Tag wie supplytemp_sec_offset ist kein Post-Processing erforderlich – der Wert wird direkt durchgereicht.

Schritt 2 – Einen Kanal am Gebäudeknoten in Yggio einrichten

Gehen Sie am Gebäudeknoten in Yggio zu Channels und fügen Sie einen MQTT-Kanal hinzu. Das resultierende Topic folgt diesem Muster:

yggio/output/v2/<recipient_id>/iotnode/<building_node_id>

Der Kanal benötigt zur Authentifizierung ein Basic Credential Set (eine ID plus Benutzername/Passwort). Siehe die Yggio-Generic-MQTT-Connector-Dokumentation, wie Sie eines über die Swagger-API erstellen.

Dieses Topic wird dann als MQTT-Topic auf dem entsprechenden Subscribe-Item in SIA verwendet.

Kopieren Sie die Einrichtung von einem bestehenden Subscribe-Item. Das entscheidende Feld ist der Post-Processing-String, der auf jedem Item gesetzt werden muss:

%VALUE.iotnode.supplytemp_sec_offset%

Ersetzen Sie supplytemp_sec_offset durch das description-Feld des jeweiligen Tags.

Für jeden Sollwert-Tag werden sowohl ein Publish-Mapping (aktueller Wert → Yggio) als auch ein Subscribe-Mapping (eingehendes Kommando → SPS) benötigt. Siehe Abschnitt 5.4.

6.6 Raumsensoren

Raumsensoren (Innentemperatursensoren über Webport/Elvaco) erfordern, dass alle vier Felder manuell gesetzt werden, bevor NODA eine thingUUID generiert.

Manuell zu setzende Felder:

Feld	Wert
`nodaDeviceType`	`sensor/indoor`
`device`	`Generic Indoor Sensor`
`contextMap.connectNODAEnergyView`	`<connectNODAEnergyView_id>` (Example1-Projekt)
`dataif`	Tag-Name (z. B. `F10003_EXAMPLE_SENSOR_GT35_PV1`)

Nach dem Patchen generiert NODA innerhalb von ~10 Minuten automatisch eine thingUUID. Sammeln Sie alle generierten thingUUID-Werte und fügen Sie sie über newChildren[] zum übergeordneten Gebäudeknoten hinzu.

Beispiel-Knotenergebnis:

{
  "name": "F10003_EXAMPLE_SENSOR_GT35_PV1",
  "nodaDeviceType": "sensor/indoor",
  "device": "Generic Indoor Sensor",
  "dataif": "F10003_EXAMPLE_SENSOR_GT35_PV1",
  "contextMap": { "connectNODAEnergyView": "<connectNODAEnergyView_id>" },
  "thingUUID": "<room_sensor_thingUUID>"
}

6.7 Raumsensoren mit einem Gebäude verknüpfen – `newChildren`

⚠️ Kritisch: newChildren ersetzt die gesamte Kinderliste – es hängt nicht an. Bestätigen Sie vor jedem Update immer die vollständige aktuelle Liste der Kind-thingUUIDs. Das Auslassen auch nur einer einzigen unterbricht stillschweigend die Sollwertsteuerung für das gesamte Gebäude, ohne dass zum Zeitpunkt des Auftretens ein Fehler angezeigt wird. Siehe die eingeschränkte Verfahrensreferenz (Kontakt zum technischen Support-Team) für die sichere Update-Sequenz.

6.8 Referenz der Schlüsselfelder

Feld	Bedeutung
`thingUUID`	Identifiziert, zu welchem Gebäude ein Knoten gehört. Immer außerhalb von `contextMap`
`contextMap.connectNODAEnergyView`	Identifiziert, welche Energy View in NODA. Pro Projekt konstant
`dataif`	Wird von NODA verwendet, um den Knoten intern zu identifizieren
`newChildren[]`	Registriert die thingUUIDs von Raumsensoren an einem Gebäudeknoten. Ersetzt alle – alle auf einmal angeben

connectNODAEnergyView ist pro NODA-Projekt konstant. Ein anderes Projekt (anderer Kunde oder andere NODA-Instanz) hat seine eigene ID.

6.9 Nodefelder setzen

Identitätsfelder von Gebäude-/Kontrollknoten (contextMap, thingUUID) werden über die Yggio-API gesetzt – keine Self-Service-Aktion in der UI. Kontaktieren Sie das technische Support-Team für Zugang zur eingeschränkten Verfahrensreferenz.

6.10 Datenlücken in NODA

NODA hat seinen eigenen internen Abfragezyklus und kann Messwerte verpassen, unabhängig davon, ob die Zustellung von SIA→Yggio korrekt funktioniert. Siehe Abschnitt 8.4 für das Vorgehen, wenn Sie Lücken bemerken.

7. Watchdog – Methoden und Fallstricke

Watchdogs sind optional und kundenspezifisch – nicht jede Integration benötigt einen, und Kunden, die einen möchten, wünschen ihn möglicherweise unterschiedlich implementiert. Das folgende Muster ist ein konkretes Beispiel aus einem Projekt, kein Standardbestandteil der SIA/Yggio/NODA-Einrichtung.

7.1 Warum Watchdog?

Bei Integrationen, bei denen ein externes System Steuersignale an eine DUC sendet, wird eine Möglichkeit benötigt, um zu erkennen, ob die Kommunikationskette unterbrochen ist. Ohne Watchdog könnte die DUC weiterhin auf ein altes Steuersignal reagieren, statt auf lokale Steuerung zurückzufallen.

7.2 Keep Alive als passiver Watchdog

MQTT Keep Alive (empfohlen: 30 s) fungiert als indirekter Watchdog für die MQTT-Verbindung. Wenn der Broker innerhalb der Keep-Alive-Periode nichts von SIA hört, gilt der Client als getrennt. Beachten Sie, dass dies nur die Verbindungsebene betrifft – es wirkt sich nicht direkt auf die Anwendungslogik wie das unten beschriebene Zählermuster aus.

7.3 Beispiel: Zählermuster (Example2-Projekt)

Diese konkrete Implementierung wird im Example2-Projekt verwendet und wird wahrscheinlich nicht unverändert anderswo wiederverwendet:

Energy Opticon → Yggio → SIA → DUC (empfängt Zähler)
                                 ↓
Energy Opticon ← Yggio ← SIA ← DUC (gibt Zähler zurück)

Energy Opticon sendet einen inkrementierten Watchdog-Zähler über Yggio und SIA an die DUC
Die DUC empfängt den Zähler und gibt ihn zurück über Modbus/SIA/Yggio an Energy Opticon
Energy Opticon markiert die Kommunikation als unterbrochen, wenn der Zähler innerhalb des projektspezifischen konfigurierten Timeouts nicht erhöht wurde (dieses Projekt verwendet ~15 Minuten – gewählt basierend auf der Risikotoleranz dieses Systems, kein Plattformstandard)
Die DUC fällt auf lokale Steuerung zurück, wenn sie innerhalb desselben Zeitfensters keinen aktualisierten Zähler erhält

8. Fehlerbehebung

8.1 Modbus

Symptom	Mögliche Ursache	Maßnahme
Alle Werte null oder konstant	Falsches Register (Offset)	Register anhand der Dokumentation prüfen, ±1 probieren
Verbindung abgelehnt	Falsche IP, Port oder Server ID	Netzwerkzugang und Einstellungen prüfen
Wert mit unplausibler Größenordnung	Falscher Datentyp (z. B. INT16 statt FLOAT)	Handbuch für Registertyp prüfen
Wert konsistent um einen Faktor daneben	Skalierungsfaktor nicht berücksichtigt	Post-Processing hinzufügen

8.2 Beckhoff / ADS

Symptom	Mögliche Ursache	Maßnahme
`Target port not found`	SIA nicht in TwinCATs statischen Routen	AMS Net ID von SIA auf der SPS hinzufügen
`Target port not found`	TwinCAT-Runtime läuft nicht	TwinCAT auf der SPS starten
Verbunden, aber keine Werte	Falscher AMS-Port (801 statt 851)	TC-Version prüfen (TC2=801, TC3=851)

8.3 MQTT / Yggio

Symptom	Mögliche Ursache	Maßnahme
Daten werden nicht veröffentlicht	Kein Connector in Yggio erfasst das Topic, oder ungültige MQTT-Zugangsdaten (siehe 3.1)	Prüfen, dass ein Connector für `siaconnect/<UUID>` existiert und dass seine UUID zum Topic passt
Tag erstellt keinen Knoten in Yggio	Feld `description` ist leer	Sicherstellen, dass der Tag ein nicht leeres `description` hat
Tag erstellt keinen Knoten in Yggio	Tag-Wert ist bei der ersten Veröffentlichung `0`	Der Knoten kann erscheinen, sobald ein Wert ungleich null empfangen wird; sonst description prüfen
Nachrichtenflut (Spam)	`trigger_behaviour=1` (All) mit kurzem Intervall	Auf `All changes` wechseln oder Intervall erhöhen
Nachrichtenflut (Beckhoff/ADS)	ADS-Push-Modus umgeht das Leseintervall	Kurzes `read_interval` auf einzelnen Tags setzen; Wechsel zu Trigger Behaviour `All changes` erwägen
Nachrichtenflut	Watchdog-Neustart alle ~7 Minuten	Siehe Abschnitt 7, Keep Alive anpassen
Pufferdump bei Wiederverbindung verursacht Flut	Store and Forward aktiviert	Store and Forward am Mapping deaktivieren

8.4 NODA Energy View

Symptom	Mögliche Ursache	Maßnahme
Lücken/fehlende Datenpunkte in NODA	NODA hat seinen eigenen internen Abfragezyklus und kann Zyklen verpassen, selbst wenn die Zustellung SIA→Yggio in Ordnung ist	Versuchen Sie, das Leseintervall in SIA zu senken (z. B. auf ~2 Minuten) für die betroffenen Tags

9. Einschränkungen

Einschränkung	Beschreibung	Workaround
`%` im Unit-Feld	Bringt den Vorlagen-Parser zum Absturz	`pct` verwenden oder leer lassen
Umbenennen eines Elements erstellt einen neuen Yggio-Knoten	Das Feld `name` ist der Knotenbezeichner – ein Umbenennen erzeugt einen neuen Knoten und lässt den alten in Yggio verwaist zurück	Benennung vor der Verbindung mit Yggio richtig festlegen; alte Knoten manuell bereinigen, wenn ein Umbenennen unvermeidlich ist
Mappings werden nicht exportiert	Der CSV-Export enthält nur Items, keine Mapping-Logik	Mappings manuell dokumentieren
Registeroffset variiert	Offset ±1 (oder anders) hängt vom Hersteller ab	Bei der Inbetriebnahme anhand tatsächlicher Daten überprüfen
Maximal 500 Tags pro Gateway	Feste Grenze des SIA-Connect-Edge-Gateways selbst	Anzahl der Gateways bei der Umfangsplanung gegen die Gesamtzahl der Tags planen – eine große Liegenschaft benötigt eventuell mehr als ein Gateway

10. Empfehlungen

Leseintervall: Ein Minimum von 10 Minuten wird empfohlen, um unnötigen Datenverkehr und Last zu vermeiden. Wenn Sie speziell in NODA Datenlücken sehen, siehe Abschnitt 8.4.
Trigger Behaviour: Wählen Sie basierend auf den Anforderungen des empfangenden Systems – es gibt keine universell richtige Antwort
Post-Processing: Nur hinzufügen, wenn tatsächlich eine Umrechnung erforderlich ist
Immer dokumentieren: IP, Port, Server ID, Register/Variablen, Datentyp, Skalierungsfaktor, Offset

Zuletzt aktualisiert: 2026-07-21
Dieses Dokument wird fortlaufend aktualisiert, sobald neue Konfigurationen bestätigt werden.

Inhaltsverzeichnis​

1. Werkzeuge und Zugang​

1.1 VPN​

1.2 SIA Connect Web-UI​

1.3 Yggio​

2. Hardwareinstallation in der IT-Umgebung des Kunden​

3. Allgemeine Konfiguration – SIA zu Yggio​

3.1 MQTT-Connector​

3.2 SIA/Edge-Gateway-UUID​

3.3 Keep Alive​

3.4 Execute on Startup​

4. Tag-Konfiguration in SIA​

4.1 Namenskonventionen​

4.2 Trigger Behaviour und Log Condition​

Minimum Trigger Interval​

4.3 Post-Processing​

4.4 Modbus TCP​

4.5 Beckhoff / TwinCAT ADS​

4.6 BACnet​

4.7 Lese-/Schreibrichtung​

5. Weiterleitungskonfiguration zu Yggio​

5.1 Mapping-Gruppen​

5.2 JSON-Vorlage zur Veröffentlichung (Publish)​

5.3 Bekannter Fehler – % im Unit-Feld​

5.4 Steuersignale und Sollwerte – Subscribe​

Beispiel – Sollwertlieferung pro Gebäude (Bastec GT51)​

Post-Processing bei Subscribe-Items​

MQTT-Topic-Format für Subscribe-Items​

5.5 Store and Forward​

6. Einrichtung für NODA Energy View​

6.1 Hintergrund​

6.2 Drei Knotentypen​

6.3 Gebäudeknoten (Building)​

6.4 Kontroll-/Leseknoten​

6.5 Write-back (Sollwerte von NODA zu SIA)​

Schritt 1 – Den Tag in SIA konfigurieren​

Schritt 2 – Einen Kanal am Gebäudeknoten in Yggio einrichten​

Schritt 3 – Das Subscribe-Item in SIA konfigurieren​

6.6 Raumsensoren​

6.7 Raumsensoren mit einem Gebäude verknüpfen – newChildren​

6.8 Referenz der Schlüsselfelder​

6.9 Nodefelder setzen​

6.10 Datenlücken in NODA​

7. Watchdog – Methoden und Fallstricke​

7.1 Warum Watchdog?​

7.2 Keep Alive als passiver Watchdog​

7.3 Beispiel: Zählermuster (Example2-Projekt)​

8. Fehlerbehebung​

8.1 Modbus​

8.2 Beckhoff / ADS​

8.3 MQTT / Yggio​

8.4 NODA Energy View​

9. Einschränkungen​

10. Empfehlungen​