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

6.9.6. esSetSlaveState

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

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

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

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

    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

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

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

struct EC_T_PROCESS_VAR_INFO_EX

Public Members

EC_T_CHAR szName[MAX_PROCESS_VAR_NAME_LEN_EX]

[out] Name of the found process variable

EC_T_WORD wDataType

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

EC_T_WORD wFixedAddr

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

EC_T_INT nBitSize

[out] Size in bit of the found process variable

EC_T_INT nBitOffs

[out] Bit offset in the process data image

EC_T_BOOL bIsInputData

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

EC_T_WORD wIndex

[out] Object index

EC_T_WORD wSubIndex

[out] Object sub index

EC_T_WORD wPdoIndex

[out] Index of PDO (process data object)

EC_T_WORD wWkcStateDiagOffs

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

EC_T_WORD wMasterSyncUnit

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

MAX_PROCESS_VAR_NAME_LEN_EX

Maximum length of a extended process variable name: 127 characters

6.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 sub index

  • pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

6.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 sub index

  • pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

6.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. EC_NOTIFY_SLAVE_PRESENCE

This notification is given, if slave appears or disappears from the network.

This notification is enabled by default.

emNotify - EC_NOTIFY_SLAVE_PRESENCE
Parameter

  • pbyInBuf: [in] Pointer to EC_T_SLAVE_PRESENCE_NTFY_DESC

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

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

Disconnecting the slave from the network, powering it off or a bad connection can produce this notification.

struct EC_T_SLAVE_PRESENCE_NTFY_DESC

Public Members

EC_T_WORD wStationAddress

Slave station address

EC_T_BYTE bPresent

EC_TRUE: present , EC_FALSE: absent

6.9.23. EC_NOTIFY_SLAVE_STATECHANGED

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

emNotify - EC_NOTIFY_SLAVES_STATECHANGED
Parameter

  • pbyInBuf: [in] Pointer to EC_T_SLAVE_STATECHANGED_NTFY_DESC

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

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

struct EC_T_SLAVE_STATECHANGED_NTFY_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

EC_T_STATE newState

New slave state

6.9.24. EC_NOTIFY_HC_TOPOCHGDONE

This notification is given by eUsrJob_SimulatorTimer when the topology changes.

emNotify - EC_NOTIFY_HC_TOPOCHGDONE
Parameter

  • pbyInBuf: [in] Should be set to EC_NULL

  • dwInBufSize: [in] Should be set to 0

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

See also

esPowerSlave() , esDisconnectPort() , esConnectPorts()

6.9.25. 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 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.9.26. 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.

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.9.27. 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.28. 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.

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

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.29. esGetCfgSlaveInfo

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

Content of EC_T_CFG_SLAVE_INFO is subject to be extended.

struct EC_T_CFG_SLAVE_INFO

Public Members

EC_T_DWORD dwSlaveId

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

EC_T_CHAR abyDeviceName[ECAT_DEVICE_NAMESIZE]

[out] The slave’s configured name (80 Byte) (from ENI file)

EC_T_DWORD dwHCGroupIdx

[out] Index of the hot connect group, 0 for mandatory

EC_T_BOOL bIsPresent

[out] Slave is currently present on bus

EC_T_BOOL bIsHCGroupPresent

[out] Slave’s hot connect group is currently present on bus

EC_T_DWORD dwVendorId

[out] Vendor identification (from ENI file)

EC_T_DWORD dwProductCode

[out] Product code (from ENI file)

EC_T_DWORD dwRevisionNumber

[out] Revision number (from ENI file)

EC_T_DWORD dwSerialNumber

[out] Serial number (from ENI file)

EC_T_WORD wStationAddress

[out] The slave’s station address (from ENI file)

EC_T_WORD wAutoIncAddress

[out] The slave’s auto increment address (from ENI file)

EC_T_DWORD dwPdOffsIn

[out] Process input data bit offset (from ENI file)

EC_T_DWORD dwPdSizeIn

[out] Process input data bit size (from ENI file)

EC_T_DWORD dwPdOffsOut

[out] Process output data bit offset (from ENI file)

EC_T_DWORD dwPdSizeOut

[out] Process output data bit size (from ENI file)

EC_T_DWORD dwPdOffsIn2

[out] 2nd sync unit process input data bit offset (from ENI file)

EC_T_DWORD dwPdSizeIn2

[out] 2nd sync unit process input data bit size (from ENI file)

EC_T_DWORD dwPdOffsOut2

[out] 2nd sync unit process output data bit offset (from ENI file)

EC_T_DWORD dwPdSizeOut2

[out] 2nd sync unit process output data bit size (from ENI file)

EC_T_DWORD dwPdOffsIn3

[out] 3rd sync unit process input data bit offset (from ENI file)

EC_T_DWORD dwPdSizeIn3

[out] 3rd sync unit process input data bit size (from ENI file)

EC_T_DWORD dwPdOffsOut3

[out] 3rd sync unit process output data bit offset (from ENI file)

EC_T_DWORD dwPdSizeOut3

[out] 3rd sync unit process output data bit size (from ENI file)

EC_T_DWORD dwPdOffsIn4

[out] 4th sync unit process input data bit offset (from ENI file)

EC_T_DWORD dwPdSizeIn4

[out] 4th sync unit process input data bit size (from ENI file)

EC_T_DWORD dwPdOffsOut4

[out] 4th sync unit process output data bit offset (from ENI file)

EC_T_DWORD dwPdSizeOut4

[out] 4th sync unit process output data bit size (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_DWORD dwMbxOutSize

[out] Mailbox output byte size (from ENI file)

EC_T_DWORD dwMbxInSize

[out] Mailbox input byte size (from ENI file)

EC_T_DWORD dwMbxOutSize2

[out] Bootstrap mailbox output byte size (from ENI file)

EC_T_DWORD dwMbxInSize2

[out] Bootstrap mailbox input byte size (from ENI file)

EC_T_BOOL bDcSupport

[out] Slave supports DC (from ENI file)

EC_T_WORD wNumProcessVarsInp

[out] Number of input process data variables (from ENI file)

EC_T_WORD wNumProcessVarsOutp

[out] Number of output process data variables (from ENI file)

EC_T_WORD wPrevStationAddress

[out] Station address of the previous slave (from ENI file)

EC_T_WORD wPrevPort

[out] Connected port of the previous slave (from ENI file)

EC_T_WORD wIdentifyAdo

[out] ADO used for identification command (from ENI file)

EC_T_WORD wIdentifyData

[out] Identification value to be validated (from ENI file)

EC_T_BYTE byPortDescriptor

[out] Port descriptor (ESC register 0x0007) (from ENI file)

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_BOOL bDisabled

[out] Slave disabled by API (emSetSlaveDisabled / emSetSlavesDisabled).

EC_T_BOOL bDisconnected

[out] Slave disconnected by API (emSetSlaveDisconnected / emSetSlavesDisconnected).

EC_T_BOOL bExtended

[out] Slave generated by emConfigExtend

Supported mailbox protocols flags

group EC_MBX_PROTOCOLS

Defines

EC_MBX_PROTOCOL_AOE
EC_MBX_PROTOCOL_EOE
EC_MBX_PROTOCOL_COE
EC_MBX_PROTOCOL_FOE
EC_MBX_PROTOCOL_SOE
EC_MBX_PROTOCOL_VOE

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

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)

struct EC_T_SIM_SLAVE_STATUS_INFO

Public Members

EC_T_BOOL bIsPowerOn

[out] esPowerSlave(…)

EC_T_SIMULATOR_DEVICE_CONNECTION_DESC aPortConnection[4]

[out] esConnectPorts(…)

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

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

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

6.9.33. 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.34. 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