License Manager Manual

About this documentation

This documentation provides essential information for working with components of the DDAS software ecosystem. It is intended for software developers and machine manufacturers who integrate, validate, and operate DDAS function blocks within CODESYS‑based applications.

This manual describes licensing of the DDAS Machine Insight Suite with DDAS activation keys.

Note!

Before installing or configuring any software, ensure that you have read and understood the operating instructions of all relevant hardware devices!

Tip!

Further information can be found at: https://www.ddas.digital

This manual is part of the DDAS library collection, which includes documentation for license management, date and time handling, scheduling, equipment performance, and other functional modules:

Document history

General

Library

The library DDAS_LicenseManager_Lib (namespace DDAS_LM) checks the license of all DDAS libraries. Each DDAS library references it; it is added to the project automatically and is delivered in compiled form only.

The library provides:

To write to GVL_License or to call GetLicenseInfo, add DDAS_LicenseManager_Lib explicitly to the Library Manager of your application. The Application Template already contains this reference.

Licensing Concept

A license is based on three keys:

• SiteCode – company identifier, chosen by the customer and registered with DDAS (see 2.3).

• LibraryGuid – identifies the bundle or a library; delivered with the libraries.

• LibraryActivationKey – issued by DDAS for exactly this SiteCode and LibraryGuid (for the Machine Insight Suite: the bundle GUID). Eight hexadecimal characters, for example EDB86DA0.

Bundle license

DDAS licenses the Machine Insight Suite as a bundle, in every edition. One activation key for the bundle GUID activates all libraries of the suite:

The bundle covers the libraries included in the suite at the time of purchase. DDAS does not issue activation keys for single libraries of the suite. Each library still has its own GUID, as a constant in the library itself, for example DDAS_DT.GVL_LibGuide.cLibraryGuid; use it to query the license status of the library with GetLicenseInfo (chapter 4).

Site code

• Choose a site code that identifies your company, for example ACME-Automation. DDAS checks that it is unique; general or sample values such as DDAS-Site-License are not accepted.

• The site code is part of every activation key. It cannot be changed after the first key has been issued.

• Enter the site code exactly as registered (up to 80 characters).

Other license source

Without activation data in GVL_License, the libraries use a CODESYS device license, if one is present on the device (Machine Insight Suite SL, see its installation and licensing documentation).

Licensing Process

1. Select the edition of the Machine Insight Suite.

2. Evaluate the libraries in the Application Template or in a test project in demo mode (2.4).

3. Request a quote, order the license and send your site code to DDAS.

4. DDAS checks the site code and sends the activation key for the bundle.

5. Enter the site code and the bundle key in GVL_License (chapter 3), or in GVL_Lib_Licensing when you use the Application Template (2.6).

6. Check the status with GetLicenseInfo (chapter 4). All function blocks of the suite now run without time limit.

Demo Mode

With a site code but without a valid activation key, a library runs with full functionality in demo mode:

• 2 hours from each start of the application. An online change does not restart the demo.

• The demo starts with the first call of a DDAS function block or of GetLicenseInfo. The demo time only runs while DDAS function blocks or GetLicenseInfo are called.

• A bundle entry starts one demo for the bundle and all its libraries.

• After the demo has expired, the library stops and GetLicenseInfo reports error 30. Start the application again to start a new demo.

• A valid activation key entered during the demo takes effect immediately.

• Without a site code there is no demo with activation keys.

License Sources and Priority

The License Manager evaluates the sources in this order; the first one that applies is used:

xLicensed is TRUE for priorities 1 to 4.

Licensing in the Application Template

The Application Template contains the licensing part in the folder 08_Licensing. Enter your data only in GVL_Lib_Licensing:

prgLicenseKeys passes these values to DDAS_LM.GVL_License; prgLicenseStatus reads the status of all libraries with GetLicenseInfo and passes licensing errors to MergeLibFBErrors. As long as no site code and no activation key are entered (state of delivery), prgLicenseKeys passes no activation data; only a CODESYS device license then applies. With a site code but without a key the demo mode starts (2.4). Details: Application Template Manual.

Screenshot: GVL_Lib_Licensing

GVL_License

General Information

Name: GVL_License (global variable list, access only qualified: DDAS_LM.GVL_License)

Library: DDAS_LicenseManager_Lib

CODESYS version compatibility: CODESYS V3.5.18.0 and higher

Purpose & Scope

GVL_License receives the activation data of the application: one site code and up to ten entries of LibraryGuid and activation key. The License Manager evaluates the entries; the status cannot be set directly.

Typical use cases

• Activate the Machine Insight Suite with one bundle entry

• Start the demo mode for evaluation (site code without key)

Interface Description

Structure scActivation

The activation key is not case-sensitive; spaces and hyphens are ignored (edb8-6da0 equals EDB86DA0). Unused entries stay empty.

Execution & Timing Behaviour

The License Manager checks GVL_License for changes at most every 100 ms and then verifies the keys. The DDAS libraries query the result at most once per second. Write the entries once at start-up or cyclically; both work.

Assumptions & Limitations

• One site code per application.

• Up to ten entries. For the Machine Insight Suite one entry with the bundle GUID is sufficient; leave the other entries empty.

• An entry with GUID but without site code produces error 11 for this GUID and, for a bundle, for all its libraries.

Example Implementation

Bundle license (Machine Insight Suite):

DDAS_LM.GVL_License.sSiteCode := 'ACME-Automation';

DDAS_LM.GVL_License.aActivation[1].sLibraryGuid := '{LIB-DDAS-MIS-BUNDLE-4A3D2F7D}';

DDAS_LM.GVL_License.aActivation[1].sActivationKey := 'EDB86DA0';

The activation key in this example is a placeholder and does not activate a license. To try the libraries without a key, use the demo mode (2.4).

Function GetLicenseInfo

General Information

Name: GetLicenseInfo (function)

Library: DDAS_LicenseManager_Lib

CODESYS version compatibility: CODESYS V3.5.18.0 and higher

Purpose & Scope

GetLicenseInfo returns the current license status of a library or of the bundle: whether the library may run, whether a full license or a demo is active, the remaining demo time, the license source and the last activation error.

Typical use cases

• Show the license status in the visualization

• Pass licensing errors to the error handling of the machine

• Check the activation after entering new keys

Interface Description

Structure scLicenseInfo

Enumeration eLicenseSource

Execution & Timing Behaviour

Call GetLicenseInfo cyclically in a task, for example once per cycle for each library of interest. The function returns the status evaluated by the License Manager (3.4); calling it more often does not change the result.

Error Handling & Diagnostics

iErrorID contains the last activation error of the GUID (chapter 5). A valid activation key clears the errors of its GUID. Use Get_sError for the error text.

Example Implementation

VAR

stInfoDT : DDAS_LM.scLicenseInfo;

sErrorDT : STRING;

END_VAR

stInfoDT := DDAS_LM.GetLicenseInfo(sLibraryGuid := DDAS_DT.GVL_LibGuide.cLibraryGuid);

IF stInfoDT.iErrorID <> 0 THEN

sErrorDT := DDAS_LM.Get_sError(iErrorID := stInfoDT.iErrorID);

END_IF

Screenshot: prgLicenseStatus of the Application Template online

Screenshot: visualization page Demo_Visu_LM with site code, bundle key and license status

Error Codes and Get_sError

Function Get_sError

Get_sError returns the error text and the enumeration value for an error code.

Each DDAS library has its own Get_sError for its own error codes, for example DDAS_DT.Get_sError. Use DDAS_LM.Get_sError for codes from GetLicenseInfo.

Enumeration eError

An empty activation key is the normal demo case and is not reported as an error. The values empty_Key (10) and empty_cLibraryGuid (12) are used internally only.

Error 10 of the function blocks: without a valid license, the function blocks of the DDAS libraries stop and report their own error 10 (no_ValidLicense). This is a code of the respective library (DDAS_DT.eError, DDAS_SL.eError, DDAS_EP.eError), not of the License Manager. Check the cause with GetLicenseInfo.

Troubleshooting

If the problem remains, contact support@ddas.digital with the library versions, the site code and the output of GetLicenseInfo.

Your Feedback Matters

These instructions have been prepared to the best of our knowledge and belief to provide you with the highest possible level of support when working with our product.

Despite our best efforts, we may not always fully achieve this objective. If you identify any issues or have suggestions for improvement, we would greatly appreciate your feedback.

Please send your comments or criticism in a short e‑mail to:

support@ddas.digital

Thank you for your support.

Your DDAS Application Software Team