About

This example demonstrates the fundamental steps involved in configuring the EtherCAT SubDevice firmware. The process encompasses the following key activities: setting the essential configuration parameters through the ECAT_SET_CONFIG_REQ request, modifying OEM-specific vendor data using the HIL_DDP_SERVICE_SET_REQ request, and adjusting the ESI file.

Prerequisites

The distribution of the examples is available at the following link: EtherCAT Slave Examples.

You can find the cifXApplicationDemo project along with the related ECS_Simple example in netXStudio at the path:

Components\cifXApplicationDemoECS_Simple

The active target for the netX90 use case can be selected as illustrated in the image below:

Overview of the example structure

The example includes a general section that remains consistent across all variations. This section outlines the functions necessary to initialize access to loadable firmware via dual-port memory, utilizing the netX toolkit. For further details, please refer to cifX/netX Toolkit (NXDRV-TKIT). The source code for this general section can be found in the folder \Components\ApplicationDemo as well as in the Targets folder.

The EtherCAT SubDevice simple configuration example, located in AppECS_DemoApplication.c, begins by initializing the packet handler through the function AppECSSimpleDemo_Initialize. This handler is responsible for managing message packets from the EtherCAT SubDevice firmware. The example includes the handling of two specific indications from the EtherCAT SubDevice firmware:

Link Status Change Indication (HIL_LINK_STATUS_CHANGE_IND): This indication is sent by the firmware whenever there is a change in link status.
EtherCAT State Machine AL Status Changed Indication (ECAT_ESM_ALSTATUS_CHANGED_IND): This indication reports the current state of the EtherCAT SubDevice state machine.

The function AppECSSimpleDemo_Setup is responsible for preparing and sending the configuration request to the EtherCAT SubDevice firmware. Following this, the communication channel is initialized.

Additionally, the communication state of the device on the network can be modified using the function App_SysPkt_AssembleStartStopCommReq.

Configuration Request packet

The EtherCAT SubDevice Configuration Request packet is constructed within the file AppECS_DemoApplication.c, as detailed below:

static int AppECSSimpleDemo_Setup(APP_ECS_CHANNEL_HANDLER_RSC_T *ptEcsRsc)
{
  uint32_t                      ulRet         = CIFX_NO_ERROR;
  CIFX_PACKET                   tCifXPkt      = {{0}};
  ECAT_SET_CONFIG_REQ_T         *ptConfigReq  = (ECAT_SET_CONFIG_REQ_T*)&tCifXPkt;
  ECAT_SET_CONFIG_DEVICEINFO_T  *ptDevInfo    = &ptConfigReq->tData.tComponentsCfg.tDeviceInfoCfg;;


  ptConfigReq->tHead.ulDest = HIL_PACKET_DEST_DEFAULT_CHANNEL;
  ptConfigReq->tHead.ulLen  = sizeof(ptConfigReq->tData);
  ptConfigReq->tHead.ulCmd  = ECAT_SET_CONFIG_REQ;

  ptConfigReq->tData.tBasicCfg.ulSystemFlags  = ECAT_SET_CONFIG_SYSTEMFLAGS_APP_CONTROLLED;
  ptConfigReq->tData.tBasicCfg.ulWatchdogTime = 1000;

  ptConfigReq->tData.tBasicCfg.ulVendorId = ECS_SECONDARY_VENDORID_HILSCHER;  /** Creates Vendor ID in Sii Image in accordance to ESI file */
  ptConfigReq->tData.tBasicCfg.ulProductCode = ECS_PRODUCTCODE; /** Creates Product Code in Sii Image in accordance to ESI file */
  ptConfigReq->tData.tBasicCfg.ulRevisionNumber = ECS_REVISIONNUMBER; /** Creates Revision Number in in Sii Image accordance to ESI file: increments with every released change of ESI file */
  ptConfigReq->tData.tBasicCfg.ulProcessDataOutputSize = sizeof(ptEcsRsc->abAktorData); /**< Process Data Output Size from master view */
  ptConfigReq->tData.tBasicCfg.ulProcessDataInputSize = sizeof(ptEcsRsc->abSensorData); /**< Process Data Input Size from master view */

  /** ECAT_SET_CONFIG_DEVICEINFO configuration ***************************************/
  ptConfigReq->tData.tBasicCfg.ulComponentInitialization |= ECAT_SET_CONFIG_DEVICEINFO;
  strncpy((char*)ptDevInfo->szGroupIdx, DEV_GROUP_TYPE_INFO, sizeof(ptDevInfo->szGroupIdx));
  ptDevInfo->bGroupIdxLength = strnlen((char*)ptDevInfo->szGroupIdx, sizeof(ptDevInfo->szGroupIdx));
  strncpy((char*)ptDevInfo->szOrderIdx, DEV_TYPE_INFO, sizeof(ptDevInfo->szOrderIdx));
  ptDevInfo->bOrderIdxLength = strnlen((char*)ptDevInfo->szOrderIdx, sizeof(ptDevInfo->szOrderIdx));
  strncpy((char*)ptDevInfo->szNameIdx, DEV_NAME_INFO, sizeof(ptDevInfo->szNameIdx));
  ptDevInfo->bNameIdxLength = strnlen((char*)ptDevInfo->szNameIdx, sizeof(ptDevInfo->szNameIdx));

  /* Send configurations */
  ulRet = Pkt_SendReceivePacket(ptEcsRsc->hPktIfRsc,&tCifXPkt, APPECS_DEMOAPPLICATION_TIMEOUT);
  if(ulRet != CIFX_NO_ERROR){
    return (int)ulRet;
  }
  else if(tCifXPkt.tHeader.ulState != SUCCESS_HIL_OK){
    return (int)tCifXPkt.tHeader.ulState;
  }

  /* initialize channel to use the configured data */
  App_SysPkt_AssembleChannelInitReq(&tCifXPkt);
  ulRet = Pkt_SendReceivePacket(ptEcsRsc->hPktIfRsc, &tCifXPkt, APPECS_DEMOAPPLICATION_TIMEOUT);
  if(ulRet != CIFX_NO_ERROR){
    return (int)ulRet;
  }
  else if(tCifXPkt.tHeader.ulState != SUCCESS_HIL_OK){
    return (int)tCifXPkt.tHeader.ulState;
  }

  /* place for optional registrations */

  /* set bus on */
  App_SysPkt_AssembleStartStopCommReq(&tCifXPkt, true);
  ulRet = Pkt_SendReceivePacket(ptEcsRsc->hPktIfRsc, &tCifXPkt, APPECS_DEMOAPPLICATION_TIMEOUT);
  if(ulRet != CIFX_NO_ERROR){
    return (int)ulRet;
  }
  else if(tCifXPkt.tHeader.ulState != SUCCESS_HIL_OK){
    return (int)tCifXPkt.tHeader.ulState;
  }

  return 0;
}

The section contains device information, specifically referring to ECAT_SET_CONFIG_DEVICEINFO as an addition to the basic parameters. These parameters must align with the values specified in the device's ESI file.

ESI (EtherCAT SubDevice Information) file

The values used for SubDevice configuration must align with those specified in the device's ESI file.

You can locate the ESI file, which is an XML document, in the "DeviceDescription" folder.

The Device Info values are specified in the file AppECS_DemoApplication.c.

#define ECS_PRODUCTCODE                    0x0000003d
#define ECS_SECONDARY_VENDORID_HILSCHER    0xE0000044
#define ECS_REVISIONNUMBER                 0x00030005
#define DEV_GROUP_TYPE_INFO                "netX"
#define DEV_TYPE_INFO                      "NETX ECS V5 Host Example"
#define DEV_NAME_INFO                      "NETX ECS V5 Host Example"

The values must match those utilized in the ESI file.

Please note that each example comes with its own ESI file; however, all examples share the same product code and revision number. As a result, these files should not be intermingled when evaluating multiple examples. Only one ESI file should be added to a MainDevice for configuration during testing.

Process Data Values

The example illustrates the configuration of process data values, measured in bytes, for both input (from MainDevice to SubDevice) and output (from SubDevice to MainDevice) directions.

ptConfigReq->tData.tBasicCfg.ulProcessDataOutputSize = sizeof(ptEcsRsc->abAktorData); /**< Process Data Output Size from master view */

ptConfigReq->tData.tBasicCfg.ulProcessDataInputSize = sizeof(ptEcsRsc->abSensorData); /**< Process Data Input Size from master view */

The process data byte size for RxPdo (Output) and TxPdo (Input) must also be specified in the ESI file, matching the values indicated in the configuration request packet.

Start Sequence of EtherCAT SubDevice

The start sequence for the EtherCAT SubDevice involves the following steps:

Initialize
Configure Stack
Initialize Configuration
Start
Stack is in Init State

EtherCAT MainDevice

Once the EtherCAT SubDevice is successfully configured and the “Start Communication Request” / “Bus On” process is completed, the EtherCAT SubDevice enters the EtherCAT “Init State.”

The next step involves the EtherCAT MainDevice transitioning the EtherCAT SubDevice from the “Init” state to the “Operational” state (OP), as illustrated in the following state diagram:

Optional Configuration

To enhance the functionality of your application, you can optionally define HOST_APPLICATION_SETS_OEM_DATA in the AppECS_DemoApplication_Config.h file. This allows for the modification of manufacturer-specific (OEM) data.

The tool available at Tag List Editor is designed to adjust the parameters of the binary firmware for OEM-specific use cases.

To configure the EtherCAT SubDevice firmware, use the Tag List Editor to set the DDP (Device Data Provider) mode to "passive" at firmware startup. This configuration ensures that the firmware will wait for additional data to be provided by the application before initiating the process.

The firmware must be flashed onto the device using tools such as NetxStudio's flasher tool, followed by a device restart to apply the new firmware. At this point, the device will not automatically start up or activate the Ethernet PHYs; instead, it will wait for additional DDP data.

In the subsequent step, the example will utilize the function AppECS_SetOemData within AppECSSimpleDemo_Initialize to configure the DDP data with the necessary OEM values. This function employs the HIL_DDP_SERVICE_SET_REQ to transmit the OEM data to the EtherCAT SubDevice firmware.

Once this is completed, AppECS_ActivateDdp() is invoked to activate the data within the firmware. The DDP OEM parameters will override the values specified in the Configuration packet szOrderIdx (DEV_TYPE_INFO) from ECAT_SET_CONFIG_DEVICEINFO.

Using TwinCAT as MainDevice

To bring the SubDevice into Operational mode using TwinCAT as the MainDevice and configuration tool, please follow these steps:

Download and Install TwinCAT: Begin by downloading TwinCAT from the Beckhoff homepage. Install it for testing purposes.
Copy the ESI File: Locate the ESI file from the provided example and copy it to the folder where TwinCAT searches for ESI files. The typical directory is:
- C:\TwinCAT\3.1\Config\Io\EtherCAT
Start a New Project: Launch TwinCAT and create a new project.

By following these steps, you will successfully configure the SubDevice for operational use.

If you add your ESI file at a later time, be sure to use the 'Reload Configuration Files' option in TwinCAT. Failing to do so may prevent TwinCAT from locating your device, resulting in the creation of a temporary ESI file named 'OnlineDescriptionCache'. This file will only be visible in the ESI files folder after you close TwinCAT. This situation can be confusing, as TwinCAT prefers that you add your file without deleting it.

To add the network adapter, please ensure that TwinCAT installs the necessary protocols on it.

Next, right-click on 'Show Real-time Ethernet Compatible Devices...' to proceed.

Select a network adapter from the provided list and click the 'Install' button. For testing in free run mode, using an adapter marked as “not compatible” will suffice.

The adapter will be positioned above in the section labeled 'Installed and ready to use ...'

To connect your SubDevice to the running example of the MainDevice, follow these steps:

Scan the Network: Begin by scanning the network to identify available devices.

The device must be located and should remain in an operational state.

To send the data, you can assign a value to the RX-PDO (Receive from SubDevice view).

The example will increase the value and return it.

To capture network traffic traces using Wireshark, you need to enable Promiscuous Mode on the Main Device.

To apply your changes, simply click the 'reload' button.

Running the EtherCAT Conformance Test

Members of the ETG can utilize the Conformance Test Tool (CTT) to conduct tests, as detailed in the following link: https://www.ethercat.org/en/conformance.html.

The CTT proves to be invaluable during the development of the EtherCAT SubDevice, offering useful features such as the ability to view EEPROM data and export the object dictionary, among others.

After downloading and installing the CTT, users should select the ESI file from the designated folder. The same folder containing the ESI file from TwinCAT can also be used.

To add the network device, simply perform a right-click using your mouse.

Click on "Scan Slaves" to add your slave to the path.

Start the test

Unused test cases can be deleted; otherwise, they will be skipped.

Loadable firmware host examples

ECS V5 - Simple Configuration Example