Compatibility
Compatibility of CODESYS projects
Storage format
Use Case | Support |
|---|---|
Loading projects in new CODESYS version without data loss | ✓ |
Saving projects for older CODESYS versions | ✓ |
Opening new projects in old CODESYS versions |
|
Existing projects which are opened with a newer CODESYS version are kept in "compatibility mode" for as long as possible. As long as you only make changes to the project which do not require any new functionality, the storage format remains the same. This is why the original CODESYS version can continue to open and edit the project without data loss. If you make changes which require new data to be saved in the project, then you will be notified interactively about this situation. You have the option of undoing the last changes if a compatibility breach would be unacceptable.
You can often open projects with newer memory versions in older CODESYS versions, but this is strongly discouraged. Whether or not you can open projects depends on the availability of plug-in types in the old version. A corresponding message is displayed when loading such a project.
You also have the option of saving a project for an older version of CODESYS by executing the File → Save as command. In this case, information about which objects are affected by the data loss is displayed in the Messages view. However, saving projects for an old version affects the explicitly only storage format. There is no full conversion of the project in which the compiler version or similar settings are adapted to match the old version.
Online behavior
Use Case | Support |
|---|---|
Compiling a project, which was created with an old CODESYS version, in a new CODESYS version | ✓ |
Log in without online change in a new version. | -- |
New CODESYS versions cannot generate the same code for existing projects as the older version with which the project was created. If you need to log in to a running application without an online change or download, then you need to open the project with the version which was last loaded on the controller. The CODESYS Installer and the project analysis help you to restore the original version if it does not already exist.
As a result, this means that opening the project with a newer or different version requires the project to be updated. This will most likely require a new download of the runtime environment. You also need to test the application for possible changes in behavior which result from new functions or bugfixes in the compiler or the graphical editors. In general, an attempt is made to minimize new compiler errors or behavioral changes for existing projects in order to keep the effort for updating to new versions as low as possible.
The following points need to be observed for compatibility with existing runtimes:
New functions in CODESYS are typically enabled in the device description. As a result, they are disabled for older runtime systems or older device descriptions.
The versions of all external libraries are resolved by means of the device description. As a result, they are matched to the corresponding runtime system.
Internal libraries are resolved by the CODESYS version, regardless of the version of the runtime system.
The communication services are structured according to a shared format with tags. Unknown tags are ignored by the runtime system. As a result, it is possible to change the communication service, but the programming system will not expect the runtime system to interpret the new information.
Compatibility of CODESYS libraries
Use Case | Support |
|---|---|
Using a compiled library, which was created in an older CODESYSversion, in a new CODESYS version. | ✓ |
Using a compiled library, which was created in a new CODESYS version, in an older CODESYS version. | -- |
Compiled libraries should always be created with the lowest CODESYSversion with which they need to be compatible. Old CODESYS versions recognize libraries which have been created with newer versions and reject their use in a project. The check is based on the compiler version set in the library. Depending on the contents of the library, the storage format can also play a role.
The same rules for CODESYS projects also apply to source libraries.
Compatibility of the CODESYS runtime system
However, it is not recommended to use an older version of CODESYS and a newer version of the runtime system. This compatibility has not been explicitly tested. Due to security corrections in newer runtime systems, there may be incompatibilities with older CODESYS versions.
The following points need to be observed for compatibility with existing runtime version:
New functions in CODESYS are typically enabled in the device description. As a result, these versions are disabled for older runtime systems or older device descriptions.
The versions of all external libraries are resolved by means of the device description. As a result, they are matched to the corresponding runtime system.
Internal libraries are resolved by the CODESYS version, regardless of the version of the runtime system.
The communication services are structured according to a shared format with tags. Unknown tags are ignored by the runtime system. As a result, it is possible to change the communication service, but the programming system will not expect the runtime system to interpret the new information.
Compatibility of device descriptions – Runtime system
Use Case | Support |
|---|---|
An older version of the device description and a newer runtime system are accepted during login. | ✓ |
A newer version of the device description and an older runtime system are not accepted, so that the login is rejected. | -- |
Existing projects must run on existing runtime systems, even with newer CODESYS versions. This can be fulfilled by not changing the device description in the project and having the existing version which matches the version of the runtime system. It is also possible to log in to the runtime system if the version of the device description and the runtime system are not too different or incompatible:
The device description contains a list of external libraries whose external functions are implemented in the runtime system. The corresponding version of the library is specified in the library placeholder list. This list is defined by the device manufacturer.
Tip
The placeholder list should contain only the libraries whose corresponding runtime components are available in the runtime system.
It is possible to configure the compatibility range between the device description and the runtime system. This means that you cannot log in to the controller if the versions do not match. This range can be selected by the device manufacturer with the following settings in the runtime system (see
SysTargetItf.hof the runtime system):SYSTARGETKEY_INT_TARGET_VERSION_MASK"TargetVersionMask": Setting to specify a mask for checking the target version for compatibility with the device description. Only the significant digits are checked in the mask.SYSTARGETKEY_INT_TARGET_VERSION_COMPATIBILITY_MASK"TargetVersionCompatibilityMask": Setting to specify a compatibility mask for checking the target version for compatibility with the device description. A device description which is lower than the target version or the same is accepted. A higher version of the device description is rejected.
CODESYS Version | CODESYS Control Version | Device Description Version | Recommended | Restrictions | Comment |
|---|---|---|---|---|---|
3.5.19.0 | 3.5.19.0 | 3.5.19.0 | Yes, optimal | -- | This is the optimal combination. |
3.5.19.0 | 3.5.12.0 | 3.5.12.0 | Yes | -- | This is a typical compatibility case. |
3.5.19.0 | 3.5.12.0 | 3.5.10.0 | No, but possible | Warning when logging in to the controller that the DevDesc does not match | This is possible because the |
3.5.19.0 | 3.5.12.0 | 3.5.19.0 | No | No access to the controller | By default, this is rejected because |
3.5.19.0 | 3.5.10.0 | 3.5.10.30 | No | No access to the controller | This is possible because the |
CODESYS Version | CODESYS Control Version | Device Description Version | Recommended | Restrictions | Comment |
|---|---|---|---|---|---|
3.5.17.0 | 3.5.19.0 | 3.5.19.0 | No | Incompatibilities are possible due to security corrections in the runtime system. | The set of all external libraries must be available in CODESYS. It is possible that in the external libraries there are newer IEC language resources used which lead to compilation errors. |
3.5.17.0 | 3.5.19.0 | 3.5.17.0 | No, but possible | Incompatibilities are possible due to security corrections in the runtime system. |
Compatibility of the boot project + Retains - Runtime system
Use Case | Support |
|---|---|
A newer runtime system loads older boot projects. | ✓ |
An older runtime system loads newer boot projects. |
|
It must be possible to load existing boot projects from the runtime system within a main version. An existing boot project is checked against the type designation of a target (VendorID, DeviceID, and the DeviceVersion since V3.5.8.0) before loading.
Retain variables from a saved retain file (<application>.ret) or from the SRAM must always be compatible. A checksum is saved in a separate file for each retain area. The same checksum is saved in the boot project. This checksum is generated by the compiler from the retain data and is an identification of all variables in the retain area with their respective types. If the checksum of the retain data and the checksum in the boot project do not match, then you have several options in the runtime system to select the behavior. You can specify these options in the [CmpApp] section of the cfg file:
Bootproject.RetainMismatch.Init = 1: The boot project is loaded and retains are initialized.Bootproject.RetainMismatch.Exception = 1: The boot project is loaded, but the application remains in the stop state, and is set to an exception state. This condition can be corrected with a manual reset.No setting
[DEFAULT]: The boot project is not loaded and an error message is added to the logger.
In runtime system version 3.5.7.0 and lower, the checksum was calculated from the entire data of the application. In newer versions, the checksum is calculated only from the data in the retain area. This means that the retain data can be loaded into a boot project with newer versions, even if the project has changed, as long as these changes do not involve any changes to the retain data.