Mapping of the logger function
This documentation describes how to send or store data in Analytics format using the Analytics Data Exchange API.
Installation
The following two components must be installed to use the Analytics Data Exchange API:
- Microsoft Visual C++ Redistributable 2019 (x64/ x86) or higher. If this package is missing, errors occur when processing symbols.
- TwinCAT 3 ADS
NuGet packages
The Analytics Data Exchange API is delivered as a NuGet package. Three different packages are available:
- Beckhoff.TwinCAT.Analytics.DataExchange.Core (.Net-Core 3.1 or .Net-5 and higher)
- Beckhoff.TwinCAT.Analytics.DataExchange.Framework (.Net-Framework 4.5.2 or higher)
- Beckhoff.TwinCAT.Analytics.DataExchange (multi-target projects)
License
A license for the TwinCAT 3 Analytics Logger is required for writing data in TwinCAT Analytics format. The Data Exchange API can be tested with a 7-day license.
Create and configure a data storage:
To send or save data in Analytics format, the first step is to create a builder to configure the data storage:
ISinkFactory factory = new SinkFactory();
IFileSinkBuilder fileBuilder = factory.ToFile(„C:\Data\Demo“);
IMqttSinkBuilder mqttBuilder = factory.ToMessageBroker(„127.0.0.1“, 1883);
There are currently two different builders available to either write to a file or send MQTT data. The builders are configured via a concatenation of method calls:
mqttBuilder.WithSymbol(„Symbol1“, TypeCode.Double).WithCompressionWidth(8)
The following methods are available for configuring the symbols:
General parameters | Description |
|---|---|
WithCompression(…) | Sets the compression method for the data sink. |
WithCompressionWidth(..) | Increasing the CompressionWidth will result in less compression, but faster processing. Values below 3 are not recommended. Default: 8 |
WithMaxSamplesPerChunk(…) | Maximum number of data in an MQTT message or in a file. Default: 32 for MQTT, 500 for file |
WithMaxChunkSize(…) | Maximum data size of an MQTT message or file. Standard: not limited |
WithCycleTime(…) | Cycle time of the data: 10 ms by default |
Symbols: |
|
WithSymbol(…) | Adds a symbol. Optionally, an array length can be specified. |
WithSymbols(Action) | Allows you to add several symbols at the same time. |
WithSymbol<T> | Adds a symbol of the generic data type. The section Generic data types contains information about the allowed data types. |
MQTT only: |
|
ToTopic(…) | Topic over which the data is communicated. |
File only: |
|
WithIndexing(…) | Distance between two indexed data points when using compression. Indexing increases performance when reading data points, but increases memory usage. 0 disables indexing and is default. The value should be set to at least 100 for activation. |
Special parameters for MQTT communication are configured using the following methods:
WithTLS(…) | Configures the certificates to use TLS |
WithCredentials(...) | User name and password for access to the message broker |
WithTcpBufferSize(…) | Sets the size of the buffer for the TCP connection to the message broker. The default is 32 kB. If very large messages are sent, this value can be increased. |
WithKeepAlivePeriod(…) | Set the KeepAlive time for the MQTT connection. (the default is 60 s) |
WithCommunicationTimeout(…) | Timeout for TCP communication to the message broker. (the default is 3 s) |
ToTopic(…) / FromTopic(…) | Topic over which the data is communicated. |
The configuration of a data sink is completed by calling the build method, which returns the configured data sink. The data sink provides the following methods. If the data sink is not used any further, it is necessary to call the Dispose method to release all resources.
InitWrite() | Initializes the MQTT connection or opens the file to be written. Also called automatically the first time values are written. |
Write(…) | Adds a new value to the buffer. |
Flush() | Sends the data stored in the buffer. Automatically called by Write. When MaxSamples or MaxSize is exceeded |
CompleteWrite() | Sends the data stored in the buffer and closes any open MQTT connections or file accesses. |
Dispose() | Closes all open MQTT connections or file accesses without sending the buffer and releases all resources. The sink can no longer be used after that |
Generic data types:
The Analytics Data Exchange API supports only "unmanaged structs" as generic data types. This results in the following restrictions
- Only structures or basic data types may be used within the structures.
- Arrays within structures are only possible with "unsafe" code. (Fixed-Array-Size)
- Only arrays of basic data types can be used. Arrays of structures are not possible.
Furthermore, only a sequential or explicit layout can be used for the structures (see https://docs.microsoft.com/de-de/dotnet/api/system.runtime.interopservices.structlayoutattribute?view=net-6.0)
- An explicit layout should be used when writing data.
- The layout must not contain padding (Pack = 1) when writing data
- The padding must correspond to the data source when reading data (https://infosys.beckhoff.com/index.php?content=../content/1033/tc3_plc_intro/3539428491.html&id=)
Error messages
If errors occur while using the Data Exchange API, they are passed on to the user by exception. The following exceptions are used:
Class name | Superclass | Description |
|---|---|---|
DataExchangeException | Exception | Superclass for all further exceptions within the API. |
InvalidSymbolDefinitionException | DataExchangeException | The configured symbols are not correct. |
SymbolNotFoundException | InvalidSymbolDefinitionException | A configured symbol could not be found in the data stream. |
InvalidSymbolNameException | InvalidSymbolDefinitionException | The entered symbol name is not valid. |
InvalidSymbolOffsetException | InvalidSymbolDefinitionException | The entered symbol offset is smaller than 0. |
InvalidSymbolByteSizeException | InvalidSymbolDefinitionException | The entered size in bytes is less than or equal to 0. |
InvalidSymbolTypeCodeException | InvalidSymbolDefinitionException | The TypeCode entered for a symbol is not valid. |
InvalidSymbolRegexPatternException | InvalidSymbolDefinitionException | The entered regex pattern for a symbol is not valid. |
InvalidSymbolFilterException | InvalidSymbolDefinitionException | The entered SymbolFilter for a regex pattern is not valid. |
DataExchangeLicenseException | DataExchangeException | No valid license for the API could be found or TwinCAT is not in run mode. |
DataExchangeTimeoutException | DataExchangeException | A time-out period has been exceeded. |
QueueFullException | DataExchangeException | A queue for processing data is full because the processing was too slow. |
FileSourceNotFoundException | DataExchangeExeption | No Analytics file could be found in the specified folder. |
ValueExtractException | DataExchangeException | An error occurred while reading the values from the data stream. More detailed information is available in the inner exception. |
DataExchangeMQTTException | DataExchangeException | An error has occurred with the MQTT connection. |
BrokerConnectException | DataExchangeMQTTException | A connection to the broker could not be established. |
TopicNotFoundException | DataExchangeMQTTException | The specified topic was not found at the broker. |
InvalidMqttStreamFormat | DataExchangeMQTTException | The specified stream format is not correct. |
Examples:
Samples of how to use the Analytics Data Exchange API can be found here: