EtherCAT Master Stack demo on STM32MP2 (STM32MP257x-EV1 board)
Architecture and platform integration
This diagram illustrates the integration of the icECAT EtherCAT Master Stack on the STM32MP2 as supported by the demo software.
The STM32MP257x-EV1 runs an OpenSTLinux with real-time extension more info.
It interfaces with the Ethernet MAC (GMAC) via the icNET Optimized Link Layer driver.
The built-in icECAT EtherCAT Configuration Library allows online configuration, based on ESI information, either provided in an ESI repository folder or dynamically retrieved from the SubDevices’ SII (Slave Information Interface).
The icECAT Master Monitor is linked to the MainDevice application and accessible via console.
The MainDevice application is run as real-time application.
Additional features in the release version:
ENI can be linked static to the MainDevice application
EtherCAT features, disabled for the demo:
Hot-Connect
EoE
FoE
Cable Redundancy
SDO Info Service
Support for read and write of Explicit Device Identification
Mailbox Gateway and Master object dictionary
Prerequisites
To run the icECAT EtherCAT Master Stack demo, you will need:
STM32MP257F-EV1 Evaluation board
1x micro SD card (min. 8 Gbit)
1x USB-C Cable
5V/3A Barrel Jack Power Supply (optional)
2x Ethernet cables
Software to flash a SD-Card (e.g. rufus or dd)
Software for a terminal via USB (e.g. teraterm or putty)
One or more EtherCAT SubDevices, optionally with ESI files
Prebuild SD-Card image with Linux and ibv kernel module (linux-image-stm32mp257f-ev1-v25.06.11.zip)
icECAT EtherCAT Master demo software for STM32MP2 on TM32MP257x-EV1 board
Demo setup
Hardware setup
The following figure illustrates the hardware setup.
Follow these steps for the hardware setup:
Configure Power Source Depending on whether the board is powered by USB-C or Barrel Jack (expects 5V/3A), the jumper next to the Power input (JP4) must be set:
Pin 1+2: USB-C Power.
Pin 2+3: Barrel Jack.
Connect ETH2 to the EtherCAT Network (Yellow)
Connect ETH1 to the Ethernet Network (optional but recommended)
Connect USB (Black) and optional USB DRD (Red) to the PC
optional connect Barrel Jack power chord next to the black USB cable
Linux Image
The Demo is provided with a pre build SD-Card image (linux-image-stm32mp257f-ev1-v25.06.11.zip) the image contains a Linux
The SD-Card image has the following extension towards the default image:
build in ibv-dweqos kernel module (optimized link layer kernel module for Designware QBV Mac)
added development tools (gdb, gdbserver)
basic tools (ifconfig, nano, git, rsync)
We recommended for demo to start with the SD-Card image provided.
The default image can not be used, as the demo is depending on the ibv-dweqos kernel module. The sources for the kernel module are provided within the demo package.
A Guide on integration of the kernel module into yocto can be requested and is part of the EVAL and release package.
Flashing the hardware
The SD-Card image needs to be flashed on the SD-Card:
Windows: we recommended rufus to flash the image
Linux: unpack the zip and use dd
Running the image
Open the terminal program and connect it to the STM
Make sure the Boot switches are correctly set:
0: closed
1: open
2: open
3: open
Insert the SD-Card into the eval board
Powerup the board
the user name is “root” without a password
Bind the ibv kernel module
The demo uses the ibv-dweqos kernel module underneath. The kernel module is build into the kernel (on the provided SD-Card). The image binds both Ethernet interface to the Linux standard drive by default. Use the following commandline to bind the kernel module and probe the ethernet device
$ echo "482d0000.eth2" > /sys/bus/platform/devices/482d0000.eth2/driver/unbind
$ echo "482d0000.eth2" > /sys/bus/platform/drivers/dweqos/bind
Setting an IP address
Inside the terminal:
$ ifconfig eth0 172.26.52.47/16
Starting the demo
connect to the linux using a ssh terminal (e.g. Putty)
copy the binary ecatm-demo-appl from the icECAT Master Demo software package to the target
e.g: via winscp or scp
start the EtherCAT Master Stack demo:
chrt 60 is required to ensure that the application is running with realtime (higher than the Linux IRQ threads)
Note
The demo package contains to demo binaries one with TTS support and one without Regarding TTS (Time triggered send) please refer to Starting the demo with TTS
$ chrt 60 ./ecatm-demo-appl
the terminal should display:
$ chrt 60 ./ecatm-demo-appl
__ ________ ______ ______ ________
....... <<<<<<< / | / | / \ / \ / |
: ------- <<<<< ##/ _______ ########/ /###### |/###### |########/
: / ....... <<< / | / |## |__ ## | ##/ ## |__## | ## |
: / :....... <<<<< ## |/#######/ ## | ## | ## ## | ## |
: | :: <<<<<<< ## |## | #####/ ## | __ ######## | ## |
: | :: :: | : ## |## \_____ ## |_____ ## \__/ |## | ## | ## | __
: \ ::......:: / : ## |## |## |## ##/ ## | ## | ## | / |
: \ :......: / : ##/ #######/ ########/ ######/ ##/ ##/ ##/ ##/
: -------- :
........ EtherCAT Master Stack for Embedded Systems
Limited Demo Version >...<
Copyright (c) by IBV - Echtzeit- und Embedded GmbH & Co. KG
https://www.ibv-augsburg.de/icecat
This is a demo application for the
icECAT EtherCAT Master Stack for Embedded Systems
The EtherCAT MainDevice software is designed for use on
microcontrollers, microprocessors and PC systems
> Optimal performance
> Small footprint
> Project based source code license, royalty free
> Press ENTER to continue...
After initialization, the system prompts for setting up the configuration:
Network setup: Choose between a physical EtherCAT network or the icECAT EtherCAT Network Simulation library.
EtherCAT network configuration: Scan the network or use the pre-configured eni.xml.
Cycle time configuration
Output options: icECAT Master Monitor, performance monitor, or extended logging
For an initial test, select 0 for all options.
The MainDevice demo then starts. The terminal should display:
=== init EtherCAT master
=== create link layer driver options ><)
-[COPYRIGHT]-------------------------------------------------------------------
(C) IBV - Echtzeit- und Embedded GmbH & Co. KG
https://www.ibv-augsburg.de/icecat
-[PRODUCT]---------------------------------------------------------------------
icECAT - EtherCAT Master Stack
Version: 1.12...
-[SYSTEM]----------------------------------------------------------------------
Operating System: ...
Target Architecture: ...
Link Layer Driver[0]: ...
-[DEMO-VERSION]----------------------------------------------------------------
!! USE ONLY FOR DEMONSTRATION PURPOSES !!
!! FOR USE IN PRODUCTION SYSTEMS, A COMMERCIAL LICENSE IS NECESSARY. !!
-------------------------------------------------------------------------------
=== create linked monitor
=== create icECAT Configuration Library instance
-[COPYRIGHT]-------------------------------------------------------------------
(C) IBV - Echtzeit- und Embedded GmbH & Co. KG
https://www.ibv-augsburg.de/icecat
-[PRODUCT]---------------------------------------------------------------------
icECAT - EtherCAT Configuration Library/Tool
Version: 1.16...
-[SYSTEM]----------------------------------------------------------------------
Operating System: ...
Target Architecture: ...
-[DEMO-VERSION]----------------------------------------------------------------
!! USE ONLY FOR DEMONSTRATION PURPOSES !!
!! FOR USE IN PRODUCTION SYSTEMS, A COMMERCIAL LICENSE IS NECESSARY. !!
-------------------------------------------------------------------------------
Open ESI repository:/sd0/esirepo repoindex:/sd0/repoindex.ini
=== run main loop
=== activate master
=== Request startup state:8
Afterwards the MainDevice tries to setup the network to OPERATIONAL state. If successful, the ACTIVITY LED on your EtherCAT SubDevice(s) should blink and the RUN LED should be on. If the setup fails, restart the demo and enable extended logging for troubleshooting.
Furthermore, the icECAT Master monitor is shown on top of the log output in blue color. The selectable screens and their hotkeys are listed.
EtherCAT MainDevice demo application
The MainDevice demo application can be used to control the EtherCAT MainDevice stack with help of the icECAT Master Monitor tool. In the release version, a programming API is provided to control the network, access the process data, etc.
EtherCAT network configuration
If no ENI (EtherCAT Network Information) file is provided, the application automatically scans the network for connected EtherCAT SubDevices. It retrieves the ESI (EtherCAT Slave Information) data from the SII (SubDevice Information Interface) repository or, if unavailable, reads the SII data from the SubDevice’s EEPROM.
An ENI is generated using the integrated icECAT Configuration Library, stored in RAM and linked to the MainDevice stack. This configuration defines the network topology, the initialization for the process variables, and the structure of the cyclic frames.
Here is a sample of the related output:
Start network scan...
Network scan done. Found 3 devices.
List of devices found in network scan:
dev#-1 prod=0x00000000 rev=0x00000000 <icECAT EVAL Master > type=
dev#00 prod=0x044C2C52 rev=0x00120000 <EVAL Slave 01 () > type=
dev#01 prod=0x07113052 rev=0x00110000 <EVAL Slave 02 () > type=
dev#02 prod=0x0AF93052 rev=0x00120000 <EVAL Slave 03 () > type=
ESI not available for all devices => use online SII as fallback
Start SII reading ...
SII read done: (4)
Generate basic ENI
lib-ecatmcfg EVENT >00h00m01.176 INFO EMCFG_EVTC_ENI_PROCESS_START: Processing ENI ... <
lib-ecatmcfg EVENT >00h00m01.184 INFO EMCFG_EVTC_ENI_PROCESS_END: Processing ENI finished. <
List of devices found in network scan:
dev#-1 prod=0x00000000 rev=0x00000000 <icECAT EVAL Master > type=
dev#00 prod=0x044C2C52 rev=0x00120000 <EVAL Slave 01 (EK1100) > type=EK1100
dev#01 prod=0x07113052 rev=0x00110000 <EVAL Slave 02 (EL1809) > type=EL1809
dev#02 prod=0x0AF93052 rev=0x00120000 <EVAL Slave 03 (EL2809) > type=EL2809
Request linking of network scan ENI
use ENI from network scan
create cyclic task (cycidx=0; prio=1; cyctime:1000us)
=== run cyclic task (cycidx=0, cyctime:1000 us)
=== activate master
=== Request startup state:8
EtherCAT Network Configuration with an external configuration tool
As an alternative to an automatic online configuration, an ENI can be generated
with an external tool and provided to the stack as XML file (eni.xml).
IBV provides the icECAT EtherCAT Configuration Library with a GUI tool for generating a network configuration. Ask IBV for an evaluation version. As alternative, you could use Beckhoff TwinCAT 3 to generate an ENI.
EtherCAT network state
Enter the EtherCAT network screen by pressing SHIFT+N in the monitor.
In this screen, the states of the MainDevice and of all SubDevices are shown. Select the device with the UP/DOWN keys and start a state transition with one of the keys i / b / p / s / o as indicated on the bottom status line.
If the SubDevice reports a problem, the AL_STATUS code is shown in column ALCODE.
Loading of an ENI file can be initiated by pressing “l” (small “L”) . By typing “scan” as ENI file name, an online network scan is triggered.
PDO access (process variables)
Enter the screen with I/O variables (PDOs) by pressing SHIFT+I in the monitor.
In this screen, select the process variables with the UP/DOWN keys. The current value is shown on the right side.
If an output value is selected, it can be modified by pressing ENTER and by
entering the new value as decimal number or as hexadecimal number with 0x
as prefix.
When working with a CiA402 drive, the CiA402 state machine can be controlled by writing the CONTROL WORD and inspecting the STATUS WORD.
SDO upload and download
A SubDevice related screen can be entered by selecting the SubDevice in the network screen and pressing ENTER. The LEFT / RIGHT keys select the previous or the next SubDevice.
If the selected SubDevice supports the CoE mailbox protocol
you can read (=upload) SDOs by pressing “u” and entering the SDO index and subindex,
e.g. 0x1008:0
If the SDO is writable, you can press “d” and enter the SDO index and subindex. Afterwards the value can be entered as hex bytes in little endian format.
ESC register access
The registers of the ESC (EtherCAT SubDevice Controller) of a SubDevice can be inspected by selecting the device the network screen and pressing SHIFT+R.
Scroll in the ESC register list with the UP/DOWN keys. By pressing ENTER, you can enter a new value to be written to the register. Example: Writing to the AL Control register (0x0120) will modify the application layer state of a SubDevice.
Diagnostic information
A screen with MainDevice related statistics and diagnostic information can be entered by pressing SHIFT+M.
In the middle, of the screen DC (Distributed Clocks) timing statistics are shown. For a reliable operation in DC mode, the counter missed shall be 0.
In the lower part, statistic counters of the Ethernet link layer driver are shown.
Performance monitor
The MainDevice demo application contains a built-in performance monitor. It can be activated when starting the demo. The performance monitor shows live values as well as min/max values of the EtherCAT timing as soon as the MainDevice enters the OPERATIONAL state:
Performance values for the platform STM32MP2 on TM32MP257x-EV1 board
The values in the table at the bottom of the screen are:
CRX: Time for receiving (getting and evaluating) the response frame from the last cycle
CPRC: Time for processing the data on application level (0 in demo application)
CTX: Time for transmitting (passing the frame to the Ethernet controller for transmission)
CTOT: Total operation time in cyclic task for one cycle
ATOT: Total operation time in acyclic task for one cycle
CTJ: Latency/jitter of the cyclic timer. This value is related to the hardware / RTOS performance and results in a frame jitter (CFJ) in the same range.
CFJ: Jitter of the cyclic frame measured with the clock of the DC reference slave. If this min/max value is out of the bandwidth shown in the Performance Monitor screen, then the SubDevices did not get updated information for the next cycle in time.
Starting the demo with TTS
The demo also contains a binary with and without TTS support.
The TTS feature uses the possibility of the Ethernet MAC to send frames scheduled by hardware instead of software based on a high precision timer. This ensure frames are send with jitter ~160ns.
The usage of the demo is basically the same as for the demo with out Starting the demo.
The TTS demo comes with the restriction that it does not support the network simulator, as the network simulator is not able to simulate the TTS behavior.
The performance monitor below shows the huge benefit of TTS.
The CFJ is reduced and compensates the jitter of the Linux operation system CTJ.
The impact of the DC control loop is no higher than frame send jitter.
EtherCAT network simulation
The MainDevice demo application contains the icECAT EtherCAT Network Simulation Library. This component simulates an EtherCAT network to a certain extent that the MainDevice stack is able to setup the network. On API level, the behavior for input/output variables could be simulated in a custom application. This could be used to develop a MainDevice control application without requiring a physical network of SubDevices. The simulation of I/O values is not supported by this demo application.
The built-in icECAT EtherCAT Network Simulation Libray can be used if no physical EtherCAT SubDevices are available. This requires an ENI file to define the simulated network topology. Select the network simulation option in the setup screen when starting the demo.
Note
Not all features of the icECAT EtherCAT Master Stack are supported by the network simulation.
Full-featured software
A full-featured evaluation version of the icECAT EtherCAT Master Stack and the icECAT EtherCAT Configuration Library is available upon request.