Deployment and Licensing

In order to prevent the library sources from being published accidentally (for example, as a project archive), only the owner (user:Owner) should have read/write access to all elements of a library. Exception: The “Library Manager” and “Project Information” objects should be readable without the need of a password (user: Nobody).

  • The sources of a library should not be distributed unprotected.

  • Libraries should be provided in compiled form (*.compiled-library) only.

  • Additional protection provides the restriction of the user rights for “Everyone”.

  • Please allow read access for the following objects:

_images/Objects.png _images/UserRights-1.png

Note

This requirement can be fulfilled very easily by creating a main folder with the library name in the uppermost level of the project. All elements other than “Project Information” und “Library Manager” are then situated under this “Main Folder”. This folder structure allows to manage the access rights of this folder and all the folders under it with one single action.

Currently CODESYS provides the following possibilities to restrict the usage:

Platform-/vendor dependent usage restriction

If certain contents of a library should only be available on a definite controller type, see Platform-/vendor dependent usage restriction for a recommendation on how to match this requirement.

Licensing for CODESYS Store

Especially for the merchandising of a library via the CODESYS Store the licensing via CODESYS Security Key is a mandatory precondition. For hints on how to process such a licensing, see Licensing for CODESYS Store

Licensing via 3SLicense.library

This option is only available for 3S libraries. They can use it to check whether they are licensed for the current controller platform.

Platform-/vendor dependent usage restriction

If a controller manufacturer wants to restrict the usage of one of his libraries to all or to parts of his controller families, he can use the library SysTarget to read the Vendor- (High-word) and Target-Id (Low-word) of the controller via SysTargetGetId. Therefore, in his library code he checks whether the return values match the expected ones, and ensures that only in the case the library works correctly. Otherwise via function LogAdd2 of library CmpLog an output in the log window should be created or even via AppGenerateException of library CmpApp an exception should be created on the runtime system.

Licensing for CODESYS Store

There are two methods of licensing supported: Either require a license for using a library in CODESYS (during the engineering process) or require a license on the controller device for executing the library code.

Engineering-License via CODESYS Security Key

Especially for the merchandising of a library via the CODESYS Store the licensing via CODESYS Security Key is available. The end user loads the library from the CODESYS Store and gets a license from there, which he saves on a CODESYS Security Key. He will only be able to compile a library protected in this way, if this dongle-bound working place license is available. For this the library provider performs the following steps:

  • Contacting 3S (store@codesys.com) in order to get firm-code, product code and a license for those

  • Entering these values in the form “Licensing” in the Project Information of the library

  • Saving the library as “compiled-library” (only possible, if the CODESYS Security Key with the above mentioned license is available on the computer on which the library gets created)

_images/LicenseKey.png

Engineering-License via Soft Container

With the release of CODESYS SP14 there is another possibility to store the Engineering-License, the Soft Container. The dialog shown above can now contain a comma-separated list of codes in the “Firm code” field. The previous “firm code” for the CODESYS Security Key must remain at the top of this list. The other “firm codes” for the soft container, are separated by a comma and appended to this entry. So a library from the store can be prepared at the same time for the licensing over a CODESYS Security Key or the licensing over the soft container.

Single-Controller-License via CmpCodemeter

For third-party CODESYS Store suppliers, there is a possibility to license their libraries for a single controller device. Precondition: The device must support the component CmpCodemeter , which can be checked with a test application “DeviceReader” provided in the CODESYS Store.

The licensing is done with the help of the library 3SLicense that must be inserted in the library that shall be inserted as placeholder library.

In addition, the third-party supplier must get in contact with (store@codesys.com) and get a product code.

In his library code, he can check the license using the operator __CHECKLICENSE (DWORD productCode, BOOL xDoChallenge) : UDINT, which returns:
-1: if the challenge succeeded and no license is present and the demo time has not passed,
0: if the challenge failed or no license is present and the demo time has passed
x: if the challenge succeeded and if the license is present.
VAR
    productCode : DWORD;
    xDoChallenge : BOOL;
    udiResult : UDINT;
END_VAR

udiResult := __CHECKLICENSE(productCode, xDoChallenge);
IF TO_INT(udiResult) = -1 THEN
    (* ... *)
END_IF
From V3.5 SP10, the user can also request the license value of a single bit of a product code: __CHECKLICENSEBIT (DWORD productCode, BOOL xDoChallenge, INT iBitNo) : INT, which returns:
-1: if the challenge succeeded and no license is present and the demo time has not passed,
0: if the challenge failed or this license is not set and the demo time has passed
1: if the challenge succeeded and if the license bit is set.
VAR
    productCode : DWORD;
    xDoChallenge : BOOL;
    iResult : INT;
END_VAR

iResult := __CHECKLICENSEBIT(productCode, xDoChallenge, 2);
IF iResult = -1 THEN
    (* ... *)
END_IF

Besides the productCode, there is an input xDoChallenge, which determines if a challenge shall be executed prior to the license check. The challenge executes an additional check to make sure that the 3SLicense.library has not been patched and should be executed once by each licensed component.

Generally, the interpretation of x is up to the licensing library, but typically, for enabling a feature, the license value should be 1. To optimize the performance, one should call the operator already in init code (reason: The first call of this operator takes slightly longer, which should not mind during initialization).

If the library wants to support a 30 minute demo mode, it must call the operator repeatedly, as – if no license is present – it will return -1 first (indicating the demo mode) and change to 0 when the demo mode has expired. Note that this method is only working on CODESYS versions starting with CODESYS 3.5 SP5. On former versions the operator is unknown and will lead to compile errors.

Licensing via 3SLicense.library

This option is only available for 3S libraries. They can use it to check whether they are licensed for the current controller platform.