8.4. Slave status functions

8.4.1. emGetNumConfiguredSlaves

EC_T_DWORD emGetNumConfiguredSlaves(EC_T_DWORD dwInstanceID)

Returns number of slaves which are configured in the ENI.

Parameters

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

Returns

Number of slaves

8.4.2. emGetNumConnectedSlaves

EC_T_DWORD emGetNumConnectedSlaves(EC_T_DWORD dwInstanceID)

Get amount of currently connected slaves.

Parameters

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

Returns

Number of connected slaves

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

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

8.4.5. emGetSlaveState

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

Limitation

Since it is not possible to determine the actual requested slave state from the master, the highest slave state of all slaves is assumed to be the requested state.

8.4.6. emIsSlavePresent

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

8.4.7. emGetSlaveProp

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

struct EC_T_SLAVE_PROP

Public Members

EC_T_WORD wStationAddress

station address or INVALID_FIXED_ADDR

EC_T_WORD wAutoIncAddr

auto increment address or INVALID_AUTO_INC_ADDR

EC_T_CHAR achName[MAX_STD_STRLEN]

name of the slave device (NULL terminated string)

See also

emGetSlaveId()

8.4.8. emGetSlaveInpVarInfoNumOf

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

8.4.9. emGetSlaveInpVarInfo

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

Gets the process variable information entries of an specific slave.

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

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

  • wSlaveAddress – [in] Slave address according bFixedAddressing

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

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

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

Returns

EC_E_NOERROR or error code

struct EC_T_PROCESS_VAR_INFO

Public Members

EC_T_CHAR szName[MAX_PROCESS_VAR_NAME_LEN]

[out] Name of the found process variable

EC_T_WORD wDataType

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

EC_T_WORD wFixedAddr

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

EC_T_INT nBitSize

[out] Size in bit of the found process variable

EC_T_INT nBitOffs

[out] Bit offset in the process data image

EC_T_BOOL bIsInputData

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

MAX_PROCESS_VAR_NAME_LEN

Maximum length of a process variable name: 71 characters

8.4.10. emGetSlaveInpVarInfoEx

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

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

8.4.11. emGetSlaveOutpVarInfoNumOf

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

8.4.12. emGetSlaveOutpVarInfo

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

8.4.13. emGetSlaveOutpVarInfoEx

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

8.4.14. emReadSlaveRegister

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 that have so far been transfered to a slave and received by the EC-Monitor.

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

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

  • wSlaveAddress – [in] Slave address according bFixedAddressing

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

  • pbyData – [out] Buffer receiving transfered data

  • wLen – [in] Number of bytes to receive

  • dwTimeout – [in] Timeout [ms]

Returns

  • EC_E_NOERROR if successful

  • EC_E_INVALIDSTATE if master isn’t initialized

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

  • EC_E_SLAVE_NOT_PRESENT if slave not present

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

  • EC_E_TIMEOUT if dwTimeout elapsed during the API call

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

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

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

8.4.15. emGetCfgSlaveInfo

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

Flags EC_MBX_PROTOCOL_

EC_MBX_PROTOCOL_AOE
EC_MBX_PROTOCOL_EOE
EC_MBX_PROTOCOL_COE
EC_MBX_PROTOCOL_FOE
EC_MBX_PROTOCOL_SOE
EC_MBX_PROTOCOL_VOE

8.4.16. emGetBusSlaveInfo

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

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

Port Slave ID’s

MASTER_SLAVE_ID
SIMULATOR_SLAVE_ID
MASTER_RED_SLAVE_ID
EL9010_SLAVE_ID
FRAMELOSS_SLAVE_ID
JUNCTION_RED_FLAG

Flags EC_LINECROSSED_

EC_LINECROSSED_NOT_CONNECTED_PORTA
EC_LINECROSSED_UNEXPECTED_INPUT_PORT
EC_LINECROSSED_UNEXPECTED_JUNCTION_RED
EC_LINECROSSED_UNRESOLVED_PORT_CONNECTION
EC_LINECROSSED_HIDDEN_SLAVE_CONNECTED
EC_LINECROSSED_PHYSIC_MISMATCH
EC_LINECROSSED_INVALID_PORT_CONNECTION