Abbildung der Logger Funktion

Diese Dokumentation beschreibt, wie Daten mithilfe der Analytics Data Exchange API im Analytics Format versendet oder gespeichert werden können.

Installation

Die folgenden zwei Komponenten müssen für die Verwendung der Analytics Data Exchange API installiert sein:

Microsoft Visual C++ Redistributable 2019 (x64/ x86) oder höher. Fehlt dieses Paket treten Fehler bei der Verarbeitung von Symbolen auf.
TwinCAT 3 ADS

NuGet-Pakete

Die Analytics Data Exchange API wird als NuGet-Paket ausgeliefert. Es stehen drei verschiedene Pakete zur Verfügung:

Beckhoff.TwinCAT.Analytics.DataExchange.Core (.Net-Core 3.1 oder .Net-5 und höher)
Beckhoff.TwinCAT.Analytics.DataExchange.Framework (.Net-Framework 4.5.2 oder höher)
Beckhoff.TwinCAT.Analytics.DataExchange (Multi-Target Projekte)

Lizenz

Für das Schreiben von Daten im TwinCAT-Analytics-Format wird eine Lizenz für den TwinCAT 3 Analytics Logger benötigt. Die Data Exchange API kann mit einer 7-Tage Lizenz getestet werden.

Erzeugen und Konfigurieren einer Datenablage:

Zum Versenden oder Speichern von Daten im Analytics Format wird im ersten Schritt ein Builder erzeugt, um die Datenablage zu konfigurieren:

ISinkFactory factory = new SinkFactory();

IFileSinkBuilder fileBuilder = factory.ToFile(„C:\Data\Demo“);

IMqttSinkBuilder mqttBuilder = factory.ToMessageBroker(„127.0.0.1“, 1883);

Es stehen zurzeit zwei verschiedene Builder zur Verfügung, um entweder in einer Datei zu schreiben oder MQTT-Daten zu verschicken. Die Builder werden über eine Verkettung von Methodenaufrufen konfiguriert:

mqttBuilder.WithSymbol(„Symbol1“, TypeCode.Double).WithCompressionWidth(8)

Folgende Methoden stehen zur Konfiguration der Symbole zur Verfügung:

Allgemeine Parameter	Beschreibung
WithCompression(…)	Legt die Komprimierungsmethode für die Datensenke fest.
WithCompressionWidth(..)	Die Vergrößerung der CompressionWidth führt zu einer gegebenenfalls geringeren Komprimierung aber schnelleren Verarbeitung. Werte unter 3 werden nicht empfohlen. Standard: 8
WithMaxSamplesPerChunk(…)	Maximale Anzahl an Daten in einer MQTT-Message oder in einer Datei. Standard: 32 bei MQTT, 500 bei Datei
WithMaxChunkSize(…)	Maximale Datengröße einer MQTT-Message oder einer Datei. Standard: Nicht begrenzt
WithCycleTime(…)	Zykluszeit der Daten: Standard 10ms
Symbole:
WithSymbol(…)	Fügt ein Symbol hinzu. Optional kann eine Arraylänge angegeben werden.
WithSymbols(Action)	Ermöglicht es mehrere Symbole gleichzeitig hinzuzufügen.
WithSymbol<T>	Fügt ein Symbol des generischen Datentyps hinzu. Information, welche Datentypen erlaubt sind, finden Sie im Abschnitt Generische Datentypen.
Nur MQTT:
ToTopic(…)	Topic, über welches die Daten kommuniziert werden.
Nur Datei:
WithIndexing(…)	Abstand zwischen zwei indexierten Datenpunkten bei Verwendung von Komprimierung. Indexierung erhöht die Performance beim Auslesen von Datenpunkten, aber vergrößert die Speichernutzung. 0 deaktiviert Indexierung und ist Standard. Zur Aktivierung sollte der Werte mindestens auf 100 gestellt werden.

Spezielle Parameter für die MQTT-Kommunikation werden über folgende Methoden konfiguriert:

WithTLS(…)	Konfiguriert die Zertifikate zur Verwendung von TLS
WithCredentials(…)	Benutzername und Passwort für den Zugriff auf den Message-Broker
WithTcpBufferSize(…)	Stellt die Größe des Puffers für die TCP-Verbindung zum Message Broker ein. Standard ist 32kB. Wenn sehr große Messages versendet werden, kann dieser Wert erhöht werden.
WithKeepAlivePeriod(…)	Einstellen der KeepAlive Zeit für die MQTT-Verbindung. (Standard 60s)
WithCommunicationTimeout(…)	Timeout für die TCP-Kommunikation zum Message Broker. (Standard 3s)
ToTopic(…) / FromTopic(…)	Topic über das die Daten kommuniziert werden.

Die Konfiguration einer Datensenke wird über den Aufruf der Build-Methode abgeschlossen, welche die konfigurierte Datensenke zurückgibt. Die Datensenke stellt folgende Methoden zur Verfügung. Wird die Datensenke nicht weiter verwendet, ist es notwendig, die Dispose-Methode aufzurufen, um alle Ressourcen wieder freizugeben.

InitWrite()	Initialisiert die MQTT-Verbindung oder öffnet die zu schreibende Datei. Wird auch automatisch beim ersten Schreiben von Werten aufgerufen.
Write(…)	Fügt einen neuen Wert zum Puffer hinzu.
Flush()	Sendet die im Puffer gespeicherten Daten. Wird automatisch von Write aufgerufen. Wenn MaxSamples oder MaxSize überschritten ist
CompleteWrite()	Sendet die im Puffer gespeicherten Daten und schließt alle offenen MQTT-Verbindungen oder Dateizugriffe.
Dispose()	Schließt alle offenen MQTT-Verbindungen oder Dateizugriffe, ohne den Puffer zu versenden und gibt alle Ressourcen frei. Die Senke kann danach nicht mehr verwendet werden

Generische Datentypen:

Die Analytics Data-Exchange-API unterstützt nur „unmanaged structs“ als generische Datentypen. Dies bedeutet folgende Einschränkungen

Innerhalb der Strukturen dürfen nur Strukturen oder Basis-Datentypen verwendet werden.
Arrays innerhalb der Strukturen sind nur mit „unsafe“ Code möglich. (Fixed-Array-Size)
Es können nur Arrays von Basis-Datentypen verwendet werden. Arrays von Strukturen sind nicht möglich.

Für die Strukturen kann außerdem nur ein sequentielles oder explizites Layout verwendet werden (siehe https://docs.microsoft.com/de-de/dotnet/api/system.runtime.interopservices.structlayoutattribute?view=net-6.0)

Beim Schreiben von Daten sollte ein explizites Layout verwendet werden.
Beim Schreiben von Daten darf das Layout kein Padding enthalten (Pack = 1)
Beim Lesen von Daten muss das Padding der Datenquelle entsprechen (https://infosys.beckhoff.com/index.php?content=../content/1031/tc3_plc_intro/3539428491.html&id=)

Fehlermeldungen

Treten beim Verwenden der Data Exchange API Fehler auf, werden diese per Ausnahme an den Benutzer weitergegeben. Folgende Ausnahmen werden verwendet:

Klassenname	Oberklasse	Beschreibung
DataExchangeException	Exception	Oberklasse für alle weiteren Ausnahmen innerhalb der API.
InvalidSymbolDefinitionException	DataExchangeException	Die konfigurierten Symbole sind nicht korrekt.
SymbolNotFoundException	InvalidSymbolDefinitionException	Ein konfiguriertes Symbol konnte im Datenstrom nicht gefunden werden.
InvalidSymbolNameException	InvalidSymbolDefinitionException	Der eingegebene Symbolname ist nicht gültig.
InvalidSymbolOffsetException	InvalidSymbolDefinitionException	Der eingegebene Symboloffset ist kleiner als 0.
InvalidSymbolByteSizeException	InvalidSymbolDefinitionException	Die eingegebene Größe in Bytes ist kleiner oder gleich 0.
InvalidSymbolTypeCodeException	InvalidSymbolDefinitionException	Der eingegebene TypeCode für ein Symbol ist nicht gültig.
InvalidSymbolRegexPatternException	InvalidSymbolDefinitionException	Das eingegebene Regex-Pattern für eine Symbol ist nicht gültig.
InvalidSymbolFilterException	InvalidSymbolDefinitionException	Der eingegebene SymbolFilter für eine Regex-Pattern ist nicht gültig.
DataExchangeLicenseException	DataExchangeException	Es konnte keine gültige Lizenz für die API gefunden werden oder TwinCAT ist nicht im Run-Mode.
DataExchangeTimeoutException	DataExchangeException	Eine Timeout-Zeit wurde überschritten.
QueueFullException	DataExchangeException	Eine Warteschlange für die Abarbeitung von Daten ist voll, da die Abarbeitung zu langsam war.
FileSourceNotFoundException	DataExchangeExeption	Im angegebenen Ordner konnte kein Analytics-File gefunden werden.
ValueExtractException	DataExchangeException	Beim Auslesen der Werte aus dem Datenstrom ist ein Fehler aufgetreten. Genauere Informationen gibt es in der inneren Ausnahme.
DataExchangeMQTTException	DataExchangeException	Ein Fehler ist bei der MQTT-Verbindung aufgetreten.
BrokerConnectException	DataExchangeMQTTException	Eine Verbindung zum Broker konnte nicht aufgebaut werden.
TopicNotFoundException	DataExchangeMQTTException	Das angegebene Topic wurde am Broker nicht gefunden.
InvalidMqttStreamFormat	DataExchangeMQTTException	Das angegebene Stream-Format ist nicht korrekt.

Beispiele:

Beispiele für die Verwendung der Analytics Data Exchange API finden Sie hier:

AnalyticsDataExchange_Samples.zip