Getting Started with EtherCAT® Using EC-Master on STM32MP135F-DK by STMicroelectronics
Introduction
Acontis EC-Master Software supports the ARM Cortex-A7 chip as used on the STM32MP135F-DK Board from STMicroelectronics (ST). The implementation is running in the OpenSTLinux Linux distribution provided by ST, and support is available for both the included Linux Network Driver and the acontis optimized Real-time Driver. The standard Linux Network Driver is a reliable, fully-featured Ethernet driver available for most Linux distributions that allows for the easy installation of the EC-Master without any need for any adaptation to the Linux distribution and kernel. This makes EC-Master possible to run "out of the box." The acontis Real-time Driver is also an option for EC-Master and can significantly improve performance and latency, however its installation requires a special build of the Linux kernel that includes the acontis open source kernel module atemsys. This architecture provides a faster execution of the frames through the Ethernet controller into the main EC-Master stack, as well as a lower latency and more deterministic jitter in overall network communications. The acontis Real-time Driver is a reliable, robust solution ideal for applications requiring high-performance real-time communication.
System Architecture
Due to the smart architecture of the EC-Master stack and our in-house expertise with hardware drivers, it is a straightforward and simple process to get started and implement EC-Master on the STM32MP135F-DK development board. The diagram below shows the overall system architecture to get started with building the network configuration (ENI) using EC-Engineer, exporting the ENI file to the target hardware running the master (in this case the STM32 dev board), and the application that will be developed and integrated with the EC-Master Application Programming Interface (API).
Download
If you are interested in testing out an EtherCAT master implementation on the STM32MP135F-DK board yourself, please contact us for more information or request a free evaluation version of EC-Master. With this you can reproduce the measurements we made on your own system, and get started with your own application development. The steps to do this are described below.
First Step
We recommend the OpenSTLinux distribution from ST as with this EC-Master will work out-of-the-box. The first step is to download and install the OpenSTLinux distribution. You can use the STM32CubeProgrammer and install the OpenSTLinux distribution on an SD-Card. For further instructions about how to setup the OpenSTLinux distribution on the STM32MP135F-DK you can read the STM32MP135F-DK wiki or watch the Getting Started video on our YouTube channel. (Link zum YouTube Video kommt noch).
Architecture 1: Using the standard Linux network driver
The EC-Master stack communicates with the devices on the network by sending and receiving EtherCAT frames utilizing a standard Ethernet Media Access Controller (MAC). Through the use of Linux network drivers included with the Linux distribution, the Master stack can access the necessary information from the Ethernet controller, and send and receive EtherCAT frames via a raw socket interface called SOCK_RAW. However, due to the inclusion of the Linux network stack and Linux drivers, performance will be limited and not possible to maintain real-time constraints. To overcome this limitation the network drivers must be optimized for high performance cyclical operations, which we offer in our optimized Real-time driver in the Architecture 2 implementation below.
Since the raw socket interface is typically available in most Linux distributions’ kernels, the pre-compiled example application included with EC-Master (EcMasterDemo) supports SOCK_RAW and can therefore be used for evaluation of the EC-Master library‘s general functionality without compiling any files for the host system.
If the application requires it, and especially for certain slave devices like those that implement and utilize Distributed Clocks, real-time constraints must be kept. In this case the raw socket option is most likely not able to send and receive frames deterministically enough and the EtherCAT devices will not operate correctly. Therefore, SOCK_RAW should only be used for initial evaluation purposes and should be replaced with the acontis Real-time Driver as explained below.
For the ST dev board we are using that has an ARM Cortex-A7 processor, it is necessary to use the EC-Master-armv6-vfp-eabihf evaluation package and the demo included from that (EcMasterDemo). Consequently, you can start the pre-compiled binary example application of the EcMasterDemo with the following command line:
./EcMasterDemo -sockraw eth1 1 -b 4000 -t 20000 -v 3
The –sockraw command takes 2 arguments, the first is the name of the network device to be used for EtherCAT communications, and the second is to specify the mode of operation which can be either polling or interrupt. In our case we specify the first network adapter instance (eth1), and for the mode we use polling mode (1). The complete list of available command line parameters and associated arguments can be checked with the –help argument (excerpt shown below), and is also in our online documentation.
-sockraw Link layer = raw socket
Device network device (e.g. eth1)
Mode Interrupt (0) or Polling (1) mode
--nommaprx disable PACKET_MMAP for receive
After we specify the Ethernet adapter to be used and the mode, we then set the EtherCAT network cycle time to 4 milliseconds (-b 4000), the example application duration time to 20 seconds (-t 20000), and the logging verbosity level to 3 (-v 3) so that we can see some helpful output. Additionally, it is possible to use EC-Engineer connected to the target controller remotely via TCP for useful debugging and to execute some custom tests. If you want to enable this then you can add the –sp command line argument which will enable the included Remote Access Service (RAS) inside EC-Master so that EC-Engineer can connect. Finally, the –f Command Line Argument is used to pass the ENI file to the master.
Architecture 2: Using the optimized real-time Ethernet driver from acontis
The acontis Real-time Driver is an Ethernet network adapter driver for real-time EtherCAT usage. This driver, which runs in user space, allows direct access to the MAC and provides high performance, deterministic, cyclic operation. To use the driver a Linux kernel module called atemsys must be compiled to match the Linux kernel in use. Linux distributions typically provide methods for compiling kernel modules. acontis also provides a Yocto build recipe for which makes the the process easier.
The acontis Real-time Driver offers significant advantages to developers by providing a high-performance way to communicate data between user space applications and the physical Ethernet controller. The driver is necessary when real-time constraints must be maintained and high-speed communication is required, as it bypasses the Linux network stack and takes full advantage of the MAC hardware. In order to use the driver, the atemsys kernel module must be loaded on the Linux target and the standard Linux network driver must be removed from the system. This can be done by unbinding the instance using the virtual sysfs, or by modifying the Linux Device Tree, depending on the type of system being used. Once the driver is installed and running, data can be sent and received quickly and reliably, allowing developers to maximize application performance and minimize latency.
The atemsys kernel module is included with EC-Master and is updated in parallel with EC-Master. For the ST dev board we are using that has an ARM Cortex-A7 processor, it is necessary to use the EC-Master-armv6-vfp-eabihf evaluation package and the demo included from that (EcMasterDemo). Consequently, you can start the pre-compiled binary example application of the EcMasterDemo with the following command line:
./EcMasterDemo -dw3504 1 1 custom stm32mp135 osdriver 0 -b 1000 -t 20000 -perf -v 3
The –dw3504 command indicates the use of the acontis Real-time Driver specific to the Ethernet controller used by the ST dev board, and takes 2 arguments. The first is the network device instance for either emac0 (1) or emac1 (2), and the second is to specify the mode of operation which can be either polling or interrupt. In our case we specify the first instance (1) for emac0, and for the mode we use polling mode (1). The complete list of available command line parameters and associated arguments can be checked with the –help argument (excerpt shown below), and is also in our online documentation.
-dw3504 Link layer = Synopsys DesignWare 3504-0 Universal 10/100/1000 Ethernet MAC (DW3504)
Instance Device instance 1 for emac0, 2 for emac1
Mode Interrupt (0) or Polling (1) mode
After we specify the network device instance and the mode, we then set the EtherCAT network cycle time to 1 millisecond (-t 1000), the example application duration time to 20 seconds (-t 20000), and the logging verbosity level to 3 (-v 3) so that we can see some helpful output. Additionally, it is possible to use EC-Engineer connected to the target controller remotely via TCP for useful debugging and to execute some custom tests. If you want to enable this then you can add the –sp command line argument which will enable the included Remote Access Service (RAS) inside EC-Master so that EC-Engineer can connect. Finally, the –f Command Line Argument is used to pass the ENI file to the master.
Conclusion
With the provided information above you can hopefully see how easy it is to setup and get started with EtherCAT using EC-Master on the STM32MP135F-DK. You can get started right away with everything included out-of-the-box by using the Linux Network Driver. For better performance the acontis Real-time Driver should be used, and in order to use this there a few kernel adjustments to be made with the acontis kernel module (atemsys). However, this driver can provide developers with a high-performance way to send and receive data between user space applications and the physical Ethernet controller. The driver is necessary when high-speed communication is required as it bypasses the Linux network stack and takes full advantage of the MAC hardware. This can be incredibly useful when it comes to high-speed communication as it eliminates the need for any bloated network stacks and provides a much more efficient and reliable way of exchanging data. Once the adjustments are made, the acontis Real-time Driver and the example application EcMasterDemo will work in perfect harmony and provide a powerful and reliable way of getting the most out of your system and EtherCAT implementation.
We hope this article helps in making the decision for what architecture to use in which scenario. And the provided information and examples should allow for an easy reproduction on any hardware, architecture, or Linux distribution with the desired network configuration.