6.9. Slave control and status functions

6.9.1. esGetNumConfiguredSlaves

EC_T_DWORD esGetNumConfiguredSlaves(EC_T_DWORD dwInstanceID)

Returns number of slaves which are configured in the ENI.

Parameters

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

Returns

Number of slaves

6.9.2. esGetNumConnectedSlaves

EC_T_DWORD esGetNumConnectedSlaves(EC_T_DWORD dwInstanceID)

Get amount of currently connected slaves.

Parameters

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

Returns

Number of connected slaves

6.9.3. esGetSlaveId

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

Example

            /* get slave id of slave with station address 1001 */
            EC_T_DWORD dwSlaveId = esGetSlaveId(dwSimulatorId, 1001);
            if (INVALID_SLAVE_ID == dwSlaveId)
            {
                dwRetVal = EC_E_NOTFOUND;
                goto Exit;
            }

6.9.4. esGetSlaveIdAtPosition

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

Example

            /* get slave id of third slave (auto inc address 0, -1, -2, ...) */
            EC_T_DWORD dwSlaveId = esGetSlaveIdAtPosition(dwSimulatorId, (EC_T_WORD)-2);
            if (INVALID_SLAVE_ID == dwSlaveId)
            {
                dwRetVal = EC_E_NOTFOUND;
                goto Exit;
            }

6.9.5. esGetSlaveState

EC_T_DWORD esGetSlaveState(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 EtherCAT stack 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

6.9.6. esSetSlaveState

EC_T_DWORD esSetSlaveState(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_WORD wDeviceState, EC_T_DWORD dwTimeout)

Set a specified slave into the requested EtherCAT 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.

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

Parameters

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

• dwSlaveId – [in] Slave ID

• wDeviceState – [in] Requested device state. See DEVICE_STATE_…

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

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if EtherCAT stack 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 EtherCAT stack 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

6.9.7. esIsSlavePresent

EC_T_DWORD esIsSlavePresent(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 EtherCAT stack isn’t initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range

• EC_E_NOTFOUND if no slave matching dwSlaveId can be found

6.9.8. esGetSlaveProp

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

Determines the properties of the slave device.

deprecated Use esGetCfgSlaveInfo 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

6.9.9. esGetSlavePortState

EC_T_DWORD esGetSlavePortState(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 (ESC Register 0x110 Bit 9, 11, 13, 15)

  xxxx : Loop closed 1=yes, 0=no (ESC Register 0x110 Bit 8, 10, 12, 14)

  yyyy : Link established 1=yes, 0=no (ESC Register 0x110 Bit 4, 5, 6, 7)

  zzzz : Slave connected 1=yes, 0=no (zzzz = logical result of w,x,y)

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if EtherCAT stack 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

6.9.10. esGetSlaveInpVarInfoNumOf

EC_T_DWORD esGetSlaveInpVarInfoNumOf(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 EtherCAT stack 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.9.11. esGetSlaveOutpVarInfoNumOf

EC_T_DWORD esGetSlaveOutpVarInfoNumOf(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.9.12. esGetSlaveInpVarInfo

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

Gets the process variable information entries of an specific slave.

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

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

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

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

Returns

EC_E_NOERROR or error code

struct EC_T_PROCESS_VAR_INFO

Public Members

EC_T_CHAR szName[MAX_PROCESS_VAR_NAME_LEN]

[out] Name of the found process variable

EC_T_WORD wDataType

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

EC_T_WORD wFixedAddr

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

EC_T_INT nBitSize

[out] Size in bit of the found process variable

EC_T_INT nBitOffs

[out] Bit offset in the process data image

EC_T_BOOL bIsInputData

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

MAX_PROCESS_VAR_NAME_LEN

Maximum length of a process variable name: 71 characters

6.9.13. esGetSlaveInpVarInfoEx

EC_T_DWORD esGetSlaveInpVarInfoEx(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 EtherCAT stack isn’t initialized

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

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

struct EC_T_PROCESS_VAR_INFO_EX

Public Members

EC_T_CHAR szName[MAX_PROCESS_VAR_NAME_LEN_EX]

[out] Name of the found process variable

EC_T_WORD wDataType

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

EC_T_WORD wFixedAddr

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

EC_T_INT nBitSize

[out] Size in bit of the found process variable

EC_T_INT nBitOffs

[out] Bit offset in the process data image

EC_T_BOOL bIsInputData

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

EC_T_WORD wIndex

[out] Object index

EC_T_WORD wSubIndex

[out] Object sub index

EC_T_WORD wPdoIndex

[out] Index of PDO (process data object)

EC_T_WORD wWkcStateDiagOffs

[out] Bit offset in the diagnostic image (API GetDiagnosisImagePtr)

EC_T_WORD wMasterSyncUnit

[out] Master Sync Unit ID (ENI: Slave/ProcessData/RxPdo[1..4]@Su, Slave/ProcessData/TxPdo[1..4]@Su, comment at Cyclic/Frame/Cmd)

EC_T_CYC_COPY_INFO CopyInfo

[out] Copy Info if applied to the variable

MAX_PROCESS_VAR_NAME_LEN_EX

Maximum length of a extended process variable name: 127 characters

6.9.14. esGetSlaveOutpVarInfo

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

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

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

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

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

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

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO

6.9.15. esGetSlaveOutpVarInfoEx

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

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

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

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

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

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

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

6.9.16. esGetSlaveInpVarByObjectEx

EC_T_DWORD esGetSlaveInpVarByObjectEx(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 SubIndex

• pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

6.9.17. esGetSlaveOutpVarByObjectEx

EC_T_DWORD esGetSlaveOutpVarByObjectEx(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 SubIndex

• pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

6.9.18. esFindInpVarByName

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

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

Parameters

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

• szVariableName – [in] Variable name

• pProcessVarInfoEntry – [out] Process variable information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO

6.9.19. esFindInpVarByNameEx

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

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

Parameters

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

• szVariableName – [in] Variable name

• pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO

6.9.20. esFindOutpVarByName

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

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

Parameters

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

• szVariableName – [in] Variable name

• pProcessVarInfoEntry – [out] Process variable information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO

6.9.21. esFindOutpVarByNameEx

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

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

Parameters

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

• szVariableName – [in] Variable name

• pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

6.9.22. esWriteSlaveRegister

Warning

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

EC_T_DWORD esWriteSlaveRegister(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 transferred data

• wLen – [in] Number of bytes to send

• dwTimeout – [in] Timeout [ms]

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if EtherCAT stack 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 EtherCAT stack 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.9.23. esReadSlaveRegister

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

Reads data from the ESC memory of a specified slave.

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

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

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

• pbyData – [out] Buffer receiving transferred data

• wLen – [in] Number of bytes to receive

• dwTimeout – [in] Timeout [ms]

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if EtherCAT stack 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 EtherCAT stack 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.9.24. esReadSlaveEEPRom

EC_T_DWORD esReadSlaveEEPRom(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.9.25. esWriteSlaveEEPRom

EC_T_DWORD esWriteSlaveEEPRom(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.

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

Note

The EEPROM’s CRC at word 7 is re-calculated automatically if the written data is completely within the ESC Configuration Area in the EEPROM’s SII.

6.9.26. esGetSimSlaveInfo

EC_T_DWORD esGetSimSlaveInfo(EC_T_DWORD dwInstanceId, EC_T_WORD wCfgFixedAddress, EC_T_SIM_SLAVE_INFO *pSimSlaveInfo)

Get extended configuration and status information for slave from simulator.

Parameters

• dwInstanceId – [in] Simulator Instance ID

• wCfgFixedAddress – [in] Slave’s station address

• pSimSlaveInfo – [out] Extended configuration and status information for slave from simulator

Returns

EC_E_NOERROR or error code

Content of EC_T_SIM_SLAVE_INFO, EC_T_SIM_SLAVE_CFG_INFO, EC_T_SIM_SLAVE_STATUS_INFO is subject to be extended.

struct EC_T_SIM_SLAVE_INFO

Public Members

EC_T_SIM_SLAVE_CFG_INFO oCfg

[out] Config Info (ENI/EXI)

EC_T_SIM_SLAVE_STATUS_INFO oStatus

[out] Status Info

EC_T_DWORD adwReserved[32]

[out] Reserved

struct EC_T_SIM_SLAVE_CFG_INFO

Public Members

EC_T_WORD wFixedAddress

[out] Slave’s station address (ENI/EXI: /EtherCATConfig/Config/Slave/Info/PhysAddr)

EC_T_BOOL bPowerOff

[out] Slave powered off on startup (EXI: /EtherCATConfig/ExtendedConfig/Slaves/Slave@PowerOff)

EC_T_BOOL bSimulated

[out] Slave is simulated (EXI: /EtherCATConfig/ExtendedConfig/Slaves/Slave/Simulated)

EC_T_BOOL bIgnoreCoeDownloadError

[out] Slave ignores CoE download errors (EXI: /EtherCATConfig/ExtendedConfig/Slaves/Slave/Mailbox/CoE@IgnoreDownloadError)

EC_T_SIMULATOR_DEVICE_CONNECTION_DESC aPortConnection[4]

[out] Explicit port connection (optional) (EXI: /EtherCATConfig/ExtendedConfig/Slaves/Slave/PortConnection)

EC_T_CHAR szApplicationName[EC_SIM_SLAVE_CFG_APP_NAME_SIZE]

[out] Configured slave application name (EXI: /EtherCATConfig/ExtendedConfig/Slaves/Slave/Application/Name)

EC_T_CHAR szApplicationParms[EC_SIM_SLAVE_CFG_APP_PARMS_SIZE]

[out] Configured slave application parameters (EXI: /EtherCATConfig/ExtendedConfig/Slaves/Slave/Application/Parameter)

EC_T_DWORD adwReserved[16]

[out] Reserved

struct EC_T_SIM_SLAVE_STATUS_INFO

Public Members

EC_T_BOOL bIsPowerOn

[out] Slave is powered on. See esPowerSlave()

EC_T_BOOL bIsPresent

[out] Slave is present in topology segment and connected to the network. See esConnectPorts(), Hot Connect.

EC_T_WORD wAlStatusReq

[out] AL Status (0x0130) requested from Simulator application. See esSetSimSlaveState()

EC_T_WORD wAlStatusCodeReq

[out] AL Status (0x0134) requested from Simulator application. See esSetSimSlaveState()

EC_T_DWORD adwRes1[4]

[out] Reserved

EC_T_SIMULATOR_DEVICE_CONNECTION_DESC aPortConnection[4]

[out] See esConnectPorts()

EC_T_DWORD adwRes2[16]

[out] Reserved

6.9.27. esGetBusSlaveInfo

EC_T_DWORD esGetBusSlaveInfo(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 EtherCAT stack isn’t initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range

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

Content of EC_T_BUS_SLAVE_INFO is subject to be extended.

struct EC_T_BUS_SLAVE_INFO

Public Members

EC_T_DWORD dwSlaveId

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

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 wAutoIncAddress

[out] The slave’s auto increment address

EC_T_BOOL bDcSupport

[out] Slave supports DC (Bus Topology Scan)

EC_T_BOOL bDc64Support

[out] Slave supports 64 Bit DC (Bus Topology Scan)

EC_T_DWORD dwVendorId

[out] Vendor Identification stored in the EEPROM at offset 0x0008

EC_T_DWORD dwProductCode

[out] Product Code stored in the EEPROM at offset 0x000A

EC_T_DWORD dwRevisionNumber

[out] Revision number stored in the EEPROM at offset 0x000C

EC_T_DWORD dwSerialNumber

[out] Serial number stored in the EEPROM at offset 0x000E

EC_T_BYTE byESCType

[out] Type of ESC (Value of slave ESC register 0x0000)

EC_T_BYTE byESCRevision

[out] Revision number of ESC (Value of slave ESC register 0x0001)

EC_T_WORD wESCBuild

[out] Build number of ESC (Value of slave ESC register 0x0002)

EC_T_BYTE byPortDescriptor

[out] Port descriptor (Value of slave ESC register 0x0007)

EC_T_WORD wFeaturesSupported

[out] Features supported (Value of slave ESC register 0x0008)

EC_T_WORD wStationAddress

[out] The slave’s station address (Value of slave ESC register 0x0010)

EC_T_WORD wAliasAddress

[out] The slave’s alias address (Value of slave ESC register 0x0012)

EC_T_WORD wAlStatus

[out] AL status (Value of slave ESC register 0x0130)

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 wDlStatus

[out] DL status (Value of slave ESC register 0x0110)

EC_T_WORD wPrevPort

[out] Connected port of the previous slave

EC_T_WORD wIdentifyData

[out] Last read identification value see EC_T_CFG_SLAVE_INFO.wIdentifyAdo

EC_T_BOOL bLineCrossed

[out] Line crossed was detected at this slave

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 bIsRefClock

[out] Slave is reference clock

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 dwCyclicWkcErrorCnt

[out] Counter for Cyclic WC Error

EC_T_DWORD dwSlaveAbsentCnt

[out] Counter for Absent/Not Present Slaves

EC_T_DWORD dwUnexpectedStateCnt

[out] Counter for Abnormal State Change

Get bus slave info with station address example

        EC_T_BUS_SLAVE_INFO oBusSlaveInfo;

        /* get bus slave info of slave with station address 1001 */
        dwRes = esGetBusSlaveInfo(dwSimulatorId, EC_TRUE, 1001, &oBusSlaveInfo);
        if (dwRes != EC_E_NOERROR)
        {
            dwRetVal = dwRes;
            goto Exit;
        }

Get bus slave info with auto-inc address example

        EC_T_BUS_SLAVE_INFO oBusSlaveInfo;

        /* get bus slave info of third slave (auto inc address 0, -1, -2, ...) */
        dwRes = esGetBusSlaveInfo(dwSimulatorId, EC_FALSE, (EC_T_WORD)-2, &oBusSlaveInfo);
        if (dwRes != EC_E_NOERROR)
        {
            dwRetVal = dwRes;
            goto Exit;
        }

6.9.28. esReadSlaveIdentification

EC_T_DWORD esReadSlaveIdentification(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 EtherCAT stack 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 EtherCAT stack 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.9.29. esGetSlaveStatistics

EC_T_DWORD esGetSlaveStatistics(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.9.30. esClearSlaveStatistics

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