Description

File access over EtherCAT (FoE) is a straightforward protocol that shares similarities with TFTP (Trivial File Transfer Protocol) but does not require a full TCP/IP stack.

The FoE implementation supports storing and retriving of a generic file onto/from the flash as well as the firmware update over FoE. The generic file is stored at the offset in the flash specified by the macro APP_OSPI_FLASH_OFFSET_BASE and the firmware file will be flashed at the offset in the flash defined by the macro APP_OSPI_FLASH_OFFSET_APPIMAGE, at which by default the SBL bootloader will look for the firmware.

This page briefly describes the file download/upload procedure in TwinCAT, API call sequence during file download/upload and testing FoE with TwinCAT. 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.

FoE File Download/Upload

The APIs called for the FoE file download and upload are

EC_SLV_APP_FoE_fileOpen()
EC_SLV_APP_FoE_fileWrite()
EC_SLV_APP_FoE_fileRead()
EC_SLV_APP_FoE_fileclose()

The API EC_SLV_APP_FoE_fileWrite is called during the file download/write which calls the API NVM_APP_write to write the file data into the flash. The API EC_SLV_APP_FoE_fileOpen is called prior to the API EC_SLV_APP_FoE_fileWrite, where the file name, file name length and 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 data payload size (1012 bytes), the API EC_SLV_APP_FoE_fileWrite is called once with the complete file data. If the file data size is larger, the API EC_SLV_APP_FoE_fileWrite is called multiple times with the file data segments of maximum size of 1012 bytes.

The last file data segment will trigger the API EC_SLV_APP_FoE_fileClose which will complete the file write pending operations by writing remaining file data and the file header into the flash.

The below diagram shows the overview of the downloaded file storage in the flash. The file header information is necessary for retriving the complete file during the file upload. The file header has the file name, file name length, file password and the file size information. The maximum file name length is defined by the macro FOE_FILE_NAME_MAX_LEN.

FoE File Storage in Flash with File Header

uint32_t EC_SLV_APP_FoE_fileWrite(void *pContext, uint16_t* pData, uint16_t size)
{
    uint32_t    retVal;
 
    retVal = ECAT_FOE_ERRCODE_DISKFULL;
 
    ...
 
    // Store the file data temporarily in a buffer
 
    ...
 
    // Call NVM API to write file data to flash
    error = NVM_APP_write(  NVM_TYPE_FLASH,
                            CONFIG_FLASH0,
                            APP_OSPI_FLASH_OFFSET_BASE,
                            (uint32_t)(OSPI_FLASH_PAGE_SIZE),
                            (uint8_t*)buffer,
                            false);
    
    if (error != NVM_ERR_SUCCESS)
    {
        retVal = ECAT_FOE_ERRCODE_ACCESS;
        return retVal;
    }
 
    retVal = size;
 
    return retVal;
}

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;
    fileAccessPassword = password;
 
    // Store the file details received in the file header.
 
    // Check if the file is a firmware file and select the corresponding flash offset.
 
    // Check if it is a file read operation then get the stored file header from the flash and verify the details. 
    error = NVM_APP_read( NVM_TYPE_FLASH,
                          CONFIG_FLASH0,
                          APP_OSPI_FLASH_OFFSET_BASE,
                          (uint32_t)sizeof(ESL_FOE_header_t),
                          (uint8_t*)&foeFileHeader);
 
    if (error != NVM_ERR_SUCCESS)
    {
        retVal = ECAT_FOE_ERRCODE_FLASH_ERROR;
        return retVal;
    }
 
    // File access password validation
    if (foeFileHeader.password != foeFileAccessPassword)
    {
        OSAL_printf("FoE - File access password incorrect!\n\r");
        retVal = ECAT_FOE_ERRCODE_ACCESS;
        return retVal;
    }
 
    if (foeFileHeader.dataSize == 0)
    {
        OSAL_printf("FoE - File not found or empty!\n\r");
        retVal = ECAT_FOE_ERRCODE_NOTFOUND;
        return retVal;
    }
 
    return retVal;
}

uint32_t EC_SLV_APP_FoE_fileClose(void* pContext, uint32_t errorCode)
{
    uint32_t    retVal  = 0;
    NVM_err_t error;
    
    // Write the remaining file data to flash
 
    // write the file header info to the flash for generic file download.
    error = NVM_APP_write(  NVM_TYPE_FLASH,
                            CONFIG_FLASH0,
                            APP_OSPI_FLASH_OFFSET_BASE,
                            (uint32_t)(sizeof(ESL_FOE_header_t)),
                            (uint8_t*)&foeFileHeader,
                            flashForceErase);
    if (error != NVM_ERR_SUCCESS)
    {
        retVal = ECAT_FOE_ERRCODE_ACCESS;
        return retVal;
    }
 
    retVal = EC_API_eERR_NONE;
    return retVal;
}

The API EC_SLV_APP_FoE_fileRead is called during the file upload which calls the API NVM_APP_read to read the file data from the flash. The API EC_SLV_APP_FoE_fileOpen is called prior to the API EC_SLV_APP_FoE_fileread, where the check for the password authentication to access the file and valid file length is performed. If the stored file data size is less than the FoE mailbox frame size (1012 bytes), the API EC_SLV_APP_FoE_fileRead is called once to retrieve the complete file data. If the stored file data size is larger, 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;
 
    retVal = ECAT_FOE_ERRCODE_ILLEGAL;
    ...
 
    // Send the file data
 
    error = NVM_APP_read(NVM_TYPE_FLASH,
                         CONFIG_FLASH0,
                         APP_OSPI_FLASH_OFFSET_FILE_DATA + fileOffset,
                         (uint32_t)foeFileChunkReadSize,
                         (uint8_t*)pData);
 
    ...  
 
    retVal = foeFileChunkReadSize;
 
    return retVal;
}

The below diagram describes the overview of the API call sequence in case of file download/upload from TwinCAT.

FoE API Call Sequence for File Download/Upload

Firmware update over FoE

The Simple demo example implementation supports the firmware update over FoE. The firmware update is supported only in the Bootstrap state. The firmware file *.appimage.hs_fs must be renamed as ECATFW__* and this file naming convention shall be used to identify the firmware file. The firmware file flashed at the offset defined by the macro APP_OSPI_FLASH_OFFSET_APPIMAGE is not available for the file upload. That means the firmware file cannot be read back using file upload procedure.

Note: If the firmware file with the naming convention ECATFW__* is downloaded in any other states (Preop or Op) different from Bootstrap state then the firmware file will be saved as a generic file at the offset specified by the macro APP_OSPI_FLASH_OFFSET_BASE in the flash and the file will be available for the file upload.

The APIs which trigger at the state transition from Init to Bootstrap and vice-versa will support the firmware update over FoE.

The API EC_SLV_APP_FoE_startBL which is called during the state transition from Init to Bootstrap can be used to prepare for the firware update activity.

void EC_SLV_APP_FoE_startBL(void* pContext)
{
    // prepare for the firmaware update
    return;
}

The API EC_SLV_APP_FoE_startBL which is called during the state transition from Init to Bootstrap can be used to check the firmware file download status and reboot activity.

void EC_SLV_APP_FoE_stopBL(void* pContext)
{
    // Check the firmware download status 
 
    // perform reboot if everything is ok
    return;
}

The below diagram describes the overview of the API call sequence in case of firmware download from TwinCAT.

FoE API Call Sequence for Firmware Update

FoE testing in TwinCAT

File Download

The same procedure applies for firmware update as well but the only difference will be the naming convention of the firmware file and the state in which the firmware file download is being performed. A sample text file FoE_Test_File.txt having 510 bytes shall be used to download into the flash memory of the EtherCAT SubDevice from TwinCAT. This file access shall be password protected and the password shall be 32bit length, 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.

Scan for the EtherCAT device in TwinCAT and click on the Box 1 (TI EtherCAT Toolkit for AMXXX.R5F).
Click on the Online tab.
Click on the Pre-Op button under the State Machine block.
Wait until the current state changes to PREOP.
Click on the Download... button under File Access over EtherCAT block.
Wait for the popup window to appear titled as Open.
Select the file extension as All Files(*.*) in the drop down.
Select the file to be downloaded to the EtherCAT SubDevice.
Click on the Open button.
Wait for the popup window to appear titled as Edit FoE Name.
Provide a password for the file in hex.
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 SubDevice.

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

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

FoE File Upload TwinCAT 1

FoE File Upload TwinCAT 2