2. Getting Started

2.1. EC-Simulator Architecture

The EC-Simulator library is implemented in C++ and can be easily ported to any embedded OS platforms using an appropriate C++ compiler. The API interfaces are C language interfaces, thus the stack can be used in ANSI-C as well as in C++ environments.

There are two different architecture editions as described below. The architectures contain the following:

EC-Simulator stack Core: In the core module cyclic (process data update) and acyclic (mailbox) EtherCAT commands are sent and received. Among others there exist some state machines to handle for example the mailbox protocols.
Configuration Layer: The EC-Simulator stack is configured using a XML file whose format is fixed in the EtherCAT specification ETG.2100 (ENI) with extended information (EXI). The EC-Simulator contains an OS independent XML parser.
Ethernet Link Layer: This layer exchanges Ethernet frames between the master and the simulator. If hard real-time requirements exist, this layer has to be optimized for the network adapter card in use.
OS Layer: All OS dependent system calls are encapsulated in a small OS layer. Most functions are that easy that they can be implemented using simple C macros.

2.2. Extended EtherCAT Network Configuration (EXI)

The EC-Simulator stack has to know about the EtherCAT bus topology and the cyclic/acyclic frames to exchange with the slaves. This configuration is determined in a configuration file which has to be available in the EtherCAT Network Information Format (ENI). This format is completely independent from EtherCAT slave vendors, from master stack vendors and from EtherCAT configuration tools. Thus inter-operability between those vendors is guaranteed.

Because the ENI file does not include information about the slave hardware, the EXI (EtherCAT Extended Information) file includes EEPROM content and Slave Object Dictionary from ESI and ESC register values from real network is typically needed. The EXI file can be exported using EC-Engineer.

2.3. HiL Simulation Software architecture

The EC-Simulator software is ready-to-run on various operating systems, e. g. Linux and Windows, and makes use of the acontis Real-time Ethernet drivers, the so called link layers.

The EC-Simulator offers a “C” language API for integration into a Software PLC (LogicLab, logi.cals) or into professional simulation software like ISG Virtuos, etc.

2.4. SiL Simulation Software architecture

The SiL Simulation Software architecture does not need a physical network interface for slave simulation. The EC-Simulator is loaded as Link-Layer instead to simulate the EtherCAT Network on a System controller running the EC-Master.

2.5. Mixed mode of real slaves and simulated slaves

In order to implement restbus simulation it is possible to mix real slaves and simulated slaves like this:

All real slaves must be configured accordingly:

See also /EtherCATConfig/ExtendedConfig/Slaves/Slave/Simulated in the EXI file:

The EC-Simulator will automatically assign the network adapters to the corresponding ports in order of configuration.

2.6. Operating system configuration

The main task is to setup the operating system to support the appropriate network adapter for EtherCAT usage and for some systems real-time configuration may be needed.

The operating system-specific settings and configurations are described in Platform and Operating Systems (OS).

2.7. Running EcSimulatorHilDemo

The EcSimulatorHilDemo is an EC-Simulator example application that handles the following tasks:

Showing basic EtherCAT communication
Stack initialization
Process Data operations for e.g. Beckhoff EL2004, EL1004 and EL4132
Periodic diagnosis task
Periodic Job Task
Logging to EcSimulator0.log, error0.log

The EcSimulatorHilDemo is available “out of the box” for different operating systems. The operating system must be prepared for running EtherCAT® applications,

See also

Operating system configuration

2.7.1. Setting up and running EcSimulatorHilDemo

2.7.1.1. Linux (EcSimulatorHilDemo)

Operating system configuration: See the section Operating system configuration for how to prepare the operating system
Starting EcSimulatorHilDemo

cd /opt/EC-Simulator/Bin/Linux/x64
LD_LIBRARY_PATH=. ./EcSimulatorHilDemo -f exi.xml -i8254x 2 1 -perf

2.7.1.2. Microsoft Windows (EcSimulatorHilDemo)

Windows configuration: See the section Operating system configuration for how to prepare the operating system
Determine the network interface: Using the command line option the network interface card used by the example application can be determined. For example the option -ndis 192.168.157.2 0 will be using the network adapter card with the IP address 192.168.157.2 .
Simulating EtherCAT modules: The simulator has to be connected with the target system using an Ethernet switch or a patch cable. Local IT infrastructure should not be mixed with EtherCAT modules at the same switch as the master will send many broadcast packets! EtherCAT® requires a 100Mbit/s connection. Gigabit-Ethernet connections between simulator and master can be typically used, too.
Copy all of the example application files into one directory: The application EcSimulatorHilDemo.exe together with the stack DLL EcSimulator.dll, the link-layer DLL emllPcap.dll and the EXI file have to be copied into one directory.
Run the example application: EcSimulatorHilDemo.exe has to be executed. The file name of the EXI file has to be given as a command line parameter as well as the appropriate Link Layer settings.

EcSimulatorHilDemo.exe -ndis 192.168.157.2 0 -f exi.xml -t 0 -v 3

2.7.2. Command line parameters

EcSimulatorHilDemo <LinkLayer> [-f ENI-FileName] [-t cycle time] [-b time] [-a affinity] [-v level] [-perf [level]] [-log prefix [msg cnt]] [-lic key] [-oem key] [-flash address] [-sp [port]] [-auxclk period] [-rec [prefix [frame cnt]]]

The parameters are as follows:

-f <configFileName>: Path to ENI file

-t <time>

Running duration in msec. When the time expires the demo application exits completely.

<time>: Time in msec, 0 = forever (default = 120000)

-b <cycle time>

Specifies the bus cycle time. Defaults to 1000 µs (1 ms).

<cycle time>: Bus cycle time in µsec

-a <affinity>

The CPU affinity specifies which CPU the demo application ought to use.

<affinity>: 0 = first CPU, 1 = second, …

-v <level>

The verbosity level specifies how much console output messages will be generated by the demo application. A high verbosity level leads to more messages.

<level>: Verbosity level: 0=off (default), 1..n=more messages

-perf [<level>]

Enable max. and average time measurement in µs for all EtherCAT jobs (e.g. ProcessAllRxFrames).

<level>: Depending on level the performance histogram can be activated as well.

-log <prefix> [<msg cnt>]

Use given file name prefix for log files.

<prefix>
<msg cnt>: Messages count for log buffer allocation

-lic <key>

Use License key.

<key>: 26 characters long license key.

-oem <key>

Use OEM key

<key>: 64 bit OEM key.

-flash <address>

Flash outputs

<address>: 0=all, >0 = slave station address

-sp [<port>]

If platform has support for IP Sockets, this command-line option enables the Remote API Server to be started. The Remote API Server is going to listen on TCP Port 6000 (or port parameter if given) and is available for connecting Remote API Clients.

<port>: RAS server port

-auxclk <period>

Use auxiliary clock

<period>: Clock period in µs (if supported by Operating System).

-rec [<prefix> [<frame cnt>]]

Packet capture file recording

<prefix>: File name prefix
<frame cnt>: Frame count for log buffer allocation

2.7.2.1. Link Layer

Using one of the following demo application Link Layer options, the EC-Simulator will dynamically load the network driver for the specified network adapter card and use the appropriate network driver to access the Ethernet adapter for EtherCAT©. ShowSyntaxLinkLayer() in Common/EcSelectLinkLayer.cpp is called automatically if the Demo application is started without parameters and lists the possibilities.

Note

Not all link layers are available on all operating systems or architectures. A detailed view in the form of a matrix can be found in the developer center.

-alteratse <instance> <mode>

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1= Polling mode

-antaios

Device instance fixed to 2

Mode fixed to 1 = Polling mode

-bcmgenet <instance> <mode>

Hardware: Broadcom BcmGenet

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1 = Polling mode

-ccat <instance> <mode>

Hardware: Beckhoff CCAT

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1= Polling mode

-cpsw <instance> <mode> <portpriority> <masterflag> <refboard>

Hardware: TI CPSW

<instance>

Device instance 1 = first, 2 = second, …

<mode>

0 = Interrupt mode, 1 = Polling mode

<portpriority>

Low priority (0) or high priority (1)

<masterflag>

Master (Initialize Switch), (s) Slave

<RefBoard>

If custom:

<CpswType>: am33XX | am437X | am57X | am387X
<PhyAddress>: 0 … 31
<PhyInterface>: rmii | gmii | rgmii | osdriver
<NotUseDmaBuffers>: 0 = FALSE | 1 = TRUE

-dw3504 <instance> <mode> <RefBoard>

Hardware: Synopsys DesignWare 3504-0 Universal 10/100/1000 Ethernet MAC (DW3504)

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1 = Polling mode
<RefBoard>: Reference Board: intel_atom | lces1 | rd55up06 | r12ccpu | rzn1 | socrates | stm32mp157a-dk1 | custom

If custom:

<DW3504Type>: intel_atom | cycloneV | lces1 | stm32mp157a-dk1
<PhyInterface>: fixed | mii | rmii | gmii | sgmii | rgmii | osdriver
<PhyAddress>: 0 … 31 (don’t use if osdriver)

-eg20t <instance> <mode>

Hardware: Intel EG20T Gigabit Ethernet Controller

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1 = Polling mode

-emac <instance> <mode> <refboard>

Hardware: Xilinx LogiCORE IP XPS EMAC

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1 = Polling mode
<RefBoard>: MC2002E | custom

If custom:

<RegisterBase>: Register base address as hex value
<RegisterLength>: Register length as hex value
<NotUseDmaBuffers>: 0 = FALSE | 1 = TRUE

-fsletsec <instance> <mode> <refboard>

Hardware: Freescale TSEC / eTSEC V1 / eTSEC V2 (VeTSEC)

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1 = Polling mode
<RefBoard>: p2020rdb | twrp1025 | istmpc8548 | xj_epu20c | twrls1021a | tqmls_ls102xa | custom

If custom:

<PhyAddress>: 0 … 31
<RxIrq>: Default depending on ETSEC type
<NotUseDmaBuffers>: 0 = FALSE | 1 = TRUE

-fslfec <instance> <mode> <refboard>

Hardware: Freescale FEC/ENET

<instance>

Device instance 1 = first, 2 = second, …

<mode>

0 = Interrupt mode | 1 = Polling mode

<RefBoard>

mars | sabrelite | sabresd | imx28evk | topaz | imxceetul2 | custom

If custom:

<FecType>

imx25 | imx28 | imx53 | imx6 | vf6 | imx7 | imx8 | imx8m | imxrt1064

<PhyInterface>

fixed | mii | rmii | rmii50Mhz | gmii | sgmii | rgmii | osdriver

<PhyAddress>

0 … 31, default 0 (don’t use if osdriver)

Optional:

<nopinmuxing>

no pin muxing

<nomacaddr>

don’t read MAC address

-gem <instance> <mode> <refboard>

Hardware: Xilinx Zynq-7000/Ultrascale (GEM)

<instance>: Device instance for GEM, 1 = GEM0,…
<mode>: 0 = Interrupt mode | 1 = Polling mode
<RefBoard>: zc702 | zedboard | microzed | zcu102 | zcu104 | KR260 | custom

If custom:

<PhyAddress>: 0 … 31
<PhyConnectionMode>: MIO (0) or EMIO (1)
<UseGmiiToRgmii>: Use Xilinx GmiiToRgmii converter TRUE (1) or FALSE (0)
<GmiiToRgmiiPort>: GmiiToRgmii converter PHY address 0 … 31
<GemType>: zynq7000 or ultrascale

Optional:

<PhyInterface>: osdriver
<ClkDivType_K26>: Clock divisor
<Pnopinmuxing>: Don’t use pin muxing

-i8254x <instance> <mode>

Hardware: Intel Pro/1000 network adapter card

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1 = Polling mode

-i8255x <instance> <mode>

Hardware: Intel Pro/100 network adapter card

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1 = Polling mode

-icss <instance> <mode> <masterflag> <refboard> [<PhyInterface> <PhyAddress>] [<NoPhyReset>] [tts TtsCycleTime TtsSendOffset]

Hardware: Texas Instruments Board with PRUSS

<instance>

ICSS Port (100 Mbit/s) 1 … 4

<mode>

0 = Interrupt mode | 1 = Polling mode

<MasterFlag>

Master (Initialize board, mdio, both phy) or (s) Slave

<RefBoard>

am572x-idk | am571x-idk | am3359-icev2 | am574x

Optional:

<PhyInterface>: mii | osdriver
<PhyAddress>: 0 … 31 (only for mii)

Optional:

<NoPhyReset>: NoPhyReset

Optional:

<TtsEnable>: tts
<TtsCycleTime>: TTS cycle time (usec)
<TtsSendOffset>: TTS cyclic frame send offset from cycle start (usec)

-icssg <instance> <mode> <masterflag> <refboard>

Hardware: Texas Instruments AARCH64 Board with Gigabit PRUSS

<instance>

ICSSG Port 1 … 6

<mode>

0 = Interrupt mode | 1 = Polling mode

<MasterFlag>

Master (Initialize board, mdio, both phy) or (s) Slave

<RefBoard>

am654x-idk

-l9218i <instance> <mode>

Hardware: SMSC LAN9218i/LAN9221

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1 = Polling mode

-lan743x <instance> <mode>

Hardware: Microchip LAN743x

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 1= Polling mode

-ndis <IpAddress> <mode>

Hardware: Hardware independent, only available for Windows.

<IpAddress>: IP address of network adapter card, e.g. 192.168.157.2 or 0.0.0.0 if name given
<mode>: 0 = Interrupt mode | 1 = Polling mode

Optional:

--name: Adapter name. Service name from HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\NetworkCards
<DisablePromiscuousMode>: Disable promiscuous mode
<DisableForceBroadcast>

-ndisuio <adapter>

Hardware: Hardware independent, only available for Windows CE.

<Adapter>: Device name (registry), ex. PCI\RTL81391

-r6040 <instance> <mode>

Hardware: RDC R6040

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 1 = Polling mode

-rin32m3 <instance> <mode>

Hardware: Renesas R-IN32M3-EC

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 1 = Polling mode

-rtl8139 <instance> <mode>

Hardware: Realtek RTL8139

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1 = Polling mode

-rtl8169 <instance> <mode>

Hardware: Realtek RTL8168 / RTL8169 / RTL8111

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1 = Polling mode

-rzt1 <instance>

Hardware: Renesas RZ/T1

<instance>: Device instance 1 = Port 0 | 2 = Port 1

-sheth <instance> <mode> <RefBoard>

Hardware: Renesas RZG1 or Armadillo-800 EVA

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 1 = Polling mode
<RefBoard>: rzg1e | a800eva

-snarf <adapterName>

Hardware: Hardware independent, only available for VxWorks

<adapterName>: Adapter name, e.g. fei0

-sockraw <device>

Hardware: Hardware independent, only available for Linux.

<device>: Network device, e.g. eth1

Optional:

<mode>: 0 = Interrupt mode | 1 = Polling mode
--nommaprx: Disable PACKET_MMAP for receive

-stm32eth <instance> <mode>

Hardware: STM32H7 Ethernet

<instance>: Device instance 1=first, 2=second, …
<mode>: 1 = Polling mode

-winpcap <ipAddress> <mode>

Hardware: Hardware independent, only available for Windows.

<ipAddress>: IP address of network adapter card, e.g. 192.168.157.2
<mode>: 0 = Interrupt mode | 1 = Polling mode

2.8. Using emllSimulator (SiL)

The EcSimulatorSilDemo example program as well as all EC-Master example programs like EcMasterDemo, EcMasterDemoDc, etc. support the EC-Simulator (SiL) link layer emllSimulator. In this case no physical link layer is passed to the EC-Master. Instead the emllSimulator (SiL) simulates the physical network. The command line syntax is for example:

EcSimulatorSilDemo -simulator 1 1 <exi-file> -f <eni-file> -t 0 -sp

The EC-Simulator Instance ID when calling EC-Simulator APIs is the Link Layer Instance ID given at command line:

EcSimulatorSilDemo -simulator <Instance-ID> 1 exi.xml -f exi.xml -t 0 -sp

Valid values for Instance ID of emllSimulator are 1 … 24 .

emllSimulator is dynamically loaded within ecatInitMaster() . In contrast to HiL, in case of SiL, ecatInitMaster() automatically calls esInitSimulator(), so the EC-Simulator SiL application may not call esInitSimulator() for the given Instance ID.

The EC-Simulator APIs can be used in the EcMasterDemo, too. The APIs are declared in SDK\INC\EcSimulator.h and EcSimulator.lib / libEcSimulator.so must be linked to the application to import the EC-Simulator APIs.

The EC-Simulator SiL Protected version with MAC based protection needs the corresponding link layer settings provided.

See also

Protected version

2.8.1. Simulator Link Layer parameters

The parameters to the Simulator Link Layer are setup-specific. The function CreateLinkParmsSimulator() in EcSelectLinkLayer.cpp demonstrates how to initialize the Link Layer instance.

struct EC_T_LINK_PARMS_SIMULATOR

Public Members

EC_T_LINK_PARMS linkParms: Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_SIMULATOR

struct _EC_T_OS_PARMS *pOsParms: OS layer parameters

EC_T_CNF_TYPE eCnfType: optional: create slaves from ENI/EXI, see esConfigureNetwork

EC_T_BYTE *pbyCnfData: optional: create slaves from ENI/EXI, see esConfigureNetwork

EC_T_DWORD dwCnfDataLen: optional: create slaves from ENI/EXI, see esConfigureNetwork

EC_T_SIMULATOR_DEVICE_CONNECTION_DESC oDeviceConnection: See EC_SIMULATOR_DEVICE_CONNECTION_TYPE_…

EC_T_BOOL bConnectHcGroups: Connect hot connect groups in topology (floating group heads to free ports)

EC_T_DWORD dwSimulatorAddress: Reserved

EC_T_DWORD dwBusCycleTimeUsec: Cycle time of simulator job task

EC_T_BOOL bDisableProcessDataImage: Don’t allocate Process Data Image at simulator (legacy support, CiA402 simulation)

EC_T_UINT64 qwOemKey: 64 bit OEM key (optional)

EC_T_BYTE abyMac[6]: MAC address

EC_T_DWORD dwRxBufferCnt: Frame buffer count for IST

EC_T_BOOL bJobsExecutedByApp: EC_FALSE: esExecJob explicitly called by application, EC_TRUE: implicitly by emllSimulator

EC_T_CHAR szLicenseKey[EC_SIMULATOR_KEY_SIZE]: License key (zero terminated string)

EC_T_LINK_PARMS *apLinkParms[EC_SIMULATOR_MAX_LINK_PARMS]: link parameters of network adapters passed to EC-Simulator Core, e.g. for validation of MAC address of license key

EC_T_WORD wRasServerPort: RAS server port

EC_T_CPUSET oRasCpuAffinityMask: RAS server threads CPU affinity mask

EC_T_DWORD dwRasPriority: RAS server threads priority

EC_T_DWORD dwRasStackSize: RAS server threads stack size

EC_T_PERF_MEAS_INTERNAL_PARMS PerfMeasInternalParms: Internal performance measurement parameters

emllSimulator accepts optional parameters, e.g.:

-simulator 1 1 <exi-file> [--mac <address>] [--lic <key>] [--link <link-parms>] [--sp] [--connect <type> <id> <address> <port>]

2.9. EC-Simulator Software Development Kit (SDK)

The EC-Simulator SDK is needed to write applications based on the EC-Simulator stack. The EC-Simulator stack is shipped as a library which is linked together with the application.

The following components are supplied together with an SDK:

….Bin: Executables containing the EC-Simulator stack
….Doc: Documentation
….Examples: Example application(s)
Libraries and header files to build C/C++-applications.
- ….SDKINC: header files to be included with the application
- ….SDKLIB: libraries to be linked with the application
….SourcesCommon: Shared C++-files

For all operating systems the same principal rules to generate the example applications can be used.

Include search path

The header files are located in the following two directories:

<InstallPath>Examples<ExampleName> (whith e.g. <ExampleName>=EcSimulatorHilDemo)
<InstallPath>ExamplesCommon<OS> (where <OS> is a placeholder for the operating system)
<InstallPath>ExamplesCommon
<InstallPath>SDKINC<OS> (where <OS> is a placeholder for the operating system)
<InstallPath>SDKINC
<InstallPath>SourcesCommon

Preprocessor macro

The demo applicatons are the same for all operating systems. The appropriate pre-processor macro has to be set for the operating system.

See also

OS Compiler settings

Libraries

The libraries located in <InstallPath>SDKLIB<OS><ARCH> have to be added (<OS> is a placeholder for the operating system used and <ARCH> for the architecture if different archtitectures are supported).

2.9.1. OS Compiler settings

2.9.1.1. Linux Compiler settings

The following settings are necessary to build the example application for Linux.

Possible ARCHs (see ATECAT_ARCHSTR in SDK/INC/Linux/EcOsPlatform.h):

armv4t-eabi, armv6-vfp-eabihf, x64 (aka amd64), x86 (aka i686), PPC (with “-te500v2”)

armv4t-eabi and armv6-vfp-eabihf are incompatible with each other. A potentially armv6-vfp-eabihf-compatible system returns success on “readelf -A /proc/self/exe | grep Tag_ABI_VFP_args”. If “readelf” isn’t available on the target, the matching ARM version can be figured out by trying to run EcSimulatorHilDemo.

Extra include paths:
<InstallPath>/Examples/EcSimulatorHilDemo <InstallPath>/SDK/INC/Linux <InstallPath>/SDK/INC <InstallPath>/Sources/Common
Extra source paths:
<InstallPath>/Examples/EcSimulatorHilDemo <InstallPath>/Sources/Common/EcTimer.cpp
Extra library paths to the main EtherCAT components (replace “x86” according to ARCH):
<InstallPath>/SDK/LIB/Linux/x86
Extra libraries (in this order)
AtesRasSrv EcSimulator pthread dl rt

2.9.1.2. Microsoft Windows

The following settings are necessary to build the example application for Windows:

Library path of the main EtherCAT components:
<InstallPath>/SDK/LIB/Windows/<Arch>
Include path:
<InstallPath>/SDK/INC/Windows <InstallPath>/SDK/INC <InstallPath>/Sources/Common

2.10. Link Layer configuration for EcSimulatorHilDemo

The different Link Layer modules are selected and parametered by a common structure (shared by all Link Layers) and a Link Layer specific structure, pointed to by an element within the common structure. This parameter set is given to the EC-Simulator stack with the call of esInitSimulator().

See also

esInitSimulator()