6.14. Vendor specific protocol over EtherCAT (VoE)

VoE is for vendor specific protocols. With VoE the vendor has access to a raw EtherCAT mailbox without a specific header or specific protocol mechanism.

6.14.1. emVoeWrite

static EC_T_DWORD ecatVoeWrite(EC_T_DWORD dwSlaveId, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD dwTimeout)
EC_T_DWORD emVoeWrite(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD dwTimeout)

Execute a VoE mailbox write to an EtherCAT slave device.

This function blocks until the VoE write has been successfully completed or an error has occurred.

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

  • dwSlaveId – [in] Slave ID

  • pbyData – [in] Buffer containing transfered data

  • dwDataLen – [in] Buffer length [bytes] The maximum data length including 6 bytes for the mailbox header is given at EC_T_CFG_SLAVE_INFO.dwMbxOutSize

  • dwTimeout – [in] Timeout [ms] The function will block at most for this time.

Returns

EC_E_NOERROR or error code

6.14.2. emVoeWriteReq

static EC_T_DWORD ecatVoeWriteReq(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_DWORD dwTimeout)
EC_T_DWORD emVoeWriteReq(EC_T_DWORD dwInstanceID, EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_DWORD dwTimeout)

Initiates a VoE mailbox write to an EtherCAT slave device.

The amount of data bytes to write has to be stored in EC_T_MBXTFER.dwDataLen. The maximum data length including 6 bytes for the mailbox header is given at EC_T_CFG_SLAVE_INFO.dwMbxOutSize. A unique transfer ID must be written into EC_T_MBXTFER.dwTferId.

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

  • pMbxTfer – [in] Mailbox transfer object

  • dwSlaveId – [in] Slave ID

  • dwTimeout – [in] Timeout [ms], EC_NOWAIT returns the function immediately

Returns

EC_E_NOERROR or error code

See also

emGetSlaveId()

6.14.3. emVoeRead

static EC_T_DWORD ecatVoeRead(EC_T_DWORD dwSlaveId, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD *pdwOutDataLen, EC_T_DWORD dwTimeout)
EC_T_DWORD emVoeRead(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD *pdwOutDataLen, EC_T_DWORD dwTimeout)

Retrieves VoE mailbox, that was sent by an EtherCAT slave device.

If a VoE mailbox was already received, further received VoE mailboxes will be discarded as long as this function was not called. The received data includes the Mailbox header of type ETHERCAT_MBOX_HEADER

followed by the VoE payload.

This function blocks until the VoE data has been successfully received or an error has occurred.

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

  • dwSlaveId – [in] Slave ID

  • pbyData – [out] Buffer receiving transfered data

  • dwDataLen – [in] Buffer length [byte]

  • pdwOutDataLen – [out] Length of received data [byte]

  • dwTimeout – [in] Timeout [ms] The function will block at most for this time. EC_NOWAIT returns the function immediately

Returns

struct ETHERCAT_MBOX_HEADER

Public Members

EC_T_WORD wLength

Following bytes (payload length)

EC_T_WORD wAddress

Station address of destination (READ) or source (WRITE). 0 == Master (ETHERCAT_MBOX_MASTER_ADDRESS)

EC_T_BYTE byChnPri

Channel, Priority

EC_T_BYTE byTypCntRsvd

wMbxType, Counter, Rsvd

See also

emGetSlaveId()

6.14.4. emNotify - eMbxTferType_VOE_READ

The corresponding Slave ID can be found in pMbxTfer->dwTferId. The MBX data stored in pMbxTfer->pbyMbxTferData may have to be buffered by the client. After emNotify returns the pointer and thus the data is invalid. Access to the memory area pointed to by pMbxTfer-> pbyMbxTferData after returning from emNotify is illegal and the results are undefined.

emNotify - eMbxTferType_VOE_READ
Parameter
  • pbyInBuf: [in] pMbxTfer - Pointer to a structure of type EC_T_MBXTFER, this structure contains the used mailbox transfer object . To retrieve this VoE mailbox data emVoeRead has to be called.

  • dwInBufSize: [in] Size of the transfer object.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

6.14.5. emNotify - eMbxTferType_VOE_WRITE

VoE mailbox was successfully written to the VoE slave. The corresponding transfer ID can be found in pMbxTfer->dwTferId. The transfer result is stored in pMbxTfer->dwErrorCode.

emNotify - eMbxTferType_VOE_WRITE
Parameter
  • pbyInBuf: [in] pMbxTfer - Pointer to a structure of type EC_T_MBXTFER, this structure contains the corresponding mailbox transfer object.

  • dwInBufSize: [in] Size of the transfer object.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL