6.1. 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.

6.2. 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: The function was successfully executed.

  • EC_E_NOTSUPPORTED: Unsupported feature or functionality.

  • EC_E_BUSY: The stack currently is busy and the function has to be re-tried at a later time.

  • EC_E_NOMEMORY: Not enough memory or frame buffer resources available.

  • EC_E_INVALIDPARM: Invalid or inconsistent parameters.

  • EC_E_TIMEOUT: Timeout error.

  • EC_E_SLAVE_ERROR: A slave error was detected.

  • EC_E_INVALID_SLAVE_STATE: The slave is not in the requested state to execute the operation (e.g. when initiating a mailbox transfer the slave must be at least in PREOP state).

  • EC_E_SLAVE_NOT_ADDRESSABLE: The slave does not respond to its station address (e.g. when requesting its AL_STATUS value). The slave may be removed from the bus or powered-off.

  • EC_E_LINK_DISCONNECTED: Link cable not connected.

  • EC_E_MASTERCORE_INACCESSIBLE: Master core inaccessible. This result code usually means a remote connected server / EC-Simulator stack does not respond anymore

6.3. Multiple EtherCAT Network Support

6.3.1. 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.

The Real-time Ethernet Driver can be of same or different type (emllPcap, emllIntelGbe, …).

6.3.2. Licensing

For each network identified with the unique Instance ID a separate runtime license is required.

6.4. General functions

6.4.1. esInitSimulator

EC_T_DWORD esInitSimulator(EC_T_DWORD dwInstanceId, EC_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 implicitely called by emInitMaster() and may not be called explicitely.

Parameters

  • dwInstanceId – [in] Simulator Instance ID

  • pParms – [in] Pointer to init parameters

Returns

EC_E_NOERROR or error code

struct EC_T_SIMULATOR_INIT_PARMS

Public Members

EC_T_DWORD dwSignature

[in] Set to SIMULATOR_SIGNATURE

EC_T_DWORD dwSize

[in] Set to sizeof(EC_T_SIMULATOR_INIT_PARMS)

EC_T_DWORD dwSimulatorAddress

[in] Reserved

EC_T_OS_PARMS *pOsParms

[in] OS layer parameters

EC_T_LINK_PARMS *apLinkParms[EC_SIMULATOR_MAX_LINK_PARMS]

[in] Link layer parameters

EC_T_DWORD dwBusCycleTimeUsec

[in] [usec] bus cycle time in microseconds

EC_T_BOOL bDisableProcessDataImage

[in] (legacy support, CiA402 simulation)

EC_T_SIMULATOR_DEVICE_CONNECTION_DESC aoDeviceConnection[EC_SIMULATOR_MAX_LINK_PARMS]

[in] see EC_SIMULATOR_DEVICE_CONNECTION_TYPE_…

EC_T_BOOL bConnectHcGroups

[in] connect hot connect groups in topology (floating group heads to free ports)

EC_T_PERF_MEAS_INTERNAL_PARMS PerfMeasInternalParms

[in] Internal performance measurement parameters

EC_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 dwSignature

[in] Set to EC_OS_PARMS_SIGNATURE

EC_T_DWORD dwSize

[in] Set to sizeof(EC_T_OS_PARMS)

EC_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 dwSupportedFeatures

[in/out] reserved

EC_PF_QUERY_MSEC_COUNT pfSystemQueryMsecCount

[in] Function to get system’s msec count

struct EC_T_LOG_PARMS

Public Members

EC_T_DWORD dwLogLevel

[in] Log level. See EC_LOG_LEVEL_…

EC_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 (*EC_PF_LOGMSGHK)(EC_T_LOG_CONTEXT *pContext, EC_T_DWORD dwLogMsgSeverity, const EC_T_CHAR *szFormat, ...)
Parameters

  • pContext – [in] Context pointer. This pointer is used as parameter when the callback function is called

  • dwLogMsgSeverity – [in] Log message severity, EC_LOG_LEVEL_…

  • 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.

Returns

EC_E_NOERROR or error code

Log messages are passed from the EC-Simulator to the callback given at EC_T_LOG_PARMS::pfLogMsg. EcLogging.cpp demonstrates how messages can be handled by the application. For performance reasons the EC-Simulator automatically filters log messages according to EC_T_LOG_PARMS::dwLogLevel. E.g. messages of severity EC_LOG_LEVEL_WARNING are not passed to the application if EC_T_LOG_PARMS::dwLogLevel is set to EC_LOG_LEVEL_ERROR.

The application can provide customized log message handlers of type EC_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 bEnabled

[in] enable/disable internal performance counters.

EC_T_PERF_MEAS_COUNTER_PARMS CounterParms

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

EC_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 pfGetCounterTicks

[in] Function returning the current counter ticks

EC_T_VOID *pvGetCounterTicksContext

[in] Context passed into GetCounterTicks

EC_T_UINT64 qwFrequency

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

typedef EC_T_UINT64 (*EC_PF_PERF_MEAS_GETCOUNTERTICKS)(EC_T_VOID *pvContext)
Parameters

pvContext – [in] Arbitrarily application-defined parameter passed to callback

struct EC_T_PERF_MEAS_HISTOGRAM_PARMS

Public Members

EC_T_DWORD dwBinCount

[in] amount of bins to use for the histogram.

EC_T_UINT64 qwMinTicks

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

EC_T_UINT64 qwMaxTicks

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

6.4.2. esDeinitSimulator

EC_T_DWORD esDeinitSimulator(EC_T_DWORD dwInstanceId)

Deinitialize EC-Simulator HiL.

Waits for pending API calls if esInitSimulator() was called with EC_T_SIMULATOR_INIT_PARMS::bApiLockByApp = EC_FALSE (default). For EC-Simulator SiL (emllSimulator) this function is implicitely called by emDeinitMaster() and may not be called explicitely.

Parameters

dwInstanceId – [in] Simulator Instance ID

Returns

EC_E_NOERROR or error code

6.4.3. esGetSimulatorParms

EC_T_DWORD esGetSimulatorParms(EC_T_DWORD dwInstanceId, EC_T_SIMULATOR_INIT_PARMS *pParms, EC_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 or error code

See also

esInitSimulator()

6.4.4. esSetSimulatorParms

EC_T_DWORD esSetSimulatorParms(EC_T_DWORD dwInstanceId, EC_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 or error code

See also

esInitSimulator()

6.4.5. esSetLogParms

EC_T_DWORD esSetLogParms(EC_T_DWORD dwInstanceID, EC_T_LOG_PARMS *pLogParms)

Sets log parameters. Used to change the parameters provided by esInitSimulator().

Parameters

pLogParms – [in] New Log parameters

See also

esInitSimulator()

See also

esSetSimulatorParms()

6.4.6. esGetSrcMacAddress

EC_T_DWORD esGetSrcMacAddress(EC_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 or error code

Refers to adapter from EC_T_SIMULATOR_INIT_PARMS.pLinkParms at esInitSimulator().

6.4.7. esSetLicenseKey (HiL)

EC_T_DWORD esSetLicenseKey(EC_T_DWORD dwInstanceID, const EC_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

Must be called after esInitSimulator() and before esConfigureNetwork().This function may not be called if a non protected version is used.

Example:

dwRes = esSetLicenseKey(dwInstanceID, "DA1099F2-15C249E9-54327FBC");

6.4.8. esSetOemKey (HiL)

static EC_T_DWORD esSetOemKey(EC_T_DWORD dwInstanceID, EC_T_UINT64 qwOemKey)

Must be called after esInitSimulator() and before esConfigureNetwork().

Example:

dwRes = esSetOemKey(dwInstanceID, 0x1234567812345678);

6.4.9. esConfigureNetwork

EC_T_DWORD esConfigureNetwork(EC_T_DWORD dwInstanceID, EC_T_CNF_TYPE eCnfType, EC_T_PBYTE pbyCnfData, EC_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

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

6.4.10. esGetCfgSlaveInfo

EC_T_DWORD esGetCfgSlaveInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_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 or error code

Content of EC_T_CFG_SLAVE_INFO is subject to be extended.

struct EC_T_CFG_SLAVE_INFO

Public Members

EC_T_DWORD dwSlaveId

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

EC_T_CHAR abyDeviceName[ECAT_DEVICE_NAMESIZE]

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

EC_T_DWORD dwHCGroupIdx

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

EC_T_BOOL bIsPresent

[out] Slave present on bus

EC_T_BOOL bIsHCGroupPresent

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

EC_T_DWORD dwVendorId

[out] Vendor identification (from ENI file)

EC_T_DWORD dwProductCode

[out] Product code (from ENI file)

EC_T_DWORD dwRevisionNumber

[out] Revision number (from ENI file)

EC_T_DWORD dwSerialNumber

[out] Serial number (from ENI file)

EC_T_WORD wStationAddress

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

EC_T_WORD wAutoIncAddress

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

EC_T_DWORD dwPdOffsIn

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

EC_T_DWORD dwPdSizeIn

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

EC_T_DWORD dwPdOffsOut

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

EC_T_DWORD dwPdSizeOut

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

EC_T_DWORD dwPdOffsIn2

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

EC_T_DWORD dwPdSizeIn2

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

EC_T_DWORD dwPdOffsOut2

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

EC_T_DWORD dwPdSizeOut2

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

EC_T_DWORD dwPdOffsIn3

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

EC_T_DWORD dwPdSizeIn3

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

EC_T_DWORD dwPdOffsOut3

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

EC_T_DWORD dwPdSizeOut3

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

EC_T_DWORD dwPdOffsIn4

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

EC_T_DWORD dwPdSizeIn4

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

EC_T_DWORD dwPdOffsOut4

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

EC_T_DWORD dwPdSizeOut4

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

EC_T_DWORD dwMbxSupportedProtocols

[out] Mailbox protocols supported by the slave (from ENI file). Combination of Supported mailbox protocols flags

EC_T_DWORD dwMbxOutSize

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

EC_T_DWORD dwMbxInSize

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

EC_T_DWORD dwMbxOutSize2

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

EC_T_DWORD dwMbxInSize2

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

EC_T_BOOL bDcSupport

[out] Slave supports DC (from ENI file)

EC_T_WORD wNumProcessVarsInp

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

EC_T_WORD wNumProcessVarsOutp

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

EC_T_WORD wPrevStationAddress

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

EC_T_WORD wPrevPort

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

EC_T_WORD wIdentifyAdo

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

EC_T_WORD wIdentifyData

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

EC_T_BYTE byPortDescriptor

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

EC_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 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 awMasterSyncUnitIn[EC_CFG_SLAVE_PD_SECTIONS]

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

EC_T_WORD awMasterSyncUnitOut[EC_CFG_SLAVE_PD_SECTIONS]

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

EC_T_BOOL bDisabled

[out] Slave disabled by API (emSetSlaveDisabled / emSetSlavesDisabled).

EC_T_BOOL bDisconnected

[out] Slave disconnected by API (emSetSlaveDisconnected / emSetSlavesDisconnected).

EC_T_BOOL bExtended

[out] Slave generated by emConfigExtend

EC_T_BOOL bDcReferenceClock

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

EC_T_BOOL bDcPotentialRefClock

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

EC_T_DWORD dwDcCycleTime0

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

EC_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 nDcShiftTime

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

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
/* 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);

6.4.11. esGetCfgSlaveSmInfo

EC_T_DWORD esGetCfgSlaveSmInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_CFG_SLAVE_SM_INFO *pSlaveSmInfo)

Return information about Sync Master 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 or error code

struct EC_T_CFG_SLAVE_SM_ENTRY

Public Members

EC_T_WORD wPhysAddr

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

EC_T_WORD wLength

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

EC_T_BYTE byOpMode

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

EC_T_BYTE byDirection

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

EC_T_DWORD dwPdBitOffs

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

EC_T_DWORD dwPdBitSize

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

EC_T_WORD wWkcStateDiagBitOffs

[out] Offset of WkcState bit in diagnosis image

EC_T_WORD wMasterSyncUnit

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

struct EC_T_CFG_SLAVE_SM_INFO

Public Members

EC_T_DWORD dwSlaveId

[out] Slave ID

EC_T_DWORD dwSmInfoNumOf

[out] Number of available sync managers

EC_T_CFG_SLAVE_SM_ENTRY aoSmInfos[ECREG_SYNCMANAGER_MAX_NUMOF]

[out] Sync managers info

esGetCfgSlaveSmInfo() Example
/* 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);

6.4.12. esSetSlaveSscApplication

EC_T_DWORD esSetSlaveSscApplication(EC_T_DWORD dwInstanceId, EC_T_WORD wCfgFixedAddress, EC_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 or error code

struct EC_T_SLAVE_SSC_APPL_DESC

Public Members

EC_T_DWORD dwSignature

[in] Set to SIMULATOR_SIGNATURE

EC_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() for each process data variable

See also

6.4.13. esRegisterClient

EC_T_DWORD esRegisterClient(EC_T_DWORD dwInstanceID, EC_PF_NOTIFY pfnNotify, EC_T_VOID *pCallerData, EC_T_REGISTERRESULTS *pRegResults)

Register the application as a client with the EtherCAT stack for notifications (EC_NOTIFY_… )

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] Parameter passed to the application when the notification callback is called. The parameter can be arbitrarily defined by the application.

  • pRegResults – [out] Registration results

Returns

typedef EC_T_DWORD (*EC_PF_NOTIFY)(EC_T_DWORD dwCode, EC_T_NOTIFYPARMS *pParms)
Parameters

  • dwCode – [in] Notification code, see EC_NOTIFY_…

  • pParms – [in] Notification code depending data.

struct EC_T_REGISTERRESULTS

Public Members

EC_T_DWORD dwClntId

[out] Client ID

EC_T_BYTE *pbyPDIn

[out] Pointer to process data input memory

EC_T_DWORD dwPDInSize

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

EC_T_BYTE *pbyPDOut

[out] Pointer to process data output memory

EC_T_DWORD dwPDOutSize

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

6.4.14. esUnregisterClient

EC_T_DWORD esUnregisterClient(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClntId)

Deregister a client from the EtherCAT stack.

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 from registeration with the EtherCAT stack

Returns

EC_E_NOERROR or error code

6.4.15. esExecJob

EC_T_DWORD esExecJob(EC_T_DWORD dwInstanceID, EC_T_USER_JOB eUserJob, EC_T_USER_JOB_PARMS *pUserJobParms)

Execute or initiate the requested master 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

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 bAllCycFramesProcessed
EC_T_DWORD dwNumFramesSent
EC_T_DWORD dwTaskIdToSend
struct EC_T_USER_JOB_PARMS::_SEND_CYCFRAME_BY_TASKID SendCycFramesByTaskId
struct EC_T_USER_JOB_PARMS::_PROCESS_RXFRAME_BY_TASKID ProcessRxFramesByTaskId
struct EC_T_USER_JOB_PARMS::_SWITCH_EOE_FRAMES SwitchEoeFrames
struct EC_T_USER_JOB_PARMS::_START_TASK StartTask
struct EC_T_USER_JOB_PARMS::_STOP_TASK StopTask
struct _PROCESS_RXFRAME_BY_TASKID

Public Members

EC_T_BOOL bCycFramesProcessed
EC_T_DWORD dwTaskId
struct _SEND_CYCFRAME_BY_TASKID

Public Members

EC_T_DWORD dwTaskId
struct _START_TASK

Public Members

EC_T_DWORD dwTaskId
struct _STOP_TASK

Public Members

EC_T_DWORD dwTaskId
struct _SWITCH_EOE_FRAMES

Public Members

EC_T_DWORD dwMaxPortsToProcess
EC_T_DWORD dwNumFramesProcessed

Detailed job description:

  1. eUsrJob_ProcessAllRxFrames

    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.

    pUserJobParms->bAllCycFramesProcessed

    This flag is set to a value of EC_TRUE it indicates that all previously initiated cyclic frames ( eUsrJob_SendAllCycFrames ) are received and processed within this call. Not used if pUserJobParms set to EC_NULL.

    Return: EC_E_NOERROR if successful, error code in case of failures.

  2. eUsrJob_SimulatorTimer

    This has to be called cyclically to trigger the slave state machines, copy process data from simulated slave firmware as well as the mailbox handling. The slave state machines handle the EtherCAT state transitions.

    Return: EC_E_NOERROR if successful, error code in case of failures.

6.4.16. esGetMasterState

EC_T_STATE esGetMasterState(EC_T_DWORD dwInstanceID)

Get the EtherCAT master current state.

Parameters

dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

Returns

EtherCAT master state

6.4.17. esIoControl

EC_T_DWORD esIoControl(EC_T_DWORD dwInstanceID, EC_T_DWORD dwCode, EC_T_IOCTLPARMS *pParms)

A generic control interface between the application, the EtherCAT stack and its Real-time Ethernet Drivers.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • dwCode – [in] Control code

  • pParms – [in/out] Control code depending parameters

Returns

struct EC_T_IOCTLPARMS

Public Members

EC_T_BYTE *pbyInBuf

[in] Pointer to control input parameter.

EC_T_DWORD dwInBufSize

[in] Size of the input buffer provided at pbyInBuf in bytes

EC_T_BYTE *pbyOutBuf

[out] Pointer to control output buffer where the results will be copied into

EC_T_DWORD dwOutBufSize

[in] Size of the output buffer provided at pbyOutBuf in bytes

EC_T_DWORD *pdwNumOutData

[out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer

6.4.18. esIoControl - EC_IOCTL_GET_PDMEMORYSIZE

Queries the necessary size the process data image has got. This IOCTL is to be called after esConfigureNetwork.

esIoControl - EC_IOCTL_GET_PDMEMORYSIZE
Parameter

  • 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 (EC_T_MEMREQ_DESC)

  • dwOutBufSize: [in] Size of the output buffer provided at pbyOutBuf in bytes.

  • pdwNumOutData: [out] Should be set to EC_NULL

struct EC_T_MEMREQ_DESC

Public Members

EC_T_DWORD dwPDOutSize

Size of the output process data image

EC_T_DWORD dwPDInSize

Size of the input process data image

6.4.19. esIoControl - EC_IOCTL_REGISTER_CYCFRAME_RX_CB

This function call registers a callback function which is called after the cyclic frame is received. Typically this is used when the Real-time Ethernet Driver operates interrupt mode to get an event when the new input data (cyclic frame) is available. The callback function has to be registered after calling esConfigureNetwork() before starting the job task.

esIoControl - EC_IOCTL_REGISTER_CYCFRAME_RX_CB
Parameter

  • pbyInBuf: [in] Cyclic frame received callback descriptor (EC_T_CYCFRAME_RX_CBDESC)

  • dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

struct EC_T_CYCFRAME_RX_CBDESC

Public Members

EC_T_VOID *pCallbackContext

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

EC_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 dwTaskId, EC_T_VOID *pvContext)
Parameters

  • dwTaskId – [in] Task ID of the received cyclic frame (ENI: Cyclic/TaskId)

  • pvContext – [in] Arbitrarily application-defined parameter passed to callback

6.4.21. esIoControl - EC_IOCTL_GET_CYCLIC_CONFIG_INFO

Get cyclic configuration details from ENI configuration file.

esIoControl - EC_IOCTL_GET_CYCLIC_CONFIG_INFO
Parameter

  • 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 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.

struct EC_T_CYC_CONFIG_DESC

Public Members

EC_T_DWORD dwNumCycEntries

[out] Total number of cyclic entries

EC_T_DWORD dwTaskId

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

EC_T_DWORD dwPriority

[out] Priority of selected cyclic entry

EC_T_DWORD dwCycleTime

[out] Cycle time of selected cyclic entry

6.4.22. esIoControl - EC_IOCTL_ADDITIONAL_VARIABLES_FOR_SPECIFIC_DATA_TYPES

Enable or disable additional variables for specific data types. Default: Enabled.

esIoControl - EC_IOCTL_ADDITIONAL_VARIABLES_FOR_SPECIFIC_DATA_TYPES
Parameter

  • 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

6.4.23. esIoControl - EC_IOCTL_SIMULATOR_SET_MBX_PROCESS_CTL

Enable or disable mailbox processing at slave. Default: Enabled.

esIoControl - EC_IOCTL_SIMULATOR_SET_MBX_PROCESS_CTL
Parameter

  • pbyInBuf: [in] Pointer to value of :cpp:struct:`EC_T_SIMULATOR_MBX_PROCESS_CTL_DESC`

  • dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

struct EC_T_SIMULATOR_MBX_PROCESS_CTL_DESC

Public Members

EC_T_WORD wCfgFixedAddress

Slave’s station address. 0: all slaves

EC_T_BOOL bReadMbxOutEnabled

Read mailbox out sync manager from DPRAM (received mailbox data from the master)

EC_T_BOOL bProcessMbxEnabled

Process mailbox data from the master (MailboxServiceInd)

6.4.24. esIoControl - EC_IOCTL_SIMULATOR_GET_MBX_PROCESS_CTL

Enable or disable mailbox processing at slave. Default: Enabled.

esIoControl - EC_IOCTL_SIMULATOR_GET_MBX_PROCESS_CTL
Parameter

  • 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 :cpp:struct:`EC_T_SIMULATOR_MBX_PROCESS_CTL_DESC`

  • 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

esIoControl - EC_IOCTL_SIMULATOR_SET_MBX_PROCESS_CTL

6.4.25. esIoControl - EC_IOCTL_GET_LINKLAYER_MODE

This call allows the application to determine whether the Real-time Ethernet Driver is currently running in polling or in interrupt mode.

emIoControl - EC_IOCTL_GET_LINKLAYER_MODE
Parameter

  • 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

  • dwOutBufSize: [in] Size of the output buffer in bytes.

  • pdwNumOutData: [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.

Return

EC_E_NOERROR 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

6.4.26. esIoControl - EC_LINKIOCTL_XXXX

With EC_LINKIOCTL_XXXX a generic control interface exists between the application and the EC-Simulator and its Real-time Ethernet Driver.

The generic control interface esIoControl() 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.

6.4.27. esIoControl - EC_LINKIOCTL_GET_ETHERNET_ADDRESS

Get MAC address of network adapter

esIoControl - 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

6.4.28. esIoControl - EC_LINKIOCTL_GET_SPEED

Get current network adapter’s speed in MBits.

esIoControl - 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

6.4.29. esIoControl - EC_LINKIOCTL_GET_PCI_INFO

Get current network adapter’s PCI information

esIoControl - 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 Location

PCI location (bus, device, function)

EC_T_PCI_INFO_IDENIFICATION Ident

PCI identification (vendor id, device id)

EC_T_DWORD dwIoBarCnt

I/O bar count

EC_T_PCI_INFO_IOBAR aIoBar

PCI I/O bars info

EC_T_DWORD dwMemBarCnt

memory bar count

EC_T_PCI_INFO_MEMBAR aMemBar

PCI Memory bars info

EC_T_DWORD dwInterruptCnt

IRQ count

EC_T_PCI_INFO_INTERRUPT aInterrupt

PCI IRQ info

EC_T_DWORD adwReserved[16]

reserved for future use

struct EC_T_PCI_INFO_LOCATION

Public Members

EC_T_DWORD dwDomainNumber

Domain

EC_T_DWORD dwBusNumber

Bus number

EC_T_DWORD dwDeviceNumber

Device number

EC_T_DWORD dwFunctionNumber

Function number

struct EC_T_PCI_INFO_IDENIFICATION

Public Members

EC_T_DWORD dwVendorId

Vendor ID

EC_T_DWORD dwDeviceId

Device ID

EC_T_DWORD dwReserved

reserved for future use

struct EC_T_PCI_INFO_IOBAR

Public Members

EC_T_UINT64 qwBaseAddress

I/O bar base address

EC_T_DWORD dwLen

bar length

EC_T_DWORD dwReserved

reserved for future use

struct EC_T_PCI_INFO_MEMBAR

Public Members

EC_T_UINT64 qwBaseAddress

Memory bar base address

EC_T_DWORD dwLen

bar length

EC_T_DWORD dwReserved

reserved for future use

struct EC_T_PCI_INFO_INTERRUPT

Public Members

EC_T_DWORD dwIrq

IRQ number

EC_T_CPUSET CpuAffinity

reserved for future use

EC_T_DWORD adwReserved[2]

reserved for future use

6.4.31. esGetVersion

EC_T_DWORD esGetVersion(EC_T_DWORD dwInstanceID, EC_T_DWORD *pdwVersion, EC_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

6.4.32. esGetText

const EC_T_CHAR *esGetText(EC_T_DWORD dwInstanceID, EC_T_DWORD dwTextId)

Return text tokens by ID.

Parameters

dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

Returns

Textual description of the given ID

6.4.33. esGetMemoryUsage

EC_T_DWORD esGetMemoryUsage(EC_T_DWORD dwInstanceID, EC_T_DWORD *pdwCurrentUsage, EC_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 or error code

6.4.34. esLogFrameEnable

EC_T_DWORD esLogFrameEnable(EC_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 or error code 

/********************************************************************************/
/** \brief  Handler to log frames.
*
*   CAUTION: Called by cyclic task! Do not consume to 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 master 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 ... */
}

6.4.35. esLogFrameDisable

EC_T_DWORD esLogFrameDisable(EC_T_DWORD dwInstanceID)

Disable the frame logging callback.

Parameters

dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

Returns

EC_E_NOERROR or error code