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.
The function was successfully executed |
|
Unsupported feature or functionality |
|
The master currently is busy and the function has to be re-tried at a later time |
|
Not enough memory or frame buffer resources available |
|
Invalid or inconsistent parameters |
|
Timeout error |
|
A slave error was detected |
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) |
|
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 |
|
Link cable not connected. |
|
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_LOG_PARMS LogParms
[in] Logging parameters
-
EC_T_WORD wMaxSlavesProcessedPerBusScanStep
[in] maximum slave-related calls per cycle during bus scans
-
EC_T_PERF_MEAS_INTERNAL_PARMS PerfMeasInternalParms
[in] Internal performance measurement parameters
-
EC_T_LOG_PARMS LogParms
-
struct EC_T_OS_PARMS
Public Members
-
EC_PF_SYSTIME pfSystemTimeGet
[in] Function to get host time in nanoseconds since 1st January 2000. Used as time base for DC Initialization.
-
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_SYSTIME pfSystemTimeGet
-
struct EC_T_LOG_PARMS
Public Members
-
EC_PF_LOGMSGHK pfLogMsg
[in] Log callback function called on every message
-
EC_PF_LOGMSGHK pfLogMsg
EC_LOG_LEVEL… The following log levels are defined:
-
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_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.
-
EC_T_PERF_MEAS_COUNTER_PARMS CounterParms
-
struct EC_T_PERF_MEAS_COUNTER_PARMS
Public Members
-
EC_PF_PERF_MEAS_GETCOUNTERTICKS pfGetCounterTicks
[in] Function returning the current counter ticks
-
EC_PF_PERF_MEAS_GETCOUNTERTICKS pfGetCounterTicks
6.3.2. emDeinitMaster
-
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
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:
- 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
6.3.5. emScanBus
-
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
6.3.6. emRescueScan
-
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
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
Depending on this enum pbyCnfData is interpreted differently. This function may not be called from within the JobTask’s context.
6.3.8. emConfigGet
-
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
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
-
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, see EC_NOTIFY_…, e.g. EC_NOTIFY_STATECHANGED
pParms – [in] Notification code depending data.
6.3.11. emUnregisterClient
-
EC_T_DWORD emUnregisterClient(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClntId)
Unregister a client from the EtherCAT master.
This function may not be called from within the JobTask’s context.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
dwClntId – [in] Client ID determined when registering with the master.
- Returns
EC_E_NOERROR or error code
6.3.12. emGetSrcMacAddress
-
EC_T_DWORD emGetSrcMacAddress(EC_T_DWORD dwInstanceID, ETHERNET_ADDRESS *pMacSrc)
Gets the source MAC address.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pMacSrc – [out] 6-byte buffer to write source MAC address to.
- Returns
EC_E_NOERROR or error code
See also
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
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
-
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:
- 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
-
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
-
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:
-
union EC_T_USER_JOB_PARMS
Public Members
-
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 EC_T_USER_JOB_PARMS::_SEND_CYCFRAME_BY_TASKID SendCycFramesByTaskId
Detailed job description:
eUsrJob_ProcessAllRxFramesWhen 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_TRUEit indicates that all previously initiated cyclic frames (eUsrJob_SendAllCycFrames) are received and processed within this call. Not used if pUserJobParms set toEC_NULL.Return: EC_E_NOERROR if successful, error code in case of failures.
eUsrJob_SendAllCycFramesSend 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 theeUsrJob_ProcessAllRxFramesjob 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).
eUsrJob_SendAcycFramesAcyclic 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.
eUsrJob_MasterTimerTo 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.
eUsrJob_SendCycFramesByTaskIdSend 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.
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).
eUsrJob_ProcessRxFramesByTaskId-
See also
Feature-Pack Split Frame Processing
eUsrJob_SwitchEoeFramesThis 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
-
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
-
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
6.3.21. emSetOemKey
-
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
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
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_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [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
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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_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_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_PBYTE pbyMasterRedPDInData
Pointer to the default input process data buffer (INACTIVE to ACTIVE)
-
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.
-
EC_T_PVOID pvContext
-
typedef EC_T_VOID (*EC_T_PFMEMREQ)(EC_T_PVOID pvContext, EC_T_DWORD dwTaskId, EC_T_PBYTE *ppbyPDData)
- Parameters
pvContext – [in] Arbitrarily application-defined parameter passed to callback
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] Arbitrarily application-defined parameter passed to callback
dwTaskId – [in] Task ID of cyclic data transfer
See also
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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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.
-
EC_T_VOID *pCallbackContext
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_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [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_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [out] Pointer to struct EC_T_LINKLAYER_MODE_DESCdwOutBufSize: [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.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 informationdwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Pointer to EC_T_CYC_CONFIG_DESC data typedwOutBufSize: [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
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_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [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_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [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_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
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_DESCdwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
Setting a value of this descriptor to zero resets the default timeout value to the initial value.
See also
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: ProcessAllRxFramesdwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_DESCdwInBufSize: [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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
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_STATEdwInBufSize: [in] Size of the input buffer in bytes. E.g. sizeof(EC_T_STATE)pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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
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
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
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
6.4.7. emReleaseAllProcessDataBits
-
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
6.4.8. emGetProcessImageInputPtr
-
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
emExecJob()(eUsrJob_ProcessAllRxFrames) in case of Polling Mode
6.4.9. emGetProcessImageOutputPtr
-
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
emExecJob()(eUsrJob_SendAllCycFrames)
6.4.10. emGetDiagnosisImagePtr
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
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
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
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
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
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
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
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
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
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
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
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
6.4.23. emTraceDataConfig
-
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
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_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 0x3D 0xAD 0x00 */
6.4.26. EC_COMPAREBITS
-
EC_COMPAREBITS(pbyBuf1, nBitOffs1, pbyBuf2, nBitOffs2, nBitSize)
Compares a block of bits of two buffers.
Note
The buffers are compared bitwise with the same semantic as memcmp(). The buffers are not checked for overrun.
- Parameters
pbyBuf1 – [in] Buffer 1
nBitOffs1 – [in] Bit offset within buffer 1
pbyBuf2 – [in] Buffer 2
nBitOffs2 – [in] Bit offset within buffer 2
nBitSize – [in] Bit size to compare
- Returns
Integral value indicating the relationship between the content of the memory blocks:
0: The blocks of bits within the two buffers are equal
<0: Binary value from block of bits in buffer 1 has a lower value than binary value from block of bits in buffer 2
>0: Binary value from block of bits in buffer 1 has a greater value than binary value from block of bits in buffer 2
See also
EC_T_BYTE pbyBuf1[] = {0xB8, 0x3D, 0xAD, 0x00};
EC_T_BYTE pbyBuf2[] = {0xF4, 0xED, 0x69, 0xA5};
assert(0 == EC_COMPAREBITS(pbyBuf1, 3, pbyBuf2, 6, 22));
6.4.27. 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.28. 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.29. 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.30. 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.31. 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.32. 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.33. 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
6.4.34. 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
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)
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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
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
6.6. Slave control and status functions
6.6.1. emGetNumConfiguredSlaves
6.6.2. emGetNumConnectedSlaves
6.6.3. emGetSlaveId
-
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
-
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]
- 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
See also
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
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().
-
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
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
6.6.9. emSlaveSerializeMbxTfers
-
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
6.6.10. emSlaveParallelMbxTfers
-
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
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_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_DESCdwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
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_DESCdwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
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
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.
- 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]
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.
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_DESCdwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
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
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
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
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
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
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
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
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_DESCdwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [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_SLAVE_PROP SlaveProp
Slave properties
-
EC_T_DWORD dwTferId
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
EC_E_NOTSUPPORTED if EC_T_INIT_MASTER_PARMS.dwMaxAcycFramesPerCycle is less than 3
EC_E_SLAVE_NOT_PRESENT if slave not present
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive
6.6.31. emIoControl - EC_IOCTL_ALL_SLAVES_MUST_REACH_MASTER_STATE
Specifies if all the slaves must reach the requested master state.
- emIoControl - EC_IOCTL_ALL_SLAVES_MUST_REACH_MASTER_STATE
- Parameter
pbyInBuf: [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE all slaves must reach the master requested state, if set to EC_FALSE the master can reach the requested state even if some slaves are missing or cannot reach the requested state.dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
Missing mandatory slaves will be signalized by emNotify - EC_NOTIFY_SLAVE_PRESENCE. Slaves who cannot reach the requested master state will be signalized by emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE. emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL will not be generated anymore if this IOCTL is called with EC_FALSE, emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR will be still generated.
6.6.32. emGetCfgSlaveInfo
-
static EC_T_DWORD ecatGetCfgSlaveInfo(EC_T_BOOL bStationAddress, EC_T_WORD wSlaveAddress, EC_T_CFG_SLAVE_INFO *pSlaveInfo)
-
EC_T_DWORD emGetCfgSlaveInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_CFG_SLAVE_INFO *pSlaveInfo)
Return information about a configured slave from the ENI file.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
wSlaveAddress – [in] Slave address according bFixedAddressing
pSlaveInfo – [out] Information about the slave.
- Returns
EC_E_NOERROR or error code
-
struct EC_T_CFG_SLAVE_INFO
Public Members
-
EC_T_CHAR abyDeviceName[ECAT_DEVICE_NAMESIZE]
[out] The slave’s configured name (80 Byte) (from ENI file)
-
EC_T_DWORD dwMbxSupportedProtocols
[out] Mailbox protocols supported by the slave (from ENI file). Combination of Supported mailbox protocols flags
-
EC_T_WORD wWkcStateDiagOffsIn[EC_CFG_SLAVE_PD_SECTIONS]
[out] Offset of WkcState bit in diagnosis image (ENI: ProcessData/Recv[1..4]/BitStart) WkcState bit values: 0 = Data Valid, 1 = Data invalid
-
EC_T_WORD wWkcStateDiagOffsOut[EC_CFG_SLAVE_PD_SECTIONS]
[out] Offset of WkcState bit in diagnosis image (ENI: ProcessData/Send[1..4]/BitStart) WkcState bit values: 0 = Data Valid, 1 = Data invalid
-
EC_T_WORD awMasterSyncUnitIn[EC_CFG_SLAVE_PD_SECTIONS]
[out] Sync Unit (ENI: ProcessData/TxPdo[1..4]@Su)
-
EC_T_WORD awMasterSyncUnitOut[EC_CFG_SLAVE_PD_SECTIONS]
[out] Sync Unit (ENI: ProcessData/RxPdo[1..4]@Su)
-
EC_T_CHAR abyDeviceName[ECAT_DEVICE_NAMESIZE]
Supported mailbox protocols flags
- group EC_MBX_PROTOCOLS
6.6.33. emGetCfgSlaveEoeInfo
-
static EC_T_DWORD ecatGetCfgSlaveEoeInfo(EC_T_BOOL bStationAddress, EC_T_WORD wSlaveAddress, EC_T_CFG_SLAVE_EOE_INFO *pSlaveEoeInfo)
-
EC_T_DWORD emGetCfgSlaveEoeInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_CFG_SLAVE_EOE_INFO *pSlaveEoeInfo)
Return EoE information about a configured slave from the ENI file.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
wSlaveAddress – [in] Slave address according bFixedAddressing
pSlaveEoeInfo – [out] Information about the slave
- 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 bFixedAddressing / wSlaveAddress can be found
EC_E_NO_MBX_SUPPORT if the slave does not support mailbox communication
EC_E_NO_EOE_SUPPORT if the slave supports mailbox communication, but not EoE
6.6.34. emGetBusSlaveInfo
-
static EC_T_DWORD ecatGetBusSlaveInfo(EC_T_BOOL bStationAddress, EC_T_WORD wSlaveAddress, EC_T_BUS_SLAVE_INFO *pSlaveInfo)
-
EC_T_DWORD emGetBusSlaveInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BUS_SLAVE_INFO *pSlaveInfo)
Return information about a slave connected to the EtherCAT bus.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
wSlaveAddress – [in] Slave address according bFixedAddressing
pSlaveInfo – [out] Information from the slave.
- Returns
EC_E_NOERROR 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 bFixedAddressing / wSlaveAddress can be found
-
struct EC_T_BUS_SLAVE_INFO
Public Members
-
EC_T_DWORD adwPortSlaveIds[ESC_PORT_COUNT]
[out] The slave’s ID of the slaves connected to ports. See Port slave ID’s
-
EC_T_WORD wPortState
[out] Port link state. Format: wwww xxxx yyyy zzzz (each nibble : port 3210)
wwww : Signal detected 1=yes, 0=no
xxxx : Loop closed 1=yes, 0=no
yyyy : Link established 1=yes, 0=no
zzzz : Slave connected 1=yes, 0=no (zzzz = logical result of w,x,y)
-
EC_T_WORD wAlStatusCode
[out] AL status code. (Value of slave ESC register 0x0134 during last error acknowledge). This value is reset after a slave state change
-
EC_T_DWORD dwSystemTimeDifference
[out] System time difference. (Value of slave ESC register 0x092C)
-
EC_T_WORD wMbxSupportedProtocols
[out] Supported Mailbox Protocols stored in the EEPROM at offset 0x001C
-
EC_T_WORD wIdentifyData
[out] Last read identification value see EC_T_CFG_SLAVE_INFO.wIdentifyAdo
-
EC_T_DWORD dwSlaveDelay
[out] Delay behind slave [ns]. This value is only valid if a DC configuration is used
-
EC_T_DWORD dwPropagDelay
[out] Propagation delay [ns]. ESC register 0x0928,This value is only valid if a DC configuration is used
-
EC_T_BOOL bIsDeviceEmulation
[out] Slave without Firmware. ESC register 0x0141, enabled by EEPROM offset 0x0000.8.
-
EC_T_WORD wLineCrossedFlags
[out] Combination of Line crossed flags
-
EC_T_DWORD adwPortSlaveIds[ESC_PORT_COUNT]
Port Slave ID’s
- group EC_SLAVE_IDS
EC_LINECROSSED_ flags
- group EC_LINECROSSED_FLAGS
6.6.35. emReadSlaveIdentification
-
static EC_T_DWORD ecatReadSlaveIdentification(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wAdo, EC_T_WORD *pwValue, EC_T_DWORD dwTimeout)
-
EC_T_DWORD emReadSlaveIdentification(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wAdo, EC_T_WORD *pwValue, EC_T_DWORD dwTimeout)
Read identification value 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
wAdo – [in] ADO used for identification command
pwValue – [out] Pointer to Word value containing the Identification value
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_ADO_NOT_SUPPORTED if the slave does not support requesting ID mechanism
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive
6.6.36. emReadSlaveIdentificationReq
-
static EC_T_DWORD ecatReadSlaveIdentificationReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wAdo, EC_T_WORD *pwValue, EC_T_DWORD dwTimeout)
-
EC_T_DWORD emReadSlaveIdentificationReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wAdo, EC_T_WORD *pwValue, EC_T_DWORD dwTimeout)
Request the identification value from a slave and returns immediately.
A notification EC_NOTIFY_SLAVE_IDENTIFICATION 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_SLAVE_IDENTIFICATION_NTFY_DESC
bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
wSlaveAddress – [in] Slave address according bFixedAddressing
wAdo – [in] ADO used for identification command
pwValue – [out] Pointer to Word value containing the Identification value, must be valid until the request complete.
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_ADO_NOT_SUPPORTED if the slave does not support requesting ID mechanism
6.6.37. emNotify - EC_NOTIFY_SLAVE_IDENTIFICATION
This notification is given, when the read slave identification request is completed.
- emNotify - EC_NOTIFY_SLAVE_IDENTIFICATION
- Parameter
pbyInBuf: [in] Pointer to EC_T_SLAVE_IDENTIFICATION_NTFY_DESCdwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
-
struct EC_T_SLAVE_IDENTIFICATION_NTFY_DESC
Public Members
-
EC_T_DWORD dwTferId
Transfer ID. For every new port operation a unique ID has to be assigned. This ID can be used after completion to identify the transfer
-
EC_T_SLAVE_PROP SlaveProp
Slave properties
-
EC_T_DWORD dwTferId
6.6.38. emIoControl - EC_IOCTL_SET_AUTO_ACK_AL_STATUS_ERROR_ENABLED
Specifies if slave errors must be automatically acknowledged
- emIoControl - EC_IOCTL_SET_AUTO_ACK_AL_STATUS_ERROR_ENABLED
- Parameter
pbyInBuf: [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE slave errors must be automatically acknowledged, if set to EC_FALSE the application must acknowledge slave errors explicitlydwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
The pending slave error will be acknowledged during the next emSetSlaveState() call.
6.6.39. emIoControl - EC_IOCTL_SET_AUTO_ADJUST_CYCCMD_WKC_ENABLED
Specifies if the cyclic commands expected WKC must be automatically adjusted according the state and the presence of the slaves.
- emIoControl - EC_IOCTL_SET_AUTO_ADJUST_CYCCMD_WKC_ENABLED
- Parameter
pbyInBuf: [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE cyclic commands expected WKC must be automatically adjusted, if set to EC_FALSE the cyclic commands expected WKC stay unchangeddwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
If TRUE, the notification emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR is only generated if a slave doesn’t increment the WKC although it should. AUTO_ADJUST_CYCCMD_WKC is disabled by default.
6.6.40. emSetSlaveDisabled
Before using this function, please check if the following patents has to be taken into consideration for your application and use case:
JP2014146077: CONTROL DEVICE AND OPERATION METHOD FOR CONTROL DEVICE
JP2014146070: CONTROL DEVICE, CONTROL METHOD, AND PROGRAM
JP2014120884: INFORMATION PROCESSING APPARATUS, INFORMATION ROCESSING PROGRAM, AND INFORMATION PROCESSING METHOD
-
static EC_T_DWORD ecatSetSlaveDisabled(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bDisabled)
-
EC_T_DWORD emSetSlaveDisabled(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bDisabled)
Enable or disable a specific slave.
The EtherCAT state of disabled slaves can not be set higher than PREOP. If the state is higher than PREOP at the time this function is called. The state will be automatically change to PREOP. The information about the last requested state is lost and is set to PREOP too.
- 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
bDisabled – [in] EC_TRUE: Disable slave, EC_FALSE: Enable slave
- Returns
EC_E_NOERROR or error code
6.6.41. emSetSlaveDisconnected
Before using this function, please check if the following patents has to be taken into consideration for your application and use case:
JP2014146077: CONTROL DEVICE AND OPERATION METHOD FOR CONTROL DEVICE
JP2014146070: CONTROL DEVICE, CONTROL METHOD, AND PROGRAM
JP2014120884: INFORMATION PROCESSING APPARATUS, INFORMATION ROCESSING PROGRAM, AND INFORMATION PROCESSING METHOD
-
static EC_T_DWORD ecatSetSlaveDisconnected(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bDisconnected)
-
EC_T_DWORD emSetSlaveDisconnected(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bDisconnected)
Mark specific slave for connection or disconnection.
The EtherCAT state of disconnected slaves can not be set higher than INIT. If the state is higher than INIT at the time this function is called, the state will be automatically change to INIT. The information about the last requested state is lost and is set to INIT too.
- 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
bDisconnected – [in] EC_TRUE: Mark slave for disconnection, EC_FALSE: Mark slave for (re-)connection
- Returns
EC_E_NOERROR or error code
6.6.42. emSetSlavesDisconnected
Before using this function, please check if the following patents has to be taken into consideration for your application and use case:
JP2014146077: CONTROL DEVICE AND OPERATION METHOD FOR CONTROL DEVICE
JP2014146070: CONTROL DEVICE, CONTROL METHOD, AND PROGRAM
JP2014120884: INFORMATION PROCESSING APPARATUS, INFORMATION ROCESSING PROGRAM, AND INFORMATION PROCESSING METHOD
-
static EC_T_DWORD ecatSetSlavesDisconnected(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_SLAVE_SELECTION eSlaveSelection, EC_T_BOOL bDisconnected)
-
EC_T_DWORD emSetSlavesDisconnected(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_SLAVE_SELECTION eSlaveSelection, EC_T_BOOL bDisconnected)
Mark a specific group of slaves for connection or disconnection.
- 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
eSlaveSelection – [in] Slave selection criteria
bDisconnected – [in] EC_TRUE: mark slaves for disconnection, EC_FALSE: mark slaves for connection
- 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 bFixedAddressing / wSlaveAddress can be found
See also
6.6.43. emGetSlavePortState
-
EC_T_DWORD emGetSlavePortState(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_WORD *pwPortState)
Returns the state of the slave ports.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
dwSlaveId – [in] Slave ID
pwPortState –
[out] Slave port state.
Format: wwww xxxx yyyy zzzz (each nibble : port 3210)
wwww : Signal detected 1=yes, 0=no
xxxx : Loop closed 1=yes, 0=no
yyyy : Link established 1=yes, 0=no
zzzz : Slave connected 1=yes, 0=no (zzzz = logical result of w,x,y)
- 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 dwSlaveId can be found
See also
6.6.44. emSetSlavePortState
-
static EC_T_DWORD ecatSetSlavePortState(EC_T_DWORD dwSlaveId, EC_T_WORD wPort, EC_T_BOOL bClose, EC_T_BOOL bForce, EC_T_DWORD dwTimeout)
-
EC_T_DWORD emSetSlavePortState(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_WORD wPort, EC_T_BOOL bClose, EC_T_BOOL bForce, EC_T_DWORD dwTimeout)
Open or close slave port.
This function allows to open or close a specific slave port in different ways. It also can be used to re-open ports closed by a rescue scan.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
dwSlaveId – [in] Slave ID
wPort – [in] Port to open or close. Can be ESC_PORT_A, ESC_PORT_B, ESC_PORT_C, ESC_PORT_D
bClose – [in] EC_TRUE: close port, EC_FALSE: open port
bForce – [in] EC_TRUE: port will be closed or open, EC_FALSE: port will be set in AutoClose mode
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_SLAVE_NOT_PRESENT if slave not present
EC_E_NOTFOUND if no slave matching dwSlaveId can be found
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive
See also
6.6.45. emSetSlavePortStateReq
-
static EC_T_DWORD ecatSetSlavePortStateReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_DWORD dwSlaveId, EC_T_WORD wPort, EC_T_BOOL bClose, EC_T_BOOL bForce, EC_T_DWORD dwTimeout)
-
EC_T_DWORD emSetSlavePortStateReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_DWORD dwSlaveId, EC_T_WORD wPort, EC_T_BOOL bClose, EC_T_BOOL bForce, EC_T_DWORD dwTimeout)
Requests Open or close slave port operation and returns immediately.
A EC_T_PORT_OPERATION_NTFY_DESC is given on completion. This function can be called to re-open ports closed by a rescue scan.
- 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_PORT_OPERATION_NTFY_DESC
dwSlaveId – [in] Slave ID
wPort – [in] Port to open or close. Can be ESC_PORT_A, ESC_PORT_B, ESC_PORT_C, ESC_PORT_D
bClose – [in] EC_TRUE: close port, EC_FALSE: open port
bForce – [in] EC_TRUE: port will be closed or open, EC_FALSE: port will be set in AutoClose mode
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_SLAVE_NOT_PRESENT if slave not present
EC_E_NOTFOUND if no slave matching dwSlaveId can be found
6.6.46. emNotify - EC_T_PORT_OPERATION_NTFY_DESC
This notification is given, when the port operation request is completed.
- emNotify - EC_T_PORT_OPERATION_NTFY_DESC
- Parameter
pbyInBuf: [in] Pointer to EC_T_PORT_OPERATION_NTFY_DESCdwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
-
struct EC_T_PORT_OPERATION_NTFY_DESC
Public Members
-
EC_T_DWORD dwTferId
Transfer ID. For every new port operation a unique ID has to be assigned. This ID can be used after completion to identify the transfer
-
EC_T_SLAVE_PROP SlaveProp
Slave properties
-
EC_T_DWORD dwTferId
See also
6.6.47. emIoControl - EC_IOCTL_SET_NEW_BUSSLAVES_TO_INIT
Force state change to INIT for all new slaves in network after detection.
- emIoControl - EC_IOCTL_SET_NEW_BUSSLAVES_TO_INIT
- Parameter
pbyInBuf: [in] Pointer to EC_T_BOOL. EC_TRUE: Force state change, EC_FALSE: No state change.dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytespbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
Default: No state change after detection
6.7. Diagnosis, error detection, error notifications
In case of errors on the bus or in one or multiple slaves the EtherCAT master stack will notify the application about such an event. The master automatically detects unexpected slaves states by evaluating the AL Status event interrupt. If the interrupt is set, the master reads the state of each slave and compares it to the expected (required) state. In case of a state mismatch the master generates the notification emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE. The application will then have to enter an error handling procedure.
The error notifications can be separated into two classes:
Slave unrelated errors
Slave related errors
A slave related error notification will also contain the information about which slave has generated an error. If for example a slave could not be set into the requested state the application will get the emNotify - EC_NOTIFY_SLAVE_INITCMD_RESPONSE_ERROR error notification including slave related information. A slave unrelated error does not contain this information even if one specific slave caused the error. For example if one or multiple slaves are powered off the working counter of the cyclic commands would be wrong. In that case the emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR error notification will be generated.
Example Error Scenario
Slave is powered off or disconnected while bus is operational
If the master is operational it cyclically sends EtherCAT commands to read and write the slave’s process data. It expects the working counter to be incremented to the appropriate value. If one slave is powered off the master will generate the emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR to indicate such an event. Also the master detects a DL status event and performs a bus scan as reaction on this. For the not reachable slaves (powered off or disconnected) the master generates the notification emNotify - EC_NOTIFY_SLAVE_PRESENCE.
A possible error recovery scenario would be to stay operational and in parallel wait until the slave is powered on again. The next step would be to determine the slave’s state and set it operational again:
- Master calls emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR
Application gets informed
WKC State in Diagnosis Image changes
See also
Use cases
- Slave is disconnected or powered off:
Master detects a DL status event interrupt an performs a bus scan.
Master calls emNotify - EC_NOTIFY_SLAVE_PRESENCE
Application gets informed and could set the whole master into a lower state, e.g.
eEcatState_INIT
- Slave state is not OPERATIONAL anymore
Master calls emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE
Application gets informed and could either set the whole master into lower state (e.g.
eEcatState_PREOP), or callsemSetSlaveState()to repair the failed slave.
- Slave is re-connected or powered on:
Master detects a DL status event interrupt an performs a bus scan.
Master calls emNotify - EC_NOTIFY_SLAVE_PRESENCE.
Application could wait until all slaves are re-connected by calling the functions
emGetNumConnectedSlaves()andemGetNumConfiguredSlaves().After all slaves are re-connected the application could either set the whole master to
eEcatState_INITand afterwards to :cpp:enumerator:`eEcatState_OP, or the application usesemSetSlaveState()to repair only the failed slaves.
6.7.1. emEthDbgMsg
-
static EC_T_DWORD ecatEthDbgMsg(EC_T_BYTE byEthTypeByte0, EC_T_BYTE byEthTypeByte1, EC_T_CHAR *szMsg)
-
EC_T_DWORD emEthDbgMsg(EC_T_DWORD dwInstanceID, EC_T_BYTE byEthTypeByte0, EC_T_BYTE byEthTypeByte1, EC_T_CHAR *szMsg)
Send a debug message to the EtherCAT Link Layer.
This feature can be used for debugging purposes.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
byEthTypeByte0 – [in] Ethernet type byte 0
byEthTypeByte1 – [in] Ethernet type byte 1
szMsg – [in] Message to send to link layer
- Returns
EC_E_NOERROR or error code
6.7.2. emIoControl - EC_IOCTL_GET_SLVSTATISTICS
Get Slave’s statistics counter. Counters are collected on a regularly base (default: off) and show errors on Ethernet Layer.
- emIoControl - EC_IOCTL_GET_SLVSTATISTICS
- Parameter
pbyInBuf: [in] Pointer to a EC_T_DWORD type variable containing the slave id.dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Pointer to struct EC_T_SLVSTATISTICS_DESCdwOutBufSize: [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
6.7.3. emGetSlaveStatistics
-
static EC_T_DWORD ecatGetSlaveStatistics(EC_T_DWORD dwSlaveId, EC_T_SLVSTATISTICS_DESC *pSlaveStatisticsDesc)
-
EC_T_DWORD emGetSlaveStatistics(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_SLVSTATISTICS_DESC *pSlaveStatisticsDesc)
Get Slave’s statistics counter.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
dwSlaveId – [in] Slave id
pSlaveStatisticsDesc – [out] Pointer to structure EC_T_SLVSTATISTICS_DESC
- Returns
EC_E_NOERROR or error code
6.7.4. emIoControl - EC_IOCTL_CLR_SLVSTATISTICS
Clear all error registers in all slaves
- emIoControl - EC_IOCTL_CLR_SLVSTATISTICS
- Parameter
pbyInBuf: [in] Should be set to EC_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
6.7.5. emClearSlaveStatistics
-
EC_T_DWORD emClearSlaveStatistics(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId)
Clears all error registers of a slave.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
dwSlaveId – [in] Slave Id, INVALID_SLAVE_ID clears all slaves
- Returns
EC_E_NOERROR or error code
See also
6.7.6. emIoControl - EC_IOCTL_GET_SLVSTAT_PERIOD
Get Slave Statistics collection period. Period of 0: automatic slave statistics collection disabled.
- emIoControl - EC_IOCTL_GET_SLVSTAT_PERIOD
- Parameter
pbyInBuf: [in] Should be set to EC_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [out] Pointer to a EC_T_DWORD type variable containing the slave statistics collection period [ms] to get.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
6.7.7. emIoControl - EC_IOCTL_SET_SLVSTAT_PERIOD
Update Slave Statistics collection period. It implicitly forces an immediate collection of slave statistics if performed successfully.
A Period of 0 disables automatic slave statistics collection, otherwise it set the time between the read sequences.
- emIoControl - EC_IOCTL_SET_SLVSTAT_PERIOD
- Parameter
pbyInBuf: [in] pointer to a EC_T_DWORD type variable containing the slave statistics collection period [ms] to set.dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
6.7.8. emIoControl - EC_IOCTL_FORCE_SLVSTAT_COLLECTION
Sends datagrams to collect slave statistics counters.
- emIoControl - EC_IOCTL_FORCE_SLVSTAT_COLLECTION
- Parameter
pbyInBuf: [in] Should be set to EC_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
6.7.9. emIoControl - EC_IOCTL_CLEAR_MASTER_INFO_COUNTERS
Reset Master Info Counters according to given bit masks
- emIoControl - EC_IOCTL_CLEAR_MASTER_INFO_COUNTERS
- Parameter
pbyInBuf: [in] Pointer to value of EC_T_CLEAR_MASTER_INFO_COUNTERS_PARMS.dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
-
struct EC_T_CLEAR_MASTER_INFO_COUNTERS_PARMS
Public Members
-
EC_T_DWORD dwClearBusDiagnosisCounters
[in] Bit 0..7: Clear corresponding Counter ID:
Bit 0: Clear all Counters
Bit 1: Clear Tx Frame Counter
Bit 2: Clear Rx Frame Counter
Bit 3: Clear Lost Frame Counter
Bit 4: Clear Cyclic Frame Counter
Bit 5: Clear Cyclic Datagram Counter
Bit 6: Clear Acyclic Frame Counter
Bit 7: Clear Acyclic DataGram Counter
Bit 8: Clear Cyclic Lost Frame Counter
Bit 9: Clear Acyclic Lost Frame Counter
-
EC_T_UINT64 qwMailboxStatisticsClearCounters
[in] Bit 0..56: Clear corresponding Counter ID.
Bit 0..7: Clear AoE statistics
Bit 0: Total Read Transfer Count
Bit 1: Read Transfer Count Last Second
Bit 2: Total Bytes Read
Bit 3: Bytes Read Last Second
Bit 4: Total Write Transfer Count
Bit 5: Write Transfer Count Last Second
Bit 6: Total Bytes Write
Bit 7: Bytes Write Last Second
Bit 8..15: Clear CoE statistics (same ordering as Bit 0..7, AoE)
Bit 16..23: Clear EoE statistics (same ordering as Bit 0..7, AoE)
Bit 24..31: Clear FoE statistics (same ordering as Bit 0..7, AoE)
Bit 32..39: Clear SoE statistics (same ordering as Bit 0..7, AoE)
Bit 40..47: Clear VoE statistics (same ordering as Bit 0..7, AoE)
Bit 48..55: Clear RawMbx statistics (same ordering as Bit 0..7, AoE)
-
EC_T_DWORD dwClearBusDiagnosisCounters
qwMailboxStatisticsClearCounters = 0x0000000100; //Clear CoE Total Read Transfer Count.
6.7.10. emIoControl - EC_IOCTL_SET_FRAME_RESPONSE_ERROR_NOTIFY_MASK
Sets a bit mask to enable or disable the generation of specific error notifications of frame response errors. The application then can decide to suppress those error messages. By default all errors, expect EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_NON_ECAT_FRAME are enabled (the notification mask is set to EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_DEFAULT).
- emIoControl - EC_IOCTL_SET_FRAME_RESPONSE_ERROR_NOTIFY_MASK
- Parameter
pbyInBuf: [in] pointer to a EC_T_DWORD type value containing the new error mask.dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
The following frame response error notification mask values exist:
6.7.11. emIoControl - EC_IOCTL_SET_FRAME_LOSS_SIMULATION
This IO Control is introduced for testing and debugging purposes. It enables an application to simulate the loss of EtherCAT frames on both transmit and receive bus direction.
Important
Do not activate this on shipped releases. Frameloss has significant influence on performance and reliablility of the application!
- emIoControl - EC_IOCTL_SET_FRAME_LOSS_SIMULATION
- Parameter
pbyInBuf: [in] Array of four EC_T_DWORDs (arrDword)dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
The parameters configurable are :
- arrDword [0] -> dwNumGoodFramesAfterStart
Number of good frames before frame loss simulation starts
- arrDword [1] -> dwFrameLossLikelihoodPpm
Random loss simulation: frame loss likelihood (ppm)
- arrDword [2] -> dwFixedLossNumGoodFrames
Fixed loss simulation: number of good frames before frame loss
- arrDword [3] -> dwFixedLossNumLostFrames
Fixed loss simulation: number of lost frames after processing the good ones
6.7.12. emIoControl - EC_IOCTL_SET_RXFRAME_LOSS_SIMULATION
Same as emIoControl - EC_IOCTL_SET_FRAME_LOSS_SIMULATION but only enables receive direction frame losses.
- emIoControl - EC_IOCTL_SET_RXFRAME_LOSS_SIMULATION
- Parameter
pbyInBuf: [in] Should be set to EC_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
6.7.13. emIoControl - EC_IOCTL_SET_TXFRAME_LOSS_SIMULATION
Same as emIoControl - EC_IOCTL_SET_FRAME_LOSS_SIMULATION but only enables transmit direction frame losses.
- emIoControl - EC_IOCTL_SET_TXFRAME_LOSS_SIMULATION
- Parameter
pbyInBuf: [in] Should be set to EC_NULLdwInBufSize: [in] Should be set to 0pbyOutBuf: [out] Should be set to EC_NULLdwOutBufSize: [in] Should be set to 0pdwNumOutData: [out] Should be set to EC_NULL
- Return
EC_E_NOERROR or error code
6.7.14. Error notifications - general information
For each error an error ID (error code) will be defined. This error ID will be used as the notification code when emNotify() is called. In addition to this notification code the second parameter given to emNotify() contains a pointer to an error notification descriptor of type EC_T_ERROR_NOTIFICATION_DESC. This error notification descriptor contains detailed information about the error.
-
struct EC_T_ERROR_NOTIFICATION_DESC
Public Members
-
union _EC_T_ERROR_NOTIFICATION_PARM
Public Members
-
EC_T_WKCERR_DESC WkcErrDesc
WKC error descriptor
-
EC_T_FRAME_RSPERR_DESC FrameRspErrDesc
Frame response error descriptor
-
EC_T_INITCMD_ERR_DESC InitCmdErrDesc
Master/Slave init command error descriptor
-
EC_T_SLAVE_ERROR_INFO_DESC SlaveErrInfoDesc
Slave Error Info Descriptor
-
EC_T_SLAVES_ERROR_DESC SlavesErrDesc
Slaves Error Descriptor
-
EC_T_MBOX_SDO_ABORT_DESC SdoAbortDesc
SDO Abort
-
EC_T_MBOX_FOE_ABORT_DESC FoeErrorDesc
FoE error code and string
-
EC_T_PDIWATCHDOG_DESC PdiWatchdogDesc
PDI watchodg expired
-
EC_T_SLAVE_NOTSUPPORTED_DESC SlaveNotSupportedDesc
Slave not supported
-
EC_T_SLAVE_UNEXPECTED_STATE_DESC SlaveUnexpectedStateDesc
Slave in unexpected state
-
EC_T_SLAVES_UNEXPECTED_STATE_DESC SlavesUnexpectedStateDesc
Slaves in unexpected state
-
EC_T_EEPROM_CHECKSUM_ERROR_DESC EEPROMChecksumErrorDesc
EEPROM checksum error
-
EC_T_FRAMELOSS_AFTER_SLAVE_NTFY_DESC FramelossAfterSlaveDesc
Frameloss after Slave descriptor
-
EC_T_BAD_CONNECTION_NTFY_DESC BadConnectionDesc
Bad connection descriptor
-
EC_T_WKCERR_DESC WkcErrDesc
-
union _EC_T_ERROR_NOTIFICATION_PARM
If the pointer to this descriptor exists (is not set to EC_NULL) the detailed error information (e.g. information about the slave) is stored in the appropriate structure of a union. These error information structures are described in the following sections.
The EtherCAT master will call emNotify() every time an error is detected. In some cases this will lead to calling this function in every EtherCAT cycle (e.g. if there is no physical connection to the slaves). Using the control interface emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED it is possible to determine which errors shall be signalled and which not.
6.7.15. emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR
To update the process data some EtherCAT commands will be sent cyclically by the master. These commands will address one or multiple slaves. These EtherCAT commands contain a working counter which has to be incremented by each slave that is addressed. The working counter will be checked after the EtherCAT command is received by the master.
If the expected working counter will not match to the working counter of the received command the error emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR will be indicated. The working counter value expected by the master is determined by the EtherCAT configuration (XML) file for each cyclic EtherCAT command (section Config/Cyclic/Frame/Cmd/Cnt).
Detailed error information is stored in structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.
This notification is enabled by default.
-
struct EC_T_WKCERR_DESC
Public Members
-
EC_T_SLAVE_PROP SlaveProp
Slave properties, content is undefined in case of cyclic WKC_ERROR
-
EC_T_SLAVE_PROP SlaveProp
See also
emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation.
6.7.16. emNotify - EC_NOTIFY_MASTER_INITCMD_WKC_ERROR
This error will be indicated in case of a working counter mismatch when sending master init commands. The working counter value expected by the master is determined by the EtherCAT configuration (XML) file for each master init command (section Config/Master/InitCmds/InitCmd/Cnt). In case there is no “Cnt” entry in the XML file for this init command there will be no working counter verification. The working counter has to be incremented by all slaves which have to process this init command.
Detailed error information is stored in structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.
6.7.17. emNotify - EC_NOTIFY_SLAVE_INITCMD_WKC_ERROR
This error will be indicated in case of a working counter mismatch when sending slave init commands. The working counter value expected by the master is determined by the EtherCAT configuration (XML) file for each slave init command (section Config/Slave/InitCmds/InitCmd/Cnt). In case there is no “Cnt” entry in the XML file for this init command there will be no working counter verification.
Detailed error information is stored in structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC. The structure member SlaveProp contains information about the corresponding slave device.
6.7.18. emNotify - EC_NOTIFY_FOE_MBSLAVE_ERROR
This error will be indicated in case a slave notifies an error over FoE.
6.7.19. emNotify - EC_NOTIFY_EOE_MBXSND_WKC_ERROR
This error will be indicated in case the working counter of a EoE mailbox write command was not set to the expected value of 1.
Detailed error information is stored in structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC. The structure member SlaveProp contains information about the corresponding slave device.
6.7.20. emNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR
This error will be indicated in case the working counter of a CoE mailbox write command was not set to the expected value of 1.
Detailed error information is stored in structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC. The structure member SlaveProp contains information about the corresponding slave device.
6.7.21. emNotify - EC_NOTIFY_FOE_MBXSND_WKC_ERROR
This error will be indicated in case the working counter of a FoE mailbox write command was not set to the expected value of 1.
6.7.22. emNotify - EC_NOTIFY_VOE_MBXSND_WKC_ERROR
This error will be indicated in case the working counter of a VoE mailbox write command was not set to the expected value of 1.
Detailed error information is stored in structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC. The structure member SlaveProp contains information about the corresponding slave device.
6.7.23. emNotify - EC_NOTIFY_S2SMBX_ERROR
This error will be indicated in case a Slave-To-Slave mailbox transfer fails.
See also
6.7.24. emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR
This error will be indicated if the actually received Ethernet frame does not match to the frame expected or if a expected frame was not received.
This notification is enabled by default.
See also
emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation.
Missing response (timeout, eRspErr_NO_RESPONSE/ eRspErr_FRAME_RETRY) acyclic frames:
Acyclic Ethernet frames are internally queued by the master and sent to the slaves at a later time (usually after sending cyclic frames).
The master will monitor the time between queueing such a frame and receiving the result. If a maximum time is exceeded then this error will be indicated. This maximum time will be determined by the parameter dwEcatCmdTimeout when the master is initialized
See also
The master will retry sending the frame if the master configuration parameter dwEcatCmdMaxRetries is set to a value greater than 1. In case of a retry the eRspErr_FRAME_RETRY error is signalled, if the number of retries has elapsed the eRspErr_NO_RESPONSE error is signalled.
Possible reasons:
- the frame was not received at all (due to bus problems)
In this case the achErrorInfo member of the error notification descriptor will contain the string “L”.
- the frame was sent too late by the master due to a improper configuration.
In this case the achErrorInfo member of the error notification descriptor will contain the string “T”.
To avoid this error the configuration may be changed as follows:
-> higher value for master configuration parameter dwMaxAcycCmdsPerCycle -> shorter master timer cycle, i.e. shorter period between two calls to
emExecJob(eUsrJob_MasterTimer)
-> higher timeout value (master configuration parameter dwEcatCmdTimeout)
If the frame was sent too late by the master (due to improper configuration values) it will also be received too late and the master then signals an eRspErr_WRONG_IDX or eRspErr_UNEXPECTED error (as the master then doesn’t expect to receive this frame).
Missing response (timeout, eRspErr_NO_RESPONSE) cyclic frames:
A response to all cyclic frames must occur until the next cycle starts. If the first cyclic frame is sent the master checks whether all cyclic frames of the last cycle were received. If there is one frame missing this error is indicated.
Possible reasons:
the frame was not received (due to bus problems)
- too many or too long acyclic frames are sent in between sending cyclic frames by the master due to a improper configuration, to avoid these error notifications the configuration may be changed as follows:
lower value for master configuration parameter dwMaxAcycCmdsPerCycle
higher cyclic timer period, i.e. less calls to
emExecJob()(eUsrJob_SendAllCycFrames)
- non-deterministic sending of acyclic frames.
Sending acyclic frames by calling
emExecJob()(eUsrJob_SendAcycFrames) have to be properly scheduled with sending cyclic frames by callingemExecJob()(eUsrJob_SendAllCycFrames).
Using the control interface emIoControl - EC_IOCTL_SET_FRAME_RESPONSE_ERROR_NOTIFY_MASK it is possible to determine which response errors shall be signalled and which not.
Detailed error information is stored in structure EC_T_FRAME_RSPERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.
-
struct EC_T_FRAME_RSPERR_DESC
Public Members
-
EC_T_FRAME_RSPERR_TYPE EErrorType
Frame response error type
-
EC_T_BYTE byEcCmdHeaderIdxSet
Expected IDX value, this value is valid only for acyclic frames in case EErrorType is not equal to eRspErr_UNEXPECTED
-
EC_T_FRAME_RSPERR_TYPE EErrorType
6.7.25. emNotify - EC_NOTIFY_SLAVE_INITCMD_RESPONSE_ERROR
This error code will be indicated if a slave does not respond appropriately while sending slave init commands. The slave init commands are defined in the EtherCAT configuration (XML) file (Config/Slave/InitCmds/InitCmd). A timeout value for these commands may also be defined in the configuration file (Config/Slave/InitCmds/InitCmd/Timeout). If there is no timeout value defined here the frame response is expected within one single cycle.
This notification is enabled by default.
Detailed error information is stored in structure EC_T_INITCMD_ERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.
-
struct EC_T_INITCMD_ERR_DESC
Public Members
-
EC_T_SLAVE_PROP SlaveProp
Slave properties
-
EC_T_INITCMD_ERR_TYPE EErrorType
Init command error type
-
EC_T_SLAVE_PROP SlaveProp
See also
emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation
6.7.26. emNotify - EC_NOTIFY_MBSLAVE_INITCMD_TIMEOUT
This error is identical to error code emNotify - EC_NOTIFY_SLAVE_INITCMD_RESPONSE_ERROR but it will be indicated in case of timeouts when processing mailbox init commands.
The timeout value used for CoE mailbox slaves is defined in the EtherCAT configuration (XML) file (Config/Slave/Mailbox/CoE/InitCmds/InitCmd/Timeout). In case this value is set to 0 a fixed timeout value of 500 msec will be used by the EtherCAT master. The timeout value used for EoE mailbox slaves will be set fixed to a value of 5000 msec.
6.7.27. emNotify - EC_NOTIFY_MASTER_INITCMD_RESPONSE_ERROR
This error code will be indicated if a missing or wrong command response was detected while sending master init commands. The master init commands are defined in the EtherCAT configuration (XML) file (Config/Master/InitCmds/InitCmd). A timeout value for these commands may also be defined in the configuration file (Config/Master/InitCmds/InitCmd/Timeout). If there is no timeout value defined here the frame response is expected within one single cycle.
Detailed error information is stored in structure EC_T_INITCMD_ERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.
6.7.28. emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL
When processing cyclic frames the EtherCAT master checks whether all slaves are still in OPERATIONAL state. If at least one slave device is not OPERATIONAL this error will be indicated.
6.7.29. emNotify - EC_NOTIFY_ALL_DEVICES_OPERATIONAL
When processing cyclic frames the EtherCAT master checks whether all slaves are still in OPERATIONAL state. This will be notified after emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL and all the slaves are back in OPERATIONAL state.
6.7.30. emNotify - EC_NOTIFY_STATUS_SLAVE_ERROR
When processing cyclic frames the EtherCAT master checks if at least one slave has the ERROR bit in the AL-STATUS register set. In that case this error will be indicated. The master will then automatically determine detailed error information of the slave(s) indicating an error and acknowledge the error status. The application will get a emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO notification for each such slave. Usually those slaves will enter safe-operational state in this case. It is the application’s response how to further handle such error cases.
This notification is enabled by default.
See also
emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation
6.7.31. emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO
Every time the master detects a slave error, the Error bit on the specific slave is cleared and this error code will be signalled to the application. Detailed error information is stored in structure EC_T_SLAVE_ERROR_INFO_DESC of EC_T_ERROR_NOTIFICATION_DESC. This notification is enabled by default.
-
struct EC_T_SLAVE_ERROR_INFO_DESC
Public Members
-
EC_T_SLAVE_PROP SlaveProp
Slave properties
-
EC_T_SLAVE_PROP SlaveProp
See also
emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation
6.7.32. emNotify - EC_NOTIFY_SLAVES_ERROR_STATUS
This notification collects notifications of type emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO. Notification is given on either collection full or master state changed whatever comes first.
This notification is disabled by default.
-
struct EC_T_SLAVES_ERROR_DESC
Public Members
-
EC_T_SLAVES_ERROR_DESC_ENTRY SlaveError[MAX_SLAVES_ERROR_NTFY_ENTRIES]
Slave error descriptions
-
EC_T_SLAVES_ERROR_DESC_ENTRY SlaveError[MAX_SLAVES_ERROR_NTFY_ENTRIES]
See also
emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the activation
6.7.33. emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE
This error is signalized every time a slave changes into an unexpected state. Detailed error information is stored in structure EC_T_SLAVE_UNEXPECTED_STATE_DESC of EC_T_ERROR_NOTIFICATION_DESC. This notification is enabled by default.
-
struct EC_T_SLAVE_UNEXPECTED_STATE_DESC
Public Members
-
EC_T_SLAVE_PROP SlaveProp
Slave properties
-
EC_T_STATE curState
Current state
-
EC_T_STATE expState
Expected state
-
EC_T_SLAVE_PROP SlaveProp
See also
emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation
6.7.34. emNotify - EC_NOTIFY_SLAVES_UNEXPECTED_STATE
This notification collects notifications of type emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE. Notification is given on either collection full or master state changed whatever comes first. This notification is disabled by default.
-
struct EC_T_SLAVES_UNEXPECTED_STATE_DESC
Public Members
-
EC_T_SLAVES_UNEXPECTED_STATE_DESC_ENTRY SlaveStates[MAX_SLAVES_UNEXPECTED_STATE_NTFY_ENTRIES]
Slave state change descriptions
-
EC_T_SLAVES_UNEXPECTED_STATE_DESC_ENTRY SlaveStates[MAX_SLAVES_UNEXPECTED_STATE_NTFY_ENTRIES]
See also
emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the activation
6.7.35. emNotify - EC_NOTIFY_ETH_LINK_NOT_CONNECTED
This notification will be indicated if the Ethernet link is disconnected. This error is never indicated if the Link Layer does not support detection of a missing link cable.
In case of permanent frame loss no slaves can be found although the slaves are connected. This does not affect link connection detection therefore this notification will be not indicated on permanent frame loss.
6.7.36. emNotify - EC_NOTIFY_ETH_LINK_CONNECTED
This notification will be indicated if the Ethernet link is reconnected after a disconnect. This notification is never indicated if the Link Layer does not support detection of a missing link cable.
6.7.37. emNotify - EC_NOTIFY_CLIENTREGISTRATION_DROPPED
This notification will be indicated if the client registration was dropped because emConfigureMaster() was called by another thread. The notification has the following parameter:
EC_T_DWORD dwDeinitForConfiguration; /* 0 = terminating Master, 1 = restarting Master */
6.7.38. emNotify - EC_NOTIFY_EEPROM_CHECKSUM_ERROR
This error is signalized every time a EEPROM checksum error is detected.
Detailed error information is stored in structure EC_T_EEPROM_CHECKSUM_ERROR_DESC of EC_T_ERROR_NOTIFICATION_DESC.
-
struct EC_T_EEPROM_CHECKSUM_ERROR_DESC
Public Members
-
EC_T_SLAVE_PROP SlaveProp
Slave properties
-
EC_T_SLAVE_PROP SlaveProp
6.7.39. emNotify - EC_NOTIFY_PDIWATCHDOG
This error is signalized every time a PDI watchdog error is detected. Detailed error information is stored in structure EC_T_PDIWATCHDOG_DESC of EC_T_ERROR_NOTIFICATION_DESC.
-
struct EC_T_PDIWATCHDOG_DESC
Public Members
-
EC_T_SLAVE_PROP SlaveProp
Slave properties
-
EC_T_SLAVE_PROP SlaveProp
6.7.40. ecatGetText
6.7.41. ecatPerfMeasInit
-
EC_T_VOID ecatPerfMeasInit(EC_T_TSC_MEAS_DESC *pTscMeasDesc, EC_T_UINT64 dwlFreqSet, EC_T_DWORD dwNumMeas, EC_T_FNMESSAGE pfnMessage)
- Parameters
pTscMeasDesc – [in,out] measurement descriptor
dwlFreqSet – [in] TSC frequency, 0: auto-calibrate
dwNumMeas – [in] number of elements to be allocated in in pTscMeasDesc->aTscTime
pfnMessage – [in] Reserved. Set to EC_NULL
6.7.42. ecatPerfMeasDeinit
6.7.43. ecatPerfMeasEnable
6.7.44. ecatPerfMeasDisable
6.7.45. ecatPerfMeasStart
6.7.46. ecatPerfMeasEnd
-
EC_T_TSC_TIME *ecatPerfMeasEnd(EC_T_TSC_MEAS_DESC *pTscMeasDesc, EC_T_DWORD dwIndex)
- Parameters
pTscMeasDesc – [in,out] measurement descriptor
dwIndex – [in] measurement index
6.7.47. ecatPerfMeasReset
6.7.48. ecatPerfMeasShow
6.7.49. ecatPerfMeasSetIrqCtlEnabled
6.7.50. emLogFrameEnable
-
static EC_T_DWORD ecatLogFrameEnable(EC_T_PFLOGFRAME_CB pvLogFrameCallBack, EC_T_VOID *pvContext)
-
EC_T_DWORD emLogFrameEnable(EC_T_DWORD dwInstanceID, EC_T_PFLOGFRAME_CB pvLogFrameCallBack, EC_T_VOID *pvContext)
Setup a callback function to log the EtherCAT network traffic.
The callback function is called by the cyclic task. Therefore the code inside the callback has to be fast and non-blocking. The callback parameter dwLogFlags can be used as a filter to log just specific frames. The master discards the frame if the callback function modifies the Ethernet frame type at byte offset 12.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pvLogFrameCallBack – [in] Pointer to frame logging callback function
pvContext – [in] Pointer to function specific context
- Returns
EC_E_NOERROR or error code
-
typedef EC_T_VOID (*EC_T_PFLOGFRAME_CB)(EC_T_VOID *pvContext, EC_T_DWORD dwLogFlags, EC_T_DWORD dwFrameSize, EC_T_BYTE *pbyFrame)
Note
The master discards the frame if the callback function modifies the Ethernet frame type at byte offset 12.
- Parameters
pvContext – [in] Arbitrarily application-defined parameter passed to callback
dwLogFlags – [in] Frame logging flags, EC_LOG_FRAME_FLAG_…, e.g. EC_LOG_FRAME_FLAG_RX_FRAME
dwFrameSize – [in] Size of frame in bytes
pbyFrame – [in] Pointer to frame data
/********************************************************************************/
/** \brief Handler to log frames.
*
* CAUTION: Called by cyclic task!!! Do not consume to much CPU time!!!
*/
EC_T_VOID LogFrameHandler(EC_T_VOID* pvContext, EC_T_DWORD dwLogFlags, EC_T_DWORD dwFrameSize, EC_T_BYTE* pbyFrame)
{
EC_T_STATE eMasterState;
/* get master state */
eMasterState = (EC_T_STATE)(dwLogFlags & EC_LOG_FRAME_FLAG_MASTERSTATE_MASK);
/* skip tx frame */
if ((S_dwLogFrameLevel == 3) && !(dwLogFlags & EC_LOG_FRAME_FLAG_RX_FRAME))
return;
/* skip cyclic frame */
if ((S_dwLogFrameLevel == 2) && !(dwLogFlags & EC_LOG_FRAME_FLAG_ACYC_FRAME))
return;
/* skip red frame */
if (dwLogFlags & EC_LOG_FRAME_FLAG_RED_FRAME)
return;
/* do something with pbyFrame ... */
}
6.7.51. emLogFrameDisable
-
EC_T_DWORD emLogFrameDisable(EC_T_DWORD dwInstanceID)
Disable the frame logging callback.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
- Returns
EC_E_NOERROR or error code
6.7.52. emGetMasterInfo
-
static EC_T_DWORD ecatGetMasterInfo(EC_T_MASTER_INFO *pMasterInfo)
-
EC_T_DWORD emGetMasterInfo(EC_T_DWORD dwInstanceID, EC_T_MASTER_INFO *pMasterInfo)
Get generic information about the Master.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pMasterInfo – [out] Master information
- Returns
EC_E_NOERROR if successful
EC_E_INVALIDSTATE if master isn’t initialized
EC_E_INVALIDPARM if dwInstanceID is out of range or pParms is NULL or contains values out of range
EC_E_ADS_IS_RUNNING if ADS server is running
-
struct EC_T_MASTER_INFO
Public Members
-
EC_T_BUS_DIAGNOSIS_INFO BusDiagnosisInfo
Bus diagnostics
-
EC_T_MAILBOX_STATISTICS MailboxStatistics
Mailbox statistics
-
EC_T_BUS_DIAGNOSIS_INFO BusDiagnosisInfo
-
struct EC_T_MAILBOX_STATISTICS
Public Members
-
EC_T_STATISTIC_TRANSFER_DUPLEX Aoe
AoE mailbox transfer statistics
-
EC_T_STATISTIC_TRANSFER_DUPLEX Coe
CoE mailbox transfer statistics
-
EC_T_STATISTIC_TRANSFER_DUPLEX Eoe
EoE mailbox transfer statistics
-
EC_T_STATISTIC_TRANSFER_DUPLEX Foe
FoE mailbox transfer statistics
-
EC_T_STATISTIC_TRANSFER_DUPLEX Soe
SoE mailbox transfer statistics
-
EC_T_STATISTIC_TRANSFER_DUPLEX Voe
VoE mailbox transfer statistics
-
EC_T_STATISTIC_TRANSFER_DUPLEX RawMbx
Raw mailbox transfer statistics
-
EC_T_STATISTIC_TRANSFER_DUPLEX Aoe
-
struct EC_T_STATISTIC_TRANSFER_DUPLEX
Public Members
-
EC_T_STATISTIC_TRANSFER Read
Number of read transfers
-
EC_T_STATISTIC_TRANSFER Write
Number of write transfers
-
EC_T_STATISTIC_TRANSFER Read
-
struct EC_T_STATISTIC_TRANSFER
Public Members
-
EC_T_STATISTIC Cnt
Number of transfers
-
EC_T_STATISTIC Bytes
Number of bytes transferred
-
EC_T_STATISTIC Cnt
6.7.53. emGetMemoryUsage
-
EC_T_DWORD emGetMemoryUsage(EC_T_DWORD dwInstanceID, EC_T_DWORD *pdwCurrentUsage, EC_T_DWORD *pdwMaxUsage)
Returns information about memory usage.
All calls to malloc/free and new/delete are monitored.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pdwCurrentUsage – [out] Current memory usage in Bytes at the time where this function is called
pdwMaxUsage – [out] Maximum memory usage in Bytes since initialization at the time where this function is called
- Returns
EC_E_NOERROR or error code
6.7.54. emGetMasterDump
-
static EC_T_DWORD ecatGetMasterDump(EC_T_BYTE *pbyBuffer, EC_T_DWORD dwBufferSize, EC_T_DWORD *pdwDumpSize)
-
EC_T_DWORD emGetMasterDump(EC_T_DWORD dwInstanceID, EC_T_BYTE *pbyBuffer, EC_T_DWORD dwBufferSize, EC_T_DWORD *pdwDumpSize)
The dump contains relevant information about the master and slave status.
The dump is only intended for internal troubleshooting at acontis Amongst others it contains the following descriptors:
The buffer is written until all relevant data have been dumped or buffer size has been exceeded.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pbyBuffer – [in] Preallocated buffer to dump log data
dwBufferSize – [in] Size of preallocated buffer
pdwDumpSize – [out] Size of master dump
- Returns
EC_E_NOMEMORY if buffer too small
6.7.55. emGetMasterSyncUnitInfoNumOf
6.7.56. emGetMasterSyncUnitInfo
-
static EC_T_DWORD ecatGetMasterSyncUnitInfo(EC_T_WORD wMsuId, EC_T_MSU_INFO *pMsuInfo)
-
EC_T_DWORD emGetMasterSyncUnitInfo(EC_T_DWORD dwInstanceID, EC_T_WORD wMsuId, EC_T_MSU_INFO *pMsuInfo)
Get information about specific Master Sync Unit.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
wMsuId – [in] Master Sync Unit to get the information from
pMsuInfo – [out] Pointer to an EC_T_MSU_INFO structure receiving the Master Sync Unit information
- Returns
EC_E_NOERROR or error code
MSU_ID_ALL_INFO_ENTRIES retrieves the information from all master sync units at once. The application must ensure that pMsuInfo is capable for all entries.
See also
6.7.57. emBadConnectionsDetect
-
EC_T_DWORD emBadConnectionsDetect(EC_T_DWORD dwInstanceID, EC_T_DWORD dwTimeout)
Detects bad connections.
Reads the error counters of all slaves and analyzes the slave ESC error counters:
Invalid Frame Counter (0x0300),
RX Error Counter (0x0301),
Lost Link Counter (0x0310),
whether there is a problem in the area PHY - connector - cable - connector - PHY. If one of the above error counters shows a value not equal to zero, an EC_NOTIFY_BAD_CONNECTION is generated, which contains the exact position of the faulty connection. It is recommended to call emBadConnectionsReset() on startup of EC-Master to ensure that all error counters of all slaves are in a defined state.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
dwTimeout – [in] Timeout [ms] May not be EC_NOWAIT!
- Returns
EC_E_NOERROR or error code
See also
6.7.58. emBadConnectionsReset
6.7.59. emNotify - EC_NOTIFY_BAD_CONNECTION
This error is signalized every time a bad connection is detected within the call of emBadConnectionsDetect(). It contains the exact location of the bad connection between two slaves. This notification is enabled by default.
-
struct EC_T_BAD_CONNECTION_NTFY_DESC
Public Members
-
EC_T_SLAVE_PROP SlavePropParent
slave properties of parent slave
-
EC_T_SLAVE_PROP SlavePropChild
slave properties of child slave
-
EC_T_SLAVE_PROP SlavePropParent
See also
emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation
6.7.60. emSelfTestScan
-
static EC_T_DWORD ecatSelfTestScan(EC_T_SELFTESTSCAN_PARMS *pParms)
-
EC_T_DWORD emSelfTestScan(EC_T_DWORD dwInstanceID, EC_T_SELFTESTSCAN_PARMS *pParms)
Self test scan.
Send a burst of numerous frames and analyze the slave connections. After deactivating the job task, frames will be sent as fast as the LinkLayer can send them. The size of the frames increases and decreases between the defined limits. Dependent on the parameters the BadConnectionsDetect API will analyze the slave connections.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pParms – [in] Self-test scan 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 pParms is NULL or contains values out of range
EC_E_BAD_CONNECTION if bad connection was detected
EC_E_FRAME_LOST if frame(s) lost during self-test
EC_E_NOTSUPPORTED if not in polling mode
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive
-
struct EC_T_SELFTESTSCAN_PARMS
Public Members
-
EC_T_DWORD dwFrameCount
[in] Total number of frames sent during the self-test. Default value is 1500. A value of 0 let the current setting unmodified.
-
EC_T_DWORD dwFrameSizeMin
[in] Min frame size [bytes]. Default value is 60. A value of 0 let the current setting unmodified.
-
EC_T_DWORD dwFrameSizeMax
[in] Max frame size [bytes]. Default value is 1514. A value of 0 let the current setting unmodified.
-
EC_T_DWORD dwFrameSizeStep
[in] Size [bytes] by which the frame increases or decreases continuously during the self-test. Default value is 1. A value of 0 let the current setting unmodified.
-
EC_T_UINT64 qwFrameRoundtripTimeAvg
[out] Roundtrip time average [us]. Time taken from sending to receiving the frame (master application level).
-
EC_T_DWORD dwFrameCount
See also