EtherCAT.NET

EtherCAT.NET provides high-level abstraction of the underlying native Simple Open Source EtherCAT Master (SOEM). To accomplish this, the solution contains another project: SOEM.PInvoke. It comprises the actual native libraries for Windows and Linux and allows to simply P/Invoke into the native SOEM methods. The intention is to provide a managed way to access the native SOEM master. EtherCAT.NET depends on SOEM.PInvoke and adds classes for high-level abstraction.

In its current state, many, but not all planned features are implemented. Thus, only an alpha version is available (NuGet) up to now. This mainly means that any EtherCAT network can be configured and started, but high-level features like simple configuration of the SDOs are not yet implemented.

This master already supports slave configuration via ESI files. In fact, these files are required for the master to work. As shown in the sample, you need to point the configuration to the folder, where the ESI files live.

Another feature is the configuration of complex slaves. For example, this master has been sucessfully tested with the Profibus terminal (EL6731-0010). TwinCAT allows configuration of this terminal through a special configuration page. Since creating high-level configuration interfaces for each complex slave is much work, the priority for EtherCAT.NET lies on providing a simple interface to customize SDOs (like in TwinCAT), so that the end user can tune the required settings for any slave in a generic way.

Running the application

Linux: Run the application with root privileges as pointed out here.

Windows: Install WinPcap.

How to use EtherCAT.NET

If you start with the sample, make sure to adapt the interface name in Program.cs to that of your network adapter and to populate the ESI directory with the required ESI files. When you run the sample application, the output will be similar to the following:

Generate the list of slaves

The master can be operated without having a list of slaves. In that case, it scans available slaves during startup. But the disadvantage is that the slaves cannot be configured in advance and that no variable references are available. Therefore, there are two ways to generate the slave list as shown here:

1. Create the list manually (it must match with the actually connected slaves)

   --> not yet possible
   

2. Scan the list of connected slaves

   var rootSlave = EcUtilities.ScanDevices(<network interface name>);

The returned rootSlave is the master itself, which holds child slaves in its Children / Descendants property) After that, the found slaves should be populated with ESI information:

rootSlave.Descendants().ToList().ForEach(slave =>
{
    ExtensibilityHelper.CreateDynamicData(settings.EsiDirectoryPath, slave);
});
    

Accessing the slaves

This master works differently to TwinCAT in that the slaves are identified using the configure slave alias (CSA) field in the EEPROM (see section 2.3.1 of the Hardware Data Sheet Section II). Whenever the master finds a slave with CSA = 0 it assigns a new random number. This number can be acquired after the first run by printing the CSA of each slave:

var message = new StringBuilder();
var slaves = rootSlave.Descendants().ToList();

message.AppendLine($"Found {slaves.Count()} slaves:");

slaves.ForEach(current =>
{
    message.AppendLine($"{current.DynamicData.Name} (PDOs: {current.DynamicData.Pdos.Count} - CSA: { current.Csa })");
});

logger.LogInformation(message.ToString().TrimEnd());

Now, if the hardware slave order is changed, the individual slaves can be identified by:

var slaves = rootSlave.Descendants().ToList();
var EL1008 = slaves.FirstOrDefault(current => current.Csa == 3);

Of course, as long as the hardware setup does not change, you can always get a reference to a slave by simple indexing:

var EL1008 = slaves[1];

Accessing process data objects (PDOs) and variables

When you have a reference to a slave, the PDOs can be accessed via the DynamicData property:

var pdos = slaves[0].DynamicData.Pdos;
var channel0 = pdo[0];

Since a PDO is a group of variables, these can be found below the PDO:

var variables = pdo.Variables;
var variable0 = variables[0];

A variable holds a reference to a certain address in RAM. This address is found in the property variable0.DataPtr. During runtime (after configuration of the master), this address is set to a real RAM address. So the data can be manipulated using the unsafe keyword. Here we have a boolean variable, which is a single bit in EtherCAT, and it can be toggled with the following code:

unsafe
{
    var myVariableSpan = new Span<int>(variable0.DataPtr.ToPointer(), 1);
    myVariableSpan[0] ^= 1UL << variable0.BitOffset;
}

Be careful when using raw pointers, so that you do not modify data outside the array boundaries.

Running the master

First, an EcSettings object must be created. The constructor takes the parameters cycleFrequency, esiDirectoryPath and interfaceName. The first one specifies the cycle time of the master and is important for distributed clock configuration. The last one, interfaceName, is the name of your network adapter.

The esiDirectoryPath parameter contains a path to a folder containing the ESI files. For Beckhoff slaves, these can be downloaded here. The first startup may take a while since an ESI cache is built to speed-up subsequent starts. Whenever a new and unknown slave is added, this cache is rebuilt.

With the EcSettings object and a few more types (like ILogger, see the sample), the master can be put in operation using:

using (var master = new EcMaster(rootSlave, settings, extensionFactory, logger))
{
    master.Configure();

    while (true)
    {
        /* Here you can update your inputs and outputs. */
        master.UpdateIO(DateTime.UtcNow);
        /* Here you should let your master pause for a while, e.g. using Thread.Sleep or by simple spinning. */
    }
}

If you need a more sophisticated timer implementation, take a look to this one. It can be used as follows:

var interval = TimeSpan.FromMilliseconds(100);
var timeShift = TimeSpan.Zero;
var timer = new RtTimer();

using (var master = new EcMaster(settings, extensionFactory, logger))
{
    master.Configure(rootSlave);
    timer.Start(interval, timeShift, UpdateIO);

    void UpdateIO()
    {
        /* Here you can update your inputs and outputs. */
        master.UpdateIO(DateTime.UtcNow);
    }

    Console.ReadKey();
    timer.Stop();
}

Compiling the application

A single Powershell Core script is used for all platforms to initialize the solution. This simplifies CI builds - but requires Powershell Core to be available on the target system. If you don't want to install it, you can extract the information in the script and perform the steps manually.

Linux (tested on Ubuntu 18.04 x64)

You need the following tools:

• .NET Core 3.1
• PowerShell Core
• build-essential
• g++-multilib
• CMake

The solution can then be built as follows:

1. Execute the powershell script once within the root folder:

   pwsh ./init_solution.ps1
   

2. Run make everytime you make changes to the native code:

   make --directory ./artifacts/bin32
   make --directory ./artifacts/bin64
   

3. Run dotnet build everytime make changes to the managed code:

   dotnet build ./src/EtherCAT.NET/EtherCAT.NET.csproj
   

4. Find the resulting packages in ./artifacts/packages/*.

Windows

You need the following tools:

• .NET Core 3.1
• PowerShell Core
• Visual Studio 2019
• CMake

The solution can then be built as follows:

1. Execute the powershell script once within the root folder. If you don't want to install Powershell Core, you can adapt the script and replace $IsWindows with $true.

   ./init_solution.ps1
   

2. Run msbuild* everytime you make changes to the native code:

   msbuild ./artifacts/bin32/SOEM_wrapper/soem_wrapper.vcxproj /p:Configuration=Release
   msbuild ./artifacts/bin64/SOEM_wrapper/soem_wrapper.vcxproj /p:Configuration=Release
   

   (* use Visual Studio Developer Command Prompt if msbuild is not available in the PATH variable or compile using Visual Studio directly).
3. Run dotnet build everytime you make changes to the managed code:

   dotnet build ./src/EtherCAT.NET/EtherCAT.NET.csproj
   

4. Find the resulting packages in ./artifacts/packages/*.