6.6. SubDevice control and status functions

6.6.1. emGetNumConfiguredSlaves

static EC_T_DWORD ecatGetNumConfiguredSlaves(EC_T_VOID)

EC_T_DWORD emGetNumConfiguredSlaves(EC_T_DWORD dwInstanceID)

Returns the number of slaves which are configured in the ENI.

Parameters

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

Returns

Number of slaves

emGetNumConfiguredSlaves() Example

EC_T_DWORD dwSlaveCnt = emGetNumConfiguredSlaves(dwInstanceId);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO, 
    " Slave Count: %d", dwSlaveCnt));

6.6.2. emGetNumConnectedSlaves

static EC_T_DWORD ecatGetNumConnectedSlaves(EC_T_VOID)

EC_T_DWORD emGetNumConnectedSlaves(EC_T_DWORD dwInstanceID)

Get number of currently connected slaves.

Parameters

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

Returns

Number of connected slaves

emGetNumConnectedSlaves() Example

EC_T_DWORD dwSlaveCnt = emGetNumConnectedSlaves(dwInstanceId);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO, 
    " Slave Count: %d", dwSlaveCnt));

6.6.3. emGetSlaveId

static EC_T_DWORD ecatGetSlaveId(EC_T_WORD wStationAddress)

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 the stack is not initialized

emGetSlaveId() Example

/* get slave ID using slave station address */
EC_T_WORD wStationAddress = 1002;
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, wStationAddress);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO, 
    " Slave ID: %d", dwSlaveId));

6.6.4. emGetSlaveIdAtPosition

static EC_T_DWORD ecatGetSlaveIdAtPosition(EC_T_WORD wAutoIncAddress)

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

emGetSlaveIdAtPosition() Example

/* get slave ID using configured auto increment address */
EC_T_WORD wAutoIncAdress = 0xFFFB;
EC_T_DWORD dwSlavePos = emGetSlaveIdAtPosition(dwInstanceId, wAutoIncAdress);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO, 
    " Slave Position: %d", dwSlavePos));

6.6.5. emSetSlaveState

static EC_T_DWORD ecatSetSlaveState(EC_T_DWORD dwSlaveId, EC_T_WORD wDeviceState, EC_T_DWORD dwTimeout)

EC_T_DWORD emSetSlaveState(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 Slave device state’s

• 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

DEVICE_STATE_UNKNOWN

Slave in unknown state

DEVICE_STATE_INIT

Slave in INIT state

DEVICE_STATE_PREOP

Slave in PREOP state

DEVICE_STATE_BOOTSTRAP

Slave in BOOTSTRAP state

DEVICE_STATE_SAFEOP

Slave in SAFEOP state

DEVICE_STATE_OP

Slave in OP state

DEVICE_STATE_ERROR

Slave in error state

emSetSlaveState() Example

EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
EC_T_WORD wDeviceState = DEVICE_STATE_PREOP;
dwRes = emSetSlaveState(dwInstanceId, dwSlaveId, wDeviceState, 5000 /* timeout */);

See also

emGetSlaveId()

6.6.6. emSetSlaveStateReq

static EC_T_DWORD ecatSetSlaveStateReq(EC_T_DWORD dwSlaveId, EC_T_WORD wDeviceState, EC_T_DWORD dwTimeout)

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

Request to set a specified slave into the requested EtherCAT state and return immediately.

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.

Parameters

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

• dwSlaveId – [in] Slave ID

• wDeviceState – [in] Requested device state. See Slave device state’s

• dwTimeout – [in] Timeout [ms]

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_BUSY if the EtherCAT stack cannot execute the request at this time, the function has to be called at a later time

• EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

emSetSlaveStateReq() Example

EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
EC_T_WORD wDeviceState = DEVICE_STATE_PREOP;
dwRes = emSetSlaveStateReq(dwInstanceId, dwSlaveId, wDeviceState, 5000 /* timeout */);

See also

emSetSlaveState()

See also

emGetSlaveId()

6.6.7. emGetSlaveState

static EC_T_DWORD ecatGetSlaveState(EC_T_DWORD dwSlaveId, EC_T_WORD *pwCurrDevState, EC_T_WORD *pwReqDevState)

EC_T_DWORD emGetSlaveState(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_WORD *pwCurrDevState, EC_T_WORD *pwReqDevState)

Get the slave state.

The slave state is always read automatically from the AL_STATUS register whenever necessary. It is not forced by calling this function. This function may be called from within the JobTask’s context.

Parameters

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

• dwSlaveId – [in] Slave ID

• pwCurrDevState – [out] Current slave state

• pwReqDevState – [out] Requested slave state

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if 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 the slave is not present

• EC_E_NOTFOUND if no slave matching dwSlaveId can be found

emGetSlaveState() Example

/* get slave state */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1002);
EC_T_WORD pwCurrDevState = 0;
EC_T_WORD wReqDevState = 0;
dwRes = emGetSlaveState(dwInstanceId, dwSlaveId, &pwCurrDevState, &wReqDevState);

See also

• emGetSlaveId()

• emSetSlaveState()

6.6.8. emIsSlavePresent

static EC_T_DWORD ecatIsSlavePresent(EC_T_DWORD dwSlaveId, EC_T_BOOL *pbPresence)

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

emIsSlavePresent() Example

EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1002);
EC_T_BOOL bPresence = EC_FALSE;

/* returns whether a specific slave is currently connected to network */
dwRes = emIsSlavePresent(dwInstanceId, dwSlaveId, &bPresence);

See also

emGetSlaveId()

6.6.9. emGetSlaveProp

static EC_T_BOOL ecatGetSlaveProp(EC_T_DWORD dwSlaveId, EC_T_SLAVE_PROP *pSlaveProp)

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

Determines the properties of the slave device.

Deprecated:

Use emGetCfgSlaveInfo instead

Parameters

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

• dwSlaveId – [in] Slave ID

• pSlaveProp – [out] Slave properties

Returns

EC_TRUE if the slave exists, EC_FALSE if no slave matching dwSlaveId can be found

emGetSlaveProp() Example

EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1002);
EC_T_SLAVE_PROP oSlaveProp;
OsMemset(&oSlaveProp, 0, sizeof(EC_T_SLAVE_PROP));
EC_T_BOOL bSlaveProp = emGetSlaveProp(dwInstanceId, dwSlaveId, &oSlaveProp);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO, " Slave ID: %d", bSlaveProp));

See also

emGetSlaveId()

6.6.10. emSlaveSerializeMbxTfers

static EC_T_DWORD ecatSlaveSerializeMbxTfers(EC_T_DWORD dwSlaveId)

EC_T_DWORD emSlaveSerializeMbxTfers(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId)

Serializes all mailbox transfers to the specified slave.

The parallel (overlapped) usage of more than one protocol (CoE, EoE, FoE, etc.) will be disabled. By default parallel mailbox transfers are enabled.

Parameters

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

• dwSlaveId – [in] Slave ID

Returns

• EC_E_NOERROR if successful

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

• EC_E_NO_MBX_SUPPORT if slave does not support mailbox transfers

emSlaveSerializeMbxTfers() Example

/* serialize all mailbox transfers to specified slave */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
dwRes = emSlaveSerializeMbxTfers(dwInstanceId, dwSlaveId);

See also

emGetSlaveId()

6.6.11. emSlaveParallelMbxTfers

static EC_T_DWORD ecatSlaveParallelMbxTfers(EC_T_DWORD dwSlaveId)

EC_T_DWORD emSlaveParallelMbxTfers(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId)

Re-enable the parallel mailbox transfers to the specified slave.

Allows parallel (overlapped) usage of more than one protocol (CoE, EoE, FoE, etc.). By default parallel mailbox transfers are enabled.

Parameters

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

• dwSlaveId – [in] Slave ID

Returns

• EC_E_NOERROR if successful

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

• EC_E_NO_MBX_SUPPORT if slave does not support mailbox transfers

emSlaveParallelMbxTfers() Example

/* re-enable parallel mailbox transfers to specified slave */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
dwRes = emSlaveParallelMbxTfers(dwInstanceId, dwSlaveId);

See also

emGetSlaveId()

6.6.12. emIoCtl - EC_IOCTL_SET_MBX_RETRYACCESS_PERIOD

EC_IOCTL_SET_MBX_RETRYACCESS_PERIOD

Sets the mailbox retry access period [ms] for a specific slave. If a slave rejects a mailbox access because of a busy state, the master restarts mailbox access after that period of time.

Parameters

• pbyInBuf – [in] Pointer to a size 6 byte array. The first 4 bytes must contain the slave id (EC_T_DWORD), the last 2 bytes the new retry access period in milliseconds(EC_T_WORD).

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

• pbyOutBuf – [out] Should be set to EC_NULL

• dwOutBufSize – [in] Should be set to 0

• pdwNumOutData – [out] Should be set to EC_NULL

Returns

EC_E_NOERROR or error code

By default, the retry access period is set to 25 milliseconds.

6.6.13. emNotify - EC_NOTIFY_SLAVE_STATECHANGED

This notification is given when a SubDevice changed its EtherCAT® state. This notification is disabled by default.

emNotify - EC_NOTIFY_SLAVE_STATECHANGED

Parameter

• pbyInBuf: [in] Pointer to EC_T_SLAVE_STATECHANGED_NTFY_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

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the activation

6.6.14. emNotify - EC_NOTIFY_SLAVES_STATECHANGED

Collects emNotify - EC_NOTIFY_SLAVE_STATECHANGED.

This notification is disabled by default.

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the activation

emNotify - EC_NOTIFY_SLAVES_STATECHANGED

Parameter

• pbyInBuf: [in] Pointer to EC_T_SLAVES_STATECHANGED_NTFY_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_SLAVES_STATECHANGED_NTFY_DESC_ENTRY

Public Members

EC_T_WORD wStationAddress

Slave station address

EC_T_BYTE byState

New slave state

6.6.15. emWriteSlaveRegister

static EC_T_DWORD ecatWriteSlaveRegister(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen, EC_T_DWORD dwTimeout)

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

Writes data into the ESC memory of a specified slave.

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

Warning

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

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wRegisterOffset – [in] Register offset. E.g. use 0x0120 to write to the AL Control register.

• pbyData – [in] Buffer containing transfered data

• wLen – [in] Number of bytes to send

• dwTimeout – [in] Timeout [ms]

Returns

• EC_E_NOERROR if successful

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

emWriteSlaveRegister() Example

dwRes = emWriteSlaveRegister(dwInstanceId, EC_TRUE, 
    1001, wRegisterOffset, abyData, wLen, 5000 /* timeout */);

6.6.16. emWriteSlaveRegisterReq

static EC_T_DWORD ecatWriteSlaveRegisterReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen)

EC_T_DWORD emWriteSlaveRegisterReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen)

Requests a data write transfer into the ESC memory of a specified slave and returns immediately.

A notification EC_NOTIFY_SLAVE_REGISTER_TRANSFER is given on completion. This function may be called from within the JobTask’s context.

Warning

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

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_SLAVEREGISTER_TRANSFER_NTFY_DESC.

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wRegisterOffset – [in] Register offset. E.g. use 0x0120 to write to the AL Control register.

• pbyData – [in] Buffer containing transferred data

• wLen – [in] Number of bytes to send

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

emWriteSlaveRegisterReq() Example

EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
/* assigned by application. should be unique for each transfer */

/* write data into slave's ESC memory */
dwRes = emWriteSlaveRegisterReq(dwInstanceId, dwClientId, dwTferId, 
    EC_TRUE, 1001, wRegisterOffset, abyData, wLen);

See also

emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER

6.6.17. emReadSlaveRegister

static EC_T_DWORD ecatReadSlaveRegister(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen, EC_T_DWORD dwTimeout)

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

Reads data from the ESC memory of a specified slave.

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 transfered 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 the slave is 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 if 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.

emReadSlaveRegister() Example

/* read ESC memory */
EC_T_BYTE abyData[2] = {0, 0};

dwRes = emReadSlaveRegister(dwInstanceId, EC_TRUE, 1001, 
    0 /* ADO */, abyData, 2, 5000 /* timeout */);

6.6.18. emReadSlaveRegisterReq

static EC_T_DWORD ecatReadSlaveRegisterReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen)

EC_T_DWORD emReadSlaveRegisterReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wRegisterOffset, EC_T_BYTE *pbyData, EC_T_WORD wLen)

Requests data read transfer from the ESC memory of a specified slave and returns immediately.

A notification EC_NOTIFY_SLAVE_REGISTER_TRANSFER is given on completion. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_SLAVEREGISTER_TRANSFER_NTFY_DESC.

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

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

• pbyData – [out] Buffer receiving transfered data

• wLen – [in] Number of bytes to receive

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if 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_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.

emReadSlaveRegisterReq() Example

/* read ESC memory (non-blocking) */
EC_T_BYTE abyData[2] = {0, 0};
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */

/* get data read transfer from ESC memory of specified slave */
dwRes = emReadSlaveRegisterReq(dwInstanceId, dwClientId, dwTferId, 
    EC_TRUE, 1001, 0 /* ADO */, abyData, 2);

See also

emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER

6.6.19. emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER

This notification is given, when a SubDevice register transfer is completed.

emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER

Parameter

• pbyInBuf: [in] Pointer to EC_T_SLAVEREGISTER_TRANSFER_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_SLAVEREGISTER_TRANSFER_NTFY_DESC

Public Members

EC_T_DWORD dwTferId

Transfer ID. For every new slave register transfer a unique ID has to be assigned. This ID can be used after completion to identify the transfer.

EC_T_DWORD dwResult

Result of Slave register transfer

EC_T_BOOL bRead

EC_TRUE: Read register, EC_FALSE: Write register transfer

EC_T_WORD wFixedAddr

Station address of slave

EC_T_WORD wRegisterOffset

Register offset

EC_T_WORD wLen

Length of slave register transfer

EC_T_BYTE *pbyData

Pointer to the data read

EC_T_WORD wWkc

Received working counter

6.6.20. emReadSlaveEEPRom

static EC_T_DWORD ecatReadSlaveEEPRom(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwReadData, EC_T_DWORD dwReadLen, EC_T_DWORD *pdwNumOutData, EC_T_DWORD dwTimeout)

EC_T_DWORD emReadSlaveEEPRom(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwReadData, EC_T_DWORD dwReadLen, EC_T_DWORD *pdwNumOutData, EC_T_DWORD dwTimeout)

Read EEPROM data from a 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

emReadSlaveEEPRom() Example

/* read EEPROM data from slave */
EC_T_WORD awData[16];
EC_T_DWORD dwNumOutData = 0;
OsMemset(awData, 0, sizeof(awData));

dwRes = emReadSlaveEEPRom(dwInstanceId, EC_TRUE, 1001, 
    7 /* WORD offset */, awData, EC_NUMOFELEMENTS(awData), 
    &dwNumOutData, 5000 /* timeout */);

6.6.21. emReadSlaveEEPRomReq

static EC_T_DWORD ecatReadSlaveEEPRomReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwReadData, EC_T_DWORD dwReadLen, EC_T_DWORD *pdwNumOutData, EC_T_DWORD dwTimeout)

EC_T_DWORD emReadSlaveEEPRomReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, EC_T_WORD *pwReadData, EC_T_DWORD dwReadLen, EC_T_DWORD *pdwNumOutData, EC_T_DWORD dwTimeout)

Requests an EEPROM data read operation from a slave and returns immediately.

An EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_EEPROM_OPERATION_NTFY_DESC.

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wEEPRomStartOffset – [in] Word address to start EEPROM read from

• pwReadData – [out] Pointer to EC_T_WORD array to carry the read data, must be valid until the operation complete

• dwReadLen – [in] Size of the EC_T_WORD array provided at pwReadData (in EC_T_WORDs)

• pdwNumOutData – [out] Pointer to EC_T_DWORD carrying actually read data (in EC_T_WORDs) after completion

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

emReadSlaveEEPRomReq() Example

EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
EC_T_WORD awData[16];
EC_T_DWORD dwNumOutData = 0;
OsMemset(awData, 0, sizeof(awData));

/* requests EEPROM data read operation from slave */
dwRes = emReadSlaveEEPRomReq(dwInstanceId, dwClientId, 
    dwTferId, EC_TRUE, 1001, 7 /* WORD offset */, awData, 
    EC_NUMOFELEMENTS(awData), &dwNumOutData, 5000 /* timeout */);

See also

emNotify - EC_NOTIFY_EEPROM_OPERATION

6.6.22. emWriteSlaveEEPRom

static EC_T_DWORD ecatWriteSlaveEEPRom(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, const EC_T_WORD *pwWriteData, EC_T_DWORD dwWriteLen, EC_T_DWORD dwTimeout)

EC_T_DWORD emWriteSlaveEEPRom(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, const 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 data to write

• 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

emWriteSlaveEEPRom() Example

dwRes = emWriteSlaveEEPRom(dwInstanceId, EC_TRUE, 
    1001, 0 /* offset */, awData, dwWriteLen, 5000 /* timeout */);

See also

emResetSlaveController()

6.6.23. emWriteSlaveEEPRomReq

static EC_T_DWORD ecatWriteSlaveEEPRomReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, const EC_T_WORD *pwWriteData, EC_T_DWORD dwWriteLen, EC_T_DWORD dwTimeout)

EC_T_DWORD emWriteSlaveEEPRomReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wEEPRomStartOffset, const EC_T_WORD *pwWriteData, EC_T_DWORD dwWriteLen, EC_T_DWORD dwTimeout)

Requests an EEPROM data write operation from a slave and returns immediately.

The EEPROM’s CRC is updated automatically. A reset of the slave controller is needed to reload the alias address in register 0x12. An EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_EEPROM_OPERATION_NTFY_DESC.

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wEEPRomStartOffset – [in] Word address to start EEPROM Write from

• pwWriteData – [in] Pointer to WORD array carrying the write data, must be valid until operation complete

• dwWriteLen – [in] Size of Write Data WORD array (in WORDS)

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

emWriteSlaveEEPRomReq() Example

EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
dwRes = emWriteSlaveEEPRomReq(dwInstanceId, dwClientId, dwTferId, 
    EC_TRUE, 1001, 0 /* offset */, awData, dwWriteLen, 5000 /* timeout */);

See also

• emResetSlaveController()

• emNotify - EC_NOTIFY_EEPROM_OPERATION

6.6.24. emAssignSlaveEEPRom

static EC_T_DWORD ecatAssignSlaveEEPRom(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bSlavePDIAccessEnable, EC_T_BOOL bForceAssign, EC_T_DWORD dwTimeout)

EC_T_DWORD emAssignSlaveEEPRom(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bSlavePDIAccessEnable, EC_T_BOOL bForceAssign, EC_T_DWORD dwTimeout)

Set EEPROM Assignment to PDI or EtherCAT Master.

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

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• bSlavePDIAccessEnable – [in] EC_TRUE: EEPROM assigned to slave PDI application, EC_FALSE: EEPROM assigned to EC-Master

• bForceAssign – [in] Force Assignment of EEPROM (only for ECat Master Assignment)

• dwTimeout – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

emAssignSlaveEEPRom() Example

/* set EEPROM access to PDI */
dwRes = emAssignSlaveEEPRom(dwInstanceId, EC_TRUE, 
    1001, EC_TRUE /* PDI access */, EC_TRUE /* force */, 5000 /* timeout */);

6.6.25. emAssignSlaveEEPRomReq

static EC_T_DWORD ecatAssignSlaveEEPRomReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bSlavePDIAccessEnable, EC_T_BOOL bForceAssign, EC_T_DWORD dwTimeout)

EC_T_DWORD emAssignSlaveEEPRomReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bSlavePDIAccessEnable, EC_T_BOOL bForceAssign, EC_T_DWORD dwTimeout)

Requests EEPROM Assignment to PDI or EtherCAT Master operation and returns immediately.

EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_EEPROM_OPERATION_NTFY_DESC.

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• bSlavePDIAccessEnable – [in] EC_TRUE: EEPROM assigned to slave PDI application, EC_FALSE: EEPROM assigned to EC-Master

• bForceAssign – [in] Force Assignment of EEPROM (only for ECat Master Assignment)

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

emAssignSlaveEEPRomReq() Example

/* set EEPROM access to PDI (non-blocking) */
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
/* requests EEPROM Assignment to PDI or EtherCAT Master operation and return immediately */
dwRes = emAssignSlaveEEPRomReq(dwInstanceId, dwClientId, dwTferId, 
    EC_TRUE, 1001, EC_TRUE /* PDI access */, EC_TRUE /* force */, 5000 /* timeout */);

See also

emNotify - EC_NOTIFY_EEPROM_OPERATION

6.6.26. emActiveSlaveEEPRom

static EC_T_DWORD ecatActiveSlaveEEPRom(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL *pbSlavePDIAccessActive, EC_T_DWORD dwTimeout)

EC_T_DWORD emActiveSlaveEEPRom(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL *pbSlavePDIAccessActive, EC_T_DWORD dwTimeout)

Check whether EEPROM is marked access active by Slave PDI application.

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

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• pbSlavePDIAccessActive – [out] Pointer to Boolean value: EC_TRUE: EEPROM active by PDI application, EC_FALSE: EEPROM not active

• dwTimeout – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

emActiveSlaveEEPRom() Example

/* check whether EEPROM is marked access active by PDI */
EC_T_BOOL bSlavePDIAccessActive = EC_FALSE;
dwRes = emActiveSlaveEEPRom(dwInstanceId, EC_TRUE, 1001, 
    &bSlavePDIAccessActive, 5000 /* timeout */);

6.6.27. emActiveSlaveEEPRomReq

static EC_T_DWORD ecatActiveSlaveEEPRomReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL *pbSlavePDIAccessActive, EC_T_DWORD dwTimeout)

EC_T_DWORD emActiveSlaveEEPRomReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL *pbSlavePDIAccessActive, EC_T_DWORD dwTimeout)

Requests EEPROM is marked access active by Slave PDI application check and returns immediately.

An EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_EEPROM_OPERATION_NTFY_DESC.

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• pbSlavePDIAccessActive – [out] Pointer to Boolean value: EC_TRUE: EEPROM active by PDI application, EC_FALSE: EEPROM not active. Must be valid until operation complete.

• dwTimeout – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

emActiveSlaveEEPRomReq() Example

/* check whether EEPROM is marked access active by PDI (non-blocking) */
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
EC_T_BOOL bSlavePDIAccessActive = EC_FALSE;
dwRes = emActiveSlaveEEPRomReq(dwInstanceId, dwClientId, dwTferId, 
    EC_TRUE, 1001, &bSlavePDIAccessActive, 5000 /* timeout */);

See also

emNotify - EC_NOTIFY_EEPROM_OPERATION

6.6.28. emReloadSlaveEEPRom

static EC_T_DWORD ecatReloadSlaveEEPRom(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

EC_T_DWORD emReloadSlaveEEPRom(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

Causes a slave to reload its EEPROM values to ESC registers.

Alias address at 0x12 is not reloaded through this command, this is prevented by the slave hardware. The slave controller must be reset to reload the alias address. This function may not be called from within the JobTask’s context.

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• dwTimeout – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

emReloadSlaveEEPRom() Example

dwRes = emReloadSlaveEEPRom(dwInstanceId, EC_TRUE, 1001, 5000/* timeout */);

See also

emResetSlaveController()

6.6.29. emReloadSlaveEEPRomReq

static EC_T_DWORD ecatReloadSlaveEEPRomReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

EC_T_DWORD emReloadSlaveEEPRomReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

Request a slave to reload its EEPROM values to ESC registers, and returns immediately.

Alias address at 0x12 is not reloaded through this command, this is prevented by the slave hardware. The slave controller must be reset to reload the alias address. An EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_EEPROM_OPERATION_NTFY_DESC.

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

emReloadSlaveEEPRomReq() Example

EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
dwRes = emReloadSlaveEEPRomReq(dwInstanceId, dwClientId, 
    dwTferId, EC_TRUE, 1001, 5000 /* timeout */);

See also

• emNotify - EC_NOTIFY_EEPROM_OPERATION

• emResetSlaveController()

6.6.30. emNotify - EC_NOTIFY_EEPROM_OPERATION

This notification is given when a SubDevice EEPROM operation is completed.

emNotify - EC_NOTIFY_EEPROM_OPERATION

Parameter

• pbyInBuf: [in] Pointer to EC_T_EEPROM_OPERATION_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_EEPROM_OPERATION_NTFY_DESC

Public Members

EC_T_DWORD dwTferId

Transfer ID. For every new EEPROM operation a unique ID has to be assigned. This ID can be used after completion to identify the transfer.

EC_T_EEPROM_OPERATION_TYPE eType

Type of EEPROM operation

EC_T_DWORD dwResult

Result of EEPROM operation

EC_T_SLAVE_PROP SlaveProp

Slave properties

union _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT

struct _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_ACTIVE

Public Members

EC_T_BOOL bSlavePDIAccessActive

EC_TRUE: EEPROM active by PDI application, EC_FALSE: EEPROM not active

struct _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_READ

Public Members

EC_T_WORD wEEPRomStartOffset

Start address of EEPRom operation. Given by API.

EC_T_WORD *pwData

Pointer to WORD array containing the data. Given by API.

EC_T_DWORD dwReadLen

Number of Words to be read. Given by API.

EC_T_DWORD dwNumOutData

Number of Words actually read from EEPRom

struct _EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_WRITE

Public Members

EC_T_WORD wEEPRomStartOffset

Start address of EEPRom operation. Given by API.

EC_T_WORD *pwData

Pointer to WORD array containing the data. Given by API.

EC_T_DWORD dwWriteLen

Number of Words to be written. Given by API.

enum EC_T_EEPROM_OPERATION_TYPE

Values:

enumerator eEEPRomOp_Unknown

Unknown EEPROM operation, only for internal use

enumerator eEEPRomOp_Assign

Assign slave EEPROM operation, used by emAssignSlaveEEPRomReq

enumerator eEEPRomOp_Active

Active slave EEPROM operation, used by emActiveSlaveEEPRomReq

enumerator eEEPRomOp_Read

Read slave EEPRom operation, used by emReadSlaveEEPRomReq

enumerator eEEPRomOp_Write

Write slave EEPRom operation, used by emWriteSlaveEEPRomReq

enumerator eEEPRomOp_Reload

Reload slave EEPRom operation, used by emReloadSlaveEEPRomReq

enumerator eEEPRomOp_Reset

Reset slave EEPRom operation, used by emResetSlaveController

6.6.31. emResetSlaveController

static EC_T_DWORD ecatResetSlaveController(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

EC_T_DWORD emResetSlaveController(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_DWORD dwTimeout)

Reset EtherCAT slave controller (ESC)

A special sequence of three independent and consecutive frames/commands is sent to the slave (reset register ECAT 0x0040 or PDI 0x0041), after which the slave resets. If that fails, the reset sequence is repeated until it succeeds or the timeout expires. The ESC must support resetting and the slave state should be INIT when calling this function. The number of acyclic frames per cycle EC_T_INIT_MASTER_PARMS.dwMaxAcycFramesPerCycle must be at least 3, otherwise an error is returned. This function may not be called from within the JobTask’s context.

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• dwTimeout – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.

Returns

• EC_E_NOERROR or error code

• EC_E_NOTSUPPORTED if EC_T_INIT_MASTER_PARMS.dwMaxAcycFramesPerCycle is less than 3

• EC_E_SLAVE_NOT_PRESENT if the slave is not present

• EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

emResetSlaveController() Example

/* reset EtherCAT slave controller */
dwRes = emResetSlaveController(dwInstanceId, EC_TRUE, 1001, 5000 /* timeout */);

6.6.32. emIoCtl - EC_IOCTL_ALL_SLAVES_MUST_REACH_MASTER_STATE

EC_IOCTL_ALL_SLAVES_MUST_REACH_MASTER_STATE

Specifies if all the slaves must reach the requested master state.

Parameters

• pbyInBuf – [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE all slaves must reach the master requested state, if set to EC_FALSE the master can reach the requested state even if some slaves are missing or cannot reach the requested state.

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

• pbyOutBuf – [out] Should be set to EC_NULL

• dwOutBufSize – [in] Should be set to 0

• pdwNumOutData – [out] Should be set to EC_NULL

Returns

EC_E_NOERROR or error code

Missing mandatory SubDevices will be signalized by emNotify - EC_NOTIFY_SLAVE_PRESENCE. SubDevices that cannot reach the requested MainDevice state will be signalized by emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE. emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL will not be generated anymore if this IOCTL is called with EC_FALSE, emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR will be still generated.

6.6.33. emGetCfgSlaveInfo

static EC_T_DWORD ecatGetCfgSlaveInfo(EC_T_BOOL bStationAddress, EC_T_WORD wSlaveAddress, EC_T_CFG_SLAVE_INFO *pSlaveInfo)

EC_T_DWORD emGetCfgSlaveInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_CFG_SLAVE_INFO *pSlaveInfo)

Return information about a configured slave from the ENI file.

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• pSlaveInfo – [out] Information about the slave

Returns

EC_E_NOERROR or error code

struct EC_T_CFG_SLAVE_INFO

Public Members

EC_T_DWORD dwSlaveId

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

EC_T_CHAR abyDeviceName[ECAT_DEVICE_NAMESIZE]

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

EC_T_DWORD dwHCGroupIdx

[out] Index of Hot Connect group, 0 for mandatory

EC_T_BOOL bIsPresent

[out] Slave present on bus

EC_T_BOOL bIsHCGroupPresent

[out] Slave’s Hot Connect group 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] Slave’s configured station address (from ENI file)

EC_T_WORD wAutoIncAddress

[out] Slave’s auto increment address (may differ 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): 0xFFFFFFFF = offset not available. 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): 0xFFFFFFFF = offset not available. 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 SetSlaveDisabled / SetSlavesDisabled.

EC_T_BOOL bDisconnected

[out] Slave disconnected by API SetSlaveDisconnected / SetSlavesDisconnected.

EC_T_BOOL bExtended

[out] Slave generated by API ConfigExtend

EC_T_BOOL bDcReferenceClock

[out] Slave is reference clock (from ENI file)

EC_T_BOOL bDcPotentialRefClock

[out] Slave can be used as a reference clock (from ENI file)

EC_T_DWORD dwDcCycleTime0

[out] Cycle time of Sync0 event [ns] (from ENI file)

EC_T_DWORD dwDcCycleTime1

[out] Calculated value dwDcCycleTime1 [ns] = Cycle time of Sync1 event - Cycle time of Sync1 event + Shift time of Sync0 event (from ENI file)

EC_T_INT nDcShiftTime

[out] Shift time of Sync0 event [ns] (from ENI file)

Supported mailbox protocols flags

EC_MBX_PROTOCOL_AOE

EC_MBX_PROTOCOL_EOE

EC_MBX_PROTOCOL_COE

EC_MBX_PROTOCOL_FOE

EC_MBX_PROTOCOL_SOE

EC_MBX_PROTOCOL_VOE

emGetCfgSlaveInfo() Example

/* get information about slave configured in ENI file */
EC_T_CFG_SLAVE_INFO oSlaveInfo;
OsMemset(&oSlaveInfo, 0, sizeof(EC_T_CFG_SLAVE_INFO));
dwRes = emGetCfgSlaveInfo(dwInstanceId, EC_TRUE, 1001, &oSlaveInfo);

6.6.34. emGetCfgSlaveEoeInfo

static EC_T_DWORD ecatGetCfgSlaveEoeInfo(EC_T_BOOL bStationAddress, EC_T_WORD wSlaveAddress, EC_T_CFG_SLAVE_EOE_INFO *pSlaveEoeInfo)

EC_T_DWORD emGetCfgSlaveEoeInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_CFG_SLAVE_EOE_INFO *pSlaveEoeInfo)

Return EoE information about a configured slave from the ENI file.

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• pSlaveEoeInfo – [out] Information about the slave

Returns

• EC_E_NOERROR if successful

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

• EC_E_NO_MBX_SUPPORT if the slave does not support mailbox communication

• EC_E_NO_EOE_SUPPORT if the slave supports mailbox communication, but not EoE

struct EC_T_CFG_SLAVE_EOE_INFO

Public Members

EC_T_DWORD dwSlaveId

[out] Slave ID

EC_T_BOOL bMacAddr

[out] Indicates whether the MAC address could be read and is valid

EC_T_BYTE abyMacAddr[6]

[out] MAC address

EC_T_BOOL bIpAddr

[out] Indicates whether the IP address could be read and is valid

EC_T_IPADDR oIpAddr

[out] IP address

EC_T_BOOL bSubnetMask

[out] Indicates whether the subnet mask could be read and is valid

EC_T_IPADDR oSubnetMask

[out] Subnet mask

EC_T_BOOL bDefaultGateway

[out] Indicates whether the default gateway could be read and is valid

EC_T_IPADDR oDefaultGateway

[out] Default gateway

EC_T_BOOL bDnsServer

[out] Indicates whether the DNS server could be read and is valid

EC_T_IPADDR oDnsServer

[out] DNS server

EC_T_BOOL bDnsName

[out] Indicates whether the DNS name could be read and is valid

EC_T_CHAR szDnsName[32]

[out] DNS name

EC_T_BOOL bDisableEoe

[out] Indicates whether the EoE is Disabled or not

emGetCfgSlaveEoeInfo() Example

/* get EoE information about slave configured in ENI file */
EC_T_CFG_SLAVE_EOE_INFO oSlaveInfo;
OsMemset(&oSlaveInfo, 0, sizeof(EC_T_CFG_SLAVE_EOE_INFO));
dwRes = emGetCfgSlaveEoeInfo(dwInstanceId, EC_TRUE, 1001, &oSlaveInfo);

6.6.35. emGetCfgSlaveSmInfo

static EC_T_DWORD ecatGetCfgSlaveSmInfo(EC_T_BOOL bStationAddress, EC_T_WORD wSlaveAddress, EC_T_CFG_SLAVE_SM_INFO *pSlaveSmInfo)

EC_T_DWORD emGetCfgSlaveSmInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_CFG_SLAVE_SM_INFO *pSlaveSmInfo)

Return SyncManager information of 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

• pSlaveSmInfo – [out] Information about the slave.

Returns

EC_E_NOERROR or error code

struct EC_T_CFG_SLAVE_SM_ENTRY

Public Members

EC_T_WORD wPhysAddr

[out] ESC (0x800 + y * 8)

EC_T_WORD wLength

[out] ESC (0x802 + y * 8)

EC_T_BYTE byOpMode

[out] Bits 0..1 ESC (0x804 + y * 8)

EC_T_BYTE byDirection

[out] Bits 2..3 ESC (0x804 + y * 8)

EC_T_DWORD dwPdBitOffs

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

EC_T_DWORD dwPdBitSize

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

EC_T_WORD wWkcStateDiagBitOffs

[out] Offset of WkcState bit in diagnosis image

EC_T_WORD wMasterSyncUnit

[out] Sync Unit (ENI: ProcessData/TxPdo[1..4]@Su)

struct EC_T_CFG_SLAVE_SM_INFO

Public Members

EC_T_DWORD dwSlaveId

[out] Slave ID

EC_T_DWORD dwSmInfoNumOf

[out] Number of available sync managers

EC_T_CFG_SLAVE_SM_ENTRY aoSmInfos[ECREG_SYNCMANAGER_MAX_NUMOF]

[out] Sync managers info

emGetCfgSlaveSmInfo() Example

/* get information about slave's sync managers configured in ENI file */
EC_T_CFG_SLAVE_SM_INFO oSlaveSmInfo;
OsMemset(&oSlaveSmInfo, 0, sizeof(EC_T_CFG_SLAVE_SM_INFO));
dwRes = emGetCfgSlaveSmInfo(dwInstanceId, EC_TRUE, 1001, &oSlaveSmInfo);

6.6.36. emGetBusSlaveInfo

static EC_T_DWORD ecatGetBusSlaveInfo(EC_T_BOOL bStationAddress, EC_T_WORD wSlaveAddress, EC_T_BUS_SLAVE_INFO *pSlaveInfo)

EC_T_DWORD emGetBusSlaveInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BUS_SLAVE_INFO *pSlaveInfo)

Return information about a slave connected to the EtherCAT bus.

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• pSlaveInfo – [out] Information from the slave

Returns

• EC_E_NOERROR if successful

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

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

EC_T_DWORD dwPropagDelay

[out] Propagation delay [ns]. ESC register 0x0928.

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

Port Slave ID’s

MASTER_SLAVE_ID

SIMULATOR_SLAVE_ID

MASTER_RED_SLAVE_ID

EL9010_SLAVE_ID

FRAMELOSS_SLAVE_ID

JUNCTION_RED_FLAG

EC_LINECROSSED_ flags

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

EC_LINECROSSED_UNEXPECTED_CABLE_RED

emGetBusSlaveInfo() Example

/* get information about slave connected to EtherCAT bus */
EC_T_BUS_SLAVE_INFO oSlaveInfo;
OsMemset(&oSlaveInfo, 0, sizeof(EC_T_BUS_SLAVE_INFO));
dwRes = emGetBusSlaveInfo(dwInstanceId, EC_TRUE, 1001, &oSlaveInfo);

6.6.37. emReadSlaveIdentification

static EC_T_DWORD ecatReadSlaveIdentification(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wAdo, EC_T_WORD *pwValue, EC_T_DWORD dwTimeout)

EC_T_DWORD emReadSlaveIdentification(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wAdo, EC_T_WORD *pwValue, EC_T_DWORD dwTimeout)

Read identification value from a 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 if another transfer request is already pending or the master or the corresponding slave is currently changing its operational state

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

• EC_E_ADO_NOT_SUPPORTED if the slave does not support requesting ID mechanism

• EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

emReadSlaveIdentification() Example

/* get identification value from slave */
EC_T_WORD wValue = 0;
dwRes = emReadSlaveIdentification(dwInstanceId, EC_TRUE, 1001, 
    0x0134 /* explicit device ID */, &wValue, 5000 /* timeout */);

6.6.38. emReadSlaveIdentificationReq

static EC_T_DWORD ecatReadSlaveIdentificationReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wAdo, EC_T_WORD *pwValue, EC_T_DWORD dwTimeout)

EC_T_DWORD emReadSlaveIdentificationReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wAdo, EC_T_WORD *pwValue, EC_T_DWORD dwTimeout)

Request the identification value from a slave and returns immediately.

A notification EC_NOTIFY_SLAVE_IDENTIFICATION is given on completion or timeout. This function may be called from within the JobTask’s context.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_SLAVE_IDENTIFICATION_NTFY_DESC.

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• wAdo – [in] ADO used for identification command

• pwValue – [out] Pointer to Word value containing the Identification value, must be valid until the request complete.

• dwTimeout – [in] Timeout [ms]

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if 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_ADO_NOT_SUPPORTED if the slave does not support requesting ID mechanism

emReadSlaveIdentificationReq() Example

/* get identification value from slave (non-blocking) */
EC_T_WORD wValue = 0;
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
dwRes = emReadSlaveIdentificationReq(dwInstanceId, dwClientId,
    dwTferId, EC_TRUE, 1001, 0x0134 /* explicit device ID */, &wValue, 5000 /* timeout */);

See also

emNotify - EC_NOTIFY_SLAVE_IDENTIFICATION

6.6.39. emNotify - EC_NOTIFY_SLAVE_IDENTIFICATION

This notification is given, when the read SubDevice identification request is completed.

emNotify - EC_NOTIFY_SLAVE_IDENTIFICATION

Parameter

• pbyInBuf: [in] Pointer to EC_T_SLAVE_IDENTIFICATION_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_IDENTIFICATION_NTFY_DESC

Public Members

EC_T_DWORD dwTferId

Transfer ID. For every new port operation a unique ID has to be assigned. This ID can be used after completion to identify the transfer.

EC_T_DWORD dwResult

Result of request

EC_T_SLAVE_PROP SlaveProp

Slave properties

EC_T_WORD wAdo

Slave address offset used for identification. Given by API.

EC_T_WORD wValue

Slave identification value. Given by API.

6.6.40. emIoCtl - EC_IOCTL_SET_AUTO_ACK_AL_STATUS_ERROR_ENABLED

EC_IOCTL_SET_AUTO_ACK_AL_STATUS_ERROR_ENABLED

Specifies if slave errors must be automatically acknowledged.

Parameters

• pbyInBuf – [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE slave errors must be automatically acknowledged, if set to EC_FALSE the application must acknowledge slave errors explicitly.

• 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

Returns

EC_E_NOERROR or error code

The pending SubDevice error will be acknowledged during the next emSetSlaveState() call.

6.6.41. emIoCtl - EC_IOCTL_SET_AUTO_ADJUST_CYCCMD_WKC_ENABLED

EC_IOCTL_SET_AUTO_ADJUST_CYCCMD_WKC_ENABLED

Specifies if the cyclic commands expected WKC must be automatically adjusted according to the state and the presence of the slaves.

Parameters

• pbyInBuf – [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE cyclic commands expected WKC must be automatically adjusted, if set to EC_FALSE the cyclic commands expected WKC stays unchanged.

• 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

Returns

EC_E_NOERROR or error code

If TRUE, the notification emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR is only generated if a SubDevice doesn’t increment the WKC although it should. AUTO_ADJUST_CYCCMD_WKC is disabled by default.

See also

• Cyclic cmd WKC validation and Frame Loss

• Working Counter (WKC) State in Diagnosis Image

6.6.42. emSetSlaveDisabled

Before using this function, please check if the following patents have to be taken into consideration for your application and use case:

• JP2014146077: CONTROL DEVICE AND OPERATION METHOD FOR CONTROL DEVICE

• JP2014146070: CONTROL DEVICE, CONTROL METHOD, AND PROGRAM

• JP2014120884: INFORMATION PROCESSING APPARATUS, INFORMATION ROCESSING PROGRAM, AND INFORMATION PROCESSING METHOD

static EC_T_DWORD ecatSetSlaveDisabled(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bDisabled)

EC_T_DWORD emSetSlaveDisabled(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bDisabled)

Enable or disable a specific slave.

The EtherCAT state of disabled slaves cannot be set higher than PREOP. If the state is higher than PREOP at the time this function is called the state will be automatically changed to PREOP. The information about the last requested state is lost and is set to PREOP too.

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• bDisabled – [in] EC_TRUE: Disable slave, EC_FALSE: Enable slave

Returns

EC_E_NOERROR or error code

emSetSlaveDisabled() Example

/* enable or disable specific slave */
dwRes = emSetSlaveDisabled(dwInstanceId, EC_TRUE, 1002, EC_TRUE /* disabled */);

6.6.43. emIoCtl - EC_IOCTL_SET_SLAVE_MAX_STATE

Specifies maximum state for specific slave.

EC_IOCTL_SET_SLAVE_MAX_STATE

Set maximum state for the slave.

Parameters

• pbyInBuf – [in] Pointer to struct EC_T_SLAVE_MAX_STATE_DESC

• dwInBufSize – [in] Size of the input buffer in bytes, e.g. sizeof(EC_T_SLAVE_MAX_STATE_DESC)

• pbyOutBuf – [out] Should be set to EC_NULL

• dwOutBufSize – [in] Should be set to 0

• pdwNumOutData – [out] Should be set to EC_NULL

Returns

EC_E_NOERROR or error code

struct EC_T_SLAVE_MAX_STATE_DESC

Public Members

EC_T_DWORD dwSlaveId

[in] Slave ID

EC_T_STATE eState

[in] Requested Slave State

6.6.44. emSetSlaveDisconnected

Before using this function, please check if the following patents have to be taken into consideration for your application and use case:

• JP2014146077: CONTROL DEVICE AND OPERATION METHOD FOR CONTROL DEVICE

• JP2014146070: CONTROL DEVICE, CONTROL METHOD, AND PROGRAM

• JP2014120884: INFORMATION PROCESSING APPARATUS, INFORMATION ROCESSING PROGRAM, AND INFORMATION PROCESSING METHOD

static EC_T_DWORD ecatSetSlaveDisconnected(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bDisconnected)

EC_T_DWORD emSetSlaveDisconnected(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_BOOL bDisconnected)

Mark specific slave for connection or disconnection.

The EtherCAT state of disconnected slaves cannot be set higher than INIT. If the state is higher than INIT at the time this function is called, the state will be automatically changed to INIT. The information about the last requested state is lost and is set to INIT too.

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• bDisconnected – [in] EC_TRUE: Mark slave for disconnection, EC_FALSE: Mark slave for (re-)connection

Returns

EC_E_NOERROR or error code

emSetSlaveDisconnected() Example

/*Connect or disconnect specific slave*/
dwRes = emSetSlaveDisconnected(dwInstanceId, EC_TRUE, 1002, 
    EC_TRUE /* disconnected */);

6.6.45. emSetSlavesDisconnected

Before using this function, please check if the following patents have to be taken into consideration for your application and use case:

• JP2014146077: CONTROL DEVICE AND OPERATION METHOD FOR CONTROL DEVICE

• JP2014146070: CONTROL DEVICE, CONTROL METHOD, AND PROGRAM

• JP2014120884: INFORMATION PROCESSING APPARATUS, INFORMATION ROCESSING PROGRAM, AND INFORMATION PROCESSING METHOD

static EC_T_DWORD ecatSetSlavesDisconnected(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_SLAVE_SELECTION eSlaveSelection, EC_T_BOOL bDisconnected)

EC_T_DWORD emSetSlavesDisconnected(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_SLAVE_SELECTION eSlaveSelection, EC_T_BOOL bDisconnected)

Mark a specific group of slaves for connection or disconnection.

Parameters

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

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

• wSlaveAddress – [in] Slave address according bFixedAddressing

• eSlaveSelection – [in] Slave selection criteria

• bDisconnected – [in] EC_TRUE: mark slaves for disconnection, EC_FALSE: mark slaves for connection

Returns

• EC_E_NOERROR if successful

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

emSetSlavesDisconnected() Example

/* set specific group of slaves for connection or disconnection */
dwRes = emSetSlavesDisconnected(dwInstanceId, EC_TRUE, 1001, 
    eSlaveSelectionTopoFollowers, EC_TRUE /* disconnected*/);

See also

emSetSlaveDisconnected()

6.6.46. emGetSlavePortState

static EC_T_DWORD ecatGetSlavePortState(EC_T_DWORD dwSlaveId, EC_T_WORD *pwPortState)

EC_T_DWORD emGetSlavePortState(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_WORD *pwPortState)

Returns the state of the slave ports.

Parameters

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

• dwSlaveId – [in] Slave ID

• pwPortState –

  [out] Slave port state.

  Format: wwww xxxx yyyy zzzz (each nibble : port 3210)

  wwww : Signal detected 1=yes, 0=no (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

emGetSlavePortState() Example

EC_T_DWORD dwSlaveId = 2;
EC_T_WORD wPortState = 0;
dwRes = emGetSlavePortState(dwInstanceId, dwSlaveId, &wPortState);

See also

emGetSlaveId()

6.6.47. emSetSlavePortState

static EC_T_DWORD ecatSetSlavePortState(EC_T_DWORD dwSlaveId, EC_T_WORD wPort, EC_T_BOOL bClose, EC_T_BOOL bForce, EC_T_DWORD dwTimeout)

EC_T_DWORD emSetSlavePortState(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_WORD wPort, EC_T_BOOL bClose, EC_T_BOOL bForce, EC_T_DWORD dwTimeout)

Open or close slave port.

This function allows to open or close a specific slave port in different ways. It can also be used to re-open ports closed by a rescue scan.

Parameters

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

• dwSlaveId – [in] Slave ID

• wPort – [in] Port to open or close. Can be ESC_PORT_A, ESC_PORT_B, ESC_PORT_C, ESC_PORT_D.

• bClose – [in] EC_TRUE: close port, EC_FALSE: open port

• bForce – [in] EC_TRUE: port will be closed or open, EC_FALSE: port will be set in AutoClose mode

• dwTimeout – [in] Timeout [ms]

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if EtherCAT stack isn’t initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range

• EC_E_SLAVE_NOT_PRESENT if slave not present

• EC_E_NOTFOUND if no slave matching dwSlaveId can be found

• EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

emSetSlavePortState() Example

EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
dwRes = emSetSlavePortState(dwInstanceId, dwSlaveId, ESC_PORT_B, 
    EC_TRUE /* close */ , EC_TRUE /* force */, 5000 /* timeout */);

See also

• emRescueScan()

• emGetSlaveId()

6.6.48. emSetSlavePortStateReq

static EC_T_DWORD ecatSetSlavePortStateReq(EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_DWORD dwSlaveId, EC_T_WORD wPort, EC_T_BOOL bClose, EC_T_BOOL bForce, EC_T_DWORD dwTimeout)

EC_T_DWORD emSetSlavePortStateReq(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTferId, EC_T_DWORD dwSlaveId, EC_T_WORD wPort, EC_T_BOOL bClose, EC_T_BOOL bForce, EC_T_DWORD dwTimeout)

Requests Open or close slave port operation and returns immediately.

An EC_T_PORT_OPERATION_NTFY_DESC is given on completion. This function can be called to re-open ports closed by a rescue scan.

Parameters

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

• dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

• dwTferId – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within EC_T_PORT_OPERATION_NTFY_DESC.

• dwSlaveId – [in] Slave ID

• wPort – [in] Port to open or close. Can be ESC_PORT_A, ESC_PORT_B, ESC_PORT_C, ESC_PORT_D.

• bClose – [in] EC_TRUE: close port, EC_FALSE: open port

• bForce – [in] EC_TRUE: port will be closed or open, EC_FALSE: port will be set in AutoClose mode

• dwTimeout – [in] Timeout [ms]

Returns

• EC_E_NOERROR if successful

• EC_E_INVALIDSTATE if EtherCAT stack isn’t initialized

• EC_E_INVALIDPARM if dwInstanceID is out of range

• EC_E_SLAVE_NOT_PRESENT if slave not present

• EC_E_NOTFOUND if no slave matching dwSlaveId can be found

emSetSlavePortStateReq() Example

EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
dwRes = emSetSlavePortStateReq(dwInstanceId, dwTferId, dwClientId, 
    dwSlaveId, ESC_PORT_B, EC_TRUE /* close */ , EC_TRUE /* force */, 5000 /* timeout */);

See also

• emNotify - EC_NOTIFY_PORT_OPERATION

• emRescueScan()

• emGetSlaveId()

6.6.49. emNotify - EC_NOTIFY_PORT_OPERATION

This notification is given, when the port operation request is completed.

emNotify - EC_NOTIFY_PORT_OPERATION

Parameter

• pbyInBuf: [in] Pointer to EC_T_PORT_OPERATION_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_PORT_OPERATION_NTFY_DESC

Public Members

EC_T_DWORD dwTferId

Transfer ID. For every new port operation a unique ID has to be assigned. This ID can be used after completion to identify the transfer.

EC_T_DWORD dwResult

Result of request

EC_T_SLAVE_PROP SlaveProp

Slave properties

EC_T_WORD wPortStateOld

Old state of the slave ports

EC_T_WORD wPortStateNew

New state of the slave ports

See also

emGetSlavePortState()

6.6.50. emIoCtl - EC_IOCTL_SET_NEW_BUSSLAVES_TO_INIT

EC_IOCTL_SET_NEW_BUSSLAVES_TO_INIT

Force state change to INIT for all new slaves in the network after detection.

Parameters

• pbyInBuf – [in] Pointer to EC_T_BOOL. EC_TRUE: Force state change, EC_FALSE: No state change.

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

• pbyOutBuf – [out] Should be set to EC_NULL

• dwOutBufSize – [in] Should be set to 0

• pdwNumOutData – [out] Should be set to EC_NULL

Returns

EC_E_NOERROR or error code

Default: No state change after detection