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:
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)
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.
__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 passedx
: 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
__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 passed1
: 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.