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

See also

• emNotify - EC_NOTIFY_STATUS_SLAVE_ERROR

• emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO

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 / EtherCAT Master does not respond anymore

The EC_E_BUSY return status value indicates that a previously requested operation is still in progress. For example if the master is requested to enter the OPERATIONAL state the next request from the API will return this status value unless the OPERATIONAL state is entered.

6.2. Multiple EtherCAT Bus Support

6.2.1. Licensing

Multiple EtherCAT Bus support is included within the Class B and Class A master stack. For each bus a separate runtime license is required. A single runtime allows the usage of the multi instance functions only with an instance identifier of 0.

6.2.2. Overview

The acontis EtherCAT master allows controlling more than one EtherCAT bus within one application process. For this use case the master core is instantiated several times by using the multi instance API functions inside the application. Each API function is available as a single instance version (prefix ecat, e.g. ecatInitMaster()) and a multi instance version (prefix em, e.g. emInitMaster()). The first parameter of all multi instance functions emXxx() is the instance identifier. The single instance functions ecatXxx() will use the first master core instance with the identifier 0. The maximum number of supported instances is 12 (MAX_NUMOF_MASTER_INSTANCES).

6.2.3. Example application

The application EcMasterDemoMulti demonstrates a client application which handles two master instances with the following configuration (el9800.xml):

• Master instance 0: One Beckhoff EtherCAT Evaluation Board EL9800

• Master instance 1: One Beckhoff EtherCAT Evaluation Board EL9800

Parameters for this application:

-winpcap 192.168.1.32 1 -f el9800.xml @ -winpcap 192.168.2.32 1 -f el9800.xml

6.3. General functions

6.3.1. emInitMaster

static EC_T_DWORD ecatInitMaster(EC_T_INIT_MASTER_PARMS *pParms)

EC_T_DWORD emInitMaster(EC_T_DWORD dwInstanceID, EC_T_INIT_MASTER_PARMS *pParms)

Initializes the EtherCAT master stack.

This function has to be called prior to calling any other functions of the EtherCAT master.

Parameters

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

• pParms – [in] Pointer to parameter definitions

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if master is already initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range or pParms is EC_NULL or contains some values out of range

• EC_E_SIGNATURE_MISMATCH if EC_T_INIT_MASTER_PARMS.dwSignature mismatch

• EC_E_NOTFOUND if the link layer cannot be found

• EC_E_FEATURE_DISABLED if a configured feature is not included in the license key

• EC_E_NOTSUPPORTED if a configured feature is not supported (e.g not compiled in the library)

• EC_E_LOCK_CREATE_FAILED if some lock (e.g mutex) cannot be created

• EC_E_NOMEMORY if some memory cannot be allocated

struct EC_T_INIT_MASTER_PARMS

Public Members

EC_T_DWORD dwSignature

[in] set to ATECAT_SIGNATURE

EC_T_DWORD dwSize

[in] set to sizeof(EC_T_INIT_MASTER_PARMS)

struct _EC_T_OS_PARMS *pOsParms

[in] OS layer parameters

struct _EC_T_LINK_PARMS *pLinkParms

[in] Link layer parameters

struct _EC_T_LINK_PARMS *pLinkParmsRed

[in] Link layer parameters for red device (cable redundancy)

EC_T_DWORD dwBusCycleTimeUsec

[in] [usec] bus cycle time in microseconds

EC_T_DWORD dwMaxBusSlaves

[in] maximum pre-allocated bus slave objects

EC_T_DWORD dwMaxAcycFramesQueued

[in] maximum queued acyclic frames

EC_T_DWORD dwAdditionalEoEEndpoints

[in] additional EoE endpoints

EC_T_DWORD dwMaxAcycBytesPerCycle

[in] maximum bytes sent during eUsrJob_SendAcycFrames per cycle

EC_T_DWORD dwMaxAcycFramesPerCycle

[in] maximum frames sent during eUsrJob_SendAcycFrames per cycle

EC_T_DWORD dwMaxAcycCmdsPerCycle

[in] maximum commands sent during eUsrJob_SendAcycFrames per cycle

EC_T_DWORD dwMaxSlavesProcessedPerCycle

[in] maximum slave-related state machine calls per cycle

EC_T_DWORD dwEcatCmdMaxRetries

[in] maximum retries to send pending ethercat command frames

EC_T_DWORD dwEcatCmdTimeout

[in] timeout to send pending ethercat command frames

EC_T_BOOL bVLANEnable

[in] E=enable (1/0)

EC_T_WORD wVLANId

[in] I=VLAN Id (12Bit)

EC_T_BYTE byVLANPrio

[in] P=Prio (3Bit)

EC_T_LOG_PARMS LogParms

[in] Logging parameters

EC_T_MASTER_RED_PARMS MasterRedParms

[in] Master Redundancy parameters

EC_T_DWORD dwMaxS2SMbxSize

[in] Size of the queued S2S mailbox in bytes

EC_T_DWORD dwMaxQueuedS2SMbxTfer

[in] S2S Fifo number of entries

EC_T_WORD wMaxSlavesProcessedPerBusScanStep

[in] maximum slave-related calls per cycle during bus scans

EC_T_BOOL bApiLockByApp

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

EC_T_PERF_MEAS_INTERNAL_PARMS PerfMeasInternalParms

[in] Internal performance measurement parameters

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

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

Log messages are passed from the EC-Master 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-Master 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] – Context pointer

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.3.2. emDeinitMaster

static EC_T_DWORD ecatDeinitMaster(EC_T_VOID)

EC_T_DWORD emDeinitMaster(EC_T_DWORD dwInstanceID)

Terminates the EtherCAT master and releases all resources.

Returns

EC_E_NOERROR or error code

6.3.3. emGetMasterParms

static EC_T_DWORD ecatGetMasterParms(EC_T_INIT_MASTER_PARMS *pParms, EC_T_DWORD dwParmsBufSize)

EC_T_DWORD emGetMasterParms(EC_T_DWORD dwInstanceID, EC_T_INIT_MASTER_PARMS *pParms, EC_T_DWORD dwParmsBufSize)

Get current Master initialization parameters.

If the given buffer is larger than the actual size of structure EC_T_INIT_MASTER_PARMS, the parameters of EC_T_INIT_MASTER_PARMS.pOsParms, EC_T_INIT_MASTER_PARMS.pLinkParms and EC_T_INIT_MASTER_PARMS.pLinkParmsRed are appended.

Parameters

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

• pParms – [out] Buffer to store Master parameters

• dwParmsBufSize – [in] Size of Master parameters buffer

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 or dwParmsBufSize is too small

Example

/* Read all master init parameters, including OS, Main- and Red-Link parameters */
EC_T_BYTE abyBuffer[sizeof(EC_T_INIT_MASTER_PARMS) + sizeof(EC_T_OS_PARMS) + 512 /* LinkLayer parameters */];
EC_T_INIT_MASTER_PARMS* pParms = (EC_T_INIT_MASTER_PARMS*)abyBuffer;

dwRes = emGetMasterParms(dwInstanceId, pParms, sizeof(abyBuffer));

See also

emInitMaster()

6.3.4. emSetMasterParms

static EC_T_DWORD ecatSetMasterParms(EC_T_INIT_MASTER_PARMS *pParms)

EC_T_DWORD emSetMasterParms(EC_T_DWORD dwInstanceID, EC_T_INIT_MASTER_PARMS *pParms)

Change Master initialization parameters.

Currently the following parameters cannot be changed:

• EC_T_INIT_MASTER_PARMS.pOsParms

• EC_T_INIT_MASTER_PARMS.pLinkParms

• EC_T_INIT_MASTER_PARMS.pLinkParmsRed

• EC_T_INIT_MASTER_PARMS.dwMaxBusSlaves

• EC_T_INIT_MASTER_PARMS.dwMaxAcycFramesQueued

• EC_T_INIT_MASTER_PARMS.dwAdditionalEoEEndpoints

• EC_T_INIT_MASTER_PARMS.bVLANEnable

• EC_T_INIT_MASTER_PARMS.wVLANId

• EC_T_INIT_MASTER_PARMS.byVLANPrio

Parameters

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

• pParms – [in] New Master parameters

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if master isn’t initialized

See also

emInitMaster()

6.3.5. emScanBus

static EC_T_DWORD ecatScanBus(EC_T_DWORD dwTimeout)

EC_T_DWORD emScanBus(EC_T_DWORD dwInstanceID, EC_T_DWORD dwTimeout)

Scans all connected slaves.

Scans all connected slaves connected to EC-Master. If a configuration has been loaded, a validation between the configuration and the connected slaves is done. This function should not be called from within the JobTask’s context.

Parameters

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

• dwTimeout – [in] Timeout [ms]

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_LINK_DISCONNECTED if link is disconnected

• EC_E_TIMEOUT if dwTimeout elapsed during the API call

• EC_E_BUSCONFIG_MISMATCH if the slaves found are not matching the configured ones

• EC_E_LINE_CROSSED if a line crossed (cabling wrong) condition has been detected

• EC_E_REDLINEBREAK if cable redundancy is configured and a line break condition has been detected

• EC_E_JUNCTION_RED_LINE_BREAK if junction redundancy is configured and a line break condition has been detected

• EC_E_MAX_BUS_SLAVES_EXCEEDED if the amount of slaves found exceeds EC_T_INIT_MASTER_PARMS.dwMaxBusSlaves

• EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

• EC_E_ADS_IS_RUNNING if ADS server is running

See also

• EtherCAT Bus Scan

6.3.6. emRescueScan

static EC_T_DWORD ecatRescueScan(EC_T_DWORD dwTimeout)

EC_T_DWORD emRescueScan(EC_T_DWORD dwInstanceID, EC_T_DWORD dwTimeout)

Recovers the bus from permanent frame loss situations.

Scans all connected slaves. Closes and open ports on the network to rule out slaves which permanently discard frames. The Master notifies every slave port which permanently discard frames with EC_NOTIFY_FRAMELOSS_AFTER_SLAVE. Due to port opening and closing the scanning time is increased about 2 seconds per slave. The Master will not automatically re-open this port. The application can force to open the port again. This function may not be called from within the JobTask’s context.

Parameters

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

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

See also

• emSetSlavePortState()

• emNotify - EC_NOTIFY_FRAMELOSS_AFTER_SLAVE

6.3.7. emConfigureMaster

static EC_T_DWORD ecatConfigureMaster(EC_T_CNF_TYPE eCnfType, EC_T_PBYTE pbyCnfData, EC_T_DWORD dwCnfDataLen)

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

Configure the Master.

This function must be called after the master has been initialized. 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 if successful

• EC_E_INVALIDSTATE if master isn’t initialized or eCnfType is eCnfType_GenPreopENI or eCnfType_GenOpENI and link is disconnected

• EC_E_INVALIDPARM if dwInstanceID is out of range or pParms is EC_NULL contains some values out of range

• EC_E_LINK_DISCONNECTED if link is disconnected

• EC_E_FEATURE_DISABLED if a configured feature is not included in the license key

• EC_E_NOTSUPPORTED if a configured feature is not supported (e.g not compiled in the library)

• EC_E_CFGFILENOTFOUND if the ENI file cannot be found

• EC_E_WRONG_FORMAT if some format error have been detected in the ENI

• EC_E_OEM_SIGNATURE_MISMATCH if the OEM signature in the ENI file doesn’t match the used OEM key

• EC_E_ENI_ENCRYPTION_WRONG_VERSION if the ENI encryption version is not supported (e.g. the library is too old)

• EC_E_ENI_ENCRYPTED if the ENI is encrypted and no OEM key has been set

• EC_E_XML_CYCCMDS_MISSING if the ENI doesn’t contain cyclic commands

• EC_E_XML_ALSTATUS_READ_MISSING if the ENI doesn’t contain any read AL status command

• EC_E_XML_CYCCMDS_SIZEMISMATCH if the size of the cyclic commands in the ENI mismatch

• EC_E_XML_INVALID_INP_OFF if some input offset in the ENI are invalid

• EC_E_XML_INVALID_OUT_OFF if some output offset in the ENI are invalid

• EC_E_XML_INVALID_CMD_WITH_RED if the ENI contains LRW commands and cable redundancy is configured

• EC_E_XML_PREV_PORT_MISSING if some previous port information are missing in the ENI

• EC_E_XML_DC_CYCCMDS_MISSING if the DC related cyclic commands are missing in the ENI

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

enumerator eCnfType_None

Reset configuration

enumerator eCnfType_ConfigData

pbyCnfData: Binary structured configuration

Depending on this enum pbyCnfData is interpreted differently. This function may not be called from within the JobTask’s context.

6.3.8. emConfigGet

static EC_T_DWORD ecatConfigGet(EC_T_BYTE **ppbyCnfData, EC_T_DWORD *pdwCnfDataLen)

EC_T_DWORD emConfigGet(EC_T_DWORD dwInstanceID, EC_T_BYTE **ppbyCnfData, EC_T_DWORD *pdwCnfDataLen)

Get the master configuration.

This function returns the result of ENI parsing in binary format. This data can be stored at a different location (e.g. read only flash). Later on, the Master can be configured without ENI using the type EC_T_CNF_TYPE::eCnfType_ConfigData.

Note

The binary format is not version independent and the data becomes invalid, when used with a different version. The returned pointer is valid as long as the Master is initialized and no other configuration was loaded.

Parameters

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

• ppbyCnfData – [out] Configuration data

• pdwCnfDataLen – [out] Length of configuration data in byte

Returns

EC_E_NOERROR or error code

See also

emConfigureMaster()

6.3.9. emConfigExtend

Warning

Before using this function, please check if the following patents has to be taken into consideration for your application and use case: JP5212509:ADDRESS SETTING METHOD IN NETWORK SYSTEM

static EC_T_DWORD ecatConfigExtend(EC_T_BOOL bResetConfig, EC_T_DWORD dwTimeout)

EC_T_DWORD emConfigExtend(EC_T_DWORD dwInstanceID, EC_T_BOOL bResetConfig, EC_T_DWORD dwTimeout)

Extends the existing network configuration.

This function extends the existing configuration described in the ENI to allow mailbox communication with unexpected slaves. After this function was called, unexpected slaves can reach PREOP state. After the configuration was extended, disconnecting any slave will generate a bus mismatch, because all the slaves are part of the configuration. Recalling this function with bResetConfig set to EC_FALSE will extend the configuration again by any new connected unexpected slaves. The previous extension is not deleted. Calling the function with bResetConfig set to EC_TRUE, reset all the previous extensions.

Note

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

Parameters

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

• bResetConfig – [in] EC_TRUE: Extended configuration will be removed

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

6.3.10. emRegisterClient

static EC_T_DWORD ecatRegisterClient(EC_PF_NOTIFY pfnNotify, EC_T_VOID *pCallerData, EC_T_REGISTERRESULTS *pRegResults)

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.

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

static EC_T_DWORD ecatUnregisterClient(EC_T_DWORD dwClntId)

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

6.3.12. emGetSrcMacAddress

static EC_T_DWORD ecatGetSrcMacAddress(ETHERNET_ADDRESS *pMacSrc)

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_INIT_MASTER_PARMS::pLinkParms

6.3.13. emSetMasterState

static EC_T_DWORD ecatSetMasterState(EC_T_DWORD dwTimeout, EC_T_STATE eReqState)

EC_T_DWORD emSetMasterState(EC_T_DWORD dwInstanceID, EC_T_DWORD dwTimeout, EC_T_STATE eReqState)

Set the EtherCAT master (and all slaves) into the requested state.

If the function is called with EC_NOWAIT, the client may wait for reaching the requested state using the notification callback (EC_NOTIFY_STATECHANGED).

Master by default will just change to a higher state, if all slaves have reached the requested state. It may happen that some slaves are in higher state at network than Master, e.g.:

• Master and all slaves are in PREOP

• Application requests SAFEOP

• Master starts transition for all slaves

• Some slaves changed to SAFEOP, but some fail and therefore stay in PREOP

• Master state stays in PREOP, function returns with error

The application can request SAFEOP again to re-request state of previously failed slaves. Transition to lower state: The master changes to lower state, even if one slave is not able to follow. This function may not be called from within the JobTask’s context with dwTimeout other than EC_NOWAIT.

Parameters

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

• dwTimeout – [in] Timeout [ms] This function will block until the requested state is reached or the timeout elapsed. If the timeout value is set to EC_NOWAIT the function will return immediately.

• eReqState – [in] Requested System 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 pointer is EC_NULL

• EC_E_TIMEOUT if dwTimeout elapsed during the API call

• EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

• EC_E_ADS_IS_RUNNING if ADS server is running

enum EC_T_STATE

Values:

enumerator eEcatState_UNKNOWN

Unknown state

enumerator eEcatState_INIT

EtherCAT state INIT

enumerator eEcatState_PREOP

EtherCAT state PREOP (pre-operational)

enumerator eEcatState_SAFEOP

EtherCAT state SAFEOP (safe operational)

enumerator eEcatState_OP

EtherCAT state OP (operational)

enumerator eEcatState_BOOTSTRAP

EtherCAT state BOOTSTRAP

See also

emIoControl - EC_IOCTL_ALL_SLAVES_MUST_REACH_MASTER_STATE

6.3.14. emGetMasterState

static EC_T_STATE ecatGetMasterState(EC_T_VOID)

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

6.3.15. emGetMasterStateEx

static EC_T_DWORD ecatGetMasterStateEx(EC_T_WORD *pwCurrState, EC_T_WORD *pwReqState)

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

6.3.16. emStart

static EC_T_DWORD ecatStart(EC_T_DWORD dwTimeout)

EC_T_DWORD emStart(EC_T_DWORD dwInstanceID, EC_T_DWORD dwTimeout)

The EtherCAT master and all slaves will be set into the OPERATIONAL state.

Deprecated:

Use emSetMasterState() instead

Note

If the function is called with EC_NOWAIT, the client may wait for reaching the OPERATIONAL state using the notification callback (EC_NOTIFY_STATECHANGED). This function may not be called from within the JobTask’s context.

Parameters

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

• dwTimeout – [in] Timeout [ms] This function will block until the OPERATIONAL state is reached or the timeout elapsed. If the timeout value is set to EC_NOWAIT the function will return immediately.

Returns

EC_E_NOERROR or error code

6.3.17. emStop

static EC_T_DWORD ecatStop(EC_T_DWORD dwTimeout)

EC_T_DWORD emStop(EC_T_DWORD dwInstanceID, EC_T_DWORD dwTimeout)

The EtherCAT master and all slaves will be set back into the INIT state.

Deprecated:

Use emSetMasterState() instead

Note

If the function is called with EC_NOWAIT, the client may wait for reaching the INIT state using the notification callback (ECAT_NOTIFY_STATECHANGE). This function may not be called from within the JobTask’s context.

Parameters

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

• dwTimeout – [in] Timeout [ms] This function will block until the INIT state is reached or the timeout elapsed. If the timeout value is set to EC_NOWAIT the function will return immediately.

Returns

EC_E_NOERROR or error code

6.3.18. emExecJob

static EC_T_DWORD ecatExecJob(EC_T_USER_JOB eUserJob, EC_T_USER_JOB_PARMS *pUserJobParms)

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_SendAllCycFrames

   Send all cyclic frames. New values will be written to the EtherCAT slave’s outputs and new input values will be received. If the Link Layer operates in interrupt mode, the process data input values will be updated immediately after receiving the frames. If the Link Layer operates in polling mode, the next call to emExecJob() with the eUsrJob_ProcessAllRxFrames job will check for received frames and update the process data input values.

   pUserJobParms->dwNumFramesSent
   

   Indicates number of frames send within this call. Not used if pUserJobParms set to EC_NULL.

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

   In case not all previously initiated cyclic frames are processed when calling this function an error notification will be generated ( emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR).

3. eUsrJob_SendAcycFrames

   Acyclic EtherCAT datagrams stored in the acyclic frame buffer FIFO will be sent when executing this call.

   pUserJobParms->dwNumFramesSent
   

   Indicates number of frames send within this call. Not used if pUserJobParms set to EC_NULL.

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

4. eUsrJob_MasterTimer

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

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

5. eUsrJob_SendCycFramesByTaskId

   Send cyclic frames related to a specific task id. If more than one cyclic entries are configured this user job can be used to send the appropriate cyclic frames. All frames stored in cyclic entries with the given task id will be sent.

   See also

   Multiple cyclic entries configuration

   pUserJobParms->SendCycFramesByTaskId.dwTaskId
   

   Task id.

   Return: EC_E_NOERROR if successful, error code in case of failures. If not all previously initiated cyclic frames for the same task are already processed when calling this function an error will be generated ( emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR).

6. eUsrJob_ProcessRxFramesByTaskId

   eUsrJob_ProcessAcycRxFrames

   See also

   Feature-Pack Split Frame Processing

7. eUsrJob_SwitchEoeFrames

   This job must be called if emIoControl - EC_IOCTL_SET_EOE_DEFFERED_SWITCHING_ENABLED has been called before. It can be called in parallel to Send / Process jobs in a lower prioritized task

   pUserJobParms->SwitchEoeFrames.dwMaxPortsToProcess
   

   Indicates number of ports to be processed within this call. If zero, all ports will be processed.

   pUserJobParms->SwitchEoeFrames.dwNumFramesProcessed
   

   Returns number of frames processed within this call.

   Return: EC_E_NOERROR if successful

6.3.19. emGetVersion

static EC_T_DWORD ecatGetVersion(EC_T_DWORD *pdwVersion)

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

6.3.20. emSetLicenseKey

static EC_T_DWORD ecatSetLicenseKey(const EC_T_CHAR *pszLicenseKey)

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");

See also

• emInitMaster()

• emConfigureMaster()

6.3.21. emSetOemKey

static EC_T_DWORD ecatSetOemKey(EC_T_UINT64 qwOemKey)

static EC_T_DWORD emSetOemKey(EC_T_DWORD dwInstanceID, EC_T_UINT64 qwOemKey)

Provide OEM Key needed for OEM Masters to parse ENI files and provide access via RAS. Must be called after initialization and before configuration.

Parameters

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

• qwOemKey – [in] 64 bit OEM key

Example

dwRes = emSetOemKey(dwInstanceId, 0x1234567812345678);

See also

• emInitMaster()

• emConfigureMaster()

6.3.22. emIoControl

static EC_T_DWORD ecatIoControl(EC_T_DWORD dwCode, EC_T_IOCTLPARMS *pParms)

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

A generic control interface between the application, the EC-Master and its Link Layers.

Parameters

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

• dwCode – [in] Control code

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

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if master isn’t initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range, the input pointer is EC_NULL or contains EC_NULL pointer

• EC_E_NOMEMORY if some memory cannot be allocated

• EC_E_ADS_IS_RUNNING if ADS server is running

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

Queries the master for the necessary size the process data image has got. This information may be used to provide process data image storage from outside the master core. This IOCTL is to be called after emConfigureMaster() and before emStart().

emIoControl - 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 (type: EC_T_MEMREQ_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_MEMREQ_DESC

6.3.24. emIoControl - EC_IOCTL_REGISTER_PDMEMORYPROVIDER

This function call registers an external memory provider to the EtherCAT master, this memory will be used to store process data. If no memory provider is registered the master will internally allocate the necessary amount of memory. The function emIoControl - EC_IOCTL_GET_PDMEMORYSIZE should be executed to determine the amount of memory the master needs to store process data values. The external memory provider may additionally supply some hooks to give the master a possibility to synchronize memory access with the application. The memory provider has to be registered after calling emConfigureMaster() but prior to registering any client. Every client that registers with the master ( emRegisterClient() ) will get back the memory pointers to PDOut/PDIn data registered within this call.

emIoControl - EC_IOCTL_REGISTER_PDMEMORYPROVIDER

Parameter

• pbyInBuf: [in] Memory provider (EC_T_MEMPROV_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

Return

EC_E_NOERROR or error code

struct EC_T_MEMPROV_DESC

Public Members

EC_T_PVOID pvContext

Context pointer. This pointer is used every time when one of the callback functions (e.g. pfPDOutReadRequest) is called

EC_T_PBYTE pbyPDOutData

Pointer to the fixed output process data buffer (values transferred from the master to the slaves). A value of EC_NULL may be given in case the pointer will be provided later when function EC_T_MEMPROV_DESC.pfPDOutDataReadRequest is called

EC_T_DWORD dwPDOutDataLength

Length of the output process data buffer

EC_T_PBYTE pbyPDInData

Pointer to the fixed input process data buffer (values transferred from the slaves to the master). A value of EC_NULL may be given in case the pointer will be provided later when function EC_T_MEMPROV_DESC.pfPDInDataWriteRequest is called

EC_T_DWORD dwPDInDataLength

Length of the output process data buffer

EC_T_PFMEMREQ pfPDOutDataReadRequest

This function will be called cyclically within the process data transfer cycle prior to read data from the output process data buffer. If EC_NULL is set, the fixed buffer EC_T_MEMPROV_DESC.pbyPDOutData is used.

EC_T_PFMEMREL pfPDOutDataReadRelease

This function will be called cyclically within the process data transfer cycle after all data were read from the output process data buffer.

EC_T_PFMEMREQ pfPDOutDataWriteRequest

This function will be called cyclically within the process data transfer cycle prior to write new data into the output process data buffer. If EC_NULL is set, the fixed buffer EC_T_MEMPROV_DESC.pbyPDOutData is used.

EC_T_PFMEMREL pfPDOutDataWriteRelease

This function will be called cyclically within the process data transfer cycle after all data were written into the output process data buffer.

EC_T_PFMEMREQ pfPDInDataWriteRequest

This function will be called cyclically within the process data transfer cycle prior to write new data into the input process data buffer. If EC_NULL is set, the fixed buffer EC_T_MEMPROV_DESC.pbyPDInData is used.

EC_T_PFMEMREL pfPDInDataWriteRelease

This function will be called cyclically within the process data transfer cycle after all data were written into the input process data buffer.

EC_T_PBYTE pbyMasterRedPDOutData

Pointer to the MasterRed output process data buffer (ACTIVE to INACTIVE)

EC_T_DWORD dwMasterRedPDOutDataLength

Length of the MasterRed output process data buffer

EC_T_PBYTE pbyMasterRedPDInData

Pointer to the default input process data buffer (INACTIVE to ACTIVE)

EC_T_DWORD dwMasterRedPDInDataLength

Length of the input process data buffer

EC_T_PFMEMREQ pfMasterRedPDOutReadRequest

This function will be called within the process data transfer cycle prior to read data.

EC_T_PFMEMREL pfMasterRedPDOutReadRelease

This function will be called after all data was read from output process data buffer.

EC_T_PFMEMREQ pfMasterRedPDOutWriteRequest

This function will be called within the process data transfer cycle prior to read data.

EC_T_PFMEMREL pfMasterRedPDOutWriteRelease

This function will be called after all data was read from output process data buffer.

EC_T_PFMEMREQ pfMasterRedPDInWriteRequest

This function will be called within the process data transfer cycle prior to write data.

EC_T_PFMEMREL pfMasterRedPDInWriteRelease

This function will be called after all data was written to input process data buffer.

EC_T_PFMEMREQ pfMasterRedPDInReadRequest

This function will be called within the process data transfer cycle prior to write data.

EC_T_PFMEMREL pfMasterRedPDInReadRelease

This function will be called after all data was written to input process data buffer.

typedef EC_T_VOID (*EC_T_PFMEMREQ)(EC_T_PVOID pvContext, EC_T_DWORD dwTaskId, EC_T_PBYTE *ppbyPDData)

Parameters

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

• dwTaskId – [in] Task id of cyclic data transfer. If TASKID_COMPLETE_PD is given, the function must return a complete output process data buffer which contains valid data for all cyclic tasks.

• ppbyPDData – [out] Pointer to the process data buffer to be used. If set to EC_NULL, the corresponding fixed buffer from EC_T_MEMPROV_DESC is used. The provided buffer size must correspond to the caller context.

typedef EC_T_VOID (*EC_T_PFMEMREL)(EC_T_PVOID pvContext, EC_T_DWORD dwTaskId)

Parameters

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

• dwTaskId – [in] Task id of cyclic data transfer.

See also

• emIoControl - EC_IOCTL_GET_PDMEMORYSIZE

• emConfigureMaster()

• emRegisterClient()

• Feature Pack “Master Redundancy”

6.3.25. 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 emInitMaster() 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] Context pointer. This pointer is used as parameter every time when the callback function is called.

6.3.26. emIoControl - EC_IOCTL_ISLINK_CONNECTED

Determine whether link between the EtherCAT master and the first slave is connected.

emIoControl - EC_IOCTL_ISLINK_CONNECTED

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 link is connected, 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

With Redundancy support enabled, EC_FALSE is only set if main and redundancy link are down.

6.3.27. emIoControl - EC_IOCTL_GET_LINKLAYER_MODE

This call allows the application to determine whether the LinkLayer 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.3.28. emIoControl - EC_IOCTL_GET_CYCLIC_CONFIG_INFO

Determine cyclic configuration details from ENI configuration file. It can be called only after calling ecatConfigureMaster() or emConfigureMaster()

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

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

6.3.30. emIoControl - EC_LINKIOCTL…

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

EC_T_DWORD dwCode = (EC_IOCTL_LINKLAYER_MAIN | EC_LINKIOCTL_GET_ETHERNET_ADDRESS);

6.3.31. emIoControl - EC_LINKIOCTL_GET_ETHERNET_ADDRESS

Provides MAC addresses of main or red line.

emIoControl - EC_LINKIOCTL_GET_ETHERNET_ADDRESS

Parameter

• pbyInBuf: [in] Should be set to EC_NULL

• dwInBufSize: [in] Should be set to 0

• pbyOutBuf: [out] Pointer to MAC address buffer (6 bytes).

• dwOutBufSize: [in] Size of the output buffer in bytes (at least 6).

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

Return

EC_E_NOERROR or error code

6.3.32. emIoControl - EC_LINKIOCTL_GET_SPEED

emIoControl - 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 Link Layer driver to 10/100/1000.

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

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

Return

EC_E_NOERROR or error code

6.3.33. emIoControl - EC_IOCTL_SET_CYCFRAME_LAYOUT

Set the cyclic frames layout.

emIoControl - EC_IOCTL_SET_CYCFRAME_LAYOUT

Parameter

• pbyInBuf: [in] Pointer to a EC_T_CYCFRAME_LAYOUT value containing the cyclic frame layout.

• 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

enum EC_T_CYCFRAME_LAYOUT

Values:

enumerator eCycFrameLayout_STANDARD

Layout according ENI with command add/reordering, no relationship to PD

enumerator eCycFrameLayout_DYNAMIC

Layout is dynamically modified to send as less as possible cyclic frames and commands

enumerator eCycFrameLayout_FIXED

Layout strictly match ENI, frame buffers and PD area overlapped

enumerator eCycFrameLayout_IN_DMA

Layout strictly match ENI, frame buffers and PD area overlapped, frame buffers in DMA

6.3.34. emIoControl - EC_IOCTL_SET_MASTER_DEFAULT_TIMEOUTS

Set master default timeouts.

emIoControl - EC_IOCTL_SET_MASTER_DEFAULT_TIMEOUTS

Parameter

• pbyInBuf: [in] Pointer to EC_T_MASTERDEFAULTTIMEOUTS_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

Return

EC_E_NOERROR or error code

struct EC_T_MASTERDEFAULTTIMEOUTS_DESC

Public Members

EC_T_DWORD dwMasterStateChange

Default state change timeout [ms], applied if emSetMasterState called with EC_NOWAIT.

EC_T_DWORD dwInitCmdRetry

Timeout [ms] between retry sending an init-command.

EC_T_DWORD dwMbxCmd

Timeout [ms] between retry sending an mailbox command

EC_T_DWORD dwMbxPolling

Mailbox polling cycle [ms]

EC_T_DWORD dwDcmInSync

Timeout [ms] to wait for DCM InSync in state change PREOP to SAFEOP

EC_T_WORD wInitCmd

Timeout [ms] to InitCmds if not specified in ENI

EC_T_DWORD dwSlaveIdentification

Timeout [ms] to wait for the reading of the slave identification

Setting a value of this descriptor to zero resets the default timeout value to the initial value.

See also

• emSetMasterState()

6.3.35. emIoControl - EC_IOCTL_SET_COPYINFO_IN_SENDCYCFRAMES

Set copy info processed in either SendCycFrames or in ProcessAllRxFrames.

emIoControl - EC_IOCTL_SET_COPYINFO_IN_SENDCYCFRAMES

Parameter

• pbyInBuf: [in] Pointer to EC_T_BOOL. EC_TRUE: SendCycFrames, EC_FALSE: ProcessAllRxFrames

• 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

Default: Set by ProcessAllRxFrames.

6.3.36. emIoControl - EC_IOCTL_SET_BUS_CYCLE_TIME

Set bus cycle time in usec master parameter without calling emInitMaster() again.

emIoControl - EC_IOCTL_SET_BUS_CYCLE_TIME

Parameter

• pbyInBuf: [in] Pointer to value of EC_T_DWORD. Value may not be 0!

• 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

Implicitly recalculates Order Timeout and EC_T_INIT_MASTER_PARMS::dwEcatCmdTimeout.

6.3.37. emIoControl - EC_IOCTL_ADDITIONAL_VARIABLES_FOR_SPECIFIC_DATA_TYPES

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

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

Return

EC_E_NOERROR or error code

Additional variables are added to the process image for the following data types:

• FSOE_4096

• FSOE_4098

• FSOE_4099

• FB Info 1

• FB Info 3

6.3.38. emIoControl - EC_IOCTL_SLV_ALIAS_ENABLE

Enables slave alias addressing for all slaves.

emIoControl - EC_IOCTL_SLV_ALIAS_ENABLE

Parameter

• pbyInBuf: [in] Should be set to EC_NULL

• dwInBufSize: [in] Should be set to 0

• pbyOutBuf: [out] Should be set to EC_NULL

• dwOutBufSize: [in] Should be set to 0

• pdwNumOutData: [out] Should be set to EC_NULL

Return

EC_E_NOERROR or error code

Important

All slaves need to have the correct alias address set! If in doubt, don’t use this IOCTL.

6.3.39. emIoControl - EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR

Set ignore inputs on WKC error

emIoControl - EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR

Parameter

• pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: inputs are ignored on WKC error.

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

• pbyOutBuf: [out] Should be set to EC_NULL

• dwOutBufSize: [in] Should be set to 0

• pdwNumOutData: [out] Should be set to EC_NULL

Return

EC_E_NOERROR or error code

Calling this IOCTL with EC_TRUE as parameter will ignore the inputs data of cyclic commands on WKC error. The default behavior will copy the input data if WKC is non zero and below the expected value. If WKC is not matching the expected value a notification emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR is generated and the application must consider this status for the current cycle.

6.3.40. emIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR

Set zero inputs on WKC error

emIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR

Parameter

• pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: inputs are set to zero on WKC error.

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

• pbyOutBuf: [out] Should be set to EC_NULL

• dwOutBufSize: [in] Should be set to 0

• pdwNumOutData: [out] Should be set to EC_NULL

Return

EC_E_NOERROR or error code

Calling this IOCTL with EC_TRUE as parameter will set the inputs data of cyclic commands to zero on WKC error. The default behavior will copy the input data if WKC is non zero and below the expected value. If WKC is not matching the expected value a notification emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR is generated and the application must consider this status for the current cycle.

6.3.41. emIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO

Set zero inputs on WKC is zero

emIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO

Parameter

• pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: inputs are set to zero on WKC is zero.

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

• pbyOutBuf: [out] Should be set to EC_NULL

• dwOutBufSize: [in] Should be set to 0

• pdwNumOutData: [out] Should be set to EC_NULL

Return

EC_E_NOERROR or error code

Calling this IOCTL with EC_TRUE as parameter will ignore the inputs data of cyclic commands on WKC error. At default behavior it will ignore the input data if WKC is zero, and keep the previous state.

6.3.42. emIoControl - EC_IOCTL_SET_GENENI_ASSIGN_EEPROM_BACK_TO_EM

Enable or disable creation of “assign EEPROM back to EM” InitCmd if ENI generated based on bus-scan result.

emIoControl - EC_IOCTL_SET_GENENI_ASSIGN_EEPROM_BACK_TO_EM

Parameter

• pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: generate InitCmd.

• 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

The ENI’s “assign EEPROM back to EM” InitCmd depends on the attribute “AssignToPdi” of the EEPROM tag in the slave’s description within the ESI file. Because this attribute is not reflected in the SII in the slave’s EEPROM, the Master cannot know its value and inserts for legacy reasons the InitCmd if not disabled using this IOCTL.

6.3.43. emIoControl - EC_IOCTL_SET_EOE_DEFFERED_SWITCHING_ENABLED

Enable or disable deferred EoE switching

emIoControl - EC_IOCTL_SET_EOE_DEFFERED_SWITCHING_ENABLED

Parameter

• pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: Deferred EoE switching enabled.

• 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

Enabling deffered EoE switching reduces the CPU load of JOB_ProcessAllRxFrames in case of EoE communication. eUsrJob_SwitchEoeFrames has to be called explicitely to switch the received EoE frames between the EoE slaves and EoE end point(s).

6.3.44. emIoControl - EC_IOCTL_SET_MAILBOX_POLLING_CYCLES

This call changes the mailbox polling cycles.

emIoControl - EC_IOCTL_SET_MAILBOX_POLLING_CYCLES

Parameter

• pbyInBuf: [in] Pointer to struct EC_T_SET_MAILBOX_POLLING_CYCLES_DESC

• dwInBufSize: [in] Size of the input buffer in bytes. E.g. sizeof(EC_T_SET_MAILBOX_POLLING_CYCLES_DESC)

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

Public Members

EC_T_DWORD dwSlaveId

[in] Slave Id

EC_T_WORD wCycles

[in] Number of cycles between polling [ms]

6.3.45. emIoControl - EC_IOCTL_SET_MASTER_MAX_STATE

This call sets maximal master state. emSetMasterState() returns with EC_E_INVALIDSTATE if the requested master state exceeds the maximal master state.

emIoControl - EC_IOCTL_SET_MASTER_MAX_STATE

Parameter

• pbyInBuf: [in] Pointer to value of EC_T_STATE

• dwInBufSize: [in] Size of the input buffer in bytes. E.g. sizeof(EC_T_STATE)

• 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

See also

enum EC_T_STATE

6.4. Process Data Access

6.4.1. emGetProcessData

static EC_T_DWORD ecatGetProcessData(EC_T_BOOL bOutputData, EC_T_DWORD dwOffset, EC_T_BYTE *pbyData, EC_T_DWORD dwLength, EC_T_DWORD dwTimeout)

EC_T_DWORD emGetProcessData(EC_T_DWORD dwInstanceID, EC_T_BOOL bOutputData, EC_T_DWORD dwOffset, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD dwTimeout)

Retrieve Process data synchronized.

If process data are required outside the cyclic master job task (which is calling ecatExecJob), direct access to the process data is not recommended as data consistency cannot be guaranteed. A call to this function will send a data read request to the master stack and then check every millisecond whether new data are provided. The master stack will provide new data after calling ecatExecJob(eUsrJob_ MasterTimer) within the job task. This function is usually only called remotely (using the Remote API).

Note

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

Parameters

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

• bOutputData – [in] EC_TRUE: read output data, EC_FALSE: read input data.

• dwOffset – [in] Byte offset in Process data to read from.

• pbyData – [out] Buffer receiving transfered data

• dwDataLen – [in] Buffer length [bytes]

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

6.4.2. emGetProcessDataBits

static EC_T_DWORD ecatGetProcessDataBits(EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_BYTE *pbyDataDst, EC_T_DWORD dwBitLengthDst, EC_T_DWORD dwTimeout)

EC_T_DWORD emGetProcessDataBits(EC_T_DWORD dwInstanceID, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_BYTE *pbyData, EC_T_DWORD dwDataBitLen, EC_T_DWORD dwTimeout)

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

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

Parameters

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

• bOutputData – [in] EC_TRUE: read output data, EC_FALSE: write input data.

• dwBitOffsetPd – [in] Bit offset in Process data image.

• pbyData – [out] Buffer receiving transfered data

• dwDataBitLen – [in] Buffer length [bit]

• dwTimeout – [in] Timeout [ms] The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

See also

emGetProcessData()

6.4.3. emSetProcessData

static EC_T_DWORD ecatSetProcessData(EC_T_BOOL bOutputData, EC_T_DWORD dwOffset, EC_T_BYTE *pbyData, EC_T_DWORD dwLength, EC_T_DWORD dwTimeout)

EC_T_DWORD emSetProcessData(EC_T_DWORD dwInstanceID, EC_T_BOOL bOutputData, EC_T_DWORD dwOffset, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD dwTimeout)

Write Process data synchronized.

If process data shall be set outside the cyclic master job task (which is calling ecatExecJob), direct access to the process data is not recommended as data consistency cannot be guaranteed. A call to this function will send a data write request to the master stack and then check every millisecond whether new data is written. The master stack will copy the data after calling ecatExecJob(eUsrJob_ MasterTimer) within the job task. This function is usually only called remotely (using the Remote API).

Note

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

Parameters

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

• bOutputData – [in] EC_TRUE: write output data, EC_FALSE: write input data.

• dwOffset – [in] Byte offset in Process data to write to.

• pbyData – [in] Buffer containing transfered data

• dwDataLen – [in] Buffer length [bytes]

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

6.4.4. emSetProcessDataBits

static EC_T_DWORD ecatSetProcessDataBits(EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_BYTE *pbyDataSrc, EC_T_DWORD dwBitLengthSrc, EC_T_DWORD dwTimeout)

EC_T_DWORD emSetProcessDataBits(EC_T_DWORD dwInstanceID, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_BYTE *pbyData, EC_T_DWORD dwDataBitLen, EC_T_DWORD dwTimeout)

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

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

Parameters

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

• bOutputData – [in] EC_TRUE: write output data, EC_FALSE: write input data.

• dwBitOffsetPd – [in] Bit offset in Process data image.

• pbyData – [in] Buffer containing transfered data

• dwDataBitLen – [in] Buffer length [bit]

• dwTimeout – [in] Timeout [ms] The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

See also

emSetProcessData()

6.4.5. emForceProcessDataBits

static EC_T_DWORD ecatForceProcessDataBits(EC_T_DWORD dwClientId, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_WORD wBitLength, EC_T_BYTE *pbyData, EC_T_DWORD dwTimeout)

EC_T_DWORD emForceProcessDataBits(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_WORD wDataBitLen, EC_T_BYTE *pbyData, EC_T_DWORD dwTimeout)

Force a specific number of bits from a given buffer to the process image with a bit offset.

All output data set by this API are overwriting the values set by the application. All input data set by this API are overwriting the values read from the slaves. Forcing will be terminated by calling the corresponding functions. This function may not be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified).

• bOutputData – [in] EC_TRUE: write output data, EC_FALSE: write input data.

• dwBitOffsetPd – [in] Bit offset in Process data image

• wDataBitLen – [in] Buffer length [bit]

• pbyData – [in] Buffer containing transfered data

• dwTimeout – [in] Timeout [ms] The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

See also

• emSetProcessData()

• emReleaseProcessDataBits()

• emReleaseAllProcessDataBits()

6.4.6. emReleaseProcessDataBits

static EC_T_DWORD ecatReleaseProcessDataBits(EC_T_DWORD dwClientId, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_WORD wBitLength, EC_T_DWORD dwTimeout)

EC_T_DWORD emReleaseProcessDataBits(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_WORD wBitLength, EC_T_DWORD dwTimeout)

Release previously forced process data.

• Forced output: Value set by application become valid again. Because forced process data bits are written directly into the process output image, the application has to update the process image with the required value, otherwise the forced value is still valid.

• Forced input: Value read from the slaves become valid again.

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

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified).

• bOutputData – [in] EC_TRUE: write output data, EC_FALSE: write input data

• dwBitOffsetPd – [in] Bit offset in Process data image

• wBitLength – [in] Number of bits that shall be written to the process image.

• dwTimeout – [in] Timeout [ms] The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

See also

• emSetProcessData()

• emForceProcessDataBits()

6.4.7. emReleaseAllProcessDataBits

static EC_T_DWORD ecatReleaseAllProcessDataBits(EC_T_DWORD dwClientId, EC_T_DWORD dwTimeout)

EC_T_DWORD emReleaseAllProcessDataBits(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTimeout)

Release all previously forced process data for a dedicated client.

• Forced output: Value set by application become valid again. Because forced process data bits are written directly into the process output image, the application has to update the process image with the required value, otherwise the forced value is still valid.

• Forced input: Value read from the slaves become valid again.

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

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified).

• dwTimeout – [in] Timeout [ms] The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

See also

• emSetProcessData()

• emForceProcessDataBits()

6.4.8. emGetProcessImageInputPtr

static EC_T_BYTE *ecatGetProcessImageInputPtr(EC_T_VOID)

EC_T_BYTE *emGetProcessImageInputPtr(EC_T_DWORD dwInstanceID)

Gets the process data input image pointer.

Parameters

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

Returns

Process data input image pointer

See also

• emConfigureMaster()

• emIoControl - EC_IOCTL_GET_PDMEMORYSIZE

• emIoControl - EC_IOCTL_REGISTER_PDMEMORYPROVIDER

• emExecJob() ( eUsrJob_ProcessAllRxFrames) in case of Polling Mode

6.4.9. emGetProcessImageOutputPtr

static EC_T_BYTE *ecatGetProcessImageOutputPtr(EC_T_VOID)

EC_T_BYTE *emGetProcessImageOutputPtr(EC_T_DWORD dwInstanceID)

Gets the process data output image pointer.

Parameters

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

Returns

Process data output image pointer

See also

• emConfigureMaster()

• emIoControl - EC_IOCTL_GET_PDMEMORYSIZE

• emIoControl - EC_IOCTL_REGISTER_PDMEMORYPROVIDER

• emExecJob() ( eUsrJob_SendAllCycFrames)

6.4.10. emGetDiagnosisImagePtr

static EC_T_BYTE *ecatGetDiagnosisImagePtr(EC_T_VOID)

EC_T_BYTE *emGetDiagnosisImagePtr(EC_T_DWORD dwInstanceID)

Gets the diagnosis image pointer.

Parameters

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

Returns

Diagnosis image pointer

6.4.11. emGetSlaveInpVarInfoNumOf

static EC_T_DWORD ecatGetSlaveInpVarInfoNumOf(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD *pwSlaveInpVarInfoNumOf)

EC_T_DWORD emGetSlaveInpVarInfoNumOf(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD *pwSlaveInpVarInfoNumOf)

Gets the number of input variables of a specific slave.

Parameters

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

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• pwSlaveInpVarInfoNumOf – [out] Number of found process variable entries

Returns

• EC_E_NOERROR 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_NOTFOUND if no slave matching bFixedAddressing / wSlaveAddress can be found

See also

• emGetSlaveInpVarInfo()

• emGetSlaveInpVarInfoEx()

6.4.12. emGetSlaveInpVarInfo

static EC_T_DWORD ecatGetSlaveInpVarInfo(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)

EC_T_DWORD emGetSlaveInpVarInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)

Gets the process variable information entries of an specific slave.

Parameters

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

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wNumOfVarsToRead – [in] Number process variable entries that have been stored in pSlaveProcVarInfoEntries

• pSlaveProcVarInfoEntries – [out] The read process variable information entries

• pwReadEntries – [out] The number of read process variable information entries

Returns

EC_E_NOERROR or error code

struct EC_T_PROCESS_VAR_INFO

Public Members

EC_T_CHAR szName[MAX_PROCESS_VAR_NAME_LEN]

[out] Name of the found process variable

EC_T_WORD wDataType

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

EC_T_WORD wFixedAddr

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

EC_T_INT nBitSize

[out] Size in bit of the found process variable

EC_T_INT nBitOffs

[out] Bit offset in the process data image

EC_T_BOOL bIsInputData

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

MAX_PROCESS_VAR_NAME_LEN

Maximum length of a process variable name: 71 characters

6.4.13. emGetSlaveInpVarInfoEx

static EC_T_DWORD ecatGetSlaveInpVarInfoEx(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO_EX *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)

EC_T_DWORD emGetSlaveInpVarInfoEx(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO_EX *pSlaveProcVarInfoEntriesEx, EC_T_WORD *pwReadEntries)

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

Parameters

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

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wNumOfVarsToRead – [in] Number process variable entries that have been stored in pSlaveProcVarInfoEntries

• pSlaveProcVarInfoEntriesEx – [out] The read process variable extended information entries

• pwReadEntries – [out] The number of read process variable information entries

Returns

• EC_E_NOERROR 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_NOTFOUND if no slave matching bFixedAddressing / wSlaveAddress can be found

struct EC_T_PROCESS_VAR_INFO_EX

Public Members

EC_T_CHAR szName[MAX_PROCESS_VAR_NAME_LEN_EX]

[out] Name of the found process variable

EC_T_WORD wDataType

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

EC_T_WORD wFixedAddr

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

EC_T_INT nBitSize

[out] Size in bit of the found process variable

EC_T_INT nBitOffs

[out] Bit offset in the process data image

EC_T_BOOL bIsInputData

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

EC_T_WORD wIndex

[out] Object index

EC_T_WORD wSubIndex

[out] Object sub index

EC_T_WORD wPdoIndex

[out] Index of PDO (process data object)

EC_T_WORD wWkcStateDiagOffs

[out] Bit offset in the diagnostic image (emGetDiagnosisImagePtr)

EC_T_WORD wMasterSyncUnit

[out] Master Sync Unit (ENI: RxPdo[1..4]@Su, TxPdo[1..4]@Su)

MAX_PROCESS_VAR_NAME_LEN_EX

Maximum length of a extended process variable name: 127 characters

6.4.14. emGetSlaveOutpVarInfoNumOf

static EC_T_DWORD ecatGetSlaveOutpVarInfoNumOf(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD *pwSlaveOutpVarInfoNumOf)

EC_T_DWORD emGetSlaveOutpVarInfoNumOf(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD *pwSlaveOutpVarInfoNumOf)

Gets the number of output variables of a specific slave.

Parameters

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

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• pwSlaveOutpVarInfoNumOf – [out] Number of found process variables

Returns

EC_E_NOERROR or error code

See also

• emGetSlaveOutpVarInfo()

• emGetSlaveOutpVarInfoEx()

6.4.15. emGetSlaveOutpVarInfo

static EC_T_DWORD ecatGetSlaveOutpVarInfo(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)

EC_T_DWORD emGetSlaveOutpVarInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)

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

Parameters

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

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wNumOfVarsToRead – [in] Number of found process variable entries

• pSlaveProcVarInfoEntries – [out] The read process variable information entries

• pwReadEntries – [out] The number of read process variable information entries

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO

6.4.16. emGetSlaveOutpVarInfoEx

static EC_T_DWORD ecatGetSlaveOutpVarInfoEx(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO_EX *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)

EC_T_DWORD emGetSlaveOutpVarInfoEx(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO_EX *pSlaveProcVarInfoEntriesEx, EC_T_WORD *pwReadEntries)

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

Parameters

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

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wNumOfVarsToRead – [in] Number of process variable information entries

• pSlaveProcVarInfoEntriesEx – [out] The read process extended variable entries

• pwReadEntries – [out] The number of read process variable information entries

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

6.4.17. emGetSlaveInpVarByObjectEx

static EC_T_DWORD ecatGetSlaveInpVarByObjectEx(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

EC_T_DWORD emGetSlaveInpVarByObjectEx(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

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

Parameters

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

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wIndex – [in] Object index

• wSubIndex – [in] Object sub index

• pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

6.4.18. emGetSlaveOutpVarByObjectEx

static EC_T_DWORD ecatGetSlaveOutpVarByObjectEx(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

EC_T_DWORD emGetSlaveOutpVarByObjectEx(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

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

Parameters

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

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wIndex – [in] Object index

• wSubIndex – [in] Object sub index

• pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

6.4.19. emFindInpVarByName

static EC_T_DWORD ecatFindInpVarByName(const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO *pProcessVarInfoEntry)

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

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

Parameters

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

• szVariableName – [in] Variable name

• pProcessVarInfoEntry – [out] Process variable information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO

6.4.20. emFindInpVarByNameEx

static EC_T_DWORD ecatFindInpVarByNameEx(const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

EC_T_DWORD emFindInpVarByNameEx(EC_T_DWORD dwInstanceID, const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

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

Parameters

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

• szVariableName – [in] Variable name

• pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

6.4.21. emFindOutpVarByName

static EC_T_DWORD ecatFindOutpVarByName(const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO *pProcessVarInfoEntry)

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

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

Parameters

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

• szVariableName – [in] Variable name

• pProcessVarInfoEntry – [out] Process variable information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO

6.4.22. emFindOutpVarByNameEx

static EC_T_DWORD ecatFindOutpVarByNameEx(const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

EC_T_DWORD emFindOutpVarByNameEx(EC_T_DWORD dwInstanceID, const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

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

Parameters

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

• szVariableName – [in] Variable name

• pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

6.4.23. emTraceDataConfig

static EC_T_DWORD ecatTraceDataConfig(EC_T_WORD wTraceDataSize)

EC_T_DWORD emTraceDataConfig(EC_T_DWORD dwInstanceID, EC_T_WORD wTraceDataSize)

Configures a trace data buffer and enables it for transmission.

Must be called after initialization and before configuration.

Note

If wTraceDataSize is too large, configuration will fail with return code EC_E_XML_CYCCMDS_SIZEMISMATCH.

Parameters

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

• wTraceDataSize – [in] Size of Trace Data in bytes

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_NOTSUPPORTED if eCycFrameLayout_FIXED is configured

6.4.24. emTraceDataGetInfo

static EC_T_DWORD ecatTraceDataGetInfo(EC_T_TRACE_DATA_INFO *pTraceDataInfo)

EC_T_DWORD emTraceDataGetInfo(EC_T_DWORD dwInstanceID, EC_T_TRACE_DATA_INFO *pTraceDataInfo)

Get information about the offset and size of trace data.

The trace data buffer is locate in EC_T_TRACE_DATA_INFO.pbyData at the byte offset EC_T_TRACE_DATA_INFO.dwOffset.

Parameters

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

• pTraceDataInfo – [out] Information about trace data

Returns

EC_E_NOERROR or error code

struct EC_T_TRACE_DATA_INFO

Public Members

EC_T_BYTE *pbyData

[out] Process data output buffer, containing trace data

EC_T_DWORD dwOffset

[out] Trace data offset in bytes

EC_T_WORD wSize

[out] Trace data size in bytes

6.4.25. EC_COPYBITS

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

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

Note

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

Parameters

• pbyDst – [out] Destination buffer

• nDstBitOffs – [in] Bit offset within destination buffer

• pbySrc – [in] Source buffer

• nSrcBitOffs – [in] Bit offset within source buffer

• nBitSize – [in] Block size in bits

See also

• EC_SETBITS

• EC_GETBITS

EC_T_BYTE pbySrc[] = {0xF4, 0xED, 0x69, 0xA5};
EC_T_BYTE pbyDst[] = {0x00, 0x00, 0x00, 0x00};
EC_COPYBITS(pbyDst, 3, pbySrc, 6, 22);

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

6.4.26. EC_GET_FRM_WORD

EC_GET_FRM_WORD(ptr)

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

Parameters

• ptr – [in] Source buffer

Returns

EC_T_WORD value (16 bit) from buffer.

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

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

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

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

6.4.27. EC_GET_FRM_DWORD

EC_GET_FRM_DWORD(ptr)

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

Parameters

• ptr – [in] Source buffer

Returns

EC_T_DWORD value (32 bit) from buffer.

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

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

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

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

6.4.28. EC_GET_FRM_QWORD

EC_GET_FRM_QWORD(ptr)

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

Parameters

• ptr – [in] Source buffer

Returns

EC_T_QWORD value (64 bit) from buffer.

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

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

6.4.29. EC_SET_FRM_WORD

EC_SET_FRM_WORD(ptr, w)

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

Parameters

• ptr – [in] Destination buffer

• w – [in] 16 bit value

EC_T_BYTE byFrame[32];

/* Initialize the frame buffer */
OsMemset(byFrame, 0xFF, 32);

EC_SET_FRM_WORD(byFrame + 1, 0x1234);
/* byFrame = FF 34 12 FF FF FF ... */

6.4.30. EC_SET_FRM_DWORD

EC_SET_FRM_DWORD(ptr, dw)

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

Parameters

• ptr – [in] Destination buffer

• dw – [in] 32 bit value

EC_T_BYTE byFrame[32];

/* Initialize the frame buffer */
OsMemset(byFrame, 0xFF, 32);

EC_SET_FRM_DWORD(byFrame + 1, 0x12345678);
/* byFrame = FF 78 56 34 12 FF ... */

6.4.31. EC_SET_FRM_QWORD

EC_SET_FRM_QWORD(ptr, qw)

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

Parameters

• ptr – [in] Destination buffer

• qw – [in] 64 bit value

EC_T_BYTE byFrame[32];

/* Initialize the frame buffer */
OsMemset(byFrame, 0xFF, 32);

EC_SET_FRM_QWORD(byFrame + 1, 0xFEDCBA9876543210);
/* byFrame = FF 10 32 54 76 98 BA DC FE FF FF ... */

6.4.32. EC_GETBITS

EC_GETBITS(pbySrcBuf, pbyDstData, nSrcBitOffs, nBitSize)

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

Note

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

Parameters

• pbySrcBuf – [in] Source buffer to be copied

• pbyDstData – [out] Destination buffer where data is copied to

• nSrcBitOffs – [in] Source bit offset where data is copied from

• nBitSize – [in] Bit count to be copied

See also

• EC_GET_FRM_WORD

• EC_GET_FRM_DWORD

• EC_GET_FRM_QWORD

6.4.33. EC_SETBITS

EC_SETBITS(pbyDstBuf, pbySrcData, nDstBitOffs, nBitSize)

Writes a given number of bits from source data starting at first bit to destination buffer at given bit offset.

Note

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

Parameters

• pbyDstBuf – [out] Destination buffer where data is copied to

• pbySrcData – [in] Source buffer to be copied, starting with first bit

• nDstBitOffs – [in] Destination bit offset where data is copied to

• nBitSize – [in] Bit count to be copied

See also

• EC_SET_FRM_WORD

• EC_SET_FRM_DWORD

• EC_SET_FRM_QWORD

6.5. Generic notification interface

One of the parameters the client has to set when registering with the EtherCAT master is a generic notification callback function ( emNotify()). The master calls this function every time a event (for example an error event) occurs about which the client has to be informed.

Within this callback function the client must not call any active EtherCAT functions which finally would lead to send EtherCAT commands (e.g. initiation of mailbox transfers, starting/stopping the master, sending raw commands). In such cases the behavior is undefined.

This callback function is usually called in the context of the EtherCAT master timer thread or the EtherCAT Link Layer receiver thread. It may also be called within the context of a user thread (when calling an EtherCAT master function). To avoid dead-lock situations the notification callback handler may not use mutex semaphores.

As the whole EtherCAT operation is blocked while calling this function the error handling must not use much CPU time or even call operating system functions that may block. Usually the error handling will be done in a separate application thread.

6.5.1. Notification callback: emNotify

When a client registers with the EtherCAT master the client has to determine a generic notification callback function. The master calls this function every time an event (for example an error event or operational state change event) occurs about which the client has to be informed. Within this callback function the client must not call any active EtherCAT functions which finally would lead to send EtherCAT commands (e.g. initiation of mailbox transfers, starting/stopping the master, sending raw commands). In such cases the behavior is undefined. Only EtherCAT functions which are explicitly marked to be callable within emNotify() may be called.

A further important rule exists due to the fact that this callback function is usually called in the context of the EtherCAT master timer thread. As the whole EtherCAT operation is blocked while calling this function the notification handler must not use much CPU time or even call operating system functions that may block. Time consuming operations should be executed in separate application threads.

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

struct EC_T_NOTIFYPARMS

Public Members

EC_T_VOID *pCallerData

[in] Client depending caller data parameter. This pointer is one of the parameters when the client registers

EC_T_BYTE *pbyInBuf

[in] Notification input parameters

EC_T_DWORD dwInBufSize

[in] Size of input buffer in byte

EC_T_BYTE *pbyOutBuf

[out] Notification output (result)

EC_T_DWORD dwOutBufSize

[in] Size of output buffer in byte

EC_T_DWORD *pdwNumOutData

[out] Amount of bytes written to the output buffer

6.5.2. emNotify - EC_NOTIFY_STATECHANGED

Notification about a change in the master’s operational state. This notification is enabled by default.

emNotify - EC_NOTIFY_STATECHANGED

Parameter

• pbyInBuf: [in] Pointer to data of type EC_T_STATECHANGE which contains the old and the new master operational state.

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

• pbyOutBuf: [out] Should be set to EC_NULL

• dwOutBufSize: [in] Should be set to 0

• pdwNumOutData: [out] Should be set to EC_NULL

struct EC_T_STATECHANGE

Public Members

EC_T_STATE oldState

old operational state

EC_T_STATE newState

new operational state

See also

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation

6.5.3. emNotify - EC_NOTIFY_XXXX

Notification about an error.

emNotify - EC_NOTIFY_XXXX

Parameter

• pbyInBuf: [in] Pointer to data of type EC_T_ERROR_NOTIFICATION_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

See also

Diagnosis, error detection, error notifications

6.5.4. Feature Pack Master Redundancy Notifcations

See also

Feature Pack “Master Redundancy”

6.5.5. emNotifyApp

By calling this function the generic notification callback function setup by emRegisterClient() is called for all clients including RAS.

static EC_T_DWORD ecatNotifyApp(EC_T_DWORD dwCode, EC_T_NOTIFYPARMS *pParms)

EC_T_DWORD emNotifyApp(EC_T_DWORD dwInstanceID, EC_T_DWORD dwCode, EC_T_NOTIFYPARMS *pParms)

Calls the notification callback functions of all registered clients.

Note

EC_E_ERROR and EC_E_INVALIDPARM from registered clients’ callback functions are ignored.

Parameters

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

• dwCode – [in] Application specific notification code. dwCode must be <= EC_NOTIFY_APP_MAX_CODE. The callback functions get “EC_NOTIFY_APP | dwCode” as parameter.

• pParms – [in] Parameter to all callback functions. Note: Output parameters are not transferred from RAS client to RAS server.

Returns

EC_E_ERROR or first error code different from EC_E_ERROR and EC_E_INVALIDPARM of registered clients’ callback functions

The maximum value for dwCode is defined by EC_NOTIFY_APP_MAX_CODE

6.5.6. emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED

The following notifications can be enabled or disabled.

• emNotify - EC_NOTIFY_SLAVE_STATECHANGED (default Off)

• emNotify - EC_NOTIFY_SLAVES_STATECHANGED (default Off)

• emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE (default On)

• emNotify - EC_NOTIFY_SLAVES_UNEXPECTED_STATE (default Off)

• emNotify - EC_NOTIFY_SLAVE_PRESENCE (default On)

• emNotify - EC_NOTIFY_SLAVES_PRESENCE (default Off)

• emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO (default On)

• emNotify - EC_NOTIFY_SLAVES_ERROR_STATUS (default Off)

• emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL (default On)

• emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR (default On)

• emNotify - EC_NOTIFY_SB_MISMATCH (default On)

• emNotify - EC_NOTIFY_SB_STATUS (default On)

• emNotify - EC_NOTIFY_STATUS_SLAVE_ERROR (default On)

• emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR (default On)

• emNotify - EC_NOTIFY_HC_TOPOCHGDONE (default On)

• emNotify - EC_NOTIFY_STATECHANGED (default On)

• emNotify - EC_NOTIFY_COE_INIT_CMD (default Off)

• EC_NOTIFY_JUNCTION_RED_CHANGE (default Off)

• emNotify - EC_NOTIFY_ALL_DEVICES_OPERATIONAL (default Off)

• EC_NOTIFY_DC_STATUS (default On)

• EC_NOTIFY_DC_SLV_SYNC (default On)

• EC_NOTIFY_DCM_SYNC (default On)

• emNotify - EC_NOTIFY_SLAVE_INITCMD_RESPONSE_ERROR (default On)

• EC_NOTIFY_REFCLOCK_PRESENCE (default Off)

• EC_NOTIFY_DCX_SYNC (default On)

• EC_NOTIFY_HC_DETECTADDGROUPS (default On)

• emNotify - EC_NOTIFY_FRAMELOSS_AFTER_SLAVE (default On)

• emNotify - EC_NOTIFY_ETH_LINK_NOT_CONNECTED (default On)

• emNotify - EC_NOTIFY_S2SMBX_ERROR (default On)

• emNotify - EC_NOTIFY_SLAVE_INITCMD_WKC_ERROR (default On)

• emNotify - EC_NOTIFY_BAD_CONNECTION (default On)

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED

Parameter

• pbyInBuf: [in] pointer to EC_T_SET_NOTIFICATION_ENABLED_PARMS.

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

Public Members

EC_T_DWORD dwClientId

[in] Client ID, 0: Master

EC_T_DWORD dwCode

[in] Notification code or EC_ALL_NOTIFICATIONS

EC_T_DWORD dwEnabled

[in] Enable, disable or reset to default notification. See EC_NOTIFICATION_ flags

Notifications are given to clients if enabled for dwClientId = 0 AND corresponding dwClientId.

6.5.7. emIoControl - EC_IOCTL_GET_NOTIFICATION_ENABLED

The enabled state of notifications can be retrieved using emIoControl - EC_IOCTL_GET_NOTIFICATION_ENABLED.

emIoControl - EC_IOCTL_GET_NOTIFICATION_ENABLED

Parameter

• pbyInBuf: [in] pointer to EC_T_GET_NOTIFICATION_ENABLED_PARMS.

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

• pbyOutBuf: [out] Pointer to EC_T_BOOL to carry out current enable set.

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

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

Return

EC_E_NOERROR or error code

struct EC_T_GET_NOTIFICATION_ENABLED_PARMS

Public Members

EC_T_DWORD dwClientId

[in] Client ID, 0: Master

EC_T_DWORD dwCode

[in] Notification code

See also

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED

6.6. Slave control and status functions

6.6.1. emGetNumConfiguredSlaves

static EC_T_DWORD ecatGetNumConfiguredSlaves(EC_T_VOID)

EC_T_DWORD emGetNumConfiguredSlaves(EC_T_DWORD dwInstanceID)

Returns number of slaves which are configured in the ENI.

Parameters

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

Returns

Number of slaves

6.6.2. emGetNumConnectedSlaves

static EC_T_DWORD ecatGetNumConnectedSlaves(EC_T_VOID)

EC_T_DWORD emGetNumConnectedSlaves(EC_T_DWORD dwInstanceID)

Get amount of currently connected slaves.

Parameters

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

Returns

Number of connected slaves

6.6.3. emGetSlaveId

static EC_T_DWORD ecatGetSlaveId(EC_T_WORD wStationAddress)

EC_T_DWORD emGetSlaveId(EC_T_DWORD dwInstanceID, EC_T_WORD wStationAddress)

Determines the slave ID using the slave station address.

Parameters

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

• wStationAddress – [in] Station address of the slave

Returns

Slave ID or INVALID_SLAVE_ID if the slave could not be found or stack is not initialized

6.6.4. emGetSlaveIdAtPosition

static EC_T_DWORD ecatGetSlaveIdAtPosition(EC_T_WORD wAutoIncAddress)

EC_T_DWORD emGetSlaveIdAtPosition(EC_T_DWORD dwInstanceID, EC_T_WORD wAutoIncAddress)

Determines the slave ID using the slave auto increment address.

Parameters

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

• wAutoIncAddress – [in] Auto increment address of the slave

Returns

Slave ID or INVALID_SLAVE_ID if no slave matching wAutoIncAddress can be found

6.6.5. emSetSlaveState

static EC_T_DWORD ecatSetSlaveState(EC_T_DWORD dwSlaveId, EC_T_WORD wNewReqDevState, EC_T_DWORD dwTimeout)

EC_T_DWORD emSetSlaveState(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_WORD wNewReqDevState, EC_T_DWORD dwTimeout)

Set a specified slave into the requested state.

The requested state shall not be higher than the overall operational state. DEVICE_STATE_BOOTSTRAP can only be requested if the slave’s state is INIT. This function may not be called from within the JobTask’s context.

Parameters

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

• dwSlaveId – [in] Slave ID

• wNewReqDevState – [in] Requested state

• dwTimeout – [in] Timeout [ms] May not be EC_NOWAIT!

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if master isn’t initialized or denies the requested state, see comments below

• EC_E_INVALIDPARM if dwInstanceID is out of range or BOOTSTRAP was requested for a slave that does not support it

• EC_E_NOTFOUND if no slave matching dwSlaveId can be found

• EC_E_TIMEOUT if dwTimeout elapsed during the API call

• EC_E_BUSY if the master cannot execute the request at this time, the function has to be called at a later time

• EC_E_NOTREADY if the working counter was not set when requesting the slave’s state (slave may not be connected or did not respond)

• EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

DEVICE_STATE_UNKNOWN

Slave in unknown state

DEVICE_STATE_INIT

Slave in INIT state

DEVICE_STATE_PREOP

Slave in PREOP state

DEVICE_STATE_BOOTSTRAP

Slave in BOOTSTRAP state

DEVICE_STATE_SAFEOP

Slave in SAFEOP state

DEVICE_STATE_OP

Slave in OP state

DEVICE_STATE_ERROR

Slave in error state

See also

emGetSlaveId()

6.6.6. emGetSlaveState

static EC_T_DWORD ecatGetSlaveState(EC_T_DWORD dwSlaveId, EC_T_WORD *pwCurrDevState, EC_T_WORD *pwReqDevState)

EC_T_DWORD emGetSlaveState(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_WORD *pwCurrDevState, EC_T_WORD *pwReqDevState)

Get the slave state.

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

Parameters

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

• dwSlaveId – [in] Slave ID

• pwCurrDevState – [out] Current slave state.

• pwReqDevState – [out] Requested slave state

Returns

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

• EC_E_SLAVE_NOT_PRESENT if slave not present.

• EC_E_NOTFOUND if no slave matching dwSlaveId can be found

See also

• emGetSlaveId()

• emSetSlaveState()

6.6.7. emIsSlavePresent

This function may be called from within the JobTask. Since Slave Id is a parameter, valid response only can be retrieved after calling emConfigureMaster().

static EC_T_DWORD ecatIsSlavePresent(EC_T_DWORD dwSlaveId, EC_T_BOOL *pbPresence)

EC_T_DWORD emIsSlavePresent(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_BOOL *pbPresence)

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

This function may be called from within the JobTask.

Parameters

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

• dwSlaveId – [in] Slave ID

• pbPresence – [out] EC_TRUE if slave is currently connected to the bus, EC_FALSE if not.

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_NOTFOUND if no slave matching dwSlaveId can be found

See also

emGetSlaveId()

6.6.8. emGetSlaveProp

static EC_T_BOOL ecatGetSlaveProp(EC_T_DWORD dwSlaveId, EC_T_SLAVE_PROP *pSlaveProp)

EC_T_BOOL emGetSlaveProp(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_SLAVE_PROP *pSlaveProp)

Determines the properties of the slave device.

Deprecated:

Use emGetCfgSlaveInfo instead

Parameters

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

• dwSlaveId – [in] Slave ID

• pSlaveProp – [out] Slave properties

Returns

EC_TRUE if the slave exists, EC_FALSE if no slave matching dwSlaveId can be found

See also

emGetSlaveId()

6.6.9. emSlaveSerializeMbxTfers

static EC_T_DWORD ecatSlaveSerializeMbxTfers(EC_T_DWORD dwSlaveId)

EC_T_DWORD emSlaveSerializeMbxTfers(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId)

Serializes all mailbox transfers to the specified slave.

The parallel (overlapped) usage of more than one protocol (CoE, EoE, FoE, etc.) will be disabled. By default parallel mailbox transfers are enabled.

Parameters

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

• dwSlaveId – [in] Slave ID

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_NOTFOUND if no slave matching dwSlaveId can be found

• EC_E_NO_MBX_SUPPORT if slave does not support mailbox transfers

See also

emGetSlaveId()

6.6.10. emSlaveParallelMbxTfers

static EC_T_DWORD ecatSlaveParallelMbxTfers(EC_T_DWORD dwSlaveId)

EC_T_DWORD emSlaveParallelMbxTfers(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId)

Re-enable the parallel mailbox transfers to the specified slave.

Allows parallel (overlapped) usage of more than one protocol (CoE, EoE, FoE, etc.). By default parallel mailbox transfers are enabled.

Parameters

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

• dwSlaveId – [in] Slave ID

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_NOTFOUND if no slave matching dwSlaveId can be found

• EC_E_NO_MBX_SUPPORT if slave does not support mailbox transfers

See also

emGetSlaveId()

6.6.11. emIoControl - EC_IOCTL_SET_MBX_RETRYACCESS_PERIOD

Sets the mailbox retry access period in milliseconds for a specific slave. If a slave rejects a mailbox access because of a busy state, the master restarts mailbox access after that period of time.

emIoControl - EC_IOCTL_SET_MBX_RETRYACCESS_PERIOD

Parameter

• pbyInBuf: [in] Pointer to a size 6 byte array. The first 4 bytes must contain the slave id (EC_T_DWORD), the last 2 bytes the new retry access period in milliseconds(EC_T_WORD).

• 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

By default, the retry access period is set to 25 milliseconds.

6.6.12. emNotify - EC_NOTIFY_SLAVE_STATECHANGED

This notification is given, when a slave changed its EtherCAT state. This notification is disabled by default.

emNotify - EC_NOTIFY_SLAVE_STATECHANGED

Parameter

• pbyInBuf: [in] Pointer to EC_T_SLAVE_STATECHANGED_NTFY_DESC

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

• pbyOutBuf: [out] Should be set to EC_NULL

• dwOutBufSize: [in] Should be set to 0

• pdwNumOutData: [out] Should be set to EC_NULL

struct EC_T_SLAVE_STATECHANGED_NTFY_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

EC_T_STATE newState

New slave state

See also

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the activation

6.6.13. emNotify - EC_NOTIFY_SLAVES_STATECHANGED

Collects emNotify - EC_NOTIFY_SLAVE_STATECHANGED

This notification is disabled by default.

See also

emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the activation

emNotify - EC_NOTIFY_SLAVES_STATECHANGED

Parameter

• pbyInBuf: [in] Pointer to EC_T_SLAVES_STATECHANGED_NTFY_DESC

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

• pbyOutBuf: [out] Should be set to EC_NULL

• dwOutBufSize: [in] Should be set to 0

• pdwNumOutData: [out] Should be set to EC_NULL

struct EC_T_SLAVES_STATECHANGED_NTFY_DESC_ENTRY

Public Members

EC_T_WORD wStationAddress

Slave station address

EC_T_BYTE byState

New slave state

6.6.14. emWriteSlaveRegister

static EC_T_DWORD ecatWriteSlaveRegister(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen, EC_T_DWORD dwTimeout)

EC_T_DWORD emWriteSlaveRegister(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen, EC_T_DWORD dwTimeout)

Writes data into the ESC memory of a specified slave.

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

Warning

Changing contents of ESC registers may lead to unpredictable behavior of the slaves and/or the master.

Parameters

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

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wRegisterOffset – [in] Register offset, e.g. use 0x0120 to write to the AL Control register.

• pbyData – [in] Buffer containing transfered data

• wLen – [in] Number of bytes to send

• dwTimeout – [in] Timeout [ms]

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 command is not supported or the timeout value is set to EC_NOWAIT

• EC_E_SLAVE_NOT_PRESENT if slave not present

• EC_E_NOTFOUND if no slave matching bFixedAddressing / wSlaveAddress can be found

• EC_E_TIMEOUT if dwTimeout elapsed during the API call

• EC_E_BUSY another transfer request is already pending or the master or the corresponding slave is currently changing its operational state

• EC_E_NOTREADY if the working counter was not set when sending the command (slave may not be connected or did not respond)

• EC_E_INVALIDSIZE if the size of the complete command does not fit into a single Ethernet frame. The maximum amount of data to transfer must not exceed 1486 bytes

6.6.15. emWriteSlaveRegisterReq

static EC_T_DWORD ecatWriteSlaveRegisterReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen)

EC_T_DWORD emWriteSlaveRegisterReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen)

Requests a data write transfer into the ESC memory of a specified slave and returns immediately.

A notification EC_NOTIFY_SLAVE_REGISTER_TRANSFER is given on completion. This function may be called from within the JobTask’s context.

Warning

Changing contents of ESC registers may lead to unpredictable behavior of the slaves and/or the master.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified).

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_SLAVEREGISTER_TRANSFER_NTFY_DESC

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wRegisterOffset – [in] Register offset. I.e. use 0x0120 to write to the AL Control register

• pbyData – [in] Buffer containing transfered data

• wLen – [in] Number of bytes to send

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 command is not supported or the timeout value is set to EC_NOWAIT

• EC_E_SLAVE_NOT_PRESENT if slave not present

• EC_E_NOTFOUND if no slave matching bFixedAddressing / wSlaveAddress can be found

• EC_E_INVALIDSIZE if the size of the complete command does not fit into a single Ethernet frame. The maximum amount of data to transfer must not exceed 1486 bytes

See also

emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER

6.6.16. emReadSlaveRegister

static EC_T_DWORD ecatReadSlaveRegister(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen, EC_T_DWORD dwTimeout)

EC_T_DWORD emReadSlaveRegister(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen, EC_T_DWORD dwTimeout)

Reads data from the ESC memory of a specified slave.

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

Parameters

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

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wRegisterOffset – [in] Register offset. I.e. use 0x0130 to read the AL Status register.

• pbyData – [out] Buffer receiving transfered data

• wLen – [in] Number of bytes to receive

• dwTimeout – [in] Timeout [ms]

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if master isn’t initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range or the command is not supported or the timeout value is set to EC_NOWAIT

• EC_E_SLAVE_NOT_PRESENT if slave not present

• EC_E_NOTFOUND if no slave matching bFixedAddressing / wSlaveAddress can be found

• EC_E_TIMEOUT if dwTimeout elapsed during the API call

• EC_E_BUSY another transfer request is already pending or the master or the corresponding slave is currently changing its operational state

• EC_E_NOTREADY if the working counter was not set when sending the command (slave may not be connected or did not respond)

• EC_E_INVALIDSIZE if the size of the complete command does not fit into a single Ethernet frame. The maximum amount of data to transfer must not exceed 1486 bytes

6.6.17. emReadSlaveRegisterReq

static EC_T_DWORD ecatReadSlaveRegisterReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen)

EC_T_DWORD emReadSlaveRegisterReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen)

Requests data read transfer from the ESC memory of a specified slave and returns immediately.

A notification EC_NOTIFY_SLAVE_REGISTER_TRANSFER is given on completion. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified).

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_SLAVEREGISTER_TRANSFER_NTFY_DESC

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wRegisterOffset – [in] Register offset, e.g. use 0x0130 to read the AL Status register.

• pbyData – [out] Buffer receiving transfered data

• wLen – [in] Number of bytes to receive

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 command is not supported or the timeout value is set to EC_NOWAIT

• EC_E_SLAVE_NOT_PRESENT if slave not present.

• EC_E_NOTFOUND if no slave matching bFixedAddressing / wSlaveAddress can be found

• EC_E_INVALIDSIZE if the size of the complete command does not fit into a single Ethernet frame. The maximum amount of data to transfer must not exceed 1486 bytes.

See also

emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER

6.6.18. emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER

This notification is given, when a slave register transfer is completed.

emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER

Parameter

• pbyInBuf: [in] Pointer to EC_T_SLAVEREGISTER_TRANSFER_NTFY_DESC

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

• pbyOutBuf: [out] Should be set to EC_NULL

• dwOutBufSize: [in] Should be set to 0

• pdwNumOutData: [out] Should be set to EC_NULL

struct EC_T_SLAVEREGISTER_TRANSFER_NTFY_DESC

Public Members

EC_T_DWORD dwTferId

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

EC_T_DWORD dwResult

Result of Slave register transfer

EC_T_BOOL bRead

EC_TRUE: Read register, EC_FALSE: Write register transfer

EC_T_WORD wFixedAddr

Station address of slave

EC_T_WORD wRegisterOffset

Register offset

EC_T_WORD wLen

Length of slave register transfer

EC_T_BYTE *pbyData

Pointer to the data read

EC_T_WORD wWkc

Received working counter

6.6.19. emReadSlaveEEPRom

static EC_T_DWORD ecatReadSlaveEEPRom(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwReadData, EC_T_DWORD dwReadLen, EC_T_DWORD *pdwNumOutData, EC_T_DWORD dwTimeout)

EC_T_DWORD emReadSlaveEEPRom(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwReadData, EC_T_DWORD dwReadLen, EC_T_DWORD *pdwNumOutData, EC_T_DWORD dwTimeout)

Read EEPROM data from slave.

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

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

• wEEPRomStartOffset – [in] Word address to start EEPROM read from

• pwReadData – [in] Pointer to EC_T_WORD array to carry the read data

• dwReadLen – [in] Size of the EC_T_WORD array provided at pwReadData (in EC_T_WORDs)

• pdwNumOutData – [out] Pointer to EC_T_DWORD carrying actually read data (in EC_T_WORDs) after completion

• dwTimeout – [in] Timeout [ms] The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

6.6.20. emReadSlaveEEPRomReq

static EC_T_DWORD ecatReadSlaveEEPRomReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwReadData, EC_T_DWORD dwReadLen, EC_T_DWORD *pdwNumOutData, EC_T_DWORD dwTimeout)

EC_T_DWORD emReadSlaveEEPRomReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwReadData, EC_T_DWORD dwReadLen, EC_T_DWORD *pdwNumOutData, EC_T_DWORD dwTimeout)

Requests a EEPROM data read operation from slave and returns immediately.

A EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified).

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_EEPROM_OPERATION_NTFY_DESC

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wEEPRomStartOffset – [in] Word address to start EEPROM read from

• pwReadData – [out] Pointer to EC_T_WORD array to carry the read data, must be valid until the operation complete

• dwReadLen – [in] Size of the EC_T_WORD array provided at pwReadData (in EC_T_WORDs)

• pdwNumOutData – [out] Pointer to EC_T_DWORD carrying actually read data (in EC_T_WORDs) after completion

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

See also

emNotify - EC_NOTIFY_EEPROM_OPERATION

6.6.21. emWriteSlaveEEPRom

static EC_T_DWORD ecatWriteSlaveEEPRom(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwWriteData, EC_T_DWORD dwWriteLen, EC_T_DWORD dwTimeout)

EC_T_DWORD emWriteSlaveEEPRom(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwWriteData, EC_T_DWORD dwWriteLen, EC_T_DWORD dwTimeout)

Write EEPROM data to slave.

The EEPROM’s CRC is updated automatically. emResetSlaveController() is needed to reload the alias address in register 0x12. This function may not be called from within the JobTask’s context.

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

• wEEPRomStartOffset – [in] Word address to start EEPROM Write from

• pwWriteData – [in] Pointer to WORD array carrying the write data

• dwWriteLen – [in] Size of Write Data WORD array (in WORDS)

• dwTimeout – [in] Timeout [ms] The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

See also

emResetSlaveController()

6.6.22. emWriteSlaveEEPRomReq

static EC_T_DWORD ecatWriteSlaveEEPRomReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwWriteData, EC_T_DWORD dwWriteLen, EC_T_DWORD dwTimeout)

EC_T_DWORD emWriteSlaveEEPRomReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwWriteData, EC_T_DWORD dwWriteLen, EC_T_DWORD dwTimeout)

Requests a EEPROM data write operation from slave and returns immediately.

The EEPROM’s CRC is updated automatically. A reset of the slave controller is needed to reload the alias address in register 0x12. A EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified).

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_EEPROM_OPERATION_NTFY_DESC

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wEEPRomStartOffset – [in] Word address to start EEPROM Write from.

• pwWriteData – [in] Pointer to WORD array carrying the write data, must be valid until operation complete

• dwWriteLen – [in] Size of Write Data WORD array (in WORDS)

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

See also

• emResetSlaveController()

• emNotify - EC_NOTIFY_EEPROM_OPERATION

6.6.23. emAssignSlaveEEPRom

static EC_T_DWORD ecatAssignSlaveEEPRom(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bSlavePDIAccessEnable, EC_T_BOOL bForceAssign, EC_T_DWORD dwTimeout)

EC_T_DWORD emAssignSlaveEEPRom(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bSlavePDIAccessEnable, EC_T_BOOL bForceAssign, EC_T_DWORD dwTimeout)

Set EEPROM Assignment to PDI or EtherCAT Master.

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

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

• bSlavePDIAccessEnable – [in] EC_TRUE: EEPROM assigned to slave PDI application, EC_FALSE: EEPROM assigned to EC-Master

• bForceAssign – [in] Force Assignment of EEPROM (only for ECat Master Assignment)

• dwTimeout – [in] Timeout [ms] The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

6.6.24. emAssignSlaveEEPRomReq

static EC_T_DWORD ecatAssignSlaveEEPRomReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bSlavePDIAccessEnable, EC_T_BOOL bForceAssign, EC_T_DWORD dwTimeout)

EC_T_DWORD emAssignSlaveEEPRomReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bSlavePDIAccessEnable, EC_T_BOOL bForceAssign, EC_T_DWORD dwTimeout)

Requests EEPROM Assignment to PDI or EtherCAT Master operation and return immediately.

EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified).

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_EEPROM_OPERATION_NTFY_DESC

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• bSlavePDIAccessEnable – [in] EC_TRUE: EEPROM assigned to slave PDI application, EC_FALSE: EEPROM assigned to EC-Master

• bForceAssign – [in] Force Assignment of EEPROM (only for ECat Master Assignment)

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

See also

emNotify - EC_NOTIFY_EEPROM_OPERATION

6.6.25. emActiveSlaveEEPRom

static EC_T_DWORD ecatActiveSlaveEEPRom(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL *pbSlavePDIAccessActive, EC_T_DWORD dwTimeout)

EC_T_DWORD emActiveSlaveEEPRom(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL *pbSlavePDIAccessActive, EC_T_DWORD dwTimeout)

Check whether EEPROM is marked access active by Slave PDI application.

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

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

• pbSlavePDIAccessActive – [out] Pointer to Boolean value: EC_TRUE: EEPROM active by PDI application, EC_FALSE: EEPROM not active

• dwTimeout – [in] Timeout [ms] The function will block at most for this time. The timeout value must not be set to EC_NOWAIT

Returns

EC_E_NOERROR or error code

6.6.26. emActiveSlaveEEPRomReq

static EC_T_DWORD ecatActiveSlaveEEPRomReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL *pbSlavePDIAccessActive, EC_T_DWORD dwTimeout)

EC_T_DWORD emActiveSlaveEEPRomReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL *pbSlavePDIAccessActive, EC_T_DWORD dwTimeout)

Requests EEPROM is marked access active by Slave PDI application check and returns immediately.

A EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified).

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_EEPROM_OPERATION_NTFY_DESC

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• pbSlavePDIAccessActive – [out] Pointer to Boolean value: EC_TRUE: EEPROM active by PDI application, EC_FALSE: EEPROM not active. Must be valid until operation complete

• dwTimeout – [in] Timeout [ms] The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

See also

emNotify - EC_NOTIFY_EEPROM_OPERATION

6.6.27. emReloadSlaveEEPRom

static EC_T_DWORD ecatReloadSlaveEEPRom(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

EC_T_DWORD emReloadSlaveEEPRom(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

Causes a slave to reload its EEPROM values to ESC registers.

Alias address at 0x12 is not reloaded through this command, this is prevented by the slave hardware. The slave controller must be reset to reload the alias address. This function may not be called from within the JobTask’s context.

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

• dwTimeout – [in] Timeout [ms] The function will block at most for this time. The timeout value must not be set to EC_NOWAIT

Returns

EC_E_NOERROR or error code

See also

emResetSlaveController()

6.6.28. emReloadSlaveEEPRomReq

static EC_T_DWORD ecatReloadSlaveEEPRomReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

EC_T_DWORD emReloadSlaveEEPRomReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

Request a slave to reload its EEPROM values to ESC registers, and returns immediately.

Alias address at 0x12 is not reloaded through this command, this is prevented by the slave hardware. The slave controller must be reset to reload the alias address. A EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified).

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_EEPROM_OPERATION_NTFY_DESC

• bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

• wSlaveAddress – [in] Slave address according bFixedAddressing

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

See also

• emNotify - EC_NOTIFY_EEPROM_OPERATION

• emResetSlaveController()

6.6.29. emNotify - EC_NOTIFY_EEPROM_OPERATION

This notification is given, when a slave EEPROM operation is completed.

emNotify - EC_NOTIFY_EEPROM_OPERATION

Parameter

• pbyInBuf: [in] Pointer to EC_T_EEPROM_OPERATION_NTFY_DESC

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

• pbyOutBuf: [out] Should be set to EC_NULL

• dwOutBufSize: [in] Should be set to 0

• pdwNumOutData: [out] Should be set to EC_NULL

struct EC_T_EEPROM_OPERATION_NTFY_DESC

Public Members

EC_T_DWORD dwTferId

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

EC_T_EEPROM_OPERATION_TYPE eType

Type of EEPROM operation

EC_T_DWORD dwResult

Result of EEPROM operation

EC_T_SLAVE_PROP SlaveProp

Slave properties

union _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT

struct _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_ACTIVE

Public Members

EC_T_BOOL bSlavePDIAccessActive

EC_TRUE: EEPROM active by PDI application, EC_FALSE: EEPROM not active

struct _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_READ

Public Members

EC_T_WORD wEEPRomStartOffset

Start address of EEPRom operation. Given by API

EC_T_WORD *pwData

Pointer to WORD array contains the data. Given by API

EC_T_DWORD dwReadLen

Number of Words to be read. Given by API

EC_T_DWORD dwNumOutData

Number of Words actually read from EEPRom

struct _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_WRITE

Public Members

EC_T_WORD wEEPRomStartOffset

Start address of EEPRom operation. Given by API

EC_T_WORD *pwData

Pointer to WORD array contains the data. Given by API

EC_T_DWORD dwWriteLen

Number of Words to be written. Given by API

enum EC_T_EEPROM_OPERATION_TYPE

Values:

enumerator eEEPRomOp_Unknown

Unknown EEPROM operation, only for internal use

enumerator eEEPRomOp_Assign

Assign slave EEPROM operation, used by emAssignSlaveEEPRomReq

enumerator eEEPRomOp_Active

Active slave EEPROM operation, used by emActiveSlaveEEPRomReq

enumerator eEEPRomOp_Read

Read slave EEPRom operation, used by emReadSlaveEEPRomReq

enumerator eEEPRomOp_Write

Write slave EEPRom operation, used by emWriteSlaveEEPRomReq

enumerator eEEPRomOp_Reload

Reload slave EEPRom operation, used by emReloadSlaveEEPRomReq

enumerator eEEPRomOp_Reset

Reset slave EEPRom operation, used by emResetSlaveController

6.6.30. emResetSlaveController

static EC_T_DWORD ecatResetSlaveController(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

EC_T_DWORD emResetSlaveController(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

Reset EtherCAT slave controller (ESC)

A special sequence of three independent and consecutive frames/commands is sent to the slave (reset register ECAT 0x0040 or PDI 0x0041), after which the slave resets. If that fails, the reset sequence is repeated until it succeeds or the timeout expires. The ESC must support resetting and the slave state should be INIT when calling this function. The number of acyclic frames per cycle EC_T_INIT_MASTER_PARMS.dwMaxAcycFramesPerCycle must be at least 3, otherwise an error is returned. This function may not be called from within the JobTask’s context.

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

• dwTimeout – [in] Timeout [ms] The function will block at most for this time. The timeout value must not be set to EC_NOWAIT

Returns

• EC_E_NOERROR or error code