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.
Operation modes
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 a 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, where <> brackets indicate variables as opposed to the other parts that are fixed.
Component | Topic structure | Format | Purpose |
|---|---|---|---|
Description | <MainTopic>/<StreamTopic>/Descr | JSON | Provides information on whether a stream source is online or offline. Includes a timestamp for the information. |
Tx description | <MainTopic>/<StreamTopic>/Bin/Tx/Descr | JSON | Provides information about the transmission parameters when a stream source is actively 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. A stream can be started by default via the System Manager configuration as soon as TwinCAT starts in Run Mode. Additionally, streams can be started and stopped from PLC code.
Once connected to a broker, the Logger first sends the stream description. Then, as soon as the stream starts, it sends the Tx description and symbol info. This enables recipients to take all measures that are needed before data arrives. Finally, data is sent cyclically.
In 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. A specific .tas file in the stream directory contains the symbol information, while .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.