8.9. File access over EtherCAT (FoE)

The EC-Monitor can record file transfers via the FoE protocol between an EtherCAT master and a slave. These FoE transfers can be forwarded to the application as segmented packets in real time via the notifications emNotify - eMbxTferType_FOE_SEG_DOWNLOAD and emNotify - eMbxTferType_FOE_SEG_UPLOAD.

In addition, the FoE transfers can be stored as a file on the file system. The files are automatically created and stored in EC_T_MONITOR_INIT_PARMS::szFileStoragePath. The file name consists of the following:
<TimeStamp[msec]>_Slave<StationAddress>_<FoeFileName>
For example:
0123456789_Slave1001_firmware.bin

The notifications for FoE can be deactivated using the EC_T_MBX_PARMS::_EC_T_MBX_PARMS_FOE::bDisableNotifications parameter if they are not required or to save computing time. If no file system is available or file storage is not desired, it can be disabled using the EC_T_MBX_PARMS::_EC_T_MBX_PARMS_FOE::bDisableFileStorage parameter.

If both parameters EC_T_MBX_PARMS::_EC_T_MBX_PARMS_FOE::bDisableNotifications and EC_T_MBX_PARMS::_EC_T_MBX_PARMS_FOE::bDisableFileStorage are set, the FoE monitoring is completely deactivated.

8.9.1. Notification sequence

Once the EC-Monitor detects an FoE transfer, the application is notified via an emNotify - eMbxTferType_FOE_DOWNLOAD_REQ or emNotify - eMbxTferType_FOE_UPLOAD_REQ notification. This notification contains basic information about the upcoming transfer, e.g. requested file name.

After that, each individual packet is transmitted via an emNotify - eMbxTferType_FOE_SEG_DOWNLOAD or emNotify - eMbxTferType_FOE_SEG_UPLOAD notification. The end of the transfer is set via the EC_T_MBXTFER::eTferStatus = eMbxTferStatus_TferDone.

Download

skinparam monochrome true skinparam SequenceMessageAlign direction skinparam SequenceBoxBorderColor transparent skinparam ParticipantPadding 50 hide footbox participant Master participant Monitor participant Slave participant App Master->Slave: WRQ(file name) activate Monitor Monitor->App: eMbxTferType_FOE_DOWNLOAD_REQ\neMbxTferStatus_Pend deactivate Monitor Master->Slave: DATA(first packet) activate Monitor Monitor->App: eMbxTferType_FOE_SEG_DOWNLOAD\neMbxTferStatus_Pend deactivate Monitor ... Master->Slave: DATA(last packet) activate Monitor Monitor->App: eMbxTferType_FOE_SEG_DOWNLOAD\neMbxTferStatus_Done deactivate Monitor

Upload

skinparam monochrome true skinparam SequenceBoxBorderColor transparent skinparam ParticipantPadding 50 hide footbox participant Master participant Monitor participant Slave participant App Master->Slave: RRQ(file name) activate Monitor Monitor->App: eMbxTferType_FOE_UPLOAD_REQ\neMbxTferStatus_Pend deactivate Monitor Slave->Master: DATA(first packet) activate Monitor Monitor->App: eMbxTferType_FOE_SEG_UPLOAD\neMbxTferStatus_Pend deactivate Monitor ... Slave->Master: DATA(last packet) activate Monitor Monitor->App: eMbxTferType_FOE_SEG_UPLOAD\neMbxTferStatus_Done deactivate Monitor

8.9.2. emNotify - eMbxTferType_FOE_DOWNLOAD_REQ

Notifies a FoE download request from the EtherCAT master to a slave.

emNotify - eMbxTferType_FOE_DOWNLOAD_REQ
Parameter

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

  • dwInBufSize: [in] Size of the transfer object 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 parameters that the master has requested from the slave are stored in the structure EC_T_MBX_DATA::FoE_Request which is part of EC_T_MBXTFER::MbxData.

struct EC_T_MBX_DATA_FOE_REQ

Public Members

EC_T_WORD wStationAddress

[out] Station address of the slave

EC_T_DWORD dwPassword

[out] FoE read/write request password

EC_T_CHAR szFileName[EC_MAX_FILE_NAME_SIZE]

[out] Name of the file to be read/write

8.9.3. emNotify - eMbxTferType_FOE_SEG_DOWNLOAD

Transmits a data segment of the ongoing FoE download.

emNotify - eMbxTferType_FOE_SEG_DOWNLOAD
Parameter

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

  • dwInBufSize: [in] Size of the transfer object 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 FoE download data segment is stored at EC_T_MBXTFER::pbyMbxTferData with size EC_T_MBXTFER::dwDataLen and may have to be buffered by the application. Access to the memory area EC_T_MBXTFER::pbyMbxTferData outside of the notification caller context is illegal and the results are undefined.

Information about the current transfer are in structure EC_T_MBX_DATA::FoE which is part of EC_T_MBXTFER::MbxData. Among other things, it contains the slave station address EC_T_MBX_DATA_FOE::wStationAddress and the number of bytes already transmitted EC_T_MBX_DATA_FOE::dwTransferredBytes.

struct EC_T_MBX_DATA_FOE

Public Members

EC_T_DWORD dwTransferredBytes

[out] amount of transferred bytes

EC_T_DWORD dwRequestedBytes

[out] amount of bytes to be provided by application

EC_T_DWORD dwBusyDone

[out] If slave is busy: 0 … dwBusyEntire

EC_T_DWORD dwBusyEntire

[out] If dwBusyEntire > 0: Slave is busy

EC_T_CHAR szBusyComment[EC_FOE_BUSY_COMMENT_SIZE]

[out] Busy Comment from slave

EC_T_DWORD dwFileSize

[out] File size

EC_T_WORD wStationAddress

[out] Station address of the slave

Note

The elements EC_T_MBX_DATA_FOE::dwRequestedBytes and EC_T_MBX_DATA_FOE::dwFileSize are not used by the EC-Monitor because they are not known at runtime.

8.9.4. emNotify - eMbxTferType_FOE_UPLOAD_REQ

Notifies a FoE upload request from the EtherCAT master to a slave.

emNotify - eMbxTferType_FOE_DOWNLOAD_REQ
Parameter

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

  • dwInBufSize: [in] Size of the transfer object 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 parameters that the master has requested from the slave are stored in the structure EC_T_MBX_DATA::FoE_Request which is part of EC_T_MBXTFER::MbxData.

struct EC_T_MBX_DATA_FOE_REQ
EC_T_WORD wStationAddress
EC_T_DWORD dwPassword
EC_T_CHAR szFileName[EC_MAX_FILE_NAME_SIZE]

8.9.5. emNotify - eMbxTferType_FOE_SEG_UPLOAD

Transmits a data segment of the ongoing FoE upload.

emNotify - eMbxTferType_FOE_SEG_UPLOAD
Parameter

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

  • dwInBufSize: [in] Size of the transfer object 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 FoE upload data segment is stored at EC_T_MBXTFER::pbyMbxTferData with size EC_T_MBXTFER::dwDataLen and may have to be buffered by the application. Access to the memory area EC_T_MBXTFER::pbyMbxTferData outside of the notification caller context is illegal and the results are undefined.

Information about the current transfer are in structure EC_T_MBX_DATA::FoE which is part of EC_T_MBXTFER::MbxData. Among other things, it contains the slave station address EC_T_MBX_DATA_FOE::wStationAddress and the number of bytes already transmitted EC_T_MBX_DATA_FOE::dwTransferredBytes.

struct EC_T_MBX_DATA_FOE
EC_T_DWORD dwTransferredBytes
EC_T_DWORD dwRequestedBytes
EC_T_DWORD dwBusyDone
EC_T_DWORD dwBusyEntire
EC_T_CHAR szBusyComment[EC_FOE_BUSY_COMMENT_SIZE]
EC_T_DWORD dwFileSize
EC_T_WORD wStationAddress

Note

The elements EC_T_MBX_DATA_FOE::dwRequestedBytes and EC_T_MBX_DATA_FOE::dwFileSize are not used by the EC-Monitor because they are not known at runtime.

8.9.6. emNotify - EC_NOTIFY_FOE_MBSLAVE_ERROR

This error will be indicated in case a FoE mailbox slave send an error message. Detailed error information is stored in structure EC_T_MBOX_FOE_ABORT_DESC which is part of EC_T_ERROR_NOTIFICATION_DESC.

struct EC_T_MBOX_FOE_ABORT_DESC

Public Members

EC_T_SLAVE_PROP SlaveProp

Slave properties

EC_T_DWORD dwErrorCode

Error code

EC_T_CHAR achErrorString[MAX_STD_STRLEN]

FoE error string

8.9.7. emConvertEcErrorToFoeError

EC_T_DWORD emConvertEcErrorToFoeError(EC_T_DWORD dwInstanceID, EC_T_DWORD dwErrorCode)

Convert master error code to FoE error code.

Returns

FoE error code according to ETG1000.6 Table 92 - Error codes of FoE