/
Appendix S – EtherCAT Import/Export description template specifiers and variables

Appendix S – EtherCAT Import/Export description template specifiers and variables

Owned by Veronika Tannewitz
Last updated: Jul 05, 2023 by Michael Struwe

specifier name

category

description

${index.address}

description:

numerical number of the main-index.

category:

mandatory

value range:

0x0040 - 0xFFFF

${index.dataType.address}

description:

numerical value of the data type according to /CiA-301/.

category:

mandatory

value range:

0x0001 - 0xFFF

${index.name}

description:

name of the object for the documentation in the ESI file. If no name is specified the Communication Creator builds own names:

·         for data types:

DATATYPE_<index>_T, example: DATATYPE_0040_T

·         for variables: obj_<index>, example: obj_2000

category:

Optional

value range:

String

${index.objectCode}

description:

numerical value of the object code according to /CiA-301/.

Variable value is one of the following:

  • EC_VARIABLE

  • EC_ARRAY

  • EC_RECORD

  • EC_DEFTYPE

  • EC_DEFSTRUCT

category:

mandatory

value range:

0x06 for DEFSTRUCT

0x07 for VAR

0x08 for ARRAY

0x09 for RECORD

${index. createObjName}

description:

defines if the object name will be written to the ec_od.c file.

category:

Optional

value range:

0 – object name is not written to file

1- object name is written to file

 

Default: 1

${index.description}

description:

documentation of the object.

category:

optional

value range:

String

${index.createExtern}

description:

defines if an external declaration shall be generated.

category:

optional

value range:

0 - extern declaration is not generated

1- extern declaration is generated

 

Default: 1

${index.createTypedef}

description:

defines if the C struct for a complex data type shall be generated in C code.

category:

optional

value range:

0 - data type struct is not generated

1- data type struct is generated

 

Default: 1

${index.createVariable}

description:

defines if the variable shall be generated in C code. (not applicable for data types)

 

condition: this attribute must be local changeable (see GUI Line > Standard Settings > Create variable > local changeable) 

category:

optional

value range:

0 - variable is not generated

1- variable is generated

 

Default: 1

${index.virtualObject}

description:

defines if the object shall be interpreted as virtual or normal object.

 

condition: this attribute must be local changeable (see GUI Line > Standard Settings > Virtual object > local changeable) 

category:

optional

value range:

0 - normal object

1- virtual object

 

Default: 0

${index.generateESIEntry}

description:

defines if the object is excluded from ESI generation

category:

optional

value range:

0 - object is not generated in ESI

1 - object is not generated in ESI

 

Default: 1

${index.generateDocEntry}

description:

defines if the object is excluded from exported documents generation

category:

optional

value range:

0 - object is not generated in exported documents

1 - object is not generated in exported documents

 

Default: 1

${subindex.address}

description:

numerical number of the sub-index.

category:

mandatory

value range:

0 - 255

${subindex.dataType.address}

description:

numerical value of the data type of the sub-index according to /CiA-301/.

category:

mandatory

value range:

0x0001 - 0x001E

${subindex.name}

description:

name of the sub-index in the ESI file and in the documentation. If no name is specified the name is generated by the Communication Creator as follow:

  1. for object code VAR: The name of the main-index is used, see ${index.name}.

for object Code ARRAY or RECORD: The name is generated: sub_<sub>, example: sub_0C. <sub> is a hexadecimal number with 2 digits.

category:

optional

value range:

String

${subindex.CName}

description:

name of the sub-index used in the generated C code for the element of complex data types. If no name is specified the name is generated by the Communication Creator as follow:

  1. for object code VAR: see ${index.name}.

  2. for object Code ARRAY or RECORD: The name is generated: sub_<sub>, example: sub_0C. <sub> is a hexadecimal number with 2 digits.

category:

optional

value range:

String with C-syntax

${subindex.size}

description:

size of the sub-index. This csv-specifier is relevant for extended data types, e.g.

VISIBLE_STRINGs.

category:

optional

value range:

depends on data type

${subindex.unit}

description:

unit of the object.

category:

optional

value range:

String

${subindex.accessPreOp}

description:

access right of the sub-index in the state PRE-OPERATIONAL.

Variable value is one of the following:

  • EC_READONLY

  • EC_WRITEONLY

  • EC_READWRITE

category:

optional

value range:

RO, RW, WO

 

Default: RO

${subindex.accessSafeOp}

description:

access right of the sub-index in the state SAFE-OPERATIONAL.

Variable value is one of the following:

  • EC_READONLY

  • EC_WRITEONLY

  • EC_READWRITE

category:

optional

value range:

RO, RW, WO

 

Default: RO

${subindex.accessOp}

description:

access right of the sub-index in the state OPERATIONAL.

Variable value is one of the following:

  • EC_READONLY

  • EC_WRITEONLY

  • EC_READWRITE

category:

optional

value range:

RO, RW, WO

 

Default: RO

${subindex.lowerLimit}

description:

lower limit of numerical objects.

category:

optional

value range:

range of numerical data type

${subindex.upperLimit}

description:

upper limit of numerical objects.

category:

optional

value range:

range of numerical data type

${subindex.defaultValue}

description:

value of the object.

category:

optional

value range:

depends on data type

${subindex.pdoAccess}

description:

PDO access right of the sub-index.

Variable value is one of the following:

  • EC_NO_PDO

  • EC_RPDO

  • EC_TPDO

  • EC_RPDO_TPDO

category:

optional

value range:

no - PDO mapping is not allowed

 r – only mappable via RPDO

 t – only mappable via TPDO

tr – mappable in RPDO and TPDO

 

Default: no

${subindex.limitsInESI}

description:

defines if the limit values shall be documented in the ESI files.

category:

optional

value range:

0 - ESI without limits

1 - ESI with limits

 

Default: 1

${subindex.defaultInESI}

description:

defines if the default value shall be documented in the ESI files.

category:

optional

value range:

0 - ESI without default value

1 - ESI with default value

 

Default: 1

${subindex.category}

description:

defines category of the sub-index.

Variable value is one of the following:

  • EC_MANDATORY

  • EC_OPTIONAL

  • EC_CONDITIONAL

category:

optional

value range:

mandatory, optional, conditional

 

Default: mandatory

${subindex.CImpl}

description:

defines C Implementation of the sub-index.

Variable value is one of the following:

  • EC_MANAGED_CONST

  • EC_MANAGED_VAR

  • EC_APPL_VAR

  • EC_APPL_ARRAY

category:

optional

value range:

Managed Constant, Managed Variable, Application Variable, Application Array

 

Default: Managed Constant

${subindex.backupFlag}

description:

defines the Backup property

category:

optional

value range:

0 – object is not restored during device exchange

1 – object is restored during device exchange

 

Default: 0

${subindex.settingFlag}

description:

defines the Setting property

category:

optional

value range:

0 – object has not to be configured before changing into an operational state

1 – object has to be configured before changing into an operational state

 

Default: 0

 

The following specifiers are not applicable for csv-import

 

${subsegment.address}

description:

numerical number of the sub-segment.

category:

mandatory

value range:

0x2000 - 0xFFFF

${subsegment.CName}

description:

name of the variable in the generated C code. If no name is specified the name is generated by the Communication Creator as follow:

  1. The subsegment name (${subsegment.name}) is

used if it is specified with adjustments to C syntax.

  1. If no name is specified the Communication Creator builds own names:

subseg_<subsegment>, example: subseg_2000

category:

optional

value range:

String with C-syntax

${subsegment.name}

description:

name of the object for the documentation in the exported documents files. If no name is specified the Communication Creator uses the C name, see specifier ${subsegment.CName}.

category:

optional

value range:

String

${subsegment.startIndex}

description:

numerical number of the lower limit of the index range that this subsegment can contain. (has to be the same value like ${subsegment.address})

category:

optional

value range:

0x2000 - 0xFFFF

${subsegment.endIndex}

description:

numerical number of the upper limit of the index range that this subsegment can contain.

category:

mandatory

value range:

0x2000 - 0xFFFF

${subsegment.virtualObject}

description:

defines if the sub-segment shall be interpreted as virtual or normal sub-segment (see chapter 12.9 à sub-segmentation).

category:

optional

value range:

0 - normal sub-segment

1- virtual sub-segment

 

Default: 0

Table 44: Specifiers for import/export description templates

name in code

type

description

${subsegment.contents}

list

list of indices that is hold by this subsegment

${index.contents}

list

list of sub-indices that is hold by this index

${esiVendorComment}

var

value of setting: EtherCAT Slave Information > Vendor > Comment

${projectName}

var

project file name without file extension

${exampleEcLogoFilePath}

var

file path for EtherCAT logo

${allSubSegsStructureList}

list²

list that contains a list for every line.

the second level list contains all subsegments with their documented indices

 

condition: depends on setting Exported document > select segments

${manufactSubSegsStructureList}

list²

list that contains a list for every line.

the second level list contains only the manufacturer subsegments with their documented indices

 

condition: depends on setting Exported document > select segments

${devSubSegsStructureList}

list²

list that contains a list for every line.

the second level list contains only the device profile subsegments with their documented indices

 

condition: depends on setting Exported document > select segments

${enableIndRange1}

var

value of setting: Exported document > Enable 1st index range

${enableIndRange2}

var

value of setting: Exported document > Enable 2nd index range

${allIndexAndDatObjects}

list²

list that contains a list for every line.

the second level list contains all documented indices from all segments without sub-segmens, but indices from sub-segments are included

${datTypeSegObjects}

list²

list that contains a list for every line.

the second level list contains all documented indices from the datatypes segment

${commSegObjects}

list²

list that contains a list for every line.

the second level list contains all documented indices from the communication segment

${manuFactObjects}

list²

list that contains a list for every line.

the second level list contains all documented indices from the manufacturer segment

${deviceSegObjects}

list²

list that contains a list for every line.

the second level list contains all documented indices from the device profile segment

${allSubSegsList}

list²

list that contains a list for every line.

the second level list contains all subsegments with their documented indices

${manufactSubSegsList}

list²

list that contains a list for every line.

the second level list contains only the manufacturer subsegments with their documented indices

${devSubSegsList}

list²

list that contains a list for every line.

the second level list contains only the device profile subsegments with their documented indices

${hasUserDatSegObjects}

var

bool value indicating that there are one or more objects with address 0x40-0x25F

${hasCommSegObjects}

var

bool value indicating that there is one or more objects with address 0x1000-0x1FFF

${hasManufSegObjects}

var

bool value indicating that there is one or more objects with address 0x2000-0x5FFF

${hasDevSegObjects}

var

bool value indicating that there is one or more objects with address 0x6000-0xFFFF

${lineList}

list

List that holds the number of each line

${modDate}

var

date of generation with format: yyyy/MM/dd