# index.html.md

# EC-Monitor


# api.html.md

# Application programming interface, reference

Function prototypes, definitions etc. of the API can be found in the header file `EcMonitor.h` which is the main header file to include when using EC-Monitor.

### Fundamental types

<!-- -*- mode: rst -*- -->

<a id="d8-d43-group-e-c-t-y-p-e-s"></a>

### typedef void \*EC_T_PVOID

Pointer of type void 

### typedef int EC_T_BOOL

Boolean 

### typedef char EC_T_CHAR

Character, 8 bit 

### typedef unsigned short EC_T_WCHAR

Wide-character, 16 bit 

### typedef unsigned char EC_T_BYTE

Byte, unsigned integer 8 bit 

### typedef unsigned char \*EC_T_PBYTE

Pointer of type EC_T_BYTE 

### typedef unsigned short EC_T_WORD

Word, unsigned integer 16 bit 

### typedef unsigned int EC_T_DWORD

Double word, unsigned integer 32 bit 

### typedef signed char EC_T_SBYTE

Signed-Byte, signed integer 8 bit 

### typedef signed short EC_T_SWORD

Signed-Word, signed integer 16 bit 

### typedef signed int EC_T_SDWORD

Signed-Double-Word, signed integer 32 bit 

### typedef int EC_T_INT

Integer 

### typedef unsigned int EC_T_UINT

Unsigned-Integer 

### typedef short EC_T_SHORT

Short 

### typedef unsigned short EC_T_USHORT

Unsigned-Short 

### typedef float EC_T_REAL

Real, floating point 

### typedef double EC_T_LREAL

long Real, floating point 

### typedef unsigned long long EC_T_UINT64

Unsigned integer 64 bits 

### typedef signed long long EC_T_INT64

Signed integer 64 bits 

### EC_T_VOID

Void type 

### Macros

### EC_TRUE

Boolean value: True 

### EC_FALSE

Boolean value: False 

### EC_NULL

Null pointer constant


# api_diag.html.md

# Diagnosis

## emonGetDiagnosisImagePtr

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*emonGetDiagnosisImagePtr([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)

Gets the diagnosis image pointer. 

* **Parameters:**
  **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
* **Returns:**
  Diagnosis image pointer 

#### SEE ALSO
- [`EC_T_CFG_SLAVE_INFO::wWkcStateDiagOffsIn`](api_slave.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO19wWkcStateDiagOffsInE)
- [`EC_T_CFG_SLAVE_INFO::wWkcStateDiagOffsOut`](api_slave.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO20wWkcStateDiagOffsOutE)

## emonGetDiagnosisImageSize

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetDiagnosisImageSize([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)

Gets the diagnosis image size. 

* **Parameters:**
  **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
* **Returns:**
  Diagnosis image size 

#### SEE ALSO
- [`EC_T_CFG_SLAVE_INFO::wWkcStateDiagOffsIn`](api_slave.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO19wWkcStateDiagOffsInE)
- [`EC_T_CFG_SLAVE_INFO::wWkcStateDiagOffsOut`](api_slave.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO20wWkcStateDiagOffsOutE)

## emonGetMasterSyncUnitInfoNumOf

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetMasterSyncUnitInfoNumOf([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)

Get number of Master Sync Units info entries. 

* **Parameters:**
  **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
* **Returns:**
  Number of Master Sync Units info entries 

## emonGetMasterSyncUnitInfo

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetMasterSyncUnitInfo([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wMsuId, [EC_T_MSU_INFO](api_diag.html.md#_CPPv413EC_T_MSU_INFO) \*pMsuInfo)

Get information about a specific Master Sync Unit. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **wMsuId** – [in] Master Sync Unit to get the information from 
  * **pMsuInfo** – [out] Pointer to an [EC_T_MSU_INFO](api_diag.html.md#d4/dfc/struct_e_c___t___m_s_u___i_n_f_o) structure receiving the Master Sync Unit information 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

`MSU_ID_ALL_INFO_ENTRIES` retrieves the information from all MainDevice sync units at once. The application must ensure that pMsuInfo is capable for all entries.

### struct EC_T_MSU_INFO

### Public Members

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wMsuId

[out] Master Sync Unit ID (ENI: Slave/ProcessData/RxPdo[1..4]@Su, Slave/ProcessData/TxPdo[1..4]@Su, comment at Cyclic/Frame/Cmd) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBitOffsIn

[out] Process Data Image INPUTs bit offset 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBitSizeIn

[out] Process Data Image INPUTs bit length 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBitOffsOut

[out] Process Data Image OUTPUTs bit offset 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBitSizeOut

[out] Process Data Image OUTPUTs bit length 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagOffsIn

[out] INPUTs WkcState bit offset in Diagnosis Image. (Bit values: 0 = Process Data valid, 1 = Process Data invalid) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagOffsOut

[out] OUTPUTs WkcState bit offset in Diagnosis Image. (Bit values: 0 = Process Data valid, 1 = Process Data invalid) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) adwReserved[16]

reserved 

#### SEE ALSO
[`emonGetMasterSyncUnitInfoNumOf()`](api_diag.html.md#_CPPv430emonGetMasterSyncUnitInfoNumOf10EC_T_DWORD)

## emonGetSlaveStatistics

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveStatistics([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_SLVSTATISTICS_DESC](api_diag.html.md#_CPPv423EC_T_SLVSTATISTICS_DESC) \*pSlaveStatisticsDesc)

Get Slave’s statistics counter. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwSlaveId** – [in] Slave id 
  * **pSlaveStatisticsDesc** – [out] Pointer to structure [EC_T_SLVSTATISTICS_DESC](api_diag.html.md#d6/dee/struct_e_c___t___s_l_v_s_t_a_t_i_s_t_i_c_s___d_e_s_c)
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
- [emonIoCtl - EC_IOCTL_GET_SLVSTATISTICS](api_diag.html.md#emonioctl-ec-ioctl-get-slvstatistics)
- [`emonGetSlaveId()`](api_slave.html.md#_CPPv414emonGetSlaveId10EC_T_DWORD9EC_T_WORD)
- [`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonBadConnectionsDetect

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonBadConnectionsDetect([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bRefreshSlaveStatistics, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Detects bad connections. 

Analyzes the slave ESC error counters:
* Invalid Frame Counter (0x0300),
* RX Error Counter (0x0301),
* Lost Link Counter (0x0310),

whether there is a problem in the area PHY - connector - cable - connector - PHY. If one of the above error counters shows a value not equal to zero, an EC_NOTIFY_BAD_CONNECTION is generated, which contains the exact position of the faulty connection. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bRefreshSlaveStatistics** – [in]  Not supported by EC-Monitor, set to EC_FALSE 
  * **dwTimeout** – [in] Timeout [ms].  Not currently used by EC-Monitor, but may  not be EC_NOWAIT! 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonIoCtl - EC_IOCTL_GET_SLVSTATISTICS

### EC_IOCTL_GET_SLVSTATISTICS

Get slave statistics showing errors on Ethernet layer for slave id. Statistics are read on a regular basis (default: off). 

#### NOTE
See also EC_IOCTL_SET_SLVSTAT_PERIOD, EC_IOCTL_FORCE_SLVSTAT_COLLECTION, EC_IOCTL_GET_SLVSTAT_PERIOD 

* **Parameters:**
  * **pbyInBuf** – [in] Pointer to an EC_T_DWORD type variable containing the slave id 
  * **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes 
  * **pbyOutBuf** – [out] Pointer to struct [EC_T_SLVSTATISTICS_DESC](api_diag.html.md#d6/dee/struct_e_c___t___s_l_v_s_t_a_t_i_s_t_i_c_s___d_e_s_c)
  * **dwOutBufSize** – [in] Size of the output buffer provided at pbyOutBuf in bytes 
  * **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_SLVSTATISTICS_DESC

### Public Members

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) abyInvalidFrameCnt[ESC_PORT_COUNT]

[out] Invalid Frame Counters per Slave Port 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) abyRxErrorCnt[ESC_PORT_COUNT]

[out] RX Error Counters per Slave Port 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) abyFwdRxErrorCnt[ESC_PORT_COUNT]

[out] Forwarded RX Error Counters per Slave Port 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byProcessingUnitErrorCnt

[out] Processing Unit Error Counter 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byPdiErrorCnt

[out] PDI Error Counter 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wAlStatusCode

[out] AL Status Code 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) abyLostLinkCnt[ESC_PORT_COUNT]

[out] Lost Link Counters per Slave Port 

### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwReadTime

[out] Timestamp of the last read [ns] 

### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwChangeTime

[out] Timestamp of the last counter change [ns] 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonClearSlaveStatistics

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonClearSlaveStatistics([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId)

Clears all error registers of a slave. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwSlaveId** – [in] Slave Id, INVALID_SLAVE_ID clears all slaves 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### NOTE
Only the buffered error register values are deleted. The actual counters on the SubDevices remain unchanged.

#### SEE ALSO
[`emonGetSlaveId()`](api_slave.html.md#_CPPv414emonGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emonIoCtl - EC_IOCTL_CLR_SLVSTATISTICS

### EC_IOCTL_CLR_SLVSTATISTICS

Clear slave statistics in slaves. 

* **Parameters:**
  * **pbyInBuf** – [in] Should be set to EC_NULL 
  * **dwInBufSize** – [in] Should be set to 0 
  * **pbyOutBuf** – [out] Should be set to EC_NULL 
  * **dwOutBufSize** – [in] Should be set to 0 
  * **pdwNumOutData** – [out] Should be set to EC_NULL 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonIoCtl - EC_IOCTL_SB_STATUS_GET

### EC_IOCTL_SB_STATUS_GET

Get the status of the last bus scan. 

* **Parameters:**
  * **pbyInBuf** – [in] Should be set to EC_NULL 
  * **dwInBufSize** – [in] Should be set to 0 
  * **pbyOutBuf** – [out] Pointer to [EC_T_SB_STATUS_NTFY_DESC](notification_status.html.md#d1/d72/struct_e_c___t___s_b___s_t_a_t_u_s___n_t_f_y___d_e_s_c)
  * **dwOutBufSize** – [in] Size of the output buffer in bytes 
  * **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
- [emonNotify - EC_NOTIFY_SB_STATUS](notification_status.html.md#emonnotify-ec-notify-sb-status)
- [`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)


# api_general.html.md

# General functions

## emonInitMonitor

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonInitMonitor([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceId, const [EC_T_MONITOR_INIT_PARMS](api_general.html.md#_CPPv423EC_T_MONITOR_INIT_PARMS) \*pParms)

Initialize EC-Monitor. 

This function has to be called prior to calling any other function of EC-Monitor.

* **Parameters:**
  * **dwInstanceId** – [in] Instance ID 
  * **pParms** – [in] Monitor initialization parameters 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_MONITOR_INIT_PARMS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSignature

[in] Set to MONITOR_SIGNATURE 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSize

[in] Set to sizeof(EC_T_MONITOR_INIT_PARMS) 

### [EC_T_LOG_PARMS](api_general.html.md#_CPPv414EC_T_LOG_PARMS) LogParms

[in] Logging parameters 

### [EC_T_OS_PARMS](api_general.html.md#_CPPv413EC_T_OS_PARMS) \*pOsParms

[in] Operation system layer parameters 

### [EC_T_LINK_PARMS](emll_generic.html.md#_CPPv415EC_T_LINK_PARMS) \*pLinkParms

[in] Link layer parameters 

### [EC_T_ETHERNET_TAP_TYPE](api_general.html.md#_CPPv422EC_T_ETHERNET_TAP_TYPE) eEthTapType

[in] Type of Ethernet TAP 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wMainTapPortIn

[in] TAP IN port. For ET2000: X1.0 = 10, X1.1 = 11, X2.0 = 20, …, X4.1 = 41. For other supported TAPs, this is the port number starting from 0. If both wMainTapPortIn and wMainTapPortOut are 0, no filtering is performed 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wMainTapPortOut

[in] TAP OUT port. See wMainTapPortIn 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBusCycleTimeNsec

[in] Bus cycle time [ns] 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxBusSlaves

[in] Maximum pre-allocated bus slave objects 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBacktraceFrames

[in] Number of frames held in backtrace buffer. Total memory requirements of the buffer: $ 2 \times dwBacktraceFrames \times 1536 bytes $. 

### [EC_T_PERF_MEAS_INTERNAL_PARMS](api_general.html.md#_CPPv429EC_T_PERF_MEAS_INTERNAL_PARMS) PerfMeasInternalParms

[in] Internal performance measurement parameters 

### [EC_T_WORKER_THREAD_PARMS](api_general.html.md#_CPPv424EC_T_WORKER_THREAD_PARMS) WorkerThreadParms

[in] Internal worker thread parameters 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCommunicationTimeoutMsec

[in] Timeout [ms] for communication on the Ethernet TAP. 0: defaults to 3 sec, EC_WAITINFINITE: disables monitoring. 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bApiLockByApp

[in] Lock pending API against emonDeinitMonitor(). EC_FALSE (default): locked internally. EC_TRUE: application is responsible for locking. 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szFileStoragePath[EC_FILESTORAGE_PATH_SIZE]

[in] Path used to store records and files, e.g. FoE transfers. EC_NULL: defaults to “”. 

### [EC_T_MBX_PARMS](api_general.html.md#_CPPv414EC_T_MBX_PARMS) MbxParms

[in] Mailbox monitoring parameters 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bProcessRestructuredCyclicCmds

[in] Support processing of restructured cyclic command layout. All cyclic commands are processed as long as they are within the process data boundary of the ENI. 

### enum EC_T_ETHERNET_TAP_TYPE

*Values:*

### enumerator eEthTap_Unknown

Unknown type 

### enumerator eEthTap_AutoDetect

Auto detect TAP type. If no suitable type is detected, eEthTap_Generic is used. 

### enumerator eEthTap_Generic

Generic Ethernet switch 

### enumerator eEthTap_Beckhoff_ET2000

Beckhoff ET2000 Ethernet probe 

### enumerator eEthTap_Kunbus_TapCurious

Kunbus TAP Curious Ethernet probe 

### enumerator eEthTap_PortMirror

Port mirror Ethernet probe with separate monitoring ports for TX and RX. Only RX port supported. 

### enumerator eEthTap_Dummy

### struct EC_T_OS_PARMS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSignature

[in] Set to EC_OS_PARMS_SIGNATURE 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSize

[in] Set to sizeof(EC_T_OS_PARMS) 

### [EC_T_LOG_PARMS](api_general.html.md#_CPPv414EC_T_LOG_PARMS) \*pLogParms

[in] Pointer to logging parameters 

### EC_PF_SYSTIME pfSystemTimeGet

[in] Function to get host time in nanoseconds since 1st January 2000. Used as time base for DC Initialization. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSupportedFeatures

[in/out] Reserved 

### EC_PF_QUERY_MSEC_COUNT pfSystemQueryMsecCount

[in] Function to get system’s ms count 

### struct EC_T_LOG_PARMS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwLogLevel

[in] Log level. See [EC_LOG_LEVEL…](api_general.html.md#d3-d63-group-e-c-l-o-g-l-e-v-e-l-s)

### [EC_PF_LOGMSGHK](api_general.html.md#_CPPv414EC_PF_LOGMSGHK) pfLogMsg

[in] Log callback function called on every message 

### EC_T_LOG_CONTEXT \*pLogContext

[in] Log context to be passed to log callback 

<!-- -*- mode: rst -*- -->

<a id="d3-d63-group-e-c-l-o-g-l-e-v-e-l-s"></a>

### EC_LOG_LEVEL_SILENT

### EC_LOG_LEVEL_ANY

### EC_LOG_LEVEL_CRITICAL

### EC_LOG_LEVEL_ERROR

### EC_LOG_LEVEL_WARNING

### EC_LOG_LEVEL_INFO

### EC_LOG_LEVEL_INFO_API

### EC_LOG_LEVEL_VERBOSE

### EC_LOG_LEVEL_VERBOSE_ACYC

### EC_LOG_LEVEL_VERBOSE_CYC

### EC_LOG_LEVEL_UNDEFINED

### typedef [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) (\*EC_PF_LOGMSGHK)(EC_T_LOG_CONTEXT \*pContext, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwLogMsgSeverity, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szFormat, ...)

* **Param pContext:**
  [in] Context pointer. This pointer is used as parameter when the callback function is called. 
* **Param dwLogMsgSeverity:**
  [in] Log message severity, EC_LOG_LEVEL_… 
* **Param szFormat:**
  [in] String that contains the text to be written. It can optionally contain embedded format specifiers that are replaced by the values specified in subsequent additional arguments and formatted as requested. 
* **Return:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_PERF_MEAS_INTERNAL_PARMS

### Public Members

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bEnabled

[in] Enable/disable internal performance counters 

### [EC_T_PERF_MEAS_COUNTER_PARMS](api_general.html.md#_CPPv428EC_T_PERF_MEAS_COUNTER_PARMS) CounterParms

[in] Timer function settings. When not provided OsMeasGetCounterTicks is used. 

### [EC_T_PERF_MEAS_HISTOGRAM_PARMS](api_general.html.md#_CPPv430EC_T_PERF_MEAS_HISTOGRAM_PARMS) HistogramParms

[in] Histogram settings. When not provided the histogram is disabled. 

### struct EC_T_PERF_MEAS_COUNTER_PARMS

### Public Members

### [EC_PF_PERF_MEAS_GETCOUNTERTICKS](api_general.html.md#_CPPv431EC_PF_PERF_MEAS_GETCOUNTERTICKS) pfGetCounterTicks

[in] Function returning the current counter ticks 

### EC_T_VOID \*pvGetCounterTicksContext

[in] Context passed into GetCounterTicks 

### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwFrequency

[in] Frequency in Hz used by the timer in GetCounterTicks 

### typedef [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) (\*EC_PF_PERF_MEAS_GETCOUNTERTICKS)(EC_T_VOID \*pvContext)

* **Param pvContext:**
  **[in]** Arbitrarily application-defined parameter passed to callback 

### struct EC_T_PERF_MEAS_HISTOGRAM_PARMS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBinCount

[in] Amount of bins to use for the histogram 

### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwMinTicks

[in] Results below qwMinTicks are stored in the first bin 

### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwMaxTicks

[in] Results above qwMaxTicks are stored in the last bin 

### struct EC_T_WORKER_THREAD_PARMS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPrio

[in] Priority to use for the worker thread 

### EC_T_CPUSET cpuAffinityMask

[in] CPU affinity to use for the worker thread 

### struct EC_T_MBX_PARMS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMemoryPoolSize

[in] Memory for each slave supporting mailbox communication to record e.g. the CoE dictionary. The memory is asynchronously increased by dwBufferSize by the WorkerThread when it is over 80% full. 0: defaults to 1kb 

### [EC_T_MBX_PARMS_COE](api_general.html.md#_CPPv418EC_T_MBX_PARMS_COE) Coe

[in] CoE parameters 

### [EC_T_MBX_PARMS_FOE](api_general.html.md#_CPPv418EC_T_MBX_PARMS_FOE) Foe

[in] FoE parameters 

### struct EC_T_MBX_PARMS_COE

### Public Members

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDisableNotifications

[in] Disable all CoE related EC_NOTIFY_MBOXRCV notifications 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDisableODStorage

[in] Disable storage of CoE objects in the internal object dictionary 

### struct EC_T_MBX_PARMS_FOE

### Public Members

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDisableNotifications

[in] Disable all FoE related EC_NOTIFY_MBOXRCV notifications 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDisableFileStorage

[in] Disable storage of FoE transfers as a file on the file system 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxQueuedMbxTransfers

[in] Maximum number of queued single FoE mailbox transfers that be used as a file write buffer. 0: defaults to 32. 

## emonDeinitMonitor

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonDeinitMonitor([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceId)

Deinitialize EC-Monitor. 

Waits for pending API calls if [emonInitMonitor()](api_general.html.md#d2/d0b/_ec_monitor_api_8cpp_1a7dc0c3962d2aeefb169778c0d6bba4b7) was called with [EC_T_MONITOR_INIT_PARMS::bApiLockByApp](api_general.html.md#d5/de9/struct_e_c___t___m_o_n_i_t_o_r___i_n_i_t___p_a_r_m_s_1a6ce066754aae58192d92885cc3932240) = EC_FALSE (default).

* **Parameters:**
  **dwInstanceId** – [in] Instance ID 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonConfigureNetwork

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonConfigureNetwork([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_CNF_TYPE](api_general.html.md#_CPPv413EC_T_CNF_TYPE) eCnfType, [EC_T_PBYTE](api.html.md#_CPPv410EC_T_PBYTE) pbyCnfData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCnfDataLen)

Configure the Network. 

This function must be called after the initialization. Among others the EtherCAT topology defined in the given XML configuration file will be stored internally. 

#### NOTE
A client must not be registered prior to calling this function. Existing client registrations will be dropped.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **eCnfType** – [in] Type of configuration data provided 
  * **pbyCnfData** – [in] Filename / configuration data, or EC_NULL if eCnfType is  eCnfType_GenEBI 
  * **dwCnfDataLen** – [in] Length of configuration data in byte, or zero if eCnfType is  eCnfType_GenEBI 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized or eCnfType is eCnfType_GenPreopENI or eCnfType_GenOpENI and link is disconnected
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or pParms is EC_NULL contains some values out of range
  * [EC_E_LINK_DISCONNECTED](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8dac899f16df522b9c6754c7d8d0fb72) if link is disconnected
  * [EC_E_FEATURE_DISABLED](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gab1113b4cdd40bec6cddbd07d8780ff8a) if a configured feature is not included in the license key
  * [EC_E_NOTSUPPORTED](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga11f77305fb1d3868539a735298cc7864) if a configured feature is not supported (e.g not compiled in the library)
  * [EC_E_CFGFILENOTFOUND](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga7da2ce5dd71f5dbc9c5b37ced65de133) if the ENI file cannot be found
  * [EC_E_WRONG_FORMAT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga7ef775b882e22c0ac3ff95e8f0b5fb53) if format errors have been detected in the ENI or EEPROM in case of eCnfType_GenPreopENI or eCnfType_GenOpENI
  * [EC_E_OEM_SIGNATURE_MISMATCH](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gaa9c0e78be6f5d34aa079232c84a9f796) if the OEM signature in the ENI file doesn’t match the used OEM key
  * [EC_E_ENI_ENCRYPTION_WRONG_VERSION](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga5c1f9e38352dc3ac3d458c30be5fa064) if the ENI encryption version is not supported (e.g. the library is too old)
  * [EC_E_ENI_ENCRYPTED](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gae95f45d1e8937074725ff7fe77cbaf12) if the ENI is encrypted and no OEM key has been set
  * [EC_E_XML_CYCCMDS_MISSING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gaefee0a6b4f7097cc1ccdab22e2efccca) if the ENI doesn’t contain cyclic commands
  * [EC_E_XML_ALSTATUS_READ_MISSING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga570d575d0d3bf5ee8e3a11cdd9e09eb2) if the ENI doesn’t contain any read AL status command
  * [EC_E_XML_CYCCMDS_SIZEMISMATCH](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga057e7cdfe426e792a7ab60830d2b3cf7) if the size of the cyclic commands in the ENI mismatch
  * [EC_E_XML_INVALID_INP_OFF](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga26f2972ae26bb55a653adbb40a8fefa0) if some input offsets in the ENI are invalid
  * [EC_E_XML_INVALID_OUT_OFF](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gad32f71e9d681cba85774d28f4416ee00) if some output offsets in the ENI are invalid
  * [EC_E_XML_INVALID_CMD_WITH_RED](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga6bdb2349373a8e935d23521806c4462b) if the ENI contains LRW commands and cable redundancy is configured
  * [EC_E_XML_PREV_PORT_MISSING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga9ad1388e4ca96dcc4cef15851b09b654) if some previous port information are missing in the ENI
  * [EC_E_XML_DC_CYCCMDS_MISSING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga6aa2d4a50dde9e285f7c0f936edbb1d0) if the DC related cyclic commands are missing in the ENI
  * [EC_E_XML_AOE_NETID_INVALID](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga11c2ea29d41ed1e850c4c0e76a0f3b89) if the ENI contains some invalid NetID 

### enum EC_T_CNF_TYPE

*Values:*

### enumerator eCnfType_Unknown

### enumerator eCnfType_Filename

pbyCnfData: ENI filename to read 

### enumerator eCnfType_Data

pbyCnfData: ENI data 

### enumerator eCnfType_Datadiag

pbyCnfData: ENI data for diagnosis 

### enumerator eCnfType_GenPreopENI

Generate ENI based on bus-scan result to get into PREOP state 

### enumerator eCnfType_GenPreopENIWithCRC

Same as eCnfType_GenPreopENI with CRC protection 

### enumerator eCnfType_GenOpENI

Generate ENI based on bus-scan result to get into OP state. The default PDO mapping read from the slaves is activated. See ETG2010 “SII Specification”, Table 14 “Structure Category TXPDO and RXPDO for each PDO”. 

### enumerator eCnfType_None

Reset configuration 

### enumerator eCnfType_ConfigData

pbyCnfData: Binary structured configuration 

### enumerator eCnfType_GenOpENINoStrings

Generate ENI based on bus-scan result to get into OP state, does not read strings from EEPROM 

### enumerator eCnfType_FileByApp

File access provided by user application, See EC_T_CNF_FILEBYAPP_DESC

### enumerator eCnfType_GenEBI

Generate EBI based on bus-scan result 

## emonGetMonitorStatus

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetMonitorStatus([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MONITOR_STATUS](api_general.html.md#_CPPv419EC_T_MONITOR_STATUS) \*pStatus)

Get current Monitor status. 

Information about the current status of the EtherCAT frame / cycle processing

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID 
  * **pStatus** – [out] Monitor status descriptor 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) on success
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if Monitor isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if pStatus invalid 

### struct EC_T_MONITOR_STATUS

### Public Members

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bNextFramesReceived

[out] Indicates whether further unprocessed frames form the next EtherCAT cycle were received 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCyclesProcessed

[out] Number of EtherCAT cycles processed 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wEthTapPositionAutoIncAddr

[out] Ethernet tap position as auto increment address 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bNextCyclicEntryReceived

[out] Indicates whether all frames from the next EtherCAT cycle have been received and have not yet been processed 

### [EC_T_ETHERNET_TAP_TYPE](api_general.html.md#_CPPv422EC_T_ETHERNET_TAP_TYPE) eEthTapType

[out] Type of Ethernet TAP. Detected TAP if [EC_T_MONITOR_INIT_PARMS::eEthTapType](api_general.html.md#d5/de9/struct_e_c___t___m_o_n_i_t_o_r___i_n_i_t___p_a_r_m_s_1a7118d395daa9aa700eefe3a0655d65a1) = eEthTap_AutoDetect is set. 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bTopologyKnown

[out] Topology successfully detected and validated 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bPdoAssigned

[out] PDO assignment of all slaves detected and validated 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bPdoMapped

[out] PDO mapping (SyncSM/FMMU) of all slaves detected and validated 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bPdCommunicationDetected

[out] Process Data communication detected 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wDeviceStatesDetected

[out] Bit mask that indicates which slave states already detected/monitored, see [Slave device state’s](api_general.html.md#dd-dc3-group-d-e-v-i-c-e-s-t-a-t-e-s)

**Slave device state’s**

<!-- -*- mode: rst -*- -->

<a id="dd-dc3-group-d-e-v-i-c-e-s-t-a-t-e-s"></a>

### DEVICE_STATE_UNKNOWN

Slave in unknown state 

### DEVICE_STATE_INIT

Slave in INIT state 

### DEVICE_STATE_PREOP

Slave in PREOP state 

### DEVICE_STATE_BOOTSTRAP

Slave in BOOTSTRAP state 

### DEVICE_STATE_SAFEOP

Slave in SAFEOP state 

### DEVICE_STATE_OP

Slave in OP state 

### DEVICE_STATE_ERROR

Slave in error state 

## emonSetLicenseKey

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonSetLicenseKey([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szLicenseKey)

Sets the license key for the protected version of EC-Master. 

Must be called after initialization and before configuration. This function may not be called if a non protected version is used.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **szLicenseKey** – [in] License key as zero terminated string with 26, 53 or 56 characters 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range
  * [EC_E_INVALIDSIZE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gacd9f0baea7a294f85c3f5bde1543d1d0) if the format of the license key is wrong. The correct length is 26, 53 or 56 characters.
  * [EC_E_LICENSE_MISSING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga810a43bd89a1ef6ffa39af31090ac83e) if the license key doesn’t match the MAC Address 

### Example

```default
dwRes = emonSetLicenseKey(dwInstanceId, "DA1099F2-15C249E9-54327FBC");
if (dwRes != EC_E_NOERROR)
{
    EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "ERROR: Cannot set license key: %s (0x%lx))\n",
        ecatGetText(dwRes), dwRes));
}
```

#### SEE ALSO
- [`emonInitMonitor()`](api_general.html.md#_CPPv415emonInitMonitor10EC_T_DWORDPK23EC_T_MONITOR_INIT_PARMS)
- [`emonConfigureNetwork()`](api_general.html.md#_CPPv420emonConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD)

## emonRegisterClient

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonRegisterClient([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_PF_NOTIFY](api_general.html.md#_CPPv412EC_PF_NOTIFY) pfnNotify, EC_T_VOID \*pCallerData, [EC_T_REGISTERRESULTS](api_general.html.md#_CPPv420EC_T_REGISTERRESULTS) \*pRegResults)

Registers a client on the EC-Master. 

It must be called after configuration, otherwise the registration handle is lost. This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pfnNotify** – [in] Notification callback function. This function will be called every time a state change occurs, an error occurs or a mailbox transfer terminates. 
  * **pCallerData** – [in] Pointer to a caller data area which will be passed to the client on every notification callback 
  * **pRegResults** – [out] Registration results, a pointer to a structure of type [EC_T_REGISTERRESULTS](api_general.html.md#dc/d06/struct_e_c___t___r_e_g_i_s_t_e_r_r_e_s_u_l_t_s)
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or the output pointer is EC_NULL
  * [EC_E_NOMEMORY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga48c2a7b288dc6922a8c0eb116495e1fd) if some memory cannot be allocated 

### typedef [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) (\*EC_PF_NOTIFY)([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCode, [EC_T_NOTIFYPARMS](notification_callback.html.md#_CPPv416EC_T_NOTIFYPARMS) \*pParms)

* **Param dwCode:**
  **[in]** Notification code, see EC_NOTIFY_… 
* **Param pParms:**
  **[in]** Notification code depending data 

### struct EC_T_REGISTERRESULTS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClntId

[out] Client ID 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyPDIn

[out] Pointer to process data input memory 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPDInSize

[out] Size of process data input memory (in bytes) 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyPDOut

[out] Pointer to process data output memory 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPDOutSize

[out] Size of process data output memory (in bytes) 

## emonUnregisterClient

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonUnregisterClient([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClntId)

Unregister a client from the EtherCAT master. 

This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwClntId** – [in] Client ID determined when registering with the master 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonGetSrcMacAddress

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSrcMacAddress([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [ETHERNET_ADDRESS](api_general.html.md#_CPPv416ETHERNET_ADDRESS) \*pMacSrc)

Gets the source MAC address. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMacSrc** – [out] 6-byte buffer to write source MAC address to 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct ETHERNET_ADDRESS

### Public Members

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) b[6]

MAC address 

#### SEE ALSO
[`EC_T_MONITOR_INIT_PARMS::pLinkParms`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS10pLinkParmsE)

## emonExecJob

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonExecJob([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_USER_JOB](api_general.html.md#_CPPv413EC_T_USER_JOB) eUserJob, [EC_T_USER_JOB_PARMS](api_general.html.md#_CPPv419EC_T_USER_JOB_PARMS) \*pUserJobParms)

Execute or initiate the requested job. 

To achieve maximum speed, this function is implemented non re-entrant. It is highly recommended that only one single task is calling all required jobs to run the stack. If multiple tasks are calling this function, the calls have to be synchronized externally. Calling it in a context that doesn’t support operating system calls can lead to unpredictable behavior.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **eUserJob** – [in] User requested job 
  * **pUserJobParms** – [in] Optional user job parameters 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or the output pointer is EC_NULL
  * [EC_E_LINK_DISCONNECTED](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8dac899f16df522b9c6754c7d8d0fb72) if the link is disconnected
  * [EC_E_FEATURE_DISABLED](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gab1113b4cdd40bec6cddbd07d8780ff8a) for eUsrJob_SwitchEoeFrames if EC_IOCTL_SET_EOE_DEFFERED_SWITCHING_ENABLED hasn’t be called before
  * [EC_E_ADS_IS_RUNNING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gac053cb32c9b2bee0305b0644ef76e933) if the ADS server is running 

*Brief job overview:*

### enum EC_T_USER_JOB

*Values:*

### enumerator eUsrJob_Undefined

### enumerator eUsrJob_ProcessAllRxFrames

### enumerator eUsrJob_SendAllCycFrames

### enumerator eUsrJob_MasterTimer

### enumerator eUsrJob_SendAcycFrames

### enumerator eUsrJob_SendCycFramesByTaskId

### enumerator eUsrJob_MasterTimerMinimal

### enumerator eUsrJob_ProcessRxFramesByTaskId

### enumerator eUsrJob_ProcessAcycRxFrames

### enumerator eUsrJob_SwitchEoeFrames

### enumerator eUsrJob_StartTask

### enumerator eUsrJob_StopTask

### enumerator eUsrJob_StampSendAllCycFrames

### enumerator eUsrJob_StampSendCycFramesByTaskId

### enumerator eUsrJob_SimulatorTimer

### enumerator eUsrJob_MonitorTimer

### union EC_T_USER_JOB_PARMS

### Public Members

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bAllCycFramesProcessed

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwNumFramesSent

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTaskIdToSend

### struct [EC_T_USER_JOB_PARMS](api_general.html.md#_CPPv419EC_T_USER_JOB_PARMS)::[\_SEND_CYCFRAME_BY_TASKID](api_general.html.md#_CPPv4N19EC_T_USER_JOB_PARMS24_SEND_CYCFRAME_BY_TASKIDE) SendCycFramesByTaskId

### struct [EC_T_USER_JOB_PARMS](api_general.html.md#_CPPv419EC_T_USER_JOB_PARMS)::[\_PROCESS_RXFRAME_BY_TASKID](api_general.html.md#_CPPv4N19EC_T_USER_JOB_PARMS26_PROCESS_RXFRAME_BY_TASKIDE) ProcessRxFramesByTaskId

### struct [EC_T_USER_JOB_PARMS](api_general.html.md#_CPPv419EC_T_USER_JOB_PARMS)::[\_SWITCH_EOE_FRAMES](api_general.html.md#_CPPv4N19EC_T_USER_JOB_PARMS18_SWITCH_EOE_FRAMESE) SwitchEoeFrames

### struct [EC_T_USER_JOB_PARMS](api_general.html.md#_CPPv419EC_T_USER_JOB_PARMS)::[\_START_TASK](api_general.html.md#_CPPv4N19EC_T_USER_JOB_PARMS11_START_TASKE) StartTask

### struct [EC_T_USER_JOB_PARMS](api_general.html.md#_CPPv419EC_T_USER_JOB_PARMS)::[\_STOP_TASK](api_general.html.md#_CPPv4N19EC_T_USER_JOB_PARMS10_STOP_TASKE) StopTask

### struct \_PROCESS_RXFRAME_BY_TASKID

### Public Members

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bCycFramesProcessed

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTaskId

### struct \_SEND_CYCFRAME_BY_TASKID

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTaskId

### struct \_START_TASK

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTaskId

### struct \_STOP_TASK

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTaskId

### struct \_SWITCH_EOE_FRAMES

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxPortsToProcess

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwNumFramesProcessed

*Detailed job description:*

1. [`eUsrJob_ProcessAllRxFrames`](api_general.html.md#_CPPv4N13EC_T_USER_JOB26eUsrJob_ProcessAllRxFramesE)
   : When the Real-time Ethernet Driver operates in polling mode this call will process all currently received frames, when the Real-time Ethernet Driver operates in interrupt mode all received frames are processed immediately and this call just returns with nothing done.
     ```cpp
     pUserJobParms->bAllCycFramesProcessed
     ```
     <br/>
     If this flag is set to a value of [`EC_TRUE`](api.html.md#c.EC_TRUE) it indicates that all previously initiated cyclic frames ( [`eUsrJob_SendAllCycFrames`](api_general.html.md#_CPPv4N13EC_T_USER_JOB24eUsrJob_SendAllCycFramesE) ) are received and processed within this call. Not used if pUserJobParms set to [`EC_NULL`](api.html.md#c.EC_NULL).
     <br/>
     Return: [`EC_E_NOERROR`](error-codes_generic.html.md#c.EC_E_NOERROR) if successful, error code in case of failures.
2. [`eUsrJob_MonitorTimer`](api_general.html.md#_CPPv4N13EC_T_USER_JOB20eUsrJob_MonitorTimerE)
   : To trigger the monitor and SubDevice state machines as well as the mailbox handling this call has to be executed cyclically. The monitor cycle time is determined by the period between calling [`emonExecJob()`](api_general.html.md#_CPPv411emonExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) ( [`eUsrJob_MonitorTimer`](api_general.html.md#_CPPv4N13EC_T_USER_JOB20eUsrJob_MonitorTimerE)). The state-machines are handling the EtherCAT® state change transfers.
     <br/>
     Return: [`EC_E_NOERROR`](error-codes_generic.html.md#c.EC_E_NOERROR) if successful, error code in case of failures.

## emonGetMonitorParms

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetMonitorParms([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MONITOR_INIT_PARMS](api_general.html.md#_CPPv423EC_T_MONITOR_INIT_PARMS) \*pParms, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwParmsBufSize)

Gets current Monitor Init Parameters. 

If the given buffer is larger than the actual size of the struct [EC_T_MONITOR_INIT_PARMS](api_general.html.md#d5/de9/struct_e_c___t___m_o_n_i_t_o_r___i_n_i_t___p_a_r_m_s), the parameters of [EC_T_MONITOR_INIT_PARMS.pOsParms](api_general.html.md#d5/de9/struct_e_c___t___m_o_n_i_t_o_r___i_n_i_t___p_a_r_m_s_1a1a3d2db383eeee91ae09cd1d22771666), [EC_T_MONITOR_INIT_PARMS.pLinkParms](api_general.html.md#d5/de9/struct_e_c___t___m_o_n_i_t_o_r___i_n_i_t___p_a_r_m_s_1a6fb7e195762e0a52667be9097763d1f8) are appended.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID 
  * **pParms** – [out] Buffer to store parameters 
  * **dwParmsBufSize** – [in] Size of the buffer in bytes 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) on success
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if Monitor isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if buffer pParms is too small 

### Example

```default
/* Read all monitor init parameters, including OS and Link parameters */
EC_T_BYTE abyBuffer[sizeof(EC_T_MONITOR_INIT_PARMS) + sizeof(EC_T_OS_PARMS) + 512 /* LinkLayer parameters */];
EC_T_MONITOR_INIT_PARMS* pParms = (EC_T_MONITOR_INIT_PARMS*)abyBuffer;
OsMemset(abyBuffer, 0, sizeof(abyBuffer));

dwRes = emonGetMonitorParms(dwInstanceId, pParms, sizeof(abyBuffer));
if (EC_E_NOERROR != dwRes)
{
    EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "Cannot get monitor parameters: %s (0x%lx))\n",
        ecatGetText(dwRes), dwRes));
}
```

#### SEE ALSO
[`emonInitMonitor()`](api_general.html.md#_CPPv415emonInitMonitor10EC_T_DWORDPK23EC_T_MONITOR_INIT_PARMS)

## emonSetMonitorParms

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonSetMonitorParms([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_MONITOR_INIT_PARMS](api_general.html.md#_CPPv423EC_T_MONITOR_INIT_PARMS) \*pParms)

Change Monitor Init Parameters. 

OS parms, Main Link parms cannot be changed.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID 
  * **pParms** – [in] New Monitor init parameters 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) on success
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if Monitor isn’t initialized 

#### SEE ALSO
[`emonInitMonitor()`](api_general.html.md#_CPPv415emonInitMonitor10EC_T_DWORDPK23EC_T_MONITOR_INIT_PARMS)

## emonGetVersion

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetVersion([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*pdwVersion, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*pdwVersionType)

Gets the version information. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pdwVersion** – [out] Pointer to EC_T_DWORD to carry out version number as a 32-bit value 
  * **pdwVersionType** – [out] Pointer to EC_T_DWORD to carry out version type. See EC_VERSION_TYPE. 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or the output pointer is EC_NULL 

## emonGetText

### const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*emonGetText([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTextId)

Return text tokens by ID. 

* **Parameters:**
  **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
* **Returns:**
  Textual description of the given ID 

## emonGetMemoryUsage

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetMemoryUsage([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*pdwCurrentUsage, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*pdwMaxUsage)

Returns information about memory usage. 

All calls to malloc/free and new/delete are monitored.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pdwCurrentUsage** – [out] Current memory usage in Bytes at the time where this function is called 
  * **pdwMaxUsage** – [out] Maximum memory usage in Bytes since initialization at the time where this function is called 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonGetMasterState

### [EC_T_STATE](api_general.html.md#_CPPv410EC_T_STATE) emonGetMasterState([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)

Get the EtherCAT master current state. 

* **Parameters:**
  **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
* **Returns:**
  EtherCAT master state 

### enum EC_T_STATE

*Values:*

### enumerator eEcatState_UNKNOWN

### enumerator eEcatState_INIT

### enumerator eEcatState_PREOP

### enumerator eEcatState_SAFEOP

### enumerator eEcatState_OP

### enumerator eEcatState_BOOTSTRAP

## emonGetMasterStateEx

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetMasterStateEx([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwCurrState, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwReqState)

Get the EtherCAT master current and requested state. Possible return values for current and requested state: 

* [DEVICE_STATE_UNKNOWN](api_general.html.md#dd/dc3/group___d_e_v_i_c_e___s_t_a_t_e_s_1ga33b90f5429fe46ff40e374be0d64c76b)
* [DEVICE_STATE_INIT](api_general.html.md#dd/dc3/group___d_e_v_i_c_e___s_t_a_t_e_s_1ga2a184454821e98410d522211abc6e136)
* [DEVICE_STATE_PREOP](api_general.html.md#dd/dc3/group___d_e_v_i_c_e___s_t_a_t_e_s_1ga0b667c3c6c197200043dde1cc401e5e1)
* [DEVICE_STATE_SAFEOP](api_general.html.md#dd/dc3/group___d_e_v_i_c_e___s_t_a_t_e_s_1ga185291cf09a7d9dd5dfa8461d90e39c7)
* [DEVICE_STATE_OP](api_general.html.md#dd/dc3/group___d_e_v_i_c_e___s_t_a_t_e_s_1ga9e6fe68bf128d21867c80f053b29a76a)

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pwCurrState** – [out] Current master state 
  * **pwReqState** – [out] Requested master state 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or the output pointers are EC_NULL 

## emonFindInpVarByName - “Inputs.DevicesState”

The device status of all SubDevices (OR-linked) is part of the process data with name “Inputs.DevicesState”.

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [emonFindInpVarByName](api_processdata.html.md#_CPPv420emonFindInpVarByName10EC_T_DWORDPK9EC_T_CHARP21EC_T_PROCESS_VAR_INFO)([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO](api_slave.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pProcessVarInfoEntry)

## emonFindInpVarByName - “Inputs.BusTime”

The DC system time (written to ESC register 0x0910) is part of the process data with name “Inputs.BusTime”.

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [emonFindInpVarByName](api_processdata.html.md#_CPPv420emonFindInpVarByName10EC_T_DWORDPK9EC_T_CHARP21EC_T_PROCESS_VAR_INFO)([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO](api_slave.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pProcessVarInfoEntry)

## emonExportEniBuilderConfig

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonExportEniBuilderConfig([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szFileName)

Export an EniBuilder file describing the observed network topology. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID 
  * **szFileName** – [in] null-terminated export file path 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) on success
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if parameter file name invalid
  * [EC_E_OPENFAILED](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga7f5b8a45f69094fd6f1b05aa204c6b8e) if file could not be opened
  * [EC_E_NOMEMORY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga48c2a7b288dc6922a8c0eb116495e1fd) if not enough memory available 

#### SEE ALSO
[Operation without ENI](integration_genebi.html.md#operation-without-eni)

## emonIoCtl

With `emonIoCtl` a generic control interface exists between the application and the EC-Monitor and its Real-time Ethernet Drivers.

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonIoCtl([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCode, const EC_T_VOID \*const pbyInBuf, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInBufSize, EC_T_VOID \*const pbyOutBuf, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwOutBufSize, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*const pdwNumOutData)

A generic control interface between the application, the EtherCAT stack and its Link Layers. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwCode** – [in] IOCTL code (EC_IOCTL…) 
  * **pbyInBuf** – [in] IOCTL input parameters 
  * **dwInBufSize** – [in] Size of IOCTL input parameters in bytes 
  * **pbyOutBuf** – [out] Buffer for IOCTL output 
  * **dwOutBufSize** – [in] Size of buffer at pbyOutBuf in bytes 
  * **pdwNumOutData** – [out] Amount of bytes written to pbyOutBuf by IOCTL. EC_NULL: amount not set by IOCTL. 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range, the input pointer is EC_NULL or contains EC_NULL pointer
  * [EC_E_NOMEMORY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga48c2a7b288dc6922a8c0eb116495e1fd) if memory cannot be allocated
  * [EC_E_ADS_IS_RUNNING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gac053cb32c9b2bee0305b0644ef76e933) if the ADS server is running 

## emonIoCtl - EC_IOCTL_REGISTER_CYCFRAME_RX_CB

### EC_IOCTL_REGISTER_CYCFRAME_RX_CB

Register callback for all cyclic frames received. Typically this is used when the Real-time Ethernet Driver operates in interrupt mode to get an event when the new input data (cyclic frame) is available. The callback function has to be registered after the stack initialization and before starting the job task. 

* **Parameters:**
  * **pbyInBuf** – [in] Cyclic frame received callback descriptor ([EC_T_CYCFRAME_RX_CBDESC](api_general.html.md#dd/dff/struct_e_c___t___c_y_c_f_r_a_m_e___r_x___c_b_d_e_s_c)) 
  * **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes 
  * **pbyOutBuf** – [out] Should be set to EC_NULL 
  * **dwOutBufSize** – [in] Should be set to 0 
  * **pdwNumOutData** – [out] Should be set to EC_NULL 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_CYCFRAME_RX_CBDESC

### Public Members

### EC_T_VOID \*pCallbackContext

[in] Context pointer. This pointer is used as parameter every time the callback function is called. 

### [EC_PF_CYCFRAME_RECV](api_general.html.md#_CPPv419EC_PF_CYCFRAME_RECV) pfnCallback

[in] This function will be called after the cyclic frame is received, if there is more than one cyclic frame after the last frame. The application has to assure that these functions will not block. 

### typedef EC_T_VOID (\*EC_PF_CYCFRAME_RECV)([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTaskId, EC_T_VOID \*pvContext)

* **Param dwTaskId:**
  [in] Task id of the received cyclic frame 
* **Param pvContext:**
  [in] Context pointer. This pointer is used as parameter every time when the callback function is called. 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonIoCtl - EC_IOCTL_GET_CYCLIC_CONFIG_INFO

### EC_IOCTL_GET_CYCLIC_CONFIG_INFO

Get cyclic configuration information from ENI file. 

* **Parameters:**
  * **pbyInBuf** – [in] Pointer to dwCycEntryIndex: Cyclic entry index for which to get information 
  * **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes 
  * **pbyOutBuf** – [out] Pointer to [EC_T_CYC_CONFIG_DESC](api_general.html.md#d2/d75/struct_e_c___t___c_y_c___c_o_n_f_i_g___d_e_s_c) data type 
  * **dwOutBufSize** – [in] Size of the output buffer provided at pbyOutBuf in bytes 
  * **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_CYC_CONFIG_DESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwNumCycEntries

[out] Total number of cyclic entries 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTaskId

[out] Task ID of selected cyclic entry (ENI: Cyclic/TaskId) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPriority

[out] Priority of selected cyclic entry 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCycleTime

[out] Cycle time of selected cyclic entry 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonIoCtl - EC_IOCTL_IS_SLAVETOSLAVE_COMM_CONFIGURED

### EC_IOCTL_IS_SLAVETOSLAVE_COMM_CONFIGURED

Determine if any slave to slave communication is configured. 

* **Parameters:**
  * **pbyInBuf** – [in] Should be set to EC_NULL 
  * **dwInBufSize** – [in] Should be set to 0 
  * **pbyOutBuf** – [out] Pointer to EC_T_DWORD. If value is EC_TRUE slave to slave communication is configured, if EC_FALSE it is not. 
  * **dwOutBufSize** – [in] Size of the output buffer in bytes 
  * **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)


# api_hotconnect.html.md

# Hot Connect

## emonHCGetNumGroupMembers

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonHCGetNumGroupMembers([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwGroupIndex)

Get number of slaves belonging to a specific Hot-Connect group. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwGroupIndex** – [in] Index of Hot-Connect group, 0 is the mandatory group 
* **Returns:**
  Number of slaves 

## emonHCGetSlaveIdsOfGroup

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonHCGetSlaveIdsOfGroup([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwGroupIndex, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*adwSlaveId, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxNumSlaveIds)

Get a list of Slave ID’s belonging to a specific Hot-Connect group. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwGroupIndex** – [in] Index of Hot-Connect group, 0 is the mandatory group 
  * **adwSlaveId** – [out] Preallocated Slave ID list buffer 
  * **dwMaxNumSlaveIds** – [in] Size of Slave ID list buffer 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonNotify - EC_NOTIFY_HC_DETECTADDGROUPS

This notification is raised when HotConnect group detection is finished, after SubDevice addition.

**emonNotify - EC_NOTIFY_HC_DETECTADDGROUPS**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to notification descriptor EC_T_HC_DETECTALLGROUP_NTFY_DESC
    * `dwInBufSize`: [in] sizeof(EC_T_HC_DETECTALLGROUP_NTFY_DESC)
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

### struct EC_T_HC_DETECTALLGROUP_NTFY_DESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwResultCode

Result of Group detection 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwGroupCount

Total number of Groups 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwGroupsPresent

Number of connected groups 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwGroupMask

Bitmask of first 32 Groups. 1 = present, 0 = absent. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) adwGroupMask[100]

Bitmask of first 3200 Groups 

## emonNotify - EC_NOTIFY_HC_PROBEALLGROUPS

This notification is raised when HotConnect Group Detection is finished, after SubDevice Disappearance.

**emonNotify - EC_NOTIFY_HC_PROBEALLGROUPS**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to notification descriptor EC_T_HC_DETECTALLGROUP_NTFY_DESC
    * `dwInBufSize`: [in] sizeof(EC_T_HC_DETECTALLGROUP_NTFY_DESC)
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

### struct [EC_T_HC_DETECTALLGROUP_NTFY_DESC](api_hotconnect.html.md#_CPPv432EC_T_HC_DETECTALLGROUP_NTFY_DESC)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwResultCode](api_hotconnect.html.md#_CPPv4N32EC_T_HC_DETECTALLGROUP_NTFY_DESC12dwResultCodeE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwGroupCount](api_hotconnect.html.md#_CPPv4N32EC_T_HC_DETECTALLGROUP_NTFY_DESC12dwGroupCountE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwGroupsPresent](api_hotconnect.html.md#_CPPv4N32EC_T_HC_DETECTALLGROUP_NTFY_DESC15dwGroupsPresentE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwGroupMask](api_hotconnect.html.md#_CPPv4N32EC_T_HC_DETECTALLGROUP_NTFY_DESC11dwGroupMaskE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [adwGroupMask](api_hotconnect.html.md#_CPPv4N32EC_T_HC_DETECTALLGROUP_NTFY_DESC12adwGroupMaskE)[100]

## emonNotify - EC_NOTIFY_HC_TOPOCHGDONE

This notification is raised when HotConnect has completely processed a topology change.

**emonNotify - EC_NOTIFY_HC_TOPOCHGDONE**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_DWORD (EC_E_NOERROR on success, Error code otherwise)
    * `dwInBufSize`: [in] sizeof(EC_T_DWORD)
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

The notification is raised when the SubDevices reached the current bus state.


# api_linklayer.html.md

# Real-time Ethernet Driver Control Interface

## emonIoCtl - EC_IOCTL_ISLINK_CONNECTED

### EC_IOCTL_ISLINK_CONNECTED

Determine whether the main link or redundancy link is connected. 

#### NOTE
See also EC_IOCTL_IS_MAIN_LINK_CONNECTED, EC_IOCTL_IS_RED_LINK_CONNECTED 

* **Parameters:**
  * **pbyInBuf** – [in] Should be set to EC_NULL 
  * **dwInBufSize** – [in] Should be set to 0 
  * **pbyOutBuf** – [out] Pointer to EC_T_DWORD or [EC_T_LINK_CONNECTED_INFO](api_linklayer.html.md#d9/d56/struct_e_c___t___l_i_n_k___c_o_n_n_e_c_t_e_d___i_n_f_o). EC_T_DWORD: If value is EC_TRUE link is connected, if EC_FALSE it is not. 
  * **dwOutBufSize** – [in] Size of the output buffer in bytes (sizeof(EC_T_DWORD) / sizeof(EC_T_LINK_CONNECTED_INFO)) 
  * **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_LINK_CONNECTED_INFO

### Public Members

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bConnected

[out] MAIN or RED link detected 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bSendEnabled

[out] Send enabled on MAIN or RED 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bMainConnected

[out] MAIN link detected 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bMainMasked

[out] MAIN link not used for sending, because topology changed delay not elapsed yet 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bRedConnected

[out] RED link detected 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bRedMasked

[out] RED link not used for sending, because topology changed delay not elapsed yet 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonIoCtl - EC_IOCTL_GET_LINKLAYER_MODE

### EC_IOCTL_GET_LINKLAYER_MODE

Get Real-time Ethernet Driver mode (EcLinkMode_POLLING, EcLinkMode_INTERRUPT) 

* **Parameters:**
  * **pbyInBuf** – [in] Should be set to EC_NULL 
  * **dwInBufSize** – [in] Should be set to 0 
  * **pbyOutBuf** – [out] Pointer to struct [EC_T_LINKLAYER_MODE_DESC](api_linklayer.html.md#db/d79/struct_e_c___t___l_i_n_k_l_a_y_e_r___m_o_d_e___d_e_s_c)
  * **dwOutBufSize** – [in] Size of the output buffer in bytes 
  * **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_LINKLAYER_MODE_DESC

### Public Members

### EC_T_LINKMODE eLinkMode

[out] Operation mode of main interface 

### EC_T_LINKMODE eLinkModeRed

[out] Operation mode of redundancy interface 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonIoCtl - EC_LINKIOCTL…

The generic control interface provides access to the main network adapter when adding `EC_IOCTL_LINKLAYER_MAIN` to the `EC_LINKIOCTL` parameter at dwCode.

```cpp
EC_T_DWORD dwCode = (EC_IOCTL_LINKLAYER_MAIN | EC_LINKIOCTL_GET_ETHERNET_ADDRESS);
```

## emonIoCtl - EC_LINKIOCTL_GET_ETHERNET_ADDRESS

Provides MAC addresses of main or red line.

**emonIoCtl - EC_LINKIOCTL_GET_ETHERNET_ADDRESS**
: **Parameter**
  : * `pbyInBuf`: [in] Should be set to EC_NULL
    * `dwInBufSize`: [in] Should be set to 0
    * `pbyOutBuf`: [out] Pointer to MAC address buffer (6 bytes)
    * `dwOutBufSize`: [in] Size of the output buffer in bytes (at least 6)
    * `pdwNumOutData`: [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonIoCtl - EC_LINKIOCTL_GET_SPEED

**emonIoCtl - EC_LINKIOCTL_GET_SPEED**
: **Parameter**
  : * `pbyInBuf`: [in] Should be set to EC_NULL
    * `dwInBufSize`: [in] Should be set to 0
    * `pbyOutBuf`: [out] Pointer to EC_T_DWORD. Set by Real-time Ethernet Driver to 10/100/1000.
    * `dwOutBufSize`: [in] Size of the output buffer in bytes
    * `pdwNumOutData`: [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)


# api_mbx.html.md

# EtherCAT® Mailbox Transfer

To be able to initiate a mailbox transfer the client has to create a mailbox transfer object first.
This mailbox transfer object also contains the memory where the data to be transferred is stored.
The one client that initiated the mailbox transfer will be notified about a mailbox transfer completion by the `emonNotify()` callback function.

To be able to identify the transfer which was completed the client has to assign a unique transfer identifier for each mailbox transfer.
The mailbox transfer object can only be used for one single mailbox transfer.
If multiple transfers shall be initiated in parallel the client has to create one transfer object for each.
The transfer object can be re-used after mailbox transfer completion.

Typical mailbox transfer sequence:

1. Record a mailbox transfer.
2. Create a transfer object (for example an SDO download transfer object).
   : ```cpp
     MbxTferDesc.dwMaxDataLen = 10
     <br/>
     MbxTferDesc.pbyMbxTferDescData = (EC_T_PBYTE)OsMalloc(MbxTferDesc.dwMaxDataLen)
     <br/>
     pMbxTfer = emonMbxTferCreate(&MbxTferDesc)
         state of the transfer object = Idle
     ```
3. Set the location to write the transferred data to, determine the transfer ID, store the client ID in the object and initiate the transfer (e.g. a SDO upload). A transfer may only be initiated if the state of the transfer object is Idle.
   : ```cpp
     pMbxTfer->dwDataLen = MbxTferDesc.dwMaxDataLen;
     <br/>
     pMbxTfer->pbyMbxTferData = MbxTferDesc.pbyMbxTferDescData
     <br/>
     pMbxTfer->dwTferId = 1;
     <br/>
     pMbxTfer->dwClntId = dwClntId;
     <br/>
     <br/>
     dwResult = emonCoeSdoUplodadReq(pMbxTfer, dwSlaveId, wObIndex, ...);
         state of the transfer object = Pend or TferReqError
     ```
     <br/>
     The state will then be set to Pend to indicate that this mailbox transfer object currently is in use and the transfer is not completed.
     If the mailbox transfer cannot be initiated the MainDevice will set the object into the state TferReqError - in such cases the client
     is responsible to set the state back into Idle.
4. If the mailbox transfer is completed the notification callback function of the corresponding client ( `emonNotify()`) will be called with a pointer to the mailbox transfer object. The state of the transfer object is set to TferDone prior to calling `emonNotify()`.
   : ```cpp
     if( dwResult != EC_E_NOERROR ) { ... }
     <br/>
     emonNotify( EC_NOTIFY_MBOXRCV, pParms )
         state of the transfer object = TferDone
     ```
5. In case of errors the appropriate error handling has to be executed. The application must set the transfer object state to Idle.
   : ```cpp
     if( pMbxTfer->dwErrorCode != EC_E_NOERROR ) { ... }
         In emonNotify: application may set transfer object state to Idle
     ```
6. Delete the transfer object. Alternatively this object can be used for the next transfer.
   : ```cpp
     emonMbxTferDelete(pMbxTfer);
     ```

## Mailbox transfer object states

The following states exist for a mailbox transfer object:

### enum EC_T_MBXTFER_STATUS

*Values:*

### enumerator eMbxTferStatus_Idle

Mailbox transfer object not in use 

### enumerator eMbxTferStatus_Pend

Mailbox transfer in process 

### enumerator eMbxTferStatus_TferDone

Mailbox transfer completed 

### enumerator eMbxTferStatus_TferReqError

Mailbox transfer request error 

### enumerator eMbxTferStatus_TferWaitingForContinue

Mailbox transfer waiting for continue, object owned by application 

A mailbox transfer will be processed by the monitor independently from the client’s timeout setting.
Some types of mailbox transfers can be cancelled by the client, e.g. if the client’s timeout elapsed.

After completion of the mailbox transfer (with timeout) the client may finally set the transfer object into
the state [`EC_T_MBXTFER_STATUS::eMbxTferStatus_Idle`](api_mbx.html.md#_CPPv4N19EC_T_MBXTFER_STATUS19eMbxTferStatus_IdleE).
New mailbox transfers can only be requested if the object is in the state [`EC_T_MBXTFER_STATUS::eMbxTferStatus_Idle`](api_mbx.html.md#_CPPv4N19EC_T_MBXTFER_STATUS19eMbxTferStatus_IdleE).

## emonMbxTferCreate

### [EC_T_MBXTFER](api_mbx.html.md#_CPPv412EC_T_MBXTFER) \*emonMbxTferCreate([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER_DESC](api_mbx.html.md#_CPPv417EC_T_MBXTFER_DESC) \*pMbxTferDesc)

Creates a mailbox transfer object. 

While a mailbox transfer is in process the related transfer object and the corresponding memory may not be accessed. After a mailbox transfer completion the object may be used for the next transfer. The mailbox transfer object has to be deleted by calling ecatMbxTferDelete if it is not needed any more.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTferDesc** – [in] Pointer to the mailbox transfer descriptor. Determines details of the mailbox transfer. 
* **Returns:**
  * Pointer to the created mailbox transfer object if successful
  * EC_NULL on error (No memory left) 

### struct EC_T_MBXTFER_DESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxDataLen

Maximum amount of data bytes that shall be transferred using this object. A mailbox transfer type without data transfer will ignore this parameter. 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyMbxTferDescData

Pointer to byte stream carrying in and out data of mailbox content 

### struct EC_T_MBXTFER

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClntId

[] Client ID 

### [EC_T_MBXTFER_DESC](api_mbx.html.md#_CPPv417EC_T_MBXTFER_DESC) MbxTferDesc

[out] Mailbox transfer descriptor. All elements of pMbxTferDesc will be stored here. 

### [EC_T_MBXTFER_TYPE](api_mbx.html.md#_CPPv417EC_T_MBXTFER_TYPE) eMbxTferType

[] This type of information is written to the Mailbox Transfer Object by the last call to a mailbox command function. It may be used as information, and is required to fan out consecutive notifications. This value is only valid until the next relevant mailbox API call, where this value may be overwritten. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDataLen

[] Amount of data bytes for the next mailbox download transfer. If the mailbox transfer does not transfer data to the slave this parameter will be ignored. This element has to be set to an appropriate value every time prior to initiating a new download request. When either a download or upload transfer is completed (emNotify) this value will contain the amount of data that was actually transferred. 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyMbxTferData

[in/out] Pointer to data. In case of a download transfer the client has to store the data in this location. In case of an upload transfer this element points to the received data. Access to data that was uploaded from a slave is only valid within the notification function because the buffer will be re-used by the master. These data have to be copied into a separate buffer in case it has to be used later by the client. 

### [EC_T_MBXTFER_STATUS](api_mbx.html.md#_CPPv419EC_T_MBXTFER_STATUS) eTferStatus

[out] Transfer state. After a new transfer object is created the state will be set to eMbxTferStatus_Idle. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwErrorCode

[out] Error code of a mailbox transfer that was terminated with error 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTferId

[] Transfer ID. For every new mailbox transfer a unique ID has to be assigned. This ID can be used after mailbox transfer completion to identify the transfer. 

### [EC_T_MBX_DATA](api_mbx.html.md#_CPPv413EC_T_MBX_DATA) MbxData

[] Mailbox data. This element contains mailbox transfer data, e.g. the CoE object dictionary list. 

### enum EC_T_MBXTFER_TYPE

*Values:*

### enumerator eMbxTferType_COE_SDO_DOWNLOAD

CoE SDO download 

### enumerator eMbxTferType_COE_SDO_UPLOAD

CoE SDO upload 

### enumerator eMbxTferType_COE_GETODLIST

CoE Get object dictionary list 

### enumerator eMbxTferType_COE_GETOBDESC

CoE Get object description 

### enumerator eMbxTferType_COE_GETENTRYDESC

CoE Get object entry description 

### enumerator eMbxTferType_COE_EMERGENCY

CoE emergency request 

### enumerator eMbxTferType_COE_RX_PDO

CoE RxPDO 

### enumerator eMbxTferType_FOE_FILE_UPLOAD

FoE upload 

### enumerator eMbxTferType_FOE_FILE_DOWNLOAD

FoE download 

### enumerator eMbxTferType_SOE_READREQUEST

SoE read request 

### enumerator eMbxTferType_SOE_READRESPONSE

SoE read response 

### enumerator eMbxTferType_SOE_WRITEREQUEST

SoE write request 

### enumerator eMbxTferType_SOE_WRITERESPONSE

SoE write response 

### enumerator eMbxTferType_SOE_NOTIFICATION

SoE notification 

### enumerator eMbxTferType_SOE_EMERGENCY

SoE emergency 

### enumerator eMbxTferType_VOE_MBX_READ

VoE read 

### enumerator eMbxTferType_VOE_MBX_WRITE

VoE write 

### enumerator eMbxTferType_AOE_READ

AoE read 

### enumerator eMbxTferType_AOE_WRITE

AoE write 

### enumerator eMbxTferType_AOE_READWRITE

AoE read/write 

### enumerator eMbxTferType_AOE_WRITECONTROL

AoE write control 

### enumerator eMbxTferType_RAWMBX

Raw mbx 

### enumerator eMbxTferType_FOE_SEG_DOWNLOAD

FoE segmented download 

### enumerator eMbxTferType_FOE_SEG_UPLOAD

FoE segmented upload 

### enumerator eMbxTferType_S2SMBX

S2S mbx 

### enumerator eMbxTferType_FOE_UPLOAD_REQ

FoE upload request 

### enumerator eMbxTferType_FOE_DOWNLOAD_REQ

FoE download request 

### enumerator eMbxTferType_EOE_SEND_FRAME

EoE send frame 

### enumerator eMbxTferType_EOE_RECEIVE_FRAME

EoE receive frame 

### enumerator eMbxTferType_EOE_SET_IP

EoE set IP address 

### union EC_T_MBX_DATA

 *#include <EcInterfaceCommon.h>*

### Public Members

### EC_T_AOE_CMD_RESPONSE AoE_Response

AoE 

### [EC_T_MBX_DATA_COE](api_mbx_coe.html.md#_CPPv417EC_T_MBX_DATA_COE) CoE

CoE 

### [EC_T_COE_ODLIST](api_mbx_coe.html.md#_CPPv415EC_T_COE_ODLIST) CoE_ODList

CoE Object Dictionary list 

### EC_T_COE_OBDESC CoE_ObDesc

CoE object description 

### [EC_T_COE_ENTRYDESC](api_mbx_coe.html.md#_CPPv418EC_T_COE_ENTRYDESC) CoE_EntryDesc

CoE entry description 

### [EC_T_COE_EMERGENCY](api_mbx_coe.html.md#_CPPv418EC_T_COE_EMERGENCY) CoE_Emergency

CoE emergency data 

### EC_T_MBX_DATA_COE_INITCMD CoE_InitCmd

CoE InitCmd 

### [EC_T_MBX_DATA_FOE](api_mbx_foe.html.md#_CPPv417EC_T_MBX_DATA_FOE) FoE

FoE 

### [EC_T_MBX_DATA_FOE_REQ](api_mbx_foe.html.md#_CPPv421EC_T_MBX_DATA_FOE_REQ) FoE_Request

FoE request 

### EC_T_MBX_DATA_SOE SoE

SoE 

### EC_T_SOE_NOTIFICATION SoE_Notification

SoE notification request 

### EC_T_SOE_EMERGENCY SoE_Emergency

SoE emergency request 

## emonMbxTferAbort

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonMbxTferAbort([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER](api_mbx.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer)

Abort a running mailbox transfer. 

This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer object created with emMbxTferCreate 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful 

Currently only supported for FoE Transfer, CoE Download and CoE Upload.

## emonMbxTferDelete

### EC_T_VOID emonMbxTferDelete([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER](api_mbx.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer)

Deletes a mailbox transfer object. 

A transfer object may only be deleted if it is in the Idle state.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer object created with emMbxTferCreate 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonNotify - EC_NOTIFY_MBOXRCV

Indicates a mailbox transfer completion.

**emonNotify - EC_NOTIFY_MBOXRCV**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to a structure of type EC_T_MBXTFER, containing the corresponding mailbox transfer object
    * `dwInBufSize`: [in] Size of the transfer object provided at pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

The element [`EC_T_MBXTFER::dwClntId`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER8dwClntIdE) contains the corresponding ID of the client that is notified, the corresponding transfer ID can be found in [`EC_T_MBXTFER::dwTferId`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER8dwTferIdE). The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE).

On error [`EC_T_MBXTFER::eTferStatus`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER11eTferStatusE) is [`eMbxTferStatus_TferReqError`](api_mbx.html.md#_CPPv4N19EC_T_MBXTFER_STATUS27eMbxTferStatus_TferReqErrorE), on success [`eMbxTferStatus_TferDone`](api_mbx.html.md#_CPPv4N19EC_T_MBXTFER_STATUS23eMbxTferStatus_TferDoneE). In order to reuse the transfer object the application must set it back to [`eMbxTferStatus_Idle`](api_mbx.html.md#_CPPv4N19EC_T_MBXTFER_STATUS19eMbxTferStatus_IdleE).

The [`EC_T_MBXTFER::eMbxTferType`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER12eMbxTferTypeE) element determines the mailbox transfer type (e.g. [`eMbxTferType_COE_SDO_DOWNLOAD`](api_mbx.html.md#_CPPv4N17EC_T_MBXTFER_TYPE29eMbxTferType_COE_SDO_DOWNLOADE) for a completion of a CoE SDO download transfer).

## emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR

Indicates a WKC error during a mailbox write. Detailed error information is stored in structure [`EC_T_WKCERR_DESC`](notification_error.html.md#_CPPv416EC_T_WKCERR_DESC) which is part of [`EC_T_ERROR_NOTIFICATION_DESC`](notification_error.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).

**emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_ERROR_NOTIFICATION_DESC
    * `dwInBufSize`: [in] Size of the error description provided at pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

## emonNotify - EC_NOTIFY_AOE_MBXSND_WKC_ERROR

See [emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR](api_mbx.html.md#emonnotify-ec-notify-coe-mbxsnd-wkc-error)

## emonNotify - EC_NOTIFY_EOE_MBXSND_WKC_ERROR

See [emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR](api_mbx.html.md#emonnotify-ec-notify-coe-mbxsnd-wkc-error)

## emonNotify - EC_NOTIFY_FOE_MBXSND_WKC_ERROR

See [emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR](api_mbx.html.md#emonnotify-ec-notify-coe-mbxsnd-wkc-error)

## emonNotify - EC_NOTIFY_SOE_MBXSND_WKC_ERROR

See [emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR](api_mbx.html.md#emonnotify-ec-notify-coe-mbxsnd-wkc-error)

## emonNotify - EC_NOTIFY_VOE_MBXSND_WKC_ERROR

See [emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR](api_mbx.html.md#emonnotify-ec-notify-coe-mbxsnd-wkc-error)


# api_mbx_coe.html.md

# CAN application protocol over EtherCAT® (CoE)

The EC-Monitor can forward CoE transfers to the application in real time via the notifications [emonNotify - eMbxTferType_COE_SDO_DOWNLOAD](api_mbx_coe.html.md#emonnotify-embxtfertype-coe-sdo-download), [emonNotify - eMbxTferType_COE_SDO_UPLOAD](api_mbx_coe.html.md#emonnotify-embxtfertype-coe-sdo-upload) and [emonNotify - eMbxTferType_COE_EMERGENCY](api_mbx_coe.html.md#coe-emergency-emonnotify-embxtfertype-coe-emergency).

There is also the option of storing the recorded data from the CoE transfers in an internal object dictionary.
This object dictionary is structured analogously to that from the SubDevices and can be read out via the functions [`emonCoeSdoUpload()`](api_mbx_coe.html.md#_CPPv416emonCoeSdoUpload10EC_T_DWORD10EC_T_DWORD9EC_T_WORD9EC_T_BYTEP9EC_T_BYTE10EC_T_DWORDP10EC_T_DWORD10EC_T_DWORD10EC_T_DWORD) / [`emonCoeSdoUploadReq()`](api_mbx_coe.html.md#_CPPv419emonCoeSdoUploadReq10EC_T_DWORDP12EC_T_MBXTFER10EC_T_DWORD9EC_T_WORD9EC_T_BYTE10EC_T_DWORD10EC_T_DWORD) and [`emonCoeGetODListReq()`](api_mbx_coe.html.md#_CPPv419emonCoeGetODListReq10EC_T_DWORDP12EC_T_MBXTFER10EC_T_DWORD20EC_T_COE_ODLIST_TYPE10EC_T_DWORD).

The notifications for CoE can be deactivated using the [`EC_T_MBX_PARMS_COE::bDisableNotifications`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_COE21bDisableNotificationsE) parameter if they are not required or to save computing time.
In order to reduce memory consumption, the internal memory for the CoE data can be deactivated using the [`EC_T_MBX_PARMS_COE::bDisableODStorage`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_COE17bDisableODStorageE) parameter.

If both parameters [`EC_T_MBX_PARMS_COE::bDisableNotifications`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_COE21bDisableNotificationsE) and [`EC_T_MBX_PARMS_COE::bDisableODStorage`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_COE17bDisableODStorageE) are set, the CoE monitoring is completely deactivated.

## emonNotify - eMbxTferType_COE_SDO_DOWNLOAD

SDO download transfer completion.

**emonNotify - eMbxTferType_COE_SDO_DOWNLOAD**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to a structure of type EC_T_MBXTFER, containing the corresponding mailbox transfer object
    * `dwInBufSize`: [in] Size of the transfer object pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE). The requested parameters stored in element [`EC_T_MBX_DATA::CoE`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA3CoEE) of type [`EC_T_MBX_DATA_COE`](api_mbx_coe.html.md#_CPPv417EC_T_MBX_DATA_COE) are part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE).
The SDO data stored in [`EC_T_MBXTFER::pbyMbxTferData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE).

### struct EC_T_MBX_DATA_COE

### Public Members

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress

Station address of the slave 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wIndex

Object index 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) bySubIndex

Object subindex 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bCompleteAccess

Complete access 

## emonNotify - eMbxTferType_COE_SDO_UPLOAD

SDO upload transfer completion.

**emonNotify - eMbxTferType_COE_SDO_UPLOAD**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to a structure of type EC_T_MBXTFER, containing the corresponding mailbox transfer object
    * `dwInBufSize`: [in] Size of the transfer object in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE). The request parameters stored in element [`EC_T_MBX_DATA::CoE`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA3CoEE) of type [`EC_T_MBX_DATA_COE`](api_mbx_coe.html.md#_CPPv417EC_T_MBX_DATA_COE) are part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE).
The SDO data stored in [`EC_T_MBXTFER::pbyMbxTferData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE).

## CoE Emergency (emonNotify - eMbxTferType_COE_EMERGENCY)

Indication of a CoE emergency request. A [emonNotify - EC_NOTIFY_MBOXRCV](api_mbx.html.md#emonnotify-ec-notify-mboxrcv) is given with [`EC_T_MBXTFER::eMbxTferType`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER12eMbxTferTypeE) = [`EC_T_MBXTFER_TYPE::eMbxTferType_COE_EMERGENCY`](api_mbx.html.md#_CPPv4N17EC_T_MBXTFER_TYPE26eMbxTferType_COE_EMERGENCYE).

**emonNotify - eMbxTferType_COE_EMERGENCY**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to a structure of type EC_T_MBXTFER, containing the corresponding mailbox transfer object
    * `dwInBufSize`: [in] Size of the transfer object in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

In case of an emergency notification all registered clients will get this notification.
The corresponding mailbox transfer object will be created. [`EC_T_MBXTFER::dwTferId`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER8dwTferIdE) is undefined as it is not needed by the client.
The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE).

The emergency data stored in element [`EC_T_MBX_DATA::CoE_Emergency`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA13CoE_EmergencyE) of type [`EC_T_COE_EMERGENCY`](api_mbx_coe.html.md#_CPPv418EC_T_COE_EMERGENCY) is part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) and may have to be buffered by the client.
Access to the memory area [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) outside of the notification caller context is illegal and the results are undefined.

### struct EC_T_COE_EMERGENCY

### Public Members

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wErrorCode

Error code according to EtherCAT specification 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byErrorRegister

Error register 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) abyData[EC_COE_EMERGENCY_DATASIZE]

Error data 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress

Slave node address of the faulty slave 

#### SEE ALSO
A more detailed description of the values can be found in the EtherCAT® specification ETG.1000, section 5.

## emonCoeSdoUpload

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonCoeSdoUpload([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*pdwOutDataLen, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTimeout, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwFlags)

Execute a CoE SDO upload from an EtherCAT slave device to the master. 

This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwSlaveId** – [in] Slave ID 
  * **wObIndex** – [in] Object index 
  * **byObSubIndex** – [in] Object sub index. If Complete Access only 0 or 1 allowed. 
  * **pbyData** – [out] Buffer receiving transferred data 
  * **dwDataLen** – [in] Buffer length [bytes] 
  * **pdwOutDataLen** – [out] Length of received data [byte] 
  * **dwTimeout** – [in] Timeout [ms] 
  * **dwFlags** – [in] Mailbox Flags. Bit 0: set if Complete Access (EC_MAILBOX_FLAG_SDO_COMPLETE). 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [EC_E_MASTER_RED_STATE_INACTIVE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gae2870f20d370920995e27b2a78171a5e) if Master Redundancy is configured and master is inactive
  * [EC_E_ADS_IS_RUNNING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

#### SEE ALSO
[`emonGetSlaveId()`](api_slave.html.md#_CPPv414emonGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emonCoeSdoUploadReq

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonCoeSdoUploadReq([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER](api_mbx.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTimeout, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwFlags)

Initiates a CoE SDO upload from an EtherCAT slave device to the master and returns immediately. 

A unique transfer ID must be written into [EC_T_MBXTFER.dwTferId](api_mbx.html.md#dd/db6/struct_e_c___t___m_b_x_t_f_e_r_1a36cd53365b5741523a1f5b8777866024). EC_NOTIFY_MBOXRCV is given on completion.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer object created with emMbxTferCreate 
  * **dwSlaveId** – [in] Slave ID 
  * **wObIndex** – [in] Object index 
  * **byObSubIndex** – [in] Object sub index. If Complete Access only 0 or 1 allowed. 
  * **dwTimeout** – [in] Timeout [ms] 
  * **dwFlags** – [in] Mailbox Flags. Bit 0: set if Complete Access (EC_MAILBOX_FLAG_SDO_COMPLETE). 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [EC_E_MASTER_RED_STATE_INACTIVE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gae2870f20d370920995e27b2a78171a5e) if Master Redundancy is configured and master is inactive
  * [EC_E_ADS_IS_RUNNING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gac053cb32c9b2bee0305b0644ef76e933) if the ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

#### SEE ALSO
- [emonNotify - eMbxTferType_COE_SDO_UPLOAD](api_mbx_coe.html.md#emonnotify-embxtfertype-coe-sdo-upload)
- [`emonGetSlaveId()`](api_slave.html.md#_CPPv414emonGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emonIoCtl - EC_IOCTL_MONITOR_SET_COESDO_CLEAR_ON_READ

### EC_IOCTL_MONITOR_SET_COESDO_CLEAR_ON_READ

Enable or disable clear on read of the CoE SDO data. If clear on read is enabled, the data is automatically cleared after each read of the CoE SDO Index, SubIndex using : [emonCoeSdoUpload()](api_mbx_coe.html.md#db/d74/_ec_master_api_8cpp_1a901fe227913f012d68e77c12b42d0aca) or : [emonCoeSdoUploadReq()](api_mbx_coe.html.md#db/d74/_ec_master_api_8cpp_1a33064d6d492bdda5f169b78ef381e277). The IOCTL must be called after : [emonConfigureNetwork()](api_general.html.md#db/d74/_ec_master_api_8cpp_1abdf92b52ec02b48f106a638f839db3c0). 

* **Parameters:**
  * **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: enable clear on read 
  * **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes 
  * **pbyOutBuf** – [out] Should be set to EC_NULL 
  * **dwOutBufSize** – [in] Should be set to 0 
  * **pdwNumOutData** – [out] Should be set to EC_NULL 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonCoeGetODList

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonCoeGetODList([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_COE_ODLIST_TYPE](api_mbx_coe.html.md#_CPPv420EC_T_COE_ODLIST_TYPE) eListType, [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_COE_ODLIST](api_mbx_coe.html.md#_CPPv415EC_T_COE_ODLIST) \*poOdList, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Gets a list of object IDs that have so far been transferred to a slave and received by the EC-Monitor. 

This function may not be called from within the JobTask’s context.

#### NOTE
The data buffer will receive the slave response containing the list type followed by the list itself. Therefore the buffer must be 2 bytes bigger than the expected list size.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwSlaveId** – [in] Slave ID 
  * **eListType** – [in] Which object types shall be transferred 
  * **pbyData** – [out] Buffer receiving transferred data 
  * **dwDataLen** – [in] Buffer length in bytes 
  * **poOdList** – [out] Received OD list object 
  * **dwTimeout** – [in] Timeout [ms] 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if master isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [EC_E_MASTER_RED_STATE_INACTIVE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gae2870f20d370920995e27b2a78171a5e) if Master Redundancy is configured and master is inactive
  * [EC_E_ADS_IS_RUNNING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

### enum EC_T_COE_ODLIST_TYPE

*Values:*

### enumerator eODListType_Lengths

Lengths of each list type 

### enumerator eODListType_ALL

List contains all objects 

### enumerator eODListType_RxPdoMap

List with PDO mappable objects 

### enumerator eODListType_TxPdoMap

List with objects that can be changed 

### enumerator eODListType_StoredFRepl

Only stored for a device replacement objects 

### enumerator eODListType_StartupParm

Only startup parameter objects 

#### SEE ALSO
- [`emonGetSlaveId()`](api_slave.html.md#_CPPv414emonGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emonCoeGetODListReq

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonCoeGetODListReq([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER](api_mbx.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_COE_ODLIST_TYPE](api_mbx_coe.html.md#_CPPv420EC_T_COE_ODLIST_TYPE) eListType, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Initiates retrieval of a list of object IDs that have so far been transferred to a slave and received by the EC-Monitor and returns immediately. 

#### NOTE
The mailbox transfer object will receive the slave response containing the list type followed by the list itself. Therefore the buffer must be 2 bytes bigger than the expected list size.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer 
  * **dwSlaveId** – [in] Slave ID 
  * **eListType** – [in] Which object types shall be transferred 
  * **dwTimeout** – [in] Timeout [ms] 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [EC_E_MASTER_RED_STATE_INACTIVE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gae2870f20d370920995e27b2a78171a5e) if Master Redundancy is configured and master is inactive
  * [EC_E_ADS_IS_RUNNING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

#### SEE ALSO
- [`emonMbxTferCreate()`](api_mbx.html.md#_CPPv417emonMbxTferCreate10EC_T_DWORDP17EC_T_MBXTFER_DESC)
- [`emonGetSlaveId()`](api_slave.html.md#_CPPv414emonGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emonNotify - eMbxTferType_COE_GETODLIST

Notification of a detected CoE SDO information service transfer for an object dictionary list.

**emonNotify - eMbxTferType_COE_GETODLIST**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to a structure of type EC_T_MBXTFER
    * `dwInBufSize`: [in] Size of the transfer object in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE).

The object list stored in element [`EC_T_MBX_DATA::CoE_ODList`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA10CoE_ODListE) of type [`EC_T_COE_ODLIST`](api_mbx_coe.html.md#_CPPv415EC_T_COE_ODLIST) is part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) and may have to be buffered by the client.
Access to the memory area [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) outside of the notification caller context is illegal and the results are undefined.

### struct EC_T_COE_ODLIST

### Public Members

### [EC_T_COE_ODLIST_TYPE](api_mbx_coe.html.md#_CPPv420EC_T_COE_ODLIST_TYPE) eOdListType

List type 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wLen

Amount of object IDs 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress

Station address of the slave 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwOdList

Array containing object IDs 

## emonNotify - eMbxTferType_COE_GETENTRYDESC

Notification of a detected CoE SDO information service transfer for an object entry description.

**emonNotify - eMbxTferType_COE_GETENTRYDESC**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to a structure of type EC_T_MBXTFER
    * `dwInBufSize`: [in] Size of the transfer object in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE).

The object entry description stored in element [`EC_T_MBX_DATA::CoE_EntryDesc`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA13CoE_EntryDescE) of type [`EC_T_COE_ENTRYDESC`](api_mbx_coe.html.md#_CPPv418EC_T_COE_ENTRYDESC) is part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) and may have to be buffered by the client.
Access to the memory area [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) outside of the notification caller context is illegal and the results are undefined.

### struct EC_T_COE_ENTRYDESC

### Public Members

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wObIndex

Index in the object dictionary 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byObSubIndex

Sub index in the object dictionary 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byValueInfo

Bit mask which information is included in pbyData. See [Value info flags](api_mbx_coe.html.md#df-db0-group-e-c-c-o-e-e-n-t-r-y-v-a-l-u-e-i-n-f-o). 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wDataType

Object data type according to ETG.1000 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wBitLen

Object size (number of bits) 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byObAccess

Access rights. See [Object access flags](api_mbx_coe.html.md#de-d21-group-e-c-c-o-e-e-n-t-r-y-o-b-j-a-c-c-e-s-s). 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bRxPdoMapping

Object is mappable in a RxPDO 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bTxPdoMapping

Object is mappable in a TxPDO 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bObCanBeUsedForBackup

Object can be used for backup 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bObCanBeUsedForSettings

Object can be used for settings 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress

Station address of the slave 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wDataLen

Size of the remaining object data 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyData

Remaining object data: dwUnitType, pbyDefaultValue, pbyMinValue, pbyMaxValue, pbyDescription

(see ETG.1000.5 and ETG.1000.6)

**Value info flags**

<!-- -*- mode: rst -*- -->

<a id="df-db0-group-e-c-c-o-e-e-n-t-r-y-v-a-l-u-e-i-n-f-o"></a>

### EC_COE_ENTRY_ObjAccess

Object access 

### EC_COE_ENTRY_ObjCategory

Object category 

### EC_COE_ENTRY_PdoMapping

PDO mapping 

### EC_COE_ENTRY_UnitType

Unit type 

### EC_COE_ENTRY_DefaultValue

Default value 

### EC_COE_ENTRY_MinValue

Minimum value 

### EC_COE_ENTRY_MaxValue

Maximum value 

**Object access flags**

<!-- -*- mode: rst -*- -->

<a id="de-d21-group-e-c-c-o-e-e-n-t-r-y-o-b-j-a-c-c-e-s-s"></a>

### EC_COE_ENTRY_Access_R_PREOP

Read access in Pre-Operational state 

### EC_COE_ENTRY_Access_R_SAFEOP

Read access in Safe-Operational state 

### EC_COE_ENTRY_Access_R_OP

Read access in Operational state 

### EC_COE_ENTRY_Access_W_PREOP

Write access in Pre-Operational state 

### EC_COE_ENTRY_Access_W_SAFEOP

Write access in Safe-Operational state 

### EC_COE_ENTRY_Access_W_OP

Write access in Operational state 

#### SEE ALSO
A more detailed description of the values can be found in the EtherCAT® specification ETG.1000, section 5 and 6.


# api_mbx_foe.html.md

# File access over EtherCAT® (FoE)

The EC-Monitor can record file transfers via the FoE protocol between an EtherCAT® MainDevice and a SubDevice. These FoE transfers can be forwarded to the application as segmented packets in real time via the notifications [emonNotify - eMbxTferType_FOE_SEG_DOWNLOAD](api_mbx_foe.html.md#emonnotify-embxtfertype-foe-seg-download) and [emonNotify - eMbxTferType_FOE_SEG_UPLOAD](api_mbx_foe.html.md#emonnotify-embxtfertype-foe-seg-upload).

In addition, the FoE transfers can be stored as a file on the file system. The files are automatically created and stored in [`EC_T_MONITOR_INIT_PARMS::szFileStoragePath`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS17szFileStoragePathE). The file name consists of the following:
: ```default
  <TimeStamp[msec]>_Slave<StationAddress>_<FoeFileName>
  ```

For example:
: ```default
  0123456789_Slave1001_firmware.bin
  ```

The notifications for FoE can be deactivated using the [`EC_T_MBX_PARMS_FOE::bDisableNotifications`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_FOE21bDisableNotificationsE) parameter if they are not required or to save computing time.
If no file system is available or file storage is not desired, it can be disabled using the [`EC_T_MBX_PARMS_FOE::bDisableFileStorage`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_FOE19bDisableFileStorageE) parameter.

If both parameters [`EC_T_MBX_PARMS_FOE::bDisableNotifications`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_FOE21bDisableNotificationsE) and [`EC_T_MBX_PARMS_FOE::bDisableFileStorage`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_FOE19bDisableFileStorageE) are set, the FoE monitoring is completely deactivated.

## Notification sequence

Once the EC-Monitor detects an FoE transfer, the application is notified via an [emonNotify - eMbxTferType_FOE_DOWNLOAD_REQ](api_mbx_foe.html.md#emonnotify-embxtfertype-foe-download-req) or [emonNotify - eMbxTferType_FOE_UPLOAD_REQ](api_mbx_foe.html.md#emonnotify-embxtfertype-foe-upload-req) notification. This notification contains basic information about the upcoming transfer, e.g. requested file name.

After that, each individual packet is transmitted via an [emonNotify - eMbxTferType_FOE_SEG_DOWNLOAD](api_mbx_foe.html.md#emonnotify-embxtfertype-foe-seg-download) or [emonNotify - eMbxTferType_FOE_SEG_UPLOAD](api_mbx_foe.html.md#emonnotify-embxtfertype-foe-seg-upload) notification. The end of the transfer is set via the [`EC_T_MBXTFER::eTferStatus`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER11eTferStatusE) = [`eMbxTferStatus_TferDone`](api_mbx.html.md#_CPPv4N19EC_T_MBXTFER_STATUS23eMbxTferStatus_TferDoneE).

**Download**

**Upload**

## emonNotify - eMbxTferType_FOE_DOWNLOAD_REQ

Notifies an FoE download request from the EtherCAT® MainDevice to a SubDevice.

**emonNotify - eMbxTferType_FOE_DOWNLOAD_REQ**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to a structure of type EC_T_MBXTFER, containing the corresponding mailbox transfer object
    * `dwInBufSize`: [in] Size of the transfer object pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

The parameters that the MainDevice has requested from the SubDevice are stored in the structure [`EC_T_MBX_DATA::FoE_Request`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA11FoE_RequestE) which is part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE).

### struct EC_T_MBX_DATA_FOE_REQ

### Public Members

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress

[out] Station address of the slave 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPassword

[out] FoE read/write request password 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szFileName[EC_MAX_FILE_NAME_SIZE]

[out] Name of the file to be read/write 

## emonNotify - eMbxTferType_FOE_SEG_DOWNLOAD

Transmits a data segment of the ongoing FoE download.

**emonNotify - eMbxTferType_FOE_SEG_DOWNLOAD**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to a structure of type EC_T_MBXTFER, containing the corresponding mailbox transfer object
    * `dwInBufSize`: [in] Size of the transfer object pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

The FoE download data segment is stored at [`EC_T_MBXTFER::pbyMbxTferData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE) with size [`EC_T_MBXTFER::dwDataLen`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER9dwDataLenE) and may have to be buffered by the application.
Access to the memory area [`EC_T_MBXTFER::pbyMbxTferData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE) outside of the notification caller context is illegal and the results are undefined.

Information about the current transfer is stored in the structure [`EC_T_MBX_DATA::FoE`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA3FoEE) which is part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE). Among other things, it contains the SubDevice station address [`EC_T_MBX_DATA_FOE::wStationAddress`](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE15wStationAddressE) and the number of bytes already transmitted [`EC_T_MBX_DATA_FOE::dwTransferredBytes`](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE18dwTransferredBytesE).

### struct EC_T_MBX_DATA_FOE

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTransferredBytes

[out] Amount of transferred bytes 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwRequestedBytes

[out] Amount of bytes to be provided by the application 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBusyDone

[out] If slave is busy: 0 … dwBusyEntire 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBusyEntire

[out] If dwBusyEntire > 0: Slave is busy 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szBusyComment[EC_FOE_BUSY_COMMENT_SIZE]

[out] Busy Comment from slave 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwFileSize

[out] File size 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress

[out] Station address of the slave 

#### NOTE
The elements [`EC_T_MBX_DATA_FOE::dwRequestedBytes`](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE16dwRequestedBytesE) and [`EC_T_MBX_DATA_FOE::dwFileSize`](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE10dwFileSizeE) are not used by the EC-Monitor because they are not known at runtime.

## emonNotify - eMbxTferType_FOE_UPLOAD_REQ

Notifies an FoE upload request from the EtherCAT® MainDevice to a SubDevice.

**emonNotify - eMbxTferType_FOE_DOWNLOAD_REQ**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to a structure of type EC_T_MBXTFER, containing the corresponding mailbox transfer object
    * `dwInBufSize`: [in] Size of the transfer object pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

The parameters that the MainDevice has requested from the SubDevice are stored in the structure [`EC_T_MBX_DATA::FoE_Request`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA11FoE_RequestE) which is part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE).

### struct [EC_T_MBX_DATA_FOE_REQ](api_mbx_foe.html.md#_CPPv421EC_T_MBX_DATA_FOE_REQ)

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) [wStationAddress](api_mbx_foe.html.md#_CPPv4N21EC_T_MBX_DATA_FOE_REQ15wStationAddressE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwPassword](api_mbx_foe.html.md#_CPPv4N21EC_T_MBX_DATA_FOE_REQ10dwPasswordE)

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) [szFileName](api_mbx_foe.html.md#_CPPv4N21EC_T_MBX_DATA_FOE_REQ10szFileNameE)[EC_MAX_FILE_NAME_SIZE]

## emonNotify - eMbxTferType_FOE_SEG_UPLOAD

Transmits a data segment of the ongoing FoE upload.

**emonNotify - eMbxTferType_FOE_SEG_UPLOAD**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to a structure of type EC_T_MBXTFER, containing the corresponding mailbox transfer object
    * `dwInBufSize`: [in] Size of the transfer object pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

The FoE upload data segment is stored at [`EC_T_MBXTFER::pbyMbxTferData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE) with size [`EC_T_MBXTFER::dwDataLen`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER9dwDataLenE) and may have to be buffered by the application.
Access to the memory area [`EC_T_MBXTFER::pbyMbxTferData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE) outside of the notification caller context is illegal and the results are undefined.

Information about the current transfer is stored in the structure [`EC_T_MBX_DATA::FoE`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA3FoEE) which is part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE). Among other things, it contains the SubDevice station address [`EC_T_MBX_DATA_FOE::wStationAddress`](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE15wStationAddressE) and the number of bytes already transmitted [`EC_T_MBX_DATA_FOE::dwTransferredBytes`](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE18dwTransferredBytesE).

### struct [EC_T_MBX_DATA_FOE](api_mbx_foe.html.md#_CPPv417EC_T_MBX_DATA_FOE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwTransferredBytes](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE18dwTransferredBytesE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwRequestedBytes](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE16dwRequestedBytesE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwBusyDone](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE10dwBusyDoneE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwBusyEntire](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE12dwBusyEntireE)

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) [szBusyComment](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE13szBusyCommentE)[EC_FOE_BUSY_COMMENT_SIZE]

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwFileSize](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE10dwFileSizeE)

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) [wStationAddress](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE15wStationAddressE)

#### NOTE
The elements [`EC_T_MBX_DATA_FOE::dwRequestedBytes`](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE16dwRequestedBytesE) and [`EC_T_MBX_DATA_FOE::dwFileSize`](api_mbx_foe.html.md#_CPPv4N17EC_T_MBX_DATA_FOE10dwFileSizeE) are not used by the EC-Monitor because they are not known at runtime.

## emonNotify - EC_NOTIFY_FOE_MBSLAVE_ERROR

This error will be indicated in case an FoE mailbox SubDevice sends an error message.
Detailed error information is stored in the structure [`EC_T_MBOX_FOE_ABORT_DESC`](api_mbx_foe.html.md#_CPPv424EC_T_MBOX_FOE_ABORT_DESC) which is part of [`EC_T_ERROR_NOTIFICATION_DESC`](notification_error.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).

### struct EC_T_MBOX_FOE_ABORT_DESC

### Public Members

### [EC_T_SLAVE_PROP](api_slave.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp

Slave properties 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwErrorCode

Error code 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) achErrorString[MAX_STD_STRLEN]

FoE error string 

## emonConvertEcErrorToFoeError

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonConvertEcErrorToFoeError([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwErrorCode)

Convert master error code to FoE error code. 

* **Returns:**
  FoE error code according to ETG1000.6 Table 92 - Error codes of FoE


# api_pcap.html.md

# Packet Capture

## emonOpenPacketCapture

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonOpenPacketCapture([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_PACKETCAPTURE_PARMS](api_pcap.html.md#_CPPv424EC_T_PACKETCAPTURE_PARMS) \*pParms)

Open packet capture file (PCAP). 

Opens a PCAP trace for further processing within the JobTask. No LinkLayer must have been loaded.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID 
  * **pParms** – [in] Packet capture parameter 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) on success
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if Monitor isn’t initialized or link layer loaded
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if parameter file name invalid
  * [EC_E_OPENFAILED](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga7f5b8a45f69094fd6f1b05aa204c6b8e) if file could not be opened
  * [EC_E_NOMEMORY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga48c2a7b288dc6922a8c0eb116495e1fd) if not enough memory available 

### struct EC_T_PACKETCAPTURE_PARMS

### Public Members

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szFileName[EC_PACKETCAPTURE_FILE_NAME_SIZE]

[in] File name. Supported formats are .pcap or .pcapng. 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bReadMultipleFiles

[in] Read multiple contiguous files. File name format must be “fileName.nnnnn.pcap[ng]”, e.g. wireshark.00000.pcap. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxFrameCnt

[in] Creates a new file every time the number of frames written exceeds this limit. Disabled with a value set to 0. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxFileSize

[in] Creates a new file every time the number of bytes written exceeds this limit. Disabled with a value set to 0. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwRingBufferFileCnt

[in] Form a ring buffer of the capture files with the given number of files. Only if [EC_T_PACKETCAPTURE_PARMS::dwMaxFrameCnt](api_pcap.html.md#d2/d29/struct_e_c___t___p_a_c_k_e_t_c_a_p_t_u_r_e___p_a_r_m_s_1a1783c8103ee0b960f880eed4054d3fc3) or [EC_T_PACKETCAPTURE_PARMS::dwMaxFileSize](api_pcap.html.md#d2/d29/struct_e_c___t___p_a_c_k_e_t_c_a_p_t_u_r_e___p_a_r_m_s_1a3d65c0b7d27fd09bae4e08c25fe4ecae) are set. Disabled with a value set to 0. 

### Example

```default
EC_T_PACKETCAPTURE_PARMS PacketCaptureParms;
OsMemset(&PacketCaptureParms, dwInstanceId, sizeof(EC_T_PACKETCAPTURE_PARMS));

OsSafeStrcpy(PacketCaptureParms.szFileName, "C:\\ecat.pcap");
dwRes = emonOpenPacketCapture(0, &PacketCaptureParms);
if (EC_E_NOERROR != dwRes)
{
    EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "Cannot open packet capture: %s (0x%lx))\n",
        ecatGetText(dwRes), dwRes));
}
```

## emonClosePacketCapture

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonClosePacketCapture([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)

Close packet capture file (PCAP). 

* **Parameters:**
  **dwInstanceID** – [in] Instance ID 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) on success
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if Monitor isn’t initialized or link layer loaded 

## emonGetPacketCaptureInfo

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetPacketCaptureInfo([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_PACKETCAPTURE_INFO](api_pcap.html.md#_CPPv423EC_T_PACKETCAPTURE_INFO) \*pInfo)

Get packet capture file processing status information. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID 
  * **pInfo** – [out] Packet capture info descriptor 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) on success
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if Monitor isn’t initialized or link layer loaded 

### struct EC_T_PACKETCAPTURE_INFO

### Public Members

### [EC_T_PACKETCAPTURE_STATUS](api_pcap.html.md#_CPPv425EC_T_PACKETCAPTURE_STATUS) eStatus

[out] Status of packet capture processing 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szFileName[EC_PACKETCAPTURE_FILE_NAME_SIZE]

[out] File name of current processed capture 

### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwFrameNumberTotal

[out] Total number of processed frames from all capture files 

### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwFrameNumberCur

[out] Last processed frame number from the current packet capture file 

### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwBytesProcessed

[out] Number of processed bytes from the current packet capture file 

### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwFileSize

[out] File size[bytes] of the current packet capture 

### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwTimeStamp

[out] Time stamp [ns] of the last processed frame from the current packet capture file 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCyclesProcessed

[out] Number of EtherCAT cycles processed 

### enum EC_T_PACKETCAPTURE_STATUS

*Values:*

### enumerator ePcapStatus_Unknown

Unknown packet capture status 

### enumerator ePcapStatus_NotLoaded

No packet capture loaded 

### enumerator ePcapStatus_Running

Packet capture processing running 

### enumerator ePcapStatus_Finished

Packet capture processing finished 

### enumerator ePcapStatus_Dummy

## emonStartLivePacketCapture

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonStartLivePacketCapture([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_PACKETCAPTURE_PARMS](api_pcap.html.md#_CPPv424EC_T_PACKETCAPTURE_PARMS) \*pParms)

Start live packet capture (PCAP). 

Starts a live recording of the EtherCAT frames in a specified PCAP file.

#### NOTE
Only the PCAP file format is currently supported.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID 
  * **pParms** – [in] Packet capture parameter 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) on success
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if parameter file name invalid
  * [EC_E_OPENFAILED](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga7f5b8a45f69094fd6f1b05aa204c6b8e) if file could not be opened
  * [EC_E_NOMEMORY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga48c2a7b288dc6922a8c0eb116495e1fd) if not enough memory available 

## emonStopLivePacketCapture

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonStopLivePacketCapture([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)

Stop live packet capture (PCAP). 

Stops a previously started live recording of the EtherCAT frames.

* **Parameters:**
  **dwInstanceID** – [in] Instance ID 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) on success
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if Monitor isn’t initialized or no recording is in progress 

## emonBacktracePacketCapture

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonBacktracePacketCapture([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_PACKETCAPTURE_PARMS](api_pcap.html.md#_CPPv424EC_T_PACKETCAPTURE_PARMS) \*pParms)

Dump packet capture (PCAP) from backtrace buffer. 

Writes a backtrace of the received frames in a specified PCAP file. The number of frames in the backtrace buffer is parameterized via [EC_T_MONITOR_INIT_PARMS::dwBacktraceFrames](api_general.html.md#d5/de9/struct_e_c___t___m_o_n_i_t_o_r___i_n_i_t___p_a_r_m_s_1ab0733b8eb271325b11c958253ef212f2).

#### NOTE
Only the PCAP file format is currently supported.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID 
  * **pParms** – [in] Packet capture parameter 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) on success
  * [EC_E_BUSY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga7c1a3a6dafef1469c97b8e6c4f3868a5) if another dump is in progress
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if backtrace buffer is not initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if parameter file name invalid
  * [EC_E_OPENFAILED](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga7f5b8a45f69094fd6f1b05aa204c6b8e) if file could not be opened
  * [EC_E_NOMEMORY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga48c2a7b288dc6922a8c0eb116495e1fd) if not enough memory available 

#### SEE ALSO
[`emonInitMonitor()`](api_general.html.md#_CPPv415emonInitMonitor10EC_T_DWORDPK23EC_T_MONITOR_INIT_PARMS)


# api_processdata.html.md

# Process Data functions

## emonGetProcessData

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetProcessData([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwOffset, [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Blocking function to retrieve consistent process data from outside the JobTask context. 

This function requests a copy of the process data (stored in RAM). The actual memcpy operation is executed by the JobTask to ensure data consistency. While waiting for the copy to complete, the calling context blocks and repeatedly calls sleep with an interval of at least the cycle time or one millisecond, whichever is greater. The function returns either with the requested process data once the copy is finished, or when the specified timeout has expired.

#### NOTE
The function is blocking and should be used carefully in time-sensitive contexts and may not be called from within the JobTask context. If process data are required outside the cyclic monitor job task (which is calling emonExecJob), direct access to the process data is not recommended as data consistency cannot be guaranteed. A call to this function will send a data read request to the monitor stack and then check every millisecond whether new data is provided. The monitor stack will provide new data after calling emonExecJob(eUsrJob_MonitorTimer) within the job task. This function is usually only called remotely (using the Remote API).

#### NOTE
This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bOutputData** – [in] EC_TRUE: read output data, EC_FALSE: read input data 
  * **dwOffset** – [in] Byte offset in Process data to read from 
  * **pbyData** – [out] Buffer receiving transferred data 
  * **dwDataLen** – [in] Buffer length [bytes] 
  * **dwTimeout** – [in] Timeout [ms] 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonGetProcessDataBits

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetProcessDataBits([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBitOffsetPd, [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDataBitLen, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Reads a specific number of bits from the process image to the given buffer with a bit offset (synchronized). 

This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bOutputData** – [in] EC_TRUE: read output data, EC_FALSE: write input data 
  * **dwBitOffsetPd** – [in] Bit offset in Process data image 
  * **pbyData** – [out] Buffer receiving transferred data 
  * **dwDataBitLen** – [in] Buffer length [bit] 
  * **dwTimeout** – [in] Timeout [ms]. The timeout value must not be set to EC_NOWAIT. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`emonGetProcessData()`](api_processdata.html.md#_CPPv418emonGetProcessData10EC_T_DWORD9EC_T_BOOL10EC_T_DWORDP9EC_T_BYTE10EC_T_DWORD10EC_T_DWORD)

## emonGetProcessImageInputPtr

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*emonGetProcessImageInputPtr([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)

Gets the process data input image pointer. 

* **Parameters:**
  **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
* **Returns:**
  Process data input image pointer 

## emonGetProcessImageOutputPtr

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*emonGetProcessImageOutputPtr([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)

Gets the process data output image pointer. 

* **Parameters:**
  **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
* **Returns:**
  Process data output image pointer 

## emonFindInpVarByName

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonFindInpVarByName([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO](api_slave.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pProcessVarInfoEntry)

Finds an input process variable information entry by the variable name. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **szVariableName** – [in] Variable name 
  * **pProcessVarInfoEntry** – [out] Process variable information entry 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO`](api_slave.html.md#_CPPv421EC_T_PROCESS_VAR_INFO)

## emonFindInpVarByNameEx

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonFindInpVarByNameEx([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO_EX](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)

Finds an input process variable extended information entry by the variable name. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **szVariableName** – [in] Variable name 
  * **pProcessVarInfoEntry** – [out] Process variable extended information entry 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)

## emonFindOutpVarByName

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonFindOutpVarByName([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO](api_slave.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pProcessVarInfoEntry)

Finds an output process variable information entry by the variable name. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **szVariableName** – [in] Variable name 
  * **pProcessVarInfoEntry** – [out] Process variable information entry 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO`](api_slave.html.md#_CPPv421EC_T_PROCESS_VAR_INFO)

## emonFindOutpVarByNameEx

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonFindOutpVarByNameEx([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO_EX](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)

Finds an output process variable extended information entry by the variable name. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **szVariableName** – [in] Variable name 
  * **pProcessVarInfoEntry** – [out] Process variable extended information entry 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)

## emonIoCtl - EC_IOCTL_GET_PDMEMORYSIZE

### EC_IOCTL_GET_PDMEMORYSIZE

Get the process data image size. This information may be used to provide process data image storage from outside the core. This IOCTL is to be called after network configuration. 

* **Parameters:**
  * **pbyInBuf** – [in] Should be set to EC_NULL 
  * **dwInBufSize** – [in] Should be set to 0 
  * **pbyOutBuf** – [out] Pointer to memory where the memory size information will be stored (type: [EC_T_MEMREQ_DESC](api_processdata.html.md#da/df0/struct_e_c___t___m_e_m_r_e_q___d_e_s_c)) 
  * **dwOutBufSize** – [in] Size of the output buffer in bytes 
  * **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_MEMREQ_DESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPDOutSize

Size of the output process data image 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPDInSize

Size of the input process data image 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## Process Data access functions

### EC_COPYBITS

### EC_COPYBITS(pbyDst, nDstBitOffs, pbySrc, nSrcBitOffs, nBitSize)

Copies a block of bits from a source buffer to a destination buffer. 

#### NOTE
The memory buffers must be allocated before. The buffers must be big enough to hold the block starting at the given offsets! The buffers are not checked for overrun. 

* **Parameters:**
  * **pbyDst** – [out] Destination buffer 
  * **nDstBitOffs** – [in] Bit offset within destination buffer 
  * **pbySrc** – [in] Source buffer 
  * **nSrcBitOffs** – [in] Bit offset within source buffer 
  * **nBitSize** – [in] Block size in bits 

#### SEE ALSO
- `EC_SETBITS`
- [`EC_GETBITS`](api_processdata.html.md#c.EC_GETBITS)

![Diagram illustrating the EC_COPYBITS macro copying 22 bits from a source byte array at bit offset 6 to a destination byte array at bit offset 3](../Media/EC_COPYBITS.PNG)
```cpp
EC_T_BYTE pbySrc[] = {0xF4, 0xED, 0x69, 0xA5};
EC_T_BYTE pbyDst[] = {0x00, 0x00, 0x00, 0x00};
EC_COPYBITS(pbyDst, 3, pbySrc, 6, 22);

/* pbyDst now contains 0xB8 0x3C 0xAC 0x00 */
```

### EC_GET_FRM_WORD

### EC_GET_FRM_WORD(ptr)

Reads a value of type EC_T_WORD (16 bit) at given pointer. The value is swapped on big endian systems. 

* **Parameters:**
  * **ptr** – [in] Source buffer 
* **Returns:**
  EC_T_WORD value (16 bit) from buffer 

```cpp
EC_T_BYTE byFrame[] = {0x01, 0xF4, 0xDD, 0x85, 0x03, 0x00, 0x60, 0xC1, 0x00};
EC_T_WORD wResult = 0;

wResult = EC_GET_FRM_WORD(byFrame);
/* wResult is 0xF401 on little endian systems */

wResult = EC_GET_FRM_WORD(byFrame + 5);
/* wResult is 0x6000 on little endian systems */

wResult = EC_GET_FRM_WORD(byFrame + 2);
/* wResult is 0x85DD on little endian systems */
```

### EC_GET_FRM_DWORD

### EC_GET_FRM_DWORD(ptr)

Reads a value of type EC_T_DWORD (32 bit) at given pointer. The value is swapped on big endian systems. 

* **Parameters:**
  * **ptr** – [in] Source buffer 
* **Returns:**
  EC_T_DWORD value (32 bit) from buffer 

```cpp
EC_T_BYTE byFrame[] = {0x01, 0xF4, 0xDD, 0x85, 0x03, 0x00, 0x60, 0xC1, 0x00};
EC_T_DWORD dwResult = 0;

dwResult = EC_GET_FRM_DWORD(byFrame);
/* dwResult is 0x85DDF401 on little endian systems */

dwResult = EC_GET_FRM_DWORD(byFrame + 5);
/* dwResult is 0x00C16000 on little endian systems */

dwResult = EC_GET_FRM_DWORD(byFrame + 2);
/* dwResult is 0x000385DD on little endian systems */
```

### EC_GET_FRM_QWORD

### EC_GET_FRM_QWORD(ptr)

Reads a value of type EC_T_QWORD (64 bit) at given pointer. The value is swapped on big endian systems. 

* **Parameters:**
  * **ptr** – [in] Source buffer 
* **Returns:**
  EC_T_QWORD value (64 bit) from buffer 

```cpp
EC_T_BYTE byFrame[] = {0x01, 0xF4, 0xDD, 0x85, 0x03, 0x00, 0x60, 0xC1, 0x00};
EC_T_UINT64 ui64Result = 0;

ui64Result = EC_GET_FRM_QWORD(byFrame + 1);
/* wResult is 0x00C160000385DDF4 on little endian systems */
```

### EC_GETBITS

### EC_GETBITS(pbySrcBuf, pbyDstData, nSrcBitOffs, nBitSize)

Reads a given number of bits from source buffer starting at given bit offset to destination buffer. 

#### NOTE
This function should only be used to get bit-aligned data. For byte-aligned data the corresponding functions should be used. 

* **Parameters:**
  * **pbySrcBuf** – [in] Source buffer to be copied 
  * **pbyDstData** – [out] Destination buffer where data is copied to 
  * **nSrcBitOffs** – [in] Source bit offset where data is copied from 
  * **nBitSize** – [in] Bit count to be copied 

#### SEE ALSO
- [`EC_GET_FRM_WORD`](api_processdata.html.md#c.EC_GET_FRM_WORD)
- [`EC_GET_FRM_DWORD`](api_processdata.html.md#c.EC_GET_FRM_DWORD)
- [`EC_GET_FRM_QWORD`](api_processdata.html.md#c.EC_GET_FRM_QWORD)

## EC_TESTBIT

### EC_TESTBIT(pbyBuf, nBitOffs)

Test whether a bit in the buffer is set. 

* **Parameters:**
  * **pbyBuf** – Source buffer. 
  * **nBitOffs** – Bit offset to test. 
* **Returns:**
  EC_TRUE if bit is set, otherwise EC_FALSE. 

## emonIoCtl - EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR

### EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR

Set ignore INPUTs on WKC error. 

* **Parameters:**
  * **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: Ignore INPUTs on WKC error. 
  * **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes 
  * **pbyOutBuf** – [out] Should be set to EC_NULL 
  * **dwOutBufSize** – [in] Should be set to 0 
  * **pdwNumOutData** – [out] Should be set to EC_NULL 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

Calling this IOCTL with [`EC_TRUE`](api.html.md#c.EC_TRUE) as parameter will ignore input data of cyclic commands on WKC error.
By default input data are updated if WKC is non zero. If WKC is not matching the expected value a notification [emonNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](notification_error.html.md#emonnotify-ec-notify-cyccmd-wkc-error) is generated and the application must consider this status for the current cycle.

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonIoCtl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR

### EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR

Set INPUTs to zero on WKC error. 

* **Parameters:**
  * **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: INPUTs are set to zero on WKC error. 
  * **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes 
  * **pbyOutBuf** – [out] Should be set to EC_NULL 
  * **dwOutBufSize** – [in] Should be set to 0 
  * **pdwNumOutData** – [out] Should be set to EC_NULL 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

Calling this IOCTL with [`EC_TRUE`](api.html.md#c.EC_TRUE) as parameter will set inputs to zero on WKC error.
By default input data are updated if WKC is non zero. If WKC is not matching the expected value a notification [emonNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](notification_error.html.md#emonnotify-ec-notify-cyccmd-wkc-error) is generated and the application must consider this status for the current cycle.

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonIoCtl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO

### EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO

Set INPUTs to zero on WKC is zero. 

* **Parameters:**
  * **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: Set INPUTs to zero if WKC is zero. 
  * **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes 
  * **pbyOutBuf** – [out] Should be set to EC_NULL 
  * **dwOutBufSize** – [in] Should be set to 0 
  * **pdwNumOutData** – [out] Should be set to EC_NULL 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

Calling this IOCTL with [`EC_TRUE`](api.html.md#c.EC_TRUE) as parameter will set inputs to zero on WKC is zero.
By default input data are ignored on WKC is zero and remain unchanged. If WKC is not matching the expected value a notification [emonNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](notification_error.html.md#emonnotify-ec-notify-cyccmd-wkc-error) is generated and the application must consider this status for the current cycle.

## emonIoCtl - EC_IOCTL_SET_ZERO_INPUTS_ON_FRAME_LOSS

### EC_IOCTL_SET_ZERO_INPUTS_ON_FRAME_LOSS

Set inputs to zero on frame loss. 

* **Parameters:**
  * **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: Set inputs to zero on frame loss 
  * **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes 
  * **pbyOutBuf** – [out] Should be set to EC_NULL 
  * **dwOutBufSize** – [in] Should be set to 0 
  * **pdwNumOutData** – [out] Should be set to EC_NULL 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

Calling this IOCTL with [`EC_TRUE`](api.html.md#c.EC_TRUE) as parameter will set inputs to zero on frame loss.
By default input data are ignored on frame loss and remain unchanged.

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)


# api_slave.html.md

# SubDevice status functions

## emonGetNumConfiguredSlaves

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetNumConfiguredSlaves([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)

Returns the number of slaves which are configured in the ENI. 

* **Parameters:**
  **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
* **Returns:**
  Number of slaves 

## emonGetNumConnectedSlaves

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetNumConnectedSlaves([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)

Get number of currently connected slaves. 

* **Parameters:**
  **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
* **Returns:**
  Number of connected slaves 

## emonGetSlaveId

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveId([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress)

Determines the slave ID using the slave station address. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **wStationAddress** – [in] Station address of the slave 
* **Returns:**
  Slave ID or INVALID_SLAVE_ID if the slave could not be found or the stack is not initialized 

## emonGetSlaveIdAtPosition

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveIdAtPosition([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wAutoIncAddress)

Determines the slave ID using the slave auto increment address. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **wAutoIncAddress** – [in] Auto increment address of the slave 
* **Returns:**
  Slave ID or INVALID_SLAVE_ID if no slave matching wAutoIncAddress can be found 

## emonGetSlaveState

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveState([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwCurrDevState, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwReqDevState)

Get the slave state. 

The slave state is always read automatically from the AL_STATUS register whenever necessary. It is not forced by calling this function. This function may be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwSlaveId** – [in] Slave ID 
  * **pwCurrDevState** – [out] Current slave state 
  * **pwReqDevState** – [out] Requested slave state 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or the output pointers are EC_NULL
  * [EC_E_SLAVE_NOT_PRESENT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga45555d5de25571188a82d2d76c02dd81) if the slave is not present
  * [EC_E_NOTFOUND](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found 

#### SEE ALSO
- [`emonGetSlaveId()`](api_slave.html.md#_CPPv414emonGetSlaveId10EC_T_DWORD9EC_T_WORD)
- [emonNotify - EC_NOTIFY_SLAVE_STATECHANGED](notification_status.html.md#emonnotify-ec-notify-slave-statechanged)

## emonIsSlavePresent

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonIsSlavePresent([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) \*pbPresence)

Returns whether a specific slave is currently connected to the Bus. 

This function may be called from within the JobTask.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwSlaveId** – [in] Slave ID 
  * **pbPresence** – [out] EC_TRUE if the slave is currently connected to the bus, EC_FALSE if not 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range
  * [EC_E_NOTFOUND](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found 

#### SEE ALSO
- [`emonGetSlaveId()`](api_slave.html.md#_CPPv414emonGetSlaveId10EC_T_DWORD9EC_T_WORD)
- [emonNotify - EC_NOTIFY_SLAVE_PRESENCE](notification_status.html.md#emonnotify-ec-notify-slave-presence)

## emonGetSlaveProp

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) emonGetSlaveProp([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_SLAVE_PROP](api_slave.html.md#_CPPv415EC_T_SLAVE_PROP) \*pSlaveProp)

Determines the properties of the slave device. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwSlaveId** – [in] Slave ID 
  * **pSlaveProp** – [out] Slave properties 
* **Returns:**
  EC_TRUE if the slave exists, EC_FALSE if no slave matching dwSlaveId can be found 

### struct EC_T_SLAVE_PROP

### Public Members

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress

Configured station address or INVALID_FIXED_ADDR 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wAutoIncAddr

Configured auto increment address or INVALID_AUTO_INC_ADDR 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) achName[MAX_STD_STRLEN]

Configured name of the slave device (NULL terminated string) 

#### SEE ALSO
[`emonGetSlaveId()`](api_slave.html.md#_CPPv414emonGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emonGetProcessVarInfoNumOf, emonGetProcessVarInfoEx

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetProcessVarInfoNumOf([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_VAR_DIRECTION](api_slave.html.md#_CPPv418EC_T_VAR_DIRECTION) eVarDirection, [EC_T_VAR_SOURCE](api_slave.html.md#_CPPv415EC_T_VAR_SOURCE) eVarSource, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*pdwProcessVarInfoNumOf)

Get process variables information. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **eVarDirection** – [in] INPUTs, OUTPUTs, … . See [EC_T_VAR_DIRECTION](api_slave.html.md#d0-dd4-group-e-c-t-v-a-r-d-i-r-e-c-t-i-o-n) . 
  * **eVarSource** – [in] Slave, Master, … . See [EC_T_VAR_SOURCE](api_slave.html.md#db-db7-group-e-c-t-v-a-r-s-o-u-r-c-e) . 
  * **bFixedAddress** – [in] Use station address if EC_TRUE. Otherwise use AutoInc address. 
  * **wSlaveAddress** – [in] Slave address according to bFixedAddress 
  * **pdwProcessVarInfoNumOf** – [out] Process variables count 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetProcessVarInfoEx([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_VAR_DIRECTION](api_slave.html.md#_CPPv418EC_T_VAR_DIRECTION) eVarDirection, [EC_T_VAR_SOURCE](api_slave.html.md#_CPPv415EC_T_VAR_SOURCE) eVarSource, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_PROCESS_VAR_INFO_EX](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*aoVarInfoEx, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxVarInfoCnt, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*pdwVarInfoCnt)

Get process variables information. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **eVarDirection** – [in] INPUTs, OUTPUTs, … . See [EC_T_VAR_DIRECTION](api_slave.html.md#d0-dd4-group-e-c-t-v-a-r-d-i-r-e-c-t-i-o-n) . 
  * **eVarSource** – [in] Slave, Master, … . See [EC_T_VAR_SOURCE](api_slave.html.md#db-db7-group-e-c-t-v-a-r-s-o-u-r-c-e) . 
  * **bFixedAddress** – [in] Use station address if EC_TRUE. Otherwise use AutoInc address. 
  * **wSlaveAddress** – [in] Slave address according to bFixedAddress 
  * **aoVarInfoEx** – [out] The read process variable extended information entries 
  * **dwMaxVarInfoCnt** – [in] Maximum number of variables that can be stored at aoVarInfoEx 
  * **pdwVarInfoCnt** – [out] Number process variable entries that have been stored in aoVarInfoEx 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

The following example demonstrates how to get all process data variables:

### **emonGetProcessVarInfoEx() Example**

```cpp
EC_T_DWORD dwProcessVarInfoNumOf = 0;
dwRes = emonGetProcessVarInfoNumOf(dwInstanceId, eVarDirection_All, eVarSource_All, EC_FALSE, 0, &dwProcessVarInfoNumOf);
/* ... */
EC_T_PROCESS_VAR_INFO_EX* aoVarInfoEx = (EC_T_PROCESS_VAR_INFO_EX*)OsMalloc(dwProcessVarInfoNumOf * sizeof(EC_T_PROCESS_VAR_INFO_EX));
dwRes = emonGetProcessVarInfoEx(dwInstanceId, eVarDirection_All, eVarSource_All, EC_FALSE, 0, aoVarInfoEx, dwProcessVarInfoNumOf, EC_NULL);
/* ... */
OsSafeFree(aoVarInfoEx);
```

**EC_T_VAR_DIRECTION**

<!-- -*- mode: rst -*- -->

<a id="d0-dd4-group-e-c-t-v-a-r-d-i-r-e-c-t-i-o-n"></a>

### enum EC_T_VAR_DIRECTION

*Values:*

### enumerator eVarDirection_Undefined

Undefined Direction 

### enumerator eVarDirection_INPUT

INPUTs 

### enumerator eVarDirection_OUTPUT

OUTPUTs 

### enumerator eVarDirection_All

INPUTs and OUTPUTs 

### enumerator eVarDirection_BCppDummy

**EC_T_VAR_SOURCE**

<!-- -*- mode: rst -*- -->

<a id="db-db7-group-e-c-t-v-a-r-s-o-u-r-c-e"></a>

### enum EC_T_VAR_SOURCE

*Values:*

### enumerator eVarSource_Undefined

Undefined Source 

### enumerator eVarSource_All

Slaves and Master/Monitor/Simulator 

### enumerator eVarSource_AllSlaves

All Slaves 

### enumerator eVarSource_Slave

Slave 

### enumerator eVarSource_Master

Master 

### enumerator eVarSource_Monitor

Monitor 

### enumerator eVarSource_Simulator

Simulator 

### enumerator eVarSource_BCppDummy

## emonGetSlaveInpVarInfoNumOf

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveInpVarInfoNumOf([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwSlaveInpVarInfoNumOf)

Gets the number of input variables of a specific slave. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **pwSlaveInpVarInfoNumOf** – [out] Number of found process variable entries 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or the output pointer is EC_NULL
  * [EC_E_NOTFOUND](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found 

#### SEE ALSO
- [`emonGetSlaveInpVarInfo()`](api_slave.html.md#_CPPv422emonGetSlaveInpVarInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORDP21EC_T_PROCESS_VAR_INFOP9EC_T_WORD)
- [`emonGetSlaveInpVarInfoEx()`](api_slave.html.md#_CPPv424emonGetSlaveInpVarInfoEx10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORDP24EC_T_PROCESS_VAR_INFO_EXP9EC_T_WORD)

## emonGetSlaveInpVarInfo

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveInpVarInfo([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO](api_slave.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pSlaveProcVarInfoEntries, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)

Gets the process variable information entries of a specific slave. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **wNumOfVarsToRead** – [in] Number process variable entries that have been stored in pSlaveProcVarInfoEntries 
  * **pSlaveProcVarInfoEntries** – [out] The read process variable information entries 
  * **pwReadEntries** – [out] The number of read process variable information entries 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_PROCESS_VAR_INFO

### Public Members

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szName[MAX_PROCESS_VAR_NAME_LEN]

[out] Name of the found process variable 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wDataType

[out] Data type of the found process variable (according to ETG.1000, section 5). See also EcType.h, DEFTYPE_BOOLEAN. 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wFixedAddr

[out] Station address of the slave that is owner of this variable 

### [EC_T_INT](api.html.md#_CPPv48EC_T_INT) nBitSize

[out] Size in bits of the found process variable 

### [EC_T_INT](api.html.md#_CPPv48EC_T_INT) nBitOffs

[out] Bit offset in the process data image 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bIsInputData

[out] Determines whether the found process variable is an input variable or an output variable 

### MAX_PROCESS_VAR_NAME_LEN

Maximum length of a process variable name: 71 characters 

## emonGetSlaveInpVarInfoEx

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveInpVarInfoEx([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO_EX](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pSlaveProcVarInfoEntriesEx, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)

Gets the input process variable extended information entries of a specific slave. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **wNumOfVarsToRead** – [in] Number process variable entries that have been stored in pSlaveProcVarInfoEntries 
  * **pSlaveProcVarInfoEntriesEx** – [out] The read process variable extended information entries 
  * **pwReadEntries** – [out] The number of read process variable information entries 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or the output pointer is EC_NULL
  * [EC_E_NOTFOUND](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found 

### struct EC_T_PROCESS_VAR_INFO_EX

### Public Members

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szName[MAX_PROCESS_VAR_NAME_LEN_EX]

[out] Name of the found process variable 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wDataType

[out] Data type of the found process variable (according to ETG.1000, section 5). See also EcType.h, DEFTYPE_BOOLEAN. 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wFixedAddr

[out] Station address of the slave that is owner of this variable 

### [EC_T_INT](api.html.md#_CPPv48EC_T_INT) nBitSize

[out] Size in bits of the found process variable 

### [EC_T_INT](api.html.md#_CPPv48EC_T_INT) nBitOffs

[out] Bit offset in the process data image 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bIsInputData

[out] Determines whether the found process variable is an input variable or an output variable 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wIndex

[out] Object index 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSubIndex

[out] Object sub index 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPdoIndex

[out] Index of PDO (process data object) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagOffs

[out] Bit offset in the diagnostic image (API GetDiagnosisImagePtr) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wMasterSyncUnit

[out] Master Sync Unit ID (ENI: Slave/ProcessData/RxPdo[1..4]@Su, Slave/ProcessData/TxPdo[1..4]@Su, comment at Cyclic/Frame/Cmd) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTaskId

[out] ID of task where process variable is located 

### EC_T_CYC_COPY_INFO CopyInfo

[out] Copy Info if applied to the variable 

### MAX_PROCESS_VAR_NAME_LEN_EX

Maximum length of an extended process variable name: 127 characters 

## emonGetSlaveOutpVarInfoNumOf

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveOutpVarInfoNumOf([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwSlaveOutpVarInfoNumOf)

Gets the number of output variables of a specific slave. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **pwSlaveOutpVarInfoNumOf** – [out] Number of found process variables 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
- [`emonGetSlaveOutpVarInfo()`](api_slave.html.md#_CPPv423emonGetSlaveOutpVarInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORDP21EC_T_PROCESS_VAR_INFOP9EC_T_WORD)
- [`emonGetSlaveOutpVarInfoEx()`](api_slave.html.md#_CPPv425emonGetSlaveOutpVarInfoEx10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORDP24EC_T_PROCESS_VAR_INFO_EXP9EC_T_WORD)

## emonGetSlaveOutpVarInfo

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveOutpVarInfo([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO](api_slave.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pSlaveProcVarInfoEntries, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)

Gets the output process variable information entries of a specific slave. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **wNumOfVarsToRead** – [in] Number of found process variable entries 
  * **pSlaveProcVarInfoEntries** – [out] The read process variable information entries 
  * **pwReadEntries** – [out] The number of read process variable information entries 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO`](api_slave.html.md#_CPPv421EC_T_PROCESS_VAR_INFO)

## emonGetSlaveOutpVarInfoEx

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveOutpVarInfoEx([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO_EX](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pSlaveProcVarInfoEntriesEx, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)

Gets the output process variable extended information entries of a specific slave. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **wNumOfVarsToRead** – [in] Number of process variable information entries 
  * **pSlaveProcVarInfoEntriesEx** – [out] The read process extended variable entries 
  * **pwReadEntries** – [out] The number of read process variable information entries 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)

## emonGetSlaveInpVarByObjectEx

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveInpVarByObjectEx([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wIndex, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSubIndex, [EC_T_PROCESS_VAR_INFO_EX](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)

Gets the input process variable extended information entry by object index, subindex of a specific slave. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **wIndex** – [in] Object index 
  * **wSubIndex** – [in] Object sub index 
  * **pProcessVarInfoEntry** – [out] Process variable extended information entry 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)

## emonGetSlaveOutpVarByObjectEx

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetSlaveOutpVarByObjectEx([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wIndex, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSubIndex, [EC_T_PROCESS_VAR_INFO_EX](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)

Gets the input process variable extended information entry by object index, subindex of a specific slave. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **wIndex** – [in] Object index 
  * **wSubIndex** – [in] Object sub index 
  * **pProcessVarInfoEntry** – [out] Process variable extended information entry 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)

## emonReadSlaveRegister

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonReadSlaveRegister([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wRegisterOffset, [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wLen, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Reads data from the ESC memory that have so far been transferred to a slave and received by the EC-Monitor. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **wRegisterOffset** – [in] Register offset. I.e. use 0x0130 to read the AL Status register. 
  * **pbyData** – [out] Buffer receiving transfered data 
  * **wLen** – [in] Number of bytes to receive 
  * **dwTimeout** – [in] Timeout [ms] 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or the command is not supported or the timeout value is set to EC_NOWAIT
  * [EC_E_SLAVE_NOT_PRESENT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga45555d5de25571188a82d2d76c02dd81) if the slave is not present
  * [EC_E_NOTFOUND](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
  * [EC_E_TIMEOUT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2d09527654c655e159d26d36143674cb) if dwTimeout elapsed during the API call
  * [EC_E_BUSY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga7c1a3a6dafef1469c97b8e6c4f3868a5) if another transfer request is already pending or the master or the corresponding slave is currently changing its operational state
  * [EC_E_NOTREADY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga4033f6f3b33aa2550d6e46e808a92f37) if the working counter was not set when sending the command (slave may not be connected or did not respond)
  * [EC_E_INVALIDSIZE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gacd9f0baea7a294f85c3f5bde1543d1d0) if the size of the complete command does not fit into a single Ethernet frame. The maximum amount of data to transfer must not exceed 1486 bytes. 

## emonGetCfgSlaveInfo

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetCfgSlaveInfo([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_CFG_SLAVE_INFO](api_slave.html.md#_CPPv419EC_T_CFG_SLAVE_INFO) \*pSlaveInfo)

Return information about a configured slave from the ENI file. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **pSlaveInfo** – [out] Information about the slave 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_CFG_SLAVE_INFO

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId

[out] Slave’s ID to bind bus slave and config slave information 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) abyDeviceName[ECAT_DEVICE_NAMESIZE]

[out] Slave’s configured name (80 Byte) (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwHCGroupIdx

[out] Index of Hot Connect group, 0 for mandatory 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bIsPresent

[out] Slave present on bus 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bIsHCGroupPresent

[out] Slave’s Hot Connect group present on bus 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwVendorId

[out] Vendor identification (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwProductCode

[out] Product code (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwRevisionNumber

[out] Revision number (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSerialNumber

[out] Serial number (from ENI file) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress

[out] Slave’s configured station address (from ENI file) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wAutoIncAddress

[out] Slave’s auto increment address (may differ from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdOffsIn

[out] Process input data bit offset (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdSizeIn

[out] Process input data bit size (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdOffsOut

[out] Process output data bit offset (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdSizeOut

[out] Process output data bit size (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdOffsIn2

[out] 2nd sync unit process input data bit offset (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdSizeIn2

[out] 2nd sync unit process input data bit size (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdOffsOut2

[out] 2nd sync unit process output data bit offset (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdSizeOut2

[out] 2nd sync unit process output data bit size (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdOffsIn3

[out] 3rd sync unit process input data bit offset (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdSizeIn3

[out] 3rd sync unit process input data bit size (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdOffsOut3

[out] 3rd sync unit process output data bit offset (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdSizeOut3

[out] 3rd sync unit process output data bit size (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdOffsIn4

[out] 4th sync unit process input data bit offset (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdSizeIn4

[out] 4th sync unit process input data bit size (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdOffsOut4

[out] 4th sync unit process output data bit offset (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdSizeOut4

[out] 4th sync unit process output data bit size (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMbxSupportedProtocols

[out] Mailbox protocols supported by the slave (from ENI file). Combination of [Supported mailbox protocols](api_slave.html.md#d6-d4d-group-e-c-m-b-x-p-r-o-t-o-c-o-l-s) flags. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMbxOutSize

[out] Mailbox output byte size (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMbxInSize

[out] Mailbox input byte size (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMbxOutSize2

[out] Bootstrap mailbox output byte size (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMbxInSize2

[out] Bootstrap mailbox input byte size (from ENI file) 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDcSupport

[out] Slave supports DC (from ENI file) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wNumProcessVarsInp

[out] Number of input process data variables (from ENI file) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wNumProcessVarsOutp

[out] Number of output process data variables (from ENI file) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPrevStationAddress

[out] Station address of the previous slave (from ENI file) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPrevPort

[out] Connected port of the previous slave (from ENI file) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wIdentifyAdo

[out] ADO used for identification command (from ENI file) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wIdentifyData

[out] Identification value to be validated (from ENI file) 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byPortDescriptor

[out] Port descriptor (ESC register 0x0007) (from ENI file) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagOffsIn[EC_CFG_SLAVE_PD_SECTIONS]

[out] Offset of WkcState bit in diagnosis image (ENI: ProcessData/Recv[1..4]/BitStart): 0xFFFFFFFF = offset not available. WkcState bit values: 0 = Data valid, 1 = Data invalid. 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagOffsOut[EC_CFG_SLAVE_PD_SECTIONS]

[out] Offset of WkcState bit in diagnosis image (ENI: ProcessData/Send[1..4]/BitStart): 0xFFFFFFFF = offset not available. WkcState bit values: 0 = Data valid, 1 = Data invalid. 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) awMasterSyncUnitIn[EC_CFG_SLAVE_PD_SECTIONS]

[out] Sync Unit (ENI: ProcessData/TxPdo[1..4]@Su) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) awMasterSyncUnitOut[EC_CFG_SLAVE_PD_SECTIONS]

[out] Sync Unit (ENI: ProcessData/RxPdo[1..4]@Su) 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDisabled

[out] Slave disabled by API SetSlaveDisabled / SetSlavesDisabled. 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDisconnected

[out] Slave disconnected by API SetSlaveDisconnected / SetSlavesDisconnected. 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bExtended

[out] Slave generated by API ConfigExtend 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDcReferenceClock

[out] Slave is reference clock (from ENI file) 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDcPotentialRefClock

[out] Slave can be used as a reference clock (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDcCycleTime0

[out] Cycle time of Sync0 event [ns] (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDcCycleTime1

[out] Calculated value dwDcCycleTime1 [ns] = Cycle time of Sync1 event - Cycle time of Sync1 event + Shift time of Sync0 event (from ENI file) 

### [EC_T_INT](api.html.md#_CPPv48EC_T_INT) nDcShiftTime

[out] Shift time of Sync0 event [ns] (from ENI file) 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szProductRevision[24]

[out] Slave’s ProductRevision (ENI:Slave/Info/ProductRevision), e.g. “EK1100-0000-0018”. Empty string if not present in ENI. 

**Flags EC_MBX_PROTOCOL_**

<!-- -*- mode: rst -*- -->

<a id="d6-d4d-group-e-c-m-b-x-p-r-o-t-o-c-o-l-s"></a>

### EC_MBX_PROTOCOL_AOE

### EC_MBX_PROTOCOL_EOE

### EC_MBX_PROTOCOL_COE

### EC_MBX_PROTOCOL_FOE

### EC_MBX_PROTOCOL_SOE

### EC_MBX_PROTOCOL_VOE

## emonGetCfgSlaveSmInfo

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetCfgSlaveSmInfo([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_CFG_SLAVE_SM_INFO](api_slave.html.md#_CPPv422EC_T_CFG_SLAVE_SM_INFO) \*pSlaveSmInfo)

Return SyncManager information of a configured slave from the ENI file. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **pSlaveSmInfo** – [out] Information about the slave. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_CFG_SLAVE_SM_ENTRY

### Public Members

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPhysAddr

[out] ESC (0x800 + y \* 8) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wLength

[out] ESC (0x802 + y \* 8) 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byOpMode

[out] Bits 0..1 ESC (0x804 + y \* 8) 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byDirection

[out] Bits 2..3 ESC (0x804 + y \* 8) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdBitOffs

[out] Process input data bit offset (from ENI file) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPdBitSize

[out] Process input data bit size (from ENI file) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagBitOffs

[out] Offset of WkcState bit in diagnosis image 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wMasterSyncUnit

[out] Sync Unit (ENI: ProcessData/TxPdo[1..4]@Su) 

### struct EC_T_CFG_SLAVE_SM_INFO

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId

[out] Slave ID 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSmInfoNumOf

[out] Number of available sync managers 

### [EC_T_CFG_SLAVE_SM_ENTRY](api_slave.html.md#_CPPv423EC_T_CFG_SLAVE_SM_ENTRY) aoSmInfos[ECREG_SYNCMANAGER_MAX_NUMOF]

[out] Sync managers info 

### Example

```default
/* get information about slave's sync managers configured in ENI file */
EC_T_CFG_SLAVE_SM_INFO oSlaveSmInfo;
OsMemset(&oSlaveSmInfo, 0, sizeof(EC_T_CFG_SLAVE_SM_INFO));
dwRes = emonGetCfgSlaveSmInfo(dwInstanceId, EC_TRUE, 1001, &oSlaveSmInfo);
```

## emonGetBusSlaveInfo

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetBusSlaveInfo([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BUS_SLAVE_INFO](api_slave.html.md#_CPPv419EC_T_BUS_SLAVE_INFO) \*pSlaveInfo)

Return information about a slave connected to the EtherCAT bus. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **pSlaveInfo** – [out] Information from the slave 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range
  * [EC_E_NOTFOUND](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found 

### struct EC_T_BUS_SLAVE_INFO

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveId

[out] The slave’s ID to bind bus slave and config slave information 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) adwPortSlaveIds[ESC_PORT_COUNT]

[out] The slave’s ID of the slaves connected to ports. See [Port slave ID’s](api_slave.html.md#df-dfc-group-e-c-s-l-a-v-e-i-d-s). 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPortState

[out] Port link state. Format: wwww xxxx yyyy zzzz (each nibble : port 3210)

wwww : Signal detected 1=yes, 0=no

xxxx : Loop closed 1=yes, 0=no

yyyy : Link established 1=yes, 0=no


 zzzz : Slave connected 1=yes, 0=no (zzzz = logical result of w,x,y) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wAutoIncAddress

[out] The slave’s auto increment address 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDcSupport

[out] Slave supports DC (Bus Topology Scan) 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDc64Support

[out] Slave supports 64 Bit DC (Bus Topology Scan) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwVendorId

[out] Vendor Identification stored in the EEPROM at offset 0x0008 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwProductCode

[out] Product Code stored in the EEPROM at offset 0x000A 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwRevisionNumber

[out] Revision number stored in the EEPROM at offset 0x000C 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSerialNumber

[out] Serial number stored in the EEPROM at offset 0x000E 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byESCType

[out] Type of ESC (Value of slave ESC register 0x0000) 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byESCRevision

[out] Revision number of ESC (Value of slave ESC register 0x0001) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wESCBuild

[out] Build number of ESC (Value of slave ESC register 0x0002) 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byPortDescriptor

[out] Port descriptor (Value of slave ESC register 0x0007) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wFeaturesSupported

[out] Features supported (Value of slave ESC register 0x0008) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress

[out] The slave’s station address (Value of slave ESC register 0x0010) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wAliasAddress

[out] The slave’s alias address (Value of slave ESC register 0x0012) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wAlStatus

[out] AL status (Value of slave ESC register 0x0130) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wAlStatusCode

[out] AL status code. (Value of slave ESC register 0x0134 during last error acknowledge). This value is reset after a slave state change. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSystemTimeDifference

[out] System time difference. (Value of slave ESC register 0x092C) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wMbxSupportedProtocols

[out] Supported Mailbox Protocols stored in the EEPROM at offset 0x001C 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wDlStatus

[out] DL status (Value of slave ESC register 0x0110) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPrevPort

[out] Connected port of the previous slave 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wIdentifyData

[out] Last read identification value see [EC_T_CFG_SLAVE_INFO.wIdentifyAdo](api_slave.html.md#d5/dca/struct_e_c___t___c_f_g___s_l_a_v_e___i_n_f_o_1a5972bcd59947447718549523d67d828d)

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bLineCrossed

[out] Line crossed was detected at this slave 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveDelay

[out] Delay behind slave [ns]. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPropagDelay

[out] Propagation delay [ns]. ESC register 0x0928. 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bIsRefClock

[out] Slave is reference clock 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bIsDeviceEmulation

[out] Slave without Firmware. ESC register 0x0141, enabled by EEPROM offset 0x0000.8. 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wLineCrossedFlags

[out] Combination of [Line crossed flags](api_slave.html.md#db-d4d-group-e-c-l-i-n-e-c-r-o-s-s-e-d-f-l-a-g-s)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCyclicWkcErrorCnt

[out] Counter for Cyclic WC Error 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveAbsentCnt

[out] Counter for Absent/Not Present Slaves 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwUnexpectedStateCnt

[out] Counter for Abnormal State Change 

**Port SubDevice ID’s**

<!-- -*- mode: rst -*- -->

<a id="df-dfc-group-e-c-s-l-a-v-e-i-d-s"></a>

### MASTER_SLAVE_ID

### SIMULATOR_SLAVE_ID

### MASTER_RED_SLAVE_ID

### EL9010_SLAVE_ID

### FRAMELOSS_SLAVE_ID

### JUNCTION_RED_FLAG

**Flags EC_LINECROSSED_**

<!-- -*- mode: rst -*- -->

<a id="db-d4d-group-e-c-l-i-n-e-c-r-o-s-s-e-d-f-l-a-g-s"></a>

### EC_LINECROSSED_NOT_CONNECTED_PORTA

### EC_LINECROSSED_UNEXPECTED_INPUT_PORT

### EC_LINECROSSED_UNEXPECTED_JUNCTION_RED

### EC_LINECROSSED_UNRESOLVED_PORT_CONNECTION

### EC_LINECROSSED_HIDDEN_SLAVE_CONNECTED

### EC_LINECROSSED_PHYSIC_MISMATCH

### EC_LINECROSSED_INVALID_PORT_CONNECTION

### EC_LINECROSSED_UNEXPECTED_CABLE_RED


# api_superseteni.html.md

# Configuration adjustments

The Configuration adjustments allows to adapt the configuration without generating a new ENI file. The base ENI file contains a superset of all the possible connected SubDevices. Possible use cases are:

Optional SubDevices
: ENI contains several optional SubDevices that can be excluded depending on their presence.

Alternative SubDevices
: ENI contains several different alternatives for a SubDevice at a certain position.

According to the use case the application can exclude SubDevices from this superset.

## emonConfigLoad

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonConfigLoad([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_CNF_TYPE](api_general.html.md#_CPPv413EC_T_CNF_TYPE) eCnfType, [EC_T_PBYTE](api.html.md#_CPPv410EC_T_PBYTE) pbyCnfData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCnfDataLen)

Load the network configuration. 

In combination with emConfigApply, this function replaces emConfigureNetwork and must be called after the initialization. Among others the EtherCAT topology defined in the given XML configuration file will be stored internally.

#### NOTE
A client must not be registered prior to calling this function. Existing client registrations will be dropped.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **eCnfType** – [in] Type of configuration data provided 
  * **pbyCnfData** – [in] Configuration data 
  * **dwCnfDataLen** – [in] Length of configuration data in byte 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range, the input pointer is EC_NULL or contains EC_NULL pointer
  * [EC_E_NOMEMORY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga48c2a7b288dc6922a8c0eb116495e1fd) if some memory cannot be allocated
  * [EC_E_ADS_IS_RUNNING](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gac053cb32c9b2bee0305b0644ef76e933) if the ADS server is running 

### enum [EC_T_CNF_TYPE](api_general.html.md#_CPPv413EC_T_CNF_TYPE)

### enumerator [eCnfType_Unknown](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE16eCnfType_UnknownE)

### enumerator [eCnfType_Filename](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE17eCnfType_FilenameE)

### enumerator [eCnfType_Data](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE13eCnfType_DataE)

### enumerator [eCnfType_Datadiag](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE17eCnfType_DatadiagE)

### enumerator [eCnfType_GenPreopENI](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE20eCnfType_GenPreopENIE)

### enumerator [eCnfType_GenPreopENIWithCRC](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE27eCnfType_GenPreopENIWithCRCE)

### enumerator [eCnfType_GenOpENI](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE17eCnfType_GenOpENIE)

### enumerator [eCnfType_None](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE13eCnfType_NoneE)

### enumerator [eCnfType_ConfigData](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE19eCnfType_ConfigDataE)

### enumerator [eCnfType_GenOpENINoStrings](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE26eCnfType_GenOpENINoStringsE)

### enumerator [eCnfType_FileByApp](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE18eCnfType_FileByAppE)

### enumerator [eCnfType_GenEBI](api_general.html.md#_CPPv4N13EC_T_CNF_TYPE15eCnfType_GenEBIE)

## emonConfigExcludeSlave

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonConfigExcludeSlave([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress)

Exclude a slave from the network configuration. 

It has to be called after emConfigLoad and prior to calling emConfigApply.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **wStationAddress** – [in] Station address of the slave to be excluded. A value of 0 excludes all slaves. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonConfigIncludeSlave

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonConfigIncludeSlave([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress)

Include a slave in the network configuration. 

Slaves that were previously excluded with emConfigSlaveExclude can be added again. It has to be called after emConfigLoad and prior to calling emConfigApply.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **wStationAddress** – [in] Station address of the slave to be included. A value of 0 includes all slaves. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonConfigSetPreviousPort

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonConfigSetPreviousPort([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddressPrev, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPortPrev)

Set previous port information of a slave. 

It has to be called after emConfigLoad and prior to calling emConfigApply.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **wStationAddress** – [in] Station address of the slave 
  * **wStationAddressPrev** – [in] Previous slave station address 
  * **wPortPrev** – [in] Previous port 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonConfigApply

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonConfigApply([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)

Apply the network configuration. 

It has to be called after emConfigLoad.

* **Parameters:**
  **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code


# architecture.html.md

# Architecture

The EC-Monitor Software Development Kit (SDK) offers the possibility for Data Tracing / Listening / Sniffing / Logging Diagnosis and Monitoring of EtherCAT® Networks. It’s suitable for new (Greenfield) and existing (Brownfield) installations. Also it’s independent from EtherCAT® MainDevice Software and Hardware.

EC-Monitor is implemented in C++ and can be easily ported to any embedded OS platforms using an appropriate C++ compiler. The API functions are C language interfaces, thus the EC-Monitor can be used in ANSI-C as well as in C++ environments.

The EC-Monitor is divided into modules, see diagram and descriptions below:

![EC-Monitor software architecture diagram showing the EC-Monitor Library, Configuration Layer, OS Abstraction Layer, and Real-time Ethernet Driver Layer](../Media/EC-Monitor_Architecture.png)

EC-Monitor Library:
: In the core module cyclic (process data update) and acyclic (mailbox) EtherCAT® commands are received and processed.

Configuration Layer:
: The EC-Monitor is configured using an XML file whose format is fixed in the EtherCAT® specification ETG.2100. EC-Monitor contains an OS independent XML parser.

OS Abstraction Layer:
: All OS dependent system calls are encapsulated in a small OS layer. Most functions are that easy that they can be implemented using simple C macros.

Real-time Ethernet Driver Layer:
: This driver receives Ethernet frames from the TAP devices.

## EtherCAT® Network Configuration (ENI)

The EC-Monitor has to know about the EtherCAT® bus topology and the cyclic/acyclic frames which are exchanged by the third party EtherCAT® MainDevice with the SubDevices. This configuration is determined in a configuration file which has to be available in the EtherCAT® Network Information Format (ENI). This format is completely independent from EtherCAT® SubDevice vendors, from EtherCAT® MainDevice vendors and from EtherCAT® configuration tools. Thus inter-operability between those vendors is guaranteed.

## Operating system configuration

The main task is to setup the operating system to support the appropriate network adapter for EtherCAT® usage and for some systems real-time configuration may be needed.

The operating system-specific settings and configurations are described in [Platform and Operating Systems (OS)](os.html.md#platform-and-operating-systems-os).


# emll.html.md

# Real-time Ethernet Driver

This chapter describes how the EC-Monitor selects its Real-time Ethernet Driver module and lists the supported network controllers, one chapter per driver.

* [Real-time Ethernet Driver selection](emll_generic.html.md)
  * [Real-time Ethernet Driver and PHY OS Driver](emll_generic.html.md#real-time-ethernet-driver-and-phy-os-driver)
  * [Real-time Ethernet Driver selection and initialization](emll_generic.html.md#real-time-ethernet-driver-selection-and-initialization)
  * [Real-time Ethernet Driver instance selection via PCI location](emll_generic.html.md#real-time-ethernet-driver-instance-selection-via-pci-location)
* [Intel Pro/1000 - emllIntelGbe](emllintelgbe.html.md)
  * [TTS Feature](emllintelgbe.html.md#tts-feature)
  * [Supported PCI devices](emllintelgbe.html.md#supported-pci-devices)
* [Windows NDIS - emllNdis](emllndis.html.md)
* [Windows WinPcap - emllPcap](emllpcap.html.md)
  * [WinPcap, Npcap support](emllpcap.html.md#winpcap-npcap-support)
* [emllRemote](emllremote.html.md)
* [VxWorks SNARF - emllSNARF](emllsnarf.html.md)
* [Linux SockRaw - emllSockRaw](emllsockraw.html.md)
* [Windows TAP - emllTap](emlltap.html.md)


# emll_generic.html.md

# Real-time Ethernet Driver selection

The EC-Monitor currently supports a variety of different Real-time Ethernet Driver modules, each contained in a single library file, which is loaded by the core library dynamically. The EC-Monitor shipment consist of a core library and one (or more) libraries each containing support for one specific Real-time Ethernet Driver module (type of hardware card).
Which library actually is loaded depends on the Real-time Ethernet Driver parameters at runtime.

Real-time means operating directly on the network adapter’s register set instead of using the operating system’s native driver.

The principle of Real-time Ethernet Driver selection is that the name of the Real-time Ethernet Driver (Real-time Ethernet Driver Identification) is used to determine the location and name of a registration function, which is called by the EC-Monitor and registers function pointers which allow access to the Real-time Ethernet Driver functional entries.

The EtherCAT® Real-time Ethernet Driver will be initialized using a Real-time Ethernet Driver specific configuration parameter set.
A pointer to this parameter set is part of the EC-Monitor initialization settings.

The EC-Monitor supports two Real-time Ethernet Driver operating modes:

> - Interrupt mode all received Ethernet frames will be processed immediately in the context of the Real-time Ethernet Driver receiver task.
> - Polling mode the EC-Monitor will call the Real-time Ethernet Driver receiver polling function prior to processing received frames.

## Real-time Ethernet Driver and PHY OS Driver

Some operating systems, e.g. Linux and Xenomai, provide drivers for most common Ethernet controllers and their related physical transceivers (PHY).
The manufacturer specific PHY circuits can be handled by a dedicated driver.
Using the PHY OS Driver interface it is possible to use the manufacturer’s dedicated PHY driver without modification of the Real-time Ethernet Driver driver.
Depending on the hardware architecture, an additional module from acontis, e.g. atemsys for Linux, grants access to the MDIO bus to the OS drivers, or request MDIO operations from the OS drivers.

![PHY OS Driver interface architecture showing how the Real-time Ethernet Driver communicates with manufacturer-specific PHY drivers via an OS abstraction module such as atemsys on Linux](../../EcMaster/Media/emll_phy_os_driver_architecture.png)

#### NOTE
Real-time Ethernet Driver modules not listed here may be available if purchased additionally

## Real-time Ethernet Driver selection and initialization

The different Real-time Ethernet Driver modules are selected and parameterized by a common structure [`EC_T_LINK_PARMS`](emll_generic.html.md#_CPPv415EC_T_LINK_PARMS) shared by all Real-time Ethernet Driver and a Real-time Ethernet Driver specific structure, pointed to by an element within the common structure. This parameter set is given to [`EC_T_MONITOR_INIT_PARMS::pLinkParms`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS10pLinkParmsE) with the call of [`emonInitMonitor()`](api_general.html.md#_CPPv415emonInitMonitor10EC_T_DWORDPK23EC_T_MONITOR_INIT_PARMS).

### struct EC_T_LINK_PARMS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSignature

[in] Signature of the adapter specific structure containing the [EC_T_LINK_PARMS](emll_generic.html.md#d1/d58/struct_e_c___t___l_i_n_k___p_a_r_m_s) structure 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSize

[in] Size of the adapter specific structure containing the [EC_T_LINK_PARMS](emll_generic.html.md#d1/d58/struct_e_c___t___l_i_n_k___p_a_r_m_s) structure 

### [EC_T_LOG_PARMS](api_general.html.md#_CPPv414EC_T_LOG_PARMS) LogParms

[in] Logging parameters 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szDriverIdent[EC_DRIVER_IDENT_NAME_SIZE]

[in] Name of Link Layer module (driver identification) for Link Layer Selection 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstance

[in] Instance of the adapter. If EC_LINKUNIT_PCILOCATION is set: contains PCI address. 

### EC_T_LINKMODE eLinkMode

[in] Mode of operation 

### EC_T_CPUSET cpuIstCpuAffinityMask

[in] Interrupt service thread CPU affinity mask 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwIstPriority

[in] Task priority of the interrupt service task (not used in polling mode) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwIstStackSize

[in] Task stack size 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwLinkSpeed

[in] 10, 100, 1000 Mbit/s 

### [EC_T_LINKLAYER_TIMINGTASK](emll_generic.html.md#_CPPv425EC_T_LINKLAYER_TIMINGTASK) oLinkLayerTimingTask

[in] LinkLayer timimg task parameters 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szLoadPath[EC_DRIVER_PATH_SIZE]

[in] Path from which the libraries should be loaded 

### struct EC_T_LINKLAYER_TIMINGTASK

### Public Members

### EC_T_LINKLAYER_TIMING eLinkLayerTiming

[in] LinkLayer timing task mode 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCycleTimeNsec

[in] Cycle time between 2 pfnStartCycle calls in ns. Will be set by the master stack for the link layer. 

### EC_T_LINK_STARTCYCLE_CALLBACK pfnStartCycle

[in] Callback function called cyclically according to dwCycleTimeNsec 

### EC_T_VOID \*pvStartCycleContext

[in] Context passed to each pfnStartCycle call 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTtsSendOffsetUsec

[in] Time between pfnStartCycle call and TTS frame transmission 

### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) nSystemTime

[in] System 

## Real-time Ethernet Driver instance selection via PCI location

For some operating systems it is possible to address the Real-time Ethernet Driver instance using its PCI address as an alternative. To do this, EC_LINKUNIT_PCILOCATION (0x01000000) and the PCI location must be set as [`EC_T_LINK_PARMS::dwInstance`](emll_generic.html.md#_CPPv4N15EC_T_LINK_PARMS10dwInstanceE).

On Linux the PCI address  can be shown using e.g.:

```console
$ lspci | grep Ethernet
```

```console
$ 00:19.0 Ethernet controller: Intel Corporation Ethernet Connection I217-LM (rev 04)
$ 04:00.0 Ethernet controller: Intel Corporation 82574L Gigabit Network Connection
$ 05:00.0 Ethernet controller: Intel Corporation 82574L Gigabit Network Connection
```

The format of [`EC_T_LINK_PARMS::dwInstance`](emll_generic.html.md#_CPPv4N15EC_T_LINK_PARMS10dwInstanceE) using PCI bus address is:

0x01bbddff
: - bb Bus Number
  - dd Device Number
  - ff Function Number

```cpp
EC_T_LINK_PARMS::dwInstance = 0x01001900; //"0000:00:19.0"
```

On Windows the integer value displayed in properties dialog must be converted to HEX. E.g the number from the following dialog (PCI bus 11, device 0, function 0) corresponds to 0x010B0000 (bus 0x0B).

![Windows network connection properties dialog showing PCI bus, device, and function numbers for determining the Real-time Ethernet Driver instance address](../Media/NetworkConnectionProps_Windows.png)


# emllintelgbe.html.md

# Intel Pro/1000 - emllIntelGbe

The parameters to the Real-time Ethernet Driver Intel Pro/1000 are setup-specific.
The function “CreateLinkParmsFromCmdLineIntelGbe” in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.

### struct EC_T_LINK_PARMS_INTELGBE

### Public Members

### [EC_T_LINK_PARMS](emll_generic.html.md#_CPPv415EC_T_LINK_PARMS) linkParms

Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_INTELGBE. 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wRxBufferCnt

Receive buffer count, 0: default to 96 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wRxBufferSize

Receive buffer size for a single Ethernet frame. 0: buffer optimized for standard Ethernet frame. 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wTxBufferCnt

Transmit buffer count, 0: default to 96 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wTxBufferSize

Transmit buffer size for a single Ethernet frame. 0: buffer optimized for standard Ethernet frame. 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDisableLocks

Disable locks 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwAutoNegTimeout

Timeout [ms] for auto negotiation 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers

EC_FALSE: Use buffers from DMA for receive (default), EC_TRUE: use buffers from heap for receive. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE. 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bNoPhyCtrlOnConnect

EC_TRUE: No PHY control (e.g. PHY reset, PHY PM settings, Gbits Ctrl) on link connection detected 

NICs equipped with 82577, 82579 or 82567 may need HardCodedPhySettings. This must be set after `emInitMaster()`, before using the NIC, e.g.:

```cpp
{
    emIoCtl(dwInstanceId, EC_IOCTL_LINKLAYER_MAIN + EC_LINKIOCTL_FORCELINKMODE, EC_NULL + 0x20103, sizeof(EC_T_DWORD), EC_NULL, 0, EC_NULL);
    OsSleep(1000);
}
```

## TTS Feature

The IntelGbe Real-time Ethernet Driver can optionally use Time-Triggered Send (TTS) feature. Ethernet/EtherCAT® frames are sent and time stamped according to the NIC timer instead of the CPU timer. Which is usually more accurate.

#### SEE ALSO
[`EC_T_LINKLAYER_TIMINGTASK`](emll_generic.html.md#_CPPv425EC_T_LINKLAYER_TIMINGTASK), `EC_T_LINKLAYER_TIMING`

## Supported PCI devices

<!-- -*- mode: rst -*- -->

Intel PRO-1000 PCI specific definitions (VendorId, DeviceId)


# emllndis.html.md

# Windows NDIS - emllNdis

As default EC-Monitor for Windows contains `emllNdis.dll` to use a native Windows driver for EtherCAT®.

The acontis ECAT Protocol Driver is needed to use the Ethernet Driver NDIS and can be installed from

- `Bin/Windows/x64/EcatNdisSetup-x86_64Bit.msi` or
- `Bin/Windows/x86/EcatNdisSetup-x86_32Bit.msi`

respectively depend on the Windows Operating System Type of 64 Bit or 32 Bit.

IPv4 must be installed for the network adapter as the Ethernet Driver NDIS uses the IP address to identify the network adapter.

The parameters to the Ethernet Driver NDIS are setup-specific. The function `CreateLinkParmsFromCmdLineNDIS()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Ethernet Driver instance.

### struct EC_T_LINK_PARMS_NDIS

### Public Members

### [EC_T_LINK_PARMS](emll_generic.html.md#_CPPv415EC_T_LINK_PARMS) linkParms

Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_NDIS. 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szAdapterName[EC_NDIS_ADAPTER_NAME_SIZE]

ServiceName of network adapter, see HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\NetworkCards in registry (zero terminated) 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) abyIpAddress[4]

IP address of network adapter 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDisablePromiscuousMode

Disable adapter promiscuous mode 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDisableForceBroadcast

Don’t change target MAC address to FF:FF:FF:FF:FF:FF 

In case of problems while using the Ethernet Driver, it is advised to set the windows registry entry DontSetPromiscuousMode of the ECAT NDIS Protocol driver. This option is available since V3.1.3.02 of the driver.
This can be done through the following steps:

- Install ECAT NDIS Protocol driver (V3.1.3.02 or newer version)
- Open the registry editor
- Switch to Computer\\HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\Ecatndis, or just look for Ecatndis in the editor
- Create a new DWORD entry named DontSetPromiscuousMode
- Set the value of DontSetPromiscuousMode to 1
- Close the registry editor and restart your computer


# emllpcap.html.md

# Windows WinPcap - emllPcap

An Ethernet Driver based on the WinPcap library is shipped with the EC-Monitor. This Ethernet Driver is implemented using a network filter driver that enables the software to send and receive raw Ethernet frames. Using this Ethernet Driver any Windows standard network drivers can be used.
The Windows network adapter card has to be assigned a unique IP address (private IP address range). This IP address is used by the EtherCAT® WinPcap Ethernet Driver driver to select the appropriate adapter.

It is recommended to use a separate network adapter to connect EtherCAT® devices. If the network adapter is used for both EtherCAT® and the local area network, it may significantly impact local area network operation.
A static private IP address (e.g., 192.168.x.y) must be assigned to the EtherCAT® network adapter.

The parameters to the Ethernet Driver WinPcap are setup-specific. The function `CreateLinkParmsFromCmdLineWinPcap()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Ethernet Driver instance.

### struct EC_T_LINK_PARMS_WINPCAP

### Public Members

### [EC_T_LINK_PARMS](emll_generic.html.md#_CPPv415EC_T_LINK_PARMS) linkParms

Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_WINPCAP. 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) abyIpAddress[4]

IP address 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szAdapterId[MAX_LEN_WINPCAP_ADAPTER_ID]

Adapter ID, format: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bFilterInput

Filter input if EC_TRUE. This is needed on some system if the winpcap library notify the sent frames to the network adapter. 

## WinPcap, Npcap support

At least WinPcap version 4.1.2 or Npcap 0.07 r17 must be used. WinPcap version 4.1.2 is the preferred library.

The EC-Monitor installer installs WinPcap by default.

If using Npcap 0.07 r17, the WinPcap API-compatible mode must be chosen:

![Npcap installer dialog showing the WinPcap API-compatible mode option that must be selected for use with EC-Master](../../LinkLayer/Media/Npcap-Installer.png)


# emllremote.html.md

# emllRemote

The emllRemote is used to tunnel EtherCAT® frames within a TCP socket between EC-Master and EC-Simulator.

The emllRemote is used to receive EtherCAT® frames tunneled through TCP sockets.

The parameters to the Remote Driver are setup-specific. The function `CreateLinkParmsFromCmdLineRemote()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the driver instance.

### struct EC_T_LINK_PARMS_REMOTE

### Public Members

### [EC_T_LINK_PARMS](emll_generic.html.md#_CPPv415EC_T_LINK_PARMS) linkParms

Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_REMOTE. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSocketType

Socket type. Must be set to 1 (emrassocktype_tcp). 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) abySrcIpAddress[4]

Source adapter IP address (listen) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wSrcPort

Source port number (listen) 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) abyDstIpAddress[4]

Destination adapter IP address (connect) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wDstPort

Destination port number (connect) 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) abyMac[6]

MAC address 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwRxBufferCnt

Frame buffer count for interrupt service thread (IST) 

While EC-Monitor listens on the given port using emllRemote, the EC-Master can connect to it using emllRemote.

EcMonitorDemo command line example:
: ```console
  $ EcMonitorDemo -remote 1 0 0.0.0.0 10001 0.0.0.0 0 -f eni.xml
  ```

EcMasterDemo command line example:
: ```console
  $ EcMasterDemo -integbe 1 1 -f eni.xml -mirror -remote 1 1 0.0.0.0 0 127.0.0.1 10001
  ```


# emllsnarf.html.md

# VxWorks SNARF - emllSNARF

Using the EC-Monitor stack’s SNARF Real-time Ethernet Driver it is possible to use any of the standard network drivers shipped with VxWorks.
In VxWorks every network adapter is identified using a short string and a unit number in case of multiple identical network adapters. The unit numbers start with a value of 0.
For example the string for the Intel Pro/100 network adapter driver is “fei”. The first unit is identified using the string “fei0”:

The network adapter driver has to be loaded prior to initializing the EC-Monitor stack.

Using the Real-time Ethernet Driver SNARF has some disadvantages. As the VxWorks network layering is involved in this architecture, the drivers are usually not optimized for realtime behavior and the needed CPU time is often too high to reach cycle times less than 300 to 500 microseconds. Additionally there is an impact if in parallel to EtherCAT® traffic the VxWorks application needs to use a second network card for transferring TCP/IP data. The single tNetTask is shared by all network drivers.
Using a dedicated EtherCAT® driver these disadvantages can be overcome.

The parameters to the Real-time Ethernet Driver SNARF are setup-specific. The function `CreateLinkParmsFromCmdLineSNARF()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.

### struct EC_T_LINK_PARMS_SNARF

### Public Members

### [EC_T_LINK_PARMS](emll_generic.html.md#_CPPv415EC_T_LINK_PARMS) linkParms

Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_SNARF. 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szAdapterName[EC_SNARF_ADAPTER_NAME_SIZE]

SNARF adapter name (zero terminated) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwRxBuffers

Receive buffer count, only used in RTP context, 0: default to 20 

```cpp
#include "EcLink.h"
EC_T_LINK_PARMS_SNARF oLinkParmsAdapter;

OsMemset(&oLinkParmsAdapter, 0, sizeof(EC_T_LINK_PARMS_SNARF));
oLinkParmsAdapter.linkParms.dwSignature = EC_LINK_PARMS_SIGNATURE_SNARF;
oLinkParmsAdapter.linkParms.dwSize      = sizeof(EC_T_LINK_PARMS_SNARF);
OsStrncpy(oLinkParmsAdapter.linkParms.szDriverIdent,
        EC_LINK_PARMS_IDENT_SNARF, MAX_DRIVER_IDENT_LEN - 1);
OsStrncpy(oLinkParmsAdapter.szAdapterName, "fei0", MAX_DRIVER_IDENT_LEN - 1);
```


# emllsockraw.html.md

# Linux SockRaw - emllSockRaw

emllSockRaw is part of EC-Monitor for Linux. emllSockRaw uses the network interface of the native driver, e.g., eth0, eth1, etc.
The network adapter must be exclusively used for EtherCAT® and cannot be used for LAN (local area network) at the same time.
Because the native Linux driver for the network adapter type is typically not fully real-time capable, it cannot be used for real time applications. If possible, an acontis Real-time Ethernet Driver, e.g. emllIntelGbe, should be used instead.
emllSockRaw does not need the atemsys driver.

#### NOTE
Root privileges are required. A cycle time of 4 ms or higher may be needed.

To run the application without root privileges, set the Linux capability ‘cap_net_raw’ to the application.
: ```console
  $ sudo setcap 'cap_net_raw+pe' ./EcMasterDemo
  ```

To run python scripts without root privileges, create a Python environment and set the Linux capability ‘cap_net_raw’ to the python interpreter.
: ```console
  $ cd Bin/Linux
  $ python3 -m venv --copies PyEnv/
  $ source PyEnv/bin/activate
  $ sudo setcap 'cap_net_raw+pe' PyEnv/bin/python3
  ```

The parameters to emllSockRaw are setup-specific. The function `CreateLinkParmsFromCmdLineSockRaw()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the parameters.

### struct EC_T_LINK_PARMS_SOCKRAW

### Public Members

### [EC_T_LINK_PARMS](emll_generic.html.md#_CPPv415EC_T_LINK_PARMS) linkParms

Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_SOCKRAW. 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szAdapterName[EC_SOCKRAW_ADAPTER_NAME_SIZE]

Native ETH device name, e.g. “eth0” (zero terminated) 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDisableForceBroadcast

Don’t change target MAC address to FF:FF:FF:FF:FF:FF 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bReplacePaddingWithNopCmd

Prevent adding Ethernet padding to work-around EtherCAT corruption bugs from native Linux driver(s) 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bUsePacketMmapRx

Use PACKET_MMAP PACKET_RX_RING for receive 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bSetCoalescingParms

Set Coalescing parameters to enhance the link layer performance 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bSetPromiscuousMode

Enable promiscuous mode at network adapter


# emlltap.html.md

# Windows TAP - emllTap

The parameters to the Windows TAP Real-time Ethernet Driver are setup-specific. The function `CreateLinkParmsFromCmdLineTap()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.

### struct EC_T_LINK_PARMS_TAP

### Public Members

### [EC_T_LINK_PARMS](emll_generic.html.md#_CPPv415EC_T_LINK_PARMS) linkParms

Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_TAP. 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szAdapterName[EC_TAP_ADAPTER_NAME_SIZE]

Native tap device name, e.g. “tap0” (zero terminated) 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szAdapterGuid[EC_TAP_ADAPTER_GUID_SIZE]

GUID of virtual interface to connect (zero terminated) 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) abyMac[6]

MAC address 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwRxBufferCnt

Frame buffer count for IST 

The adapter must be manually installed as described in the OpenVPN’s Windows TAP-driver manual, see [https://community.openvpn.net/openvpn/wiki/GettingTapWindows](https://community.openvpn.net/openvpn/wiki/GettingTapWindows) .

While EC-Monitor is connected to the adapter using emllTap, the MainDevice can use it with e.g. emllNdis.


# error-codes.html.md

# Error Codes

### Groups

|   **No.** | **Group**                                  | **Abbr.**   | **Description**                                                                                                                                                                  |
|-----------|--------------------------------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|         1 | Application Error                          | APP         | Error within application, running the Monitor<br/><br/>E.g. API function call with invalid parameters                                                                            |
|         2 | EtherCAT® network information file problem | ENI         | Monitor configuration XML file mismatches SubDevice configuration on bus<br/><br/>E.g. Bus Topology Scan cannot detect all SubDevices configured within network information file |
|         3 | Monitor parameter configuration            | CFG         | Monitor configuration parameters erroneous<br/><br/>E.g. mailbox command queue not large enough                                                                                  |
|         4 | Bus/SubDevice Error                        | SLV         | SubDevice error<br/><br/>E.g. Working Counter Error                                                                                                                              |
|         5 | Real-time Ethernet Driver                  | LLA         | Real-time Ethernet Driver error (network interface driver)<br/><br/>E.g. Intel Pro/1000 NIC could not be found                                                                   |
|         6 | Remote API                                 | RAS         | Remote API error<br/><br/>E.g. connection to Remote API server is not possible from client                                                                                       |
|         7 | Internal software error                    | ISW         | Monitor internal error<br/><br/>E.g. Monitor state machine in undefined state                                                                                                    |
|         8 | DC Monitor Sync                            | DCM         | DC SubDevice and host time synchronization                                                                                                                                       |
|         9 | Pass-Through-Server                        | PTS         | Initialization/De-Initialization errors                                                                                                                                          |
|        10 | System Setup                               | SYS         | Errors from Operating System or obviously due to System Setup                                                                                                                    |


# error-codes_aoe.html.md

# ADS over EtherCAT® (AoE) Error Codes

<!-- -*- mode: rst -*- -->

<a id="d6-deb-group-e-c-e-r-r-o-r-c-o-d-e-s-a-o-e"></a>

### EC_E_AOE_NO_RTIME

0x9813000D: AoE: No Rtime 

### EC_E_AOE_LOCKED_MEMORY

0x9813000E: AoE: Allocation locked memory 

### EC_E_AOE_MAILBOX

0x9813000F: AoE: Insert mailbox error 

### EC_E_AOE_WRONG_HMSG

0x98130010: AoE: Wrong receive HMSG 

### EC_E_AOE_BAD_TASK_ID

0x98130011: AoE: Bad task ID 

### EC_E_AOE_NO_IO

0x98130012: AoE: No IO 

### EC_E_AOE_UNKNOWN_AMS_COMMAND

0x98130013: AoE: Unknown ADS command 

### EC_E_AOE_WIN32

0x98130014: AoE: Win 32 error 

### EC_E_AOE_LOW_INSTALL_LEVEL

0x98130015: AoE: Low installation level 

### EC_E_AOE_NO_DEBUG

0x98130016: AoE: No debug available 

### EC_E_AOE_AMS_SYNC_WIN32

0x98130017: AoE: Sync Win 32 error 

### EC_E_AOE_AMS_SYNC_TIMEOUT

0x98130018: AoE: Sync Timeout 

### EC_E_AOE_AMS_SYNC_AMS

0x98130019: AoE: Sync AMS error 

### EC_E_AOE_AMS_SYNC_NO_INDEX_MAP

0x9813001A: AoE: Sync no index map 

### EC_E_AOE_TCP_SEND

0x9813001B: AoE: TCP send error 

### EC_E_AOE_HOST_UNREACHABLE

0x9813001C: AoE: Host unreachable 

### EC_E_AOE_INVALIDAMSFRAGMENT

0x9813001D: AoE: Invalid AMS fragment 

### EC_E_AOE_NO_LOCKED_MEMORY

0x9813001E: AoE: No allocation locked memory 

### EC_E_AOE_MAILBOX_FULL

0x9813001F: AoE: Mailbox full 

\\newpage


# error-codes_coe.html.md

# CAN application protocol over EtherCAT® (CoE) SDO Error Codes

<!-- -*- mode: rst -*- -->

<a id="df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e"></a>

### EC_E_SDO_ABORTCODE_TOGGLE

0x98110040: SLV: SDO: Toggle bit not alternated (CoE abort code 0x05030000 of slave) 

### EC_E_SDO_ABORTCODE_TIMEOUT

0x98110041: SLV: SDO: Protocol timed out (CoE abort code 0x05040000 of slave) 

### EC_E_SDO_ABORTCODE_CCS_SCS

0x98110042: SLV: SDO: Client/server command specifier not valid or unknown (CoE abort code 0x05040001 of slave) 

### EC_E_SDO_ABORTCODE_BLK_SIZE

0x98110043: SLV: SDO: Invalid block size (block mode only) (CoE abort code 0x05040002 of slave) 

### EC_E_SDO_ABORTCODE_SEQNO

0x98110044: SLV: SDO: Invalid sequence number (block mode only) (CoE abort code 0x05040003 of slave) 

### EC_E_SDO_ABORTCODE_CRC

0x98110045: SLV: SDO: CRC error (block mode only) (CoE abort code 0x05040004 of slave) 

### EC_E_SDO_ABORTCODE_MEMORY

0x98110046: SLV: SDO: Out of memory (CoE abort code 0x05040005 of slave) 

### EC_E_SDO_ABORTCODE_ACCESS

0x98110047: SLV: SDO: Unsupported access to an object (CoE abort code 0x06010000 of slave) 

### EC_E_SDO_ABORTCODE_WRITEONLY

0x98110048: SLV: SDO: Attempt to read a write only object (CoE abort code 0x06010001 of slave) 

### EC_E_SDO_ABORTCODE_READONLY

0x98110049: SLV: SDO: Attempt to write a read only object (CoE abort code 0x06010002 of slave) 

### EC_E_SDO_ABORTCODE_INDEX

0x9811004A: SLV: SDO: Object does not exist in the object dictionary (CoE abort code 0x06020000 of slave) 

### EC_E_SDO_ABORTCODE_PDO_MAP

0x9811004B: SLV: SDO: Object cannot be mapped to the PDO (CoE abort code 0x06040041 of slave) 

### EC_E_SDO_ABORTCODE_PDO_LEN

0x9811004C: SLV: SDO: The number and length of the objects to be mapped would exceed PDO length (CoE abort code 0x06040042 of slave) 

### EC_E_SDO_ABORTCODE_P_INCOMP

0x9811004D: SLV: SDO: General parameter incompatibility reason (CoE abort code 0x06040043 of slave) 

### EC_E_SDO_ABORTCODE_I_INCOMP

0x9811004E: SLV: SDO: General internal incompatibility in the device (CoE abort code 0x06040047 of slave) 

### EC_E_SDO_ABORTCODE_HARDWARE

0x9811004F: SLV: SDO: Access failed due to a hardware error (CoE abort code 0x06060000 of slave) 

### EC_E_SDO_ABORTCODE_DATA_LENGTH_NOT_MATCH

0x98110050: SLV: SDO: Data type does not match, length of service parameter does not match (CoE abort code 0x06070010 of slave) 

### EC_E_SDO_ABORTCODE_DATA_LENGTH_TOO_HIGH

0x98110051: SLV: SDO: Data type does not match, length of service parameter too high (CoE abort code 0x06070012 of slave) 

### EC_E_SDO_ABORTCODE_DATA_LENGTH_TOO_LOW

0x98110052: SLV: SDO: Data type does not match, length of service parameter too low (CoE abort code 0x06070013 of slave) 

### EC_E_SDO_ABORTCODE_OFFSET

0x98110053: SLV: SDO: Sub-index does not exist (CoE abort code 0x06090011 of slave) 

### EC_E_SDO_ABORTCODE_VALUE_RANGE

0x98110054: SLV: SDO: Value range of parameter exceeded (only for write access) (CoE abort code 0x06090030 of slave) 

### EC_E_SDO_ABORTCODE_VALUE_TOO_HIGH

0x98110055: SLV: SDO: Value of parameter written too high (CoE abort code 0x06090031 of slave) 

### EC_E_SDO_ABORTCODE_VALUE_TOO_LOW

0x98110056: SLV: SDO: Value of parameter written too low (CoE abort code 0x06090032 of slave) 

### EC_E_SDO_ABORTCODE_MINMAX

0x98110057: SLV: SDO: Maximum value is less than minimum value (CoE abort code 0x06090036 of slave) 

### EC_E_SDO_ABORTCODE_GENERAL

0x98110058: SLV: SDO: General error (CoE abort code 0x08000000 of slave) 

### EC_E_SDO_ABORTCODE_TRANSFER

0x98110059: SLV: SDO: Data cannot be transferred or stored to the application (CoE abort code 0x08000020 of slave) 

### EC_E_SDO_ABORTCODE_TRANSFER_LOCAL_CONTROL

0x9811005A: SLV: SDO: Data cannot be transferred or stored to the application because of local control (CoE abort code 0x08000021 of slave) 

### EC_E_SDO_ABORTCODE_TRANSFER_DEVICE_STATE

0x9811005B: SLV: SDO: Data cannot be transferred or stored to the application because of the present device state (CoE abort code 0x08000022 of slave) 

### EC_E_SDO_ABORTCODE_DICTIONARY

0x9811005C: SLV: SDO: Object dictionary dynamic generation fails or no object dictionary is present (e.g. object dictionary is generated from file and generation fails because of an file error) (CoE abort code 0x08000023 of slave) 

### EC_E_SDO_ABORTCODE_UNKNOWN

0x9811005D: SLV: SDO: Unknown code (Unknown CoE abort code of slave) 

### EC_E_SDO_ABORTCODE_MODULE_ID_LIST_NOT_MATCH

0x9811005E: Detected Module Ident List (0xF030) and Configured Module Ident list (0xF050) does not match 

### EC_E_SDO_ABORTCODE_SI_NOT_WRITTEN

0x98130004: SLV: SDO: Sub Index cannot be written, SI0 must be 0 for write access (CoE abort code 0x06010003 of slave) 

### EC_E_SDO_ABORTCODE_CA_TYPE_MISM

0x98130005: SLV: SDO: Complete access not supported for objects of variable length such as ENUM object types (CoE abort code 0x06010004 of slave) 

### EC_E_SDO_ABORTCODE_OBJ_TOO_BIG

0x98130006: SLV: SDO: Object length exceeds mailbox size (CoE abort code 0x06010005 of slave) 

### EC_E_SDO_ABORTCODE_PDO_MAPPED

0x98130007: SLV: SDO: Object mapped to RxPDO, SDO Download blocked (CoE abort code 0x06010006 of slave) 

\\newpage


# error-codes_dcm.html.md

# DCM Error Codes

<!-- -*- mode: rst -*- -->

<a id="d1-d4e-group-e-c-e-r-r-o-r-c-o-d-e-s-d-c-m"></a>

### DCM_E_ERROR

0x981201C0: Unspecific DCM Error 

### DCM_E_NOTINITIALIZED

0x981201C1: Not initialized 

### DCM_E_MAX_CTL_ERROR_EXCEED

0x981201C2: DCM controller - synchronization out of limit 

### DCM_E_NOMEMORY

0x981201C3: Not enough memory 

### DCM_E_INVALID_HWLAYER

0x981201C4: Hardware layer - (BSP) invalid 

### DCM_E_TIMER_MODIFY_ERROR

0x981201C5: Hardware layer - error modifying timer 

### DCM_E_TIMER_NOT_RUNNING

0x981201C6: Hardware layer - timer not running 

### DCM_E_WRONG_CPU

0x981201C7: Hardware layer - function called on wrong CPU 

### DCM_E_INVALID_SYNC_PERIOD

0x981201C8: Invalid DC sync period length (invalid clock master?) 

### DCM_E_INVALID_SETVAL

0x981201C9: DCM controller SetVal too small 

### DCM_E_DRIFT_TO_HIGH

0x981201CA: DCM controller - Drift between local timer and ref clock to high 

### DCM_E_BUS_CYCLE_WRONG

0x981201CB: DCM controller - Bus cycle time (dwBusCycleTimeUsec) doesn’t match real cycle 

### DCX_E_NO_EXT_CLOCK

0x981201CC: DCX controller - No external synchronization clock found 

### DCM_E_INVALID_DATA

0x981201CD: DCM controller - Invalid data 

\\newpage


# error-codes_foe.html.md

# File Transfer over EtherCAT® (FoE) Error Codes

<!-- -*- mode: rst -*- -->

<a id="d0-d24-group-e-c-e-r-r-o-r-c-o-d-e-s-f-o-e"></a>

### EC_E_FOE_ERRCODE_NOTDEFINED

0x98110060: SLV: ERROR FoE: not defined (FoE Error Code 0 (0x8000) of slave) 

### EC_E_FOE_ERRCODE_NOTFOUND

0x98110061: SLV: ERROR FoE: not found (FoE Error Code 1 (0x8001) of slave) 

### EC_E_FOE_ERRCODE_ACCESS

0x98110062: SLV: ERROR FoE: access denied (FoE Error Code 2 (0x8002) of slave) 

### EC_E_FOE_ERRCODE_DISKFULL

0x98110063: SLV: ERROR FoE: disk full (FoE Error Code 3 (0x8003) of slave) 

### EC_E_FOE_ERRCODE_ILLEGAL

0x98110064: SLV: ERROR FoE: illegal (FoE Error Code 4 (0x8004) of slave) 

### EC_E_FOE_ERRCODE_PACKENO

0x98110065: SLV: ERROR FoE: packet number wrong (FoE Error Code 5 (0x8005) of slave) 

### EC_E_FOE_ERRCODE_EXISTS

0x98110066: SLV: ERROR FoE: already exists (FoE Error Code 6 (0x8006) of slave) 

### EC_E_FOE_ERRCODE_NOUSER

0x98110067: SLV: ERROR FoE: no user (FoE Error Code 7 (0x8007) of slave) 

### EC_E_FOE_ERRCODE_BOOTSTRAPONLY

0x98110068: SLV: ERROR FoE: bootstrap only (FoE Error Code 8 (0x8008) of slave) 

### EC_E_FOE_ERRCODE_NOTINBOOTSTRAP

0x98110069: SLV: ERROR FoE: Downloaded file name is not valid in Bootstrap state (FoE Error Code 9 (0x8009) of slave) 

### EC_E_FOE_ERRCODE_INVALIDPASSWORD

0x9811006A: SLV: ERROR FoE: no rights (FoE Error Code 10 (0x800A) of slave) 

### EC_E_FOE_ERRCODE_PROGERROR

0x9811006B: SLV: ERROR FoE: program error (FoE Error Code 11 (0x800B) of slave) 

### EC_E_FOE_ERRCODE_INVALID_CHECKSUM

0x9811006C: FoE: Wrong checksum 

### EC_E_FOE_ERRCODE_INVALID_FIRMWARE

0x9811006D: SLV: ERROR FoE: Firmware does not fit for Hardware (FoE Error Code 13 (0x800D) of slave) 

### EC_E_FOE_ERRCODE_NO_FILE

0x9811006F: SLV: ERROR FoE: No file to read (FoE Error Code 15 (0x800F) of slave) 

### EC_E_NO_FOE_SUPPORT_BS

0x9811010F: APP: ERROR FoE: Protocol not supported in boot strap (e.g. Application requested FoE in Bootstrap although slave does not support this) 

### EC_E_FOE_ERRCODE_MAX_FILE_SIZE

0x9811017A: APP: ERROR FoE: File is bigger than max file size (e.g. Slave returned more data than the buffer provided by application can store.) 

### EC_E_FOE_ERRCODE_FILE_HEAD_MISSING

0x98130001: SLV: ERROR FoE: File header does not exist (FoE Error Code 16 (0x8010) of slave) 

### EC_E_FOE_ERRCODE_FLASH_PROBLEM

0x98130002: SLV: ERROR FoE: Flash problem (FoE Error Code 17 (0x8011) of slave) 

### EC_E_FOE_ERRCODE_FILE_INCOMPATIBLE

0x98130003: SLV: ERROR FoE: File incompatible (FoE Error Code 18 (0x8012) of slave) 

\\newpage


# error-codes_generic.html.md

# Generic Error Codes

<!-- -*- mode: rst -*- -->

<a id="d3-d2f-group-e-c-e-r-r-o-r-c-o-d-e-s-g-e-n-e-r-i-c"></a>

### EC_E_NOERROR

0x00000000: No Error 

### EC_E_ERROR

0x98110000: Unspecific Error 

### EMRAS_E_ERROR

0x98110180: Unspecific RAS Error 

### EC_E_NOTSUPPORTED

0x98110001: APP: Feature not supported (e.g. function or property not available) 

### EC_E_INVALIDINDEX

0x98110002: APP: Invalid index (e.g. CoE: invalid SDO index) 

### EC_E_INVALIDOFFSET

0x98110003: ISW: Invalid offset (e.g. invalid offset while accessing Process Data Image) 

### EC_E_CANCEL

0x98110004: APP: Cancel (e.g. EtherCAT stack should abort current mailbox transfer) 

### EC_E_INVALIDSIZE

0x98110005: APP: Invalid size 

### EC_E_INVALIDDATA

0x98110006: ISW: Invalid data (multiple error sources) 

### EC_E_NOTREADY

0x98110007: ISW: Not ready (multiple error sources) 

### EC_E_BUSY

0x98110008: APP: Busy (e.g. EtherCAT stack is currently busy and not available to process the API request. The function may be called again later) 

### EC_E_ACYC_FRM_FREEQ_EMPTY

0x98110009: ISW: Cannot queue acyclic EtherCAT command (Acyclic command queue is full. Possible solution: Increase of configuration value dwMaxQueuedEthFrames) 

### EC_E_NOMEMORY

0x9811000A: CFG: No memory left (e.g. memory full / fragmented)) 

### EC_E_INVALIDPARM

0x9811000B: APP: Invalid parameter (e.g. API function called with erroneous parameter set) 

### EC_E_NOTFOUND

0x9811000C: APP: Not found (e.g. Network Information File ENI not found or API called with invalid slave ID) 

### EC_E_DUPLICATE

0x9811000D: ISW: Duplicated fixed address detected (handled internally) 

### EC_E_INVALIDSTATE

0x9811000E: ISW: Invalid state (EtherCAT stack not initialized or not configured) 

### EC_E_TIMER_LIST_FULL

0x9811000F: ISW: Cannot add slave to timer list (slave timer list full) 

### EC_E_TIMEOUT

0x98110010: Timeout 

### EC_E_OPENFAILED

0x98110011: ISW: Open failed 

### EC_E_SENDFAILED

0x98110012: LLA: Frame send failed 

### EC_E_INSERTMAILBOX

0x98110013: CFG: Insert Mailbox error (internal limit MAX_QUEUED_COE_CMDS: 20) 

### EC_E_INVALIDCMD

0x98110014: ISW: Invalid Command (Unknown mailbox command code) 

### EC_E_UNKNOWN_MBX_PROTOCOL

0x98110015: ISW: Unknown Mailbox Protocol Command (Unknown Mailbox protocol or mailbox command with unknown protocol association) 

### EC_E_ACCESSDENIED

0x98110016: ISW: Access Denied (e.g. master internal software error) 

### EC_E_IDENTIFICATIONFAILED

0x98110017: ENI: Identification failed (e.g. identification command failed) 

### EC_E_LOCK_CREATE_FAILED

0x98110018: SYS: Create lock failed (e.g. OsCreateLockTyped failed) 

### EC_E_VERSION_MISMATCH

0x98110019: APP: Version mismatch for loaded library 

### EC_E_PRODKEY_INVALID

0x9811001A: CFG: Product Key Invalid (e.g. application using protected version of the stack, which stops operation after the evaluation time limit reached if a license is not provided) 

### EC_E_WRONG_FORMAT

0x9811001B: ENI: Wrong configuration format (e.g. Network information file empty or malformed), SLV: Malformed EEPROM content 

### EC_E_FEATURE_DISABLED

0x9811001C: APP: Feature disabled (e.g. Application tried to perform a missing or disabled API function) 

### EC_E_SHADOW_MEMORY

0x9811001D: Shadow memory requested in wrong mode 

### EC_E_BUSCONFIG_MISMATCH

0x9811001E: ENI: Bus configuration mismatch (e.g. Network information file and currently connected bus topology does not match) 

### EC_E_CONFIGDATAREAD

0x9811001F: ENI: Error reading configuration file (e.g. Network information file could not be read) 

### EC_E_ENI_NO_SAFEOP_OP_SUPPORT

0x98110020: Configuration doesn’t support SAFEOP and OP requested state 

### EC_E_XML_CYCCMDS_MISSING

0x98110021: ENI: Cyclic commands are missing (e.g. Network information file does not contain cyclic commands) 

### EC_E_XML_ALSTATUS_READ_MISSING

0x98110022: ENI: AL_STATUS register read missing in XML file for at least one state (e.g. Read of AL Status register is missing in cyclic part of given network information file) 

### EC_E_MCSM_FATAL_ERROR

0x98110023: ISW: Fatal internal McSm (master control state machine is in an undefined state) 

### EC_E_SLAVE_ERROR

0x98110024: SLV: Slave error (e.g. A slave error was detected. See also EC_NOTIFY_STATUS_SLAVE_ERROR and EC_NOTIFY_SLAVE_ERROR_STATUS_INFO) 

### EC_E_FRAME_LOST

0x98110025: SLV: Frame lost, IDX mismatch (EtherCAT frame(s) lost on bus, means the response was not received. In case this error shows frequently a problem with the wiring could be the cause) 

### EC_E_CMD_MISSING

0x98110026: SLV: At least one EtherCAT command is missing in the received frame (e.g. received EtherCAT frame incomplete) 

### EC_E_CYCCMD_WKC_ERROR

0x98110027: Cyclic command WKC error 

### EC_E_INVALID_DCL_MODE

0x98110028: APP: IOCTL EC_IOCTL_DC_LATCH_REQ_LTIMVALS invalid in DCL auto read mode (this function cannot be used if DC Latching is running in mode “Auto Read”) 

### EC_E_AI_ADDRESS

0x98110029: SLV: Auto increment address increment mismatch (e.g. Network information file and bus topology doesn’t match any more. Error shows only, if an already recognized slave isn’t present any more) 

### EC_E_INVALID_SLAVE_STATE

0x9811002A: APP: Slave in invalid state, e.g. not in OP (API not callable in this state) (mailbox commands are not allowed in current slave state) 

### EC_E_SLAVE_NOT_ADDRESSABLE

0x9811002B: SLV: Station address lost (or slave missing) - FPRD to AL_STATUS failed (e.g. Slave had a power cycle) 

### EC_E_CYC_CMDS_OVERFLOW

0x9811002C: ENI: Too many cyclic commands in XML configuration file (e.g. EC_T_INIT_MASTER_PARMS.dwMaxAcycFramesQueued too small) 

### EC_E_LINK_DISCONNECTED

0x9811002D: SLV: Ethernet link cable disconnected (e.g. EtherCAT bus segment not connected to network interface) 

### EC_E_MASTERCORE_INACCESSIBLE

0x9811002E: RAS: Master core not accessible (e.g. Connection to remote server was terminated or master instance has been stopped on remote side) 

### EC_E_COE_MBXSND_WKC_ERROR

0x9811002F: SLV: CoE mailbox send: working counter (e.g. CoE mailbox couldn’t be read on slave, slave didn’t read out mailbox since last write) 

### EC_E_COE_MBXRCV_WKC_ERROR

0x98110030: SLV: CoE mailbox receive: working counter (e.g. CoE mailbox couldn’t be read from slave) 

### EC_E_NO_MBX_SUPPORT

0x98110031: APP: No mailbox support (e.g. Slave does not support mailbox access) 

### EC_E_NO_COE_SUPPORT

0x98110032: ENI: CoE protocol not supported (e.g. Configuration error or slave information file doesn’t match slave firmware) 

### EC_E_NO_EOE_SUPPORT

0x98110033: ENI: EoE protocol not supported (e.g. Configuration error or slave information file doesn’t match slave firmware) 

### EC_E_NO_FOE_SUPPORT

0x98110034: ENI: FoE protocol not supported (e.g. Configuration error or slave information file doesn’t match slave firmware) 

### EC_E_NO_SOE_SUPPORT

0x98110035: ENI: SoE protocol not supported (e.g. Configuration error or slave information file doesn’t match slave firmware) 

### EC_E_NO_VOE_SUPPORT

0x98110036: ENI: VoE protocol not supported (e.g. Configuration error or slave information file doesn’t match slave firmware) 

### EC_E_EVAL_VIOLATION

0x98110037: ENI: Configuration violates Evaluation limits (obsolete) 

### EC_E_EVAL_EXPIRED

0x98110038: CFG: Evaluation Time limit reached (e.g. License not provided and evaluation period (1 hour) of protected version exceeded) 

### EC_E_LICENSE_MISSING

0x98110039: License key invalid or missing 

### EC_E_CFGFILENOTFOUND

0x98110070: CFG: Network configuration file not found (e.g. path to configuration file (XML) was wrong or the file is not available) 

### EC_E_EEPROMREADERROR

0x98110071: SLV: Command error while EEPROM upload (read slave EEPROM) 

### EC_E_EEPROMWRITEERROR

0x98110072: SLV: Command error while EEPROM download (write slave EEPROM) 

### EC_E_XML_CYCCMDS_SIZEMISMATCH

0x98110073: ENI: Cyclic command wrong size (too long) (size in network configuration file (XML) does not match size of process data) 

### EC_E_XML_INVALID_INP_OFF

0x98110074: ENI: Invalid input offset in cyclic command, please check InputOffs 

### EC_E_XML_INVALID_OUT_OFF

0x98110075: ENI: Invalid output offset in cyclic command, please check OutputOffs 

### EC_E_PORTCLOSE

0x98110076: Port close failed 

### EC_E_PORTOPEN

0x98110077: Port open failed 

### EC_E_SLAVE_NOT_PRESENT

0x9811010E: APP / SLV: command not executed (slave not present on bus) (e.g. slave disappeared or was never present) 

### EC_E_EEPROMRELOADERROR

0x98110110: Command error while EEPROM reload 

### EC_E_SLAVECTRLRESETERROR

0x98110111: Command error while Reset Slave Controller 

### EC_E_SYSDRIVERMISSING

0x98110112: SYS: Cannot open system driver (e.g. system driver was not loaded) 

### EC_E_BUSCONFIG_TOPOCHANGE

0x9811011E: Bus configuration not detected, Topology changed (e.g. Topology changed while scanning bus) 

### EC_E_EOE_MBX_WKC_ERROR

0x9811011F: EoE: Mailbox receive: working counter 

### EC_E_FOE_MBX_WKC_ERROR

0x98110120: FoE: Mailbox receive: working counter 

### EC_E_SOE_MBX_WKC_ERROR

0x98110121: SoE: mailbox receive: working counter 

### EC_E_AOE_MBX_WKC_ERROR

0x98110122: AoE: Mailbox receive: working counter 

### EC_E_VOE_MBX_WKC_ERROR

0x98110123: SLV: VoE mailbox send: working counter (VoE mailbox couldn’t be written) 

### EC_E_EEPROMASSIGNERROR

0x98110124: SLV: EEPROM assignment failed 

### EC_E_MBX_ERROR_TYPE

0x98110125: SLV: Unknown mailbox error code received in mailbox 

### EC_E_REDLINEBREAK

0x98110126: SLV: Redundancy line break (e.g. cable break between slaves or between EtherCAT network adapter and first slave) 

### EC_E_XML_INVALID_CMD_WITH_RED

0x98110127: ENI: Invalid EtherCAT command in cyclic frame with redundancy (e.g. BRW commands are not allowed with redundancy) 

### EC_E_XML_PREV_PORT_MISSING

0x98110128: ENI: <PreviousPort>-tag is missing (e.g. if the auto increment address is not the first slave on the bus we check if a previous port tag OR a hot connect tag is available) 

### EC_E_XML_DC_CYCCMDS_MISSING

0x98110129: DC enabled and DC cyclic commands missing (e.g. access to 0x0900) 

### EC_E_DLSTATUS_IRQ_TOPOCHANGED

0x98110130: SLV: Data link (DL) status interrupt because of changed topology (automatically handled by master) 

### EC_E_PTS_IS_NOT_RUNNING

0x98110131: PTS: Pass Through Server is not running (Pass-Through-Server was tried to be enabled/disabled or stopped without being started) 

### EC_E_PTS_IS_RUNNING

0x98110132: PTS: Pass Through Server is running (obsolete, replaced by EC_E_ADS_IS_RUNNING) 

### EC_E_ADS_IS_RUNNING

0x98110132: PTS: ADS adapter (Pass Through Server) is running (API call conflicts with ADS state (running)) 

### EC_E_PTS_THREAD_CREATE_FAILED

0x98110133: PTS: Could not start the Pass Through Server 

### EC_E_PTS_SOCK_BIND_FAILED

0x98110134: PTS: The Pass Through Server could not bind the IP address with a socket (e.g. Possibly because the IPaddress (and Port) is already in use or the IP-address does not exist) 

### EC_E_PTS_NOT_ENABLED

0x98110135: PTS: The Pass Through Server is running but not enabled 

### EC_E_PTS_LL_MODE_NOT_SUPPORTED

0x98110136: PTS: The Link Layer mode is not supported by the Pass Through Server (e.g. The Master is running in interrupt mode but the Pass-Through-Server only supports polling mode) 

### EC_E_VOE_NO_MBX_RECEIVED

0x98110137: SLV: No VoE mailbox received yet from specific slave 

### EC_E_DC_REF_CLOCK_SYNC_OUT_UNIT_DISABLED

0x98110138: DC (time loop control) unit of reference clock disabled 

### EC_E_DC_REF_CLOCK_NOT_FOUND

0x98110139: SLV: Reference clock not found! May happen if reference clock is removed from network. 

### EC_E_MBX_CMD_WKC_ERROR

0x9811013B: SLV: Mailbox command working counter error (e.g. Mailbox init command Retry Count exceeded) 

### EC_E_NO_AOE_SUPPORT

0x9811013C: APP / SLV: AoE: Protocol not supported (e.g. Application calls AoE-API although not implemented at slave) 

### EC_E_AOE_INV_RESPONSE_SIZE

0x9811013D: AoE: Invalid AoE response received 

### EC_E_AOE_ERROR

0x9811013E: AoE: Common AoE device error 

### EC_E_AOE_SRVNOTSUPP

0x9811013F: AoE: Service not supported by server 

### EC_E_AOE_INVALIDGRP

0x98110140: AoE: Invalid index group 

### EC_E_AOE_INVALIDOFFSET

0x98110141: AoE: Invalid index offset 

### EC_E_AOE_INVALIDACCESS

0x98110142: AoE: Reading/writing not permitted 

### EC_E_AOE_INVALIDSIZE

0x98110143: AoE: Parameter size not correct 

### EC_E_AOE_INVALIDDATA

0x98110144: AoE: Invalid parameter value(s) 

### EC_E_AOE_NOTREADY

0x98110145: AoE: Device not in a ready state 

### EC_E_AOE_BUSY

0x98110146: AoE: Device busy 

### EC_E_AOE_INVALIDCONTEXT

0x98110147: AoE: Invalid context 

### EC_E_AOE_NOMEMORY

0x98110148: AoE: Out of memory 

### EC_E_AOE_INVALIDPARM

0x98110149: AoE: Invalid parameter value(s) 

### EC_E_AOE_NOTFOUND

0x9811014A: AoE: Not found 

### EC_E_AOE_SYNTAX

0x9811014B: AoE: Syntax error in command or file 

### EC_E_AOE_INCOMPATIBLE

0x9811014C: AoE: Objects do not match 

### EC_E_AOE_EXISTS

0x9811014D: AoE: Object already exists 

### EC_E_AOE_SYMBOLNOTFOUND

0x9811014E: AoE: Symbol not found 

### EC_E_AOE_SYMBOLVERSIONINVALID

0x9811014F: AoE: Symbol version invalid 

### EC_E_AOE_INVALIDSTATE

0x98110150: AoE: Server in invalid state 

### EC_E_AOE_TRANSMODENOTSUPP

0x98110151: AoE: AdsTransMode not supported 

### EC_E_AOE_NOTIFYHNDINVALID

0x98110152: AoE: Notification handle invalid 

### EC_E_AOE_CLIENTUNKNOWN

0x98110153: AoE: Notification client not registered 

### EC_E_AOE_NOMOREHDLS

0x98110154: AoE: No more notification handles 

### EC_E_AOE_INVALIDWATCHSIZE

0x98110155: AoE: Size for watch to big 

### EC_E_AOE_NOTINIT

0x98110156: AoE: Device not initialized 

### EC_E_AOE_TIMEOUT

0x98110157: AoE: Device has a timeout 

### EC_E_AOE_NOINTERFACE

0x98110158: AoE: Query interface failed 

### EC_E_AOE_INVALIDINTERFACE

0x98110159: AoE: Wrong interface required 

### EC_E_AOE_INVALIDCLSID

0x9811015A: AoE: Class ID invalid 

### EC_E_AOE_INVALIDOBJID

0x9811015B: AoE: Object ID invalid 

### EC_E_AOE_PENDING

0x9811015C: AoE: Request pending 

### EC_E_AOE_ABORTED

0x9811015D: AoE: Request aborted 

### EC_E_AOE_WARNING

0x9811015E: AoE: Signal warning 

### EC_E_AOE_INVALIDARRAYIDX

0x9811015F: AoE: Invalid array index 

### EC_E_AOE_SYMBOLNOTACTIVE

0x98110160: AoE: Symbol not active -> release handle and try again 

### EC_E_AOE_ACCESSDENIED

0x98110161: AoE: Access denied 

### EC_E_AOE_INTERNAL

0x98110162: AoE: Internal error 

### EC_E_AOE_TARGET_PORT_NOT_FOUND

0x98110163: AoE: Target port not found 

### EC_E_AOE_TARGET_MACHINE_NOT_FOUND

0x98110164: AoE: Target machine not found 

### EC_E_AOE_UNKNOWN_CMD_ID

0x98110165: AoE: Unknown command ID 

### EC_E_AOE_PORT_NOT_CONNECTED

0x98110166: AoE: Port not connected 

### EC_E_AOE_INVALID_AMS_LENGTH

0x98110167: AoE: Invalid AMS length 

### EC_E_AOE_INVALID_AMS_ID

0x98110168: AoE: invalid AMS Net ID 

### EC_E_AOE_PORT_DISABLED

0x98110169: AoE: Port disabled 

### EC_E_AOE_PORT_CONNECTED

0x9811016A: AoE: Port already connected 

### EC_E_AOE_INVALID_AMS_PORT

0x9811016B: AoE: Invalid AMS port 

### EC_E_AOE_NO_MEMORY

0x9811016C: AoE: No memory 

### EC_E_AOE_VENDOR_SPECIFIC

0x9811016D: AoE: Vendor specific AoE device error 

### EC_E_XML_AOE_NETID_INVALID

0x9811016E: ENI: AoE: Invalid NetID (e.g. Error from Configuration Tool) 

### EC_E_MAX_BUS_SLAVES_EXCEEDED

0x9811016F: CFG: Error: Maximum number of bus slave has been exceeded (The maximum number of preallocated bus slave objects is too small. The maximum number can be adjusted by the master initialization parameter EC_T_INITMASTERPARMS.dwMaxBusSlaves) 

### EC_E_MBXERR_SYNTAX

0x98110170: SLV: Mailbox error: Syntax of 6 octet Mailbox header is wrong (Slave error mailbox return value: 0x01) 

### EC_E_MBXERR_UNSUPPORTEDPROTOCOL

0x98110171: SLV: Mailbox error: The Mailbox protocol is not supported (Slave error mailbox return value: 0x02) 

### EC_E_MBXERR_INVALIDCHANNEL

0x98110172: SLV: Mailbox error: Field contains wrong value (Slave error mailbox return value: 0x03) 

### EC_E_MBXERR_SERVICENOTSUPPORTED

0x98110173: SLV: Mailbox error: The addressed service in the mailbox protocol is not supported (Slave error mailbox return value: 0x04) 

### EC_E_MBXERR_INVALIDHEADER

0x98110174: SLV: Mailbox error: The mailbox protocol header of the mailbox protocol is wrong (Slave error mailbox return value: 0x05) 

### EC_E_MBXERR_SIZETOOSHORT

0x98110175: SLV: Mailbox error: Length of received mailbox data is too short (Slave error mailbox return value: 0x06) 

### EC_E_MBXERR_NOMOREMEMORY

0x98110176: SLV: Mailbox error: Mailbox protocol can not be processed because of limited resources (Slave error mailbox return value: 0x07) 

### EC_E_MBXERR_INVALIDSIZE

0x98110177: SLV: Mailbox error: The length of data is inconsistent (Slave error mailbox return value: 0x08) 

### EC_E_DC_SLAVES_BEFORE_REF_CLOCK

0x98110178: ENI: Slaves with DC configured present on bus before reference clock (e.g. The first DC Slave was not configured as potential reference clock) 

### EC_E_DATA_TYPE_CONVERSION_FAILED

0x98110179: Data type conversion failed 

### EC_E_LINE_CROSSED

0x9811017B: Line crossed (cabling wrong) 

### EC_E_LINE_CROSSED_SLAVE_INFO

0x9811017C: Line crossed at slave (obsolete) 

### EC_E_ADO_NOT_SUPPORTED

0x9811017E: SLV: ADO for slave identification not supported (e.g. Request ID mechanism (ADO 0x134) not supported by slave) 

### EC_E_FRAMELOSS_AFTER_SLAVE

0x9811017F: Frameloss after Slave (opening port destroys communication) 

### EC_E_OEM_SIGNATURE_MISMATCH

0x98130008: ENI, OEM: Manufacturer signature mismatch 

### EC_E_ENI_ENCRYPTION_WRONG_VERSION

0x98130009: ENI, OEM: ENI encryption algorithm version not supported 

### EC_E_ENI_ENCRYPTED

0x9813000A: OEM: Loading encrypted ENI needs OEM key 

### EC_E_OEM_KEY_MISMATCH

0x9813000B: RAS, APP: OEM key mismatch 

### EC_E_OEM_KEY_MISSING

0x9813000C: APP: OEM key access needs OEM key set (e.g. Application must call esSetOemKey (HiL) or set EC_T_LINK_PARMS_SIMULATOR::qwOemKey (SiL)) 

### EC_E_S2SMBX_NOT_CONFIGURED

0x98130020: S2S: Not Configured 

### EC_E_S2SMBX_NO_MEMORY

0x98130021: S2S: No Memory 

### EC_E_S2SMBX_NO_DESCRIPTOR

0x98130022: S2S: No Descriptor 

### EC_E_S2SMBX_DEST_SLAVE_NOT_FOUND

0x98130023: S2S: Destination Slave not found 

### EC_E_MASTER_RED_STATE_INACTIVE

0x98130024: APP: Master Redundancy State is INACTIVE (e.g. API not allowed in current Master Redundancy State) 

### EC_E_MASTER_RED_STATE_ACTIVE

0x98130025: APP: Master Redundancy State is ACTIVE (e.g. API not allowed in current Master Redundancy State) 

### EC_E_JUNCTION_RED_LINE_BREAK

0x98130026: Junction redundancy line break 

### EC_E_VALIDATION_ERROR

0x98130027: Validation error (validation data mismatch) 

### EC_E_TIMEOUT_WAITING_FOR_DC

0x98130028: Timeout waiting for DC 

### EC_E_TIMEOUT_WAITING_FOR_DCM

0x98130029: Timeout waiting for DCM 

### EC_E_SIGNATURE_MISMATCH

0x98130030: Signature mismatch 

### EC_E_PDIWATCHDOG

0x98130031: PDI watchdog expired 

### EC_E_BAD_CONNECTION

0x98130032: Bad connection 

### EC_E_XML_INCONSISTENT

0x98130033: ENI: Inconsistent content


# error-codes_ras.html.md

# Remote API Error Codes

<!-- -*- mode: rst -*- -->

<a id="d3-d00-group-e-c-e-r-r-o-r-c-o-d-e-s-r-a-s"></a>

### EC_E_SOCKET_DISCONNECTED

0x9811017D: RAS: Socket disconnected (e.g. IP connection terminated or lost) 

### EMRAS_E_INVALIDCOOKIE

0x98110181: RAS: Invalid Cookie (e.g.obsolete) 

### EMRAS_E_MULSRVDISMULCON

0x98110183: RAS: Connect 2nd server denied because Multi Server support is disabled (obsolete) 

### EMRAS_E_LOGONCANCELLED

0x98110184: RAS: Logon canceled (Server-side connection reject while opening a client connection.) 

### EMRAS_E_INVALIDVERSION

0x98110186: RAS: Invalid Version (Connection reject because of using mismatching protocol versions on client and server side) 

### EMRAS_E_INVALIDACCESSCONFIG

0x98110187: RAS: Access configuration is invalid (e.g. SPoC access configuration invalid) 

### EMRAS_E_ACCESSLESS

0x98110188: RAS: No access to this call at this access level (e.g. a higher SPoC access level is needed to use the called Remote API function) 

### EMRAS_E_INVALIDDATARECEIVED

0x98110189: RAS: Invalid data received (communication corrupted) 

### EMRAS_EVT_SERVERSTOPPED

0x98110191: RAS: Server stopped (e.g. connection dropped because of Remote API Server stop) 

### EMRAS_EVT_WDEXPIRED

0x98110192: RAS: Watchdog expired (e.g. connection dropped because of missing keep-alive messages) 

### EMRAS_EVT_RECONEXPIRED

0x98110193: RAS: Reconnect expired (obsolete) 

### EMRAS_EVT_CLIENTLOGON

0x98110194: RAS Server: Client logged on 

### EMRAS_EVT_RECONNECT

0x98110195: RAS: obsolete 

### EMRAS_EVT_SOCKCHANGE

0x98110196: RAS: Socket exchanged after reconnect (obsolete) 

### EMRAS_EVT_CLNTDISC

0x98110197: RAS: Client disconnect 

### EMRAS_E_ACCESS_NOT_FOUND

0x98110198: RAS: Access not configured for this call (e.g. SPoC access configuration missing) 

### EMRAS_E_TOKEN_MISSING

0x98110199: RAS: Token missing 

### EMRAS_E_TOKEN_INVALID

0x9811019A: RAS: Token invalid 

### EMRAS_E_TOKEN_DENIED

0x9811019B: RAS: Token denied 

### EMRAS_E_TLS_CERTIFICATE_ERROR

0x9811019C: RAS: TLS certificate error 

### EMRAS_E_TLS_PRIVATEKEY_ERROR

0x9811019D: RAS: TLS private key error 

### EMRAS_E_TLS_HANDSHAKE_FAILED

0x9811019E: RAS: TLS handshake failed 

\\newpage


# error-codes_soe.html.md

# Servo Drive Profil over EtherCAT® (SoE) Error Codes

<!-- -*- mode: rst -*- -->

<a id="d2-d9d-group-e-c-e-r-r-o-r-c-o-d-e-s-s-o-e"></a>

### EC_E_SOE_ERRORCODE_INVALID_ACCESS

0x98110078: ERROR SoE: Invalid access to element 0 

### EC_E_SOE_ERRORCODE_NOT_EXIST

0x98110079: ERROR SoE: Does not exist 

### EC_E_SOE_ERRORCODE_INVL_ACC_ELEM1

0x9811007A: ERROR SoE: Invalid access to element 1 

### EC_E_SOE_ERRORCODE_NAME_NOT_EXIST

0x9811007B: ERROR SoE: Name does not exist 

### EC_E_SOE_ERRORCODE_NAME_UNDERSIZE

0x9811007C: ERROR SoE: Name undersize in transmission 

### EC_E_SOE_ERRORCODE_NAME_OVERSIZE

0x9811007D: ERROR SoE: Name oversize in transmission 

### EC_E_SOE_ERRORCODE_NAME_UNCHANGE

0x9811007E: ERROR SoE: Name unchangeable 

### EC_E_SOE_ERRORCODE_NAME_WR_PROT

0x9811007F: ERROR SoE: Name currently write-protected 

### EC_E_SOE_ERRORCODE_UNDERS_TRANS

0x98110080: ERROR SoE: Attribute undersize in transmission 

### EC_E_SOE_ERRORCODE_OVERS_TRANS

0x98110081: ERROR SoE: Attribute oversize in transmission 

### EC_E_SOE_ERRORCODE_ATTR_UNCHANGE

0x98110082: ERROR SoE: Attribute unchangeable 

### EC_E_SOE_ERRORCODE_ATTR_WR_PROT

0x98110083: ERROR SoE: Attribute currently write-protected 

### EC_E_SOE_ERRORCODE_UNIT_NOT_EXIST

0x98110084: ERROR SoE: Unit does not exist 

### EC_E_SOE_ERRORCODE_UNIT_UNDERSIZE

0x98110085: ERROR SoE: Unit undersize in transmission 

### EC_E_SOE_ERRORCODE_UNIT_OVERSIZE

0x98110086: ERROR SoE: Unit oversize in transmission 

### EC_E_SOE_ERRORCODE_UNIT_UNCHANGE

0x98110087: ERROR SoE: Unit unchangeable 

### EC_E_SOE_ERRORCODE_UNIT_WR_PROT

0x98110088: ERROR SoE: Unit currently write-protected 

### EC_E_SOE_ERRORCODE_MIN_NOT_EXIST

0x98110089: ERROR SoE: Minimum input value does not exist 

### EC_E_SOE_ERRORCODE_MIN_UNDERSIZE

0x9811008A: ERROR SoE: Minimum input value undersize in transmission 

### EC_E_SOE_ERRORCODE_MIN_OVERSIZE

0x9811008B: ERROR SoE: Minimum input value oversize in transmission 

### EC_E_SOE_ERRORCODE_MIN_UNCHANGE

0x9811008C: ERROR SoE: Minimum input value unchangeable 

### EC_E_SOE_ERRORCODE_MIN_WR_PROT

0x9811008D: ERROR SoE: Minimum input value currently write-protected 

### EC_E_SOE_ERRORCODE_MAX_NOT_EXIST

0x9811008E: ERROR SoE: Maximum input value does not exist 

### EC_E_SOE_ERRORCODE_MAX_UNDERSIZE

0x9811008F: ERROR SoE: Maximum input value undersize in transmission 

### EC_E_SOE_ERRORCODE_MAX_OVERSIZE

0x98110090: ERROR SoE: Maximum input value oversize in transmission 

### EC_E_SOE_ERRORCODE_MAX_UNCHANGE

0x98110091: ERROR SoE: Maximum input value unchangeable 

### EC_E_SOE_ERRORCODE_MAX_WR_PROT

0x98110092: ERROR SoE: Maximum input value currently write-protected 

### EC_E_SOE_ERRORCODE_DATA_NOT_EXIST

0x98110093: ERROR SoE: Data item does not exist 

### EC_E_SOE_ERRORCODE_DATA_UNDERSIZE

0x98110094: ERROR SoE: Data item undersize in transmission 

### EC_E_SOE_ERRORCODE_DATA_OVERSIZE

0x98110095: ERROR SoE: Data item oversize in transmission 

### EC_E_SOE_ERRORCODE_DATA_UNCHANGE

0x98110096: ERROR SoE: Data item unchangeable 

### EC_E_SOE_ERRORCODE_DATA_WR_PROT

0x98110097: ERROR SoE: Data item currently write-protected 

### EC_E_SOE_ERRORCODE_DATA_MIN_LIMIT

0x98110098: ERROR SoE: Data item less than minimum input value limit 

### EC_E_SOE_ERRORCODE_DATA_MAX_LIMIT

0x98110099: ERROR SoE: Data item exceeds maximum input value limit 

### EC_E_SOE_ERRORCODE_DATA_INCOR

0x9811009A: ERROR SoE: Data item incorrect 

### EC_E_SOE_ERRORCODE_PASWD_PROT

0x9811009B: ERROR SoE: Data item protected by password 

### EC_E_SOE_ERRORCODE_TEMP_UNCHANGE

0x9811009C: ERROR SoE: Data item temporary unchangeable (in AT or MDT) 

### EC_E_SOE_ERRORCODE_INVL_INDIRECT

0x9811009D: ERROR SoE: Invalid indirect 

### EC_E_SOE_ERRORCODE_TEMP_UNCHANGE1

0x9811009E: ERROR SoE: Data item temporary unchangeable (parameter or opmode) 

### EC_E_SOE_ERRORCODE_ALREADY_ACTIVE

0x9811009F: ERROR SoE: Command already active 

### EC_E_SOE_ERRORCODE_NOT_INTERRUPT

0x98110100: ERROR SoE: Command not interruptible 

### EC_E_SOE_ERRORCODE_CMD_NOT_AVAIL

0x98110101: ERROR SoE: Command not available (in this phase) 

### EC_E_SOE_ERRORCODE_CMD_NOT_AVAIL1

0x98110102: ERROR SoE: Command not available (invalid parameter) 

### EC_E_SOE_ERRORCODE_DRIVE_NO

0x98110103: ERROR SoE: Response drive number not identical with requested drive number 

### EC_E_SOE_ERRORCODE_IDN

0x98110104: ERROR SoE: Response IDN not identical with requested IDN 

### EC_E_SOE_ERRORCODE_FRAGMENT_LOST

0x98110105: ERROR SoE: At least one fragment lost 

### EC_E_SOE_ERRORCODE_BUFFER_FULL

0x98110106: ERROR SoE: RX buffer full (EtherCAT call with to small data-buffer) 

### EC_E_SOE_ERRORCODE_NO_DATA

0x98110107: ERROR SoE: No data state 

### EC_E_SOE_ERRORCODE_NO_DEFAULT_VALUE

0x98110108: ERROR SoE: No default value 

### EC_E_SOE_ERRORCODE_DEFAULT_LONG

0x98110109: ERROR SoE: Default value transmission too long 

### EC_E_SOE_ERRORCODE_DEFAULT_WP

0x9811010A: ERROR SoE: Default value cannot be changed, read only 

### EC_E_SOE_ERRORCODE_INVL_DRIVE_NO

0x9811010B: ERROR SoE: Invalid drive number 

### EC_E_SOE_ERRORCODE_GENERAL_ERROR

0x9811010C: ERROR SoE: General error 

### EC_E_SOE_ERRCODE_NO_ELEM_ADR

0x9811010D: ERROR SoE: No element addressed 

\\newpage


# ethercat-masters.html.md

# EtherCAT® MainDevices

In principle, all EtherCAT® MainDevices with ENI are supported. EtherCAT® MainDevices without ENI are currently not supported.

All tested EtherCAT® MainDevices are listed below, as well as special EC-Monitor parameters that are necessary for operation.

## Acontis EC-Master

Fully supported without any special parameter settings.

## Beckhoff TwinCAT®

Fully supported without any special parameter settings.

## CODESYS®

Supported starting from version V3.5 SP17 and above, with the CODESYS EtherCAT® Module requiring version 4.2.0.0 or later.
In some topologies, the actual number of cyclical commands on the bus differs from the configuration in the ENI. To fix this discrepancy, the EC-Monitor parameter [`EC_T_MONITOR_INIT_PARMS::bProcessRestructuredCyclicCmds`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS30bProcessRestructuredCyclicCmdsE) must be set to [`EC_TRUE`](api.html.md#c.EC_TRUE).

## KPA EtherCAT® MainDevice

Supported.


# ethernet-tap.html.md

# Ethernet TAP

To capture the EtherCAT® traffic, EC-Monitor supports a variety of different Ethernet Test Access Points (TAP). These can be special real-time optimized TAPs with minimal propagation delay and extended diagnostic options, or simple 100MBit/s Ethernet switches. The only requirement is that the input (RX) and output (TX) traffic is forwarded to the EC-Monitor via a common up-link port.

The various Ethernet TAP devices can be automatically detected by the EC-Monitor via [`EC_T_MONITOR_INIT_PARMS::eEthTapType`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS11eEthTapTypeE) set to [`EC_T_ETHERNET_TAP_TYPE::eEthTap_AutoDetect`](api_general.html.md#_CPPv4N22EC_T_ETHERNET_TAP_TYPE18eEthTap_AutoDetectE).

## TAP positioning

The Ethernet TAP device should be inserted in the network between the EtherCAT® MainDevice and SubDevices or, if this is not possible, between two SubDevices. The position of the Ethernet TAP is detected automatically and the EtherCAT® traffic is processed accordingly.

![Diagram showing the recommended TAP placement between the EtherCAT MainDevice and SubDevices for traffic monitoring](../Media/EC-Monitor_Master-Tap-Slaves.png)

For configurations where the EtherCAT® MainDevice has a direct interface to the SubDevices without an RJ45 cable, e.g. Beckhoff IPCs it is possible to connect the input port of the Ethernet TAP device to the RJ45 port of the topologically last SubDevice. The output port of the Ethernet TAP device must be bridged using an RJ45 loopback plug so that the EtherCAT® frames are forwarded back to the MainDevice.

![Diagram showing an alternative TAP placement with the TAP connected to the last SubDevice RJ45 port and a loopback plug on the output to return frames to the MainDevice](../Media/EC-Monitor_Master-Slaves-Tap.png)

In configurations where the TAP can only be inserted at an EtherCAT® Junction SubDevice, the port closest to the end of the topology should be used. Any SubDevices connected to the subsequent port will no longer be detected.

![Diagram showing a TAP inserted at an EtherCAT Junction SubDevice using the port closest to the end of the topology, with a warning that SubDevices on subsequent ports will not be detected](../Media/EC-Monitor_Master-Slaves-Junction-Tap.png)

#### WARNING
Positioning the TAP within the topology can lead to inconsistencies in the process data image. This affects the outputs of the SubDevices preceding the TAP and that are read by a `Logical Read-Write` (`LRW`) command. The affected outputs are set to 0 by the EC-Monitor.

## Generic 100MBit/s Ethernet Switch

A generic 100MBit/s Ethernet switch with at least 3 ports can be used with EC-Monitor. The propagation delay can be up to several hundred μs per port and should therefore only be used for slower cycle times.

To manually select this device set [`EC_T_MONITOR_INIT_PARMS::eEthTapType`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS11eEthTapTypeE) to  [`EC_T_ETHERNET_TAP_TYPE::eEthTap_Generic`](api_general.html.md#_CPPv4N22EC_T_ETHERNET_TAP_TYPE15eEthTap_GenericE).

## Beckhoff ET2000

The Beckhoff ET2000 comes with propagation delay below 1 μs, a high-precision timestamp and extended frame error detection capabilities.
The TAP offers the possibility to determine on which port the frame was received. The EC-Monitor uses this to evaluate whether it is a TX or RX frame. Therefore, the outgoing connection from the EtherCAT® MainDevice should be connected to either port `X1.0`, `X2.0`, `X3.0` or `X4.0`.

To manually select this device set [`EC_T_MONITOR_INIT_PARMS::eEthTapType`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS11eEthTapTypeE) to  [`EC_T_ETHERNET_TAP_TYPE::eEthTap_Beckhoff_ET2000`](api_general.html.md#_CPPv4N22EC_T_ETHERNET_TAP_TYPE23eEthTap_Beckhoff_ET2000E).

To filter frames by line, set [`EC_T_MONITOR_INIT_PARMS::wMainTapPortIn`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS14wMainTapPortInE) and [`EC_T_MONITOR_INIT_PARMS::wMainTapPortOut`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS15wMainTapPortOutE) accordingly.

## Dualcomm ETAP-1000

The Dualcomm ETAP-1000 has a propagation delay below 1 μs. Since it has no other extended capabilities it can be used as generic Ethernet TAP [`EC_T_ETHERNET_TAP_TYPE::eEthTap_Generic`](api_general.html.md#_CPPv4N22EC_T_ETHERNET_TAP_TYPE15eEthTap_GenericE).

## Kunbus TAP Curious

The Kunbus TAP Curious comes with propagation delay below 1 μs, a high-precision timestamp and extended frame error detection capabilities.
The TAP offers the possibility to determine on which port the frame was received. The EC-Monitor uses this to evaluate whether it is a TX or RX frame. Therefore, the outgoing connection from the EtherCAT® MainDevice should be connected to either port `A` or `C`.

To manually select this device set [`EC_T_MONITOR_INIT_PARMS::eEthTapType`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS11eEthTapTypeE) to  [`EC_T_ETHERNET_TAP_TYPE::eEthTap_Kunbus_TapCurious`](api_general.html.md#_CPPv4N22EC_T_ETHERNET_TAP_TYPE25eEthTap_Kunbus_TapCuriousE).

To filter frames by line, set [`EC_T_MONITOR_INIT_PARMS::wMainTapPortIn`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS14wMainTapPortInE) and [`EC_T_MONITOR_INIT_PARMS::wMainTapPortOut`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS15wMainTapPortOutE) accordingly.

## ProfiTap ProfiShark

The ProfiTap ProfiShark devices are USB3.0 based Ethernet TAPs with a propagation delay below 1 μs. To use it with EC-Monitor, the Hardware Timestamping feature must be disabled in the Featues Tab of ProfiShark Manager.

As the device appear as a virtual Ethernet interface in the operating system, it can be used as a generic Ethernet TAP [`EC_T_ETHERNET_TAP_TYPE::eEthTap_Generic`](api_general.html.md#_CPPv4N22EC_T_ETHERNET_TAP_TYPE15eEthTap_GenericE).

## Port Mirror

A TAP or switch with port mirroring functionality can also be used with EC-Monitor. Typically, a port mirroring device has four Ethernet ports, two input ports for the network and two mirroring output ports. Incoming traffic on the respective network port is mirrored to the corresponding mirror port.

In the EtherCAT® use case, this means that the Ethernet frames outgoing from the EtherCAT® MainDevice are mirrored on one port and the Ethernet frames returning from the EtherCAT® SubDevices are output on another port.
Since EC-Monitor currently only supports one port for connecting to the TAP, the mirror port with the returning Ethernet frames must be connected.

![Diagram of a port mirror TAP configuration where the mirror port receiving returning EtherCAT frames is connected to the EC-Monitor uplink](../Media/EC-Monitor_Master-PortMirror-Slaves.png)

This network adapter must be selected manually by setting [`EC_T_MONITOR_INIT_PARMS::eEthTapType`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS11eEthTapTypeE) to [`EC_T_ETHERNET_TAP_TYPE::eEthTap_PortMirror`](api_general.html.md#_CPPv4N22EC_T_ETHERNET_TAP_TYPE18eEthTap_PortMirrorE).

#### WARNING
Since only the returning frames are processed, inconsistencies occur in the process data image of the outputs for EtherCAT® frames with `LRW` commands.


# gettingstarted.html.md

# 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

#### SEE ALSO
[Example application](integration_example.html.md#example-application) for detailed explanation


# gettingstarted_compiling.html.md

<a id="compile-ecdemo"></a>

# 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.

## 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

## Include search path

The header files are located in the following directories:

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

## 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
: ```default
  <InstallPath>/SDK/LIB/<OS>/<ARCH>
  ```
  <br/>
  EC-Monitor core
  : ```default
    libEcMonitor.a
    ```
  <br/>
  EC-Monitor RAS server (optional)
  : ```default
    libEcMonitorRasServer.a
    ```

Dynamic libraries
: ```default
  <InstallPath>/Bin/<OS>/<ARCH>
  ```
  <br/>
  EC-Monitor core
  : ```default
    libEcMonitor.so
    ```
  <br/>
  EC-Monitor RAS server (optional)
  : ```default
    libEcMonitorRasServer.so
    ```

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

## Preprocessor definitions

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

```default
EC_MONITOR
```

Exclude the EC-Daq support in the demo:

```default
EXCLUDE_DAQ_SUPPORT
```


# gettingstarted_running-demo-mqtt.html.md

# Running EcMonitorDemoMqtt

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

```doscon
> 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](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](gettingstarted_running-demo.html.md#command-line-parameters). Each SubDevice variable is assigned a separate MQTT topic:

```default
/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.

## 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 |


# gettingstarted_running-demo.html.md

<a id="running-ecdemo"></a>

# Running EcMonitorDemo

To capture the EtherCAT® traffic insert a TAP device between the EtherCAT® adapter of the MainDevice and the first SubDevice.

![Diagram of an EtherCAT network with a TAP device inserted between the MainDevice and the first SubDevice for traffic capture](../Media/EC-Monitor_Masters-Tap-Slaves.png)

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.

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

#### SEE ALSO
[Platform and Operating Systems (OS)](os.html.md#platform-and-operating-systems-os) for OS specific additional instructions to run the demo application

## 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 [ms]. When the time expires the demo application exits completely.

* **<time>:**
  Time [ms], 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.

### -fingerprint <method>

Read license fingerprint

* **<method>:**
  Fingerprint method

### -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

### 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`](_downloads/bf62c71a4a7e317930818b9da4a9815c/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](https://developer.acontis.com/).

### -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:**
    Enable Real-time Ethernet Driver Time Triggered Send (TTS)
  * **<SendOffset>:**
    TTS cyclic frame send offset from cycle start (usec)
  * **or:**
  * **--tmr:**
    Enable 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:**
    Disable force broadcast

### -remote <instance> <mode> <src ip> <src port> <dst ip> <dst port> [--mac <address>] [--rxbuffercnt <count>]

Hardware:   Hardware independent. Tunnels EtherCAT frames through a TCP socket

> * **<Instance>:**
>   Device instance 1 = first, 2 = second, …
> * **<Mode>:**
>   1 = Polling mode
> * **<Src ip>:**
>   Source adapter IP address (listen)
> * **<Src port>:**
>   Source port number (listen)
> * **<Dst ip>:**
>   Destination adapter IP address (connect)
> * **<Dst port>:**
>   Destination port number (connect)

Optional:
: * **--mac:**
    MAC Address
  * **<Address>:**
    formatted as xx:xx:xx:xx:xx:xx or xx-xx-xx-xx-xx-xx

Optional:
: * **--rxbuffercnt:**
    Frame buffer count for interrupt service thread (IST)
  * **<Count>:**
    Buffer count

### -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 adapter, e.g. eth1

Optional:
: * **<Mode>:**
    0 = Interrupt mode | 1 = Polling mode

Optional:
: * **--nommaprx:**
    Disable PACKET_MMAP for receive

Optional:
: * **--promiscuousmode:**
    Enable promiscuous mode

### -tap <instance> <mode> <adaptername>

OpenVPN’s Windows TAP
: * **<Instance>:**
    Device instance 1 = first, 2 = second, …
  * **<Mode>:**
    0 = Interrupt mode | 1 = Polling mode
  * **<AdapterName>:**
    Adapter name


# integration.html.md

# Software Integration

For the integration of the EC-Monitor, the EcMonitorDemo can be seen as an application framework, serve as a template and be expanded accordingly.

* [Example application](integration_example.html.md)
  * [File reference](integration_example.html.md#file-reference)
  * [EC-Monitor life cycle](integration_example.html.md#product-life-cycle)
* [Event notification](integration_notification.html.md)
  * [Direct event notification handling](integration_notification.html.md#direct-event-notification-handling)
  * [Postponed notification handling](integration_notification.html.md#postponed-notification-handling)
* [Logging](integration_logging.html.md)
* [EtherCAT® Network Configuration ENI](integration_eni.html.md)
  * [Single cyclic entry configuration](integration_eni.html.md#single-cyclic-entry-configuration)
  * [Multiple cyclic entries configuration](integration_eni.html.md#multiple-cyclic-entries-configuration)
* [Process Data Access](integration_processdata.html.md)
  * [Process Data Access Functions](integration_processdata.html.md#process-data-access-functions)
  * [Process variables’ offset and size](integration_processdata.html.md#process-variables-offset-and-size)
  * [Process variable access via hard coded offsets](integration_processdata.html.md#process-variable-access-via-hard-coded-offsets)
  * [Process variable access via generated PD Layout](integration_processdata.html.md#process-variable-access-via-generated-pd-layout)
  * [Process variable access dynamically from ENI](integration_processdata.html.md#process-variable-access-dynamically-from-eni)
* [Diagnosis](integration_diag.html.md)
  * [Working Counter](integration_diag.html.md#working-counter)
  * [MainDevice Sync Units](integration_diag.html.md#maindevice-sync-units)
* [MainDevice Variables](integration_mastervariables.html.md)
* [Operation without ENI](integration_genebi.html.md)
* [EC-Monitor Source Code](integration_src.html.md)
  * [Real-time Ethernet Driver Binaries](integration_src.html.md#real-time-ethernet-driver-binaries)
  * [EC-Monitor Binaries](integration_src.html.md#product-binaries)
  * [Remote API Server Binaries:](integration_src.html.md#remote-api-server-binaries)


# integration_diag.html.md

# Diagnosis

EtherCAT® offers comprehensive diagnostic capabilities at both hardware and software levels. Errors that can impact a network can be classified into two main categories:

Hardware errors
: 1. Interruptions in the physical medium or unexpected changes in network topology, resulting in frames not reaching all network SubDevices or failing to return to the MainDevice. Examples include damaged cables, loose contacts, or SubDevice resets during operation.
  2. All SubDevices are reached by frames, but the correct bit sequence is corrupted. Caused by factors such as electromagnetic disturbances or faulty devices.

Software errors
: 1. Incorrect or mismatched parameters sent by the MainDevice during the start-up phase, failing to meet SubDevice expectations. This may include errors in process data size/configuration or unsupported cycle times.
  2. Previously error-free SubDevices detecting issues during operation, such as synchronization loss or watchdog expiration.

These errors can be diagnosed cyclically or acyclically.

## Working Counter

Every datagram within an EtherCAT® frame ends with a 16-bit Working Counter (WKC), which increments for each SubDevice that the datagram addresses.

![EtherCAT frame diagram illustrating a datagram with a 16-bit Working Counter that increments for each SubDevice the datagram addresses](../Media/Diag_EcDatagramWkc.png)

The Working Counter is always received by the EC-Monitor together with the corresponding datagram, and enables therefore an immediate reaction in case of invalid or inconsistent data.
The information regarding the Working Counter is essentially digital (*WKC correct* vs. *WKC invalid*), and does not differentiate between various error causes. An invalid WKC can result from several situations:

- One or more SubDevices are not physically connected to the network, or they are not reached by the frames.
- One or more SubDevices have been reset.
- One or more SubDevices are not in the Operational state.

If a datagram returns to the EC-Monitor with an unexpected WKC, the EC-Monitor discards the input data carried by that datagram. The application will be informed by an [emonNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](notification_error.html.md#emonnotify-ec-notify-cyccmd-wkc-error) notification.

In addition to notification, it is also possible to evaluate the WKC states of the individual SubDevices and their process data sections. The following example demonstrates how to evaluate the WKC state of the SubDevice inputs:

```cpp
EC_T_BYTE* pbyDiagnosisImage = emonGetDiagnosisImagePtr(dwInstanceId);
EC_T_CFG_SLAVE_INFO CfgSlaveInfo;

dwRes = emonGetCfgSlaveInfo(dwInstanceId, EC_TRUE, 1002, &CfgSlaveInfo);

for (EC_T_DWORD i = 0; i < EC_CFG_SLAVE_PD_SECTIONS; i++)
{
    if (0xFFFF == CfgSlaveInfo.wWkcStateDiagOffsIn[i])
    {
        /* offset not available */
        break;
    }

    if (EC_TESTBIT(pbyDiagnosisImage, CfgSlaveInfo.wWkcStateDiagOffsIn[i]))
    {
        /* ... error ... */
    }
}
```

#### SEE ALSO
[`emonGetDiagnosisImagePtr()`](api_diag.html.md#_CPPv424emonGetDiagnosisImagePtr10EC_T_DWORD), [`emonGetCfgSlaveInfo()`](api_slave.html.md#_CPPv419emonGetCfgSlaveInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORDP19EC_T_CFG_SLAVE_INFO)

## MainDevice Sync Units

EtherCAT® configurators can optionally group network SubDevices into disjoint subsets called MainDevice Sync Units. SubDevices in different MainDevice Sync Units are served by separate datagrams and are thus independent from each other in terms of Working Counter diagnostics.

The following example demonstrates how to evaluate the WKC state of the MainDevice Sync Unit 0:

```cpp
EC_T_BYTE* pbyDiagnosisImage = emonGetDiagnosisImagePtr(dwInstanceId);
EC_T_MSU_INFO MsuInfo;

dwRes = emonGetMasterSyncUnitInfo(dwInstanceId, 0, &MsuInfo);

if (EC_TESTBIT(pbyDiagnosisImage, MsuInfo.wWkcStateDiagOffsIn))
{
    /* ... error ... */
}
```

#### SEE ALSO
[`emonGetDiagnosisImagePtr()`](api_diag.html.md#_CPPv424emonGetDiagnosisImagePtr10EC_T_DWORD), [`emonGetMasterSyncUnitInfo()`](api_diag.html.md#_CPPv425emonGetMasterSyncUnitInfo10EC_T_DWORD9EC_T_WORDP13EC_T_MSU_INFO)

<!-- Hardware diagnosis
******************

    Software diagnosis
    ****************** -->


# integration_eni.html.md

# EtherCAT® Network Configuration ENI

The EtherCAT® configuration file ENI contains one or more Cyclic entries for reading new input data values and output data values (process data update).
These entries contain one or more frames, so-called cyclic frames, which are to be sent cyclically by the EtherCAT® MainDevice.
Within the cyclic frames are one or more EtherCAT® datagrams that contain logical read/write commands for accessing the process data values.

## Single cyclic entry configuration

In the simplest case, there is only a single cyclic entry with one or more cyclic frames.

![Diagram of a single cyclic entry ENI configuration with one or more cyclic frames containing EtherCAT datagrams for process data updates](../Media/Eni_SingleCycEntry.png)

## Multiple cyclic entries configuration

For more complex scenarios it is possible to configure the system using multiple cyclic entries with one or more cyclic frames for each cyclic entry.

![Diagram of a multiple cyclic entries ENI configuration with separate sets of cyclic frames for each cyclic entry](../Media/Eni_MultipleCycEntry.png)
<!-- Copy Information for SubDevice-to-SubDevice communication
=========================================================

It is possible to configure the system to copy input variables to output variables within EC-Master.
The copy info declarations of the corresponding received cyclic frame are processed in :cpp:expr:`emonExecJob(eUsrJob_ProcessAllRxFrames)`.

The exchange of process data takes two communication cycles. The duration is necessary if cable redundancy is used or if the WKC of INPUT needs to be checked before changing OUTPUT.

The copy info declarations are located at ``/EtherCATConfig/Config/Cyclic/Frame/Cmd/CopyInfos`` in the ENI file.

.. seealso::
    - :ref:`software-integration:Cyclic cmd WKC validation`
    - CopyInfosType in ETG.2100

**Configuration with EC-Engineer**

#. In the "SubDevice to SubDevice" tab of the MainDevice select Input and Output Variable and connect them:
    .. figure:: ../Media/configengineer.png
        :alt:

**Configuration with ET9000**

#. Select "Linked to..." from the Output Variable:
    .. figure:: ../Media/configet9000.png
        :alt:

#. Select Input Variable to be attached to the Output Variable:
    .. figure:: ../Media/outputvariable.png
        :alt:

.. hint:: Copy info declaration processing is independent of WKC values, but updating the INPUT source depends on successful Cyclic cmd WKC validation.

Swap variables' bytes according to ENI
======================================

The following screenshot (ET9000) shows how to configure variables to be swapped by the EC-Master:

.. figure:: ../Media/swapENI.png
    :alt:

.. hint:: The EC-Master does not distinguish between WORD or BYTE swapping. Setting any PDO swap flag instructs the EC-Master to swap the PDO variable.

The swap declarations are located at DataType's attribute SwapData of RxPdo or TxPdo, e.g. ``/EtherCATConfig/Config/Slave/ProcessData/RxPdo/Entry/DataType`` in the ENI file. -->


# integration_example.html.md

# Example application

The example application will handle the following tasks:

- EC-Monitor initialization
- Process Data acquisition with EC-Daq
- Periodic Job Task in polling or interrupt mode
- Thread with periodic tasks and application thread already implemented
- Record and replay wireshark traces
- Logging. The output messages of the demo application will be printed on the console as well as in some files
- “Out of the box” solution for different operating systems: Windows, Linux …

## File reference

The EcMonitorDemo application consists of the following files:

![File reference diagram showing the source files of the EcMonitorDemo application including EcDemoMain, EcDemoApp, EcNotification, and supporting modules](../Media/EcMonitorDemoFileOverview.png)

| Filename                                                                                     | Description                                                                                       |
|----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
| [`EcDemoMain.cpp`](_downloads/fc875d17cbef52a4c4879f7ba411fe69/EcDemoMain.cpp)               | Entry point for the different operating systems                                                   |
| [`EcDemoPlatform.h`](_downloads/8a98bd88751f8738d3ec7f509d67f6e7/EcDemoPlatform.h)           | Operating system specific settings (task priorities, timer settings)                              |
| [`EcDemoApp.cpp`](_downloads/c5da2e59739a538a68c8ce1dcf916229/EcDemoApp.cpp)                 | Initialize, start and terminate EC-Monitor                                                        |
| [`EcDemoApp.h`](_downloads/f8fa0ce85acb39a07c40e9a021d3815d/EcDemoApp.h)                     | Application specific settings for EcDemoApp                                                       |
| [`EcDemoParms.cpp`](_downloads/cc5a320ac29f8e16f99cb4d2be8320fa/EcDemoParms.cpp)             | Parsing of command line parameters                                                                |
| [`EcDemoParms.h`](_downloads/7da4d0b851574416d0292c150711af29/EcDemoParms.h)                 | Basic configuration parameters                                                                    |
| [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) | Common Functions which abstract the command line parsing into Real-time Ethernet Driver parameter |
| [`EcNotification.cpp`](_downloads/a8230e7ca1c52aaedb62898da301f674/EcNotification.cpp)       | SubDevice monitoring and error detection (function `ecatNotify()` )                               |
| [`EcSlaveInfo.cpp`](_downloads/1717ceec03b28a568975a261bbaff164/EcSlaveInfo.cpp)             | SubDevice information services                                                                    |
| [`EcLogging.cpp`](_downloads/688adc0df0fa9d756770fefe6720978f/EcLogging.cpp)                 | Message logging functions                                                                         |
| [`EcTimer.cpp`](_downloads/f9c3bd98e3ff32524fc04ff3bde41b53/EcTimer.cpp)                     | Start and monitor timeouts                                                                        |

## EC-Monitor life cycle

Basically the operation of the EC-Monitor is wrapped between the functions

- [`emonInitMonitor()`](api_general.html.md#_CPPv415emonInitMonitor10EC_T_DWORDPK23EC_T_MONITOR_INIT_PARMS)
- [`emonConfigureNetwork()`](api_general.html.md#_CPPv420emonConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD)

and

- [`emonDeinitMonitor()`](api_general.html.md#_CPPv417emonDeinitMonitor10EC_T_DWORD)

The EC-Monitor is made ready for operation and started with the first two functions mentioned. During this preparation, a thread is set up and started that handles all the cyclic tasks of the EC-Monitor.
The last function stops the EC-Monitor and clears the memory.

An overview of the complete life cycle as a sequence diagram:

A more detailed description of the functions:

EcDemoMain()
: A wrapper to start the demo from the respective operating system.
  In addition to initializing the operating system, parsing command line parameters and initializing logging it also starts the timing task.

EcDemoApp()
: Demo application. The function takes care of starting and stopping the EC-Monitor and all related tasks. In between, the function runs idle, while all relevant work is done by the EcMonitorJobTask().

EcMonitorJobTask()
: Thread that does the necessary periodic work. Very important here is myAppWorkPd() between [`eUsrJob_ProcessAllRxFrames`](api_general.html.md#_CPPv4N13EC_T_USER_JOB26eUsrJob_ProcessAllRxFramesE) and [`eUsrJob_MonitorTimer`](api_general.html.md#_CPPv4N13EC_T_USER_JOB20eUsrJob_MonitorTimerE).
  Application-specific access to the process data image can be made here, which is synchronous with the bus cycle.

EcTimingTask()
: Timing Thread. This thread sets the timing event that triggers the EcMonitorJobTask for the next cycle.

[`emonInitMonitor()`](api_general.html.md#_CPPv415emonInitMonitor10EC_T_DWORDPK23EC_T_MONITOR_INIT_PARMS)
: Prepare the EC-Monitor for operation and set operational parameters, e.g. used Real-time Ethernet Driver, buffer sizes, maximum number of SubDevices, … .

[`emonConfigureNetwork()`](api_general.html.md#_CPPv420emonConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD)
: Loads the configuration from the ENI (XML file).

[`emonRegisterClient()`](api_general.html.md#_CPPv418emonRegisterClient10EC_T_DWORD12EC_PF_NOTIFYP9EC_T_VOIDP20EC_T_REGISTERRESULTS)
: Register the application as a client at the EC-Monitor to receive event notifications.

[`emonDeinitMonitor()`](api_general.html.md#_CPPv417emonDeinitMonitor10EC_T_DWORD)
: Clean up.


# integration_genebi.html.md

# Operation without ENI

The EC-Monitor can operate on a reduced feature set without an ENI file. This is particularly useful in cases where an ENI file is unavailable or inaccessible. To operate the EC-Monitor in this mode, configure the network using the **eCnfType_GenEBI** configuration type.

In this mode, the EC-Monitor is able to observe basic information on the bus such as the network topology, SubDevice descriptions and registers. The application can retrieve this information using [emonGetBusSlaveInfo](api_slave.html.md#emongetbusslaveinfo) and [emonReadSlaveRegister](api_slave.html.md#emonreadslaveregister) respectively. Because the EC-Monitor does not store or access EtherCAT® SubDevice Information (ESI) files, it does not have a process data image, and APIs which depend on configuration data will be limited or non-functional.

The EC-Monitor supports exporting an ENI Builder (\*.ebi) configuration file. This file contains the observed network topology and SubDevice descriptions and can be imported in the acontis EC-Engineer, which can export an ENI file in turn. This ENI file can then be used to operate the EC-Monitor on its full feature set.

#### SEE ALSO
- [emonConfigureNetwork](api_general.html.md#emonconfigurenetwork)
- [emonExportEniBuilderConfig](api_general.html.md#emonexportenibuilderconfig)


# integration_logging.html.md

# Logging

The EC-Monitor offers a logging interface for a more detailed analysis of application errors, problems in the EtherCAT® network and for diagnosing internal processes.
The log messages are passed from the EC-Monitor to the application via the callback [`EC_T_LOG_PARMS::pfLogMsg`](api_general.html.md#_CPPv4N14EC_T_LOG_PARMS8pfLogMsgE) given at [`EC_T_MONITOR_INIT_PARMS::LogParms`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS8LogParmsE).

### typedef [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) (\*[EC_PF_LOGMSGHK](api_general.html.md#_CPPv414EC_PF_LOGMSGHK))(EC_T_LOG_CONTEXT \*pContext, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwLogMsgSeverity, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szFormat, ...)

The level of detail of the logging output can be set via [`EC_T_LOG_PARMS::dwLogLevel`](api_general.html.md#_CPPv4N14EC_T_LOG_PARMS10dwLogLevelE). The log levels are firmly defined:

<!-- -*- mode: rst -*- -->

EC_LOG_LEVELS

For performance reasons, the log messages are automatically filtered based on the log level and then passed to the callback.

**Example**

The `EcMonitorDemo` examples demonstrate how log messages can be processed by the application, see `Examples/Common/EcLogging.cpp`.
The messages processed by `EcLogging.cpp` are of different types, e.g. EC-Monitor log messages and application messages are logged to the console and/or files.
Identical messages are skipped automatically by default.

#### NOTE
With some operating systems, logging in files is deactivated, e.g. because a file system is not available.

The verbosity of the `EcMonitorDemo` is specified as a `-v` command line parameter. It is used to determine the log level of the application, see `EcDemoMain.cpp`.
`EcLogging.cpp` has various parameters beside the log level, like Roll Over setting, log task priority, CPU affinity, log buffer size and etc.


# integration_mastervariables.html.md

# MainDevice Variables

MainDevice variables are an EC-Master extension that allows applications to trace data in real time on the network. To ensure real-time transmission, it is implemented as part of the cyclic process data. They are placed behind the SubDevice output data in the output area of the process data image of the EtherCAT® application. The MainDevice variables can be configured via the ENI with the help of the EC-Engineer.

MainDevice variables can be captured with a network monitoring tool like Wireshark.

![Architecture diagram showing MainDevice Variables appended as NOP commands in EtherCAT cyclic frames for real-time network monitoring and tracing](../../EcMaster/Media/TraceData_Architecture.png)

To transfer the data, an additional NOP command is appended to the end of the cyclic EtherCAT® frame. The NOP command has ADP 0 and ADO 0x4154. The EC-Master automatically fills the data area of the NOP command with the current MainDevice variables when sending cyclic frames. Since the MainDevice variables are transferred to the network as NOP command, they are not evaluated by any ESC. Therefore, the WKC of the MainDevice variables remains 0 and the application cannot validate the data.

The easiest and most comfortable way to create MainDevice variables is with the help of the EC-Engineer.
The necessary NOP command and the process data variables are automatically created and exported to the ENI. The process variables can be accessed as usual using the [`emonFindOutpVarByNameEx()`](api_processdata.html.md#_CPPv423emonFindOutpVarByNameEx10EC_T_DWORDPK9EC_T_CHARP24EC_T_PROCESS_VAR_INFO_EX) function.


# integration_notification.html.md

# Event notification

The EC-Monitor provides event notification for a great number of events. These events are for example:

- Bus state change
- Link state change
- Working counter errors
- …

Any thread can register for these events to be notified. This is achieved by calling the API function

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [emonRegisterClient](api_general.html.md#_CPPv418emonRegisterClient10EC_T_DWORD12EC_PF_NOTIFYP9EC_T_VOIDP20EC_T_REGISTERRESULTS)([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_PF_NOTIFY](api_general.html.md#_CPPv412EC_PF_NOTIFY) pfnNotify, EC_T_VOID \*pCallerData, [EC_T_REGISTERRESULTS](api_general.html.md#_CPPv420EC_T_REGISTERRESULTS) \*pRegResults)

An example implementation for processing notifications is contained in the class `CEmNotification` of the EcMonitorDemo example, see `Examples/Common/EcNotification.cpp`. It implements the full framework to catch and process the EC-Monitor notifications.
The class is instantiated once and registered at the EC-Monitor with the call [`emonRegisterClient()`](api_general.html.md#_CPPv418emonRegisterClient10EC_T_DWORD12EC_PF_NOTIFYP9EC_T_VOIDP20EC_T_REGISTERRESULTS). It contains the method `ecatNotify()` as major entry point (or callback function) for every event notification.

There are two different ways events can be handled. The method of handling an event is primarily determined by the time required to handle the event and the processing context in which the event is to be handled.

## Direct event notification handling

Minor events that take a very short time to process can be handled directly in the context in which they are recognized. A possible example of such an event is the detection of a false working counter (WKC).

The event handling is reduced to simply issuing a log message, which is not time critical. The event is handled directly within the context of the [`emonExecJob()`](api_general.html.md#_CPPv411emonExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) function.

## Postponed notification handling

Events that require more time-consuming processing cannot be handled directly in the context in which they are detected. The handling or processing of the event must be postponed. This is accomplished through a queue, which is also readily implemented using the `CEmNotification` class.

By calling periodically `CEmNotification::ProcessNotificationJobs()`, the application checks and handles all queued notifications.

#### IMPORTANT
The call of `CEmNotification::ProcessNotificationJobs()` shall NOT be executed in the context of `EcMonitorJobTask()`. As the CPU time consumption may be high, this would have a high impact to the real-time behavior of the cyclic operation.


# integration_processdata.html.md

# Process Data Access

The process data that is exchanged between an EtherCAT® MainDevice and the SubDevices in each cycle is stored in the process data image. There are two separate memory areas, one for the input data and one for the output data.
The base addresses of these areas are provided by calling the functions [`emonGetProcessImageInputPtr()`](api_processdata.html.md#_CPPv427emonGetProcessImageInputPtr10EC_T_DWORD) and [`emonGetProcessImageOutputPtr()`](api_processdata.html.md#_CPPv428emonGetProcessImageOutputPtr10EC_T_DWORD).
The size of the process data input image is defined in the ENI file under `EtherCATConfig/Config/ProcessImage/Inputs/ByteSize` and `EtherCATConfig/Config/ProcessImage/Outputs/ByteSize` and is returned by [`emonRegisterClient()`](api_general.html.md#_CPPv418emonRegisterClient10EC_T_DWORD12EC_PF_NOTIFYP9EC_T_VOIDP20EC_T_REGISTERRESULTS) at [`EC_T_REGISTERRESULTS::dwPDOutSize`](api_general.html.md#_CPPv4N20EC_T_REGISTERRESULTS11dwPDOutSizeE) and [`EC_T_REGISTERRESULTS::dwPDInSize`](api_general.html.md#_CPPv4N20EC_T_REGISTERRESULTS10dwPDInSizeE).

## Process Data Access Functions

Process data variables that are packed as array of bits are bit aligned and not byte aligned in process data. Accessing bits that are bit aligned and not byte aligned should be done using [`EC_GETBITS`](api_processdata.html.md#c.EC_GETBITS). See [`EC_COPYBITS`](api_processdata.html.md#c.EC_COPYBITS) for how to copy data areas with bit offsets that are not byte aligned.
Corresponding aligned variables, e.g. of the types [`EC_T_BYTE`](api.html.md#_CPPv49EC_T_BYTE), [`EC_T_WORD`](api.html.md#_CPPv49EC_T_WORD), [`EC_T_DWORD`](api.html.md#_CPPv410EC_T_DWORD), [`EC_T_UINT64`](api.html.md#_CPPv411EC_T_UINT64), can be accessed more efficiently using the appropriate macros according to the following table.

#### NOTE
Process data is typically transmitted as little endian and must therefore be swapped on big endian systems in order to be correctly interpreted.

| Variable type                                                                    |   Bit size | Macro                                                                                | Hint                                                      |
|----------------------------------------------------------------------------------|------------|--------------------------------------------------------------------------------------|-----------------------------------------------------------|
| Bit                                                                              |          1 | [`EC_GETBITS`](api_processdata.html.md#c.EC_GETBITS)             | Contains swap for big endian systems                      |
| [`EC_T_BYTE`](api.html.md#_CPPv49EC_T_BYTE)      |          8 | N/A                                                                                  | Bytes can be directly addressed at pbyBuffer[BitOffset/8] |
| [`EC_T_WORD`](api.html.md#_CPPv49EC_T_WORD)      |         16 | [`EC_GET_FRM_WORD`](api_processdata.html.md#c.EC_GET_FRM_WORD)   | Contains swap for big endian systems                      |
| [`EC_T_DWORD`](api.html.md#_CPPv410EC_T_DWORD)   |         32 | [`EC_GET_FRM_DWORD`](api_processdata.html.md#c.EC_GET_FRM_DWORD) | Contains swap for big endian systems                      |
| [`EC_T_UINT64`](api.html.md#_CPPv411EC_T_UINT64) |         64 | [`EC_GET_FRM_QWORD`](api_processdata.html.md#c.EC_GET_FRM_QWORD) | Contains swap for big endian systems                      |

## Process variables’ offset and size

The following screenshot shows variables’ offset and size within the Process Data Image:

![EC-Engineer screenshot showing SubDevice process variables with their bit offset and size values in the Process Data Image](../Media/PdAccess_PdVariablesList.png)

Accessing the process data of a specific SubDevice always works by adding an offset to the base address. All offsets are given as bit offsets!

There are different ways possible to get this offset. The offset values will not change until a new configuration is provided, therefore it is sufficient to load them once right after [`emonConfigureNetwork()`](api_general.html.md#_CPPv420emonConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD), it is not needed every cycle.

## Process variable access via hard coded offsets

The offset value can be determined from an EtherCAT® configuration tool. It is not recommended to use fixed values as the offsets will change as SubDevices are added/removed from the configuration.

As shown in the screenshot above, SubDevice_1004 [EL2004].Channel 3.Output is at offset 1.2 with size 0.1 in the example.

The numbering is Byte.Bit so the offset in the example is Byte 1, Bit 2, Bit offset:
: $8*1+2 = 10$

Bit size
: $0*8+1 = 1$

```cpp
EC_T_BYTE* pbyPdOut = emonGetProcessImageInputPtr(dwInstanceId);
EC_T_BYTE  byValue = 0x00;
EC_T_DWORD dwBitOffset = 10;
EC_T_DWORD dwBitSize = 1;

/* get variable in process data */
EC_GETBITS(pbyPdOut, &byValue, dwBitOffset, dwBitSize);
```

## Process variable access via generated PD Layout

The EC-Engineer / EC-Inspector can export the process variables to a PD-Layout C-Header via the menu item Network ‣ Export Process Variables as shown in the following screenshots:

![EC-Engineer Network menu showing the Export Process Variables option for generating a PD Layout C header file](../Media/PdAccess_ExportProcVar1.png)![EC-Engineer showing the Export Process Data Image dialog](../Media/PdAccess_ExportProcVar2.png)

This will generate a header file containing the SubDevices’ variables as follows:

```cpp
#include EC_PACKED_INCLUDESTART(1)
#define PDLAYOUT_OUT_OFFSET_SLAVE_2002 22
    typedef struct _T_PDLAYOUT_OUT_SLAVE_2002
    {
        EC_T_SWORD  swChannel_1_Output; // Slave_2002 [EL4132].Channel 1.Output ...
        EC_T_SWORD  swChannel_2_Output; // Slave_2002 [EL4132].Channel 2.Output ...
    } EC_PACKED(1) T_PDLAYOUT_OUT_SLAVE_2002;
#include EC_PACKED_INCLUDESTOP
```

Example how a value can be accessed:

```cpp
EC_T_BYTE* pbyPdOut = emonGetProcessImageOutputPtr(dwInstanceId);
T_PDLAYOUT_OUT_SLAVE_2002* pPdOutSlave2002 = (T_PDLAYOUT_OUT_SLAVE_2002*)(pbyPdOut + PDLAYOUT_OUT_OFFSET_SLAVE_2002);

EC_T_WORD wChannel1Out = EC_GET_FRM_WORD(&pPdOutSlave2002->swChannel_1_Output);
```

## Process variable access dynamically from ENI

### emonGetCfgSlaveInfo

The SubDevice offsets can be determined dynamically with the function [`emonGetCfgSlaveInfo()`](api_slave.html.md#_CPPv419emonGetCfgSlaveInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORDP19EC_T_CFG_SLAVE_INFO).
The offsets are stored in [`EC_T_CFG_SLAVE_INFO::dwPdOffsIn`](api_slave.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO10dwPdOffsInE) and [`EC_T_CFG_SLAVE_INFO::dwPdOffsOut`](api_slave.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO11dwPdOffsOutE).

Example of how SubDevice_1004 [EL2004].Channel 3.Output can be accessed:

```cpp
EC_T_CFG_SLAVE_INFO SlaveInfo;
dwRes = emonGetCfgSlaveInfo(dwInstanceId, EC_TRUE, 1004, &SlaveInfo);

EC_T_BYTE* pbyPdOut = emonGetProcessImageOutputPtr(dwInstanceId);
EC_T_BYTE  byValue = 0x00;
EC_T_DWORD dwBitOffset = SlaveInfo.dwPdOffsOut + 2;
EC_T_DWORD dwBitSize = 1;

/* get variable in process data */
EC_GETBITS(pbyPdOut, &byValue, dwBitOffset, dwBitSize);
```

### emonGetSlaveOutpVarInfo

All variables of a specific SubDevice can be determined dynamically with the functions [`emonGetSlaveInpVarInfoEx()`](api_slave.html.md#_CPPv424emonGetSlaveInpVarInfoEx10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORDP24EC_T_PROCESS_VAR_INFO_EXP9EC_T_WORD) or [`emonGetSlaveOutpVarInfoEx()`](api_slave.html.md#_CPPv425emonGetSlaveOutpVarInfoEx10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORDP24EC_T_PROCESS_VAR_INFO_EXP9EC_T_WORD).
The offset is stored in [`EC_T_PROCESS_VAR_INFO_EX::nBitOffs`](api_slave.html.md#_CPPv4N24EC_T_PROCESS_VAR_INFO_EX8nBitOffsE).

Example of how SubDevice_1004 [EL2004].Channel 3.Output can be accessed:

```cpp
EC_T_WORD wNumSlaveVars = 0;
EC_T_WORD wNumVarsRead = 0;
EC_T_PROCESS_VAR_INFO_EX* aProcVarInfo = EC_NULL;

/* get number of output variables */
dwRes = emonGetSlaveOutpVarInfoNumOf(dwInstanceId, EC_TRUE, 1004, &wNumSlaveVars);

/* allocate buffer for the variable info structs */
aProcVarInfo = (EC_T_PROCESS_VAR_INFO_EX*)OsMalloc(sizeof(EC_T_PROCESS_VAR_INFO_EX) * wNumSlaveVars);
OsMemset(aProcVarInfo, 0, sizeof(EC_T_PROCESS_VAR_INFO_EX) * wNumSlaveVars);

/* read all variables of the slave at once */
dwRes = emonGetSlaveOutpVarInfoEx(dwInstanceId, EC_TRUE, 1004, wNumSlaveVars, aProcVarInfo, &wNumVarsRead);

EC_T_BYTE* pbyPdOut = emonGetProcessImageOutputPtr(dwInstanceId);
EC_T_BYTE  byValue = 0x00;

/* get variable in process data */
EC_GETBITS(pbyPdOut, &byValue, aProcVarInfo[0].nBitOffs, aProcVarInfo[0].nBitSize);
```

### emonFindOutpVarByName

The variable offsets can be determined dynamically using the names with the functions [`emonFindInpVarByNameEx()`](api_processdata.html.md#_CPPv422emonFindInpVarByNameEx10EC_T_DWORDPK9EC_T_CHARP24EC_T_PROCESS_VAR_INFO_EX) or [`emonFindOutpVarByNameEx()`](api_processdata.html.md#_CPPv423emonFindOutpVarByNameEx10EC_T_DWORDPK9EC_T_CHARP24EC_T_PROCESS_VAR_INFO_EX).
Each input or output has a unique variable name, all variable names are stored in the ENI file under `EtherCATConfig/Config/ProcessImage/[Inputs|Outputs]/Variable`.
The offset is stored in [`EC_T_PROCESS_VAR_INFO_EX::nBitOffs`](api_slave.html.md#_CPPv4N24EC_T_PROCESS_VAR_INFO_EX8nBitOffsE).

Example of how SubDevice_1004 [EL2004].Channel 3.Output can be accessed:

```cpp
EC_T_PROCESS_VAR_INFO_EX ProcVarInfo;
dwRes = emonFindOutpVarByNameEx(dwInstanceId, "Slave_1004 [EL2004].Channel 3.Output", &ProcVarInfo);

EC_T_BYTE* pbyPdOut = emonGetProcessImageOutputPtr(dwInstanceId);
EC_T_BYTE  byValue = 0x00;

/* get variable in process data */
EC_GETBITS(pbyPdOut, &byValue, ProcVarInfo.nBitOffs, ProcVarInfo.nBitSize);
```

### emonGetSlaveOutpVarByObjectEx

The variable offsets can be determined dynamically using the object index and subindex with the functions [`emonGetSlaveInpVarByObjectEx()`](api_slave.html.md#_CPPv428emonGetSlaveInpVarByObjectEx10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORD9EC_T_WORDP24EC_T_PROCESS_VAR_INFO_EX) or [`emonGetSlaveOutpVarByObjectEx()`](api_slave.html.md#_CPPv429emonGetSlaveOutpVarByObjectEx10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORD9EC_T_WORDP24EC_T_PROCESS_VAR_INFO_EX).

The object index and subindex can be got with EC-Engineer:

![EC-Engineer showing SubDevice object index and subindex values for dynamic process variable access via emonGetSlaveOutpVarByObjectEx](../Media/PdAccess_ObjIdx.png)

Example of how SubDevice_1004 [EL2004].Channel 3.Output can be accessed:

```cpp
EC_T_PROCESS_VAR_INFO_EX ProcVarInfo;
dwRes = emonGetSlaveOutpVarByObjectEx(dwInstanceId, EC_TRUE, 1004, 0x7010, 0x01, &ProcVarInfo);

EC_T_BYTE* pbyPdOut = emonGetProcessImageOutputPtr(dwInstanceId);
EC_T_BYTE  byValue = 0x00;

/* get variable in process data */
EC_GETBITS(pbyPdOut, &byValue, ProcVarInfo.nBitOffs, ProcVarInfo.nBitSize);
```


# integration_src.html.md

# EC-Monitor Source Code

In a source code delivery the EC-Monitor sources are divided into 4 parts:

- SDK Header files
- Real-time Ethernet Driver files (multiple Real-time Ethernet Drivers may be shipped)
- Link OS layer files (only valid for the Real-time Ethernet Drivers)
- EC-Monitor files (configuration, core and interface layer)
- OS layer files

The EC-Monitor can be ported to several different operating systems and CPU architectures with different compilers and development environments. Typically no supported build environment files like IDE projects are shipped with the source code.

To build the EC-Monitor the appropriate build environment for the target operating system has to be used. If an integrated development environment (IDE) exists (Visual Studio, Eclipse, etc.) several projects containing all necessary files are needed to build the artefacts. If no integrated development environment is available makefiles and dependency rules may have to be created which contain the necessary EC-Monitor source and header files.

For most platforms three separate independent binaries will have to be generated:

1. Real-time Ethernet Driver Binary. The Real-time Ethernet Driver binary will be dynamically bound to the application at runtime.
2. EC-Monitor Library
3. Remote API Server Library

## Real-time Ethernet Driver Binaries

The following files have to be included into an IDE project or makefile:

- Real-time Ethernet Driver files. Only one single Real-time Ethernet Driver must be selected even if multiple Real-time Ethernet Driver are shipped. For each Real-time Ethernet Driver a separate binary has to be created.
- Link OS layer files
- Windows: a dynamic link library (.dll) has to be created. The name of the DLL has to be emllXxxx.dll where Xxxx shall be replaced by the Link Layer type (e.g. emllI8255x.dll for the I8255x Link Layer).

## EC-Monitor Binaries

The following files have to be included into an IDE project or makefile:

- EC-Monitor files
- OS layer files
- For all platforms a static library has to be created. This library will have to be linked together with the application.

## Remote API Server Binaries:

The following files have to be included into an IDE project or makefile:

- Remote API server files.
- For all platforms a static library has to be created. This library will have to be linked together with the application.

#### SEE ALSO
[Platform and Operating Systems (OS)](os.html.md#platform-and-operating-systems-os) for required tool chain settings


# intro.html.md

# Introduction

## What is EtherCAT®?

EtherCAT® (Ethernet for Control Automation Technology) is a high-performance Ethernet Fieldbus technology that provides a reliable, efficient, and cost-effective communication solution for a wide variety of industrial automation applications. Originally developed as an open technology by Beckhoff Automation in 2003, and subsequently turned over to an independent organization known as the EtherCAT® Technology Group, EtherCAT® has since become one of the most widely used industrial Ethernet protocols in the world.

#### SEE ALSO
A comprehensive introduction to EtherCAT® technology can be found at [https://www.acontis.com/en/what-is-EtherCAT-communication-protocol.html](https://www.acontis.com/en/what-is-EtherCAT-communication-protocol.html).

## The EC-Monitor - Features

## Protected version

The EC-Monitor software is available in different protected versions:

Protected
: Binary with MAC protection

Unrestricted
: Binary without MAC protection

Source
: Source code

The protected version will automatically stop after about 30 minutes of continuous operation. In order to remove this restriction a valid runtime license key is required. The runtime license protection is based on the MAC address of the Ethernet controller used for the EtherCAT® protocol. With a valid License Key the protected version will automatically become an unrestricted version.

### Licensing procedure for Development Licenses

1. Installation of EC-Monitor protected version
2. Determine the MAC Address by calling [`emonGetSrcMacAddress()`](api_general.html.md#_CPPv420emonGetSrcMacAddress10EC_T_DWORDP16ETHERNET_ADDRESS) or from a sticker applied on the hardware near the Ethernet controller
3. Send an Email with the subject “**Development License Key Request, Commission** *your commission number*” with the MAC address to [sales@acontis.com](mailto:sales@acontis.com)
4. Acontis will create the license keys and return them in a **License Key Text File (CSV format)**.
   ```none
   Number;MAC Address;License Key
   1;00-00-5A-11-77-FE;DA1099F2-15C249E9-54327FBC
   2;64-31-50-80-20-4E;1B7C1F86-D08E40A8-4F96F2BA
   ```
5. Activate the License Key by calling [`emonSetLicenseKey()`](api_general.html.md#_CPPv417emonSetLicenseKey10EC_T_DWORDPK9EC_T_CHAR) with the license key that corresponds to the MAC address on the hardware and check the return code. The license key is 26 characters long.
   ```cpp
   dwRes = emonSetLicenseKey(0, "DA1099F2-15C249E9-54327FBC");
   ```

### Licensing procedure for Runtime Licenses

1. Installation of EC-Monitor protected version
2. Determine the MAC Address by calling [`emonGetSrcMacAddress()`](api_general.html.md#_CPPv420emonGetSrcMacAddress10EC_T_DWORDP16ETHERNET_ADDRESS) or from a sticker applied on the hardware near the Ethernet controller
3. Provide the MAC Addresses and numbers from **previously ordered and unused runtime license stickers** in a text file to acontis as described in the example below. Please use a separate line for each runtime license sticker number and MAC Address.
   ```none
   S/N; MAC Address
   100-105-1-1/1603310001;00-00-5A-11-77-FE
   100-105-1-1/1603310002;64-31-50-80-20-4E
   ```
4. Send an Email with the subject “**Runtime License Key Request, Commission** *your commission number*” with the MAC address to [sales@acontis.com](mailto:sales@acontis.com)
5. Acontis will create the license keys and return them in a **License Key Text File (CSV format)**.
   ```none
   Number;MAC Address;License Key
   1;00-00-5A-11-77-FE;DA1099F2-15C249E9-54327FBC
   2;64-31-50-80-20-4E;1B7C1F86-D08E40A8-4F96F2BA
   ```
6. Activate the License Key by calling [`emonSetLicenseKey()`](api_general.html.md#_CPPv417emonSetLicenseKey10EC_T_DWORDPK9EC_T_CHAR) with the license key that corresponds to the MAC address on the hardware and check the return code.
   ```cpp
   dwRes = emonSetLicenseKey(0, "DA1099F2-15C249E9-54327FBC");
   ```

## License

### EC-Monitor license

According to EC-Monitor Software License Agreement (SLA).

### Free Open Source Software contained in EC-Monitor

#### Expat XML parser license V2.6.0

```none
Copyright (c) 1997-2000 Thai Open Source Software Center Ltd
Copyright (c) 2000      Clark Cooper <coopercc@users.sourceforge.net>
Copyright (c) 2000-2005 Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
Copyright (c) 2001-2002 Greg Stein <gstein@users.sourceforge.net>
Copyright (c) 2002-2016 Karl Waclawek <karl@waclawek.net>
Copyright (c) 2016-2024 Sebastian Pipping <sebastian@pipping.org>
Copyright (c) 2016      Cristian Rodríguez <crrodriguez@opensuse.org>
Copyright (c) 2016      Thomas Beutlich <tc@tbeu.de>
Copyright (c) 2017      Rhodri James <rhodri@wildebeest.org.uk>
Copyright (c) 2022      Thijs Schreijer <thijs@thijsschreijer.nl>
Copyright (c) 2023      Hanno Böck <hanno@gentoo.org>
Copyright (c) 2023      Sony Corporation / Snild Dolkow <snild@sony.com>
Licensed under the MIT license:

Permission is  hereby granted,  free of charge,  to any  person obtaining
a  copy  of  this  software   and  associated  documentation  files  (the
"Software"),  to  deal in  the  Software  without restriction,  including
without  limitation the  rights  to use,  copy,  modify, merge,  publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons  to whom  the Software  is  furnished to  do so,  subject to  the
following conditions:

The above copyright  notice and this permission notice  shall be included
in all copies or substantial portions of the Software.

THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.
```

### Free Open Source Software supported by EC-Monitor

The following components are not part of EC-Monitor, but relate to it:

#### acontis atemsys Linux kernel module

The acontis atemsys is licensed under the GPL:

```none
Copyright (c) 2009 - 2020 acontis technologies GmbH, Ravensburg, Germany
All rights reserved.

This program is free software; you can redistribute  it and/or modify it
under  the terms of  the GNU General  Public License as published by the
Free Software Foundation;  either version 2 of the  License, or (at your
option) any later version.
```

## Versioning

EC-Monitor follows the following versioning scheme: **V***MAJOR***.** *MINOR***.** *SERVICEPACK***.** *BUILD* (e.g. V3.2.1.04).

The libraries are binary compatible by unchanged *MAJOR* and *MINOR* digits. If *SERVICEPACK* increments, *BUILD* restarts with 01.
*BUILD* 99 is reserved for test builds that have not been officially released for productive usage.


# notification.html.md

# Generic notification interface

One of the parameters the client has to set when registering with the EC-Monitor is a generic notification callback function ( `emonNotify()`). This function is called every time an event occurs about which the client needs to be informed.

Within this callback function the client must not call any active EtherCAT® functions which finally would lead to send EtherCAT® commands (e.g. initiation of mailbox transfers, starting/stopping the MainDevice, sending raw commands). In such cases the behavior is undefined. Only EtherCAT® functions which are explicitly marked to be callable within `emonNotify()` may be called.

This callback function is usually called in the context of the EC-Monitor timer thread or the EtherCAT® Real-time Ethernet Driver receiver thread. To avoid dead-lock situations the notification callback handler may not use mutex semaphores.

As the whole EtherCAT® operation is blocked while calling this function the error handling must not use much CPU time or even call operating system functions that may block. Usually the error handling will be done in a separate application thread.


# notification_callback.html.md

# Notification callback

### typedef [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) (\*[EC_PF_NOTIFY](api_general.html.md#_CPPv412EC_PF_NOTIFY))([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCode, [EC_T_NOTIFYPARMS](notification_callback.html.md#_CPPv416EC_T_NOTIFYPARMS) \*pParms)

### struct EC_T_NOTIFYPARMS

Data structure filled with detailed information about the according notification. 

### Public Members

### EC_T_VOID \*pCallerData

[in] Client depending caller data parameter. This pointer is one of the parameters when the client registers. 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyInBuf

[in] Notification input parameters 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInBufSize

[in] Size of notification input parameters in bytes 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyOutBuf

[out] Buffer for notification output (result) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwOutBufSize

[in] Size of buffer at pbyOutBuf in bytes 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOutData

[out] Amount of bytes written to pbyOutBuf by notification. EC_NULL: amount not set by notification.


# notification_emonnotifyapp.html.md

# emonNotifyApp

By calling this function the generic notification callback function setup by [`emonRegisterClient()`](api_general.html.md#_CPPv418emonRegisterClient10EC_T_DWORD12EC_PF_NOTIFYP9EC_T_VOIDP20EC_T_REGISTERRESULTS) is called.

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonNotifyApp([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCode, [EC_T_NOTIFYPARMS](notification_callback.html.md#_CPPv416EC_T_NOTIFYPARMS) \*pParms)

Calls the notification callback functions of all registered clients. 

#### NOTE
EC_E_ERROR and EC_E_INVALIDPARM from registered clients’ callback functions are ignored.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwCode** – [in] Application specific notification code. dwCode must be <= EC_NOTIFY_APP_MAX_CODE. The callback functions get “EC_NOTIFY_APP | dwCode” as parameter. 
  * **pParms** – [in] Parameter to all callback functions. Note: Output parameters are not transferred from RAS client to RAS server. 
* **Returns:**
  [EC_E_ERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gae45dc6c94a43aa671697ecc700555c22) or first error code different from [EC_E_ERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gae45dc6c94a43aa671697ecc700555c22) and [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) of registered clients’ callback functions 

The maximum value for dwCode is defined by `EC_NOTIFY_APP_MAX_CODE`


# notification_enable-disable.html.md

# Enable/Disable notifications

All notifications can be enabled or disabled. By default, all notifications are enabled except for:

<!-- -*- mode: rst -*- -->
- EC_NOTIFY_SLAVE_STATECHANGED
- EC_NOTIFY_SLAVES_STATECHANGED
- EC_NOTIFY_SLAVES_PRESENCE
- EC_NOTIFY_REFCLOCK_PRESENCE
- EC_NOTIFY_SLAVES_UNEXPECTED_STATE
- EC_NOTIFY_SLAVES_ERROR_STATUS
- EC_NOTIFY_COE_INIT_CMD
- EC_NOTIFY_SLAVE_REGISTER_TRANSFER

## emonIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED

### EC_IOCTL_SET_NOTIFICATION_ENABLED

Set notification enabled state. With [EC_T_SET_NOTIFICATION_ENABLED_PARMS::dwCode](notification_enable-disable.html.md#d6/ddc/struct_e_c___t___s_e_t___n_o_t_i_f_i_c_a_t_i_o_n___e_n_a_b_l_e_d___p_a_r_m_s_1ae1b2f429de202edb4e017449955a8800) set to [EC_ALL_NOTIFICATIONS](notification_enable-disable.html.md#de/dee/group___e_c___s_e_t___n_o_t_i_f_i_c_a_t_i_o_n___e_n_a_b_l_e_d_1ga5c0e488c77506c184264fac70db448ee), all notifications can be changed at once. [EC_T_SET_NOTIFICATION_ENABLED_PARMS::dwEnabled](notification_enable-disable.html.md#d6/ddc/struct_e_c___t___s_e_t___n_o_t_i_f_i_c_a_t_i_o_n___e_n_a_b_l_e_d___p_a_r_m_s_1a322df8c32453561c2be96821b3d3e1db) set to [EC_NOTIFICATION_DEFAULT](notification_enable-disable.html.md#de/dee/group___e_c___s_e_t___n_o_t_i_f_i_c_a_t_i_o_n___e_n_a_b_l_e_d_1gafc3e9d34942a7587b73530566e3edd06), resets to default. 

* **Parameters:**
  * **pbyInBuf** – [in] Pointer to [EC_T_SET_NOTIFICATION_ENABLED_PARMS](notification_enable-disable.html.md#d6/ddc/struct_e_c___t___s_e_t___n_o_t_i_f_i_c_a_t_i_o_n___e_n_a_b_l_e_d___p_a_r_m_s). 
  * **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes 
  * **pbyOutBuf** – [out] Should be set to EC_NULL 
  * **dwOutBufSize** – [in] Should be set to 0 
  * **pdwNumOutData** – [out] Should be set to EC_NULL 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_SET_NOTIFICATION_ENABLED_PARMS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClientId

[in] Client ID, 0: Master 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCode

[in] Notification code or [EC_ALL_NOTIFICATIONS](notification_enable-disable.html.md#de/dee/group___e_c___s_e_t___n_o_t_i_f_i_c_a_t_i_o_n___e_n_a_b_l_e_d_1ga5c0e488c77506c184264fac70db448ee)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwEnabled

[in] Enable, disable or reset to default notification. See [EC_NOTIFICATION_](notification_enable-disable.html.md#de-dee-group-e-c-s-e-t-n-o-t-i-f-i-c-a-t-i-o-n-e-n-a-b-l-e-d) flags. 

<!-- -*- mode: rst -*- -->

<a id="de-dee-group-e-c-s-e-t-n-o-t-i-f-i-c-a-t-i-o-n-e-n-a-b-l-e-d"></a>

### EC_NOTIFICATION_DISABLED

Disable notification 

### EC_NOTIFICATION_ENABLED

Enable notification 

### EC_NOTIFICATION_DEFAULT

Reset notification to default 

### EC_ALL_NOTIFICATIONS

Notification code to change all notifications 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonIoCtl - EC_IOCTL_GET_NOTIFICATION_ENABLED

### EC_IOCTL_GET_NOTIFICATION_ENABLED

The enabled state of notifications can be retrieved using [EC_IOCTL_GET_NOTIFICATION_ENABLED](notification_enable-disable.html.md#d0/d35/_ec_io_ctl_8h_1a925565a04161b26d801353adb08054dd). 

* **Parameters:**
  * **pbyInBuf** – [in] Pointer to [EC_T_GET_NOTIFICATION_ENABLED_PARMS](notification_enable-disable.html.md#dc/d03/struct_e_c___t___g_e_t___n_o_t_i_f_i_c_a_t_i_o_n___e_n_a_b_l_e_d___p_a_r_m_s)
  * **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes 
  * **pbyOutBuf** – [out] Pointer to EC_T_BOOL to carry out current enable set 
  * **dwOutBufSize** – [in] Size of the output buffer provided at pbyOutBuf in bytes 
  * **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_GET_NOTIFICATION_ENABLED_PARMS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClientId

[in] Client ID, 0: Master 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCode

[in] Notification code 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)


# notification_error.html.md

# Error notifications

For each error an error ID (error code) will be defined. This error ID will be used as the notification code when `emonNotify()` is called. In addition to this notification code the second parameter given to `emonNotify()` contains a pointer to an error notification descriptor of type [`EC_T_ERROR_NOTIFICATION_DESC`](notification_error.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC). This error notification descriptor contains detailed information about the error.

### struct EC_T_ERROR_NOTIFICATION_DESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwNotifyErrorCode

Error ID (same value as the notification code) 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) achErrorInfo[MAX_ERRINFO_STRLEN]

Additional error string (may be empty) 

### union \_EC_T_ERROR_NOTIFICATION_PARM

### Public Members

### [EC_T_WKCERR_DESC](notification_error.html.md#_CPPv416EC_T_WKCERR_DESC) WkcErrDesc

WKC error descriptor 

### [EC_T_FRAME_RSPERR_DESC](notification_error.html.md#_CPPv422EC_T_FRAME_RSPERR_DESC) FrameRspErrDesc

Frame response error descriptor 

### EC_T_INITCMD_ERR_DESC InitCmdErrDesc

Master/Slave init command error descriptor 

### [EC_T_SLAVE_ERROR_INFO_DESC](notification_error.html.md#_CPPv426EC_T_SLAVE_ERROR_INFO_DESC) SlaveErrInfoDesc

Slave Error Info Descriptor 

### EC_T_SLAVES_ERROR_DESC SlavesErrDesc

Slaves Error Descriptor 

### EC_T_MBOX_SDO_ABORT_DESC SdoAbortDesc

SDO Abort 

### EC_T_RED_CHANGE_DESC RedChangeDesc

Redundancy Descriptor 

### [EC_T_MBOX_FOE_ABORT_DESC](api_mbx_foe.html.md#_CPPv424EC_T_MBOX_FOE_ABORT_DESC) FoeErrorDesc

FoE error code and string 

### EC_T_MBXRCV_INVALID_DATA_DESC MbxRcvInvalidDataDesc

Invalid mailbox data received descriptor 

### [EC_T_PDIWATCHDOG_DESC](notification_error.html.md#_CPPv421EC_T_PDIWATCHDOG_DESC) PdiWatchdogDesc

PDI watchdog expired 

### EC_T_SLAVE_NOTSUPPORTED_DESC SlaveNotSupportedDesc

Slave not supported 

### EC_T_SLAVE_UNEXPECTED_STATE_DESC SlaveUnexpectedStateDesc

Slave in unexpected state 

### EC_T_SLAVES_UNEXPECTED_STATE_DESC SlavesUnexpectedStateDesc

Slaves in unexpected state 

### EC_T_EEPROM_CHECKSUM_ERROR_DESC EEPROMChecksumErrorDesc

EEPROM checksum error 

### EC_T_JUNCTION_RED_CHANGE_DESC JunctionRedChangeDesc

Junction redundancy change descriptor 

### EC_T_FRAMELOSS_AFTER_SLAVE_NTFY_DESC FramelossAfterSlaveDesc

Frameloss after Slave descriptor 

### EC_T_S2SMBX_ERROR_DESC S2SMbxErrorDesc

S2S Mailbox Error descriptor 

### EC_T_BAD_CONNECTION_NTFY_DESC BadConnectionDesc

Bad connection descriptor 

### [EC_T_COMMUNICATION_TIMEOUT_NTFY_DESC](notification_error.html.md#_CPPv436EC_T_COMMUNICATION_TIMEOUT_NTFY_DESC) CommunicationTimeoutDesc

Communication timeout descriptor 

### [EC_T_TAP_LINK_STATUS_NTFY_DESC](notification_error.html.md#_CPPv430EC_T_TAP_LINK_STATUS_NTFY_DESC) TapLinkStatusDesc

Tap link status 

If the pointer to this descriptor exists the detailed error information (e.g. information about the SubDevice) is stored in the appropriate structure of a union. These error information structures are described in the following sections.

<!-- The |Product| will call :cpp:func:`emonNotify` every time an error is detected. In some cases this will lead to calling this function in every |ETHERCAT_R| cycle (e.g. if there is no physical connection to the SubDevices). Using the control interface :ref:`api:emonIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED` it is possible to determine which errors shall be signaled and which not. -->

## emonNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL

When processing cyclic frames the EtherCAT® MainDevice checks whether all SubDevices are still in OPERATIONAL state. If at least one SubDevice is not OPERATIONAL this error will be indicated.

## emonNotify - EC_NOTIFY_ALL_DEVICES_OPERATIONAL

When processing cyclic frames the EtherCAT® MainDevice checks whether all SubDevices are still in OPERATIONAL state. This will be notified after [emonNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL](notification_error.html.md#emonnotify-ec-notify-not-all-devices-operational) and all the SubDevices are back in OPERATIONAL state.

## emonNotify - EC_NOTIFY_CLIENTREGISTRATION_DROPPED

This notification will be indicated if the client registration was dropped because [`emonConfigureNetwork()`](api_general.html.md#_CPPv420emonConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD) was called by another thread.

```cpp
EC_T_DWORD dwDeinitForConfiguration; /* 0 = terminating MainDevice, 1 = restarting MainDevice */
```

## emonNotify - EC_NOTIFY_CYCCMD_WKC_ERROR

To update the process data some EtherCAT® commands will be sent cyclically by the external MainDevice. These commands will address one or multiple SubDevices. These EtherCAT® commands contain a working counter which has to be incremented by each SubDevice that is addressed. The working counter will be checked after the EtherCAT® command is received by the monitor.
If the expected working counter will not match the working counter of the received command the error EC_NOTIFY_CYCCMD_WKC_ERROR will be indicated. The working counter value expected by the monitor is determined by the EtherCAT® configuration (XML) file for each cyclic EtherCAT® command (section Config/Cyclic/Frame/Cmd/Cnt).
Detailed error information are stored in structure [`EC_T_WKCERR_DESC`](notification_error.html.md#_CPPv416EC_T_WKCERR_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](notification_error.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).

### struct EC_T_WKCERR_DESC

### Public Members

### [EC_T_SLAVE_PROP](api_slave.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp

Slave properties, content is undefined in case of cyclic WKC_ERROR 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byCmd

EtherCAT command type 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwAddr

Logical address or physical address (ADP/ADO) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wWkcSet

Working counter set value 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wWkcAct

Working counter actual value 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTaskId

Cyclic Task ID (ENI: Cyclic/TaskId) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wMsuId

Master Sync Unit ID (ENI: Slave/ProcessData/RxPdo[1..4]@Su, Slave/ProcessData/TxPdo[1..4]@Su, comment at Cyclic/Frame/Cmd) 

### struct [EC_T_SLAVE_PROP](api_slave.html.md#_CPPv415EC_T_SLAVE_PROP)

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) [wStationAddress](api_slave.html.md#_CPPv4N15EC_T_SLAVE_PROP15wStationAddressE)

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) [wAutoIncAddr](api_slave.html.md#_CPPv4N15EC_T_SLAVE_PROP12wAutoIncAddrE)

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) [achName](api_slave.html.md#_CPPv4N15EC_T_SLAVE_PROP7achNameE)[MAX_STD_STRLEN]

<!-- .. seealso::
    - :ref:`software-integration:Cyclic cmd WKC validation`
    - :ref:`software-integration:Working Counter (WKC) State in Diagnosis Image` -->

## emonNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR

This notification will be indicated if the actually received Ethernet frame does not match the expected frame or if an expected frame was not received.

### struct EC_T_FRAME_RSPERR_DESC

### Public Members

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bIsCyclicFrame

Indicates whether the lost frame was a cyclic frame 

### [EC_T_FRAME_RSPERR_TYPE](notification_error.html.md#_CPPv422EC_T_FRAME_RSPERR_TYPE) EErrorType

Frame response error type 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byEcCmdHeaderIdxSet

Expected IDX value, this value is valid only for acyclic frames in case EErrorType is not equal to eRspErr_UNEXPECTED 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byEcCmdHeaderIdxAct

Actually received IDX value, this value is only valid for acyclic frames in case of EErrorType is equal to: eRspErr_WRONG_IDX and eRspErr_UNEXPECTED 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wCycFrameNum

Number of the lost cyclic frame from the ENI 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTaskId

Cyclic Task ID (ENI: Cyclic/TaskId). Only valid if bIsCyclicFrame is set 

### enum EC_T_FRAME_RSPERR_TYPE

*Values:*

### enumerator eRspErr_UNDEFINED

Undefined 

### enumerator eRspErr_NO_RESPONSE

No Ethernet frame received (timeout, frame loss) 

### enumerator eRspErr_WRONG_IDX

Wrong IDX value in acyclic frame 

### enumerator eRspErr_UNEXPECTED

Unexpected frame was received 

### enumerator eRspErr_FRAME_RETRY

Ethernet frame will be re-sent (timeout, frame loss) 

### enumerator eRspErr_RETRY_FAIL

All retry mechanism fails to re-sent acyclic frames 

### enumerator eRspErr_FOREIGN_SRC_MAC

Frame with MAC from other Master received 

### enumerator eRspErr_NON_ECAT_FRAME

Non EtherCAT frame received 

### enumerator eRspErr_CRC

Ethernet frame with CRC error received 

### enumerator eRspErr_ETHERNET_PAUSE_FRAME

Ethernet pause frame (flow control) received 

## emonNotify - EC_NOTIFY_STATUS_SLAVE_ERROR

When processing cyclic frames, the EC-Monitor checks whether the ERROR bit in the AL-STATUS register is set for at least one SubDevice. In this case, this notification is triggered.
If the EtherCAT® MainDevice determines the error information of the SubDevice(s) signal an error, another notification [emonNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO](notification_error.html.md#emonnotify-ec-notify-slave-error-status-info) with more precise error information is triggered.

## emonNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO

This notification will be indicated if the EtherCAT® MainDevice reads the AL-STATUS and AL-STATUS-CODE registers and the SubDevice signals an error in them. Detailed error information is stored in structure [`EC_T_SLAVE_ERROR_INFO_DESC`](notification_error.html.md#_CPPv426EC_T_SLAVE_ERROR_INFO_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](notification_error.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).

### struct EC_T_SLAVE_ERROR_INFO_DESC

### Public Members

### [EC_T_SLAVE_PROP](api_slave.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp

Slave properties 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStatus

Slave Status (AL Status) 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStatusCode

Error status code (AL STATUS CODE) 

## emonNotify - EC_NOTIFY_PDIWATCHDOG

This notification will be indicated every time a PDI watchdog error is detected. Detailed error information is stored in structure [`EC_T_PDIWATCHDOG_DESC`](notification_error.html.md#_CPPv421EC_T_PDIWATCHDOG_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](notification_error.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).

### struct EC_T_PDIWATCHDOG_DESC

### Public Members

### [EC_T_SLAVE_PROP](api_slave.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp

Slave properties 

## emonNotify - EC_NOTIFY_COMMUNICATION_TIMEOUT

This notification will be indicated if the EC-Monitor does not detect any EtherCAT® communication on the Ethernet tap for a parameterizable timeout.
The descriptor of the notification contains information on which port of the Ethernet tap the timeout occurred.

### struct EC_T_COMMUNICATION_TIMEOUT_NTFY_DESC

### Public Members

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bMainTapPortIn

EC_TRUE: Timeout occurred at the input port of the Ethernet TAP for the EtherCAT main line 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bMainTapPortOut

EC_TRUE: Timeout occurred at the output port of the Ethernet TAP for the EtherCAT main line 

#### SEE ALSO
[`EC_T_MONITOR_INIT_PARMS::dwCommunicationTimeoutMsec`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS26dwCommunicationTimeoutMsecE)

## emonNotify - EC_NOTIFY_TAP_LINK_STATUS

This notification will be indicated if the link status between EC-Monitor and Ethernet TAP device has changed.

### struct EC_T_TAP_LINK_STATUS_NTFY_DESC

### Public Members

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bLinkConnected

Link status of EC-Monitor - Ethernet Tap connection


# notification_status.html.md

# Status notifications

<!-- .. doxygenstruct:: EC_T_NOTIFICATION_DESC
    :members: -->

## emonNotify - EC_NOTIFY_STATECHANGED

Notification about a change in the MainDevice’s operational state.

**emonNotify - EC_NOTIFY_STATECHANGED**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to data of type EC_T_STATECHANGE which contains the old and the new MainDevice operational state
    * `dwInBufSize`: [in] Size of the input buffer provided at pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

### struct EC_T_STATECHANGE

### Public Members

### [EC_T_STATE](api_general.html.md#_CPPv410EC_T_STATE) oldState

Old operational state 

### [EC_T_STATE](api_general.html.md#_CPPv410EC_T_STATE) newState

New operational state 

## emonNotify - EC_NOTIFY_SB_STATUS

Scan bus status notification.

**emonNotify - EC_NOTIFY_SB_STATUS**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_SB_STATUS_NTFY_DESC
    * `dwInBufSize`: [in] Size of the input buffer provided at pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

### struct EC_T_SB_STATUS_NTFY_DESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwResultCode

[in] [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116): success, [EC_E_NOTREADY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga4033f6f3b33aa2550d6e46e808a92f37): no bus scan executed, [EC_E_BUSCONFIG_MISMATCH](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga613dd4e3b8cac7ac5193993f1afeaae6): bus configuration mismatch result of scanbus 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSlaveCount

[in] Number of slaves connected to the bus 

## emonNotify - EC_NOTIFY_SB_MISMATCH

This notification is triggered when the bus scan detects a discrepancy between connected SubDevices and configuration due to unexpected SubDevices or missing mandatory SubDevices.
In case of permanent frame loss no SubDevices can be found although the SubDevices are connected.

**emonNotify - EC_NOTIFY_SB_MISMATCH**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_SB_MISMATCH_DESC
    * `dwInBufSize`: [in] Size of the input buffer provided at pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

### struct EC_T_SB_MISMATCH_DESC

### Public Members

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPrevFixedAddress

[in] Previous slave station address 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPrevPort

[in] Previous slave station address 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPrevAIncAddress

[in] Previous slave auto-increment address 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wBusAIncAddress

[in] Unexpected slave (bus) auto-inc address 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBusVendorId

[in] Unexpected slave (bus) vendor ID 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBusProdCode

[in] Unexpected slave (bus) product code 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBusRevisionNo

[in] Unexpected slave (bus) revision number 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBusSerialNo

[in] Unexpected slave (bus) serial number 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wBusFixedAddress

[in] Unexpected slave (bus) station address 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bIdentificationError

[in] Identification command sent to slave but failed 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wIdentificationAdo

[in] Identification register 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wIdentificationVal

[in] Last identification value read from slave according to the last used identification method 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wIdentificationValExpected

[in] Identification expected value 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wCfgFixedAddress

[in] Missing slave (config) station Address 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wCfgAIncAddress

[in] Missing slave (config) Auto-Increment Address 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCfgVendorId

[in] Missing slave (config) Vendor ID 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCfgProdCode

[in] Missing slave (config) Product code 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCfgRevisionNo

[in] Missing slave (config) Revision Number 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCfgSerialNo

[in] Missing slave (config) Serial Number 

## emonNotify - EC_NOTIFY_HC_TOPOCHGDONE

This notification is triggered when a topology change was completely processed.

**emonNotify - EC_NOTIFY_HC_TOPOCHGDONE**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_DWORD (EC_E_NOERROR on success, Error code otherwise)
    * `dwInBufSize`: [in] sizeof(EC_T_DWORD)
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

## emonNotify - EC_NOTIFY_SLAVE_PRESENCE

This notification is given when a SubDevice appears at or disappears from the network.

**emonNotify - EC_NOTIFY_SLAVE_PRESENCE**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_SLAVE_PRESENCE_NTFY_DESC
    * `dwInBufSize`: [in] Size of the input buffer provided at pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

Disconnecting the SubDevice from the network, powering it off or a bad connection can produce this notification.

### struct EC_T_SLAVE_PRESENCE_NTFY_DESC

### Public Members

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress

Slave station address 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) bPresent

EC_TRUE: present, EC_FALSE: absent 

## emonNotify - EC_NOTIFY_SLAVE_STATECHANGED

This notification is triggered when a SubDevice has changed its EtherCAT® state. This notification is disabled by default.

**emonNotify - EC_NOTIFY_SLAVE_STATECHANGED**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_SLAVE_STATECHANGED_NTFY_DESC
    * `dwInBufSize`: [in] Size of the input buffer provided at pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

### struct EC_T_SLAVE_STATECHANGED_NTFY_DESC

### Public Members

### [EC_T_SLAVE_PROP](api_slave.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp

Slave properties 

### [EC_T_STATE](api_general.html.md#_CPPv410EC_T_STATE) newState

New slave state 

#### SEE ALSO
[emonIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](notification_enable-disable.html.md#emonioctl-ec-ioctl-set-notification-enabled) to enable notification.

## emonNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER

This notification is triggered when a SubDevice register transfer is completed.

To avoid excessive triggering of the notification, registers that are read by the EtherCAT® MainDevice at regular intervals are not notified. These are the following registers:

<!-- -*- mode: rst -*- -->
- AL-Status (0x0130)
- RX Error Counter, Forwarded RX Error Counter, ECAT Processing Unit Error Counter, PDI Error Counter, PDI Error Code, Lost Link Counter (0x0300:0x0314)
- SII EEPROM Interface (0x0500:0x050F)
- Registers above 0x1000

This notification is disabled by default.

**emonNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_SLAVEREGISTER_TRANSFER_NTFY_DESC
    * `dwInBufSize`: [in] Size of the input buffer provided at pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

### struct EC_T_SLAVEREGISTER_TRANSFER_NTFY_DESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTferId

Transfer ID. For every new slave register transfer a unique ID has to be assigned. This ID can be used after completion to identify the transfer. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwResult

Result of Slave register transfer 

### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bRead

EC_TRUE: Read register, EC_FALSE: Write register transfer 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wFixedAddr

Station address of slave 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wRegisterOffset

Register offset 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wLen

Length of slave register transfer 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyData

Pointer to the data read 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wWkc

Received working counter 

#### SEE ALSO
[emonIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](notification_enable-disable.html.md#emonioctl-ec-ioctl-set-notification-enabled) to enable notification.


# os.html.md

# Platform and Operating Systems (OS)

EC-Monitor and the EcMonitorDemo example application support a range of operating systems and platforms.
This chapter covers OS-specific setup, build, and compiler settings for each supported platform.

EC-Monitor is implemented in portable C++ and contains no direct operating system call. Everything it requires from its environment, such as memory, threads, synchronization and time, is obtained through a small OS layer. Only this layer is platform dependent, all other sources are built unmodified on every supported platform.

The OS layer interface is declared in the header file `EcOs.h` and covers the following services:

Memory
: Allocation as well as memory and string operations.

Threads
: Thread creation including priority and CPU affinity.

Synchronization
: Locks of several types and events.

Time
: Millisecond tick, sleep, host system time and high resolution counter.

Module loading
: Binding of the [Real-time Ethernet Driver](emll.html.md#real-time-ethernet-driver) at runtime on platforms supporting dynamically loaded modules.

Debug
: Assertions and string formatting.

The platform specific implementation consists of `EcOsPlatform.h` and `EcOs.cpp`. Most functions are that easy that they can be implemented using simple C macros mapping to the native API. Implementations for all platforms listed below are part of a source code delivery, see [source code delivery](integration_src.html.md#product-source-code).

The OS layer is initialized with `EC_T_OS_PARMS`, either by calling `OsInit()` as done by the demo applications, or by [`EC_T_MONITOR_INIT_PARMS::pOsParms`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS8pOsParmsE) when calling [`emonInitMonitor()`](api_general.html.md#_CPPv415emonInitMonitor10EC_T_DWORDPK23EC_T_MONITOR_INIT_PARMS).

#### NOTE
Real-time behaviour is determined by the operating system and not by EC-Monitor.


# os_linux.html.md

# Linux

<!-- *****
Linux
***** -->

## OS optimizations

Linux itself is not real-time capable, so it is recommended to use it with the additional PREEMPT_RT patch.

The power management can disrupt cyclical processing, it is advisable to disable the [CPUIDLE sub-system](os_linux.html.md#cpuidle-sub-system) and [CPUFREQ sub-system](os_linux.html.md#cpufreq-sub-system).
The sub-systems can be disabled by changing the kernel command line parameters in the boot loader. On x86, x86_64 systems this is usually GRUB, on embedded devices with ARM, ARM64 is usually u-boot. It is also possible to build a custom kernel without these sub-systems.

Running an EC-Monitor application on a dedicated CPU core that is isolated from the Linux scheduler ([ISOLCPUS](os_linux.html.md#isolcpus)) can provide additional stability.

### CPUIDLE sub-system

Check if CPUFREQ sub-system is enabled:
: ```console
  $ ls /sys/devices/system/cpu/
  ```

If `cpuidle` appears in the list, it is enabled.

Disable CPUIDLE via the kernel command-line in GRUB:
: ```default
  linux  /boot/vmlinuz-4.19.0-16-rt-amd64 cpuidle.off=1
  ```

### CPUFREQ sub-system

Check if CPUFREQ sub-system is enabled:
: ```console
  $ ls /sys/devices/system/cpu/
  ```

If `cpufreq` appears in the list, it is enabled.

Disable CPUFREQ sub-system via the kernel command-line GRUB:
: ```default
  linux  /boot/vmlinuz-4.19.0-16-rt-amd64 cpufreq.off=1
  ```

If CPUFREQ is not to be deactivated, the governor should be set to `performance`.

The currently active governor can be determined as follows:
: ```console
  $ cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
  ```

The available governors with:
: ```console
  $ cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_available_governors
  ```

To change governor use:
: ```console
  $ echo performance > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
  ```

### ISOLCPUS

Isolate CPU core number 4 of a quad-core processor via the kernel command-line GRUB:
: ```default
  linux  /boot/vmlinuz-4.19.0-16-rt-amd64 isolcpus=3
  ```

`isolcpus` alone removes scheduler tasks from selected CPUs, but does not prevent timer interrupts, RCU callbacks, or network adapter IRQs. To fully isolate a CPU for real-time workloads, `nohz_full`, `rcu_nocbs`, and `irqaffinity` should be used together to eliminate kernel noise and ensure deterministic execution.

Enhanced isolation of CPU core 4  via the kernel command-line GRUB:
: ```default
  linux  /boot/vmlinuz-4.19.0-16-rt-amd64 isolcpus=3 nohz_full=3 rcu_nocbs=3 rcu_nocb_poll irqaffinity=0-2
  ```

Running EcMonitorDemo on the isolated CPU core by setting the CPU affinity `-a`:
: ```console
  $ ./EcMonitorDemo -a 3
  ```

## atemsys kernel module

To use Real-time Ethernet Drivers under Linux, the atemsys kernel module must be compiled and loaded. atemsys grants direct access to hardware to improve the performance.

All necessary scripts, source code and a detailed description of the installation can be found on [https://github.com/acontis/atemsys](https://github.com/acontis/atemsys). A ready-to-use Yocto recipe is also available on [https://github.com/acontis/meta-acontis](https://github.com/acontis/meta-acontis)

![EC-Master architecture diagram for Linux showing the atemsys kernel module providing direct hardware access for Real-time Ethernet Drivers](../../OsLayer/Media/ec-masterarchlinux.png)

### atemsys as Device Tree Ethernet Driver

atemsys can also be used as a device tree driver to avoid certain conflicts between the Real-time Ethernet Driver and the Linux kernel, e.g. power management, shared MDIO bus, etc..

A detailed guide on how to customize the device tree accordingly can also be found on [https://github.com/acontis/atemsys](https://github.com/acontis/atemsys). Example device tree modifications for different Real-time Ethernet Drivers/SoC can be found in [https://github.com/acontis/atemsys/wiki](https://github.com/acontis/atemsys/wiki).

#### NOTE
This is the preferred solution on all embedded devices with device tree support.

### atemsys and PHY OS Driver

To use the PHY OS Driver, the acontis kernel module atemsys has to be included in the kernel device tree as an official driver for the Ethernet controller and doesn’t require any additional configuration at the application level.
As a result atemsys can interact with Linux drivers.

## Unbind Ethernet Driver instance

Ethernet Driver instances used by Real-time Ethernet Drivers may not be bound by kernel driver modules!
Unbind can be done by unloading the kernel driver module, via the unbind interface of the driver or by modifying the device tree.

### Unbind from kernel driver

The following command unbinds an instance without unloading the kernel driver module:

**PCI**

```console
$ echo "<Instance-ID>" > /sys/bus/pci/drivers/<driver-name>/unbind
```

Example:

```console
$ echo "0000:00:19.0" > /sys/bus/pci/drivers/e1000e/unbind
```

This call requires the PCI bus, device, function codes (in the above example it is 0000:00:19.0).
The codes can be found using Linux commands like, for example:

```console
$ ls /sys/bus/pci/drivers/e1000e
```

**SoC**

```console
$ echo "<Instance-ID>" > /sys/bus/platform/drivers/<driver-name>/unbind
```

Example:

```console
$ echo "2188000.ethernet" > /sys/bus/platform/drivers/fec/unbind
```

### Unload kernel driver

Not all drivers allow unbinding of network interfaces. If unbinding is not supported the corresponding Linux kernel driver must not be loaded.

The following command lists the loaded kernel modules that may conflict with Real-time Ethernet Driver:

```console
$ lsmod | egrep "<module-name>"
```

Example:

```console
$ lsmod | egrep "e1000|e1000e|igb"
```

PCI/PCIe: The command lspci -v shows which driver is assigned to which network card, e.g.:

```console
$ lspci -v
```

```console
...
11:0a.0 Ethernet controller: Intel Corporation 82541PI Gigabit Ethernet Controller (rev 05)
...
Kernel driver in use: e1000e
```

Modules can be prevented from loading with the following commands:

```console
$ echo blacklist <module-name> | sudo tee -a /etc/modprobe.d/blacklist.conf
$ update-initramfs -k all -u
$ sudo reboot
```

The following table shows the Kernel modules related to the Real-time Ethernet Driver:

| Chip                                | Real-time Ethernet Driver   | Kernel driver(s)   | Remarks              |
|-------------------------------------|-----------------------------|--------------------|----------------------|
| Broadcom Genet                      | emllBcmGenet                | genet              | Unbind not supported |
| Beckhoff CCAT                       | emllCCAT                    | ec_bhf             |                      |
| CPSW                                | emllCPSW                    | ti_cpsw            |                      |
| Generic                             | emllDpdk                    |                    |                      |
| DesignWare 3504                     | emllDW3504                  | stmmac             |                      |
|                                     | emllEG20T                   |                    |                      |
| Freescale TSEC/eTSEC v1/2           | emllETSEC                   | gianfar_driver     |                      |
| Freescale FEC and ENET controller   | emllFslFec                  | fec, fec_ptp       |                      |
| Cadence GEM/MACB                    | emllGEM                     | gem, macb          |                      |
| Intel Pro/1000                      | emllI8254x                  | igb, e1000, e1000e |                      |
| Intel Pro/1000                      | emllIntelGbe                | igb, e1000, e1000e |                      |
| Intel Pro/100                       | emllI8255x                  | e100               |                      |
| ICSS                                | emllICSS                    | prueth,pruss       | Unbind not supported |
| RDC R6040                           | emllR6040                   |                    |                      |
| Realtek RTL8139                     | emllRTL8139                 | 8139too, 8139cp    |                      |
| Realtek RTL8169 / RTL8111 / RTL8168 | emllRTL8169                 | r8169              | Unbind not supported |
| SuperH                              | emllSHEth                   | sh_eth             | Unbind not supported |
| Generic                             | emllSockRaw                 |                    |                      |
| Generic                             | emllSockXdp                 |                    |                      |

## Docker

It is possible to operate EC-Monitor within a Docker container with realtime priority. The atemsys kernel module should be installed on the host in order to operate the container with the lowest possible capabilities and privileges.

The following additional settings, permissions for `docker run` are required:

Add atemsys device to container
: ```default
  --device=/dev/atemsys:/dev/atemsys
  ```

Allow max realtime priority
: ```default
  --ulimit rtprio=99
  ```

Add capability to set priority an lock memory
: ```default
  --cap-add=sys_nice
  --cap-add=ipc_lock
  ```

Publish RAS server port 6000
: ```default
  -p 6000:6000
  ```

## Setting up and running EcMonitorDemo

1. Unbind Ethernet Driver instance, e.g.
   ```console
   $ echo 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind
   ```
2. Load atemsys kernel module
   ```console
   $ insmod atemsys.ko
   ```
3. Copy files from EC-Monitor package `/bin` and a `eni.xml` to directory e.g. `/tmp`.
4. Run EcMonitorDemo
   ```console
   $ cd /tmp
   $ ./EcMonitorDemo -intelgbe 1 1 -f eni.xml -perf
   ```

#### SEE ALSO
[Running EcMonitorDemo](gettingstarted_running-demo.html.md#running-ecdemo)

### Run in Docker container

1. Unbind Ethernet Driver instance and load atemsys on the host.
2. Create a directory on the host (e.g. `~/docker`) and copy files from EC-Monitor package `/bin` and `exi.xml` into this directory.
3. Start bash console in container
   : ```console
     $ sudo docker run -it \
         --name atem_container \
         --device=/dev/atemsys:/dev/atemsys \
         --ulimit rtprio=99 \
         --cap-add=sys_nice --cap-add=ipc_lock \
         -v ~/docker:/home/docker \
         -p 6000:6000 \
         ubuntu bash
     ```
     <br/>
     **Command line arguments:**
     - `-it` Allocate a pseudo-TTY and run container
     - `--name atem_container` Container name
     - `--device=/dev/atemsys:/dev/atemsys` Add atemsys device to container
     - `--ulimit rtprio=99` Allow max realtime priority
     - `--cap-add=sys_nice` Add Linux capability to set priority
     - `--cap-add=ipc_lock` Add Linux capability to lock memory
     - `-v ~/docker:/home/docker` Mount previously create directory to container
     - `-p 6000:6000` Publish RAS server port 6000
     - `ubuntu bash` Use Docker image ubuntu and start bash
4. Run EcMonitorDemo in container
   ```console
   # cd /home/docker
   # ./EcMonitorDemo -intelgbe 2 1 -f eni.xml -perf
   ```

## OS Compiler settings

Besides the general settings from [Compiling the EcMonitorDemo](gettingstarted_compiling.html.md#compile-ecdemo) the following settings are necessary to build the example application for Linux

Possible ARCHs (see ATECAT_ARCHSTR in `SDK/INC/Linux/EcOsPlatform.h`):
: - aarch64 (ARM 64Bit)
  - armv7-vfp-eabihf (ARM 32Bit)
  - PPC (PPC 32Bit with “-te500v2”)
  - riscv64 (RISC-V 64Bit)
  - x64 (x86 64Bit)
  - x86 (x86 32Bit)
  <br/>
  An ARM VFP system returns success on
  : ```console
    $ readelf -A /proc/self/exe | grep Tag_ABI_VFP_args
    ```

Extra include paths
: ```default
  <InstallPath>/Examples/Common/Linux
  <InstallPath>/SDK/INC/Linux
  ```

Extra source paths
: ```default
  <InstallPath>/Examples/Common/Linux
  <InstallPath>/Sources/OsLayer/Linux
  ```

Extra library paths to the main EtherCAT® components
: ```default
  <InstallPath>/SDK/LIB/Linux/<Arch>
  ```

Extra libraries (in this order)
: ```default
  EcMonitor pthread dl rt
  ```

## Build using cmake on Linux

Example usage to build Linux x64 Debug with cmake:

```console
$ cmake -DEC_OS=Linux -DEC_ARCH=x64
$ cmake --build .
```

## Cross-platform development under Windows

The following steps describe how to develop Linux cross-platform developing on Windows for Linux:

`-DEC_OS=Windows -DEC_ARCH=x64`

1. **Install MinGW**
   : - Download the latest version of MinGW from the MinGW official website [https://osdn.net/projects/mingw/](https://osdn.net/projects/mingw/)
     - Install the mingw-get-setup.exe tool to C:\\MinGW
     - Select the ‘’Basic Setup’’
     - Apply changes
2. **Install a cross platform toolchain**
   : - Download a cross-platform toolchain from e.g. the Linaro release storage server [https://releases.linaro.org/components/toolchain/gcc-linaro/](https://releases.linaro.org/components/toolchain/gcc-linaro/)
     - Unpack it to C:\\MinGW\\opt
3. **Build using cmake on Linux**

   Example usage to build for Linux x64 Debug on Windows with cmake and ninja:
   ```console
   $ cmake -DEC_OS=Linux -DEC_ARCH=x64 -DCMAKE_BUILD_TYPE=Debug .
   $ cmake --build .
   ```
4. **Build for LxWin using cmake on Linux**

   Example usage to build EcMasterDemo for Linux x64 Debug on Windows with cmake and ninja:
   ```doscon
   Workspace/LxWin/cmake/x64/Debug> cmake.exe -G Ninja ../../../../.. -DCMAKE_TOOLCHAIN_FILE=../../../../Linux/Toolchain.cmake -DEC_OS=LxWin -DEC_ARCH=x64 -DCMAKE_BUILD_TYPE=Debug
   Workspace/LxWin/cmake/x64/Debug> ninja.exe EcMasterDemo
   ```
5. **Cross build using cmake for Linux on Windows**

   Example usage to build EcMasterDemo for Linux x64 Debug on Windows with cmake and ninja:
   ```doscon
   Workspace/Linux/cmake/x64/Debug> cmake.exe -G Ninja ../../../../.. -DCMAKE_TOOLCHAIN_FILE=../../../Toolchain.cmake -DEC_OS=Linux -DEC_ARCH=x64 -DCMAKE_BUILD_TYPE=Debug
   Workspace/Linux/cmake/x64/Debug> ninja.exe EcMasterDemo
   ```
6. **Cross build using Eclipse CDT on Windows**
   : - Download and install the latest version of Eclipse CDT from the Eclipse official website [https://projects.eclipse.org/projects/tools.cdt](https://projects.eclipse.org/projects/tools.cdt)
     - Create a start batch file for eclipse
     <br/>
     ```batch
     set PATH=C:\MinGW\bin;C:\MinGW\msys\1.0\bin;%LINUX_CROSS_GCC_ARM_PATH%;%PATH%
     set LINUX_CROSS_GCC_ARM_PATH=C:\MinGW\opt\gcc-linaro-7.3.1-2018.05-i686-mingw32_aarch64-linux-gnu\bin
     set CFLAGS=-IC:\MinGW\opt\gcc-linaro-7.3.1-2018.05-i686-mingw32_aarch64-linux-gnu\aarch64-linux-gnu\libc\usr\include
     set CROSS_COMPILE=aarch64-linux-gnu-
     set ARCH=aarch64
     eclipse.exe
     ```


# os_qnx.html.md

# QNX Neutrino

<!-- ************
QNX Neutrino
************ -->

## Thread priority

QNX supports a total of 256 scheduling priority levels. A non-root thread can set its priority to a level from 1 to 63 (the highest priority).

Using priorities higher than 63 is only possible if  the allowed priority range is changed for non-root processes:

```console
$ procnto -P priority
```

For more information on changing the priority range refer to the QNX documentation.

#### ATTENTION
Not changing the priority range leads to poor timing performance!

## Unbind Ethernet Driver instance

The network interface must be unloaded if it is used by an operating system driver. Depending on the QNX version, a corresponding command must be executed in the QNX Shell or the QNX Build Script.

QNX >= 6.5
: ```console
  $ ifconfig en1 destroy
  ```

QNX >= 7.1
: ```console
  $ umount /dev/io-sock/devs-em.so/em1
  ```

## IOMMU/SMMU support

For systems that have to use an IOMMU/SMMU for security reasons, it is possible to create a predefined typed memory region that is used by the Real-time Ethernet Driver. The definition has to be done in the QNX BSP build file and the name must match following pattern:

**smm_** *LinkLayerName* **-** *InstanceNumber(32Bit Hex)*

Example: Real-time Ethernet Driver emllIntelGbe with instance number 1
: ```default
  smm_emllIntelGbe-0x00000001
  ```

A separate typed memory region must be defined for each Real-time Ethernet Driver instance. The typed memory is automatically used by the Real-time Ethernet Driver if it matches the pattern, otherwise the default memory is used.

## Setting up and running EcMonitorDemo

1. QNX Neutrino OS configuration

   In order to get real-time priority (e.g. 250), see [Thread priority](os_qnx.html.md#thread-priority) and also set JOBS_PRIORITY. The application needs root privileges to increase the priority above 63.
2. Unbind Ethernet Driver instance, e.g.
   ```console
   $ ifconfig en1 destroy
   ```
3. Copy files from EC-Monitor package `/bin` and `eni.xml` to directory, e.g. `/tmp`.
4. Adjust LD_LIBRARY_PATH search locations for Real-time Ethernet Driver if necessary, e.g.
   ```console
   $ export LD_LIBRARY_PATH=/tmp:$LD_LIBRARY_PATH
   ```
5. Run EcMonitorDemo
   ```console
   $ cd /tmp
   $ ./EcMonitorDemo -intelgbe 1 1 -f eni.xml -perf
   ```

#### SEE ALSO
[Running EcMonitorDemo](gettingstarted_running-demo.html.md#running-ecdemo)

## OS Compiler settings

Besides the general settings from [Compiling the EcMonitorDemo](gettingstarted_compiling.html.md#compile-ecdemo) the following settings are necessary to build the example application for QNX Neutrino.

Extra include paths
: ```default
  <InstallPath>/SDK/INC/QNX
  <InstallPath>/Examples/Common/QNX
  ```

Extra source paths
: ```default
  <InstallPath>/Examples/Common/QNX
  <InstallPath>/Sources/OsLayer/QNX
  ```

Extra library paths to the main EtherCAT® components
: ```default
  <InstallPath>/SDK/LIB/QNX/<Arch>
  ```

Extra libraries (in this order)
: ```default
  EcMonitor socket
  ```


# os_vxworks.html.md

# Windriver VxWorks

<!-- *****************
Windriver VxWorks
***************** -->

Real-time Ethernet Drivers for VxWorks are available.
If none of the Real-time Ethernet Drivers can be used, the SNARF Ethernet Driver must be selected.

The identification of the Real-time Ethernet Driver is done like this:

![VxWorks Real-time Ethernet Driver identification diagram showing how to identify and select the appropriate driver](../../OsLayer/Media/Identification_LL2.PNG)

## VxWorks native

The BSP has to be prepared to support Real-time Ethernet Driver:

1. To use a Real-time Ethernet Driver the adapter memory has to be mapped into VxWorks memory space (VxWorks 5.x only). I.e. for the Intel Pro/100 Ethernet Driver this can be achieved by setting the INCLUDE_FEI_END macro in the BSP configuration file config.h.
2. To avoid conflicts with the VxWorks network driver which normally will be loaded when INCLUDE_FEI_END is set the file configNet.h has to be adjusted in a way that the network driver is not loaded. The network driver entry has to be removed from the endDevTbl[]:

```text
END_TBL_ENTRY endDevTbl [] =
    {
    :       :       :
    :       :       :
    :       :       :
/*
#ifdef INCLUDE_FEI_END
    {0, FEI82557_LOAD_FUNC, FEI82557_LOAD_STRING, FEI82557_BUFF_LOAN,
    NULL, FALSE},
#endif /* INCLUDE_FEI_END */
*/
    :       :       :
    :       :       :
```

#### WARNING
Do not call `muxDevUnload()` for a network adapter managed by a VxBus driver. VxBus drivers expect to call `muxDevUnload()` themselves in their {vxbDrvUnlink}( ) methods, and instability may result if `muxDevUnload()` is called for a VxBus network device instance by other code.

#### SEE ALSO
The VxWorks Device Driver Developer’s Guide for more information about unloading VxBus devices

## SNARF Ethernet Driver

The SNARF Ethernet Driver is only needed if none of the Real-time Ethernet Driver can be used. The appropriate network adapter drivers have to be added to the VxWorks image.

## Setting up and running EcMonitorDemo

1. VxWorks OS configuration
   : See sections above.
2. Determine the network interface
   : Using the command line option the network interface card and Real-time Ethernet Driver to be used in the example application can be determined.
3. Connection of the EtherCAT® SubDevices
   : The SubDevices have to be connected with the VxWorks system using an Ethernet switch or a patch cable.
     Local IT infrastructure should not be mixed with EtherCAT® modules at the same switch as the EC-Monitor will send many broadcast packets!
     EtherCAT® requires a 100Mbit/s connection. If the VxWorks network adapter card does not support this speed a 100Mbit/s (!) Ethernet switch has to be used.
4. Download a Real-time Ethernet Driver module
   : The Real-time Ethernet Driver library (e.g. `emllIntelGbe.out`) which contains hardware support for the corresponding NIC must be downloaded.
     By default the Ethernet Driver emllSnarfGpp are contained in the binary delivery.
5. Download the example application
   : The target has to be started and a target-server connection will have to be established. After this the example application can be downloaded into the target.
6. Set up an FTP server connection on host
   : The demo application needs to load an XML file (`eni.xml`) for the configuration of the EC-Monitor. This file can be accessed using an FTP server. The screen shot below shows how to configure the FTP server.
     The directory contents can be checked via FTP using the `ls` command. The file `eni.xml` will have to be accessed using the default directory.
7. Check for exclusive hardware access
   : Be sure that the network adapter instance dedicated to EtherCAT® is not controlled by a VxWorks driver, this can be verified using:
     ```doscon
     -> muxShow
     ```
     <br/>
     If it is needed, first unload the driver using:
     (e.g. first instance of the Intel Pro/100):
     ```doscon
     -> muxDevUnload "fei", 1
     ```
     <br/>
     (e.g. second instance of the Intel Pro/1000):
     ```doscon
     -> muxDevUnload "gei", 2
     ```
     <br/>
     (e.g. first instance of the Realtek 8139):
     ```doscon
     -> muxDevUnload "rtl", 1
     ```
     <br/>
     (e.g. first instance of the Realtek 8169):
     ```doscon
     -> muxDevUnload "rtg", 1
     ```
     <br/>
     (e.g. first instance of the FEC on Freescale iMX platform):
     ```doscon
     -> muxDevUnload "motfec", 1
     ```
     <br/>
     (e.g. first instance of the ETSEC on Freescale PPC platform):
     ```doscon
     -> muxDevUnload "motetsec", 1
     ```
8. Run the example application
   : The downloadable module `EcMonitorDemo.out` has to be executed. The configuration file `eni.xml` will be used and thus has to be accessible in the current working directory.
     The appropriate Real-time Ethernet Driver and network adapter card have to be selected.
     If the log files shall be written the global variable `bLogFileEnb` has to be set to 1 prior to starting the demo.
     <br/>
     Loading and running the demo:
     ```doscon
     -> ld<EcMonitorDemo.out
     -> sp EcMasterAppMain,"-intelgbe 1 1 -f eni.xml"
     ```

#### SEE ALSO
[Running EcMonitorDemo](gettingstarted_running-demo.html.md#running-ecdemo)

## OS Compiler settings

Besides the general settings from [Compiling the EcMonitorDemo](gettingstarted_compiling.html.md#compile-ecdemo) the following settings are necessary to build the example application for VxWorks.

Extra include paths
: ```default
  <InstallPath>/SDK/INC/VxWorks
  <InstallPath>/Examples/Common/VxWorks
  ```

Extra source paths
: ```default
  <InstallPath>/Examples/Common/VxWorks
  <InstallPath>/Sources/OsLayer/VxWorks
  ```

Extra library paths to the main EtherCAT® components
: ```default
  <InstallPath>/SDK/LIB/VxWorks/<ARCH>
  ```

GNU/PowerPC
: `-mlongcall` compiler option may be needed to avoid relocation offset errors when downloading `.out` files.


# os_windows.html.md

# Microsoft Windows

<!-- *****************
Microsoft Windows
***************** -->

## EcMonitorDemo

1. Install EC-Monitor
   : Run `setup.exe` from EC-Monitor package, which will guide you through the installation process.
2. Determine the network interface
   : For example the option -ndis 192.168.1.1 1 will be using the network adapter card with the IP address 192.168.1.1.

1. Insert a TAP device after the MainDevice Controller to capture the EtherCAT® traffic and start the EtherCAT® MainDevice

1. Run the example application
   : Execute EcMonitorDemo.exe from `<InstallPath>/Bin/Windows/<Arch>/`. At least an Ethernet Driver option has to be given.
     ```doscon
     C:\> EcMonitorDemo -ndis 192.168.1.1 1 -f D:/eni.xml -sp
     ```

#### SEE ALSO
[Running EcMonitorDemo](gettingstarted_running-demo.html.md#running-ecdemo) for a detailed description of the demo application.

## EcMonitorDemoGuiDotNet (.NET) - Microsoft Windows

1. Prerequisites
   : To run the `EcMonitorDemoGuiDotNet.exe`, the libraries `EcMonitor.dll`, `EcWrapperDotNet.dll`, `EcWrapper.dll` and `emllNdis.dll` from `Bin/Windows/x64` are needed in `Bin/Windows/x64/Release`, `Bin/Windows/x64/Debug`
2. Visual Studio C#-project
   : The C#-project for VS2015 or higher is located at `Workspace/WindowsVS2015/EcMonitorDemoGuiDotNet/EcMonitorDemoGuiDotNet.csproj`
3. If the reference EcWrapperDotNet is missing, it must be re-added from `Bin/Windows/x64/EcWrapperDotNet.dll`
4. EcMonitorDemoGuiDotNet is now prepared for Run/Debug

## OS Compiler settings

Besides the general settings from [Compiling the EcMonitorDemo](gettingstarted_compiling.html.md#compile-ecdemo) the following settings are necessary to build the example application for Windows.

Extra include paths
: ```default
  <InstallPath>\SDK\INC\Windows
  <InstallPath>\Examples\Common\Windows
  ```

Extra source paths
: ```default
  <InstallPath>\Examples\Common\Windows
  <InstallPath>\Sources\OsLayer\Windows
  ```

Extra library paths to the main EtherCAT® components
: ```default
  <InstallPath>\SDK\LIB\Windows
  ```

## RtaccDevice for Real-time Ethernet Driver

As alternative to the NDIS based or Pcap based Ethernet Driver, an optional Real-time Ethernet Driver on Windows can be installed. The Real-time Ethernet Driver replaces the original Windows driver and also requires an extra license.

To **use the Real-time Ethernet Driver under Windows**, it is necessary to install the RtaccDevice driver included in the Real-time Ethernet Driver delivery:

1. Start the “Device Manager”
   : ![Windows Device Manager showing the network adapter where the RtaccDevice Real-time Ethernet Driver will be installed](../../OsLayer/Media/ecatdrv-net-step1.png)
2. Assign RtaccDevice to the network adapter
   : ![Windows Device Manager context menu on the network adapter showing the Update driver option](../../OsLayer/Media/ecatdrv-net-step2.png)

   ![Windows Update Drivers dialog for assigning RtaccDevice to the network adapter](../../OsLayer/Media/ecatdrv-net-step3.png)![Windows Update Drivers dialog showing the Browse my computer for drivers option](../../OsLayer/Media/ecatdrv-net-step4.png)

   Click on “Browse my computer for drivers”
   ![Windows driver search showing the Let me pick from a list of available drivers option](../../OsLayer/Media/ecatdrv-net-step5.png)

   Click on “Let me pick…”
   ![Windows driver list showing the Have Disk option for installing RtaccDevice from a specific directory](../../OsLayer/Media/ecatdrv-net-step6.png)

   Click on “Have Disk…”
3. Enter the directory of RtaccDevice Driver

   The default folder if not changed is `<InstallPath>\Bin\Windows\x64`
   ![Windows Have Disk dialog for entering the RtaccDevice driver directory path such as the InstallPath Bin Windows x64 folder](../../OsLayer/Media/ecatdrv-net-step7.png)

   Enter the correct directory at the input box and press OK to proceed.
4. Choose the RtaccDevice Driver and click “Next” and confirm the installation
   : ![Windows driver selection list showing RtaccDevice ready to be chosen for the network adapter](../../OsLayer/Media/ecatdrv-net-step8.png)![Windows driver installation confirmation dialog for the RtaccDevice Real-time Ethernet Driver](../../OsLayer/Media/ecatdrv-net-step9.png)

Optionally modify the search location of the Real-time Ethernet Driver

Search locations for Real-time Ethernet Driver can be adjusted using the PATH environment variable.

\\newpage

The RtaccDevice must be assigned to the network adapter for Real-time Ethernet Driver usage on Windows. In this case it is exclusively bound for EtherCAT® usage.
The assignment can be reverted using the following steps:

1. Open the Windows device manager (Computer Management), then go to System devices. The RtaccDevice should be listed there:

> ![Windows Computer Management showing the System devices node where RtaccDevice is listed](../../Common/Media/Rtacc_Computer_Management_01.jpg)![Windows Computer Management zoomed view of the RtaccDevice Ethernet Controller in System devices](../../Common/Media/Rtacc_Computer_Management_02.jpg)
1. Right click on the RtaccDevice Ethernet Controller, then click on Properties:

> ![Windows Device Properties dialog for the RtaccDevice Ethernet Controller accessed via right-click Properties](../../Common/Media/Rtacc_Ethernet_Controller_Properties_Driver.jpg)
1. Switch to the tab “Driver”, then click the button “Update driver”:

> ![Windows Device Properties Driver tab showing the Update driver button for reverting the RtaccDevice assignment](../../Common/Media/Rtacc_Update_Driver.jpg)
1. Click on “Browse my computer for drivers”:

> ![Windows Update Drivers dialog showing the Browse my computer for drivers option to revert RtaccDevice](../../Common/Media/Rtacc_Search_for_Driver.jpg)
1. Click on “Let me pick from a list of available drivers on my computer”:

> ![Windows driver selection dialog showing the original network adapter driver to restore after removing RtaccDevice](../../Common/Media/Rtacc_Select_Device.jpg)

> Select the network adapter and click “Next”.

The assignment is now reverted.


# ras.html.md

# RAS-Server for EC-Inspector and EC-Engineer

The Remote Access Service (RAS) provides a socket-based uplink that lets diagnosis tools such as EC-Inspector and EC-Engineer connect to the EC-Monitor remotely. This chapter describes how to integrate and start the RAS server within your application, and lists the RAS server’s application programming interface.


# ras_api.html.md

# Application programming interface

## emonRasSrvStart

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) EC_NAMESPACE::emonRasSrvStart(const [EC_T_RAS_SERVER_PARMS](ras_api.html.md#_CPPv421EC_T_RAS_SERVER_PARMS) \*pParms, [EC_T_PVOID](api.html.md#_CPPv410EC_T_PVOID) \*ppHandle)

Starts the RAS Server. 

* **Parameters:**
  * **pParms** – [in] Server start-up parameters 
  * **ppHandle** – [out] Handle to opened instance, used for ctrl access 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_RAS_SERVER_PARMS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSignature

[in] Set to EC_RAS_SERVER_SIGNATURE 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSize

[in] Set to sizeof(EC_T_RAS_SERVER_PARMS) 

### [EC_T_LOG_PARMS](api_general.html.md#_CPPv414EC_T_LOG_PARMS) LogParms

[in] Logging parameters 

### [EC_T_IPADDR](ras_api.html.md#_CPPv411EC_T_IPADDR) oAddr

[in] Remote Access Server (RAS) listen IP address 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPort

[in] Remote Access Server (RAS) listen port 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wMaxClientCnt

[in] Max. clients in parallel (0: unlimited) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCycleTime

[in] Cycle Time of RAS Network access (acceptor, worker) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCommunicationTimeout

[in] Timeout [ms] before automatically closing connection 

### EC_T_CPUSET oAcceptorThreadCpuAffinityMask

[in] Acceptor Thread CPU affinity mask 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwAcceptorThreadPrio

[in] Acceptor Thread Priority 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwAcceptorThreadStackSize

[in] Acceptor Thread Stack Size 

### EC_T_CPUSET oClientWorkerThreadCpuAffinityMask

[in] Client Worker Thread CPU affinity mask 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClientWorkerThreadPrio

[in] Client Worker Thread Priority 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClientWorkerThreadStackSize

[in] Client Worker Thread Stack Size 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxQueuedNotificationCnt

[in] Amount of concurrently queue able Notifications 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxParallelMbxTferCnt

[in] Amount of concurrent active mailbox transfers 

### [EC_PF_NOTIFY](api_general.html.md#_CPPv412EC_PF_NOTIFY) pfnRasNotify

[in] Function pointer called to notify error and status information generated by Remote API Layer 

### EC_T_VOID \*pvRasNotifyCtxt

[in] Notification context returned while calling pfNotification 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCycErrInterval

[in] Interval which allows cyclic Notifications 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxQueuedNotificationSize

[in] Size of concurrent active mailbox transfers 

### EC_PF_CHECK_TOKEN pfCheckToken

[in] Function pointer called to check token 

### EC_T_VOID \*pvCheckTokenContext

[in] Check token context 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyTlsCert

[in] TLS certificate filename string 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTlsCertSize

[in] Size of TLS certeficate 

### EC_T_TLS_CERT_TYPE eTlsCertType

[in] TLS certeficate type 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyTlsPrivKey

[in] TLS private key filename string 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTlsPrivKeySize

[in] Size of TLS private key 

### EC_T_TLS_PRIVKEY_TYPE eTlsPrivKeyType

[in] TLS certeficate type 

### union EC_T_IPADDR

 *#include <EthernetServices.h>*

### Public Members

### [EC_T_INNER_IPADDR](ras_api.html.md#_CPPv417EC_T_INNER_IPADDR) sAddr

IPv4 address (endianness independent) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwAddr

Reserved, use EC_T_IPADDR::sAddr.by instead. OS-Layer socket API calls (SOCKADDR_IN::sin_addr). 

### struct EC_T_INNER_IPADDR

### Public Members

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) by[4]

IPv4 address (endianness independent) 

## emonRasSrvStop

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) EC_NAMESPACE::emonRasSrvStop([EC_T_PVOID](api.html.md#_CPPv410EC_T_PVOID) pvHandle, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Stops the RAS Server. 

* **Parameters:**
  * **pvHandle** – [in] Handle to previously started Server 
  * **dwTimeout** – [in] Timeout [ms] used to shut down all spawned threads, it’s multiplied internally by the amount of threads spawned 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonRasNotify

Callback function called by Remote API Server in case of State changes or error situations.

### typedef [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) (\*[EC_PF_NOTIFY](api_general.html.md#_CPPv412EC_PF_NOTIFY))([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCode, [EC_T_NOTIFYPARMS](notification_callback.html.md#_CPPv416EC_T_NOTIFYPARMS) \*pParms)

## emonRasNotify - EC_RAS_NOTIFY_CONNECTION

Notification about a change in the Remote API’s state.

**emonRasNotify - EC_T_RAS_CONNOTIFYDESC**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to data of type EC_T_RAS_CONNOTIFYDESC
    * `dwInBufSize`: [in] Size of the input buffer in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

### struct EC_T_RAS_CONNOTIFYDESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCause

[in] Cause of state connection state change 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCookie

[in] Unique identification cookie of connection instance 

## emonRasNotify - EC_RAS_NOTIFY_REGISTER

Notification that a connected application registered a client to the EC-Monitor.

**emonRasNotify - EC_RAS_NOTIFY_REGISTER**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to data of type EC_T_RAS_REGNOTIFYDESC
    * `dwInBufSize`: [in] Size of the input buffer in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

### struct EC_T_RAS_REGNOTIFYDESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCookie

[in] Unique identification cookie of connection instance 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwResult

[in] Result of registration request 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceId

[in] Master Instance client registered to 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClientId

[in] Client ID of registered client 

## emonRasNotify - EC_RAS_NOTIFY_UNREGISTER

Notification that a connected application un-registered a client from the EC-Monitor.

**emonRasNotify - EC_RAS_NOTIFY_UNREGISTER**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to data of type EC_T_RAS_REGNOTIFYDESC
    * `dwInBufSize`: [in] Size of the input buffer in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

#### SEE ALSO
[`EC_T_RAS_REGNOTIFYDESC`](ras_api.html.md#_CPPv422EC_T_RAS_REGNOTIFYDESC)

## emonRasNotify - EC_RAS_NOTIFY_MARSHALERROR

Notification about an error during marshalling in Remote API Server connection layer.

**emonRasNotify - EC_RAS_NOTIFY_MARSHALERRORDESC**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to data of type EC_T_RAS_MARSHALERRORDESC
    * `dwInBufSize`: [in] Size of the input buffer in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

### struct EC_T_RAS_MARSHALERRORDESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCookie

[in] Unique identification cookie of connection instance 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCause

[in] Cause of the command marshalling error 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwLenStatCmd

[in] Length of the faulty command 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCommandCode

[in] Command code of the faulty command 

## emonRasNotify - EC_RAS_NOTIFY_ACKERROR

Notification about an error during creation of ack / nack packet.

**emonRasNotify - EC_RAS_NOTIFY_ACKERROR**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_DWORD containing error code
    * `dwInBufSize`: [in] Size of the input buffer in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

## emonRasNotify - EC_RAS_NOTIFY_NONOTIFYMEMORY

Notification given, when no empty buffers for notifications are available in the pre-allocated notification store. This points to a configuration error.

**emonRasNotify - EC_RAS_NOTIFY_NONOTIFYMEMORY**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_DWORD containing unique identification cookie of connection instance
    * `dwInBufSize`: [in] Size of the input buffer in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

## emonRasNotify - EC_RAS_NOTIFY_STDNOTIFYMEMORYSMALL

Notification given when the buffer size for standard notifications available in pre-allocated notification store is too small to carry a specific notification. This points to a configuration error.

**emonRasNotify - EC_RAS_NOTIFY_STDNOTIFYMEMORYSMALL**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_DWORD containing unique identification cookie of connection instance
    * `dwInBufSize`: [in] Size of the input buffer in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

## emonRasNotify - EC_RAS_NOTIFY_MBXNOTIFYMEMORYSMALL

Notification given when the buffer size for Mailbox notifications available in pre-allocated notification store is too small to carry a specific notification. This points to a configuration error.
This is a serious error. If this error is given, Mailbox Transfer objects may have become out of sync and therefore no longer valid. Mailbox notifications should be dimensioned correctly, see `emonRasSrvStart()`

**emonRasNotify - EC_RAS_NOTIFY_MBXNOTIFYMEMORYSMALL**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_DWORD containing unique identification cookie of connection instance
    * `dwInBufSize`: [in] Size of the input buffer in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL


# ras_integration.html.md

# Integration Requirements

To use the diagnosis tool EC-Inspector with a customer application, some modifications have to be made during integration of the EC-Monitor. The task is to integrate and start the Remote API Server system within the custom application, which provides a socket based uplink, which later on is connected by the
EC-Inspector.

An example on how to integrate the Remote API Server within the application is given with the example application, which in this case is pre-configured to listen for EC-Inspector on TCP Port 6000 when command line parameter “-sp” is given.

To clarify the steps which are needed within a custom application, the following pseudo-code segment may be used as a point of start. The Remote API Server library “EcMonitorRasServer.lib” (or respectively “EcMonitorRasServer.a”) must be linked.


