Basic Concepts
Variables and Datatypes
There are several types of variables that can be logged. Variables that are part of:
- PLC or NC process images
- PLC programs
- process images of devices e.g. an EtherCAT master and
- data areas of generic TcCom objects.
Moreover, they may be of any datatype defined in IEC 61131 or the C++ standard in case of generic TcCom-objects.
Structured datatypes may recursively contain other structured datatypes and may be logged as a whole or partially. For more information on this topic, refer to the Configuration section.
Modes of Operation
This documentation makes use of the terminology and concepts described in the MQTT-section. Please refer to that section for general information about the protocol.
A key concept of TwinCAT Analytics are streams, which form the basic unit of transaction between a data source and destination. One data logger can control several streams.
A stream may comprise four components:
- stream description
- stream Tx-description
- symbol info
- and stream data.
In MQTT-mode, Analytics participants coordinate by means of the first three components using an MQTT broker and a specific MQTT topic for each component. The topics are generally structured as illustrated in the following table, whereat <>-brackets indicate variables as opposed to the other parts that are fixed.
Component | Topic Structure | Format | Purpose |
|---|---|---|---|
Description | <MainTopic>/<StreamTopic>/Desc | JSON | Informs if there is a stream source online or offline. Includes timestamp of info. |
Tx-Description | <MainTopic>/<StreamTopic>/Bin/Tx/Desc | JSON | Informs about the transmission parameters when a stream source is active transmitting data. |
Symbol Info | <MainTopic>/<StreamTopic>/Bin/Tx/Symbols | Binary | Contains meta information about the variables i.e. excluding the actual value. |
Data | <MainTopic>/<StreamTopic>/Bin/Tx/Data | Binary | Contains the plain variable values. |
The main topic is the only subtopic that can freely be set by the user.
A stream can be started and stopped. The system manager configuration allows a stream to be started by default as soon as TwinCAT starts in run-mode. Additionally, streams can be started and stopped from PLC code.
When connected to a broker, the logger first sends the stream description followed by the Tx-description and symbol info as soon as the stream starts. This enables recipients to take all measures that are needed before data arrives. Finally, data is sent cyclically.
For the file-mode, the TwinCAT Boot directory on the target device is used as a base for a dedicated Analytics directory, which in turn contains one subdirectory per stream as soon as the respective TwinCAT project has been activated. Inside the stream’s directory, a dedicated .tas-file holds the symbol info whereas .tay-files, which are created cyclically, contain the stream data.
Relation of Logger and Streams
One data logger can control several streams. As will be described more detailed in the Configuration section a user can add one or more data loggers to the Analytics configuration. Streams then are added automatically, depending on what variables are available to be logged. To understand how streams are assigned to a logger it is useful to understand that every stream has specific characteristics. One characteristic, the cycle time, comes from the fact that every variable that is acted upon cyclically is subject to a cyclic task; therefore, cycle times that underlie different variables can vary. Since a stream has a fixed cycle time by definition and to decouple tasks with the same cycle time, one stream is created for every task that drives relevant variables. Additionally, it is purposeful to further divide streams depending on the stream source, meaning the origin PLC instance or TcCom object. This enables users to send variables of different sources to different MQTT topics and start/stop the transmission independently. Eventually it all comes down to the following scheme:
 | For every stream source and every task that drives variables of that source, a stream is created. |
When configuring the data logger, there are configuration parameters that all streams have in common and those that are stream specific. The logger specifies the destination, the compression method, MQTT credentials etc. whereas e.g. the data size and start/stop-functionality are stream specific.
In most cases it might not be necessary to send or write data every task cycle, so the data of a stream recorded in a cycle, a so-called sample, can be buffered before sending it to the broker or writing it to file. The number of samples in a buffer and thus the cycle time of a buffer being sent/written can be configured. Moreover, the number of buffers in a file and thus the file size can be configured.