2. Getting Started

2.1. EC-Master Architecture

The EC-Master EtherCAT Master Stack 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 master can be used in ANSI-C as well as in C++ environments.

The Master Stack is divided into modules, see diagram and descriptions below:

EtherCAT Master 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 EtherCAT master is configured using a XML file whose format is fixed in the EtherCAT specification ETG.2100. EC-Master contains an OS independent XML parser.
Ethernet Link Layer: This layer exchanges Ethernet frames between the master and the slave devices. 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. EtherCAT Network Configuration (ENI)

The EtherCAT master 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 EtherCAT master vendors and from EtherCAT configuration tools. Thus interoperability between those vendors is guaranteed.

Additionally some static configuration parameters have to be defined like the identification of the network adapter card to use, the priority of the EtherCAT master timer task etc.

2.3. 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.4. Running EcMasterDemo

The EcMasterDemo is available “out of the box” for different operating systems. It is an EC-Master example application that handles the following tasks:

Showing basic EtherCAT communication
Master stack initialization into OPERATIONAL state
Process Data operations for e.g. Beckhoff EL2004, EL1004 and EL4132
Periodic diagnosis task
Periodic Job Task in polling mode
Logging

Start the EcMasterDemo from the command line to put the EtherCAT network into operation. At least a Link Layer must be specified.

EcMasterDemo -winpcap 192.168.157.2 1 -f eni.xml -t 0 -v 3

2.4.1. Command line parameters

EcMasterDemo <LinkLayer> [-f ENI-FileName] [-t time] [-b cycle time] [-a affinity] [-v level] [-perf [level]] [-log prefix [msg cnt]] [-lic key] [-oem key] [-maxbusslaves cnt] [-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.

-maxbusslaves <cnt>: Set max number of slaves

-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.4.1.1. Link Layer

Using one of the following demo application Link Layer options, the EC-Master 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.5. Compiling the EcMasterDemo

The following main rules can be used to generate the example applications for all operating systems.

<OS> is a placeholder for the operating system used.
<ARCH> for the architecture. If different architectures are supported.

2.5.1. EtherCAT Master Software Development Kit (SDK)

The EtherCAT master development kit is needed to write applications based on the master stack. The master stack is shipped as a library which is linked together with the application.

The following components are supplied together with an SDK:

<InstallPath>/Bin
<InstallPath>/Doc
<InstallPath>/SDK
<InstallPath>/SDK/INC
<InstallPath>/SDK/LIB
<InstallPath>/SDK/FILES
<InstallPath>/Sources/Common

/Bin

Executables containing the master stack

/Doc

Documentation

/Examples

One or more example applications using a predefined EtherCAT-configuration. It is easily adaptable to different configurations using an appropriate EtherCAT configuration XML file.

/SDK

EtherCAT Software Development Kit containing libraries and header files to build C/C++-applications.

/SDK/INC:

Header files to be included with the application

/SDK/LIB:

Libraries to be linked with the application

/SDK/FILES:

Additional files for platform integration (e.g. Windows CE registry files)

/Sources/Common:

Shared .cpp-files

2.5.2. Include search path

The header files are located in the following directories:

<InstallPath>/SDK/INC
<InstallPath>/SDK/INC/<OS>/<ARCH>
<InstallPath>/Sources/Common

2.5.3. Libraries

The libraries located in the following directories:

<InstallPath>/SDK/LIB/<OS>/<ARCH>