‍⚠️ Important Note

This feature is part of premium SDK. In case you are using standard and need premium, please contact your regional TI sales representative for additional details.

Description

The TI EtherCAT SubDevice stack provides built-in support for Backup Parameters, enabling the storage and restoration of backup parameter data to and from non-volatile memory. Backup parameters are object entries that can be stored in non-volatile memory such as EEPROM or Flash. To store an object entry parameter data in non-volatile memory, it must be indicated by the backup flag. This implementation enables the application to be able to store or restore the object entries at any time. Backup parameters ensure that critical data is retained even in the event of a power failure or system reset and it simplifies data management by allowing for easy storage and restoration of object entries.

This page briefly describes the configuration options, objects supported to handle store/restore of backup entry data, application object modifications and API call sequence during backup parameter store/restore activity with TwinCAT. The motivation of the code snippet/flow diagram is to provide a better understanding of how to handle the backup parameter data. For a detailed overview please refer to the example code.

Configuration and Storage Mode Selection

The macro BACKUP_PARAMETER_SUPPORTED defined in the ecat_def.h controls the backup parameter feature.

Macro	Value	Description
BACKUP_PARAMETER_SUPPORTED	0	Backup parameter feature is disabled. Application APIs are not triggered to store and restore backup parameter.
	1	Backup parameter feature is enabled. Application APIs are triggered to store and restore backup parameter.

Backup parameters defines 2 types of storage modes.

Manual storage mode.
Automatic storage mode.

The macro STORE_BACKUP_PARAMETER_IMMEDIATELY defined in the ecat_def.h selects the backup parameter storage mode.

Macro	Value	Description
STORE_BACKUP_PARAMETER_IMMEDIATELY	0	Manual storage mode is selected. All backup parameters are stored in NVM only when the command 0x65766172 ('e' 'v' 'a' 's' = save) is written to 0x1010.1 and writing 0x64616F6C ('d' 'a' 'o' 'l' = load) to 0x1011.1 restores the value of all the backup parameters from NVM.
	1	Automatic storage mode is enabled. Backup parameter is stored in the NVM when they are written.

Supported Objects

The following objects are defined in the communication area of the object dictionary to handle the backup parameters.

Object Index	Sub-Index	Description
0x1010	-	Store Backup Entries.
	1	Writing 0x65766173 stores the backup entries in non-volatile memory.
0x1011	-	Restore Backup Entries.
	1	Writing 0x64616F6C restores the backup entries from non-volatile memory.
0x10F0	-	Handle Backup Entries.
	1	Checksum of backup entires stored in non-volatile memory.
	2	Flag to indicate the backup entry change since last update in non-volatile memory.

Non-Volatile Memory Configuration

The implementation supports the storing and restoring of the backup object entries to and from the EEPROM as well as the Flash. The macro USE_FLASH_TO_STORE_BACKUP_PARAMETER_DATA controls the whether the backup parameters are stored in EEPROM or Flash.

Macro	Value	Description
USE_FLASH_TO_STORE_BACKUP_PARAMETER_DATA	0	EEPROM is selected as NVM to store backup entries.
	1	Flash is selected as NVM to store backup entries.

The below table describes the macros which defines the offsets used for backup parameter data reading and writing from and to NV memory.

Non-Volatile Memory	Macro	Value
EEPROM	BACKUP_PARAMETER_HEADER_OFFSET	Any valid address. For example, 0x0C00
	BACKUP_PARAMETER_DATA_OFFSET	BACKUP_PARAMETER_HEADER_OFFSET + sizeof(BACKUP_DATA_NV_header_t)
Flash	BACKUP_PARAMETER_HEADER_OFFSET	Any valid address. For example, 0x200000
	BACKUP_PARAMETER_DATA_OFFSET	BACKUP_PARAMETER_HEADER_OFFSET + Page size of flash

The backup object entry data is stored at the offset in the EEPROM or flash specified by the macro BACKUP_PARAMETER_DATA_OFFSET.

The below diagram illustrates a high-level overview of the backup parameter data storage in the flash. The backup parameter header has the checksum and the init key information. The checksum holds the CRC32 of the 'Backup parameter Storage Space' and the Init key is used to identify whether the memory holds the valid data or not after power up.

Backup Parameter Storage in Flash with File Header

The below diagram illustrates a high-level overview of the backup parameter data storage in the EEPROM.

Backup Parameter Storage in EEPROM with File Header

Backup Parameter APIs and Call Sequence

The APIs called for the backup parameter store and restore are,

EC_SLV_APP_CoE_storeBkpParam
EC_SLV_APP_CoE_restoreBkpParam
EC_SLV_APP_CoE_readBkpData
EC_SLV_APP_CoE_writeBkpData

The below flow diagram represents the API call sequence for backup parameter init sequence after power up.

The below flow diagram represents the API call sequence for backup parameter store sequence.

The below flow diagram represents the API call sequence for backup parameter restore sequence.

Application Modifications

When an object is created in the application, the object access flag is set as OBJACCESS_BACKUP and the NVM offset is set for this object using the API EC_API_SLV_CoE_setObjectNonVolatileOffset. When an object entry is being stored and restored in and from the NVM, (object's NVM offset + entry offset) is provided as an NVM address offset to backup parameter write API EC_SLV_APP_CoE_writeBkpData and read API EC_SLV_APP_CoE_readBkpData.

The following code snippet demonstrates how to configure the object entries to be used as backup parameters.

#define BACKUP_PARAMETER_DATA_OFFSET    0x0C00
uint32_t objectSize = 0;
Uint32_t nvmOffset = BACKUP_PARAMETER_DATA_OFFSET;
 
// Create a variable type object and configure it as a backup parameter entry.
error = (EC_API_EError_t)EC_API_SLV_CoE_odAddVariable(
                                                        ptSubDevice,
                                                        0x2004,
                                                        "Backup Variable",
                                                        DEFTYPE_UNSIGNED32,
                                                        32,
                                                        (ACCESS_READWRITE | OBJACCESS_BACKUP),
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        NULL);
// set the Non-volatile memory offset
EC_API_SLV_CoE_setObjectNonVolatileOffset(ptSubDevice,0x2004,nvmOffset);
 
// Create a Array type object and configure it as a backup parameter entry.
error = (EC_API_EError_t)EC_API_SLV_CoE_odAddArray(
                                                    ptSubDevice,
                                                    0x2003,
                                                    "Backup Array",
                                                    2,
                                                    DEFTYPE_UNSIGNED16,
                                                    16,
                                                    (ACCESS_READWRITE | OBJACCESS_BACKUP),
                                                    NULL,
                                                    NULL,
                                                    NULL,
                                                    NULL);
 
// set the Non-volatile memory offset
error = EC_API_SLV_CoE_getObjectLengthByIndex(ptSubDevice,0x2004,&objectSize);
nvmOffset = nvmOffset + objectSize;
EC_API_SLV_CoE_setObjectNonVolatileOffset(ptSubDevice,0x2003,nvmOffset);
 
// Create a Record type object.
error = (EC_API_EError_t)EC_API_SLV_CoE_odAddRecord(
                                                    ptSubDevice,
                                                    0x2000,
                                                    "Out Object Record",
                                                    NULL,
                                                    NULL,
                                                    NULL,
                                                    NULL,
                                                    &pApplicationInstance->ptRecObjOut);
 
// set the Non-volatile memory offset
error = EC_API_SLV_CoE_getObjectLengthByIndex(ptSubDevice,0x2003,&objectSize);
nvmOffset = nvmOffset + objectSize;
EC_API_SLV_CoE_setObjectNonVolatileOffset(ptSubDevice,0x2000,nvmOffset);
 
error = (EC_API_EError_t)EC_API_SLV_CoE_configRecordSubIndex(
                                                                ptSubDevice,
                                                                pApplicationInstance->ptRecObjOut,
                                                                1,
                                                                "SubIndex 1",
                                                                DEFTYPE_UNSIGNED16,
                                                                16,
                                                                ACCESS_READWRITE);
 
error = (EC_API_EError_t)EC_API_SLV_CoE_configRecordSubIndex(
                                                                ptSubDevice,
                                                                pApplicationInstance->ptRecObjOut,
                                                                2,
                                                                "SubIndex 2",
                                                                DEFTYPE_UNSIGNED32,
                                                                32,
                                                                ACCESS_READWRITE);
 
// Configure SI3 as a backup parameter entry.
error = (EC_API_EError_t)EC_API_SLV_CoE_configRecordSubIndex(
                                                                ptSubDevice,
                                                                pApplicationInstance->ptRecObjOut,
                                                                3,
                                                                "SubIndex 3",
                                                                DEFTYPE_UNSIGNED8,
                                                                8,
                                                                ACCESS_READWRITE | OBJACCESS_BACKUP);

The following table outlines the NVM offset for the backup entries as defined in the code snippet:

Index	SubIndex	size (bytes)	Backup Entry?	NVM Offset
0x2004	0	4	Yes	0x0C00
0x2003	0	1	No	0x0C04
	1	2	Yes	0x0C06
	2	2	Yes	0x0C08
0x2000	0	1	No	0x0C0A
	1	2	No	0x0C0C
	2	4	No	0x0C0E
	3	1	Yes	0x0C12

Note: The actual values for these offsets are defined in the code snippet and may vary depending on the specific implementation.

Simple Demo Example with Backup Parameters

The Simple demo example implements the following objects as the backup parameters:

Object 0x2003: configured as an Array object comprising 5 subindexes, each with a size of 16 bits.
Object 0x2004: configured as a Variable object of size 32bits.

These objects are specifically set up to demonstrate how to configure objects as backup parameters, showcasing the flexibility and versatility of the backup parameter feature.

Backup Parameters in TwinCAT

The below screenshot shows the CoE_Online tab in TwinCAT.

Simple Demo CoE Online Tab