ECS Synchronous Example (New Structure)

1 Example project

2 ECS Sources

Take the netXStudion to open the projcet. The ECS Sources in the ECS SimepleConfig Example are in the folder:

Components\cifXApplicationDemoECS_Simple

Get sure to choose the synchronized example and the correct usecase for your build

3 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

This example shows three different synchronized data exchange modes, depending on the used define that can be set in AppECS_DemoApplication_Config.h

3.1 SM2 sync via DPM (PDin) (No define set)

The demo part starts with the AppECSSimpleDemo_Initialize function (AppECS_DemoApplication.c). It initializes a memory pointer for the I/O data by using the xChannelPLCMemoryPtr function of the cifx Toolkit. Afterwards a packet handler for incomming packets is registerd. The function AppECSSimpleDemo_Setup sends the configuration request and also registers for ALControl indications to keep control of the devices state change when the master wants to switch it. In this example all state changes are allowed and not delayed by the function. So this function is not needed here, but it is needed in a real DC application where the application has to synchronize other components (e.g. its drive speed) before it switches to Operational. Afterwards the channel is initialized (App_SysPkt_AssembleChannelInitReq) which means to apply the configurtion data. Then the connection to the bus is switched on by App_SysPkt_AssembleStartStopCommReq.

Sync SM2 → AppECSSynchronousDemo_ReadDataFromNetwork ->
AppECSSynchronousDemo_ProcessData ->
AppECSSynchronousDemo_WriteDataToNetwork

3.2 Syncromized to DC Sync 0 → use define HOST_SYNC_DATA_TO_DC_SYNC0_SIGNAL

Difference to former variant is that the configration packet sets the Sync 0 signal as processdata in synchronisatoion source (ECAT_SET_CONFIG_SYNCMODES) instead of SM2. So it is necessary to activate the Sync 0 signal in the Master (DC tab in Twincat).

Sync Sync 0 → AppECSSynchronousDemo_ReadDataFromNetwork ->
AppECSSynchronousDemo_ProcessData ->
AppECSSynchronousDemo_WriteDataToNetwork

Twincat DC tab: Click o.k. and don´t forget to click the reload button for apply

3.3 Synchronized to DC Sync 0 + SM2 → use define HOST_HW_SYNC_DATA_PROCESS_TO_DC_SYNC0_SIGNAL

Difference to former variants. In this synchronisation mode, the hardware signal sync interrupt is activated in the AppECSSynchronousDemo_Initialize function.

The data is copied to the application with the SM2 event (like the example without define) using the cifX toolkit registration as in the other examples. Than it is processed with the Sync 0 interrupt (given to the outputs) and the produced data is latched (time synchronous to other devices) and immediately written to the bus. More accurate it is written to the Syncmanager which adds it to the next incomming frame. It is also necessary to activate the Sync 0 signal in the Master (DC tab in Twincat). The device will not go to OP otherwise because the firmware expects to see output data written minimum once.

AppECSSynchronousDemo_ReadDataFromNetwork
XCTRIGGER0_IRQHandler →AppECSSynchronousDemo_ProcessData ->
AppECSSynchronousDemo_WriteDataToNetwork

Twincat DC tab: Click o.k. and don´t forget to click the reload button for apply

4 Configuration packet

The ECS Configuration packet is in the file AppECS_DemoApplication.c

It includes the ECAT_SET_CONFIG_SYNCMODES as addition to the basic parameters for choosing the synchronisation mode.

5 Values from ESI file

DeviceInfo values:

#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 ESI file:

Each example comes with its own ESI file but all have the same product code and revicion number, so do not mix up them when testing.

Only use one ESI file at a time when adding to a master or config file folder.

Process Data Values:

Choose the number of Input and Output Bytes and tell this the stack in the configuration packet with

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 for RxPdo (Output) and TxPdo (Input) in the ESI file, like in the configuration packet

<Name>1. RxPDO</Name>

<Entry>

</Entry>

<Entry>

</Entry>

........

<Name>1. TxPDO</Name>

<Entry>

</Entry>

<Entry>

</Entry>

........

10 Byte Output

6 Byte Input

6 Start Sequenz

Intialize
Config Stack
Init Config
Start
Stack is in Init State

7 ECM Master

As soon as the ECS Stack is successfully configured and the “Start Communication Request” / “Bus On” is done, the EtherCAT Slave goes in Init State.

The EtherCAT Master now needs to bring the EtherCAT Slave from Init State to Operational State (OP).

8 Using TwinCAT as master

The following scrennshots give a shot introduction to bring the slave to Operational mode using TwinCAT as a master and configuration tool.

1st DownloadTwinCAT from the Beckhoff homepage and install. It is free to use for test purpose.

Than copy your ESI file from the example to the folder which Twincat uses to search for ESI files: C:\TwinCAT\3.1\Config\Io\EtherCAT

Than start TwinCAT and open a new project.

Hint: If you add your ESI file later, you must click 'Reload Configuration files' in TwinCAT. Otherwise TwinCAT will not find your device and create an own temporary ESI file called 'OnlineDescritionCache'. It can only be seen in the folder for ESI files if you close TwinCAT. This can be confusing because it is prefered by TwinCAT if you add your file and do not delete it.

or it may look like this:

Than you have to add a networkadapter (TwinCAT will install some protocols on it). Rightclick on the 'Show realtime Ethernet Compatible Devices...'

In the opening window choose a Networadapter from the list even if ther are no comaptible devices and click the 'Install' button. (Not compatible is mostly sufficent for testing in free run mode.)

The decice will be added above under 'Installed and ready to use ...'

Now you can connect your slave with the example running on it to the master.

Than go on scaning the network

The device shall be found and the master immediately tries to switch the slave to Operational mode. If you are still in SafeOP there is another adjustment needed (next step).

Depending on the example varaiant you are using (which define is set) the slave might not reach the operational state and returns to SafeOP state. This is because of missing data exchange. The data exchange function (interrupt) is not called when the slave does not receive a DC Sync 0 signal from the master. So you also need to activate using the DC for the slave by clicking the DC tab

Than click on reload for the values to apply.

Now the slave should go to Oparational state.

To send some data you can add a value to the RX-PDO (recive from slave view))

The example will increment the value and send it back or just mirror the data (here screenshot from simple example).

If you want to do wireshark traces you must activate the Promeiscous mode on the master device by setting the check mark.

Than cklick the 'reload' button to apply your changes.

Running a Conformance Test

To test DC slaves with the conformance test you need a Real-time Ethernet Port Multiplier from Beckhoff, like the CU2508!

As a member of the EtherCAT organisation you have to buy a licence for 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.

Connect the CU2508 to the network card of your PC running the test tool and plugg your device to the switch.

Choose the ESI file from the folder. (You might use/share the ESI file folder with TwinCAT's ESI folder). It must contain your ESI file and the ESI file of the CU2508.

Schan the network (click on right mouse button over EtherCATDevices). The first two devices shall be found. Click thesecond one which is the port where your device is connected.

Activate the DC mode for Test

Start the test (Unused Testcases can be deteted)

Test run shows 4 errors.

First two errors in the screenshot can easyily fixed. First error (TF-1300) is because Hilscher uses a secondary vendor ID (starts with 0xE..), the second erro in same TF is caused by of a wrong order number (shall not happen in the delivered example).
The two errors in TF-2301 are serious and have to be resoved to meet the conformance requirements. The tool reports missing objects 0x1C32, 0x1C33. Those objects still have to be added by the user application. They are mandatory if you are using a DC mode and among other things used to switch the DC mode (e.g. to freerun or SM-Sync) of the slave if it supports different modes.

Because this example only focuses on the configuration of the Synchronited modes adding the objects 0x1C32, 0x1C33 is not included. For implementing objects refer to the Example variant Custom OD.