Simple EtherCAT SubDevice Esi Parser Example

‍⚠️ Important Note

This feature is part of premium SDK. In case you are using standard and need premium, please contact your regional TI sales representative for additional details.

Scope

This example demonstrates how to use the ESI (EtherCAT Slave Information) parser functionality to configure an EtherCAT SubDevice. The example builds upon the basic SubDevice example (401_simple) but replaces manual object dictionary and process data configuration with automated configuration using the ESI parser.

The ESI parser example shows how to:

1. Configure the hardware and create the basic EtherCAT SubDevice instance
2. Use the EC_API_SLV_ESI_parseFileRam function to automatically parse ESI XML data from memory
3. Let the parser configure the Object Dictionary, PDO mappings, and Sync Manager settings based on the ESI data

By using the ESI parser approach, developers no longer need to manually call the following functions that were required in the basic example:

• EC_API_SLV_CoE_odAddVariable
• EC_API_SLV_CoE_odAddArray
• EC_API_SLV_CoE_odAddEnum
• EC_API_SLV_setSyncManConfig

In the ESI parser example, these configurations are replaced with:

EC_API_SLV_ESI_parseFileRam(pAppInstance_p->ptEcSlvApi, (const uint8_t *)ti_amxxx_r5f_simple_hex, ti_amxxx_r5f_simple_hex_len);

Therefore, the ESI parser significantly reduces the amount of manual configuration code while ensuring consistency between the device's implementation and its ESI description. However, developers should be aware that application-specific callbacks, hardware initialization, and runtime behavior still require manual implementation.

The ESI parser automatically handles these configurations based on the XML description, which significantly reduces code complexity and ensures consistency between the device implementation and its ESI description file.

This approach is particularly useful when:

• Developing devices with complex object dictionaries
• Maintaining consistency between ESI files and firmware implementation
• Reducing manual configuration errors
• Simplifying the development process for EtherCAT slave devices

The example shows how to convert an ESI XML file to a C array using the provided esiToArrayConverter.py tool and then use that array with the EC_SLV_ESI_esiParseRam function to configure the EtherCAT slave device.

ESI Parser API

Function Name	Description
EC_API_SLV_ESI_parseFileRam	Parses EtherCAT Slave Information (ESI) data from a raw binary buffer in memory, processing it byte-by-byte to extract configuration details needed to set up the EtherCAT slave device's object dictionary, PDO mappings, and sync managers.
EC_API_SLV_ESI_parseFile	Parses EtherCAT Slave Information (ESI) data from a file on the filesystem, reading it character-by-character to extract configuration details needed to set up the EtherCAT slave device's object dictionary, PDO mappings, and sync managers.

Mandatory elements of the ESI file

The following elements and attributes are mandatory for proper functionality of the ESI parser:

Basic Structure

• <EtherCATInfo> - Root element
  • <Vendor> - Vendor information
  • <Descriptions> - Device descriptions section
    • <Devices> - Container for device definitions
      • <Device> - Device definition

Vendor Information

• <Vendor> section with:
  • <Id> - Vendor ID
  • <Name> - Vendor name

Device Information

• <Device> with:
  • <Type ProductCode="#x..." RevisionNo="#x..." SerialNo="#x..."> - Device type with product code, revision number, and serial number
  • <Name> - Device name
  • <GroupType> - Group type classification

Object Dictionary

• <Profile> section containing:
  • <Dictionary> - Object dictionary definition
    • <DataTypes> - Data type definitions
      • <DataType> - Individual data type with:
        • <Name> - Data type name (e.g., "BOOL", "UINT", "UDINT")
        • <BitSize> - Size in bits
    • <Objects> - Object definitions
      • <Object> - Individual object with:
        • <Index> - Object index in hexadecimal format
        • <Name> - Object name
        • <Type> - Data type reference
        • <BitSize> - Size in bits
        • <Info> - Additional information (optional)
        • <Flags> - Access rights and properties

Sync Manager Configuration

• <Sm> elements with:
  • DefaultSize - Size of the PDO in bytes. This is the default size used if no PDO mapping is specified
  • MaxSize - Maximum size of the PDO in bytes. This is the maximum size that the PDO can grow to
  • StartAddress - Starting memory address in hexadecimal format
  • ControlByte - Control byte value in hexadecimal format
  • Enable - Enable flag (0 or 1)
  • Content type - e.g., "Outputs", "Inputs", "MBoxOut", "MBoxIn"

Process Data Objects

• <RxPdo> and <TxPdo> sections with:
  • <Index> - PDO index in hexadecimal format
  • <Name> - PDO name
  • <Entry> elements containing:
    • <Index> - Object index referenced by the entry
    • <SubIndex> - Object subindex referenced by the entry
    • <BitLen> - Size in bits
    • <Name> - Entry name
    • <DataType> - Data type reference

The parser automatically processes these elements to configure the EtherCAT SubDevice according to the ESI description, ensuring that the firmware implementation matches the device specification provided to the EtherCAT MainDevice.

Manual Configuration

The ESI parser automates the configuration of the EtherCAT SubDevice according to the ESI description. However, there are certain elements that still require manual configuration:

1. Callback Registration
   • Application callbacks must still be registered manually:
     • EC_API_SLV_cbRegisterMainLoopCb() - Main loop callback
     • EC_API_SLV_cbRegisterUserApplicationCb() - User application callback
     • EC_API_SLV_EEPROM_cbRegisterWrite() - EEPROM write callback
     • EC_API_SLV_EEPROM_cbRegisterRead() - EEPROM read callback
     • EC_API_SLV_cbRegisterStartInputHandler() - Start input handler callback
     • EC_API_SLV_cbRegisterStartOutputHandler() - Start output handler callback
     • ...
2. Process Data Handling
   • Application-specific processing of input and output data
   • Custom state machines and logic
   • Process data variable access and manipulation
3. ESI Data Loading
   • The ESI data array must be manually included in the application The example provides hex arrays of the basic SubDevice example ESi files in common/ESL_eoeDemoData.h
   • The call to EC_SLV_ESI_esiParseRam() must be made explicitly

Functions handled by the ESI Parser API

Function Name
EC_API_SLV_CoE_getObject
EC_API_SLV_CoE_setObjectData
EC_API_SLV_CoE_getObjectEntry
EC_API_SLV_CoE_setObjectEntryData
EC_API_SLV_PDO_create
EC_API_SLV_PDO_createEntry
EC_API_SLV_PDO_setFixed
EC_API_SLV_PDO_disable
EC_API_SLV_setDeviceType
EC_API_SLV_CiA402_setAxisNumber
EC_API_SLV_setSyncManConfig
EC_API_SLV_setStandardMailbox
EC_API_SLV_setPDOSize
EC_API_SLV_setHwVersion
EC_API_SLV_setSwVersion
EC_API_SLV_CoE_configEnum
EC_API_SLV_CoE_configRecordSubIndex
EC_API_SLV_CoE_odAddVariable
EC_API_SLV_CoE_odAddArray
EC_API_SLV_setVendorId
EC_API_SLV_setProductCode
EC_API_SLV_setRevisionNumber
EC_API_SLV_setSerialNumber
EC_API_SLV_setProductName
EC_API_SLV_setGroupType
EC_API_SLV_setBootStrapMailbox
EC_API_SLV_setPDICfg

Tooling

ESI to Array Converter

Path: common/tools/esiToArrayConverter.py

The esiToArrayConverter.py script is a utility tool for converting EtherCAT Slave Information (ESI) XML files into C-compatible arrays that can be included in embedded applications. It supports two conversion modes:

1. String mode - Converts the ESI XML file into a C-style string array where each XML line becomes a separate string element
2. Hex mode - Converts the ESI XML file into a C-style hex array representing the binary content

Usage

python3 esiToArrayConverter.py input.xml [options]

Options

• -o, --output: Output file (default: stdout)
• -n, --name: Array name (default: esiData)
• -m, --mode: Conversion mode: string (line by line) or hex (binary)
• -b, --bytes: Bytes per line in hex mode (default: 16)

Example

python esiToArrayConverter.py MyDevice.xml -o esi_data.h -m hex

This tool is useful for embedding ESI data directly into firmware, allowing the EC_SLV_ESI_esiParseRam function to parse the device configuration at runtime from the embedded array rather than requiring external file access.