EtherCAT Master Stack demo on STM32H753 (NUCLEO-H753ZI board)

Architecture and platform integration

This diagram illustrates the integration of the icECAT EtherCAT Master Stack on the STM32H753 as supported by the demo software.

icECAT EtherCAT Master Stack on |tgt_system|

The icECAT EtherCAT Master Stack runs on an Arm Cortex-M7 core based on FreeRTOS.
It interfaces with the Ethernet MAC (ETH) via the icNET Optimized Link Layer driver.
The built-in icECAT EtherCAT Configuration Library allows online configuration, based on ESI information, dynamically retrieved from the SubDevices’ SII (Slave Information Interface).
The icECAT Master Monitor is linked to the MainDevice application and accessible via UART over a serial terminal.
The MainDevice application is built on the STM32Cube MCU Package for STM32H7 series v1.12.1.

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:

A STM32 Nucleo-144 development board with STM32H753ZI MCU (STM32 NUCLEO-H753ZI).
A micro USB cable
An Ethernet cable
One or more EtherCAT SubDevices, optionally with ESI files
icECAT EtherCAT Master demo software for STM32 Nucleo-H753ZI

Request DEMO SOFTWARE PACKAGE

Demo setup

Hardware setup

The following figure illustrates the hardware setup.

|tgt_system| - |tgt_board| setup for EtherCAT MainDevice demo

Follow these steps for the hardware setup:

Check the JP2 (5 V): “STLINK”, CLOSED (default)
Check JP4, STM32H7 is powered: “IDD”, CLOSED (default)
Check JP5 (1.8 V/3.3 V): 1-2: VDD_MCU=3.3 V (default)
Power the board by connecting the STM32H7 Nucleo-144 board to a PC with a USB Type-A to Micro-B cable through the USB connector CN1 on the ST-LINK.
Connect ETHERNET RJ45 CN14 to your EtherCAT network.
On your PC, STMicroelectronics STLink Virtual COM Port will appear. To find the correct COM port on Windows:
- Open the Windows Device Manager and check for Ports (COM and LPT) devices.
- Use the STMicroelectronics STLink Virtual COM Port detected port for the UART terminal connection.
- Open a serial terminal (e.g. PuTTY) on this COM port with the settings: 115200 baud, 8 data bits, no parity, 1 stop bit

Software setup

The are two ways to flash the board.

STM32CubeIDE

The Stm32CubeIDE ships an STM32_Programmer_CLI.exe. The program can found in your Install location. Please adjust the path bellow as needed. Run windows search for STM32_Programmer_CLI.exe in your Install location.

Once you found the program run the following.

set FLASHER="C:\ST\STM32CubeIDE_1.18.1\STM32CubeIDE\plugins\com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.win32_2.2.100.202412061334\tools\bin\STM32_Programmer_CLI.exe"

set ELF=ecatm-demo-appl.elf

%FLASHER% -c port=SWD -w %ELF% -rst

The FLASHER and ELF path need to be adjusted.

The output should look like the following.

stm32h753nucleo>%FLASHER% -c port=SWD -w %ELF% -rst
      -------------------------------------------------------------------
                      STM32CubeProgrammer v2.19.0
      -------------------------------------------------------------------

ST-LINK SN  : 0040004B3234510433353533
ST-LINK FW  : V3J16M7
Board       : NUCLEO-H753ZI
Voltage     : 3.28V
SWD freq    : 8000 KHz
Connect mode: Normal
Reset mode  : Software reset
Device ID   : 0x450
Revision ID : Rev V
Device name : STM32H7xx
Flash size  : 2 MBytes
Device type : MCU
Device CPU  : Cortex-M7
BL Version  : 0x91

Opening and parsing file: ecatm-demo-appl.elf


Memory Programming ...
  File          : ecatm-demo-appl.elf
  Size          : 385.39 KB
  Address       : 0x08000000



Erasing memory corresponding to sector 0:
Erasing internal memory sectors [0 3]
Download in Progress:
██████████████████████████████████████████████████ 100%

File download complete
Time elapsed during download operation: 00:00:04.728

MCU Reset

Software reset is performed

STM32CubeProgrammer

To program a memory, go through the following steps:

Download and install the STM32CubeProgrammer.
Start the STM32CubeProgrammer software.
Press the green Connect button. The state in the menu line should switch to Connected.
Select Erasing and programming in the menu.
Press the Browse button and select the file ecatm-demo-appl.elf from the icECAT Master Demo software package. (TODO: package folder …)
Press the Start programming button to start programming of the demo application.
A detailed guide for using the STM32CubeProgrammer can be found here: UM2237: STM32CubeProgrammer software description, 2.3 Memory programming and erasing

Starting the demo

Press RESET botton (B2) on the development board. The terminal should display:

                        __            ________   ______    ______   ________
      ....... <<<<<<<  /  |          /        | /      \  /      \ /        |
    : ------- <<<<<    ##/   _______ ########/ /######  |/######  |########/
  : / ....... <<<      /  | /       |## |__    ## |  ##/ ## |__## |   ## |
 : / :....... <<<<<    ## |/#######/ ##    |   ## |      ##    ## |   ## |
: | ::        <<<<<<<  ## |## |      #####/    ## |   __ ######## |   ## |
: | ::        :: | :   ## |## \_____ ## |_____ ## \__/  |## |  ## |   ## |   __
 : \ ::......:: / :    ## |##       |##       |##    ##/ ## |  ## |   ## |  /  |
  : \ :......: / :     ##/  #######/ ########/  ######/  ##/   ##/    ##/   ##/
    : -------- :
      ........         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 configuration:

Network setup: Connect a physical EtherCAT network.
EtherCAT network configuration: Scan the network.
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.         !!
-------------------------------------------------------------------------------

=== 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 STM32 Nucleo-H753ZI

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.

Full-featured software

A full-featured evaluation version of the icECAT EtherCAT Master Stack and the icECAT EtherCAT Configuration Library is available upon request.