2.3. Programmer’s Guide
2.3.1. emDcmConfigure
-
EC_T_DWORD emDcmConfigure(EC_T_DWORD dwInstanceID, EC_T_DCM_CONFIG *pDcmConfig, EC_T_DWORD dwInSyncTimeout)
Configure DC master synchronization.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pDcmConfig – [in] Configuration information, a pointer to a structure of type EC_T_DCM_CONFIG.
dwInSyncTimeout – [in] Currently not implemented.
- Returns
EC_E_NOERROR or error code
-
struct EC_T_DCM_CONFIG
Public Members
-
EC_T_DCM_MODE eMode
[in] DCM mode
-
EC_T_DCM_CONFIG_BUSSHIFT BusShift
[in] BusShift configuration. Valid if eMode is set to eDcmMode_BusShift
-
EC_T_DCM_CONFIG_MASTERSHIFT MasterShift
[in] MasterShift configuration. Valid if eMode is set to eDcmMode_MasterShift
-
EC_T_DCM_CONFIG_LINKLAYERREFCLOCK LinkLayerRefClock
[in] LinkLayerRefClock configuration. Valid if eMode is set to eDcmMode_LinkLayerRefClock
-
EC_T_DCM_CONFIG_MASTERREFCLOCK MasterRefClock
[in] MasterRefClock configuration. Valid if eMode is set to eDcmMode_MasterRefClock
-
EC_T_DCM_CONFIG_DCX Dcx
[in] DCX configuration. Valid if eMode is set to eDcmMode_Dcx
-
EC_T_DCM_MODE eMode
-
struct EC_T_DCM_CONFIG_BUSSHIFT
Public Members
-
EC_T_INT nCtlSetVal
[in] Controller set value [ns]. This is the time distance between the cyclic frame send time and the DC base on bus (SYNC0 if shift is zero).
-
EC_T_INT nCtlGain
[in] Proportional gain in ppt (part per thousand). Default is value 2. A value of 0 let the current setting unmodified.
-
EC_T_INT nCtlDriftErrorGain
[in] Multiplier for drift error. Default value is 3. A value of 0 let the current setting unmodified
-
EC_T_INT nMaxValidVal
[in] Error inputs above this value are considered invalid. If error input prediction is valid then the difference between the error input and the expected value is taken. Default value is 3000. A value of 0 let the current setting unmodified
-
EC_T_BOOL bLogEnabled
[in] If set to EC_TRUE, logging information are generated and can be get calling emDcmGetLog
-
EC_T_DWORD dwInSyncLimit
[in] Limit [ns] for InSync monitoring. Default value is 4000. A value of 0 let the current setting unmodified
-
EC_T_DWORD dwInSyncSettleTime
[in] Settle time [ms] for InSync monitoring. Default value is 1500. A value of 0 let the current setting unmodified
-
EC_T_BOOL bCtlOff
[in] If set to EC_TRUE, control loop is disabled. Combined with bLogEnabled, it makes possible to analyze the natural drift between the stack cycle and the reference clock
-
EC_T_INT nCtlSetVal
-
struct EC_T_DCM_CONFIG_MASTERSHIFT
Public Members
-
EC_T_INT nCtlSetVal
[in] Controller set value [ns]. This is the time distance between the cyclic frame send time and the DC base on bus (SYNC0 if shift is zero)
-
EC_T_INT nCtlGain
[in] Proportional gain in ppt (part per thousand). Default is value 2. A value of 0 let the current setting unmodified
-
EC_T_INT nCtlDriftErrorGain
[in] Multiplier for drift error. Default value is 3. A value of 0 let the current setting unmodified
-
EC_T_INT nMaxValidVal
[in] Error inputs above this value are considered invalid. If error input prediction is valid then the difference between the error input and the expected value is taken. Default value is 3000. A value of 0 let the current setting unmodified
-
EC_T_BOOL bLogEnabled
[in] If set to EC_TRUE, logging information are generated and can be get calling emDcmGetLog
-
EC_T_DWORD dwInSyncLimit
[in] Limit [ns] for InSync monitoring. Default value is 4000. A value of 0 let the current setting unmodified
-
EC_T_DWORD dwInSyncSettleTime
[in] Settle time [ms] for InSync monitoring. Default value is 1500. A value of 0 let the current setting unmodified
-
EC_T_BOOL bCtlOff
[in] If set to EC_TRUE, control loop is disabled. Combined with bLogEnabled, it makes possible to analyze the natural drift between the stack cycle and the reference clock. Also it provides reading of current adjustment value using emDcmGetAdjust function
-
EC_T_DC_STARTTIME_CB_DESC DcStartTimeCallbackDesc
[in] If not null, DC start time calculated by application, otherwise by master. See also EC_T_DC_STARTTIME_CB_DESC. Shift value configured in ENI will still be applied
-
EC_T_INT nCtlSetVal
-
struct EC_T_DCM_CONFIG_LINKLAYERREFCLOCK
Public Members
-
EC_T_INT nCtlSetVal
[in] Controller set value [ns]. This is the time distance between the cyclic frame send time and the DC base on bus (SYNC0 if shift is zero)
-
EC_T_BOOL bLogEnabled
[in] If set to EC_TRUE, logging information are generated and can be get calling emDcmGetLog
-
EC_T_DC_STARTTIME_CB_DESC DcStartTimeCallbackDesc
[in] If not null, DC start time calculated by application, otherwise by master. See also EC_T_DC_STARTTIME_CB_DESC. Shift value configured in ENI will still be applied.
-
EC_T_INT nCtlSetVal
-
struct EC_T_DCM_CONFIG_MASTERREFCLOCK
Public Members
-
EC_T_INT nCtlSetVal
[in] Controller set value [ns]. This is the time distance between the cyclic frame send time and the DC base on bus (SYNC0 if shift is zero)
-
EC_T_BOOL bLogEnabled
[in] If set to EC_TRUE, logging information are generated and can be get calling emDcmGetLog
-
EC_T_DWORD dwInSyncLimit
[in] Limit [ns] for InSync monitoring. Default value is 4000. A value of 0 let the current setting unmodified
-
EC_T_INT nCtlSetVal
Contains the configuration information for the DCX external synchronization mode.
See also
Feature Pack “External Synchronization” for further details.
-
struct EC_T_DC_STARTTIME_CB_DESC
Public Members
-
EC_T_VOID *pvContext
[in] Context pointer. It is used as parameter when the callback function is called
-
EC_PF_DC_STARTTIME_CB pfnCallback
[in] Dc start time callback function pointer. If not null, DC start time calculated by application, otherwise by master
-
EC_T_VOID *pvContext
-
typedef EC_T_DWORD (*EC_PF_DC_STARTTIME_CB)(EC_T_VOID *pvContext, EC_T_WORD wSlaveFixedAddr, EC_T_UINT64 *pqwDcStartTime)
EC-Master requests DC start time for every single slave from a given callback DcStartTimeCallbackDesc with slave station address as input parameter. The slave specific DC start time value will be passed directly to the slave without modifications by master. This means no other values like nCtlSetVal will be added. Shift value configured in ENI will still be applied.
- Parameters
pvContext – [in] Context pointer. It is used as parameter when the callback function is called.
wSlaveFixedAddr – [in] Slave fixed address.
pqwDcStartTime – [out] DC start time for specific slave.
- Returns
EC_E_NOERROR or error code
2.3.2. emDcmGetStatus
-
static EC_T_DWORD ecatDcmGetStatus(EC_T_DWORD *pdwErrorCode, EC_T_INT *pnDiffCur, EC_T_INT *pnDiffAvg, EC_T_INT *pnDiffMax)
-
EC_T_DWORD emDcmGetStatus(EC_T_DWORD dwInstanceID, EC_T_DWORD *pdwErrorCode, EC_T_INT *pnDiffCur, EC_T_INT *pnDiffAvg, EC_T_INT *pnDiffMax)
Get DC master synchronization controller status.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pdwErrorCode – [out] Pointer to current error code of the DCM controller. Possible values are:
EC_E_NOTREADY DCM control loop is not running
EC_E_BUSY DCM control loop is running and try to get InSync
DCM_E_MAX_CTL_ERROR_EXCEED Set if the controller error exceeds the InSyncLimit
DCM_E_DRIFT_TO_HIGH DCM control loop not able to compensate drift. Drift above 600ppm.
pnDiffCur – [out] Pointer to current difference between set value and actual value of controller in nanoseconds.
pnDiffAvg – [out] Pointer to average difference between set value and actual value of controller in nanoseconds
pnDiffMax – [out] Pointer to maximum difference between set value and actual value of controller in nanoseconds
- Returns
EC_E_NOERROR if status retrieval was successful
EC_E_NOTSUPPORTED the DC feature is not supported/switched off. EC-Master stack has to be compiled with DC support see “define INCLUDE_DC_SUPPORT”
EC_NULL does not appear in normal flow, if EC_NULL is returned we are in a very exceptional case where m_poDcm == NULL (SW error detection)
2.3.3. emDcmResetStatus
2.3.4. emDcmGetBusShiftConfigured
-
EC_T_DWORD emDcmGetBusShiftConfigured(EC_T_DWORD dwInstanceID, EC_T_BOOL *pbBusShiftConfigured)
Determines if DCM Bus Shift is configured/possible in configuration (ENI file)
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pbBusShiftConfigured – [out] EC_TRUE if DCM bus shift mode is supported by the current configuration
- Returns
EC_E_NOERROR or error code
2.3.5. emDcmGetLog
-
EC_T_DWORD emDcmGetLog(EC_T_DWORD dwInstanceID, EC_T_CHAR **pszLog)
Get logging information from the DCM controller.
This function returns non-zero pointer only if bLogEnabled was set to EC_TRUE in EC_T_DCM_CONFIG.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pszLog – [out] Pointer to a string containing the current logging information
- Returns
EC_E_NOERROR or error code
See also
Controller adjustment for content description of pszLog
2.3.6. emIoControl - EC_IOCTL_DCM_GET_LOG
Get logging information from the DCM controller.
- emIoControl - EC_IOCTL_DCM_GET_LOG
- Parameter
pbyInBuf
: [in] Should be set to EC_NULLdwInBufSize
: [in] Should be set to 0pbyOutBuf
: [out] Pointer to struct EC_T_DCM_LOGdwOutBufSize
: [in] Size of the output buffer in bytespdwNumOutData
: [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer pbyOutBuf
- Return
EC_E_NOERROR or error code
2.3.7. emDcmShowStatus
2.3.8. emDcmGetAdjust
-
EC_T_DWORD emDcmGetAdjust(EC_T_DWORD dwInstanceID, EC_T_INT *pnAdjustPermil)
Returns the current adjustment value for the timer.
bCtlOff must be set to EC_TRUE in EC_T_DCM_CONFIG to enable external adjustment.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pnAdjustPermil – [out] Current adjustment value of the timer.
- Returns
EC_E_NOERROR or error code
2.3.9. DCM specific error codes
2.3.10. Notifications
At startup the master raises the notifications emNotify - EC_NOTIFY_DC_SLV_SYNC, emNotify - EC_NOTIFY_DC_STATUS and emNotify - EC_NOTIFY_DCM_SYNC at master state transition from INIT to PREOP.
The order is typically as follows ( emNotify - EC_NOTIFY_DCM_SYNC may be before or after reaching PREOP):
EC_NOTIFY_STATECHANGED(INIT)[…]
EC_NOTIFY_DC_SLV_SYNC […]
EC_NOTIFY_DC_STATUS […]
[EC_NOTIFY_DCM_SYNC] […]
EC_NOTIFY_STATECHANGED(PREOP) […]
[EC_NOTIFY_DCM_SYNC] […]
EC_NOTIFY_STATECHANGED(SAFEOP) […]
EC_NOTIFY_STATECHANGED(OP) […]
2.3.11. emNotify - EC_NOTIFY_DCM_SYNC
DCM InSync notification.
This notification is enabled by default.
- emNotify - EC_NOTIFY_DCM_SYNC
- Parameter
pbyInBuf
: [in] pointer to notification descriptor EC_T_DCM_SYNC_NTFY_DESCdwInBufSize
: [in] sizeof(EC_T_DCM_SYNC_NTFY_DESC).pbyOutBuf
: [out] Should be set to EC_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [out] Should be set to EC_NULL
-
struct EC_T_DCM_SYNC_NTFY_DESC
Public Members
-
EC_T_DWORD IsInSync
[in] EC_TRUE as long as time of master and reference clock are in sync. False if the InSyncLimit from the bus shift configuration is exceeded
-
EC_T_INT nCtlErrorNsecCur
[in] Current difference [ns] between set value and actual value of controller
-
EC_T_DWORD IsInSync
See also
emIoControl - EC_IOCTL_SET_NOTIFICATION_ENABLED in the EC-Master Class B documentation for how controls the deactivation