4. ENI Builder Input (EBI) file format

4.1. Data types

HexDecValue: According to ETG.2000, Ch.6.

String: ASCII string

Uint32: 32 bit unsigned integer in decimal notation

Bool: 0 or 1 or True or False

4.2. Tags

Tag name / Attribute

Description

Mandatory / Optional

Data types

Config

Top-level tag

M

Info

File metadata

M

EniFileName

Name of the output file (ENI)

M

String

FileFormatVersion

File version. If this version is <= to the version of the executable, the file is compatible to the executable and can be read in.

M

<Major>.<Minor>, both uint32, decimal

WriteVersionStringToEni

True, to write version string of the EniEngine to the ENI file.

O

Bool

Tag name / Attribute

Description

Mandatory / Optional

Data types

Master

Master settings

O

Master@Name

Name of master

O

String

Master/CycleTime

Cycle time in microseconds (used for DC)

O

Uint32

Master/Dc

Distributed Clocks settings

O

Dc@Mode

Mode for controlling the DC time.

O

“BusShift” or “MasterShift” or “ExternalSync”

Dc@SyncWindowMonitoring

SyncWindowMonitoring

O

Bool

Dc@ContinuousRunTimeMeasuring

ContinuousRunTimeMeasuring

O

Bool

Dc@SystemTime64Bit

SystemTime64Bit

O

Bool

Master/Groups

Groups settings

O

Groups/Entry@Members

Members of group

M

Semicolon separated string with slave addresses, like “1001;1002”

Groups/Entry@Name

Name of group

O

String

Groups/Entry@TaskId Task

Id of group

O

HexDecValue

Groups/Entry@PinInputOffset

Input offset of pinned group

O

HexDecValue

Groups/Entry@PinOutputOffset

Output offset of pinned group

O

HexDecValue

Groups/Entry@HcIdentificationValue

Identification value for a hot connect group

O

HexDecValue

Master/CyclicTasks

Cyclic task settings

O

CyclicTasks/Entry@TaskId

Id of cyclic task

M

String

CyclicTasks/Entry@Comment

Comment of cyclic task

O

String

CyclicTasks/Entry@CycleTime

Cycle time of cyclic task (“Task 0” uses “Master/CycleTime”)

O

HexDecValue

Master/MasterSyncUnits

Master Sync Unit settings

O

MasterSyncUnits/Entry@MsuId

Id of master sync unit

M

HexDecValue

MasterSyncUnits/Entry@TaskId

TaskId of master sync unit

O

String

MasterSyncUnits/Entry@Name

Name of master sync unit

O

String

MasterSyncUnits/Entry@InputOffset

Input offset of master sync unit

O

HexDecValue

MasterSyncUnits/Entry@OutputOffset

Output offset of master sync unit

O

HexDecValue

Master/SyncUnitPairs

Sync Unit Pairs settings

O

SyncUnitPairs/Entry@MsuId

Master sync unit id

M

HexDecValue

SyncUnitPairs/Entry@PhysAddr

Slave address

M

HexDecValue

SyncUnitPairs/Entry@SlaveSu

Slave sync unit

O

HexDecValue

Master/TraceVariables

Trace variable settings

O

TraceVariables/Entry@Name

Name of trace variable

M

String

TraceVariables/Entry@DataType

Datatype of trace variable

M

String

TraceVariables/Entry@BitSize

Bit size of trace variable

M

HexDecValue

Master/CopyLinks

Copy link settings

O

CopyLinks/Entry@TraceVariableIdx

Index of trace variable

M

String

CopyLinks/Entry@DstPhysAddr

EtherCAT slave station address of destination slave (uint16)

M

String

CopyLinks/Entry@DstPdoIndex

Index of destination PDO

M

HexDecValue

CopyLinks/Entry@DstPdoEntryIndex

Index of destination PDO entry

O

HexDecValue

CopyLinks/Entry@DstPdoEntrySubIndex

SubIndex of destination PDO entry

O

HexDecValue

CopyLinks/Entry@DstAliasOffset

Alias offset of destination PDO entry (variable)

O

HexDecValue

Tag name / Attribute

Description

Mandatory / Optional

Data types

Slaves

Slave Settings

Slaves/Slave

Description of one slave device

O

Slave@Name

Name of slave (by default it will be generated in the format “Slave_PhysAddr”)

O

String

Slave@PhysAddr

EtherCAT slave station address (uint16)

M

HexDecValue

Slave/Description

Identification of the slave device in order to lookup the corresponding ESI file.

M

Description@VendorId

Slave’s Vendor ID

M

HexDecValue

Description@ProductCode

Slave’s Product Code

M

HexDecValue

Description@RevisionNo

Slave’s Revision Number

M

HexDecValue

Slave/PreviousPort

Topology Info. May be omitted if this is the first bus slave or if this is the first slave device of a HotConnect group which can be connected anywhere in the bus topology.

O

PreviousPort/PhysAddr

Station address of predecessor slave

M

HexDecValue, uint16

PreviousPort/Port

Outgoing port of predecessor slave

M

“B”, “C” or “D” according to ESI.

Slave/Dc

Distributed Clocks settings

O

Dc@Id

Selection of DC operation mode. The Id corresponds with the OpMode/Name tag in the ESI file.

O

String

Slave/Pdo

PDO settings

O

Slave/Pdo@Sorting

Flag for sorting PDOs of slave automatically (ascending)

O

Bool

Slave/Pdo/Add

Add PDOs

O

Add/Entry@Name

Name of Pdo

O

Add/Entry@Index

Index of Pdo

M

HexDecValue

Add/Entry@Type

Type of Pdo

O

Values: Tx/Rx

Slave/Pdo/Remove

Remove PDOs

O

Remove/Entry@Index

Index of Pdo

M

HexDecValue

Slave/Pdo/Edit

Edit PDOs

O

Edit/Entry@Index

Index of Pdo (if SlotNr is used, it must contain the index of the MDP-Module)

M

HexDecValue

Edit/Entry@SlotNr

SlotNr of MDP-Slave

O

HexDecValue

Edit/Entry@Type

Type of Pdo

M

Values: Tx/Rx

Edit/Entry@Name

New name of Pdo

M

Slave/PdoEntry

PDO entry settings

O

Slave/PdoEntry/Add

Add PDO Entries

O

Add/Entry@PdoIndex

Index of Pdo (if SlotNr is used, it must contain the PDO Index of the MDP-Module)

M

HexDecValue

Add/Entry@SlotNr

SlotNr of MDP-Slave

O

HexDecValue

Add/Entry@Name

Name of Pdo Entry

M

Add/Entry@Comment

Comment for Pdo Entry

O

Add/Entry@Index

Index of Pdo Entry (if SlotNr is used, it must contain the index of the MDP-Module)

M

HexDecValue

Add/Entry@SubIndex

SubIndex of Pdo Entry

M

HexDecValue

Add/Entry@DataType

DataType of Pdo Entry

M

e.g. #xINT

Add/Entry@Size

Size of Pdo Entry

M

HexDecValue

Slave/PdoEntry/Remove

Remove PDO Entries

O

Remove/Entry@PdoIndex

Index of Pdo (if SlotNr is used, it must contain the PDO Index of the MDP-Module)

M

HexDecValue

Remove/Entry@SlotNr

SlotNr of MDP-Slave

O

HexDecValue

Remove/Entry@Index

Index of Pdo Entry (if SlotNr is used, it must contain the index of the MDP-Module)

M

HexDecValue

Remove/Entry@SubIndex

SubIndex of Pdo Entry

M

HexDecValue

Slave/PdoEntry/Edit

Edit PDO Entries

O

Edit/Entry@PdoIndex

Index of Pdo (if SlotNr is used, it must contain the PDO Index of the MDP-Module)

M

HexDecValue

Edit/Entry@SlotNr

SlotNr of MDP-Slave

O

HexDecValue

Edit/Entry@Index

Index of Pdo Entry (if SlotNr is used, it must contain the index of the MDP-Module)

M

HexDecValue

Edit/Entry@SubIndex

SubIndex of Pdo Entry

M

HexDecValue

Edit/Entry@Name

New name of Pdo Entry

M

Edit/Entry@Comment

New comment of Pdo Entry

O

Slave/AliasVariables

PDO entry settings

O

Slave/AliasVariables/Add

Add Alias Variables

O

Add/Entry@PdoIndex

Index of Pdo of the alias variable

M

HexDecValue

Add/Entry@PdoEntryIndex

Index of PdoEntry of the alias variable

M

HexDecValue

Add/Entry@PdoEntrySubIndex

SubIndex of PdoEntry of the alias variable

M

Add/Entry@Direction

Direction of alias variable

M

String: “Input”,”Output”

Add/Entry@Offset

Offset of alias variable

M

HexDecValue

Add/Entry@Name

Name of alias variable

M

String

Add/Entry@Size

Size of alias variable

M

HexDecValue

Add/Entry@DataType

Data type of alias variable

O

String

Slave/ExcludePdo

Excludes PDO settings

O

Slave/ExcludePdo/Add

Excludes PDO

O

Add/Entry@Index

Index of PDO to exclude (if SlotNr is used, it must contain the PDO Index of the MDP-Module)

M

HexDecValue

Add/Entry@SlotNr

SlotNr of MDP-Slave

O

HexDecValue

Slave/ExcludePdo/Remove

Includes PDO

O

Remove/Entry@Index

Index of PDO to include (if SlotNr is used, it must contain the PDO Index of the MDP-Module)

M

HexDecValue

Remove/Entry@SlotNr

SlotNr of MDP-Slave

O

HexDecValue

Remove/Entry@SyncManager

Index of SyncManager

O

HexDecValue

Slave/InitCmd

CoE InitCmd settings

O

Slave/InitCmd/Add

Add CoE InitCmds

O

Add/Entry@Index

Index of InitCmd

M

HexDecValue

Add/Entry@SubIndex

SubIndex of InitCmd

M

HexDecValue

Add/Entry@Ccs

Direction of InitCmd

M

1 =Download; 2 = Upload

Add/Entry@Transitions

Transitions of InitCmd (comma separated)

M

Add/Entry@Data

Data of InitCmd

O

Add/Entry@Comment

Comment of InitCmd

O

Add/Entry@CompleteAccess

CompleteAccess of InitCmd

O

Bool

Slave/InitCmd/Remove

Remove CoE InitCmds

O

Remove/Entry@Index

Index of InitCmd (if SlotNr is used, it must contain the PDO Index of the MDP-Module)

M

HexDecValue

Remove/Entry@SlotNr

SlotNr of MDP-Slave

O

HexDecValue

Remove/Entry@SubIndex

SubIndex of InitCmd

M

HexDecValue

Remove/Entry@Ccs

Direction of InitCmd

M

1 =Download; 2 = Upload

Slave/InitCmd/Edit

Edit CoE InitCmds

O

Edit/Entry@Index

Index of InitCmd (if SlotNr is used, it must contain the PDO Index of the MDP-Module)

M

HexDecValue

Edit/Entry@SlotNr

SlotNr of MDP-Slave

O

HexDecValue

Edit/Entry@SubIndex

SubIndex of InitCmd

M

HexDecValue

Edit/Entry@Ccs

Direction of InitCmd

M

1 =Download; 2 = Upload

Edit/Entry@Data

New data of InitCmd

M

Slave/SoeInitCmd

SoE InitCmd settings

O

Slave/SoeInitCmd/Add

Add SoE InitCmds

O

Add/Entry@Idn

IDN of InitCmd

M

HexDecValue

Add/Entry@Chn

Channel of InitCmd

M

HexDecValue

Add/Entry@Transitions

Transitions of InitCmd (comma separated)

M

Add/Entry@Data

Data of InitCmd

O

Add/Entry@Comment

Comment of InitCmd

O

Slave/SoeInitCmd/Remove

Remove SoE InitCmds

O

Add/Entry@Idn

IDN of InitCmd

M

HexDecValue

Add/Entry@Chn

Channel of InitCmd

M

HexDecValue

Slave/SoeInitCmd/Edit

Edit SoE InitCmds

O

Edit/Entry@Idn

IDN of InitCmd

M

HexDecValue

Edit/Entry@Chn

Channel of InitCmd

M

HexDecValue

Edit/Entry@Data

New data of InitCmd

M

Slave/Mdp

MDP settings

O

Slave/Mdp/Add

Assign MDP-Module

O

Add/Entry@SlotNr

SlotNr of MDP-Slave

M

HexDecValue

Add/Entry@ModuleIdent

ModuleIdent of MDP-Module

M

HexDecValue

Add/Entry@Name

Name of Slot/Module-Pair

O

String

Slave/Mdp/Edit

Edit MDP-Module

O

Edit/Entry@SlotNr

SlotNr of MDP-Slave

M

HexDecValue

Edit/Entry@Name

Name of Slot/Module-Pair

M

String

Slave/Mdp/Remove

Not assign MDP-Slot

O

Remove/Entry@SlotNr

SlotNr of MDP-Slave

M

HexDecValue

Slave/CopyLink

Slave to Slave copy

O

Slave/CopyLink/Add

Add “CopyLink”

O

Add/Entry@PhysAddr

EtherCAT slave station address of destination slave (uint16)

M

HexDecValue

Add/Entry@BitSize

Size to copy (bits)

M

HexDecValue

Add/Entry@SrcBitOffs

Offset in source slave (bits)

O

HexDecValue

Add/Entry@DstBitOffs

Offset in destination slave (bits)

O

HexDecValue

Add/Entry@SrcPdoIndex

Index of source PDO

O

HexDecValue

Add/Entry@SrcPdoEntryIndex

Index of source PDO entry

O

HexDecValue

Add/Entry@SrcPdoEntrySubIndex

SubIndex of source PDO entry

O

HexDecValue

Add/Entry@SrcAliasOffset

Alias offset of source PDO entry (variable)

O

HexDecValue

Add/Entry@DstPdoIndex

Index of destination PDO

O

HexDecValue

Add/Entry@DstPdoEntryIndex

Index of destination PDO entry

O

HexDecValue

Add/Entry@DstPdoEntrySubIndex

SubIndex of destination PDO entry

O

HexDecValue

Add/Entry@DstAliasOffset

Alias offset of destination PDO entry (variable)

O

HexDecValue

Add/Entry@InCycle

Enable S2S copy link in one cycle

O

Bool

Slave/EoE

EoE settings

O

EoE/Enable

Enables EoE

O

Bool

EoE/VirtualMacAddress

Virtual MAC address

O

MAC Address (e.g. “02 00 00 00 03 E9” or “Auto” = MAC Address will be generated)

EoE/TimeStampRequested

Time Stamp Requested

O

Bool

EoE/PortMode

Port Mode

O

Bool (True = “IP Port”, False = “Switch Port”)

EoE/OverwriteIpSettings

Overwrite IP Settings

O

Bool

EoE/IpAddress

IP Address

O

IP Address (e.g. “127.0.0.1”)

EoE/SubnetMask

Subnetmask

O

IP Address

EoE/DefaultGateway

Default Gateway

O

IP Address

EoE/DnsServer

DNS Server

O

IP Address

EoE/DnsName

DNS Name

O

String

Slave/Settings

Advanced Settings

O

Settings/DisableLRW

Disables LRW

O

Bool

Settings/CheckVendorId

Enables checking vendor ID

O

Bool

Settings/CheckProductCode

Enables checking product code

O

Bool

Settings/CheckRevisionNo

Checking revision number

O

NONE, EQ, EQ_OR_G, LW_EQ, LW_EQ_HW_EQ_OR_G, HW_EQ, HW_EQ_LW_EQ_OR_G

Settings/CheckSerialNo

Enables checking serial number

O

Bool

Settings/IdentificationAdo

Overwrites identification ADO value

O

HexDecValue

Settings/WatchdogMultiplier

Sets watchdog multiplier

O

HexDecValue

Settings/PdiWatchdog

Sets PDI watchdog

O

HexDecValue

Settings/SmWatchdog

Sets SM watchdog

O

HexDecValue

Settings/PotentialRefClock

Enables potential reference clock

O

Bool

Settings/MailboxAccessTimout

Sets timeout for mailbox access

O

HexDecValue

Settings/PreopTimeout

Sets the timeout for changing state machine from Init to Pre-Op and from Init to Bootstrap

O

HexDecValue

Settings/SafeopOpTimeout

Sets the timeout for changing state machine from Pre-Op to Safe-Op and from Safe-Op to Op

O

HexDecValue

Settings/BackToInitTimeout

Sets the timeout for changing state machine back to Pre-Op or Init

O

HexDecValue

Settings/BackToSafeopTimeout

Sets the timeout for changing state machine from Op to Safe-Op

O

HexDecValue

Settings/MailBoxOutputSize

Sets mailbox input size

O

HexDecValue

Settings/MailBoxInputSize

Sets mailbox output size

O

HexDecValue

Slave/TypeSpecific

Type specific data

O

TypeSpecific/Settings

Settings for “TypeSpecific”

O

Please refer to “Type Specific Settings

Settings/Entry@Name

Name of setting

M

String (e.g. “DP Slave Parameter Set” for EL6731-0010)

Settings/Entry@SubName

SubName of setting

M

String (e.g. “Station Address” for EL6731-0010)

Settings/Entry@Value

Value of setting

M

String

TypeSpecific/Inputs

Inputs of “TypeSpecific”

O

Inputs/Entry@Name

Name of input

M

String (e.g. Variable n)

Inputs/Entry@Type

Type of input

M

String (e.g. 1 BYTE, 2 WORD, …)

TypeSpecific/Outputs

Outputs of “TypeSpecific”

O

Outputs/Entry@Name

Name of output

M

String (e.g. Variable n)

Outputs/Entry@Type

Type of output

M

String (e.g. 1 BYTE, 2 WORD, …)

4.3. Create EBI file using EC-Engineer

Instead of creating the EBI file manual, EC-Engineer can be used to create an EBI file. To do that, EC-Engineer must be started with the command line parameter /ENIBUILDER (EC-Engineer User Manual, Chapter 8 Command Line Interface)

_images/create-ebi-file.png

If EC-Engineer is started like this, there will be a new entry in the context menu:

_images/create-ebi-file_2.png

So now it is possible to create the whole configuration in the EC-Engineer and then use the context menu to automatically create the EBI file.

4.4. Type Specific Settings

Some slaves needs special configuration options and support only special types of inputs and outputs. For more information please refer the manual of EC-Engineer.

4.4.1. EL6731-0010 PROFIBUS DP Slave

Further options:

General

Activate: Activates the automatism for generating PDOs and Init Commands

DP Slave Parameter Set

Station Address: DP station address of the DP slave (permitted values: 0-125) Device Type: DP Ident Number of the DP slave

4.4.2. EL6631-0010 PROFINET IO Device

Further options:

General

Activate: Activates the automatism for generating PDOs and Init Commands

4.5. Examples

4.5.1. Example 1: Simple EtherCAT topology

_images/topology.png

The EBI file for this bus topology looks like this (config_simple.xml):

_images/bus-topology.png

4.5.2. Example 2: EtherCAT topology with HotConnect

This example has one HotConnect group with two members (EK1100 and EL2008). Note that the head of the HotConnect group (EK1100, PhysAddr 1007) has no PreviousPort tag defined, so this group can be connected anywhere in the topology. E.g. to EK1110, PhysAddr 1004, PortB or EK1100, PhysAddr 1001, PortC.

Note

If the PreviousPort tag is defined, the HotConnect group can be connected only to that port specified by the PreviousPort tag (config_hc.xml).

_images/topology_2.png

The EBI file for this bus topology looks like this:

_images/bus-topology_2.png

4.5.3. Example 3: DC configuration

For a Distributed Clock (DC) enabled configuration, please see the “config_dc.xml” sample file. For DC you should at least provide the Master tag. The CycleTime should be set and must correspond with your EtherCAT cycle time.

Additionally each slave has an optional Dc-Tag. The Id attribute of this tag will choose a DC operation mode from the ESI (must match with one of the ESI OpMode/Name tag’s/ID). If the Dc-Tag is omitted the first DC operation mode in the ESI is selected (config_dc.xml).

4.5.4. Example 4: PDO exclusion

This configuration fragment shows how to exclude PDO’s and PDO-Entries. The slave “SGDV – E1 CoE Drive” has the PDO 0x1a01 (2nd Transmit PDO mapping) defined as default PDO by the ESI (Default PDO: Actually PDO’s with assigned Sync-Managers).

In the EBI file, the PDO 0x1a01 (2nd Transmit PDO mapping) will be now excluded and exclusion of PDO 0x1a00 (1st Transmit PDO mapping) will be removed. This means that the PDO assignment will be changed from 0x1a01 to 0x1a00.

Note that the ENI Builder doesn’t check if the PDO- or PDO-Entries exclusion is allowed by the ESI description. I.e. digital IO clamps without microcontroller (Device-Emulation) might have fixed PDO’s, so the PDO’s exclusion is not allowed (not supported by HW) (config_full.xml).

_images/topology_3.png

4.5.5. Example 5: Configure special slaves

This example shows how to configure special slaves which uses the tag “Type Specific Settings” (config_special.xml)…

Slave 1002: PROFIBUS DP Slave “EL6731-0010” with 1 BYTE IN & OUT
_images/Slave-1002.png
Slave 1003: PROFINET IO Device “EL6631-0010” with 1 BYTE IN & OUT
_images/Slave-1003.png
Slave 1003: K-bus Coupler “BK1120” with terminals “KL1012” and “KL2012”
_images/Slave-1003_2.png

4.5.6. Example 6: Master Sync Units

This example shows how to configure Master Sync Units (config_msu.xml).

_images/master-sync-units.png

The EBI file for this bus topology looks like this (config_msu.xml):

_images/bus-topology_3.png