6.15. Raw command transfer

6.15.1. emTferSingleRawCmd

static EC_T_DWORD ecatTferSingleRawCmd(EC_T_BYTE byCmd, EC_T_DWORD dwMemoryAddress, EC_T_BYTE *pbyData, EC_T_WORD wLen, EC_T_DWORD dwTimeout)
EC_T_DWORD emTferSingleRawCmd(EC_T_DWORD dwInstanceID, EC_T_BYTE byCmd, EC_T_DWORD dwMemoryAddress, EC_T_BYTE *pbyData, EC_T_WORD wLen, EC_T_DWORD dwTimeout)

Transfers a single raw EtherCAT command to one or multiple slaves and waits for the result.

Using this function it is possible exchange arbitrary data between the master and the slaves. When the master receives the response to the queued frame it raises EC_NOTIFY_RAWCMD_DONE to all clients. This function blocks until the command is completely processed. In case of read commands the slave data will be written back into the given memory area. If a timeout occurs (e.g. due to a bad line quality) the corresponding frame will be sent again. The timeout value and retry counter can be set using the master configuration parameters dwEcatCmdTimeout and dwEcatCmdMaxRetries. The call will return in any case (without waiting for the number of retries specified in dwEcatCmdMaxRetries) if the time determined with the dwTimeout parameter elapsed. Caveat: Using auto increment addressing (APRD, APWR, APRW) may lead to unexpected results in case the selected slave does not increment the working counter. In such cases the EtherCAT command would be handled by the slave directly behind the selected one. This function may not be called from within the JobTask’s context.

Parameters

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

  • byCmd – [in] EtherCAT command type. EC_CMD_TYPE_…

  • dwMemoryAddress – [in] Slave memory address, depending on the command to be sent this is either a physical or logical address.

  • pbyData – [in, out] Buffer containing or receiving transfered data

  • wLen – [in] Number of bytes to transfer

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

  • EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

The following EtherCAT commands are supported:

  • eRawCmd_APRD Auto Increment Physical Read (avoid to use, see below)

  • eRawCmd_APWR Auto Increment Physical Write (avoid to use, see below)

  • eRawCmd_APRW Auto Increment Physical Read/Write (avoid to use, see below)

  • eRawCmd_FPRD Fixed addressed Physical Read

  • eRawCmd_FPWR Fixed addressed Physical Write

  • eRawCmd_FPRW Fixed addressed Physical Read/Write

  • eRawCmd_BRD Broadcast (wire or’ed) Read

  • eRawCmd_BWR Broadcast Write

  • eRawCmd_BRW Broadcast Read/Write

  • eRawCmd_LRD Logical Read

  • eRawCmd_LWR Logical Write

  • eRawCmd_LRW Logical Read/Write

  • eRawCmd_ARMW Auto Increment Physical Read, multiple Write

6.15.2. emClntSendRawMbx

static EC_T_DWORD ecatClntSendRawMbx(EC_T_DWORD dwClntId, EC_T_BYTE *pbyMbxCmd, EC_T_DWORD dwMbxCmdLen, EC_T_DWORD dwTimeout)
EC_T_DWORD emClntSendRawMbx(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClntId, EC_T_BYTE *pbyMbxCmd, EC_T_DWORD dwMbxCmdLen, EC_T_DWORD dwTimeout)

Send a raw mailbox command.

Parameters

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

  • dwClntId – [in] Client ID

  • pbyMbxCmd – [in] Buffer containing the raw mailbox command starting with mailbox header

  • dwMbxCmdLen – [in] Length of pbyMbxCmd buffer

  • dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

6.15.3. emClntQueueRawCmd

static EC_T_DWORD ecatClntQueueRawCmd(EC_T_DWORD dwClntId, EC_T_WORD wInvokeId, EC_T_BYTE byCmd, EC_T_DWORD dwMemoryAddress, EC_T_BYTE *pbyData, EC_T_WORD wLen)
EC_T_DWORD emClntQueueRawCmd(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClntId, EC_T_WORD wInvokeId, EC_T_BYTE byCmd, EC_T_DWORD dwMemoryAddress, EC_T_BYTE *pbyData, EC_T_WORD wLen)

Transfers a raw EtherCAT command to one or multiple slaves.

Using this function it is possible to exchange data between the master and the slaves. When the response to the queued frame is received, the notification EC_NOTIFY_RAWCMD_DONE is given for the appropriate client. This function queues a single EtherCAT command. Queued raw commands will be sent after sending cyclic process data values. If a timeout occurs the corresponding frame will be sent again, the timeout value and retry counter can be set using the master configuration parameters EC_T_INIT_MASTER_PARMS.dwEcatCmdTimeout and EC_T_INIT_MASTER_PARMS.dwEcatCmdMaxRetries

.

Using auto increment addressing (APRD, APWR, APRW) may lead to unexpected results in case the selected slave does not increment the working counter. In such cases the EtherCAT command would be handled by the slave directly behind the selected one. This function may not be called from within the JobTask’s context.

Parameters

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

  • dwClntId – [in] Client ID to be notified (0 if all registered clients shall be notified).

  • wInvokeId – [in] Invoke ID to reassign the results to the sent CMD

  • byCmd – [in] EtherCAT command

  • dwMemoryAddress – [in] Slave memory address, depending on the command to be sent this is either a physical or logical address

  • pbyData – [in, out] Buffer containing or receiving transfered data. In case a read-only command is queued (e.g. APRD) this pointer should be set to a value of EC_NULL.

  • wLen – [in] Number of bytes to transfer.

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

  • EC_E_BUSY if the master or the corresponding slave is currently changing its operational state

  • 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

The following EtherCAT commands are supported:

enum EC_T_RAWCMD

Values:

enumerator eRawCmd_APRD

Auto-Increment physical read

enumerator eRawCmd_APWR

Auto-Increment physical write

enumerator eRawCmd_APRW

Auto-Increment physical read/write

enumerator eRawCmd_BRD

Broadcast (wire-or’ed) read

enumerator eRawCmd_BWR

Broadcast write

enumerator eRawCmd_BRW

Broadcast read/write

enumerator eRawCmd_LRD

Logical read

enumerator eRawCmd_LWR

Logical write

enumerator eRawCmd_LRW

Logical read/write

enumerator eRawCmd_ARMW

Auto-increment physical read, multiple write

enumerator eRawCmd_FPRD

Fixed address physical read

enumerator eRawCmd_FPWR

Fixed address physical write

enumerator eRawCmd_FPRW

Fixed address physical read/write

6.15.4. emQueueRawCmd

static EC_T_DWORD ecatQueueRawCmd(EC_T_WORD wInvokeId, EC_T_BYTE byCmd, EC_T_DWORD dwMemoryAddress, EC_T_BYTE *pbyData, EC_T_WORD wLen)
EC_T_DWORD emQueueRawCmd(EC_T_DWORD dwInstanceID, EC_T_WORD wInvokeId, EC_T_BYTE byCmd, EC_T_DWORD dwMemoryAddress, EC_T_BYTE *pbyData, EC_T_WORD wLen)

Transfers a raw EtherCAT command to one or multiple slaves.

All registered clients will be notified. This function may not be called from within the JobTask’s context.

Parameters

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

  • wInvokeId – [in] Invoke ID to reassign the results to the sent CMD

  • byCmd – [in] EtherCAT command

  • dwMemoryAddress – [in] Slave memory address, depending on the command to be sent this is either a physical or logical address.

  • pbyData – [in, out] Buffer containing or receiving transfered data In case a read-only command is queued (e.g. APRD) this pointer should be set to a value of EC_NULL

  • wLen – [in] Number of bytes to transfer.

Returns

EC_E_NOERROR or error code

See also

emClntQueueRawCmd()

6.15.5. emNotify - EC_NOTIFY_RAWCMD_DONE

This notification is given when the response to an emTferSingleRawCmd() or emClntQueueRawCmd() is received.

emNotify - EC_NOTIFY_RAWCMD_DONE
Parameter

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

Public Members

EC_T_DWORD dwInvokeId

[in] Invoke Id from callee. Only lower 16 bits are relevant

EC_T_DWORD dwResult

[in] EC_E_NOERROR on success, error code otherwise

EC_T_DWORD dwWkc

[in] Received working counter

EC_T_DWORD dwCmdIdx

[in] Command Index Field

EC_T_DWORD dwAddr

[in] Address Field

EC_T_DWORD dwLength

[in] Length of data portion (11 relevant bits)

EC_T_BYTE *pbyData

[in] Pointer to data portion within a PDU. The callback function has to store the data into application memory, the data pointer will be invalid after returning from the callback