8.7. 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:

  1. Record a mailbox transfer.

  2. 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
  3. Set the location to write the transferred data to, determine the transfer ID, store the client ID in the object and initiate the transfer (e.g. a SDO upload). A transfer may only be initiated if the state of the transfer object is Idle.
    pMbxTfer->dwDataLen = MbxTferDesc.dwMaxDataLen;

pMbxTfer->pbyMbxTferData = MbxTferDesc.pbyMbxTferDescData

pMbxTfer->dwTferId = 1;

pMbxTfer->dwClntId = dwClntId;


dwResult = emCoeSdoUplodadReq(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.

  4. 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 calling emNotify().
    if( dwResult != EC_E_NOERROR ) { ... }

emNotify( EC_NOTIFY_MBOXRCV, pParms )
    state of the transfer object = TferDone
  5. 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
  6. Delete the transfer object. Alternatively this object can be used for the next transfer.
    emMbxTferDelete(pMbxTfer);

8.7.1. Mailbox transfer object states

The following states exist for a mailbox transfer object:

enum EC_T_MBXTFER_STATUS

Values:

enumerator eMbxTferStatus_Idle

Mailbox transfer object not in use

enumerator eMbxTferStatus_Pend

Mailbox transfer in process

enumerator eMbxTferStatus_TferDone

Mailbox transfer completed

enumerator eMbxTferStatus_TferReqError

Mailbox transfer request error

enumerator eMbxTferStatus_TferWaitingForContinue

Mailbox transfer waiting for continue, object owned by application

A mailbox transfer will be processed by the monitor 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.

8.7.2. emMbxTferCreate

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_DESC

Public Members

EC_T_DWORD dwMaxDataLen

Maximum amount of data bytes that shall be transferred using this object. A mailbox transfer type without data transfer will ignore this parameter

EC_T_BYTE *pbyMbxTferDescData

Pointer to byte stream carrying in and out data of mailbox content

struct EC_T_MBXTFER

Public Members

EC_T_DWORD dwClntId

[] Client ID

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 dwErrorCode

[out] Error code of a mailbox transfer that was terminated with error

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.

enum EC_T_MBXTFER_TYPE

Values:

enumerator eMbxTferType_COE_SDO_DOWNLOAD

CoE SDO download

enumerator eMbxTferType_COE_SDO_UPLOAD

CoE SDO upload

enumerator eMbxTferType_COE_GETODLIST

CoE Get object dictionary list

enumerator eMbxTferType_COE_GETOBDESC

CoE Get object description

enumerator eMbxTferType_COE_GETENTRYDESC

CoE Get object entry description

enumerator eMbxTferType_COE_EMERGENCY

CoE emergency request

enumerator eMbxTferType_COE_RX_PDO

CoE RxPDO

enumerator eMbxTferType_FOE_FILE_UPLOAD

FoE upload

enumerator eMbxTferType_FOE_FILE_DOWNLOAD

FoE download

enumerator eMbxTferType_SOE_READREQUEST

SoE read request

enumerator eMbxTferType_SOE_READRESPONSE

SoE read response

enumerator eMbxTferType_SOE_WRITEREQUEST

SoE write request

enumerator eMbxTferType_SOE_WRITERESPONSE

SoE write response

enumerator eMbxTferType_SOE_NOTIFICATION

SoE notification

enumerator eMbxTferType_SOE_EMERGENCY

SoE emergency

enumerator eMbxTferType_VOE_MBX_READ

VoE read

enumerator eMbxTferType_VOE_MBX_WRITE

VoE write

enumerator eMbxTferType_AOE_READ

AoE read

enumerator eMbxTferType_AOE_WRITE

AoE write

enumerator eMbxTferType_AOE_READWRITE

AoE read/write

enumerator eMbxTferType_AOE_WRITECONTROL

AoE write control

enumerator eMbxTferType_RAWMBX

Raw mbx

enumerator eMbxTferType_FOE_SEG_DOWNLOAD

FoE segmented download

enumerator eMbxTferType_FOE_SEG_UPLOAD

FoE segmented upload

enumerator eMbxTferType_S2SMBX

S2S mbx

enumerator eMbxTferType_FOE_UPLOAD_REQ

FoE upload request

enumerator eMbxTferType_FOE_DOWNLOAD_REQ

FoE download request

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_MBX_DATA_FOE_REQ FoE_Request

FoE request

EC_T_MBX_DATA_SOE SoE

SoE

EC_T_SOE_NOTIFICATION SoE_Notification

SoE notification request

EC_T_SOE_EMERGENCY SoE_Emergency

SoE emergency request

8.7.3. emMbxTferAbort

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.

8.7.4. emMbxTferDelete

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

8.7.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_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [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).