Building an EtherCAT topology

General information

This documentation should give you an overview about 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 Slave - Code Snippet (C#)

ITcSmTreeItem 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");

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:

ITcSmTreeItem 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");

Should you have trouble using the bstrBefore parameter, please try to insert the terminal on a "device-level". See the following example.

ITcSmTreeItem 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.

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. See the following example.

ITcSmTreeItem 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 Previous Port 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.

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>read hot connect identity</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>

The <GroupMemberCnt> tag needs to specify the exact number of terminals plus the device itself.

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