2 ECS Sources
...
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
...
Get sure to choose the simple example and the correct usecase for your build
...
The active target for the netX90 use case can be selected as illustrated in the image below:
...
Overview of the example structure
The examples consist of a general part which is the same for all differnent examples. It initializes the toolkit sets up the Channels etc. The related code is mainly in the folder Components\ApplicationDemo and in the Targets folder. It is not described here but can be found under Common general part for all examples
The simple demo part starts (AppECS_DemoApplication.c) with initializing a packet handler (AppECSSimpleDemo_Initialize) for incomming packets. Actually only 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 sends is responsible for preparing and sending the configuration request and afterwards the to the EtherCAT SubDevice firmware. Following this, the communication channel is initialized (App_SysPkt_AssembleChannelInitReq) which means to apply the configurtion data. Then the connection to the bus is switched on by .
Additionally, the communication state of the device on the network can be modified using the function App_SysPkt_AssembleStartStopCommReq.
...
Configuration Request packet
The ECS EtherCAT SubDevice Configuration Request packet is in constructed within the file AppECS_DemoApplication.c
...
It includes the , as detailed below:
| Code Block | ||||
|---|---|---|---|---|
| ||||
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, which retalte to the ESI file
5 Values from ESI file
...
DeviceInfo values:
#define ECS_PRODUCTCODE 0x0000003d
#define 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.
| Code Block | ||
|---|---|---|
| ||
#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" |
need to be same like in The values must match those utilized in the ESI file:.
...
Please note that each example comes with its own ESI file but all have ; however, all examples share the same product code and revicion revision number, so do not mix up them when testing.Only use one file at a time when adding to a master or config file folder. 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
...
Choose The example illustrates the number of Input and Output Bytes and tell this the stack in the configuration packet withconfiguration of process data values, measured in bytes, for both input (from MainDevice to SubDevice) and output (from SubDevice to MainDevice) directions.
| Code Block | ||||
|---|---|---|---|---|
| ||||
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 */ |
Change the number of Bytes The process data byte size for RxPdo (Output) and TxPdo (Input) must also be specified in the ESI file, like matching the values indicated in the configuration request packet.
| Code Block | ||
|---|---|---|
| ||
<RxPdo Sm="2"> |
...
<Index>#x1600</Index> |
...
<Name>1. RxPDO</Name> |
...
<Entry> |
...
<Index>#x2000</Index> |
...
<SubIndex>1</SubIndex> |
...
<BitLen>8</BitLen> |
...
<Name>1 Byte Out (0)</Name> |
...
<DataType>BYTE</DataType> |
...
</Entry> |
...
...
<Entry> <Index>#x2000</Index> |
...
<SubIndex>2</SubIndex> |
...
<BitLen>8</BitLen> |
...
<Name>1 Byte Out (1)</Name> |
...
<DataType>BYTE</DataType> |
...
</Entry> |
...
........ |
| Code Block | ||
|---|---|---|
| ||
<TxPdo Sm="3"> |
<Index>#x1A00</Index> |
<Name>1. TxPDO</Name> |
<Entry> |
<Index>#x3000</Index> |
<SubIndex>1</SubIndex> |
<BitLen>8</BitLen> |
<Name>1 Byte In (0)</Name> |
<DataType>BYTE</DataType> |
</Entry> |
<Entry> |
<Index>#x3000</Index> |
<SubIndex>2</SubIndex> |
<BitLen>8</BitLen> |
<Name>1 Byte In (1)</Name> |
<DataType>BYTE</DataType> |
</Entry> |
........ |
Example ESI file:
10 Byte Output
6 Byte Input
...
Start Sequence of EtherCAT SubDevice
The start sequence for the EtherCAT SubDevice involves the following steps:
Initialize
Config Configure StackInit Config
Initialize Configuration
Start
Stack is in Init State
6 ECM Master
...
EtherCAT MainDevice
Once the EtherCAT SubDevice is successfully configured and the “Start Communication Request” / “Bus On” process is donecompleted, the EtherCAT Slave goes in Init SubDevice enters the EtherCAT “Init State.”
The EtherCAT Master now needs to bring next step involves the EtherCAT MainDevice transitioning the EtherCAT Slave from Init State to Operational State SubDevice from the “Init” state to the “Operational” state (OP).
7 Optional Configuration
As an extension to this simple example you can optionally set the , 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
To use it you have to change an entry of the firmware´s taglist.
At first set the taglist entry 'DDP mode ..' to passive by using the Tag List Editor Tool from hilscher and save the firmware
...
Than flash it to the device by e.g. using NetxStudio's flasher tool and restart the device to apply the firmware. Now the device will not activate the phys.
In second step you download the firmware with the define HOST_APPLICATION_SETS_OEM_DATA compiled in.
Now the function AppECS_SetOemData in the AppECSSimpleDemo_Initialize function is called. This function uses file. This allows for the modification of manufacturer-specific (OEM) data.
The tool available at https://hilscher.atlassian.net/wiki/spaces/TLE/overview 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 to send transmit the OEM data to the device. Afterwards EtherCAT SubDevice firmware.
Once this is completed, AppECS_ActivateDdp() is called invoked to activate the data in within the firmware. The DDP OEM parameters overwrite one value which is also set 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 a master the MainDevice and configuration tool.1st DownloadTwinCAT , 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.
Hint: By following these steps, you will successfully configure the SubDevice for operational use.
| Info |
|---|
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. |
...
...
or it may look like this:
...
Than you have to add a networkadapter (TwinCAT will install some 
To add the network adapter, please ensure that TwinCAT installs the necessary protocols on it). Rightclick on the 'Show realtime .
Next, right-click on 'Show Real-time Ethernet Compatible Devices...' to proceed.
...
Select a network adapter from the provided list even if ther are no comaptible devices and click the 'Install' button. (Not compatible is mostly sufficent for For testing in free run mode.), using an adapter marked as “not compatible” will suffice.
The decice adapter will be added above under positioned above in the section labeled 'Installed and ready to use ...'
...
Now you can To connect your slave with SubDevice to the running example running on it to the master.Than go on scaning the networkof the MainDevice, follow these steps:
Scan the Network: Begin by scanning the network to identify available devices.
...
The device shall must be found located and should still be in Operationalremain in an operational state.
...
To send the data, you can add assign a value to the RX-PDO (recive Receive from slave SubDevice view)).
...
The example will increment increase the value and send return it back.
...
If you want to do wireshark traces you must activate the Promeiscous mode on the master device by setting the check mark.
...
Than cklick 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 to apply your changes.
...
Running
...
the EtherCAT Conformance Test
As a member of the EtherCAT organisation you have to buy a licence for Members of the ETG can utilize the Conformance Test Tool .
The tool is also verry helpful when you are devepolling your slave. You might want to look at the EEPROM or export the objectdictionary or other things which it is usefull.
Download the Conformance Test Tool, install it, add the license file and start it.
Choose (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. (You might use/share The same folder containing the ESI file folder with TwinCAT's ESI folder)from TwinCAT can also be used.
...
Add To add the network device with , simply perform a right-click on right using your mouse button.
...
Click on "Scan Slaves" to add your slave to the path.
Start the test
...
Unused Testcases test cases can be deteteddeleted; otherwise, is not they are will be skipped.
...