Creating and handling EtherCAT devices

General information

This documentation should give you an overview avout how to create and handle EtherCAT devices and their corresponding topology via Automation Interface. For an in-depth understanding about how EtherCAT works and how it is generally integrated in TwinCAT SystemManager/XAE, please consult the EtherCAT System Documentation and the corresponding chapter about EtherCAT configuration in TwinCAT. EtherCAT boxes and terminals, which are connected to an EtherCAT Master, share a common way of creation, which is explained in a separate article about E-Bus sub types.

Creating an EtherCAT device

The first step in creating a TwinCAT EtherCAT configuration is to create an EtherCAT device, which may involve either to create an EtherCAT Master, Slave or Automation Protocol (e.g. to use network variables, as covered in a separate article). To create an EtherCAT Master/Slave, simply make use of the ITcSmTreeItem::CreateChild() method with the corresponding parameter for SubType (EtherCAT Master = 111, EtherCAT Slave = 130).

EtherCAT Master - Code Snippet (C#)

ITcSmTreeItem devices = systemManager.LookupTreeItem("TIID");
ethercatMaster = devices.CreateChild("EtherCAT Master", 111, null, null);

EtherCAT Master - Code Snippet (Powershell)

$devices = $systemManager.LookupTreeItem("TIID")
$ethercatMaster = $devices.CreateChild("EtherCAT Master", 111, $null, $null)

EtherCAT Slave - Code Snippet (C#)

ITcSmTreeItem devices = systemManager.LookupTreeItem("TIID");
ethercatSlave = devices.CreateChild("EtherCAT Slave", 130, null, null);
 

EtherCAT Slave - Code Snippet (Powershell)

$devices = $systemManager.LookupTreeItem("TIID")
$ethercatSlave = $devices.CreateChild("EtherCAT Slave", 130, $null, $null)
 

Creating EtherCAT boxes

The second step involves creating EtherCAT boxes, for example an EK1100 EtherCAT Coupler. As the article about E-Bus SubTypes explains, every child item (there a few exceptions - see below) of an EtherCAT Master uses a common SubType (9099) and will be identified via the Product Revision, which needs to be used in the vInfo parameter of the ITcSmTreeItem::CreateChild() method.

Code Snippet (C#)

ITcSmTreeItem ethercatMaster = systemManager.LookupTreeItem("TIID^EtherCAT Master");
ethercatMaster.CreateChild("EK1100", 9099, "", "EK1100-0000-0017");

Code Snippet (Powershell)

$ethercatMaster = $systemManager.LookupTreeItem("TIID^EtherCAT Master")
$ethercatMaster.CreateChild("EK1100", 9099, "", "EK1100-0000-0017")

Please note: In addition to the full product revision, you can also use a "wildcard". If you only specify "EK1100" as vInfo, Automation Interface will automatically detect and use the newest revision number. Example:

Code Snippet (C#):

ITcSmTreeItem ethercatMaster = systemManager.LookupTreeItem("TIID^EtherCAT Master");
ethercatMaster.CreateChild("EK1100", 9099, "", "EK1100"); 

Code Snippet (Powershell):

$ethercatMaster = $systemManager.LookupTreeItem("TIID^EtherCAT Master")
$ethercatMaster.CreateChild("EK1100", 9099, "", "EK1100") 

Creating EtherCAT terminals and insert into topology

The creation of EtherCAT terminals is based on the same concepts as EtherCAT boxes. Every terminal also shares a common SubType and will be identified via the Product Revision, which needs to be used in the vInfo parameter of the ITcSmTreeItem::CreateChild() method. The parameter bstrBefore lets you choose the position on which the terminal should be inserted into the configuration.

Code Snippet (C#):

ITcSmTreeItem ek1100 = systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT)^EK1100");
ek1100.CreateChild("Term 4 (EL2004)", 9099, "Term 3 (EL2004)", "EL2004-0000-0017");

Code Snippet (Powershell):

$ek1100 = $systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT)^EK1100")
$ek1100.CreateChild("Term 4 (EL2004)", 9099, "Term 3 (EL2004)", "EL2004-0000-0017")

Please note: Should you have trouble using the bstrBefore parameter, please try to insert the terminal on a "device-level", for example:

Code Snippet (C#):

ITcSmTreeItem device= systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT)");
device.CreateChild("Term 4 (EL2004)", 9099, "Term 3 (EL2004)", "EL2004-0000-0017");

Code Snippet (Powershell):

$device= $systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT)")
$device.CreateChild("Term 4 (EL2004)", 9099, "Term 3 (EL2004)", "EL2004-0000-0017")

The new terminal will then be inserted before "Term 3 (EL2004)" under the last inserted EtherCAT box.

Please note: In addition to the full product revision, you can also use a "wildcard". If you only specify "EL2004" as vInfo, Automation Interface will automatically detect and use the newest revision number. Example:

Code Snippet (C#):

ITcSmTreeItem ek1100 = systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT)^EK1100");
ek1100.CreateChild("Term 4 (EL2004)", 9099, "Term 3 (EL2004)", "EL2004"); 

Code Snippet (Powershell):

$ek1100 = $systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT)^EK1100")
$ek1100.CreateChild("Term 4 (EL2004)", 9099, "Term 3 (EL2004)", "EL2004")

Exceptions to the ItemSubType 9099

There are a few exceptions to the ItemSubType 9099, e.g. the RS232 terminals EP6002 (ItemSubType 9101) and EL600X (ItemSubType 9101). The following table gives an overview about all exceptions and their corresponding ItemSubType.

Changing the "Previous Port" of an EtherCAT terminal

The PreviousPort of an EtherCAT terminal determines the position of the terminal inside the EtherCAT topology.

In TwinCAT XAE, the DropDown box automatically includes all available previous ports. To configure this setting via Automation Interface, you can make use of the ITcSmTreeItem::ProduceXml() and ITcSmTreeItem::ConsumeXml() methods to modify the XML description of the corresponding EtherCAT terminal. This XML description therefore includes one or more XML nodes <PreviousPort>, where its attribute "Selected=1" determines, which previous port has been currently selected. Each previous port device is identified by its physical address.

Example (XML description)

<TreeItem>
  <EtherCAT>
    <Slave>
      <PreviousPort Selected="1">
        <Port>B</Port>
        <PhysAddr>1045</PhysAddr>
      </PreviousPort>
      <PreviousPort>
        <Port>B</Port>
        <PhysAddr>1023</PhysAddr>
      </PreviousPort>
    </Slave>
  <EtherCAT>
</TreeItem> 

If you want to change the Previous port you need to know the <PhysAddr> of the desired device, which can also be determined via its XML description.

When inserting childs to an EtherCAT configuration, the bstrBefore parameter of the ImportChild or CreateChild method can be used to specify the previous item when calling the ImportChild or CreateChild method on a slave. On an EtherCAT master this setting has to be specified via the XML description from above.

Adding EtherCAT slaves to a HotConnect group

EtherCAT HotConnect allows pre-configured sections to be removed from or added to the data traffic before the start or during operation of the system. For more information about EtherCAT HotConnect please read our EtherCAT System documentation.

In TwinCAT XAE, an EtherCAT slave can be added to a HotConnect group by clicking the corresponding option in the context menu of the device.

In TwinCAT Automation Interface, the same can be achieved by consuming the following XML structure on the EtherCAT slave:

Example (XML description):

<TreeItem>
 <EtherCAT>
 <Slave>
 <HotConnect>
    <GroupName>Term 1 (EK1101)</GroupName>
    <GroupMemberCnt>4</GroupMemberCnt>
    <IdentifyCmd>
     <Comment>HotConnect-Identität lesen</Comment>
     <Requires>cycle</Requires>
     <Cmd>1</Cmd>
     <Adp>0</Adp>
     <Ado>4096</Ado>
     <DataLength>2</DataLength>
     <Cnt>1</Cnt>
     <Retries>3</Retries>
     <Validate>
     <Data>0000</Data>
     <Timeout>5000</Timeout>
     </Validate>
    </IdentifyCmd>
 </HotConnect>
 </Slave>
 </EtherCAT>
</TreeItem>

Please note:

• The <GroupMemberCnt> tag needs to specify the exact amount of terminals plus the device itself

How to set EtherCAT Sync Units

EtherCAT SyncUnits can be set via ITcSmTreeItem::ConsumeXml() and by using the following XML description.

Example (XML description):

<TreeItem>
  <EtherCAT>
    <Slave>
      <SyncUnits>
        <SyncUnit>SyncUnit1</SyncUnit>
      </SyncUnits>
    </Slave>
  </EtherCAT>
</TreeItem>

Handle EtherCAT junction boxes (CU1128)

EtherCAT junction boxes can be handled similar to all other tree items. The following sample code shows how to add a CU1128 box and then add two EK1100 boxes below:

Code Snippet (C#)

ITcSmTreeItem cu1128 = ethercatMaster.CreateChild("CU1128", 9099, null, "CU1128");
ITcSmTreeItem cu1128_devA = cu1128.get_Child(1);
ITcSmTreeItem cu1128_devB = cu1128.get_Child(2);
ITcSmTreeItem ek1100_1 = cu1128_devA.CreateChild("EK1100-1", 9099, null, "EK1100");
ITcSmTreeItem ek1100_2 = cu1128_devB.CreateChild("EK1100-2", 9099, null, "EK1100");

Code Snippet (Powershell)

$cu1128 = $ethercatMaster.CreateChild("CU1128", 9099, $null, "CU1128")
$cu1128_devA = $cu1128.get_Child(1)
$cu1128_devB = $cu1128.get_Child(2)
$ek1100_1 = $cu1128_devA.CreateChild("EK1100-1", 9099, $null, "EK1100")
$ek1100_2 = $cu1128_devB.CreateChild("EK1100-2", 9099, $null, "EK1100")

Activate the EtherCAT configuration

To activate a created TwinCAT configuration via Automation Interface, the ITcSysManager::ActivateConfiguration() method may be used. However, the previous chapters only explained how to create an offline configuration, which means that every device created does not have real addresses, e.g. the EtherCAT Master has not been linked to a physical network interface card yet. Before activating the configuration you therefore need to configure each device with online addresses. To determine the real addresses, you can run a ScanDevices on the online system, determine the real addresses via the XML description (ITcSmTreeItem::ProduceXml()) and then import the address information via ITcSmTreeItem::ConsumeXml() into the created (offline) configuration. There are two HowTo samples which help you exactly with this kind of configuration:

• Scan Devices via Automation Interface