Introduction

This guide offers step-by-step instructions on how to implement the EtherCAT Slave Stack on Linux, using either the Beckhoff FC1100 PCI card or the Beckhoff FC1121 PCIe card.

Architecture

To allow the Slave Stack direct access to the PCI(e) card, we will use the acontis kernel module, called atemsys. This enables direct access to the hardware from user space. The fc11xxhw_Linux.c file establishes the connection between the Slave Stack and atemsys.

Implementation

The atemsys kernel module functions are accessed through the LinkOsLayer. A complete implementation can be requested from acontis. The following steps demonstrate how to access the functions:

  1. Create a context.

    EC_T_VOID* pvLinkOsContext;
    EC_T_LINK_PARMS linkParms;SIZEOF(EXAMPLE_INPUT0x6001));

    dwRetVal = LinkOsCreateContext(&linkParms, &pvLinkOsContext);}

  2. Look up the PCI information with LinkOsGetPciInfo(). This function scans all PCI(e) devices to find one with the matching Vendor ID and Device ID. Depending on the card you are searching for, pass “1” to the function for the FC1100, or “2” for the FC1121.

    T_PCIINFO PciInfo;

    LinkOsGetPciInfo(pvLinkOsContext, &PciInfo, "FC11XX", 1);

  3. If a matching device is found, its memory will be automatically mapped. For the FC1100, the second memory window is mapped, and for the FC1121, the first window is mapped.

    EC_T_BYTE* pbyVirtAddr;

    LinkOsMapMemory(pvLinkOsContext, PciInfo.Window.memWindows[1].qwBase,
    PciInfo.Window.memWindows[1].dwLen);

  4. The mapped memory is assigned to the ESC memory pointer. For the FC1100, the ESC memory starts with the second memory window.

    pEsc = (MEM_ADDR ESCMEM *)pbyVirtAddr;

  5. On the other hand, the ESC memory of the FC1121 starts at an offset to the first memory window. This offset can be found in the function block. The function block is directly behind the info block at the start of the first memory window.

    pFuncBlockDesc = (FC1121_Func_Block_Desc*)&pbyVirtAddr[SIZEOF(FC1121_Info_Block)];

    pEsc = (MEM_ADDR ESCMEM *)&pbyVirtAddr[pFuncBlockDesc->dwOffset];

For more details, please refer to the datasheet.

Setup

For this walkthrough, we have a Linux system with the FC11xx connected to it. Additionally, a Windows system will be used to generate the Slave Stack source code and the ESI file using the Slave Stack Code Tool.

atemsys kernel module

As explained previously, the atemsys kernel module is required to access the PCI(e) card. For installation instructions, please refer to the atemsys Github. To verify whether the installation was successful, run the following commands on your Linux system:

lsmod | grep atemsys

This will print out atemsys if it is loaded as a kernel module.

lspci -v

This will show you a list of PCI(e) devices and information about them. atemsys should now be listed as the kernel driver in use below the entry for the FC11xx.

Slave Stack Code Tool

To create an ESI file and generate the source code, you will need to install the Slave Stack Code Tool. Open the tool and create a new project. Select “FC1100” under “Custom”. While this preset is intended for Windows, it will also work on Linux with a few modifications and our fc11xxhw_Linux.c driver implementation.

If you would like to create your own application instead of using the example, simply import your PD mapping under Tool -> Application -> Import/Create new. After importing you can name your application.

Important: Under “Compiler”, change the definitions of “UINT32” and “INT32” from (unsigned) long to (unsigned) int. This change is required because in Linux, a long is a 64 bit value, unlike in Windows where it is 32-bit value.

Also, ensure that the Vendor ID, Product Code, and Revision Number align with your PCI(e) card.

Now, export the project under Project -> Create new Slave Files. This will create the source files and the ESI file. Copy the all generated source files, except fc1100hw.c and the TcHelper files, into the src folder of the included SSC-Device-FC11xx project. Additionally, if you are using your own application, delete the sampleappl files as they will be replaced by your application.

You can write your slave application in the .c file with the same name you previously selected for your application. It is important to note that the return type of the main function in that file also needs to be changed from void to int.

Compilation

The SSC-Device-FC11xx project can now be transferred to your Linux system. Once there, navigate into it and run the following command:

make SSC_IN_DIFF_DIR=false

This will generate an executable named “fc11xx” in your current working directory.

Running the Application

To start the application, run the executable from inside the compilation folder:

./fc11xx

The slave can now be operated by an EtherCAT Master.

To verify that the slave is functioning, connect the IN port of the slave card to a dedicated EtherCAT port on the Windows system. In this example, we will use the acontis EtherCAT network configuration tool, known as EC-Engineer, which will act as an EtherCAT Master.

Add the ESI file in EC-Engineer under File -> ESI Manager and connect to the slave. If you are using the example application, the “Input” variable should rapidly count up if the Output is zero. Otherwise, it should be the value of the “Output” variable plus one.