Creating and handling network variables

General information about network variables

Network variables may be used to send data between two TwinCAT devices via an IP-based network. One device declares variables as a "Publisher" (sender) and the other device receives variable values as a "Subscriber". Therefore we also speak in terms of Publisher/Subscriber variables. TwinCAT provides you with the flexibility to configure network variables directly in a TwinCAT project so that you may map them to your PLC or I/O.

Network variables use the EtherCAT Automation Protocol device to communicate via the local network. Therefore, you need to add this device before you can configure a Publisher and/or Subscriber box together with the corresponding variables.

More information about network variables and how they can be configured in TwinCAT may be found here.

Creating an EtherCAT Automation Protocol device

To create the EtherCAT Automation Protocol device, the method ITcSmTreeItem::CreateChild() may be used 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, which defines for example which type of communication pattern should be used (Unicast, Multicast, Broadcast) for the variables contained within. 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)

This small code snippet adds a Publisher box to the EtherCAT Automation Protocol device created earlier. To configure the communication pattern of this box, you need to customize its settings via the ITcSmTreeItem::ConsumeXml(), method. This is shown in more detail in the EtherCAT Automation Protocol sample of the Scripting Container or later on this page.

Creating a Subscriber box

The Subscriber box is the container for Subscriber variables, which defines for example which type of communication pattern should be used (Unicast, Multicast, Broadcast) for the variables contained within. 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)

This small code snippet adds a Subscriber box to the EtherCAT Automation Protocol device created earlier. To configure the communication pattern of this box, you need to customize its settings via the ITcSmTreeItem::ConsumeXml(), method. This is shown in more detail in the EtherCAT Automation Protocol sample of the Scripting Container or later on this page.

Creating Publisher variables

After you have successfully added a Publisher box, you can add Publisher variables to this box by making use of the ITcSmTreeItem::CreateChild() method together with the needed parameters for SubType (0) and vInfo, which specifies the data type of the Publisher variable, 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")

Please see the Scripting Container sample "EtherCAT Automation Protocol" for more information.

Setting parameters for a Publisher/Subscriber box

There are two communication patterns which need to be configured on a Publisher and/or Subscriber box: RT-Ethernet or UDP/IP . The following screenshot shows the corresponding configuration tab from TwinCAT XAE.

More detailed information about these options can be found here.

To configure the box for RT-Ethernet , you need to make use of 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 bold marked nodes need to 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 bold marked nodes need to be adapted according to the desired communication pattern. On the node <Udp>, the attribute "Enabled" needs to be set to "true".

Creating Subscriber variables

After you have successfully added a Publisher box, you can add Publisher variables to this box by making use of the ITcSmTreeItem::CreateChild() method together with the needed parameters for SubType (0) and vInfo, which specifies the data type of the Publisher variable, 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")

Please see the Scripting Container sample "EtherCAT Automation Protocol" for more information.

Linking Publisher/Subscriber variables

To link Publisher/Subscriber variables to 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")

Please see the Scripting Container sample "EtherCAT Automation Protocol" for more information.

Reading Publisher/Subscriber variable IDs

The following code snippet reads all variable IDs from a Publisher box and stores them in the List-Array "ids". This may 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)
  }
}