ControlSphere Persistence and Parameter Library Demo (CPP)

[Admin]

The ControlSphere Parameter and Persistence Service Library (CPP) provides an optimized means to store and retrieve variable values to and from well-formatted, human-readable data files. This library provides numerous advantages over the Retain/Persist, Recipes, and Parameters features built-into the CODESYS IDE, particularly in object-based design. Once a Function Block implements the CPP Library, the parameter, persistent, and recipe data for each instance are automatically managed – there are no lists to be created or maintained. The files(s) created by the CPP Library may be edited in a spreadsheet editor and/or moved to other systems to duplicate the persistent, parameter, or recipe values on those systems. This library includes a demo project.

See the videos below for more information on the purpose and application of the CPP library.

Features, advantages, and differentiators of the CPP Library include:

• The CPP Library stores data that will survive a power-cycle, reset, new download, or equipment change; or can be used in a production run. The CPP Library is often used for Parameters, Persistent variables, and Recipes.
• CPP-managed variables are automatically registered when a Function Block is instantiated. There are no persistence or recipe lists to create or maintain. Just add an instance of a Function Block and its CPP variables are automatically managed in one or more CSV files in the runtime file system. If more instances of Function Blocks are added to the design, their variables are automatically managed by the CPP Library. No further user effort is required.
• The CPP Library will create the initial CSV file containing the default values for all the CPP variables, in all the instances of Function Blocks that implement the CPP Library. This saves the user from the laborious and error-prone task of hand-typing this file.
• Since the CPP stores its variable values in well-organized human-readable ASCII files rather than binary files, the CPP files can be easily modified if persistence, parameter, or recipe variables values are added or removed from Function Blocks, or instances of Function Blocks are added or removed. Being able to modify the files allows the CPP persistence values to be moved to systems which are not identical to the originating system. Of course, at any time the user can have the CPP write a new CSV file which will include all the variables or instances, as described in the previous bullet. The CPP Library provides the maximum possible flexibility so your data is easily reused and is never lost.
• Parameters are set for all configurable objects from a consolidated source file which is easily managed in any spreadsheet software. There is no need to manually traverse the device tree searching for and opening each instance individually to set its parameters. Plus the parameters can be set either offline or online. In addition, the CPP Library does not have hierarchy restrictions like the built-in parameter tool – it works with nested Function Blocks to any size and shape of hierarchy.
• Product variations can be accommodated by placing different sets of parameter values in different parameter files. The proper file can be selected on startup based on the identification of the product. This same feature can be used to save and restore different recipes in a file format that is much more convenient than the built-in recipe tool.
• Parameter values are stored in a human readable and editable file, not buried and inaccessible in the project file. These files may be stored in the project device tree if desired so its variable values are automatically downloaded to the target on login. Or, the files can also be copied directly to the target so the CODESYS IDE is not required in a mass production environment.
• The CPP Library does not require copying values to and from a global variable list on each process cycle. So it is much more CPU efficient than the built-in persistence feature.
• The CPP can initiate a file read or write from the same Task where the file action is executed (the variables will then all be atomic), or the initiation can be in a different task from the execution (the file I/O will not pause the Task).
• Variables can all be managed in the same CSV file, or sets of variables can be partitioned to be managed in different CSV files (useful to differentiate between one-time system configuration variables, operating mode variables set by the operator via a visualization, and persistent process variables).
• The CPP can save all the variables in a Group for all the instances of Function Blocks, or it can save the variable values for one instance at a time. This is useful for saving the tuning parameters on an instance by instance basis.

.

The library and demo project can be downloaded from: This Link.
The demo version of the library will work with up to 6 Function Block instances. 
Runtime Licenses can be purchased on the CODESYS store, and the source code can be purchased from sales (at) ControlSphere (dot) pro.

These videos describe the CSS (since renamed CPP) library in more detail. While they are a little out of date, they still provide valuable information for the purpose and application of the CPP library:





The projects shown in the last video are public domain and available HERE.

[chathody123]

great topic, many thank

[sturmghost]

Can you give me any hint how he async funcions work?
I saw that you do not use any async library (like SysFileAsync) within the CPP library. So I guess you wrote your own async wrapper around the standard SysFile.library?

I did a quick test with a function block which suspends the calling task in a while loop:


FUNCTION_BLOCK BlockTask
VAR
T : TON := (IN := TRUE, PT:= T#10S);
END_VAR

WHILE NOT T.Q DO
T();
END_WHILE

IF T.Q THEN
T(IN := FALSE);
T();
T(IN := TRUE);
END_IF

I instantiated it in a program and call the instance of BlockTask. The program is in IEC-Task "A". My Main_PRG runs in IEC-Task "B" and also have the same timer setup as the BlockTask function block.

If I run the program, both timers are running simultaneously. So both program codes in Task A und B are running "async". Whats the point of having different async functions when you only have to throw the function block which should run async into another task? Am I missing something important here? Is the behavior when reading/writing files different?

[Admin]

Hello sturmghost. You are making several common mistakes for someone transitioning to PLC Programming. Unfortunately, this is far beyond what can be covered in a forum post. Please consult a good reference, such as The Book of CODESYS.

[Admin]

Errata:

If you have FBs in a string of inheritance (Extends) that all have persistence variables, try these ideas. Say, you have a grandchild which extends child which extends parent:

If you want the variables for all the FBs in the inheritance lineage to be on different lines in the CSV, modify the CPP library to:

1. Modify RecieveObjectRegistration accept a "partition" parameter
2. add a partition integer to grandchild
3. Have RegisterMySelf in grandchild and set partition:=0, then increment partition by the number of parameters in grandchild
4. Modify RegisterMySelf in child and parent pass partition to the partition parameter in RecieveObjectRegistration, and increment it by the number of parameters in this FB, then call RegisterMySelf in its parent (child)
5. Delete the MyType variable in all FBs. Hard code the name of the FB in the RecieveObjectRegistration in each RegisterMySelf. You could also append the FB name to MyPath.
6. Modify the CPP library to store the partition number in the CSV file
7. Modify the CPP library to pass the partition parameter to AcceptValues, ProvideValues, ProvideVarNames
8. In each of those, use the values from the ValueArray starting at the partition number
9. in each AcceptValues, ProvideValues, ProvideVarNames, call the parent's method of the same name

Or, if you want the parameters from each level to be on the same line in the CSV:

1. Modify AcceptValues, ProvideValues, ProvideVarNames to have a VAR_INPUT of StartingParameter integer and then use that as the first index int ValueArray
2. have each AcceptValues, ProvideValues, ProvideVarNames call the same method on its parent, passing it the number or parameters it has used in the StartingParameter argument

[lincoln20xx]

I've been working on implementing a library of functions and objects for our internal use, and after having to copy and paste and edit 20+ variable declarations to paste into the AcceptValues, ProvideValues, and ProvideVarnames methods generated by CPP, I put together a quick excel sheet to generate the relevant values quickly and with less errors than I will make manually.

I've attached it here, in hopes that someone else might find it useful.

Put the name of your variable in column B, the type in column C, and fill columns D,E, and F down to the row below your last variable.

Column F strips the last three characters from your variable name, which you may want to change if you do not add the _CI suffix to your configuration variables.

Attachments:

CPP_ValueGeneratorxlsx.xlsx (10 KB)

[Admin]

Lincoln, this is fantastic! Thank you for contributing!!

[lincoln20xx]

Attached is an updated version of the generator.

The ProvideVarNames column (G) now checks if the final three characters are _CI, and strips them if they are, and otherwise leaves them.

I've added a column before ISA_Name for inserting a prefix to the value in the case that the var you're targeting is within a STRUCT. The dummy values saved in the sheet show one case where you may want that ability.

The formulas in the cells may be a little easier to follow now, presuming that excel does not eat or mangle the line breaks and spacing I've added in when opened on a different computer.

The second tab has basic formulas allowing you to paste from your function block definitions on the right, and copy the parsed and cleaned up values on the right into the main generator sheet.

Attachments:

CPP_ValueGenerator_v1.1.xlsx (14.52 KB)

[lincoln20xx]

Feb 23, 2024 15:23:40 GMT Admin said:

Errata:

If you have FBs in a string of inheritance (Extends) that all have persistence variables, try these ideas. Say, you have a grandchild which extends child which extends parent:

If you want the variables for all the FBs in the inheritance lineage to be on different lines in the CSV, modify the CPP library to:

1. Modify RecieveObjectRegistration accept a "partition" parameter
2. add a partition integer to grandchild
3. Have RegisterMySelf in grandchild and set partition:=0, then increment partition by the number of parameters in grandchild
4. Modify RegisterMySelf in child and parent pass partition to the partition parameter in RecieveObjectRegistration, and increment it by the number of parameters in this FB, then call RegisterMySelf in its parent (child)
5. Delete the MyType variable in all FBs. Hard code the name of the FB in the RecieveObjectRegistration in each RegisterMySelf. You could also append the FB name to MyPath.
6. Modify the CPP library to store the partition number in the CSV file
7. Modify the CPP library to pass the partition parameter to AcceptValues, ProvideValues, ProvideVarNames
8. In each of those, use the values from the ValueArray starting at the partition number
9. in each AcceptValues, ProvideValues, ProvideVarNames, call the parent's method of the same name

Or, if you want the parameters from each level to be on the same line in the CSV:

1. Modify AcceptValues, ProvideValues, ProvideVarNames to have a VAR_INPUT of StartingParameter integer and then use that as the first index int ValueArray
2. have each AcceptValues, ProvideValues, ProvideVarNames call the same method on its parent, passing it the number or parameters it has used in the StartingParameter argument

For those with experience working with python, or where one is trying to do things in a way that the IDE/compiler isn't expecting, here's a very rough idea I had for handling a chain of inherited persistence/configuration values, using Codesys' python scripting in a way that is not dissimilar to an excel macro[0]:

- include some kind of comment or other flag in the parent object where you want your configuration to "live"
- scan all of the function blocks in your project, determine which have _CI parameters (or whatever else you use as your configuration identifier)
- traverse each called program, use the flags to assemble or modify persistence groups, method calls or other functionality as appropriate

A subset of this idea could also be an effective way of automagically generating the content for standard CPP methods, or for implementing the excellent suggestions made above.

[0] help.codesys.com/webapp/cds-access-cds-func-in-python-scripts;product=codesys;version=3.5.17.0

[lincoln20xx]

An example implementation of the above python script can be found here:

github.com/AccruedInnovation/ParameterPersistenceLibrary-Method-Generator

It would need to be modified in minor ways for anyone using the standard CPP library.