# EtherCAT Slave Device

This section describes an EtherCAT Slave Device

## Introduction

EtherCAT (Ethernet for Control Automation Technology) is an Ethernet-based industrial fieldbus protocol, invented by Beckhoff Automation. The protocol is specifically designed to apply an Ethernet structure for automation applications requiring short data update (cycle) times with low communication jitter and reduced hardware costs.

EtherCAT is a master/slave protocol, which means that there is one master device (implemented completely in the software) and multiple slave devices (implemented in the hardware) connected to a network. Every cycle, the master device sends one standard Ethernet frame which encapsulates multiple EtherCAT datagrams. EtherCAT datagrams address a specific part of the EtherCAT process image (up to 4GB in size), in which every slave device is assigned one or more addresses. This means that one Ethernet frame sent by a master device contains process data for every slave device in the network. Each slave device reads and writes data from the frame while the frame passes through the device, which is extremely useful for real-time communication. This also eliminates the need for higher level protocol stacks, such as TCP/IP and UDP/IP, because EtherCAT datagrams reach only as high as the second layer (data link) of the ISO/OSI reference model.

Besides this cyclic process data communication, additional acyclic communication profiles have been established, including CanOPEN over EtherCAT (CoE), Ethernet over EtherCAT (EoE) and File Access over EtherCAT (FoE). It is important to note that TyphoonHIL EtherCAT slave devices currently do not support any of the acyclic communication profiles.

The EtherCAT slave device can be configured by the master device using an ESI configuration file, which is essentialy an XML document containing all the information needed for properly setting up a slave device for communication. EtherCAT Slave Configuration decribes the ESI file template designed for use with TyphoonHIL EtherCAT slave devices.
Note: In order to avoid unexpected errors during configuration and usage of the TyphoonHIL EtherCAT slave device, it is strongly recommended to use the provided ESI file template and follow the instruction below to modify it as needed.

## EtherCAT Slave Device hardware

Every EtherCAT compatible TyphoonHIL device is equipped with the Microchip LAN9252 EtherCAT slave hardware. The Microchip LAN9252 comes with three fieldbus memory management units (FMMUs) and four SyncManagers. It contains 4kB of data process RAM (DPRAM), which is used for storing process data. Two Ethernet ports can be used for interfacing with the master device and another slave device (or two other slave devices).

## EtherCAT Slave Device Component

The EtherCAT Slave Device component, found under the Communication tab of the Schematic editor, implements EtherCAT slave functionality. It enables import of an ESI file to configure a TyphoonHIL EtherCAT slave. The component then parses the imported configuration file and displays the details of the process data.

Table 1. EtherCAT Slave Component
Component Component dialog window

Basic slave information (Vendor ID, Vendor name, Product code and Product name) is displayed directly below the Choose file widget. TxPDO information and RxPDO information tables list the Transmit Process Data Objects (PDOs) and Receive PDOs, respectively, as they are defined in the ESI file. By clicking on the PDO item in the TxPDO information or RxPDO information table, the PDO entry information table gets populated with the PDO's entries, as defined in the ESI file. The dialog window serves purely as a display, and as such does not allow any PDO modifications. All such modifications should be done in the ESI configuration file.

After clicking the OK button, defined RxPdo and TxPdo entries are translated into corresponding input and output terminals in the EtherCAT Slave component, with entries' names as the names of the terminals. It is strongly recommended to give unique names to the PDO entries, in order to differentiate the terminals of the EtherCAT Slave component.

## EtherCAT Slave Configuration

ESI configuration files are XML documents with a special element hierarchy, which describes the slave's physical properties, as well as the communication protocol details (including the size and the type of process data objects used). Since all TyphoonHIL EtherCAT compatible devices are equiped with a certain kind of EtherCAT slave hardware, and considering that the devices do not support all EtherCAT communication profiles, some restrictions are made on the content of ESI files that configure TyphoonHIL EtherCAT slave devices. The following list describes the ESI file elements and attributes which are mandatory, forbidden, fixed, or ignored. Elements and attributes not mentioned in this list are free to be used as-is. ESI file elements are annotated using <> brackets, while the element attributes are annotated with the preceding @ symbol.
<EtherCATInfo> - mandatory
<InfoReference> - forbidden
<Vendor> - mandatory
<Id> - mandatory
<Name> - mandatory
<Descriptions>
<Groups> - mandatory
<Group> - mandatory
<Devices> - mandatory
<Device> - mandatory
@Invisible - forbidden
@Physics - fixed - "YY"
<Type> - mandatory
<Name> - mandatory
<GroupType> - mandatory
<Profile> - ignored
<Fmmu> - fixed - Outputs
<Fmmu> - fixed - Inputs
<Sm> - fixed - MBoxOut
@ControlByte - mandatory
@DefaultSize - mandatory
@Enable - fixed - "1"
<Sm> - fixed - MBoxIn
@ControlByte - mandatory
@DefaultSize - mandatory
@Enable - fixed - "1"
<Sm> - fixed - Outputs
@ControlByte - mandatory
@Enable - fixed - "1"
@StartAddress - fixed - in range - 0x1000 - 0x1FFF
<Sm> - fixed - Inputs
@ControlByte - mandatory
@Enable - fixed - "1"
@StartAddress - fixed - in range - 0x1000 - 0x1FFF
<RxPdo> - mandatory (at least one)
@Fixed - fixed - "true"
@Mandatory - fixed - "true"
@Virtual - forbidden
@OverwrittenByModule - forbidden
@SRA_Parameter - forbidden
<Index> - fixed - in range - 0x1600 - 0x17FF
<Name> - mandatory
<Entry>
<Index> - fixed - in range - 0x6000 - 0x9FFF
<SubIndex> - fixed - in range - 0x01 - 0xFF
<Name> - mandatory
<BitLen> - mandatory
<DataType> - mandatory
<DependOnSlot> - forbidden
<DependOnSlotGroup> - forbidden
<TxPdo> - mandatory (at least one)
@Fixed - fixed - "true"
@Mandatory - fixed - "true"
@Virtual - forbidden
@OverwrittenByModule - forbidden
@SRA_Parameter - forbidden
<Index> - fixed - in range - 0x1A00 - 0x1BFF
<Name> - mandatory
<Entry>
<Index> - fixed - in range - 0x6000 - 0x9FFF
<SubIndex> - fixed - in range - 0x01 - 0xFF
<Name> - mandatory
<BitLen> - mandatory
<DataType> - mandatory
<DependOnSlot> - forbidden
<DependOnSlotGroup> - forbidden
<Mailbox> - forbidden
<Slots> - forbidden
<Eeprom> - mandatory
<ByteSize> - fixed - 2048
<ConfigData> - fixed - first two bytes - 80
<Modules> - forbidden       

SyncManagers

In order for the TyphoonHIL EtherCAT slave device to work properly, all four SyncManagers must be configured as described previously. MBoxOut and MBoxIn SyncManagers should have non-zero default sizes. None of the SyncManagers' memory regions should overlap. Keep in mind that the memory regions of Outputs and Inputs SyncManagers are triple the size of their assigned PDOs. This is needed in order to keep the memory regions synchronized. Lastly, the total size of the SyncManagers' memory regions should not exceed the total size of DPRAM (4kB).

Process Data Objects

RxPdo and TxPdo elements of the ESI file represent a single Process Data Object which takes part in data exchange between the master and slave devices. Data transmitted from the slave device to the master device is described by RxPdo elements, while TxPdo elements describe data transmitted from the master device to the slave device. Each PDO must be defined by a unique index and a (not necessarily unique) name. RxPdo indexes must belong to the 0x1600 - 0x17FF range, while TxPdo indexes must belog to the 0x1A00 - 0x1BFF range. Since TyphoonHIL EtherCAT slave devices do not support dynamic PDO configuration, PDO elements should have Fixed and Mandatory attributes set to "true". Sm attribute of the PDO element should be set to the index of the corresponding SyncManager (Outputs SyncManager corresponds to RxPdo elements, while Inputs SyncManager corresponds to TxPdo elements).

Each PDO element consists of zero or more Entry elements which describe a single variable partaking in the process data communication. Entries are uniquely defined by an index and a subindex. Data which they carry is described by its bitlength and data type. Data types described by the EtherCAT protocol are listed below. Note that the TyphoonHIL devices do not support data types wider than 32-bits, which means that all wider EtherCAT Base Data types will be truncated.
Table 2. EtherCAT Base Data Types
Name Description Bit Size Range
BOOL Boolean 1
BIT1 1 Bit String 1
BIT2 2 Bit String 2
BIT3 3 Bit String 3
BIT4 4 Bit String 4
BIT5 5 Bit String 5
BIT6 6 Bit String 6
BIT7 7 Bit String 7
BIT8 8 Bit String 8
BITARR8 8 Individual Bits 8
BITARR16 16 Individual Bits 16
BITARR32 32 Individual bits 32
SINT Short Integer 8 -128 to 127
INT Integer 16 -32.768 to 32.767
INT24 24-Bit Integer 24 -223 to 223 - 1
DINT Double Integer 32 -231 to 231 - 1
INT40 40-Bit Integer 40 -239 to 239 - 1
INT48 48-Bit Integer 48 -247 to 247 - 1
INT56 56-Bit Integer 56 -255 to 255 - 1
LINT Long Integer 64 -263 to 263 - 1
USINT Unsigned Short Integer 8 0 to 255
UINT Unsigned Integer 16 0 to 65.535
UINT24 Unsigned 24-Bit Integer 24 0 to 224 - 1
UDINT Unsigned Double Integer 32 0 to 232 - 1
UINT40 Unsigned 40-Bit Integer 40 0 to 240 - 1
UINT48 Unsigned 48-Bit Integer 48 0 to 248 - 1
UINT56 Unsigned 56-Bit Integer 56 0 to 256 - 1
ULINT Unsigned Long Integer 64 0 to 264 - 1
REAL Floating Point 32
LREAL Long Float 64

Due to software limitations, there should be at least one of each RxPdo and TxPdo elements of non-zero bit length in the ESI file in order for the TyphoonHIL EtherCAT slave device to work properly (even if the defined PDOs are not used).

EEPROM

<ConfigData> subelement of the <Eeprom> element of the ESI file allows the user to specify the EEPROM configuration data. Since the TyphoonHIL EtherCAT slave device uses SPI microcontroller interface, the first two bytes of the EEPROM configuration data should be set to 80.

Example ESI configuration file

The following example shows a process data configuration in which one 32-bit entry of DINT data type is sent from the slave device to the master device, and another entry of the same type is sent in the opposite direction. Adding or removing PDOs and their entries can be done freely, as long as the total size of the PDOs does not exceed the limitations of the DPRAM (described in the SyncManagers paragraph).

<?xml version="1.0"?>
<EtherCATInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="EtherCATInfo.xsd" Version="1.6">
<Vendor>
<Id>#xC7B</Id>
<Name>Typhoon HIL Inc</Name>
</Vendor>
<Descriptions>
<Groups>
<Group>
<Type>HIL100 Slaves</Type>
<Name LcId="1033">HIL100 Slaves</Name>
</Group>
</Groups>
<Devices>
<Device Physics="YY">
<Type ProductCode="#x00000100" RevisionNo="#x1">HIL100 EtherCAT Slave</Type>
<Name LcId="1033">HIL100 EtherCAT Slave</Name>
<GroupType>HIL100 Slaves</GroupType>
<Fmmu>Outputs</Fmmu>
<Fmmu>Inputs</Fmmu>
<RxPdo Fixed="true" Mandatory="true" Sm="2">
<Index>#x1600</Index>
<Name>TestRxVars</Name>
<Entry>
<Index>#x7000</Index>
<SubIndex>#x1</SubIndex>
<BitLen>32</BitLen>
<Name>TestRxVar</Name>
<DataType>DINT</DataType>
</Entry>
</RxPdo>
<TxPdo Fixed="true" Mandatory="true" Sm="3">
<Index>#x1A00</Index>
<Name>TestTxVars</Name>
<Entry>
<Index>#x6000</Index>
<SubIndex>#x1</SubIndex>
<BitLen>32</BitLen>
<Name>TestTxVar</Name>
<DataType>DINT</DataType>
</Entry>
</TxPdo>
<Eeprom>
<ByteSize>2048</ByteSize>
<ConfigData>8002000000000000</ConfigData>
<BootStrap>0010800080108000</BootStrap>
</Eeprom>
</Device>
</Devices>
</Descriptions>
</EtherCATInfo>


## Virtual HIL support

Virtual HIL currently does not support this protocol. When using a Virtual HIL environment (e.g. when running the model on a local computer), inputs to this component will be discarded and outputs from this component will be zeroed.