EtherCAT Slave
 
Loading...
Searching...
No Matches
File access over EtherCAT

Description

File access over EtherCAT (FoE) is a straightforward protocol that shares similarities with TFTP (Trivial File Transfer Protocol) but it does not require a full TCP/IP stack.
This page briefly describes the APIs related to FoE and testing FoE with TwinCAT.

FoE API Details

The motivation of the code snippets is to provide a better understanding of how to handle the FoE file data. For a detailed overview please refer to the example code.

The API EC_SLV_APP_FoE_fileWrite shall be called during the file download/write which shall then call the API NVM_APP_writeAsync to write the file data into the flash. When the file data write is complete it shall trigger the call to the registered callback function. The API EC_SLV_APP_FoE_fileOpen is called prior to the API EC_SLV_APP_FoE_fileWrite, where the file access password is received and stored in a file header along with the file data.

If the file data size is less than the FoE mailbox frame size, 1012 bytes then the API EC_SLV_APP_FoE_fileWrite is called once with the complete file data . If the file data size is larger, then the API EC_SLV_APP_FoE_fileWrite is called multiple times with the file data segments of maximum size of 1012 bytes.

uint32_t EC_SLV_APP_FoE_fileWrite(void *pContext, uint16_t* pData, uint16_t size)
{
uint32_t retVal;
retVal = ECAT_FOE_ERRCODE_DISKFULL;
...
// Handle memory allocations
// Concatenate the file data size and file access password as a file header
...
// Trigger async write to flash
error = NVM_APP_writeAsync( NVM_TYPE_FLASH,
CONFIG_FLASH0,
APP_OSPI_FLASH_OFFSET_BASE,
(uint32_t)(sizeof(ESL_FOE_header_t) + foeFileWriteChunkSize),
(uint8_t*)foeBufferPtr);
if (error != NVM_ERR_SUCCESS)
{
retVal = ECAT_FOE_ERRCODE_ACCESS;
return retVal;
}
retVal = size;
return retVal;
}

The callback function is registered in the API EC_SLV_APP_FoE_fileOpen.

uint32_t EC_SLV_APP_FoE_fileOpen(void* pContext, const char* pName, uint16_t nameLen, bool isRead, uint32_t password)
{
uint32_t retVal;
retVal = EC_API_eERR_NONE;
#if !(defined FBTLPROVIDER) || (FBTLPROVIDER==0)
NVM_err_t error;
error = NVM_APP_registerCallback(EC_SLV_APP_FoE_fileWriteCb);
if (error != NVM_ERR_SUCCESS)
{
retVal = ECAT_FOE_ERRCODE_NOTDEFINED;
return retVal;
}
#endif
fileAccessPassword = password;
return retVal;
}
@ EC_API_eERR_NONE
Definition ecSlvApiDef_error.h:45

This callback shall handle the async NVM write status and freeing up the allocated memory during the file data write to flash.

void EC_SLV_APP_FoE_fileWriteCb(uint32_t status)
{
if (status == NVM_ERR_SUCCESS)
{
// Handle the error
}
...
// Free the allocated buffers
if(foeBufferPtr != NULL)
{
OSAL_MEMORY_free(foeBufferPtr);
foeBufferPtr = NULL;
}
...
}

The API EC_SLV_APP_FoE_fileRead shall be called during the file upload/read which shall then call the API NVM_APP_read to read the file data from the flash. It also checks for the password authentication for the file access.

If the stored file data size is less than the FoE mailbox frame size, 1012 bytes then the API EC_SLV_APP_FoE_fileRead is called once to retrieve the complete file data. If the stored file data size is larger, then the API EC_SLV_APP_FoE_fileRead is called multiple times to retrieve the file data in segments of maximum size of 1012 bytes.

uint32_t EC_SLV_APP_FoE_fileRead(void* pContext, uint16_t* pData, uint16_t size, uint32_t fileOffset)
{
uint32_t retVal;
static uint32_t foeFileReadDoneSize = 0;
uint32_t foeFileChunkReadSize = 0;
ESL_FOE_header_t foeHeader = {0};
retVal = ECAT_FOE_ERRCODE_ILLEGAL;
// Read the file data size and password info
NVM_err_t error;
error = NVM_APP_read(NVM_TYPE_FLASH,
CONFIG_FLASH0,
APP_OSPI_FLASH_OFFSET_BASE,
(uint32_t)sizeof(ESL_FOE_header_t),
(uint8_t*)&foeHeader);
if (error != NVM_ERR_SUCCESS)
{
retVal = ECAT_FOE_ERRCODE_FLASH_ERROR;
return retVal;
}
// File access password validation
if (foeHeader.password != fileAccessPassword)
{
#if (defined DEBUGTRACING) && (DEBUGTRACING == 1)
OSAL_printf("FoE - File access password incorrect!\n\r");
#endif
retVal = ECAT_FOE_ERRCODE_ACCESS;
return retVal;
}
...
// Send the file data
error = NVM_APP_read(NVM_TYPE_FLASH,
CONFIG_FLASH0,
APP_OSPI_FLASH_OFFSET_BASE + sizeof(ESL_FOE_header_t) + fileOffset,
(uint32_t)foeFileChunkReadSize,
(uint8_t*)pData);
...
retVal = foeFileChunkReadSize;
return retVal;
}

FoE testing in TwinCAT

File Download

A sample text file FoE_Test_File.txt having 510 bytes shall be used to download into the flash memory of the EtherCAT slave device from TwinCAT. This file access shall be password protected and the password shall be 0x1234ABFE for example. In case, the file access is required without the password protection then leave the password to its default state 0x00000000.

Follow the below steps to download a sample file to EtherCAT device from TwinCAT.

  1. Scan for the EtherCAT device in TwinCAT and click on the Box 1 (TI EtherCAT Toolkit for AMXXX.R5F).
  2. Click on the Online tab.
  3. Click on the Pre-Op button under the State Machine block.
  4. Wait until the current state changes to PREOP.
  5. Click on the Download... button under File Access over EtherCAT block.
  6. Wait for the popup window to appear titled as Open.
  7. Select the file extension as All Files(*.*) in the drop down.
  8. Select the file to be downloaded to the EtherCAT slave device.
  9. Click on the Open button.
  10. Wait for the popup window to appear titled as Edit FoE Name.
  11. Provide a password for the file in hex.
  12. Click on the OK button.
FoE File Download TwinCAT 1
FoE File Download TwinCAT 2

File Upload

A text file FoE_Test_File.txt which has been downloaded successfully in the previous step, can be uploaded back to TwinCAT from the EtherCAT device.

Follow the below steps to upload a sample file from EtherCAT device into TwinCAT.

  1. Scan for the EtherCAT device in TwinCAT and click on the Box 1 (TI EtherCAT Toolkit for AMXXX.R5F).
  2. Click on the Online tab.
  3. Click on the Pre-Op button under the State Machine block.
  4. Wait until the current state changes to PREOP.
  5. Click on the Upload... button under File Access over EtherCAT block.
  6. Wait for the popup window to appear titled as Save As.
  7. Select the file extension as All Files(*.*) in the drop down for 'Save as type'.
  8. Enter the name of the file with extension to save the file from the EtherCAT slave device.
  9. Click on the Save button.
  10. Wait for the popup window to appear titled as Edit FoE Name.
  11. Provide a password for the file access in hex (must be same password used during the download).
  12. Click on the OK button.
FoE File Upload TwinCAT 1
FoE File Upload TwinCAT 2