8.1. General functions

8.1.1. emInitMonitor

EC_T_DWORD emInitMonitor(EC_T_DWORD dwInstanceId, EC_T_MONITOR_INIT_PARMS *pParms)

Initialize EC-Monitor.

Parameters

• dwInstanceId – [in] Instance ID

• pParms – [in] Monitor initialization parameters

Returns

EC_E_NOERROR or error code

struct EC_T_MONITOR_INIT_PARMS

Public Members

EC_T_DWORD dwSignature

[in] Set to MONITOR_SIGNATURE

EC_T_DWORD dwSize

[in] Set to sizeof(EC_T_MONITOR_INIT_PARMS)

EC_T_LOG_PARMS LogParms

[in] Logging parameters

EC_T_OS_PARMS *pOsParms

[in] Operation system layer parameters

EC_T_LINK_PARMS *pLinkParms

[in] Link layer parameters

EC_T_ETHERNET_TAP_TYPE eEthTapType

[in] Type of Ethernet TAP

EC_T_DWORD dwBusCycleTimeUsec

[in] Bus cycle time [usec]

EC_T_DWORD dwMaxBusSlaves

[in] Maximum pre-allocated bus slave objects

EC_T_DWORD dwBacktraceFrames

[in] Number of frames held in backtrace buffer. Total memory requirements of the buffer:

EC_T_PERF_MEAS_INTERNAL_PARMS PerfMeasInternalParms

[in] Internal performance measurement parameters

EC_T_WORKER_THREAD_PARMS WorkerThreadParms

[in] Internal worker thread parameters

EC_T_DWORD dwCommunicationTimeoutMsec

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

EC_T_BOOL bApiLockByApp

[in] EC_TRUE: Don’t lock pending API calls to increase performance

EC_T_CHAR szFileStoragePath[EC_FILESTORAGE_PATH_SIZE]

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

EC_T_MBX_PARMS MbxParms

[in] Mailbox monitoring parameters

enum EC_T_ETHERNET_TAP_TYPE

Values:

enumerator eEthTap_Unknown

Unknown type

enumerator eEthTap_AutoDetect

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

enumerator eEthTap_Generic

Generic Ethernet switch

enumerator eEthTap_Beckhoff_ET2000

Beckhoff ET2000 Ethernet probe

enumerator eEthTap_Kunbus_TapCurious

Kunbus TAP Curious Ethernet probe

enumerator eEthTap_Hilscher_netANALYZER

Hilscher netANALYZER Ethernet probe

enumerator eEthTap_Dummy

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)

struct _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

EC_PF_HW_TIMER_GET_INPUT_FREQUENCY pfHwTimerGetInputFrequency

[in] Function to get input frequency of HW timer. This function is needed by some DCM modes described in the Class A manual

EC_PF_HW_TIMER_MODIFY_INITIAL_COUNT pfHwTimerModifyInitialCount

[in] Function to modify initial count of HW timer. This function is needed by some DCM modes described in the Class A manual

EC_PF_HW_TIMER_GET_CURRENT_COUNT pfHwTimerGetCurrentCount

[in] Function to get current count of HW timer. This function is needed by some DCM modes described in the Class A manual

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

struct _EC_T_LOG_CONTEXT *pLogContext

[in] Log context to be passed to log callback

group EC_LOG_LEVELS

Defines

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)(struct _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

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

struct EC_T_WORKER_THREAD_PARMS

Public Members

EC_T_DWORD dwPrio

[in] Priority to use for the worker thread

EC_T_CPUSET cpuAffinityMask

[in] CPU affinity to use for the worker thread

struct EC_T_MBX_PARMS

Public Members

EC_T_DWORD dwMemoryPoolSize

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

struct _EC_T_MBX_PARMS_COE

Public Members

EC_T_BOOL bDisableNotifications

[in] Disable all CoE related EC_NOTIFY_MBOXRCV notifications

EC_T_BOOL bDisableODStorage

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

struct _EC_T_MBX_PARMS_FOE

Public Members

EC_T_BOOL bDisableNotifications

[in] Disable all FoE related EC_NOTIFY_MBOXRCV notifications

EC_T_BOOL bDisableFileStorage

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

EC_T_DWORD dwMaxQueuedMbxTransfers

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

8.1.2. emDeinitMonitor

EC_T_DWORD emDeinitMonitor(EC_T_DWORD dwInstanceId)

Deinitialize EC-Monitor.

Parameters

dwInstanceId – [in] Instance ID

Returns

EC_E_NOERROR or error code

8.1.3. emConfigureNetwork

EC_T_DWORD emConfigureNetwork(EC_T_DWORD dwInstanceID, EC_T_CNF_TYPE eCnfType, EC_T_PBYTE pbyCnfData, EC_T_DWORD dwCnfDataLen)

Configure EtherCAT network.

Parameters

• dwInstanceID – [in] Instance ID

• eCnfType – [in] Type of configuration data provided

• pbyCnfData – [in] Configuration data

• dwCnfDataLen – [in] Length of configuration data in byte

Returns

EC_E_NOERROR or error code

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

enumerator eCnfType_None

Reset configuration

enumerator eCnfType_ConfigData

pbyCnfData: Binary structured configuration

8.1.4. emGetMonitorStatus

EC_T_DWORD emGetMonitorStatus(EC_T_DWORD dwInstanceID, EC_T_MONITOR_STATUS *pStatus)

Get current Monitor status.

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

Parameters

• dwInstanceID – [in] Instance ID

• pStatus – [out] Monitor status descriptor

Returns

• EC_E_NOERROR on success

• EC_E_INVALIDSTATE if Monitor isn’t initialized

• EC_E_INVALIDPARM if pStatus invalid

struct EC_T_MONITOR_STATUS

Public Members

EC_T_BOOL bNextFramesReceived

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

EC_T_DWORD dwCyclesProcessed

[out] Number of EtherCAT cycles processed

EC_T_WORD wEthTapPositionAutoIncAddr

[out] Ethernet tap position as auto increment address

EC_T_BOOL bNextCyclicEntryReceived

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

8.1.5. emSetLicenseKey

EC_T_DWORD emSetLicenseKey(EC_T_DWORD dwInstanceID, const EC_T_CHAR *pszLicenseKey)

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)

• pszLicenseKey – [in] License key as zero terminated string with 26 characters.

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if master isn’t initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range

• EC_E_INVALIDSIZE the format of the license key is wrong. The correct length is 26 characters

• EC_E_LICENSE_MISSING the license key doesn’t match to the MAC Address

Example

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

See also

• emInitMonitor()

• emConfigureNetwork()

8.1.6. emRegisterClient

EC_T_DWORD emRegisterClient(EC_T_DWORD dwInstanceID, EC_PF_NOTIFY pfnNotify, EC_T_VOID *pCallerData, EC_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.

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if master isn’t initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range or the output pointer is EC_NULL

• EC_E_NOMEMORY if some memory cannot be allocated

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

Parameters

• dwCode – [in] Notification code, see EC_NOTIFY_…, e.g. EC_NOTIFY_STATECHANGED

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

8.1.7. emUnregisterClient

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

8.1.8. emGetSrcMacAddress

EC_T_DWORD emGetSrcMacAddress(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

See also

EC_T_MONITOR_INIT_PARMS::pLinkParms

8.1.9. emExecJob

EC_T_DWORD emExecJob(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

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if master isn’t initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range or the output pointer is EC_NULL

• EC_E_LINK_DISCONNECTED if the link is disconnected

• EC_E_FEATURE_DISABLED for eUsrJob_SwitchEoeFrames if EC_IOCTL_SET_EOE_DEFFERED_SWITCHING_ENABLED hasn’t be called before

• EC_E_ADS_IS_RUNNING if ADS server is running

Brief job overview:

enum EC_T_USER_JOB

Values:

enumerator eUsrJob_Undefined

enumerator eUsrJob_ProcessAllRxFrames

enumerator eUsrJob_SendAllCycFrames

enumerator eUsrJob_RunMcSm

enumerator eUsrJob_MasterTimer

enumerator eUsrJob_FlushQueuedCmds

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

   When the Link Layer operates in polling mode this call will process all currently received frames, when the Link Layer operates 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_MonitorTimer

   To trigger the monitor and slave state machines as well as the mailbox handling this call has to be executed cyclically. The monitor cycle time is determined by the period between calling emExecJob() ( eUsrJob_MonitorTimer). The state-machines are handling the EtherCAT state change transfers.

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

8.1.10. emGetMonitorParms

EC_T_DWORD emGetMonitorParms(EC_T_DWORD dwInstanceID, EC_T_MONITOR_INIT_PARMS *pParms, EC_T_DWORD dwParmsBufSize)

Gets current Monitor Init Parameters.

If the given buffer is larger than the actual size of struct EC_T_MONITOR_INIT_PARMS, the parameters of EC_T_MONITOR_INIT_PARMS.pOsParms, EC_T_MONITOR_INIT_PARMS.pLinkParms are appended.

Parameters

• dwInstanceID – [in] Instance ID

• pParms – [out] Buffer to store parameters

• dwParmsBufSize – [in] Size of buffer in bytes

Returns

• EC_E_NOERROR on success

• EC_E_INVALIDSTATE if Monitor isn’t initialized

• EC_E_INVALIDPARM if buffer pParms is too small

Example

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

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

See also

emInitMonitor()

8.1.11. emSetMonitorParms

EC_T_DWORD emSetMonitorParms(EC_T_DWORD dwInstanceID, EC_T_MONITOR_INIT_PARMS *pParms)

Change Monitor Init Parameters.

OS parms, Main Link parms cannot be changed.

Parameters

• dwInstanceID – [in] Instance ID

• pParms – [in] New Monitor init parameters

Returns

• EC_E_NOERROR on success

• EC_E_INVALIDSTATE if Monitor isn’t initialized

See also

emInitMonitor()

8.1.12. emGetVersion

EC_T_DWORD emGetVersion(EC_T_DWORD dwInstanceID, EC_T_DWORD *pdwVersion)

Gets the version number as a 32-bit value.

Parameters

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

• pdwVersion – [out] Pointer to EC_T_DWORD to carry out version number

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if master isn’t initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range or the output pointer is EC_NULL

8.1.13. emGetText

const EC_T_CHAR *emGetText(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

Since the texts are instance independent, a variant without instance id is also available:

const EC_T_CHAR *ecatGetText(EC_T_DWORD dwTextId)

8.1.14. emGetMemoryUsage

EC_T_DWORD emGetMemoryUsage(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

8.1.15. emGetMasterState

EC_T_STATE emGetMasterState(EC_T_DWORD dwInstanceID)

Get the EtherCAT master current state.

Parameters

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

Returns

EtherCAT master state

enum EC_T_STATE

Values:

enumerator eEcatState_UNKNOWN

enumerator eEcatState_INIT

enumerator eEcatState_PREOP

enumerator eEcatState_SAFEOP

enumerator eEcatState_OP

enumerator eEcatState_BOOTSTRAP

8.1.16. emGetMasterStateEx

EC_T_DWORD emGetMasterStateEx(EC_T_DWORD dwInstanceID, EC_T_WORD *pwCurrState, EC_T_WORD *pwReqState)

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

• DEVICE_STATE_UNKNOWN

• DEVICE_STATE_INIT

• DEVICE_STATE_PREOP

• DEVICE_STATE_SAFEOP

• DEVICE_STATE_OP

Parameters

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

• pwCurrState – [out] Current master state.

• pwReqState – [out] Requested master state

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if master isn’t initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range or the output pointers are EC_NULL

Limitation

Since it is not possible to determine the actual requested master state, the highest slave state of all slaves is assumed to be the requested master state.

8.1.17. emFindInpVarByName - “Inputs.DevicesState”

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

EC_T_DWORD emFindInpVarByName(EC_T_DWORD dwInstanceID, const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO *pProcessVarInfoEntry)

8.1.18. emFindInpVarByName - “Inputs.BusTime”

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

EC_T_DWORD emFindInpVarByName(EC_T_DWORD dwInstanceID, const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO *pProcessVarInfoEntry)

8.1.19. emIoControl

With emIoControl a generic control interface exists between the application and the EC-Monitor and its Link Layers.

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

8.1.20. emIoControl - EC_IOCTL_REGISTER_CYCFRAME_RX_CB

This function call registers an callback function which is called after the cyclic frame is received. Typically this is used when the Link Layer 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 emInitMonitor() before starting the job task.

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

Return

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

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

8.1.21. emIoControl - EC_IOCTL_GET_CYCLIC_CONFIG_INFO

Get cyclic configuration details from ENI configuration file.

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

Return

EC_E_NOERROR or error code

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

EC_T_DWORD dwPriority

[out] Priority of selected cyclic entry

EC_T_DWORD dwCycleTime

[out] Cycle time of selected cyclic entry

8.1.22. emIoControl - EC_IOCTL_IS_SLAVETOSLAVE_COMM_CONFIGURED

Determine if any slave-to-slave communication is configured.

emIoControl - EC_IOCTL_IS_SLAVETOSLAVE_COMM_CONFIGURED

Parameter

• pbyInBuf: [in] Should be set to EC_NULL

• dwInBufSize: [in] Should be set to 0

• pbyOutBuf: [out] Pointer to EC_T_DWORD. If value is EC_TRUE slave-to-slave communication is configured, if EC_FALSE it is not.

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

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

Return

EC_E_NOERROR or error code