Creating and handling network variables

General information about network variables

Network variables can be used to exchange data between two TwinCAT devices via an IP-based network. One device declares variables as "Publisher" (sender) and the other device receives variable values as "Subscriber". For this reason, we also speak of Publisher/Subscriber variables. TwinCAT offers you the flexibility to configure network variables directly within a TwinCAT project so that you can map them to your PLC or I/O.

Network variables use the EtherCAT Automation Protocol device for communication over the local network. For this reason, you must add this device before you can configure a Publisher and/or Subscriber Box together with the corresponding variables.

Further information about network variables and how to configure them in TwinCAT can be found here.

Creating an EtherCAT Automation Protocol device

To create the EtherCAT Automation Protocol device, you can use the ITcSmTreeItem::CreateChild() method together with the corresponding SubType of this device (112).

Code snippet (C#):

ITcSmTreeItem devicesNode = systemManager.LookupTreeItem("TIID");
device = devicesNode.CreateChild("Device 1 (EtherCAT Automation Protocol)", 112, null, null); 

Code snippet (PowerShell):

$devicesNode = $systemManager.LookupTreeItem("TIID")
$device = $devicesNode.CreateChild("Device 1 (EtherCAT Automation Protocol)", 112, $null, $null) 

Creating a Publisher Box

The Publisher Box is the container for Publisher variables that determine, for example, which communication pattern type is to be used for the variables it contains (unicast, multicast, broadcast). To add a Publisher Box, simply use the ITcSmTreeItem::CreateChild() method again together with the corresponding SubType (9051).

Code snippet (C#):

ITcSmTreeItem eapDevice = systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT Automation Protocol)"); 
pubBox = eapDevice.CreateChild("Box 1 (Publisher)", 9051, null, null); 

Code snippet (PowerShell):

$eapDevice = $systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT Automation Protocol)")
$pubBox = $eapDevice.CreateChild("Box 1 (Publisher)", 9051, $null, $null) 

The small code snippet adds a Publisher Box to the previously created EtherCAT Automation Protocol device. To configure the communication pattern of this box, you must customize its settings using the ITcSmTreeItem::ConsumeXml() method. This is described in more detail in the EtherCAT Automation Protocol example of the Scripting Container or further down on this page.

Creating a Subscriber Box

The Subscriber Box is the container for Subscriber variables that determine, for example, which communication pattern type is to be used for the variables it contains (unicast, multicast, broadcast). To add a Publisher Box, simply use the ITcSmTreeItem::CreateChild() method again together with the corresponding SubType (9052).

Code snippet (C#):

ITcSmTreeItem eapDevice = systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT Automation Protocol)"); 
subBox = eapDevice.CreateChild("Box 1 (Subscriber)", 9052, null, null); 

Code snippet (PowerShell):

$eapDevice = $systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT Automation Protocol)")
$subBox = $eapDevice.CreateChild("Box 1 (Subscriber)", 9052, $null, $null) 

The small code snippet adds a Subscriber Box to the previously created EtherCAT Automation Protocol device. To configure the communication pattern of this box, you must customize its settings using the ITcSmTreeItem::ConsumeXml() method. This is described in more detail in the EtherCAT Automation Protocol example of the Scripting Container or further down on this page.

Creating Publisher variables

After you have successfully added a Publisher Box, you can now add Publisher variables to this box by using the ITcSmTreeItem::CreateChild() method together with the required parameters for SubType (0) and vInfo, which define the data type of the Publisher variables, e.g. "BOOL".

Code snippet (C#):

ITcSmTreeItem pubBox = systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT Automation Protocol)^Box 1 (Publisher)");
pubVar = pubBox.CreateChild("MAIN.bTestVar", 0, null, "BOOL"); 

Code snippet (PowerShell):

$pubBox = $systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT Automation Protocol)^Box 1 (Publisher)")
$pubVar = $pubBox.CreateChild("MAIN.bTestVar", 0, $null, "BOOL") 

See also the scripting container example "EtherCAT Automation Protocol" for more information.

Setting parameters for a Publisher/Subscriber Box

Two communication patterns must be configured on a Publisher and/or Subscriber Box: RT-Ethernet or UDP/IP . The following screenshot shows the corresponding TwinCAT XAE configuration tab.

You can find more detailed information about these options here.

To configure the box for RT-Ethernet , you must use the ITcSmTreeItem::ConsumeXml() method to import the following XML structure:

<TreeItem>
<BoxDef>
<FieldbusAddress>1</FieldbusAddress>
<AmsAddress>
<AmsPort>0</AmsPort>
<AmsPortTimeout>5</AmsPortTimeout>
</AmsAddress>
<NvPubDef>
<Udp Enabled="false"/>
     <MacAddress>00 00 00 00 00 00</MacAddress> 
<IoDiv>
    <Divider>1</Divider>
    <Modulo>0</Modulo>
</IoDiv>
<VLAN>
    <Enable>false</Enable>
    <Id>0</Id>
    <Prio>0</Prio>
</VLAN>
<ArpInterval>1000</ArpInterval>
<DisableSubscriberMonitoring>false</DisableSubscriberMonitoring>
<TargetChangeable>false</TargetChangeable>
</NvPubDef>
</BoxDef>
</TreeItem>

The following table shows how the nodes marked in bold must be adapted according to the desired communication pattern.

Import the following XML structure if you want to use UDP/IP :

<TreeItem>
<BoxDef>
<FieldbusAddress>1</FieldbusAddress>
<AmsAddress>
<AmsPort>0</AmsPort>
<AmsPortTimeout>5</AmsPortTimeout>
</AmsAddress>
<NvPubDef>
<Udp Enabled="true">
    <Address>0.0.0.0</Address>
    <Gateway>0.0.0.0</Gateway>
</Udp> 
<IoDiv>
    <Divider>1</Divider>
    <Modulo>0</Modulo>
</IoDiv>
<VLAN>
    <Enable>false</Enable>
    <Id>0</Id>
    <Prio>0</Prio>
</VLAN>
<ArpInterval>1000</ArpInterval>
<DisableSubscriberMonitoring>false</DisableSubscriberMonitoring>
<TargetChangeable>false</TargetChangeable>
</NvPubDef>
</BoxDef>
</TreeItem>

The following table shows how the nodes marked in bold must be adapted according to the desired communication pattern. The "Activated" attribute must be set to "true" on the <Udp> node.

Creating Subscriber variables

After you have successfully added a Publisher Box, you can now add Publisher variables to this box by using the ITcSmTreeItem::CreateChild() method together with the required parameters for SubType (0) and vInfo, which define the data type of the Publisher variables, e.g. "BOOL".

Code snippet (C#):

ITcSmTreeItem subBox = systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT Automation Protocol)^Box 1 (Subscriber)");
subVar = pubBox.CreateChild("MAIN.bTestVar", 0, null, "BOOL"); 

Code snippet (PowerShell):

$subBox = $systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT Automation Protocol)^Box 1 (Subscriber)")
$subVar = $pubBox.CreateChild("MAIN.bTestVar", 0, $null, "BOOL") 

See also the scripting container example "EtherCAT Automation Protocol" for more information.

Linking Publisher/Subscriber variables

To link Publisher/Subscriber variables with PLC variables, simply use the ITcSysManager::Linkvariables() method.

Code snippet (C#):

systemManager.LinkVariales("TIPC^PLC Project^PLC Project Instance^PlcTask Outputs^MAIN.bTestVar", "TIID^Device 1 (EtherCAT Automation Protocol)^Box 1 (Publisher)^MAIN.bTestVar^Outputs^VarData"); 

Code snippet (PowerShell):

$systemManager.LinkVariales("TIPC^PLC Project^PLC Project Instance^PlcTask Outputs^MAIN.bTestVar", "TIID^Device 1 (EtherCAT Automation Protocol)^Box 1 (Publisher)^MAIN.bTestVar^Outputs^VarData") 

See also the scripting container example "EtherCAT Automation Protocol" for more information.

Reading Publisher/Subscriber variable IDs

The following code snippet reads all variable IDs from a Publisher Box and saves them in the list array "ids". This can also be used for Subscriber variables.

Code snippet (C#):

List<uint> ids = new List<uint>();
ITcSmTreeItem pubBox = systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT Automation Protocol)^Box 1 (Publisher)");
foreach(ITcSmTreeItem var in pubBox)
{
if (var.ItemType == 35) // 35 = publisher variable, 36 = subscriber variable 
{
string varStr = var.ProduceXml();
XmlDocument varXml = new XmlDocument();
varXml.LoadXml(varStr);
XmlNode id = varXml.SelectSingleNode("//TreeItem/NvPubVarDef/NvId");
ids.Add(Convert.ToUInt32(id.InnerXml));
}
} 

Code snippet (PowerShell):

$ids = New-Object System.Collections.ArrayList
$pubBox = $systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT Automation Protocol)^Box 1 (Publisher)")
foreach($var in $pubBox)
{
  if($var.ItemType -eq 35)
  {
    $varXml = [Xml]$var.ProduceXml()
    $id = $varXml.TreeItem.NvPubVarDef.NvId
    $ids.Add($id)
  }
}