Abbildung der Runtime Funktion
Diese Dokumentation beschreibt, wie Daten mithilfe der Analytics Data Exchange API aus dem Analytics-Format ausgelesen 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 Lesen von Daten aus dem Analytics Format werden zwei Lizenzen gebraucht:
- „TwinCAT 3 Analytics Runtime“ oder „TwinCAT 3 Analytics Runtime Base“
- „TwinCAT 3 Analytics Control Device Pack“ für jeden parallelen Lesevorgang.
Für die Verwendung der Runtime-Funktionalität muss sich TwinCAT im „RUN“ befinden.
Erzeugen und Konfigurieren einer Datenquelle:
Zum Auslesen von Daten aus dem Analytics Format wird im ersten Schritt ein Builder erzeugt und konfiguriert.
ISourceFactory factory = new SourceFactory();
IFileSourceBuilder fileBuilder = factory.FromFile(„C:\Data\Demo“);
IMqttLiveSourceBuilder mqttBuilder = factory.FromLiveStream(„127.0.0.1“, 1883);
IStorageProviderSourceBuilder FromStorageProvider(„127.0.0.1“, 1883);
Es stehen zurzeit drei verschiedene Builder zur Verfügung:
- IFileSourceBuilder: Daten aus einer Datei
- IMqttLiveSourceBuilder: Daten von einem Datenstrom eines Analytics Loggers
- IStorageProviderSourceBuilder: Aufgezeichnete Daten eines Analytics Storage Providers
Der Builder wird über eine Verkettung von Methodenaufrufen parametriert. Dabei stehen folgende Methoden zur Verfügung:
Symbole | Beschreibung |
|---|---|
WithSymbol(…) | Fügt ein zusätzliches Symbol zum Auslesen hinzu. Zur Verfügung stehende Symbole können über den TwinCAT Target Browser ausgelesen werden. |
WithSymbols(…) | Ermöglicht es mehrere Symbole gleichzeitig hinzuzufügen. |
WithSymbols(pattern, …) | Fügt mehrere Symbole anhand eines Regex-Ausdrucks hinzu. Zusätzlich können RegexOptions und ein SymbolFilter angegeben werden. SymbolFilter: Include Parent: Verwendet das Obersymbol, auch wenn Subsymbole zutreffen IncludeChilds: Verwendet die Untersymbole, auch wenn das Obersymbol zutrifft. IncludeChilds oder InlcudeParent müssen gesetzt werden |
WithSymbol<T>() | Fügt ein Symbol des generischen Datentyps hinzu. Information, welche Datentypen erlaubt sind, finden Sie im Abschnitt Generische Datentypen. |
|
|
Nur MQTT: |
|
FromTopic(…) | MQTT-Topic von dem die Daten gelesen werden sollen. |
WithStreamFormat(…) | Legt fest, welches Format die empfangen Daten haben. Wenn nichts angegeben ist wird das Format automatisch erkannt. Zur automatischen Erkennung muss der Datenstrom beim Start online sein. |
Storage Provider und Datei: |
|
From(…) | Startzeit ab der die Daten abgerufen werden sollen. |
To(…) | Endzeit bis zu der die Daten abgerufen werden sollen. |
Nur StorageProvider |
|
FromStorageProivder(…) | Gibt an, von welchem Storage Provider am verwendeten Broker die Daten abgerufen werden sollen. |
FromHistoricalStream(…) | Aus dem angegeben Topic wird die ProviderId und das MainTopic ausgelesen, welche andernfalls über die Methode FromStorageProvider übergeben werden müssen. |
FromLayout(…) | Layout des Historischen Datenstroms. |
FromOriginSystem(…) | SystemId von dem die Daten ursprünglich gesendet wurden. |
FromOriginStreamTopic (…) | Topic über das die Daten ursprünglich versendet wurden. |
FromStreamAlias(…) | Alias unter dem der Datenstrom aufgezeichnet und im TargetBrowser angezeigt wird. |
Die Methoden FromLayout, FromOriginSystem, FromOriginStreamTopic, FromStreamAlias, werden zur Identifikation des korrekten Datensatzes verwendet. Es nicht zwingend notwendig alle zu parametrieren, aber es wird empfohlen möglichst viele anzugeben, um eine Verwechslung von Datensätzen auszuschließen. Am einfachsten können diese Informationen aus dem Target Browser ausgelesen werden. Ziehen Sie dazu ein Symbol des Datensatzes in eine Texteditor (z. B. Notepad ++). In dem XML finden Sie die notwendigen Informationen im Bereich Target-Info.
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 Datenquelle wird über den Aufruf der Build-Methode abgeschlossen, welche die konfigurierte Datenquelle zurückgibt. Die Datenquelle stellt verschiedene Methoden zur Verfügung. Wird eine Datenquelle nicht mehr verwendet, ist es notwendig, die Dispose-Methode aufzurufen, um alle Ressourcen wieder freizugeben.
InitSymbols() | Initialisiert die ReadSymbols-Collection und löst vorhandene Regex-Ausdrücke auf. |
ReadSamples(…) | Fragt alle Daten synchron im aufrufenden Kontext ab. |
ReadAsync(…) | Fragt alle Daten asynchron ab. Für jedes Datum wird das ReadDelegate aufgerufen. |
Dispose() | Schließt alle offenen MQTT-Verbindungen oder Dateizugriffe und gibt alle Ressourcen frei. Die Datenquelle 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=)
Strukturierte Datentypen:
Die Analytics Data Exchange API erkennt die Datentypen von Symbolen automatisch, sollte kein generischer Datentype angegeben sein. Handelt es sich bei dem verwendeten Symbol um einen Strukturierten Datentyp, wird ein IStructuredValue zurückgegeben. Vom IStructuredValue können zum einen die Werte der Subsymbole abgefragt werden. Zum anderen kann dieser direkt in einen JSON-Text konvertiert werden. Die letzte Möglichkeit ist die Erzeugung eines IStructedValueReader, um das gesamte Symbol ähnlich eines XMLReaders durchzuparsen.
void Read(ISample sample)
{
foreach(var value in sample.Values)
{
if(value is IStructuredValue stValue)
{
//Values of structured DataTypes without generic DataType could be proccessed here
var subValue = value[„SubValues1“]; //SubValues1 is a known SubElement of the structured Value
var jsonString = stValue.ToJsonString(); //Convert the value to JSON
IStructuredValueReader reader stValue.GetReader(); //Use reader to parse the value iterative
}
}
}
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: