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
See also
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
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
EC_E_NOERROR if the VoE slave has provided some VoE data
EC_E_INVALIDSTATE if master isn’t initialized
EC_E_INVALIDPARM if dwInstanceID is out of range
EC_E_TIMEOUT if dwTimeout elapsed during the API call
EC_E_VOE_NO_MBX_RECEIVED no VoE data received
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive
See also
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_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [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_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [out] Should be set to EC_NULL