Best practice: access to TcCOM data

Introduction

The section Configuration of data access to data of a TcCOM object described how to set data access to a TcCOM in TC TcCom Interfaces in the configuration parameters of a Simulink^® model. In the following, advantages and disadvantages and also application scenarios as well as useful hints are given as to when which type of data access to a TcCOM may be useful.

Access via ADS

Properties

• On-demand data exchange
• Asynchronous communication
• Threadsafe
• Time of reading or writing not determined

Use Cases

• Read or write access from outside the TwinCAT runtime, e.g. from an HMI. Read and write model parameters or read internal signals.
• Access from inside the TwinCAT runtime to the TcCOM, if the writing software module (other TcCOM or PLC) is not called in the same task context. Thus, the data exchange is thread-safe. It can be used when a software module supplies parameter sets to different software modules in various contexts.

Notes

• If several parameters are to be changed or read simultaneously, an ADS sum command should be used. Otherwise it cannot be guaranteed that separate ADS read or write commands are all processed consistently in one task cycle.
• These properties also apply if the data access via the network is to be made via OPC UA and not via ADS.

Access via mapping

Properties

• Cyclic data exchange
• Threadsafe
• Time of data exchange determined

Use Cases

• Cyclic data exchange between different software modules, especially for data that changes every task cycle.

Notes

• Even values that have not been changed are copied in each task cycle. Therefore, it is advisable to keep the input and output mapping DataAreas small and limit them to the essentials. Large Simulink^® bus structures as input where only a few elements change cyclically should be avoided here.
• The time of the data exchange is determined and can be specified in Simulink^® under Configuration Parameters -> TC TcCom Additional settings -> Default execution sequence.
• Defining model parameters as Input Destination DataArea only makes sense if the parameters change cyclically (in which case it should first be checked whether the parameter cannot be better mapped as a model input) or the number of parameters is so small that the overhead of cyclic copying does not interfere.

Access via Data Pointer

Properties

• On-demand data exchange
• Not threadsafe
• Time of reading or writing determined (shared memory area)
• Local copy of the data in each instance
• Flexible linking of DataArea and Data Pointer in XAE

Use Cases

• Shared memory area of several TcCOM, for example for variables in the DataStore. TcCOM instances can share a common memory area with each other via Data Pointer data.

Data Pointer example An example can be found here: Shared memory between TcCOM instances.

Exported Global/Imported external

Properties

• On-demand data exchange
• Not threadsafe
• Time of reading or writing determined (shared memory area)
• No local copies of the data in each instance
• Only modules, bundled in the same driver, can access the global variable.

Use Cases

• Shared memory area for several TcCOM. Also suitable for large variables.

Example for Exported Global/Imported external An example can be found here: Shared memory between TcCOM instances.

Special case: Interaction via the TcCOM Wrapper FB

The TcCOM Wrapper FB (see Applying the TcCOM Wrapper FB) simplifies the interaction between PLC and TcCOM. This FB primarily enables, with little programming effort, the cyclic execution of the linked TcCOM object from the PLC code, including the exchange of input and output data. However, it also allows simple acyclic access to the object's parameters and, if required, flexible access to the DataAreas as well.

The wrapper provides the ITcADI interface (see ADI Interface) on the one hand and (optionally) properties on the function block (see FB properties) on the other. The TcCOM Wrapper FB should be called in the same context as the TcCOM.

Function block properties

• Access to module parameters only
• No access to DataAreas. Note: By default, model parameters are created both as DataArea and as module parameters.
• Simple access to module parameters by name
• Not threadsafe

ITcADI interface

• Efficient and flexible access to all DataAreas (also subareas of a DataArea)
• Access only via DataArea number and ByteOffset
• No type information (type cast is to be realized by the user)
• The pointer must be fetched and released every task cycle
• No access to module parameters
• Not threadsafe

Changes persist

Above, it was described how data can be changed in a TcCOM instance at TwinCAT runtime. If TwinCAT is restarted, these changes will be lost unless further recovery measures have been taken. The default behavior of a TcCOM is that when a TcCOM instance is started, the parameterization is performed according to its Startup Values.

In addition, remanent variables can be defined that retain their value beyond the usual program runtime. Remanent variables can be declared as RETAIN variables or even more strictly as PERSISTENT variables.

More information about remanent data (Persistent and Retain) in the TwinCAT PLC: Link

In the following three ways are described in which values can be restored after restarting TwinCAT.

1) Startup values

See Parameterization of a module instance for differentiation between Online, Prepared, Default and Startup Values.

TwinCAT 3 XAE necessary Startup values are changed in the TwinCAT configuration, i.e. in the engineering. Changes can be entered here. However, the change must be compiled and downloaded to the runtime system.

If online values are changed during runtime, you can read the current online values via ADS, for example. This can be done, for example, with the TE1410 TwinCAT Interface for MATLAB^®/Simulink^®. The read values can then be entered as new startup values in the TwinCAT configuration.

Use the Automation Interface example for this purpose:

TwinCAT.ModuleGenerator.Samples.Show('AutomationInterface')

In the example, a live script is used to show different functions. The section Read and write parameter online values via ADS describes how to read and write online values from a TcCOM. The section Read and change parameter startup value describes how to read and also write startup values.

The new startup values are entered in the TwinCAT configuration on the engineering system. To make the changes available on the runtime system, you must activate the configuration on the system. You can also realize this with the Automation Interface (sysManager.ActivateConfiguration). You can either restart the system directly via Automation Interface (sysManager.StartRestartTwinCAT), or you can let the system run without restarting. At the next start of TwinCAT, the startup values are set and the TcCOM starts up with the new startup values.

2) Retain Data

At TC TcCom Interfaces you can create the model parameters (and also other groups) as DataArea of type Retain Source DataArea. You can then create a retain handler in the TwinCAT configuration and connect it to the DataArea. For details see NOV-RAM and Retain Handler.

NOV RAM necessary To work with the Retain Handler, you need an IPC/CX with built-in NOV-RAM. The use of an EtherCAT Terminal with NOV-RAM (e.g. EL6080) is not supported.

3) Persistent Data

You can access persistent data in the TwinCAT 3 PLC without TwinCAT XAE and without NOV-RAM.

TwinCAT 3 PLC runtime required To use persistent data, you must declare variables as persistent in the PLC.

Persistent data can only be created in the PLC. Therefore, use the PLC to define the data you want to persist. Work with the TcCOM Wrapper FB, for example, to read data from the TcCOM and persist them via the persistent PLC variable. Create a state machine for starting the TcCOM object after a TwinCAT restart in order to write the persisted data back into the TcCOM object before it is called again in the code.