5. Getting Started

To enable a quick and easy start, every EC-Monitor package comes with a pre-compiled EcMonitorDemo executable. This example application handles the following tasks:

EC-Monitor initialization
Process Data acquisition with EC-DAQ
Periodic Job Task in polling or interrupt mode
Record and replay wireshark traces
Logging

5.1. Running EcMonitorDemo

To capture the EtherCAT® traffic insert a TAP device after the Master Controller.

Start the EcMonitorDemo from the command line to process the captured EtherCAT® frames. At least a Real-time Ethernet Driver and a ENI file must be specified.

EcMonitorDemo -ndis 192.168.157.2 1 -f eni.xml -t 0 -v 3

5.1.1. Command line parameters

EcMonitorDemo <LinkLayer> [-f ENI-FileName] [-t time] [-b cycle time] [-a affinity] [-v level] [-perf] [-log prefix [msg cnt]] [-lic key] [-sp [port]] [-rec [prefix]] [-play pcap-FileName] [-daqrec file name]

The parameters are as follows:

-f <ENI-FileName>: Path to ENI file

-t <time>

Running duration in msec. When the time expires the demo application exits completely.

<time>: Time in msec, 0 = forever (default = 120000)

-b <cycle time>

Specifies the bus cycle time. Defaults to 1000 µs (1 ms).

<cycle time>: Bus cycle time in µsec

-a <affinity>

The CPU affinity specifies which CPU the demo application ought to use.

<affinity>: 0 = first CPU, 1 = second, …

-v <level>

The verbosity level specifies how much console output messages will be generated by the demo application. A high verbosity level leads to more messages.

<level>: Verbosity level: 0=off (default), 1..n=more messages

-perf [<level>]

Enable max. and average time measurement in µs for all EtherCAT jobs (e.g. ProcessAllRxFrames).

<level>: Depending on level the performance histogram can be activated as well.

-log <prefix> [<msg cnt>]

Use given file name prefix for log files.

<prefix>
<msg cnt>: Messages count for log buffer allocation

-lic <key>

Set License key.

<key>: License key string

-oem <key>

Use OEM key

<key>: 64 bit OEM key.

-sp [<port>]

If platform has support for IP Sockets, this command-line option enables the Remote API Server to be started. The Remote API Server is going to listen on TCP Port 6000 (or port parameter if given) and is available for connecting Remote API Clients.

<port>: RAS server port

-rec [<prefix>]

Packet capture file recording

<prefix>: File name prefix

-play <FileName>

Packet capture file processing

<FileName>: File name (*.pcap|*.pcapng)

-genebi <FileName>

Export ENI Builder config on demo stop

<FileName>: File name (*.xml)

-mqtt <BrokerAddress>

Publish process data to MQTT broker. EcMonitorDemoMqtt only

<BrokerAddress>: MQTT broker address

-mqttCycTime <Msec>

Minimum time between cyclic messages for a variable. EcMonitorDemoMqtt only

<Msec>: Time in milliseconds

-mqttChgTime <Msec>

Minimum time between change-detection based messages for a variable. EcMonitorDemoMqtt only

<Msec>: Time in milliseconds

-daqrec <FileName>

<FileName>: Configuration file

5.1.1.1. Link Layer

Using one of the following demo application Link Layer options, the EC-Monitor will dynamically load the network driver for the specified network adapter card and use the appropriate network driver to access the Ethernet adapter for EtherCAT©. ShowSyntaxLinkLayer() in Common/EcSelectLinkLayer.cpp is called automatically if the Demo application is started without parameters and lists the possibilities.

Note

Not all link layers are available on all operating systems or architectures. A detailed view in the form of a matrix can be found in the developer center.

-intelgbe <instance> <mode> [tts <SendOffset>|tmr] [--nophyctrlonconnect]

Hardware: Intel Pro/1000 network adapter card

<instance>: Device instance 1 = first, 2 = second, …
<mode>: 0 = Interrupt mode | 1 = Polling mode

Optional:

tts: Enables Real-time Ethernet Driver Time Triggered Send (TTS)
<SendOffset>: TTS cyclic frame send offset from cycle start (usec)

Optional:

tmr: Enables Real-time Ethernet Driver Timer

Optional:

--nophyctrlonconnect: Disable PHY control (e.g. PHY reset, PHY PM settings, Gbits Ctrl) on link connection detected

-ndis <IpAddress> <mode> [--name <AdapterName>] [DisablePromiscuousMode] [DisableForceBroadcast]

Hardware: Hardware independent, only available for Windows.

<IpAddress>: IP address of network adapter card, e.g. 192.168.157.2 or 0.0.0.0 if name given
<mode>: 0 = Interrupt mode | 1 = Polling mode

Optional:

--name: Select network adapter by name
<AdapterName>: Service name from HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\NetworkCards

Optional:

DisablePromiscuousMode: Disable promiscuous mode

Optional:

DisableForceBroadcast

-snarf <adapterName>

Hardware: Hardware independent, only available for VxWorks

<adapterName>: Adapter name, e.g. fei0

-sockraw <device> [<mode>] [--nommaprx] [--promiscuousmode]

Hardware: Hardware independent, only available for Linux.

<device>: Network device, e.g. eth1

Optional:

<mode>: 0 = Interrupt mode | 1 = Polling mode

Optional:

--nommaprx: Disable PACKET_MMAP for receive

Optional:

--promiscuousmode: Enable promiscuous mode

-winpcap <ipAddress> <mode>

Hardware: Hardware independent, only available for Windows.

<ipAddress>: IP address of network adapter card, e.g. 192.168.157.2
<mode>: 0 = Interrupt mode | 1 = Polling mode

5.2. Running EcMonitorDemoMqtt

The EcMonitorDemoMqtt includes additional functionality to publish process data to a MQTT broker, for example Eclipse Mosquitto (https://mosquitto.org). It additionally requires at least the MQTT broker address.

EcMonitorDemoMqtt -ndis 192.168.157.2 1 -f eni.xml -mqtt localhost -t 0 -v 3

The Eclipse Paho MQTT C client library is also required. The EcMonitorDemoMqtt has been developed and tested with version 1.3.10.

A dynamic library file is required in the directory <InstallPath>/Bin/<OS>/<Arch>.

Eclipse Paho MQTT C 1.3.10 download: https://github.com/eclipse-paho/paho.mqtt.c/releases/tag/v1.3.10
For Linux, the file paho-mqtt3c.so.1 is included in the binary release.
For Windows, the file paho-mqtt3c.dll must be built from source, see the file README.md section “Building with CMake” in the source code.

The EcMonitorDemoMqtt publishes process data cyclically and on change detection. The frequency of these messages can be configured, see Command line parameters. Each slave variable is assigned a separate MQTT topic:

/EtherCAT/Monitor<instance ID>/slavebyname/<slave name>/variable/[output/input]/<variable name>

The payload is a raw byte buffer beginning with a 4-byte unsigned integer payload version. The structure of the following bytes is version-specific.

5.2.1. Payload version 0

The payload contains the process image data of the variable. Because the size differs for each variable, this data is also of variable size, but is always rounded up to full bytes. E.g. a 1-bit variable will be sent as a BYTE.

Variable type	Offset	Description	Hint
`UINT32`	0 bytes	Payload version (0)	Little-endian
`UINT64`	4 bytes	Data timestamp in nanoseconds	Little-endian
Variable data	12 bytes	Process image data of the variable	Variable size rounded up to full bytes

5.3. Compiling the EcMonitorDemo

The following main rules can be used to generate the example applications for all operating systems.

<OS> is a placeholder for the operating system used.
<ARCH> for the architecture. If different architectures are supported.

5.3.1. Software Development Kit (SDK)

The EC-Monitor development kit is needed to write applications based on the EC-Monitor core. The EC-Monitor core is shipped as a library which is linked together with the application.

The following components are supplied together with an SDK:

/Bin: Executables containing the EC-Monitor core
/Doc: Documentation
/Examples: Example applications as source code
/SDK: EtherCAT® Software Development Kit containing libraries and header files to build C/C++-applications
/SDK/INC: Header files to be included with the application
/SDK/LIB: Libraries to be linked with the application
/SDK/FILES: Additional files for platform integration
/Sources/Common: Shared source code

5.3.2. Include search path

The header files are located in the following directories:

<InstallPath>/SDK/INC/<OS>/<ARCH>
<InstallPath>/SDK/INC
<InstallPath>/Sources/Common

5.3.3. Libraries

The libraries are delivered as static, dynamic or both. This is depending on the operating system. They are located in the following directories:

Static libraries

<InstallPath>/SDK/LIB/<OS>/<ARCH>

EC-Monitor core

libEcMonitor.a

EC-Monitor RAS server (optional)

libEcMonitorRasServer.a

Dynamic libraries

<InstallPath>/Bin/<OS>/<ARCH>

EC-Monitor core

libEcMonitor.so

EC-Monitor RAS server (optional)

libEcMonitorRasServer.so

Whether it is a Shared Object *.so or a Dynamic Link Library *.dll depends on the operating system.

5.3.4. Preprocessor definitions

The following preprocessor directives must be set in the build environment or project:

EC_MONITOR

Exclude the EC-DAQ support in the demo:

EXCLUDE_DAQ_SUPPORT