6.9. EtherCAT Mailbox Transfer
To be able to initiate a mailbox transfer the client has to create a mailbox transfer object first. This mailbox transfer object also contains the memory where the data to be transferred is stored. The one client that initiated the mailbox transfer will be notified about a mailbox transfer completion by the emNotify()
callback function.
To be able to identify the transfer which was completed the client has to assign a unique transfer identifier for each mailbox transfer. The mailbox transfer object can only be used for one single mailbox transfer. If multiple transfers shall be initiated in parallel the client has to create one transfer object for each. The transfer object can be re-used after mailbox transfer completion.
Typical mailbox transfer sequence:
- Create a transfer object (for example a SDO download transfer object).
MbxTferDesc.dwMaxDataLen = 10 MbxTferDesc.pbyMbxTferDescData=(EC_T_PBYTE)OsMalloc(MbxTferDesc.dwMaxDataLen) pMbxTfer = emMbxTferCreate(&MbxTferDesc) state of the transfer object = Idle
- Copy the data to be transferred to the slave into the transfer object, determine the transfer ID, store the client ID in the object and initiate the transfer (e.g. a SDO download). A transfer may only be initiated if the state of the transfer object is Idle.
OsMemcpy(pMbxTfer->pbyMbxTferData, "0123456789", 10); pMbxTfer->dwTferId = 1; pMbxTfer->dwClntId = dwClntId; pMbxTfer->dwDataLen=10; dwResult = emCoeSdoDownloadReq(pMbxTfer, dwSlaveId, wObIndex, ...); state of the transfer object = Pend or TferReqError
The state will then be set to Pend to indicate that this mailbox transfer object currently is in use and the transfer is not completed. If the mailbox transfer cannot be initiated the master will set the object into the state TferReqError - in such cases the client is responsible to set the state back into Idle.
- If the mailbox transfer is completed the notification callback function of the corresponding client (
emNotify()
) will be called with a pointer to the mailbox transfer object. The state of the transfer object is set to TferDone prior to callingemNotify()
. if( dwResult != EC_E_NOERROR ) { ... } emNotify( EC_NOTIFY_MBOXRCV, pParms ) state of the transfer object = TferDone
- If the mailbox transfer is completed the notification callback function of the corresponding client (
- In case of errors the appropriate error handling has to be executed. Application must set the transfer object state to Idle.
if( pMbxTfer->dwErrorCode != EC_E_NOERROR ) { ... } In emNotify: application may set transfer object state to Idle
- Delete the transfer object. Alternatively this object can be used for the next transfer.
emMbxTferDelete(pMbxTfer);
6.9.1. Mailbox transfer object states
The following states exist for a mailbox transfer object:
A mailbox transfer will be processed by the master independently from the client’s timeout setting. Some types of mailbox transfers can be cancelled by the client, e.g. if the client’s timeout elapsed.
After completion of the mailbox transfer (with timeout and the client may finally set the transfer object into the state EC_T_MBXTFER_STATUS::eMbxTferStatus_Idle
.
New mailbox transfers can only be requested if the object is in the state EC_T_MBXTFER_STATUS::eMbxTferStatus_Idle
.
See also
6.9.2. emMbxTferCreate
-
static EC_T_MBXTFER *ecatMbxTferCreate(EC_T_MBXTFER_DESC *pMbxTferDesc)
-
EC_T_MBXTFER *emMbxTferCreate(EC_T_DWORD dwInstanceID, EC_T_MBXTFER_DESC *pMbxTferDesc)
Creates a mailbox transfer object.
While a mailbox transfer is in process the related transfer object and the corresponding memory may not be accessed. After a mailbox transfer completion the object may be used for the next transfer. The mailbox transfer object has to be deleted by calling ecatMbxTferDelete if it is not needed any more.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pMbxTferDesc – [in] Pointer to the mailbox transfer descriptor. Determines details of the mailbox transfer.
- Returns
Pointer to the created mailbox transfer object if successful
EC_NULL on error (No memory left)
-
struct EC_T_MBXTFER
Public Members
-
EC_T_MBXTFER_DESC MbxTferDesc
[out] Mailbox transfer descriptor. All elements of pMbxTferDesc will be stored here
-
EC_T_MBXTFER_TYPE eMbxTferType
[] This type information is written to the Mailbox Transfer Object by the last call to a mailbox command function. It may be used as an information, and is required to fan out consecutive notifications. This value is only valid until next mailbox relevant API call, where this value may be overwritten
-
EC_T_DWORD dwDataLen
[] Amount of data bytes for the next mailbox transfer. If the mailbox transfer does not transfer data from or to the slave this parameter will be ignored. This element has to be set to an appropriate value every time prior to initiate a new request. When the transfer is completed (emNotify) this value will contain the amount of data that was actually transferred
-
EC_T_BYTE *pbyMbxTferData
[in/out] Pointer to data. In case of a download transfer the client has to store the data in this location. In case of an upload transfer this element points to the received data. Access to data that was uploaded from a slave is only valid within the notification function because the buffer will be re-used by the master “this data has to be copied into a separate buffer in case it has to be used later by the client
-
EC_T_MBXTFER_STATUS eTferStatus
[out] Transfer state. After a new transfer object is created the state will be set to eMbxTferStatus_Idle
-
EC_T_DWORD dwTferId
[] Transfer ID. For every new mailbox transfer a unique ID has to be assigned. This ID can be used after mailbox transfer completion to identify the transfer
-
EC_T_MBX_DATA MbxData
[] Mailbox data. This element contains mailbox transfer data, e.g. the CoE object dictionary list.
-
EC_T_MBXTFER_DESC MbxTferDesc
-
union EC_T_MBX_DATA
Public Members
-
EC_T_AOE_CMD_RESPONSE AoE_Response
AoE
-
EC_T_MBX_DATA_COE CoE
CoE
-
EC_T_COE_ODLIST CoE_ODList
CoE Object Dictionary list
-
EC_T_COE_OBDESC CoE_ObDesc
CoE object description
-
EC_T_COE_ENTRYDESC CoE_EntryDesc
CoE entry description
-
EC_T_COE_EMERGENCY CoE_Emergency
CoE emergency data
-
EC_T_MBX_DATA_COE_INITCMD CoE_InitCmd
CoE InitCmd
-
EC_T_MBX_DATA_FOE FoE
FoE
-
EC_T_AOE_CMD_RESPONSE AoE_Response
See also
EC-Master Class A about AoE, FoE and VoE mailbox protocols.
6.9.3. emMbxTferAbort
-
static EC_T_DWORD ecatMbxTferAbort(EC_T_MBXTFER *pMbxTfer)
-
EC_T_DWORD emMbxTferAbort(EC_T_DWORD dwInstanceID, EC_T_MBXTFER *pMbxTfer)
Abort a running mailbox transfer.
This function may not be called from within the JobTask’s context.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pMbxTfer – [in] Mailbox transfer object created with emMbxTferCreate
- Returns
EC_E_NOERROR if successful
Currently only supported for FoE Transfer, CoE Download and CoE Upload.
6.9.4. emMbxTferDelete
-
static EC_T_VOID ecatMbxTferDelete(EC_T_MBXTFER *pMbxTfer)
-
EC_T_VOID emMbxTferDelete(EC_T_DWORD dwInstanceID, EC_T_MBXTFER *pMbxTfer)
Deletes a mailbox transfer object.
A transfer object may only be deleted if it is in the Idle state.
- Parameters
dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)
pMbxTfer – [in] Mailbox transfer object created with emMbxTferCreate
- Returns
EC_E_NOERROR or error code
6.9.5. emNotify - EC_NOTIFY_MBOXRCV
Indicates a mailbox transfer completion.
- emNotify - EC_NOTIFY_MBOXRCV
- Parameter
pbyInBuf
: [in] Pointer to a structure of type EC_T_MBXTFER, contains the corresponding mailbox transfer object.dwInBufSize
: [in] Size of the transfer object provided at pbyInBuf in bytes.pbyOutBuf
: [out] Should be set to EC_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [out] Should be set to EC_NULL
The element EC_T_MBXTFER::dwClntId
contains the corresponding ID of the client that is notified, the corresponding transfer ID can be found in EC_T_MBXTFER::dwTferId
. The transfer result is stored in EC_T_MBXTFER::dwErrorCode
.
On error EC_T_MBXTFER::eTferStatus
is eMbxTferStatus_TferReqError
, on success eMbxTferStatus_TferDone
. In order to reuse the transfer object the application must set it back to eMbxTferStatus_Idle
.
The EC_T_MBXTFER::eMbxTferType
element determines the mailbox transfer type (e.g. eMbxTferType_COE_SDO_DOWNLOAD
for a completion of a CoE SDO download transfer).