An Introduction to Beckhoff Persistent-Based Data Storage

Posted by on

 


Contents

  1. Introduction

  2. Data Persistence in TC3 Systems
     2.1. Determining the ADS Port Number of the PLC Project
     2.2. Data Recovery
     2.3. Constant Configuration
     2.4. Task Creation
     2.5. “Clear Invalid Persistent Data” Must NOT Be Checked
     2.6. Definition of CrcValue
     2.7. Notes on Using Persistent Variables
     2.8. How Much Data Can a 1-MB Persistent File Store
     2.9. FB_Persistent – Function Block Interface Description
     2.10. Runtime Behavior
     2.11. Example Program

  3. Data Persistence in TC2 Systems
     3.1. Determining the ADS Port Number of the PLC Project
     3.2. Data Recovery
     3.3. Constant Configuration
     3.4. Task Creation
     3.5. “Clear Invalid Persistent Data” Must NOT Be Checked
     3.6. Definition of CrcValue
     3.7. Notes on Using Persistent Variables
     3.8. How Much Data Can a 1-MB Persistent File Store
     3.9. FB_Persistent – Function Block Interface Description
     3.10. Runtime Behavior
     3.11. Example Program

1. Introduction

The Persistent data type is widely used in industrial automation applications for recording and storing real-time process data. This document provides an in-depth analysis and comparison across four operating environments:

  • TwinCAT 3 CE systems

  • TwinCAT 3 non-CE systems (Windows 10 / Windows 7, etc.)

  • TwinCAT 2 CE systems

  • TwinCAT 2 non-CE systems

Note: All explanations assume that the UPS has sufficient capacity and is operating normally.

2. Data Persistence in TC3 Systems

This section explains how to properly manage persistent data in a TC3 runtime environment using the FB_Persistent function block.

When TwinCAT 3 starts, the system loads the Port_851.bootdata file to restore persistent variables.
If this file is corrupted, the system automatically loads Port_851.bootdata-old as the fallback.
Since this backup file is generated at the previous system startup, it may not contain the most recent data.

During normal operation, FB_Persistent periodically generates a new Port_851.bootdata file, deletes the old .bootdata-old file, and renames the new file as .bootdata-old.
This mechanism ensures that a recent backup is always available.

In addition, FB_Persistent supports multi-version backups, storing up to 7 historical files, providing robust data redundancy even if both .bootdata and .bootdata-old become corrupted.

2.1. Determining the ADS Port Number of a PLC Project

In TwinCAT, the ADS port number can be viewed or modified by right-clicking the PLC object.
A newly created PLC project defaults to port 851.

If multiple PLC instances exist in the same solution, each instance must have its own FB_Persistent block.
The function block automatically detects the correct ADS port for its PLC instance.

2.2. Data Recovery

All supported systems (TC2/TC3, CE/Win7/10) can perform automatic data recovery through the restore function of FB_Persistent.
Different systems require different RestoreTool utilities.

  • CE Systems (TC2 / TC3 compatible)

  • Windows 7/10 Systems (TC2 / TC3 compatible)

The appropriate RestoreTool must be copied to the controller’s *C:* root directory or the Hard Disk root directory.

2.3. Constant Configuration

The following constants must be configured:

  • MAX_SCAN_FILES_NUM

    • Default: 20

    • Function: Maximum number of files the system will scan

  • MAX_BAK_FILES_NUM

    • Default: 7

    • Range: 1–9 (must be <10)

    • Function: Maximum number of backup persistent files

2.4. Task Creation

A 20-ms task must be created.
FB_Persistent must be called cyclically inside this 20-ms task.

2.5. “Clear Invalid Persistent Data” Must NOT Be Checked

Critical Warning:
This option must remain unchecked.
If enabled, TwinCAT will ignore the .bootdata-old file, causing loss of persistent data.

2.6. Definition of CrcValue

A persistent variable named CrcValue must be defined in a GVL and initialized to 0.
This variable is required for data integrity checking.

2.7. Notes on Using Persistent Variables

  • Clicking the “Reset” icon will reset all variables, including persistent ones.

  • Never rename a GVL file or program that contains persistent variables.

    • TC3 stores the variable name with its file/program prefix.

    • Renaming will break the mapping inside .bootdata, making recovery extremely difficult.

Recommended Practices

  • Prefer arrays to improve data-to-metadata efficiency.

  • Concentrate persistent variables in global GVLs.

  • Avoid randomly adding persistent variables without planning.

  • Use XML files for recipe data—safer, easier to restore, independent from persistent memory.

2.8. How Much Data Can a 1-MB Persistent File Store

Persistent variables are stored as files, which include values and variable names.
Thus, the actual capacity depends heavily on name length and data type.

In TC3, memory usage increments in 4-byte alignment due to internal optimization.

Conclusions

  • Arrays provide the highest storage efficiency.

  • To check whether the 1-MB limit is exceeded, examine the size of:

     C:\TwinCAT\3.1\Boot\Plc\Port_851.bootdata-old
     or
     Hard Disk\TwinCAT\3.1\Boot\Plc\Port_851.bootdata-old

2.9. FB_Persistent – Function Block Interface Description


NameDirTypeDescription
TrigFirstCycleIn_OutBOOLUsed when no persistent file exists in a new project. Must only be triggered once. Administrator-level signal recommended.
PowerOkInputBOOLUPS power-good signal. Mandatory.
BootDataLoadedInputBOOLReserved
OldBootDataInputBOOLReserved
EnableRestoreBakDataInputBOOLEnables data recovery mode. Automatically disables auto-save. Should require admin privileges.
TrigRestoreBakDataInputBOOLTrigger for recovery. Press for 10 s. Controller reboots afterward. Use with caution.
TrigErrorAckInputBOOLError reset
FilePathInputSTRINGPath of the bootdata file, typically: C:\TwinCAT\3.1\Boot\Plc\
FileTypeRawDataInputSTRINGFile extension for raw data, usually .bootdata
FileTypeBakDataInputSTRINGBackup file extension, usually .bootdata-old
SetSaveTimeInputREALAuto-save interval in seconds (10–10800 s)
ActBootDataFileNumOutputINTNumber of existing bootdata files
ActBootDataFileNameOutputSTRINGCurrent bootdata file name
ActOldDataFileNumOutputINTNumber of .bootdata-old files
ActOldDataFileNameOutputSTRINGCurrent .bootdata-old file name
ActBakBootDataFileNumOutputINTNumber of historical backup files
ActBakBootDataFileNameOutputSTRINGNames of backup files
IsDataRestoreOKOutputBOOLTRUE when parameters are initialized and data is valid
IsDataLostOutputBOOLTRUE if CRC check fails — system must not continue running
IsPowerLostOutputBOOLIndicates power loss
LogTextOutputBOOLLog output
ErrorIDOutputUDINTError codes…

2.10. Runtime Behavior

Select the correct root directory sRootDir based on the PLC system.

Using debug displays detailed information on the screen;
using nodebug runs silently in the background.

2.11. Example Program

The project contains the complete FB_Persistent source code and example calls.
Extract the project on a local PC to review the implementation.

3. Data Persistence in TC2 Systems

3.8. How Much Data Can Be Stored in a 1-MB Persistent File

In TwinCAT, persistent variables are stored as file-based records. These records contain not only the variable values but also the variable names. Therefore, the total amount of data a 1-MB persistent file can hold depends heavily on both the variable naming length and the data type.

In TC2 systems, the byte-level layout of persistent files follows a strict and predictable sequence. Any additional characters in a variable name or an increased number of array elements directly increase the amount of storage space that variable occupies.

Based on these characteristics, the following conclusions can be drawn:

  • Array-based persistent variables provide the highest storage efficiency.
    Because an array uses only one variable name entry for storage, increasing the number of array elements significantly increases the proportion of actual data relative to metadata overhead.

  • To determine whether persistent data exceeds the 1-MB capacity limit, the most reliable approach is to check the actual size of the backup files.
    TC2 persistent files are typically located at:
    C:\TwinCAT\Plc\TC2 PLC\TCPLC_T_1.wb~
    or under the “Hard Disk” directory on CE-based embedded devices.

Only backup files should be checked because, after a normal startup, the primary .wbp file is automatically removed. The system loads it once, renames it as .wb~, and only then becomes viewable.

3.9. FB_Persistent Function Block — Pin Description

The FB_Persistent function block in TC2 provides two core functions:
(1) Periodic updating and backup of the persistent data file, and
(2) Fast data restoration when data corruption occurs due to an abnormal shutdown or UPS failure.

Pin NameDirectionData TypeDescription
TrigFirstCycleIn/OutBOOLTriggers the creation of the initial persistent file when the system detects that no persistent file exists. This pin should only be triggered once per PLC project and should be protected by administrator access.
PowerOkInputBOOLUPS power-health signal. This is a mandatory connection and must reflect the external UPS status.
BootDataLoadedInputBOOLReserved.
OldBootDataInputBOOLReserved.
EnableRestoreBakDataInputBOOLEnables the restore mode. When this pin is TRUE, the automatic save mechanism becomes inactive. This should be protected by admin access.
TrigRestoreBakDataInputBOOLWhen restore mode is enabled, holding this pin TRUE for 10 seconds initiates the restoration sequence. The system will automatically reboot. Use with caution.
TrigErrorAckInputBOOLAcknowledges error states. Typically tied to the machine’s global error-reset function.
FilePathInputSTRINGFile path of the persistent storage files. Typically: C:\TwinCAT\Plc\ or the equivalent directory on CE devices.
FileTypeRawDataInputSTRINGFile type for the primary persistent file. Typically .wbp.
FileTypeBakDataInputSTRINGFile type for the secondary (backup) file. Typically .wb~.
SetSaveTimeInputREALInterval for periodic persistent-data updates (in seconds). Default: 10 s. Configurable range: 10–10,800 s.
ActBootDataFileNumOutputINTNumber of existing primary persistent files.
ActBootDataFileNameOutputSTRINGName of the active primary persistent file.
ActOldDataFileNumOutputINTNumber of existing .wb~ backup files.
ActOldDataFileNameOutputSTRINGName of the backup persistent file.
ActBakBootDataFileNumOutputINTNumber of historical backup files generated by the function block.
ActBakBootDataFileNameOutputSTRINGFile name of the most recent backup.
IsDataRestoreOKOutputBOOLTRUE when initialization is complete and data integrity is verified.
IsDataLostOutputBOOLTRUE when initialization fails or CRC verification fails. If TRUE, the machine must not proceed with operation. Data restoration should be attempted using EnableRestoreBakData.
IsPowerLostOutputBOOLIndicates that the system experienced a power loss.
LogTextOutputBOOLLog information.
ErrorIDOutputUDINTError codes:

  • 16#8001: Error deleting .wbp during restore

  • 16#8002: Error deleting .wb~ during restore

  • 16#8003: Error renaming file during restore

  • 16#8004: No backup file available during restore

  • 16#8005: System reboot failed during restore

  • 16#8006: Error creating .wbp during auto-save

  • 16#8007: Error deleting backup .wbp file

  • 16#8008: Error deleting .wb~ file

  • 16#8009: Error renaming .wbp file

  • 16#800A: Error renaming .wb~ file |

3.10. Program Behavior

Select the correct root directory (sRootDir) according to the target PLC device type.

If the option debug is replaced with nodebug, the PLC will execute the restore procedure silently.
When using debug, all restore-related messages are displayed on the HMI or desktop.

3.11. Program Example

The sample project includes:

  • Full source code of FB_Persistent for TC2.

  • Demonstration programs showing how to integrate and call the function block.

You may extract the included project package to your development PC and review the implementation in detail.