# Header files Function prototypes, definitions etc. of the API can be found in the header file `EcSimulator.h` which is the main header file to include when using EC-Simulator. # Generic API return status values Most of the functions and also some notifications will return an error status value to indicate whether a function was successfully executed or not. Some of the return status values have a generic meaning unspecific to the called API function. - [`EC_E_NOERROR`](error-codes_generic.html.md#c.EC_E_NOERROR): The function was successfully executed. - [`EC_E_NOTSUPPORTED`](error-codes_generic.html.md#c.EC_E_NOTSUPPORTED): Unsupported feature or functionality. - [`EC_E_BUSY`](error-codes_generic.html.md#c.EC_E_BUSY): The stack is currently busy and the function has to be re-tried at a later time. - [`EC_E_NOMEMORY`](error-codes_generic.html.md#c.EC_E_NOMEMORY): Not enough memory or frame buffer resources available. - [`EC_E_INVALIDPARM`](error-codes_generic.html.md#c.EC_E_INVALIDPARM): Invalid or inconsistent parameters. - [`EC_E_TIMEOUT`](error-codes_generic.html.md#c.EC_E_TIMEOUT): Timeout error. - [`EC_E_SLAVE_ERROR`](error-codes_generic.html.md#c.EC_E_SLAVE_ERROR): A SubDevice error was detected. - [`EC_E_INVALID_SLAVE_STATE`](error-codes_generic.html.md#c.EC_E_INVALID_SLAVE_STATE): The SubDevice is not in the requested state to execute the operation (e.g. when initiating a mailbox transfer the SubDevice must be at least in PREOP state). - [`EC_E_SLAVE_NOT_ADDRESSABLE`](error-codes_generic.html.md#c.EC_E_SLAVE_NOT_ADDRESSABLE): The SubDevice does not respond to its station address (e.g. when requesting its AL_STATUS value). The SubDevice may be removed from the bus or powered-off. - [`EC_E_LINK_DISCONNECTED`](error-codes_generic.html.md#c.EC_E_LINK_DISCONNECTED): Link cable not connected. - [`EC_E_MASTERCORE_INACCESSIBLE`](error-codes_generic.html.md#c.EC_E_MASTERCORE_INACCESSIBLE): MainDevice core inaccessible. This result code usually means a remote connected server / EC-Simulator stack does not respond anymore. # Multiple EtherCAT® Network Support ## Overview The acontis EC-Simulator stack supports multiple EtherCAT® network instances within the same application process. The first parameter of all esXxx API functions is the Instance ID, starting with 0. The maximum Instance ID of the EC-Simulator SDK is defined as MAX_NUMOF_SIMULATOR_INTERFACES - 1. Implementing multiple EtherCAT® network instances is realized by using multiple Instance IDs. ![Diagram showing multiple EC-Simulator stack instances within the same application process, each identified by a unique Instance ID with its own Real-time Ethernet Driver](../Media/overview.png) The Real-time Ethernet Driver can be of same or different type (emllPcap, emllIntelGbe, …). ## Licensing For each network identified with the unique Instance ID a separate runtime license is required. # General functions ## esInitSimulator ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esInitSimulator([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceId, const [EC_T_SIMULATOR_INIT_PARMS](#_CPPv425EC_T_SIMULATOR_INIT_PARMS) \*pParms) Initialize EC-Simulator HiL. This function has to be called prior to calling any other function of EC-Simulator HiL. For EC-Simulator SiL (emllSimulator) this function is implicitly called by emInitMaster() and may not be called explicitly. \_ * **Parameters:** * **dwInstanceId** – [in] Simulator Instance ID * **pParms** – [in] Pointer to 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) or error code ### struct EC_T_SIMULATOR_INIT_PARMS ### Public Members ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSignature [in] Set to SIMULATOR_SIGNATURE ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSize [in] Set to sizeof(EC_T_SIMULATOR_INIT_PARMS) ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSimulatorAddress [in] Reserved ### [EC_T_OS_PARMS](#_CPPv413EC_T_OS_PARMS) \*pOsParms [in] OS layer parameters ### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) \*apLinkParms[EC_SIMULATOR_MAX_LINK_PARMS] [in] Link layer parameters ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBusCycleTimeNsec [in] Bus cycle time in nanoseconds [ns] ### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bDisableProcessDataImage [in] Disable Process Data Image (Process Data Variables not supported) ### EC_T_SIMULATOR_DEVICE_CONNECTION_DESC aoDeviceConnection[EC_SIMULATOR_MAX_LINK_PARMS] [in] see EC_SIMULATOR_DEVICE_CONNECTION_TYPE… ### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bConnectHcGroups [in] Connect hot connect groups in topology (floating group heads to free ports) ### [EC_T_PERF_MEAS_INTERNAL_PARMS](#_CPPv429EC_T_PERF_MEAS_INTERNAL_PARMS) PerfMeasInternalParms [in] Internal performance measurement parameters ### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bApiLockByApp [in] Lock pending API against esDeinitSimulator(). EC_FALSE (default): locked internally. EC_TRUE: application is responsible for locking. ### 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](#_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…](#d3-d63-group-e-c-l-o-g-l-e-v-e-l-s) ### [EC_PF_LOGMSGHK](#_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… The following log levels are defined: ### 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 Log messages are passed from the EC-Simulator to the callback given at [`EC_T_LOG_PARMS::pfLogMsg`](#_CPPv4N14EC_T_LOG_PARMS8pfLogMsgE). The example program demonstrates how messages can be processed by the application, see `Examples/Common/EcLogging.cpp`. For performance reasons the EC-Simulator automatically filters log messages according to [`EC_T_LOG_PARMS::dwLogLevel`](#_CPPv4N14EC_T_LOG_PARMS10dwLogLevelE). E.g. messages of severity [`EC_LOG_LEVEL_WARNING`](#c.EC_LOG_LEVEL_WARNING) are not passed to the application if [`EC_T_LOG_PARMS::dwLogLevel`](#_CPPv4N14EC_T_LOG_PARMS10dwLogLevelE) is set to [`EC_LOG_LEVEL_ERROR`](#c.EC_LOG_LEVEL_ERROR). The application can provide customized log message handlers of type [`EC_PF_LOGMSGHK`](#_CPPv414EC_PF_LOGMSGHK) if the default handler in `EcLogging.cpp` does not fulfill the application’s needs. Note: The callback is typically called from the Job Task’s context and should return as fast as possible. ### 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](#_CPPv428EC_T_PERF_MEAS_COUNTER_PARMS) CounterParms [in] Timer function settings. When not provided OsMeasGetCounterTicks is used. ### [EC_T_PERF_MEAS_HISTOGRAM_PARMS](#_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](#_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 ## esDeinitSimulator ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esDeinitSimulator([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceId) Deinitialize EC-Simulator HiL. Waits for pending API calls if [esInitSimulator()](#da/dca/_ec_simulator_api_8cpp_1a9abcdec979e4ebcde0ddc9fd83da2948) was called with [EC_T_SIMULATOR_INIT_PARMS::bApiLockByApp](#dc/dc1/struct_e_c___t___s_i_m_u_l_a_t_o_r___i_n_i_t___p_a_r_m_s_1aeebfa6d6f7ed3bbc5bb278370878f3b5) = EC_FALSE (default). For EC-Simulator SiL (emllSimulator) this function is implicitly called by emDeinitMaster() and may not be called explicitly. \_ * **Parameters:** **dwInstanceId** – [in] Simulator 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 ## esGetSimulatorParms ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esGetSimulatorParms([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceId, [EC_T_SIMULATOR_INIT_PARMS](#_CPPv425EC_T_SIMULATOR_INIT_PARMS) \*pParms, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwParmsBufSize) Get Simulator parameters provided by esInitSimulator(…) or esSetSimulatorParms(…). \_ * **Parameters:** * **dwInstanceId** – [in] Simulator Instance ID * **pParms** – [out] Pointer to simulator parameters * **dwParmsBufSize** – [in] Size of buffer at pParms * **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 [`esInitSimulator()`](#_CPPv415esInitSimulator10EC_T_DWORDPK25EC_T_SIMULATOR_INIT_PARMS) ## esSetSimulatorParms ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esSetSimulatorParms([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceId, const [EC_T_SIMULATOR_INIT_PARMS](#_CPPv425EC_T_SIMULATOR_INIT_PARMS) \*pParms) Change Simulator parameters provided by esInitSimulator(…). \_ * **Parameters:** * **dwInstanceId** – [in] Simulator Instance ID * **pParms** – [in] Pointer to simulator 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 #### SEE ALSO [`esInitSimulator()`](#_CPPv415esInitSimulator10EC_T_DWORDPK25EC_T_SIMULATOR_INIT_PARMS) ## esSetLogParms ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esSetLogParms([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_LOG_PARMS](#_CPPv414EC_T_LOG_PARMS) \*pLogParms) Sets log parameters. Used to change the parameters provided by esInitSimulator(). * **Parameters:** * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) * **pLogParms** – [in] New Log parameters #### SEE ALSO [`esInitSimulator()`](#_CPPv415esInitSimulator10EC_T_DWORDPK25EC_T_SIMULATOR_INIT_PARMS) #### SEE ALSO [`esSetSimulatorParms()`](#_CPPv419esSetSimulatorParms10EC_T_DWORDPK25EC_T_SIMULATOR_INIT_PARMS) ## esGetSrcMacAddress ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esGetSrcMacAddress([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, ETHERNET_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 Refers to adapter from EC_T_SIMULATOR_INIT_PARMS.pLinkParms at [`esInitSimulator()`](#_CPPv415esInitSimulator10EC_T_DWORDPK25EC_T_SIMULATOR_INIT_PARMS). ## esSetLicenseKey (HiL) ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esSetLicenseKey([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 Must be called after [`esInitSimulator()`](#_CPPv415esInitSimulator10EC_T_DWORDPK25EC_T_SIMULATOR_INIT_PARMS) and before [`esConfigureNetwork()`](#_CPPv418esConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD). This function may not be called if a non protected version is used. Example: ```cpp dwRes = esSetLicenseKey(dwInstanceID, "DA1099F2-15C249E9-54327FBC"); ``` ## esSetOemKey (HiL) ### static [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esSetOemKey([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwOemKey) Must be called after [`esInitSimulator()`](#_CPPv415esInitSimulator10EC_T_DWORDPK25EC_T_SIMULATOR_INIT_PARMS) and before [`esConfigureNetwork()`](#_CPPv418esConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD). Example: ```cpp dwRes = esSetOemKey(dwInstanceID, 0x1234567812345678); ``` ## esConfigureNetwork ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esConfigureNetwork([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_CNF_TYPE](#_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. Analyzing the network including mailbox communication can be done without specifying an ENI file using eCnfType_GenPreopENI. #### 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_GenPreopENI * **dwCnfDataLen** – [in] Length of configuration data in byte, or zero if eCnfType is eCnfType_GenPreopENI * **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 ## esGetCfgSlaveInfo ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esGetCfgSlaveInfo([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](#_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 Content of [`EC_T_CFG_SLAVE_INFO`](#_CPPv419EC_T_CFG_SLAVE_INFO) is subject to be extended. ### 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](#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. **Supported mailbox protocols flags** ### EC_MBX_PROTOCOL_AOE ### EC_MBX_PROTOCOL_EOE ### EC_MBX_PROTOCOL_COE ### EC_MBX_PROTOCOL_FOE ### EC_MBX_PROTOCOL_SOE ### EC_MBX_PROTOCOL_VOE ### **esGetCfgSlaveInfo() Example** ```cpp /* get information about slave configured in ENI file */ EC_T_CFG_SLAVE_INFO oSlaveInfo; OsMemset(&oSlaveInfo, 0, sizeof(EC_T_CFG_SLAVE_INFO)); dwRes = esGetCfgSlaveInfo(dwInstanceId, EC_TRUE, 1001, &oSlaveInfo); ``` ## esGetCfgSlaveSmInfo ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esGetCfgSlaveSmInfo([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](#_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](#_CPPv423EC_T_CFG_SLAVE_SM_ENTRY) aoSmInfos[ECREG_SYNCMANAGER_MAX_NUMOF] [out] Sync managers info ### **esGetCfgSlaveSmInfo() Example** ```cpp /* 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 = esGetCfgSlaveSmInfo(dwInstanceId, EC_TRUE, 1001, &oSlaveSmInfo); ``` ## esSetSlaveSscApplication ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esSetSlaveSscApplication([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceId, [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wCfgFixedAddress, [EC_T_SLAVE_SSC_APPL_DESC](#_CPPv424EC_T_SLAVE_SSC_APPL_DESC) \*pApp) Register slave application’s callback functions for slave without device emulation. \_ * **Parameters:** * **dwInstanceId** – [in] Simulator Instance ID * **wCfgFixedAddress** – [in] Slave’s station address * **pApp** – [in] Pointer to application 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) or error code ### struct EC_T_SLAVE_SSC_APPL_DESC ### Public Members ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSignature [in] Set to SIMULATOR_SIGNATURE ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSize [in] Set to sizeof(EC_T_SLAVE_SSC_APPL_DESC) ### EC_T_VOID \*pvContext [in] First parameter of SSC_APPL-callbacks ### EC_PF_SSC_APPL_MAIN_INIT pfnMainInit [in] SSC_APPL-callback for APPL_MainInit, called by SSC when slave initialization finished ### EC_PF_SSC_APPL_ACK_ERROR_IND pfnAckErrorInd [in] SSC_APPL-callback for APPL_AckErrorInd, called by SSC on error acknowledge by master ### EC_PF_SSC_APPL_APPLICATION pfnApplication [in] SSC_APPL-callback for APPL_Application, called after frame processing ### EC_PF_SSC_APPL_GET_DEVICE_ID pfnGetDeviceID [in] SSC_APPL-callback for APPL_GetDeviceID, called by SSC on Explicit Device ID request by master ### EC_PF_SSC_APPL_START_MAILBOX_HANDLER pfnStartMailboxHandler [in] SSC_APPL-callback for APPL_StartMailboxHandler, called by SSC on INIT to PREOP and INIT to BOOT transition ### EC_PF_SSC_APPL_STOP_MAILBOX_HANDLER pfnStopMailboxHandler [in] SSC_APPL-callback for APPL_StopMailboxHandler, called by SSC on PREOP to INIT and BOOT to INIT transition ### EC_PF_SSC_APPL_START_INPUT_HANDLER pfnStartInputHandler [in] SSC_APPL-callback for APPL_StartInputHandler, called by SSC on PREOP to SAFEOP transition (even if no INPUTs configured) ### EC_PF_SSC_APPL_STOP_INPUT_HANDLER pfnStopInputHandler [in] SSC_APPL-callback for APPL_StopInputHandler, called by SSC on SAFEOP to PREOP transition (even if no INPUTs configured) ### EC_PF_SSC_APPL_START_OUTPUT_HANDLER pfnStartOutputHandler [in] SSC_APPL-callback for APPL_StartOutputHandler, called by SSC on SAFEOP to OP transition (even if no OUTPUTs configured) ### EC_PF_SSC_APPL_STOP_OUTPUT_HANDLER pfnStopOutputHandler [in] SSC_APPL-callback for APPL_StopOutputHandler, called by SSC on OP to SAFEOP transition (even if no OUTPUTs configured) ### EC_PF_SSC_APPL_GENERATE_MAPPING pfnGenerateMapping [in] SSC_APPL-callback for APPL_GenerateMapping, called by SSC on PREOP to SAFEOP transition ### EC_PF_SSC_APPL_INPUT_MAPPING pfnInputMapping [in] SSC_APPL-callback for APPL_InputMapping, called by SSC to map (copy) INPUTs ### EC_PF_SSC_APPL_OUTPUT_MAPPING pfnOutputMapping [in] SSC_APPL-callback for APPL_OutputMapping, called by SSC to map (copy) OUTPUTs ### EC_T_PF_AOE_READ_CB pfnAoeRead [in] SSC_APPL-callback for APPL_AoeRead, called by SSC on AoE read request ### EC_T_PF_AOE_WRITE_CB pfnAoeWrite [in] SSC_APPL-callback for APPL_AoeWrite, called by SSC on AoE write request ### EC_T_PF_AOE_READWRITE_CB pfnAoeReadWrite [in] SSC_APPL-callback for APPL_AoeReadWrite, called by SSC on AoE read/write request ### EC_PF_SSC_APPL_EOE_RECEIVE pfnEoeReceive [in] SSC_APPL-callback for APPL_EoeReceive, called by SSC on received EoE Ethernet frame completion ### EC_PF_SSC_APPL_EOE_SETTING_IND pfnEoeSettingInd [in] SSC_APPL-callback for APPL_EoeSettingInd, called by SSC on EoE settings received ### EC_PF_SSC_APPL_FOE_WRITE pfnFoeWrite [in] SSC_APPL-callback for APPL_FoeWrite, called by SSC on FoE write request ### EC_PF_SSC_APPL_FOE_WRITE_DATA pfnFoeWriteData [in] SSC_APPL-callback for APPL_FoeWriteData, called by SSC when FoE data received ### EC_PF_SSC_APPL_FOE_READ pfnFoeRead [in] SSC_APPL-callback for APPL_FoeRead, called by SSC on FoE read request to transmit first FoE data ### EC_PF_SSC_APPL_FOE_READ_DATA pfnFoeReadData [in] SSC_APPL-callback for APPL_FoeReadData, called by SSC to transmit next FoE read data, 2..n ### EC_PF_SSC_APPL_FOE_ERROR pfnFoeError [in] SSC_APPL-callback for APPL_FoeError, called by SSC on FoE abort by master ### EC_PF_SSC_APPL_SET_PROC_VAR_PTR pfnSetProcVarPtr [in] SSC_APPL-callback for APPL_SetProcVarPtr, called on [esConfigureNetwork()](#db/d74/_ec_master_api_8cpp_1a600437cfa3d318ecc069859870e9e90d) for each process data variable #### SEE ALSO - [ADS over EtherCAT® (AoE)](api_mailbox.html.md#ads-over-ethercat-r-aoe) - [Ethernet over EtherCAT® (EoE)](api_mailbox.html.md#ethernet-over-ethercat-r-eoe) - [File access over EtherCAT® (FoE)](api_mailbox.html.md#file-access-over-ethercat-r-foe) - [`esInitSimulator()`](#_CPPv415esInitSimulator10EC_T_DWORDPK25EC_T_SIMULATOR_INIT_PARMS) - [`esConfigureNetwork()`](#_CPPv418esConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD) ## esRegisterClient ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esRegisterClient([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_PF_NOTIFY](#_CPPv412EC_PF_NOTIFY) pfnNotify, EC_T_VOID \*pCallerData, [EC_T_REGISTERRESULTS](#_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](#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](api_notifications.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) ## esUnregisterClient ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esUnregisterClient([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 ## esExecJob ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esExecJob([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_USER_JOB](#_CPPv413EC_T_USER_JOB) eUserJob, [EC_T_USER_JOB_PARMS](#_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](#_CPPv419EC_T_USER_JOB_PARMS)::[\_SEND_CYCFRAME_BY_TASKID](#_CPPv4N19EC_T_USER_JOB_PARMS24_SEND_CYCFRAME_BY_TASKIDE) SendCycFramesByTaskId ### struct [EC_T_USER_JOB_PARMS](#_CPPv419EC_T_USER_JOB_PARMS)::[\_PROCESS_RXFRAME_BY_TASKID](#_CPPv4N19EC_T_USER_JOB_PARMS26_PROCESS_RXFRAME_BY_TASKIDE) ProcessRxFramesByTaskId ### struct [EC_T_USER_JOB_PARMS](#_CPPv419EC_T_USER_JOB_PARMS)::[\_SWITCH_EOE_FRAMES](#_CPPv4N19EC_T_USER_JOB_PARMS18_SWITCH_EOE_FRAMESE) SwitchEoeFrames ### struct [EC_T_USER_JOB_PARMS](#_CPPv419EC_T_USER_JOB_PARMS)::[\_START_TASK](#_CPPv4N19EC_T_USER_JOB_PARMS11_START_TASKE) StartTask ### struct [EC_T_USER_JOB_PARMS](#_CPPv419EC_T_USER_JOB_PARMS)::[\_STOP_TASK](#_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`](#_CPPv4N13EC_T_USER_JOB26eUsrJob_ProcessAllRxFramesE) : If the Real-time Ethernet Driver operates in polling mode this call will process all currently received frames, 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`](#_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_SimulatorTimer`](#_CPPv4N13EC_T_USER_JOB22eUsrJob_SimulatorTimerE) : This has to be called cyclically to trigger the SubDevice state machines, copy process data from simulated SubDevice firmware as well as the mailbox handling. The SubDevice state machines handle the EtherCAT® state transitions.
Return: [`EC_E_NOERROR`](error-codes_generic.html.md#c.EC_E_NOERROR) if successful, error code in case of failures. ## esGetMasterState ### EC_T_STATE esGetMasterState([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 ## esIoCtl ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esIoCtl([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 ## esIoCtl - 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](#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 [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esIoCtl - 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](#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](#_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 [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esIoCtl - 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. 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 #### IMPORTANT With cable redundancy support enabled, EC_FALSE is only set if all links are down. #### SEE ALSO [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esIoCtl - 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](#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 [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esIoCtl - EC_IOCTL_ADDITIONAL_VARIABLES_FOR_SPECIFIC_DATA_TYPES ### EC_IOCTL_ADDITIONAL_VARIABLES_FOR_SPECIFIC_DATA_TYPES Enable or disable additional variables for specific data types. Default: Enabled. * **Parameters:** * **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: enable, EC_FALSE: disable. * **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 [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esIoCtl - EC_IOCTL_SIMULATOR_SET_MBX_PROCESS_CTL ### EC_IOCTL_SIMULATOR_SET_MBX_PROCESS_CTL Enable or disable mailbox processing at slave. Default: Enabled. * **Parameters:** * **pbyInBuf** – [in] Pointer to value of [EC_T_SIMULATOR_MBX_PROCESS_CTL_DESC](#d8/df5/struct_e_c___t___s_i_m_u_l_a_t_o_r___m_b_x___p_r_o_c_e_s_s___c_t_l___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_SIMULATOR_MBX_PROCESS_CTL_DESC ### Public Members ### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wCfgFixedAddress Slave’s station address. 0: all slaves. ### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bReadMbxOutEnabled Read mailbox out sync manager from DPRAM (received mailbox data from the master) ### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bProcessMbxEnabled Process mailbox data from the master (MailboxServiceInd) #### SEE ALSO [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esIoCtl - EC_IOCTL_SIMULATOR_GET_MBX_PROCESS_CTL ### EC_IOCTL_SIMULATOR_GET_MBX_PROCESS_CTL Get the information if mailbox processing at slave is enabled or disabled. * **Parameters:** * **pbyInBuf** – [in] Pointer to value of EC_T_WORD. Configured station address of slave. * **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes * **pbyOutBuf** – [out] Pointer to value of [EC_T_SIMULATOR_MBX_PROCESS_CTL_DESC](#d8/df5/struct_e_c___t___s_i_m_u_l_a_t_o_r___m_b_x___p_r_o_c_e_s_s___c_t_l___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 #### SEE ALSO [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esIoCtl - 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](#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](emll_init.html.md#_CPPv413EC_T_LINKMODE) eLinkMode [out] Operation mode of main interface ### [EC_T_LINKMODE](emll_init.html.md#_CPPv413EC_T_LINKMODE) eLinkModeRed [out] Operation mode of redundancy interface #### SEE ALSO [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esIoCtl - EC_LINKIOCTL_XXXX The generic control interface [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) provides access to the main network adapter when adding EC_IOCTL_LINKLAYER_MAIN to the EC_LINKIOCTL_XXXX parameter at dwCode. EC_IOCTL_LINKLAYER_RED specifies the redundant network adapter. **Parameters** pbyInBuf, dwInBufSize, pbyOutBuf, dwOutBufSize, pdwNumOutData are specific to EC_LINKIOCTL_XXXX, e.g. EC_LINKIOCTL_GET_ETHERNET_ADDRESS. ## esIoCtl - EC_LINKIOCTL_GET_ETHERNET_ADDRESS Get MAC address of the network adapter. **esIoCtl - 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 provided at pbyOutBuf in bytes * `pdwNumOutData`: [out] Pointer to EC_T_DWORD: amount of bytes written to the output buffer #### SEE ALSO [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esIoCtl - EC_LINKIOCTL_GET_SPEED Get network adapter’s speed in MBits. **esIoCtl - 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 provided at pbyOutBuf in bytes * `pdwNumOutData`: [out] Pointer to EC_T_DWORD: amount of bytes written to the output buffer #### SEE ALSO [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esIoCtl - EC_LINKIOCTL_GET_PCI_INFO Get network adapter’s PCI information **esIoCtl - EC_LINKIOCTL_GET_PCI_INFO** : **Parameter** : * `pbyInBuf`: [in] Should be set to EC_NULL * `dwInBufSize`: [in] Should be set to 0 * `pbyOutBuf`: [out] Pointer to EC_T_PCI_INFO buffer * `dwOutBufSize`: [in] Size of the output buffer in bytes. Must be at least the size of EC_T_PCI_INFO. * `pdwNumOutData`: [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer. ### struct EC_T_PCI_INFO ### Public Members ### [EC_T_PCI_INFO_LOCATION](#_CPPv422EC_T_PCI_INFO_LOCATION) Location PCI location (bus, device, function) ### [EC_T_PCI_INFO_IDENIFICATION](#_CPPv427EC_T_PCI_INFO_IDENIFICATION) Ident PCI identification (vendor id, device id) ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwIoBarCnt I/O bar count ### [EC_T_PCI_INFO_IOBAR](#_CPPv419EC_T_PCI_INFO_IOBAR) aIoBar PCI I/O bars info ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMemBarCnt Memory bar count ### [EC_T_PCI_INFO_MEMBAR](#_CPPv420EC_T_PCI_INFO_MEMBAR) aMemBar PCI Memory bars info ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInterruptCnt IRQ count ### [EC_T_PCI_INFO_INTERRUPT](#_CPPv423EC_T_PCI_INFO_INTERRUPT) aInterrupt PCI IRQ info ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) adwReserved[16] Reserved for future use ### struct EC_T_PCI_INFO_LOCATION ### Public Members ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDomainNumber Domain ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBusNumber Bus number ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDeviceNumber Device number ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwFunctionNumber Function number ### struct EC_T_PCI_INFO_IDENIFICATION ### Public Members ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwVendorId Vendor ID ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDeviceId Device ID ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwReserved Reserved for future use ### struct EC_T_PCI_INFO_IOBAR ### Public Members ### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwBaseAddress I/O bar base address ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwLen Bar length ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwReserved Reserved for future use ### struct EC_T_PCI_INFO_MEMBAR ### Public Members ### [EC_T_UINT64](api.html.md#_CPPv411EC_T_UINT64) qwBaseAddress Memory bar base address ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwLen Bar length ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwReserved Reserved for future use ### struct EC_T_PCI_INFO_INTERRUPT ### Public Members ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwIrq IRQ number ### EC_T_CPUSET CpuAffinity Reserved for future use ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) adwReserved[2] Reserved for future use #### SEE ALSO [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esIoCtl - EC_LINKIOCTL_FORCE_LINK_STATUS Forces the network adapter’s link status **esIoCtl - EC_LINKIOCTL_FORCE_LINK_STATUS** : **Parameter** : * `pbyInBuf`: [in] Pointer to EC_T_BYTE. See EC_LINK_FORCE_LINK_STATUS_… * `dwInBufSize`: [in] Size of the input buffer in bytes. Must be at least the size of EC_T_BYTE. * `pbyOutBuf`: [out] Should be set to EC_NULL * `dwOutBufSize`: [in] Should be set to 0 * `pdwNumOutData`: [out] Should be set to EC_NULL ### EC_LINK_FORCE_LINK_STATUS_DISCONNECTED Force link status Disconnected: 0 ### EC_LINK_FORCE_LINK_STATUS_OK Force link status OK: 1 ### EC_LINK_FORCE_LINK_STATUS_AUTO Force link status Auto: 2 #### SEE ALSO [`esIoCtl()`](#_CPPv47esIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD) ## esGetVersion ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esGetVersion([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 ## esGetText ### const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*esGetText([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 ## esGetMemoryUsage ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esGetMemoryUsage([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 ## esLogFrameEnable ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esLogFrameEnable([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, EC_T_PFLOGFRAME_CB pvLogFrameCallBack, EC_T_VOID \*pvContext) Setup a callback function to log the EtherCAT network traffic. The callback function is called by the cyclic task. Therefore the code inside the callback has to be fast and non-blocking. The callback parameter dwLogFlags can be used as a filter to log just specific frames. The master discards the frame if the callback function modifies the Ethernet frame type at byte offset 12. * **Parameters:** * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) * **pvLogFrameCallBack** – [in] Pointer to frame logging callback function * **pvContext** – [in] Pointer to function specific context * **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 ```cpp /********************************************************************************/ /** \brief Handler to log frames. * * CAUTION: Called by cyclic task! Do not consume too much CPU time! */ EC_T_VOID LogFrameHandler(EC_T_VOID* pvContext, EC_T_DWORD dwLogFlags, EC_T_DWORD dwFrameSize, EC_T_BYTE* pbyFrame) { EC_T_STATE eMasterState; /* get MainDevice state */ eMasterState = (EC_T_STATE)(dwLogFlags & EC_LOG_FRAME_FLAG_MASTERSTATE_MASK); /* skip tx frame */ if ((S_dwLogFrameLevel == 3) && !(dwLogFlags & EC_LOG_FRAME_FLAG_RX_FRAME)) return; /* skip cyclic frame */ if ((S_dwLogFrameLevel == 2) && !(dwLogFlags & EC_LOG_FRAME_FLAG_ACYC_FRAME)) return; /* skip red frame */ if (dwLogFlags & EC_LOG_FRAME_FLAG_RED_FRAME) return; /* do something with pbyFrame ... */ } ``` ## esLogFrameDisable ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esLogFrameDisable([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID) Disable the frame logging callback. * **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