# 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
### 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
### 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**
### 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
```
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).
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.
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
MbxTferDesc.pbyMbxTferDescData = (EC_T_PBYTE)OsMalloc(MbxTferDesc.dwMaxDataLen)
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;
pMbxTfer->pbyMbxTferData = MbxTferDesc.pbyMbxTferDescData
pMbxTfer->dwTferId = 1;
pMbxTfer->dwClntId = dwClntId;
dwResult = emonCoeSdoUplodadReq(pMbxTfer, dwSlaveId, wObIndex, ...);
state of the transfer object = Pend or TferReqError
```
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 ) { ... }
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 *
### 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**
### 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**
### 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
_Slave_
```
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)
```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**
### 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**
### 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_**
### 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**
### MASTER_SLAVE_ID
### SIMULATOR_SLAVE_ID
### MASTER_RED_SLAVE_ID
### EL9010_SLAVE_ID
### FRAMELOSS_SLAVE_ID
### JUNCTION_RED_FLAG
**Flags EC_LINECROSSED_**
### 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 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.
#### 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).
# 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
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:
# 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
E.g. API function call with invalid parameters |
| 2 | EtherCAT® network information file problem | ENI | Monitor configuration XML file mismatches SubDevice configuration on bus
E.g. Bus Topology Scan cannot detect all SubDevices configured within network information file |
| 3 | Monitor parameter configuration | CFG | Monitor configuration parameters erroneous
E.g. mailbox command queue not large enough |
| 4 | Bus/SubDevice Error | SLV | SubDevice error
E.g. Intel Pro/1000 NIC could not be found |
| 6 | Remote API | RAS | Remote API error
E.g. connection to Remote API server is not possible from client |
| 7 | Internal software error | ISW | Monitor internal error
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
### 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
### 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
### 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
### 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
### 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: -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
### 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
### 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.
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.
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.
#### 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.
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
# Compiling the EcMonitorDemo
The following main rules can be used to generate the example applications for all operating systems.
- `` is a placeholder for the operating system used.
- `` 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
/SDK/INC///SDK/INC
/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
/SDK/LIB//
```
EC-Monitor core
: ```default
libEcMonitor.a
```
EC-Monitor RAS server (optional)
: ```default
libEcMonitorRasServer.a
```
Dynamic libraries
: ```default
/Bin//
```
EC-Monitor core
: ```default
libEcMonitor.so
```
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 `/Bin//`.
- 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/slavebyname//variable/[output/input]/
```
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
# Running EcMonitorDemo
To capture the EtherCAT® traffic insert a TAP device between the EtherCAT® adapter of the MainDevice and the first SubDevice.
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 [-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
Path to ENI file
### -t