Comprehensive Analysis of TwinCAT Persistent Power-Off Retention Functionality

Posted by on

 Content Abstract

The Persistent power-off retention function is one of the most commonly used features in PLCs. It is extremely simple to use under normal power-on/off conditions: as long as variables are declared as Persistent, the system automatically saves and loads these variables with each power cycle. However, unexpected issues can arise in practical applications. This article provides an in-depth explanation of the Persistent variable storage mechanism, the effects of various conventional and unconventional operations on Persistent data based on actual testing, and recommended best practices to avoid pitfalls derived from test results. Additionally, it shares an enhanced DIY implementation code for Persistent functionality, developed by a Beckhoff China engineer, which enables automatic recovery of data lost due to unexpected events. The article also briefly covers methods for power-off retention of NC parameters.
Keywords: Persistent, .bootdata, .bootdata-old, .wbp, .wb~
Table of Contents
  1. TwinCAT Standard Persistent Functionality
    1.1 Mechanism of Persistent Data Storage in PLCs
    1.1.1 Writing Data
    1) When Writing Occurs
    2) Writing Actions
    3) Write Failures
    1.1.2 Loading Data
    1) When Loading Occurs
    2) Loading Actions
    3) Load Failures
    4) Successful Load but Data is All Zero
    1.1.3 Clearing Data
    1) When Clearing Occurs
    2) Clearing Actions
    1.2 Scenarios Where Persistent Data Can Be Successfully Recovered
    1. During Abnormal Power Failure
    2. PLC Abnormal Exit (e.g., Page Fault)
    3. PLC Stop or Reset
    4. When Array or Struct Content Changes (With Test Records)
      1.3 Scenarios Where Persistent Data is Inevitably or Potentially Lost
    5. Repeated Power-Offs During Startup
    6. No UPS or Insufficient UPS Capacity, Preventing Persistent Data Write Before Shutdown
    7. Clicking "Reset to Initial Values and Restart," Rendering Persistent Data Unrecoverable
    8. Renaming Global Variable Files/Subroutines/FB Instances, Making Persistent Data Unrecoverable
      1.4 Recommended Settings for Persistent Variables
    9. Prefer Array Types
    10. Centralize Placement
    11. Use Variables Strategically
  2. Enhanced DIY Program for Persistent Power-Off Retention
    1. Program Code and Description
    2. Test Records
  3. Power-Off Retention of NC Axis Data
  4. Frequently Asked Questions
    4.1 How Many Variables Can a 1MB Persistent File Store?
    4.2 Who Handles Persistent Data Storage?
    4.3 References
Main Text
1 TwinCAT Standard Persistent Functionality
1.1 Mechanism of Persistent Data Storage in PLCs
In simple terms, as long as a variable in the PLC is declared with the Persistent attribute, no additional settings or operations are required—the system will automatically save and restore these variable values. The default Persistent data storage mechanism works as follows:
  • When TwinCAT exits, Persistent-type data in the PLC is saved to the file Port_851.bootdata.
  • When the PLC starts, it reads Port_851.bootdata and creates a backup as Port_851.bootdata-old.
In other words, before PLC startup, two backup files exist: Port_851.bootdata (data from the last shutdown) and Port_851.bootdata-old (data from the second-to-last shutdown). The former is updated each time TwinCAT exits, while the latter is updated each time the PLC starts.
A key prerequisite for successful Persistent data retention in practice is that TwinCAT must shut down normally. By analyzing the timing and implicit actions of writing and loading data, it’s possible to predict where errors might lead to Persistent data loss and how to mitigate these issues. Detailed explanations follow:
1.1.1 Writing Data
  1. When Writing Occurs
    • Automatic Writing: Whenever TwinCAT exits the Running mode normally, all data with the Persistent attribute is automatically written to Port_851.bootdata. "Normal" scenarios include:
      • Normal OS shutdown.
      • Win10 system with UPS, where UPS software detects power loss and triggers shutdown.
      • CE system with UPS, where the FB_S_UPS function block detects power loss and triggers shutdown.
      • Operator shuts down/restarts the OS from the desktop.
      • PLC calls NT_ShutDown or NT_Reboot to shut down/restart the OS.
      • TwinCAT exits Running mode normally (e.g., activating configuration, switching to Config/Stop, or Restart).
    • Manual Writing: Besides automatic writing during a normal TwinCAT exit, data can also be written manually by calling the FB_WritePersistentData function block and providing a rising edge to its Start signal.
  2. Writing Actions
    • All Persistent-type variables are written to a file:
      • In TwinCAT 2: TCPLC_T_1.wbp, where "1" denotes the PLC Runtime number (max 4).
      • In TwinCAT 3: Port_851.bootdata, where "851" is the default PLC port number (configurable).
  3. Write Failures
    • In the following cases, the system cannot complete an automatic write, failing to save changes since the last successful write:
      • Abnormal OS shutdown (e.g., no UPS or insufficient UPS capacity to support normal shutdown).
      • TwinCAT crashes and cannot return to Config mode normally.
      • Power loss (UPS depleted) occurs during a write triggered by FB_WritePersistentData.
    • Although a correct .bootdata file isn’t generated in these cases, the backup .bootdata-old file from startup remains, so only data changes from the current session are lost, and the system reverts to the startup state.
1.1.2 Loading Data
  1. When Loading Occurs
    • Persistent data is automatically loaded each time the PLC starts. After startup, there’s no mechanism to reload data. The .bootdata-old file is updated only once during startup.
  2. Loading Actions
    • Reads data from Port_851.bootdata.
    • If Port_851.bootdata is corrupted:
      • If Clear Invalid Data is False, it reads from Port_851.bootdata-old.
    • Initializes the loaded data into the program.
    • Backs up Port_851.bootdata as .bootdata-old.
    • Deletes Port_851.bootdata.
    • For TwinCAT 2, the Persistent file is TCPLC_T_1.wbp, and its backup is TCPLC_T_1.wb~.
  3. Load Failures
    • Port_851.bootdata is corrupted, .bootdata-old is intact, but Clear Invalid Data is True.
    • Both Port_851.bootdata and .bootdata-old are corrupted or missing.
  4. Successful Load but Data is All Zero
    • Before TwinCAT exits Running mode normally, all data (including Persistent) is zeroed out (e.g., after executing Reset All or initial value reset).
    • If data loading isn’t completed during startup (data remains zero) and a shutdown is triggered, the all-zero data is written to Port_851.bootdata.
1.1.3 Clearing Data
  1. When Clearing Occurs
    • When applying an old controller to a new project, Persistent data may need to be cleared to prevent old variables with the same name as those in the new project from being loaded and causing errors.
  2. Clearing Actions
    • Delete Port_851.bootdata and Port_851.bootdata-old files, or
    • Execute Reset All.
1.2 Scenarios Where Persistent Data Can Be Successfully Recovered
  1. During Abnormal Power Failure
    • With a UPS, TwinCAT can always shut down normally, ensuring Persistent data is saved. Even if UPS capacity degrades and a shutdown doesn’t fully write the file, the next restart will at least load the Persistent data backed up at the last startup.
  2. PLC Abnormal Exit (e.g., Page Fault)
    • Testing shows that after a Page Fault, pressing F5 changes the target system icon from yellow to red to blue, switching to Config mode and generating a .bootdata file. Restarting in Running mode successfully loads values from just before the Page Fault.
  3. PLC Stop or Reset
    • Tests confirm that after stopping the PLC program and switching TwinCAT to Config, a .bootdata file is still generated. Upon restart, Persistent data is restored to its value just before the stop.
  4. When Array or Struct Content Changes (With Test Records)
    • Test Environment: CX2040, Win10, TwinCAT 3, with UPS.
    • Test Results: Previously saved Persistent data is recoverable in these cases:
      • Changing array size.
      • Changing the size of array elements in a struct.
      • Adding elements (standard or array type) anywhere in a struct.
      • Renaming a struct.
1.3 Scenarios Where Persistent Data is Inevitably or Potentially Lost
  1. Repeated Power-Offs During Startup
    • During startup, TwinCAT loads data from .bootdata, deletes it, and generates .bootdata-old. If startup isn’t completed (Persistent variables are still 0) and a shutdown occurs, the current (zero) values are written to .bootdata. On the next stable startup, .bootdata contains zeros, and the previous .bootdata-old is overwritten.
  2. No UPS or Insufficient UPS Capacity, Preventing Persistent Data Write Before Shutdown
    • Without a UPS or with insufficient capacity for a normal shutdown, Persistent data file generation isn’t guaranteed, nor is correct data loading upon restart. Per official documentation, a 1-second UPS can save up to 1MB. If .bootdata-old or TCPLC_T_1.wb~ files approach or exceed 1MB without a larger-capacity UPS, relying solely on Persistent for process and recipe data retention poses a significant risk of data loss.
  3. Clicking "Reset to Initial Values and Restart," Rendering Persistent Data Unrecoverable
    • In TwinCAT 3: Icon-based.
    • In TwinCAT 2: Online | Reset All menu.
    • During debugging, clicking this resets all variables (including Persistent). Without a dedicated backup/restore program, subsequent normal shutdowns, configuration activations, or TwinCAT restarts cannot recover prior Persistent values.
  4. Renaming Global Variable Files/Subroutines/FB Instances, Making Persistent Data Unrecoverable
    • For global Persistent variables in TwinCAT 3, filenames are included when saving; in TwinCAT 2, they are not. For local Persistent variables in both TwinCAT 2 and 3, subroutine and FB instance names are included.
    • Example: If Main.iVar1 (Persistent) is renamed to PRG01.iVar1, a normal shutdown creates Port_851.bootdata with PRG01.iVar1 and its value, excluding Main.iVar1. On login, the renamed variable takes its initial value, and prior Main.iVar1 data cannot be restored. Only renamed subroutine Persistent variables are affected; other data remains intact.
1.4 Recommended Settings for Persistent Variables
  1. Prefer Array Types
    • Array-type Persistent variables use a single variable name. The more elements, the higher the proportion of Data in the total space. This reduces the bytes used by variable names and lengths in the Persistent file, saving space and write time.
  2. Centralize Placement
    • Preferably place them in global variables to avoid losing track after unexpected events.
  3. Use Variables Strategically
    • Avoid arbitrarily adding Persistent variables throughout the project. This prevents issues where cleaned-up or renamed variables in an ongoing project cannot recover values saved under old names.
2 Enhanced DIY Program for Persistent Power-Off Retention
To prevent data loss in the scenarios outlined in "1.3 Scenarios Where Persistent Data is Inevitably or Potentially Lost," a Beckhoff China engineer developed a dedicated "Persistent Backup and Recovery" program and documentation. It supports continuous data backup and automatic/manual recovery in TwinCAT 2 and 3, across WinCE and Win10. Integrating this program early in debugging is recommended to quickly recover data after misoperations.
  1. Program Code and Description
    • Persistent Data Storage Introduction V1.0.3.docx
  2. Test Records
    • 20250224 Persistent Test Records for Arrays and Structs.docx
3 Power-Off Retention of NC Axis Data
By default, NC axis data is not retained after power-off. However, in certain cases (e.g., zero position of an absolute encoder), mechanical reassembly might shift the zero position:




It is possible to enable the power-off retention function for NC axis data. This way, once the PLC writes a value such as the Position Bias, the system will retain this value after the next startup. The method to enable this is as follows: First, enable the Retain Data function for the NC task:





Select the axis whose parameters you want to save. Navigate to Axis | Parameter | Other Settings, and set the Data Persistent parameter to TRUE.

After activating the configuration, any modification to this axis’s parameters—whether made through the debugging interface or via the PLC program—will be retained after a TwinCAT restart.





Mastering PLC Programming: The software engineering survival guide to automation programming






The mechanism for power-off retention and loading of NC data is similar to that of PLC data, with the difference being the storage path: NC axis data is saved to C:\TwinCAT\3.1\Boot\TCNC.bootdata when TwinCAT exits. When TwinCAT starts, it loads TCNC.bootdata and creates a backup as TCNC.bootdata-old. Since NC axis parameters are not frequently modified and are typically not repeatedly written to by the PLC program, there is no dedicated PLC function block to manually save the current NC axis values to the TCNC.bootdata file. As long as a standard UPS (not a 1-second UPS) is used to ensure TwinCAT always starts and exits normally, the NC axis parameters can be reliably preserved. 4 Frequently Asked Questions 4.1 Persistent File Size and Total Variable Bytes The TwinCAT Information System specifies that the Persistent data file saved by a 1-second UPS should not exceed 1 MB. So, how many variables can a 1 MB file actually store? Since TwinCAT saves Persistent variables in a file format that includes not only the variable values but also their names, the number of variables a 1 MB Persistent file can hold depends heavily on the variable names and types. This relationship differs between TwinCAT 2 (TC2) and TwinCAT 3 (TC3): In TC3, 4-byte alignment is considered, resulting in larger file sizes. For the same set of Persistent variable names, types, and quantities, the file size will differ between TC2 and TC3. Generally, saving Persistent variables as arrays is the most efficient approach. Attempting to calculate the exact file size of Persistent variables in a PLC program is impractical. The best method is to directly check the properties of the backup files: TC3: C:\TwinCAT\3.1\Boot\Plc\Port_851.bootdata-old TC2: C:\TwinCAT\Boot\TCPLC_T_1.wb~ The reason for checking backup files is that, after a normal startup, the .bootdata and .wbp files are automatically deleted. These files are only visible in their final form when manually switching to Config mode. Once data is loaded during startup, they are renamed to .bootdata-old and .wb~ files. 4.2 Who Handles Persistent Data Storage Saving Persistent data is a mechanism of TwinCAT itself, not a function of the PLC. Therefore, as long as TwinCAT can shut down normally—rather than remaining in a service-stopped state (indicated by a red icon)—various PLC errors will not affect the generation of the .bootdata file. When TwinCAT exits, it saves not only PLC data but also NC data. For specifics, refer to "Section 3: Power-Off Retention of NC Axis Data."