ECATGUI guide

Summary
Introduction ....................................................................................................................................................... 2

Histogram Page.................................................................................................................................................. 2

Statistics Page .................................................................................................................................................... 2

Command utility Page ....................................................................................................................................... 3

Logger Page ....................................................................................................................................................... 3

Variables Page ................................................................................................................................................... 4

Slave control Page ............................................................................................................................................. 4

Enet Page ........................................................................................................................................................... 4

CoE Page ............................................................................................................................................................ 5

1
Introduction
The present document is a guide describing the features of ECATGUI tool, application for online diagnosis of
EtherCAT master and EtherCAT net.

Histogram Page
This page contains:

1. The histogram representing the statistical distribution of CPU load corresponding to EtherCAT
master cyclic activity. EtherCAT master nominal period is 100us; generally, EtherCAT master
activity keeps the CPU busy for an effective shorter time each cycle (typically less than 20us). Red
bars display the distribution of the effective cycle time. If the percentage value of a time range is
less than 3%, the number of cycles is displayed instead of the red bar. Above the graph, the current
total number of master EtherCAT cycles is displayed.
2. The checkboxes with which it’s possible to manipulate debug masks that turn on (or off) debug
messages on EtherCAT master console. Enable trace flag turns on printing activity on EtherCAT
master console; all other flags activate messages related to specific software modules or aspects of
master activity. Checked flags correspond to enabled masks, unchecked ones inhibit prints of
messages they refer to.

Statistics Page
This page contains the tree displaying master EthrCAT debug variables; each node represents a debug
variable; the variables are grouped in following main sections:
Debug: information about master EtherCAT debug (i.e. active debug mask)
Ethernet: ethernet controller parameters, EtherCAT communication details (number and size of
transmitted and received packets).
EtherCAT protocol: statistical information about EtherCAT communication status: lost packets, command
retry, working counter errors, number of malformed packets, etc.
Master: information about EtherCAT master: cycle period, average effective cycle time, number of lost
cycles, EtherCAT master performance counters, Distributed Clock parameters (DC).
Slaves: information about EtherCAT slaves detected by EtherCAT master. Each slave is described by its
Logical Address = <configured address of the slave>; hardware information, vendor id, product
code, EtherCAT AL status, status of its ports, connections are reported here. Network and
Topology section shows details such as connections and EtherCAT errors detected by the slav. DC
section contains the values related to distributed clock running.
SoE: information about groups of SoE slaves (if present)
CoE: information about groups of CoE slaves (if present)

Show variable names flags switches between value and name visualization for the variables in the tree.
Freeze button “freeze” tree node values. Clicking on the same button (now named Resume) the automatic
update of the node values will start again.

2
Dump to file button prints all EtherCAT master statistical variables tree on a XML file. That file is created in
logfile folder and named “ecatgui_nodedump_<dump date>-<dump hour >.xml (and it can be easily open
using InternetExplorer or an XML editor).
Double clicking on a tree node, Variables page will be opened: the path of the selected node will be
displayed on “Path” field and it will be possible to read or write the value of the corresponding debug
variable using GET and SET buttons, respectively.

Command utility Page

Use this page to send EtherCAT commands through EtherCAT master. First of all, select command type
from Command Type drop down list; then, fill all the fields with the parameters required for the selected
command type:

 Through Slave field indicate the address of recipient slave. Use both decimal or hexadecimal values
(hex preceded by “0x”); if “hexadecimal” flag is checked, the value will be always read as
hexadecimal. For APRD, APWR and APRW command type, the value in Slave field is interpreted as
“positional address” of the slave in EtherCAT net (you can use both the number of the position of
the slave or the negative or null number used by auto-incremental command to find the slave.; in
both cases, the first slave of the net has 0 as its position).

 Address field is always read as hexadecimal: its value, depending by the selected command type,
could mean the register address or the logical address of a memory portion you want to
read/write.

 Data size field is used to set the data size (decimal value) for write command.

 Use Data field to set data to write. They must be a unique sequence of hexadecimal digits without
spaces. The first two digits will be considered as the BYTE 0 of data, the second two as BYTE 1 and
so on.

Once all field will be filled, click on RUN button to send EtherCAT master command. The outcome of the
command will be displayed; in case of read command, read data will be displayed in Answer field.

Logger Page
Use Logger Page to trace EtherCAT traffic detected by EtherCAT master. You need to get EtherCAT master
ready to log the traffic, telling it the number of EtherCAT packets you want to store through Number of
frames field and clicking button ENABLE LOG (Note: each EtherCAT command is made of one forward and
one backward frame). When START LOG button is active, you can click on START LOG button to start
EtherCAT traffic log and dump. Detected frames will be written on a TXT file you can open with Wireshark.
All frames detected will be dumped on the file since you click on START LOG until the number of frame
(previously set) is reached or it is elapsed a certain amount of time. The log file will be named “logpkt_<log
date>_<log hour>.txt”.

Note: if EtherCAT traffic is not enough to reach the expected number of frame, trace dump is stopped after a while.

3
Variables Page
As told before, this page lets you read or write the value of master EtherCAT debug variables. Set debug
variable path in Path field (you can omit the starting “Statistics”). You can get a variable path double
clicking on the desired variable in Statistics page.
Press GET button to read the variable value (if available, it will be displayed in Value field).
Insert data to write, formatted as single bytes (two hexadecimal digits) separated by spaces, in the field
next to SET button. Press SET button to write the variable value.

Slave control Page

Use this page to get or set AL status of EtherCAT slaves and to read or write slaves EEPROM.

AL Status
In AL Status control panel, select one of the EtherCAT slaves available in Slave address list (the slaves are
here displayed through their logical address): the selected slave current AL Status is displayed in Current AL
Status. Refresh button can be used to force the application to get the selected slave status again.
Pressing on each of INIT, PREOPERATIONAL, SAFEOPERATIONAL and OPERATIONAL button, you can set
the corresponding AL Status on the selected slave. In Error code you can read the error code related to the
latest attempted AL Status change (0x0000 means success).

EEPROM
In EEPROM access panel, the available slaves, detected by the EtherCAT master, are listed through their
positional address in Slave position. For operation on EEPROM, select a slave, choose Read or Write
desired EEPROM access, write in Address (hex) the hexadecimal address of the WORD in EEPROM you
want to access to, write in Size field the number of byte to read or write.
In case of write access, insert data to write as hexadecimal digits, from Least Significant Byte to Most
Significant Byte, without separations.
Press RUN to write/read. In the little grey box below RUN button, the outcome of the operation will be
displayed (errors or success).
In case of read access, Answer box will be filled with number of byte read from the selected slave EEPROM,
as required. You can display these bytes adding or removing the spaces enabling Byte Separator checkbox.
CRC Utility button opens a window with a tool for CRC calculation on the first 7 Word of EEPROM (Word 0 –
6): in case you want to modify EEPROM content, you need to write the correct CRC value in WORD 7. If you
write 14 byte of EEPROM in the text box and press CRC button, you’ll get the two bytes of WORD 7
corresponding to the CRC value of given data to write on EEPROM. In case of errors, Error message field
will display a message.

Enet Page
This page contains Enet traffic log on the EtherCAT master console.
Select from Slave list one of the EtherCAT slaves with Enet cannels.
Configure trigger condition through the following controls:
Channel for Enet channel (branch) selection; note that Biesse PLC programmers indicates channels number
starting from 1, here channels are displayed starting from 0 (keep into account of this offset of 1).
Address for Enet module address selection (from 0 to 31).

4
Frame Limit limits the number of frames dumped on the EtherCAT master console; a counter will
increment each time a new Enet frame is dumped on the console. You can reset that counter pressing
Reset Counter button; you can set counter auto reset property enabling Auto Reset flag.
Mask Number is used to select the frames to be monitored (from 1 to 10).
TX Mask and RX Mask let you select the masks to detect variations of the bits indicated in, respectively,
transmitted and received data. Press Apply TW and Apply RW, respectively, to apply selected masks to
transmitted and received data.
Values displayed in the fields described above should correspond to the current configuration of Enet log
manager of the EtherCAT master. Pressing Refresh button you can force the application to read again the
value of current Enet logger settings.
Start Log/Stop Log button enables or disable Enet log.
Dump Frames button makes EtherCAT master to dump the Enet traffic managed by the master during one
execution cycle.

CoE Page
In this page you can read or write dictionary objects on CoE slaves (or compatible).
Select the address of a slave in Slave Address list.
Specify in Index (hex) and Subindex (hex) fields, respectively, index and sub-index of the dictionary object
you want to access to (use hexadecimal values).
Size (dec) field (decimal value) is use to set the number of bytes to read from or write to the selected
dictionary object.
Use Data to write field to set data you want to write (from MSB to LSB).
Use Read and Write buttons to start, respectively, object read or write.
Read outcome is displayed in Read data (from MSB to LSB). In case of errors (read or write), the error code
(Abort Code) is displayed in Error code.