SIEMENS 1500S Simatic Controllers Instruction Manual

Contents hide

1 SIEMENS 1500S Simatic Controllers

2 Specifications

3 Installation

4 Developing a CPU Function Library

5 Development of C/C++ Runtime Application

6 Using Example Projects

7 FAQs

8 Documents / Resources

8.1 References

SIEMENS 1500S Simatic Controllers

Specifications

Product Name: Open Development Kit 1500S V2.5 SP4
Software: SIMATIC STEP 7 (TIA Portal) Options Open Development Kit 1500S V2.5 SP4

Manual: Programming and Operating Manual
Release Date: 12/2023

Installation

Follow the installation instructions provided in the manual to set up the Open Development Kit 1500S V2.5 SP4.

Developing a CPU Function Library

Refer to sections 5 and 6 of the manual for developing CPU function libraries for both Windows and real-time environments.

Development of C/C++ Runtime Application

Section 7 provides guidance on developing a C/C++ runtime application using the kit.

Using Example Projects

Section 9 of the manual includes information on utilizing example projects to understand the kit’s functionalities better.

FAQs

What qualifications are required to operate the Open Development Kit 1500S V2.5 SP4?
Qualified personnel, as defined by training and experience, should operate the kit to identify risks and avoid hazards effectively.

How often is the information in the manual reviewed?
The information in the manual is reviewed regularly, and necessary corrections are included in subsequent editions to ensure accuracy.

View Fullscreen

Legal information

Warning notice system This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are graded according to the degree of danger.
DANGER indicates that death or severe personal injury will result if proper precautions are not taken.

WARNING indicates that death or severe personal injury may result if proper precautions are not taken.
CAUTION indicates that minor personal injury can result if proper precautions are not taken.
NOTICE indicates that property damage can result if proper precautions are not taken. If more than one degree of danger is present, the warning notice representing the highest degree of danger will be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to property damage.
Qualified Personnel The product/system described in this documentation may be operated only by personnel qualified for the specific task in accordance with the relevant documentation, in particular its warning notices and safety instructions. Qualified personnel are those who, based on their training and experience, are capable of identifying risks and avoiding potential hazards when working with these products/systems.
Proper use of Siemens products Note the following:

WARNING Siemens products may only be used for the applications described in the catalog and in the relevant technical documentation. If products and components from other manufacturers are used, these must be recommended or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and maintenance are required to ensure that the products operate safely and without any problems. The permissible ambient conditions must be complied with. The information in the relevant documentation must be observed.
Trademarks All names identified by ® are registered trademarks of Siemens Aktiengesellschaft. The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owner.

Disclaimer of Liability We have reviewed the contents of this publication to ensure consistency with the hardware and software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in this publication is reviewed regularly and any necessary corrections are included in subsequent editions.

Siemens Aktiengesellschaft Digital Industries Postfach 48 48 90026 NÜRNBERG GERMANY

S7-1500 / ET 200MP Documentation Guide
The documentation for the SIMATIC S7-1500 automation system and the ET 200MP distributed I/O system is arranged into three areas.
This arrangement enables you to access the specific content you require. Changes and supplements to the manuals are documented in a Product Information.
You can download the documentation free of charge from the Internet (https://support.industry.siemens.com/cs/ww/en/view/109742691).

Basic information
The System Manual and Getting Started describe in detail the configuration, installation, wiring and commissioning of the SIMATIC S7-1500 and ET 200MP systems. The STEP 7 online help supports you in the configuration and programming. Examples: · Getting Started S7-1500 · S7-1500/ET 200MP System Manual · Online help TIA Portal

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Introduction 1.1 S7-1500/ET 200MP Documentation Guide

Device information
Equipment manuals contain a compact description of the module-specific information, such as properties, wiring diagrams, characteristics and technical specifications. Examples: · Equipment Manuals CPUs · Equipment Manuals Interface Modules · Equipment Manuals Digital Modules · Equipment Manuals Analog Modules · Equipment Manuals Communications Modules · Equipment Manuals Technology Modules · Equipment Manuals Power Supply Modules
General information
The function manuals contain detailed descriptions on general topics relating to the SIMATIC S7-1500 and ET 200MPsystems. Examples: · Function Manual Diagnostics · Function Manual Communication · Function Manual Motion Control · Function Manual Web Server · Function Manual Cycle and Response Times · PROFINET Function Manual · PROFIBUS Function Manual
Product Information
Changes and supplements to the manuals are documented in a Product Information. The Product Information takes precedence over the device and system manuals. You can find the latest Product Information on the S7-1500 and ET 200MP systems on the Internet (https://support.industry.siemens.com/cs/de/en/view/68052815).
Manual Collection S7-1500/ET 200MP
The Manual Collection contains the complete documentation on the SIMATIC S7-1500 automation system and the ET 200MP distributed I/O system gathered together in one file. You can find the Manual Collection on the Internet. (https://support.industry.siemens.com/cs/ww/en/view/86140384)

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Introduction 1.1 S7-1500/ET 200MP Documentation Guide
SIMATIC S7-1500 comparison list for programming languages
The comparison list contains an overview of which instructions and functions you can use for which controller families. You can find the comparison list on the Internet (https://support.industry.siemens.com/cs/ww/en/view/86630375).

1.1.2

SIMATIC Technical Documentation
Additional SIMATIC documents will complete your information. You can find these documents and their use at the following links and QR codes.
The Industry Online Support gives you the option to get information on all topics. Application examples support you in solving your automation tasks.

Overview of the SIMATIC Technical Documentation
Here you will find an overview of the SIMATIC documentation available in Siemens Industry Online Support:
Industry Online Support International (https://support.industry.siemens.com/cs/ww/en/view/109742705)

Watch this short video to find out where you can find the overview directly in Siemens Industry Online Support and how to use Siemens Industry Online Support on your mobile device:
Quick introduction to the technical documentation of automation products per video (https://support.industry.siemens.com/cs/us/en/view/109780491)
YouTube video: Siemens Automation Products – Technical Documentation at a Glance (https://youtu.be/TwLSxxRQQsA)

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Introduction 1.1 S7-1500/ET 200MP Documentation Guide
Retention of the documentation
Retain the documentation for later use. For documentation provided in digital form: 1. Download the associated documentation after receiving your product and before initial
installation/commissioning. Use the following download options: Industry Online Support International: (https://support.industry.siemens.com)
The article number is used to assign the documentation to the product. The article number is specified on the product and on the packaging label. Products with new, non-compatible functions are provided with a new article number and documentation. ID link: Your product may have an ID link. The ID link is a QR code with a frame and a black frame corner at the bottom right. The ID link takes you to the digital nameplate of your product. Scan the QR code on the product or on the packaging label with a smartphone camera, barcode scanner, or reader app. Call up the ID link. 2. Retain this version of the documentation.

Updating the documentation
The documentation of the product is updated in digital form. In particular in the case of function extensions, the new performance features are provided in an updated version.
1. Download the current version as described above via the Industry Online Support or the ID link.
2. Also retain this version of the documentation.

mySupport

With “mySupport” you can get the most out of your Industry Online Support.

Registration
Support requests Documentation Favorites
Recently viewed articles CAx data

You must register once to use the full functionality of “mySupport”. After registration, you can create filters, favorites and tabs in your personal workspace. Your data is already filled out in support requests, and you can get an overview of your current requests at any time. In the Documentation area you can build your personal library. You can use the “Add to mySupport favorites” to flag especially interesting or frequently needed content. Under “Favorites”, you will find a list of your flagged entries. The most recently viewed pages in mySupport are available under “Recently viewed articles”. The CAx data area gives you access to the latest product data for your CAx or CAe system. You configure your own download package with a few clicks:
· Product images, 2D dimension drawings, 3D models, internal circuit diagrams, EPLAN macro files
· Manuals, characteristics, operating manuals, certificates
· Product master data

You can find “mySupport” on the Internet. (https://support.industry.siemens.com/My/ww/en)

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Introduction 1.1 S7-1500/ET 200MP Documentation Guide
Application examples
The application examples support you with various tools and examples for solving your automation tasks. Solutions are shown in interplay with multiple components in the system separated from the focus on individual products. You can find the application examples on the Internet. (https://support.industry.siemens.com/cs/ww/en/ps/ae)

1.1.3

Tool support
The tools described below support you in all steps: from planning, over commissioning, all the way to analysis of your system.

TIA Selection Tool
The TIA Selection Tool tool supports you in the selection, configuration, and ordering of devices for Totally Integrated Automation (TIA).
As successor of the SIMATIC Selection Tools , the TIA Selection Tool assembles the already known configurators for automation technology into a single tool.
With the TIA Selection Tool , you can generate a complete order list from your product selection or product configuration.
You can find the TIA Selection Tool on the Internet. (https://support.industry.siemens.com/cs/ww/en/view/109767888)

SINETPLAN See also

SINETPLAN, the Siemens Network Planner, supports you in planning automation systems and networks based on PROFINET. The tool facilitates professional and predictive dimensioning of your PROFINET installation as early as in the planning stage. In addition, SINETPLAN supports you during network optimization and helps you to exploit network resources optimally and to plan reserves. This helps to prevent problems in commissioning or failures during productive operation even in advance of a planned operation. This increases the availability of the production plant and helps improve operational safety.
The advantages at a glance
· Network optimization thanks to port-specific calculation of the network load
· Increased production availability thanks to online scan and verification of existing systems
· Transparency before commissioning through importing and simulation of existing STEP 7 projects
· Efficiency through securing existing investments in the long term and the optimal use of resources
You can find SINETPLAN on the Internet (https://new.siemens.com/global/en/products/automation/industrialcommunication/profinet/sinetplan.html).
PRONETA Professional (https://support.industry.siemens.com/cs/ww/en/view/109781283)

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Security information

Notes on Open Source Software
You can download and install various development tools of the Open Source project MinGW32 as a supplement to the product. Note that these components are optional and are provided and distributed by the MinGW32 project or other licensors under different licenses, which you can view on the project homepage or on the specific packages.

2.1

Cybersecurity information
Siemens provides products and solutions with industrial cybersecurity functions that support the secure operation of plants, systems, machines, and networks.
In order to protect plants, systems, machines, and networks against cyber threats, it is necessary to implement and continuously maintain a holistic, state-of-the-art industrial cybersecurity concept. Siemens’ products and solutions constitute one element of such a concept.
Customers are responsible for preventing unauthorized access to their plants, systems, machines and networks. Such systems, machines and components should only be connected to an enterprise network or the internet if and to the extent such a connection is necessary and only when appropriate security measures (e.g. firewalls and/or network segmentation) are in place.
For more information on protective industrial cybersecurity measures for implementation, please visit (https://www.siemens.com/global/en/products/automation/topic-areas/industrialcybersecurity.html).
Siemens’ products and solutions undergo continuous development to make them more secure. Siemens strongly recommends that product updates are applied as soon as they are available and that the latest product versions are used. Use of product versions that are no longer supported, and failure to apply the latest updates may increase customers’ exposure to cyber threats.
To stay informed about product updates at all times, subscribe to the Siemens Industrial Cybersecurity RSS Feed under (https://new.siemens.com/global/en/products/services/cert.html).

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Security information 2.2 Information about third-party software updates

2.2

Information about third-party software updates

This product contains third-party software. Siemens accepts liability with respect to updates/patches for the third-party software only when these are distributed by Siemens in the context of a Software Update Service contract or officially approved by Siemens. Otherwise, updates/patches are installed at the user’s own risk. You can find more information in our Software Update Service (http://w3.siemens.com/mcms/automationsoftware/en/software-update-service/Pages/Default.aspx).

2.3

Notes on protecting administrator accounts

A user with administrator rights has extensive access and manipulation possibilities.

Therefore, make sure that the administrator account is adequately protected to prevent unauthorized changes. To do this, set secure passwords and use a standard user account for regular operation. Other measures, such as the use of security policies, should be applied as required.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Product overview

3.1

Introduction to ODK 1500S

Overview

ODK is a development kit that allows you to program custom functions and generate files that STEP 7 can call directly.
ODK serves as a tool for:
· Windows environment
Execution on your Windows PC Use of resources of your Windows PC Use of operating system functions and system resources with access to external
hardware and software components
· Realtime environment
Execution on your CPU Synchronous function call (algorithmic, controllers) Calling multiple applications under Windows or in the realtime environment is possible.
You must use the CPU function libraries in the STEP 7 program.
You can use C/C++ runtime applications running in SIMATIC S7-1500 MFP C/C++ Runtime independently of the STEP 7 program.
With the PLCSIM Advanced function libraries, you can run a project in a simulated environment instead of on a hardware or software CPU.

Structure and design of an CPU function library
ODK supports the interface for calling custom high-level language programs from the controller program of the CPU.
ODK supports the following templates:
· Templates in different programming languages for Microsoft Visual Studio. This allows you to generate a DLL file. The C++, C# and Visual Basic programming languages are supported.
· A template for programming in Eclipse. This allows you to generate an SO file. ODK also supplies a class library for Eclipse. The C++ programming language is supported.
You can create a CPU function library for both the Windows and the real-time environment. The programming languages mentioned are available to you for this purpose.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Product overview 3.1 Introduction to ODK 1500S
You can run the ODK program in the following ways:
· Synchronous, i.e. executed as part of the CPU cycle (executed in the realtime environment).
· Asynchronous, i.e. started by the CPU program and ended in the background (executed in the Windows environment).
You can run CPU function libraries both under Windows (DLL) as well as in the real-time core of the CPU (SO). You call the functions of the DLL or SO file using instructions in the user program.
The CPU can perform functions in libraries that can be loaded dynamically. There are several functions possible in a CPU function library. Specific function blocks are available for a CPU function library:
· Loading and unloading of the CPU function library
· In each case, a specific function block for calling a function.
The following illustration provides a schematic overview of how CPU function libraries work and run on a PC. The illustration applies to the S7-1500 Software Controller.

Figure 3-1 Running a CPU function library on a PC

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Structure and design of a C/C++ runtime application

Product overview 3.1 Introduction to ODK 1500S

Figure 3-2 Overview of the performance segment
You can use C/C++ runtime applications to implement parallel processes to the STEP 7 user program, for example, for pre-processing or transmitting data via Industrial Ethernet. A CPU can perform several tasks at the same time. The complexity of functions is reduced and the time required for implementation is reduced.
You can reuse existing C/C++ algorithms. In order to continue using existing technological know-how, you can integrate the existing C/C++ code via the Open Development Kit as C/C++ runtime applications in the SIMATIC S7-1500 MFP C/C++ Runtime.
Once you integrate the C/C++ sources, you can execute them on the CPU.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Product overview 3.2 Development environments
The following options are available for communication between CPU Runtime and C/C++ Runtime: · On Open User Communication with the “TSTEND” and “TRCV” function blocks. · About the Communication protocol OPC UA.

Figure 3-3 Communication between CPU Runtime and C/C++ Runtime

3.2

Development environments

The following development environments for creating an ODK project are available for selection.

· Microsoft Visual Studio for CPU function libraries for the Windows environment (DLL file) and PLCSIM Advanced function libraries.

· Eclipse CPU function libraries for the realtime environment (SO file) and C/C++ runtime applications.

Microsoft Visual Studio as a development environment
Use Microsoft Visual Studio. To help you develop a CPU function library, a template for a Microsoft Visual Studio project is included in the installation of ODK 1500S. The ODK template can be found under the entry of the corresponding programming language when a new project is created.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Product overview 3.3 Basic procedure
Eclipse as a development environment
Use Eclipse. To help you develop a C/C++ runtime application, a template for an Eclipse project is included in the installation of ODK 1500S. The template can be found in the folder “ODK 1500S Templates”.

3.3

Basic procedure
The following sections describe the development tasks and procedures for the development and execution of a CPU function library/C/C++ runtime application: · Developing a CPU function library for the Windows environment (Page 28) · Developing a CPU function library for the realtime environment (Page 65) · Development of a C/C++ runtime application (Page 105) · Developing a PLCSIM Advanced function library (Page 120)

Figure 3-4 Overview of the development steps

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Product overview 3.3 Basic procedure

Overview of the development steps
To develop and execute a C/C++ runtime application/CPU function library, follow these steps: 1. Implement your function.
Implement your function for CPU function libraries in Visual Studio (DLL file) or Eclipse (SO file).
Implement your function for C/C++ runtime application in Eclipse. 2. Create the C/C++ runtime application, DLL or SO file and the SCL file. 3. Import the SCL file into STEP 7. 4. Write your user application in STEP 7. 5. Load the user program in the CPU and the C/C++ runtime application or DLL or SO file into
the target system.

Result

Your C/C++ runtime application/CPU function library is loaded in the target system. The CPU function library is loaded and executed by the user program in STEP 7.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Installation

4.1

System Requirements

Requirements
Your PC must meet the following system requirements in order to use the ODK:

Category Operating system
Processor and memory
Mass storage Operator interface SIMATIC software Additional software

Requirements
· Microsoft Windows 8.1, 64-bit · Microsoft Windows 10, 64-bit · Microsoft Windows 11, 64-bit Note: Installation on Windows 8.1 Before installing ODK 1500S with the Windows 8.1 operating system, ensure that the Windows Knowledge Base article “KB2919355” is installed on the PC. PC system: · At least systems with Intel Core i5 processor · 1.2 GHz or higher · At least 4 GB of RAM
Depending on the already installed components, you need up to 3 GB of free space on the hard disk C:. The exact amount of space required is displayed during the installation. Note: The setup files are deleted when the installation is complete. Color monitor, keyboard and mouse or another pointing device (optional) supported by Microsoft Windows
· SIMATIC STEP 7 Professional (TIA Portal) V15 or higher
Not included in the product package: · Java Runtime 32-bit as of V1.7 (for Eclipse) · Microsoft Visual Studio 2015 · Microsoft Visual Studio 2017 · Microsoft Visual Studio Community 2017 · Microsoft Visual Studio 2019 · Microsoft Visual Studio 2022 · Eclipse plugins (for MFP use) · SSH Client, for example PuTTY (for MFP use) · Microsoft Development Tool: Download Center (https://www.microsoft.com/en-
us/download/developer-tools.aspx)

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Installation 4.1 System Requirements

Note .NET version for the Windows environment
When creating a C# project, the target framework is set as “.NET 4.8” (e.g. “C# Console Application” under Visual Studio 2019/2022).
If you need a new .NET framework, ensure that a .NET version the target framework version set on the target device is installed.

ODK 1500S V2.5 SP4 is compatible with the following devices (support for loadable function libraries depends on the device):

CPU 1505SP (F/T/TF) as of V2.5 CPU 1507S (F) as of V2.5 CPU 1508S (F) as of V2.6 CPU 1518-4 PN/DP MFP (F) up to Firmware V2.6.1 CPU 1518-4 PN/DP MFP (F) Firmware V2.8 CPU 1518-4 PN/DP MFP (F) Firmware V2.9 PLCSIM Advanced as of V3.0

CPU function library DLL (Windows) Yes
No
no*

CPU function library SO (Real-time) Yes
Yes
Yes

C/C++ runtime application No Yes
No

* PLCSIM Advanced has its own function library type “PLCSIM Advanced Function Library DLL (Windows)”

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Installation 4.2 Installing ODK

4.2

Installing ODK

To install the ODK, insert the Installation DVD. Follow the instructions of the setup program.

If the setup program does not start automatically, open the “Start.exe” file on the Installation DVD manually with a double-click.

Requirements

You need administrator rights for this procedure.
It is possible to operate different ODK major versions (e.g. V2.0 and V2.5) on one PC at the same time.
It is not possible to operate the major version and service pack (e.g. V2.5 and V2.5.4) on one PC at the same time.

Note
Close applications before a repair installation/uninstall
Close all applications (especially ODK-related applications), before performing the repair installation/uninstall.

Note
Use of antivirus programs
To avoid problems during installation, disable the antivirus program during installation or close the directory “C:Program FilesCommon FilesSiemensAutomationSiemens Installer Assistant” as well as the directory in which the Start.exe of the antivirus program is located.

Procedure

If you want to use the Microsoft Visual Studio development environment, we recommend that you install this before ODK. To install ODK, follow these steps: 1. Start the “Start.exe” file from the Installation DVD manually with a double-click. 2. Select the language for performing the installation. 3. Confirm with “Next”.
If you want to upgrade an installed version V2.5, V2.5.1, V2.5.2 or V2.5.3 to V2.5.4, confirm with “Change”. 4. Click “Next” to confirm the list of components that are to be installed. The check mark for Automation License Manager (ALM) cannot be removed. 5. Follow the instructions of the installation wizard.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Installation 4.2 Installing ODK

6. Confirm the installation dialog with the “Install” button.
7. Choose whether you want to carry out the licensing (Page 25) during the installation or at a later time.

Result

The installation is complete. All product languages are installed by default during the installation process. The installation creates a shortcut in the Start menu of Windows.
Note Directory and workspace path for V2.5 SP4 The name of the directory and the path for the V2.5 workspace are retained after the update to V2.5 SP4. Example: C:Program Files (x86)SiemensAutomationODK1500SV2.5 C:Program DataSiemensAutomationODK1500SV2.5
The setup program installs the following components: · “Eclipse” development environment for the development of a CPU function library for the
realtime environment or a C/C++ runtime application · Project templates for Eclipse
C++ Project for CPU function library (CPU Runtime) C++ Project for MFP Linux application (CPU 1518 MFP – up to FW v2.6.1) C++ Project for MFP Linux application (CPU 1518 MFP FW v2.8) C++ Project for MFP Linux application (CPU 1518 MFP FW v2.9 or higher) · Project templates for Visual Studio For the Windows CPU function library For the PLCSIM function library · Tool to integrate Visual Studio templates · Installation script for MinGW32 · Code generator · Online help · HelpStarter tool · Automation License Manager, if this is out of date or was not yet installed · Certificate of license (Certificate of License)

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Installation 4.3 Licensing ODK 1500S
Note Eclipse workspace folder If you have installed ODK and the Software Controller on the same IPC, move the Eclipse Workspace from the path “%ProgramData%SiemensAutomationODK1500SV2.5” to, for example, “C:ODK1500S_V2.5_Workspace”.

4.3

Licensing ODK 1500S
To create CPU function libraries, the software requires a product-specific license key that you install with the Automation License Manager. Each SIMATIC software product for automation that is subject to license (e.g., STEP 7) has its own license key. You must install the license key for each product.

Working with the Automation License Manager
The Automation License Manager is a product of Siemens AG and is used for managing license keys. The Automation License Manager is supplied on the installation data medium of this product by default and is transferred automatically during the installation process.
Software products that require license keys for operation register the requirement for license keys automatically in the Automation License Manager. If the Automation License Manager finds a valid license key for this software, the software can be used according to the conditions of use associated with this license key.

Certificate of license
A Certificate of License is included in the scope of delivery. It contains your unique license number. The license certificate serves as proof that you have a valid license key. Store this certificate in a safe place.
Note Obtaining a replacement license key You must have a valid certificate of license to get a replacement license key.

Recovering the license key in case of defective mass storage
If a error has occurred on the mass storage or USB flash drive containing your license key file, contact your Siemens representative (https://support.industry.siemens.com/cs/ww/en/). Make sure you have your certificate of license available for this.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Installation 4.3 Licensing ODK 1500S

License key

The license key for ODK 1500S is located on a USB flash drive that is included in the scope of delivery.
If the USB flash drive containing the license key is lost or damaged, you can contact Support (https://support.industry.siemens.com/cs/ww/en/) to obtain a new license key. You need the certificate of license to receive a replacement license key from Siemens.
Handling of license key for download version of ODK 1500S
The download of ODK 1500S allows you to access ordered license keys.
For access, you need:
· A personalized login that you can use to fetch all license keys assigned to “your company”.
· An anonymous login that you can use to fetch an individual license key, and the corresponding license certificate. This document contains all data required for the anonymous download.
Additional information on the license key and the download is available in the Automation License Manager manual (https://support.industry.siemens.com/cs/ww/en/view/102770153).

Transferring the license key
The license key can be transferred during the installation or afterwards.
If the USB flash drive with the relevant license key is inserted in the USB port of the PC at the start of installation, the license key will be transferred automatically during the installation. If the USB flash drive is not inserted at the start of installation, you have three options for installing the license key subsequently:
· To transfer the license key manually from a network computer or other storage medium, select the “Manual license transfer” button.
· Insert the USB flash drive with license key, and select the “Retry license transfer” button. The Automation License Manager opens in order to transfer the license key.
· If you do not want to install a license key, select the “Skip license transfer” button.

Note Working without license key
For legal reasons, a valid license key is required for this product.
If no valid license key is present on your PC, you cannot generate any projects. An error message will inform you at regular intervals that no valid license key is present.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Installation 4.4 Subsequently integrating project template for Windows CPU function libraries in Visual Studio
Manually transferring the license key subsequently
A message is displayed if you generate a project for a CPU function library without transferred license key. To manually transfer the license key for ODK subsequently, follow these steps: 1. Start the installation of ODK 1500S with administrator rights. 2. In the “License Transfer” section, select the “Manual license transfer” button.
A dialog box for synchronization of the license opens. 3. Select the destination and the source of the license key. 4. To transfer the license key, click the “Synchronize” button.
The license key is transferred.

4.4
Result

Subsequently integrating project template for Windows CPU function libraries in Visual Studio
When Visual Studio is already installed, the project template for Windows CPU function libraries is automatically installed during the ODK installation. If Visual Studio is installed later, you have the following options to integrate the project template for Windows CPU function libraries: · Perform a repair installation of ODK. · Run the integration manually. Call your ODK installation file
“ODK_VSTemplate_Integration.exe” in the “bin” folder.
The project templates for Windows CPU function libraries is installed for Visual Studio. You can find this under the corresponding programming language.

4.5

Uninstalling ODK

Procedure Result

To remove ODK from your PC, follow these steps: 1. Close all running programs, especially ODK-related applications. 2. Select the menu “Control Panel > Programs and Features”, select the entry “SIMATIC ODK
1500S” and click “Uninstall”. 3. Select the “Uninstall” command in the shortcut menu.
A dialog box for uninstalling appears. 4. Follow the steps for uninstalling.
ODK is removed.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment

5.1

Creating a CPU function library

5.1.1

Requirements
The Microsoft Visual Studio development environment is not included in the scope of delivery of ODK.
You can find the Download Center for Microsoft development tools in the Internet (https://www.microsoft.com/en-us/download/developer-tools.aspx).

5.1.2

Creating a project
To help you develop a CPU function library, a project template for CPU function libraries for a project in Visual Studio is included in the installation of ODK 1500S. The template supports 32-bit and 64-bit applications.

Procedure

To create a project in Microsoft Visual Studio using the project template, follow these steps: 1. Open Microsoft Visual Studio as a development environment. 2. In the “File > New” menu, select the command “Project…”
The “New Project” dialog opens.

Figure 5-1 Creating a new project in Visual Studio
3. Select your preferred programming language and the corresponding project template (C++, C# or VB).
4. Enter a project name. 5. Click “OK” to confirm.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

Result

The CPU function library is created using the project template and sets the following project settings: · Project settings for generating the DLL file · Automates the generation of the DLL and SCL file The project template set ups various structures depending on the programming language: · C++ project (Page 29) · C# project (Page 32) · VB Project (Page 33)

5.1.2.1

Solution Explorer structure: C++ project

Folder / file <project> Definition File

<project>.odk <project>.scl.additional

Generated Files
Header Files ODK Helpers

ODK_Types.h ODK_Functions.h ODK_Execution.cpp
ODK_CpuReadData.h ODK_CpuReadData.cpp ODK_CpuReadWriteData.h

Resource Files Source Files
STEP7

ODK_CpuReadWriteData.cpp ODK_StringHelper.h ODK_StringHelper.cpp
<project>.rc
<project>.cpp dllmain.cpp
<project>.scl

Description
ODK interface description S7 blocks that are appended to the <project>.scl file. Although the file is not part of the project template, the code generator processes the file. Files from this folder may not be edited! Definition of the ODK base types Function prototypes Implementation of the “Execute” method Header file Files from this folder may not be edited! Definition: Help functions for reading the data blocks Implementation: Help functions for reading the data blocks Definition: Help functions for reading/writing the data blocks Implementation: Help functions for reading/writing the data blocks Definition: Help functions S7 strings / W strings Implementation: Help functions S7 strings / W strings
Source Files Function code Implementation of the “dllmain” file Files from this folder may not be edited! S7 blocks

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

The C++ Native project template supports the following applications:

Configuration and platform Debug Win32 Release Win32 Debug x64 Release x64

Visual Studio Version older than 2015 Yes Yes To be created manually To be created manually

Visual Studio 2015 and later Yes Yes Yes Yes

Note
Configuration of C/C++ Redistributables
Since the software controller contains the C/C++ redistributables for the release configuration, build the CPU function library with the configuration “Release”.
To use the “Debug” configuration, add the redistributables for the debug configuration on the target system.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library
Creating a CPU function library for x64 platform with Visual Studio version older than 2015
To create a project template for an x64 platform with a Visual Studio version older than 2015, proceed as follows: 1. Open the “Configuration Manager”.
2. Create an x64 platform.
The “New Solution Platform” dialog opens.
Select “Win32” from the drop-down list box “Copy settings from:” .

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library
3. Define a solution configuration for an x64 platform.

4. Select “Debug” or “Release” from the drop-down list box “Active solution configuration” and “x64” from the drop-down list box “Platform”.

5.1.2.2

Solution Explorer structure: C# project

Directory / file <project> Properties Definition File
Generated Files
ODK Helpers
Source STEP7

AssemblyInfo.cs
<project>.odk <project>.scl.additional
OdkTypes.cs OdkFunctions.cs OdkExecution.cs
OdkReadVariant.cs OdkReadWriteVariant.cs
<project>.cs
<project>.scl

Description
ODK interface description S7 blocks that are appended to the <project>.scl file. The file is not part of the project template, but the code generator processes the file. Files from this folder may not be edited! Definition of the ODK base types Function prototypes Implementation of the “Execute” method Files from this folder may not be edited! Help functions for reading the data blocks Help functions for reading/writing the data blocks Source Files Function code Files from this folder may not be edited! S7 blocks

The C++ project template supports the following applications:

Configuration and platform Debug each CPU Release each CPU

Visual Studio Version older than 2015 Visual Studio 2015 and later

Not supported

Yes

Not supported

Yes

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

5.1.2.3

Solution Explorer structure: VB Project

Directory / file <project path> My Project Definition File
Generated Files
ODK Helpers
Source STEP7

AssemblyInfo.vb
<project>.odk <project>.scl.additional
OdkTypes.vb OdkFunctions.vb OdkExecution.vb
OdkReadVariant.vb OdkReadWriteVariant.vb
<project>.vb
<project>.scl <project>.vb

The VB project template supports the following applications:

Configuration and platform Debug each CPU Release each CPU

Visual Studio Version older than 2015 Visual Studio 2015 and later

Not supported

Yes

Not supported

Yes

5.1.3

Generating a CPU function library
The generation of the project data is divided into two automated steps.
· Pre-Build: Generation of the files created by default based on the changed <project>.odk file and generation of the SCL file.
· Actual-Build: Generation of the DLL file.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

Procedure

To generate the project data, follow these steps: 1. Save all edited files. 2. In the “Build” menu, select the command “Build Solution”.
Note C/C++ projects Perform the build of the CPU function library in the “Release” configuration, as the software controller has already installed the C/C++ Redistributables (Release Runtime files). To use the “Debug” configuration, copy the Debug Runtime files to the software controller.

Note The project data is only generated if the files have been changed.

Result

The generation of the project data is started. The automatically generated files are stored in the file system.
· DLL file: Project directory<project><BuildConfiguration><project>.dll
· SCL file: Project directory<project>STEP7<project>.scl

5.1.4

Defining the runtime properties of a CPU function library
The next step is to define the interface description of the CPU function library in the <project>.odk file. The file contains the following elements: · Comments · Parameters · Definitions of functions and structures

Procedure

To define the interface description in the <project>.odk file, follow these steps: 1. Open the <project>.odk file. 2. Change the elements depending on your requirements.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

Description of the elements
Comments You can use comments for explanation purposes.
Parameters The definition of the parameters must be within a line of code. <parameter name>=<value> // optional comment The interfaces file supports the following parameters:

Parameter Context
STEP7Prefix

Value user
system
<String>

FullClassName

Description Specifies that the CPU function library is loaded in the context of a Windows user (Page 35). Specifies that the CPU function library is loaded in the context of the Windows system (Page 35). Describes the string that precedes your functions and is shown after importing the SCL file in STEP 7. The following characters are allowed: {A…Z, a…z, 1…9, -, _} Umlauts are not permitted. The project name is entered without spaces by default. The parameter is required for the C# and VB programming languages. To change the class names or namespace of the source files of the CPU function library, you need to adjust the “FullClassName” parameter.

Note Spaces in the project name With the STEP7 prefix, invalid characters are replaced by an underscore.

5.1.5

Environment for loading or executing the CPU function library
When the SCL file is imported into STEP 7 as an external source, the ODK instructions are created in the selected directory in STEP 7. The ODK instructions enable you to control your CPU function library regardless of the STEP 7 user program after programming and the initial loading. You can load up to 32 CPU function libraries.
Depending on whether you have created the CPU function library for a 32-bit, 64-bit system or with the “Any CPU” option, this is loaded into a 32-bit or 64-bit ODK host process.
You can choose one of two contexts for your CPU function library:
· “System” context
Windows is started, a user can be logged on
· “User” context
Windows is started, a user must be logged on

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library
The following graphic shows you when a CPU function library may be loaded depending on the context.

“System” context
Change the following line of code in your <project>.odk file to use the CPU function library in the system context (Session 0): Context=system
In the system context, the CPU function library is running without the logon of a Windows user. This means the CPU function library cannot be actively controlled with user interface elements such as message dialogs.

“User” context

Change the following line of code in the <project>.odk file to use the CPU function library in the user context: Context=user
When you load the CPU function library in the user context, it automatically unloads as soon as the user logs off in Windows. The CPU function library can be actively controlled by Windows user interface elements such as message dialogs and provides access to additional resources of the Windows environment.
If multiple users are logged on to Windows, the CPU function library loads or unloads for the user, who has the current screen rights until he logs off in Windows.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

5.1.6

Defining functions and structures of a CPU function library

Functions

Functions are defined by the following general lines of code: ODK_RESULT <FunctionName> ([<InOut identifier>] <data type> <tag name>, etc.);
The <project>.odk file is the ODK interface description for CPU function libraries. This is available for all supported programming languages.
The <project>.odk file contains an example function description by default. You can change this description and/or add more function descriptions. ODK_RESULT MyFunc1([IN] INT param1, [OUT] INT param2);

Syntax rules for functions
The following syntax rules apply to functions within the <project>.odk file: · Note that the function names are case-sensitive. · You can split function definitions into several lines. · End a function definition with a semicolon. · TAB and SPACE are allowed. · Do not define a tag name in a function twice. · Do not use any keywords for the programming language that is used (for example
“EN / ENO” as parameter name) · Use ODK_RESULT only for the return values of the function. · The tag name must start with a letter or an underscore. · Illegal function names are displayed during generation in the development environment. · The following names are not allowed in combination of <STEP 7Prefix> and <function
name>: ODK_Load, ODK_Unld, ODK_ExcA, ODK_ExcS
<FunctionName> Function names are valid with the syntax and character restrictions of the used programming language.
<InOut-Identifier> There are three defined InOut-Identifiers. Use these in the following order: [IN], [OUT], [INOUT] · [IN]: Specifies an input tag. The tag is copied to the function when it is called. This is
constant and cannot be changed. · [OUT]: Specifies an output tag. The tag is copied back after the function has been
completed. · [INOUT]: Specifies an input and output tag. The tag is copied to the function when it is
called. This is not constant and can be changed. The tag is copied back after the function has been completed.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

<DataType>
The data type defines the type of a tag. The following table defines the possible data types and their representation in the individual programming languages or STEP 7:
Elementary data types:

ODK data type ODK_DOUBLE

SIMATIC data type LREAL

C++ data type double

C# data type double

ODK_FLOAT

REAL

float

ODK_INT64 ODK_INT32 ODK_INT16 ODK_INT8 ODK_UINT64 ODK_UINT32 ODK_UINT16 ODK_UINT8 ODK_LWORD ODK_DWORD ODK_WORD ODK_BYTE ODK_BOOL

LINT DINT INT SINT ULINT UDINT UINT USINT LWORD DWORD WORD BYTE BOOL

long long long short char unsigned long long unsigned long unsigned short unsigned char unsigned long long unsigned long unsigned short unsigned char unsigned char

long int short sbyte ulong uint ushort byte ulong uint ushort byte bool

ODK_LTIME

LTIME

long long

long

ODK_TIME ODK_LDT

TIME LDT

long

int

unsigned long long ulong

ODK_LTOD
ODK_TOD
ODK_WCHAR ODK_CHAR

LTOD
TOD
WCHAR CHAR

unsigned long long ulong

unsigned long

uint

wchar_t char

char sbyte

VB data type
Double
Single
Long Integer Short SByte ULong UInteger UShort Byte ULong UInteger UShort Byte Boolean
Long
Integer ULong
ULong
UInteger
Char SByte

Description
64-bit floating point, IEEE 754 32-bit floating point, IEEE 754 64-bit signed integer 32-bit signed integer 16-bit signed integer 8-bit signed integer 64-bit unsigned integer 32-bit unsigned integer 16-bit unsigned integer 8-bit unsigned integer 64-bit bit string 32-bit bit string 16-bit bit string 8-bit bit string 1-bit bit string, remaining bits (1..7) are empty 64-bit during in nanoseconds 32-bit during in milliseconds 64-bit date and time of the day in nanoseconds since 01/01/1970 00:00 64-bit time of the day in nanoseconds since midnight 32-bit time of the day in milliseconds since midnight 16-bit character 8-bit character

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

Complex data types:

ODK data type ODK_DTL

SIMATIC data type DTL

C++ data type struct ODK_DTL

ODK_S7WSTRIN WSTRING G

unsigned short

C# data type VB data type Description

OdkInternal. Dtl (class) string

OdkInternal. Dtl (class) String

Structure for date and time
Character string: · For SIMATIC and C++:

16-bit character with length max. and act. (4xUSINT)
· For other languages:

ODK_S7STRING STRING

unsigned char

string

String

native Character string:
· For SIMATIC and C++:

8-bit character with length max. and act. (2xUSINT)
· For other languages:

ODK_VARIANT VARIANT

[ ]

ARRAY

struct ODK_VARIANT byte [ ] [ ] [ ]

byte [ ] [ ]

native Classic data (each data type that can be serialized with classic data.) Range of same data types. You can use all data types as array except IN_DATA / INOUT_DATA / OUT_DATA.

User-defined data types:
User-defined data types (UDT) include structured data, especially the names and data types of this component and their order.
A user-defined data type can be defined in the ODK interface description with the keyword “ODK_STRUCT”.

Example

ODK_STRUCT <StructName>

{

<DataType> <TagName>;

…

}; The following syntax rules apply to the structure: · You can divide the structure into multiple lines. · The structure definition must end with a semicolon.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library
· Any number of tabs and spaces between the elements is permitted. · It is not permitted to use any keywords for the generated language used (for example
“en / eno” as tag name). You can create additional structures within a structure.
<StructName> Structure names are valid with the syntax and character restrictions of the programming language and as defined for tag definitions in STEP 7. In STEP 7, the structure name is extended with the STEP 7 prefix.
<TagName> Tag names are subject to the syntax and character restrictions of the programming language.
Example The following code example explains the definitions of functions and structures. Sort the parameters by: IN, OUT, INOUT. //INTERFACE … ODK_STRUCT MyStruct
{ ODK_DWORD myDword; ODK_S7STRING myString;
}; ODK_RESULT MyFct([IN] MyStruct myInStruct
,[OUT] MyStruct myOutStruct);

5.1.6.1
40

Using ODK_VARIANT as parameter
Restrictions of the data type ODK_VARIANT:
· When a parameter of the data type ODK_VARIANT is used, it is not permitted to use other parameters with the same InOut-Identifier, regardless of data type.
· With the data type ODK_VARIANT, an [OUT] is modeled as [INOUT] in the generated FB.
Example // INTERFACE … // OK: ODK_RESULT MyFunc1([IN] ODK_VARIANT myClassicData); ODK_RESULT MyFunc2([IN] ODK_VARIANT myDataIn
, [OUT] ODK_VARIANT myDataOut , [INOUT] ODK_VARIANT myDataInout); // // NOT OK (Code Generator will throw an error): // If ODK_VARIANT is used for [IN], no other [IN] parameter // may be defined in this function ODK_RESULT MyFunc4([IN] ODK_VARIANT myClassicData
Open Development Kit 1500S V2.5 SP4 Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library
, [IN] ODK_INT32 myint);
Application example for C++ #include “ODK_CpuReadData.h” … ODK_RESULT MyFunc1 (const ODK_VARIANT& myClassicData) {
CODK_CpuReadData myReader(myClassicData); ODK_INT32 myInt1, myInt2; myReader.ReadS7DINT(0, myInt1); myReader.ReadS7DINT(4, myInt2); return myInt1 + myInt2; } Helper functions (Page 139) of the following classes are available to help you access the data type ODK_VARIANT inside a user function: · Class “CODK_CpuReadData” · Class “CODK_CpuReadWriteData”
Note Size of the ODK_VARIANT tags The size of the ODK_VARIANT tags is not known at the time of compiling and is therefore not checked during the compiling process. When selecting the other parameters, consider the possible size of the ODK_VARIANT parameter in your application.

5.1.6.2

Handling strings
You can define a maximum length for strings (String or WString). Define the maximum number of characters in square brackets directly after the data type:
· ODK_S7STRING[30] or
· ODK_S7WSTRING[1000] Without limitation, a string has a default length of 254 characters.
In order to access the data types ODK_S7STRING or ODK_S7WSTRING within a user function, the string helper functions (Page 139) are available:

Example

//INTERFACE … ODK_RESULT MyFct(
[IN] ODK_S7STRING , [OUT] ODK_S7STRING[10] , [INOUT] ODK_S7STRING[20]

myStrHas254Chars myStrHas10Chars myStrArrayHas20Chars5Times[5]);

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library
If you use [INOUT], you can set the string with a length that differs from the [INOUT of the function block in STEP 7.
Note Compatibility If you use the “WSTRING” data type with more than 253 characters in a project, create a new project with ODK version V2.5 SP1. The characters are not read/written correctly with a project created with ODK version < V2.5 SP1.

5.1.6.3

Definition of the <Project>.odk file
The function prototypes and function blocks are generated based on the selected parameters in the <project>.odk file. Define the <project>.odk file for this.
By default, the <project>.odk file contains the following:
· Description
The possible data types that are used for the interface are described in comment lines. This simplifies the definition of the correct tag type for your task.
· Context=user
The CPU function library is loaded in the “User” context. You can change the parameter to Context=system.
· STEP7Prefix=”<project>”
Sets a string for the SCL generation in front of the functions of the CPU function library. The string is visible in STEP 7. You can change the parameter. The string length of the prefix including the function name must not exceed a length of 125 characters (for example, ODK_App_SampleFunction)
· “SampleFunction” function definition
You can change this default function as you wish in the <project>.odk file and add more functions. The string length may not exceed a length of 125 characters. The associated function is located in the CPP file.
FullClassName=”<OdkProject1.Source.CpuFunctionLibrary>”
The parameter is required for the C# and VB programming languages.
To change the class names or namespace of the source files of the CPU function library, you need to adjust the “FullClassName” parameter.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

Example //INTERFACE Context=user STEP7Prefix=ODKProject FullClassName=ODKProject.Source.CpuFunctionLibrary

* Elementary data types:

* ODK_DOUBLE

LREAL 64-bit floating point, IEEE 754

* ODK_FLOAT

REAL

32-bit floating point, IEEE 754

* ODK_INT64

LINT

64-bit signed integer

* ODK_INT32

DINT

32-bit signed integer

* ODK_INT16

INT

16-bit signed integer

* ODK_INT8

SINT

8-bit signed integer

* ODK_UINT64

ULINT 64-bit unsigned integer

* ODK_UINT32

UDINT 32-bit unsigned integer

* ODK_UINT16

UINT

16-bit unsigned integer

* ODK_UINT8

USINT 8-bit unsigned integer

* ODK_LWORD

LWORD 64-bit bit string

* ODK_DWORD

DWORD 32-bit bit string

* ODK_WORD

WORD

16-bit bit string

* ODK_BYTE

BYTE

8-bit bit string

* ODK_BOOL

BOOL

1-bit bit string

* ODK_LTIME

LTIME 64-bit duration in nanoseconds

* ODK_TIME

TIME

32-bit duration in milliseconds

* ODK_LDT

LDT

64 bit date and time of day

in nanoseconds

* ODK_LTOD

LTOD

64 bit time of day in nanoseconds

since midnight

* ODK_TOD

TOD

32 bit time of day in milliseconds

since midnight

* ODK_CHAR

CHAR

8 bit character

* ODK_WCHAR

WCHAR 16 bit character

* Complex Datatypes:

* ODK_DTL

DTL

structure for date and time

* ODK_S7STRING STRING character string with 8-bit characters

* ODK_VARIANT

VARIANT classic data (any datatype which can be

serialized

to classic data)

* ODK_S7WSTRING WSTRING character string with 16 bit characters

* []

ARRAY field of this datatype

* User Defined Datatype:

* ODK_STRUCT

UDT

user defined structure

* Return Datatype:

* ODK_RESULT

0x0000-0x6FFF function succeeded

(ODK_SUCCESS = 0x0000)

0xF000-0xFFFF function failed

(ODK_USER_ERROR_BASE = 0xF000)

// Basic function in order to show // how to create a function in ODK 1500S. ODK_RESULT SampleFunction([IN] ODK_INT32
, [OUT] ODK_BOOL

myInt // integervalue // as input
myBool // bool value

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

// as output , [INOUT] ODK_DOUBLE myReal);// double value
// as input // and output

5.1.6.4

Modifying the <Project>.odk file
The following examples show you how you can change the <project>.odk file to suit your needs. //INTERFACE Context=user STEP7Prefix=ODK_SampleApp_

ODK_RESULT GetString ([OUT] ODK_S7STRING myString);

ODK_RESULT Calculate ([IN] [IN] [OUT] [OUT] [INOUT] [INOUT]

ODK_INT64 ODK_DOUBLE ODK_FLOAT ODK_INT32 ODK_BYTE ODK_BYTE

In1, In2, Out1, Out2, InOut1[64], InOut2[64]);

Function prototypes in the ODK file

Example for C++ ODK_RESULT GetString (
/*OUT*/ ODK_S7STRING myString[256]); #define _ODK_FUNCTION_GETSTRING ODK_RESULT GetString (/*OUT*/ ODK_S7STRING myString[256])

ODK_RESULT Calculate (

/*IN*/

const ODK_INT64& In1,

/*IN*/

const ODK_DOUBLE& In2,

/*OUT*/ ODK_FLOAT& Out1,

/*OUT*/ ODK_INT32& Out2,

/*INOUT*/ ODK_BYTE InOut1[64],

/*INOUT*/ ODK_BYTE InOut2[64]);

#define ODK_FUNCTION_CALCULATE ODK_RESULT Calculate(/*IN*/ const

ODK_INT64& In1,/*IN*/ 2480 const ODK_DOUBLE& In2,/*OUT*/ ODK_FLOAT&

Out1,/*OUT*/ ODK_INT32& Out2,/*INOUT*/ ODK_BYTE2481

InOut1[64],/*INOUT*/ ODK_BYTE InOut2[64])

#endif // ODK_FUNCTIONS_H

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

Example for C# namespace OdkInternal {
interface IOdkFunctions {
// declaration of the callback methods ushort OnLoad(); ushort OnUnload(); ushort OnRun(); ushort OnStop();

ushort GetString( /*OUT*/ out string myString);

ushort Calculate( /*IN*/ ref long In1, /*IN*/ ref double In2, /*OUT*/ out float Out1, /*OUT*/ out int Out2, /*INOUT*/ ref byte[] InOut1, /*INOUT*/ ref byte[] InOut2);
} }

Example for VB Namespace Global.OdkInternal
Public Interface IOdkFunctions // declaration of the callback methods Function OnLoad() As UShort Function OnUnload () As UShort Function OnRun () As UShort Function OnStop () As UShort

Function GetString(

ByRef myString As String `OUT

) As UShort

Function Calculate(

ByRef In1 As Long,

`IN

ByRef In2 As Double,

`IN

ByRef Out1 As Float,

`OUT

ByRef Out2 As Integer, `OUT

ByRef InOut1() As Byte, `INOUT

ByRef InOut2() As Byte `INOUT

) As UShort

End Interface

End Namespace

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

5.1.6.5

Comments
The following examples for using comments are valid for C++ and C#. Differences to Visual Basic are available under “Comments in Visual Basic (Page 47)”
Comments are started with a double slash “//” and end automatically at the end of the line.
Alternatively, you can limit comments by /* <comment> */, which enables new lines in a comment. Characters after the end of the comment identifier “*/” are further processed by the code generator.

Comments for functions and structures
You place comments on functions and structures directly in front of the functions/structures. These comments are transferred to the ODK_Functions.h/.cs/.vb and <project>.scl files. In the <project>.scl file, the comments are copied to the block properties and duplicated in the code area of the function. Observe the following rules: · Comments for functions and structures must be located directly in front of the
functions/structures (without blank line). · The end of the comment is located in front of the ODK_RESULT or ODK_STRUCT keyword. · You can use both identifiers “//” and “/* */” but not in combination within a comment.

Example // this comment did not appear in MyStruct, because of the empty line.

// comment MyStruct

// …

ODK_STRUCT MyStruct

{

ODK_DWORD

myDword;

ODK_S7STRING myString;

};

/* comment MyFct … */ ODK_RESULT MyFct([IN] MyStruct myInStruct
,[OUT] MyStruct myOutStruct);

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

Comments for tags in functions and structures
Comments for function and structure tags are placed directly in front of or behind the tag. These comments are transferred to the ODK_Functions.h/ and <project>.scl files. The following rules apply to comments in front of tags: · Comments must be directly in front of the tag (without blank line). · The end of the comment is the <InOut-Identifier> of the tags. The following rules apply to comments after tags: · Comments must be after the tag name (without blank line). The following general rules apply to comments for tags: · You can use both identifiers “//” and “/* */” but not in combination within a comment. · In the header file, the same comment identifier is used (“//” or “/* */”).
Example ODK_STRUCT MyStruct {
// comment myDword BEFORE definition ODK_DWORD myDword;
ODK_S7STRING myString; /* comment myString AFTER definition */ };
ODK_RESULT MyFct([IN] MyStruct myInStruct // comment // myInStruct … // … “second line”
, [OUT] MyStruct myOutStruct); /* comment myOutStruct … …
*/

5.1.6.6

Comments in Visual Basic
Not all comments can be transferred unchanged from the Interface file to the VB source. The following rules are valid only for comments in Visual Basic: · Comments are marked with a apostrophe. · To mark multiple lines as comment, you need to set an apostrophe before each line.
Example:

<project>.odk
/* Multi line comment 1 comment 2 comment 3*/
ODK_RESULT f1();

ODK_Functions.vb
` This file is AUTO GENERATED … ` <automatically generated comment> … ` Multi line comment 1 ` comment 2 ` comment 3 Function f1() As UShort

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

· Comments are not permitted in front of source code. Set the InOut identifier after the function parameter. Example:

<project>.odk ODK_RESULT f1([IN] ODK_BYTE b);

ODK_Functions.vb
Function f1( b As Byte ` [IN] ) As UShort

· Multi-line comments are not permitted between function parameters.

Set multiple comments in a line.

Example:

<project>.odk
ODK_RESULT f1( // c1 // c2 [IN] ODK_BYTE b // c3 // c4 );

ODK_Functions.vb
Function f1( b As Byte ` [IN] c1` c2` c3` c4
) As UShort

5.1.7 5.1.7.1

Implementing functions
General notes
This section provides an overview of the basic topics relating to the implementation of functions in a Windows environment. · The function call is not limited in time, because the function is called asynchronously. · Traces are possible via OutputDebugString instructions · All asynchronous functions are executed with equal priority – regardless of the priority of
the OBs · The complete Windows API (Application Programming Interface) and C++-Runtime library
are available

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

5.1.7.2

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

Callback functions
The project template includes an execute file to define your functions.

Programming language C++ C# VB

Name of the execute file <project>.cpp <project>.cs <project>.vb

This execute file contains functions filled by default. This file does not necessarily need to be filled with additional user code to be usable. However, neither may the functions be deleted under any circumstances.

The empty function has the following code (using the “OnLoad()” function as an example):

You can define the following functions in the execute file:

· OnLoad(): Called after loading the CPU function library

· OnUnload(): Called before unloading the CPU function library

· OnRun(): Called when the CPU changes to RUN mode after the OnLoad() function

· OnStop(): Called when the CPU changes to the STOP mode and before the function OnUnload()

The following table provides an overview of the various actions to invoke the callback functions:

Current operating state New operating state

RUN

STOP

RUN

RUN STOP RUN

STOP RUN RUN

RUN

SHUTDOWN / MRES

any

User action ODK_Load
ODK_Load in startup OB (e.g. OB100) <already loaded> <already loaded> ODK_Unload
<already loaded> <already loaded> Exit ODK host

ODK action 1. OnLoad() 2. OnRun()
1. OnLoad() 2. OnRun()
OnStop() OnRun() 1. OnStop() 2. OnUnload() OnStop() 1. OnStop() (optional, if
not already executed) 2. OnUnload()

“OnLoad()” and “OnUnload()” function
The functions have a return value of type “ODK_RESULT” and typically provide information about the status of the “ODK_SUCCESS” value.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.1 Creating a CPU function library

The following return values are possible:

Return value for “ODK_RESULT” ODK_SUCCESS = 0x0000
0x0001 0xEFFF 0xF000 0xFFFF ODK_USER_ERROR_BASE = 0xF000

Description Return value following a successful execution of the “OnLoad()” or “OnUnload()” function Invalid values (system-internal) You can define your own error values. The loading stops and the CPU function library unloads for the “OnLoad()” function. The CPU function library within the specified value range is still unloaded for the “OnUnload()” function.

“OnRun()” and “OnStop()” function
The functions have a return value of type “ODK_RESULT” and typically provide information about the status of the “ODK_SUCCESS” value.
The following return values are possible:

Return value for “ODK_RESULT” ODK_SUCCESS = 0x0000
0x0001 0xFFFF

Description Return value following a successful execution of the “OnRun()” or “OnStop()” function No direct feedback to the user program is possible. The return value is sent to Windows (WindowsEventLog).

5.1.7.3

Implementing custom functions
Once you have defined the ODK interface in the <project>.odk file, you must edit the functions of the CPU function library in the Project Source file.

Procedure

To edit the function of a CPU function library, follow these steps: 1. To generate the function prototypes, execute the build. 2. Open the project source file, or create a custom source file if necessary. 3. Transfer the function prototypes from <ODK_Functions.h>/<OdkFunctions.cs/vb> to the source file.
Note Use the function prototype macro to transfer the step 3 in the future when there is a change to the function parameters.
4. Edit the code of your CPU function library in the execute file.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment
5.2 Transferring a CPU function library to the target system
CPU function library
The execute file contains a schematically represented function description by default. You can change this description with corresponding changes in the <project>.odk file and/or add more function descriptions.
Execute file based on C++ example #include “ODK_Functions.h”
EXPORT_API ODK_RESULT OnLoad (void) {
return ODK_SUCCESS; } EXPORT_API ODK_RESULT OnUnload (void) {
return ODK_SUCCESS; } EXPORT_API ODK_RESULT OnRun (void) {
return ODK_SUCCESS; } EXPORT_API ODK_RESULT OnStop (void) {
return ODK_SUCCESS; } ODK_RESULT SampleFunction( const ODK_INT32& myInt,
ODK_BOOL& myBool, ODK_DOUBLE& myReal) { return ODK_SUCCESS; }

5.2

Transferring a CPU function library to the target system

Manually transfer the DLL file to a specific Windows folder on the target system (e.g. via a network share or USB flash drive). Use the standard Windows data transfer procedure to transfer of the CPU function library. The storage location in Windows is specified by a registry key. When loading an CPU function library, the ODK service automatically searches for the file in the path specified by the registry key.

Note
CPU function library in the debug configuration
When the CPU function library has been transferred to the debug configuration, you also need to transfer the debug DLLs of the development environment to the target system.

The default value that describes the file path is:

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.3 Importing and generating an SCL file in STEP 7
%ProgramData%SiemensAutomationODK1500S
Note Administrator rights Assign write permission to this folder only for the administrator. This prevents unauthorized personnel from uploading CPU function libraries. Please note: The setup of the SIMATIC S7-1500 Software Controller checks whether the file path already exists and the required administrator rights are assigned. If not, the directory is renamed to “ODK1500S_OLD1” or “ODK1500S_OLD2” and a new directory with the correct access rights is created.
The Windows file system can hide the folder based on your setting. You can view the folder using the Windows option “Show hidden files, folders, and drives”. The registry key for 32-bit systems is: HKEY_LOCAL_MACHINESOFTWARESiemensAutomationODK1500Sodk_app_path The registry key for 64-bit systems is: HKEY_LOCAL_MACHINESOFTWAREWow6432NodeSiemensAutomationODK1500Sodk_ap p_path You can change the default value of the registry key and thus adapt to the expected location for the DLL file to suit your needs.
Note Changing the path in the registry key To protect the DLL file, select a storage location that is secured by access protection.

5.3

Importing and generating an SCL file in STEP 7

The following files are created when the project map is created:

· SCL file for importing into STEP 7

· All files depending on the configuration, e.g. DLL file

If STEP 7 is installed on another PC as the development environment, you must transfer the generated SCL file to the PC where the STEP 7 is installed.

Requirements
The project data were generated.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Procedure Result

Developing a CPU function library for the Windows environment 5.3 Importing and generating an SCL file in STEP 7
To import and compile the SCL file, follow these steps: 1. Start STEP 7. 2. Open your project. 3. Select the project view. 4. Select the CPU in the project tree. 5. Select the “External Sources” subfolder.
The “Open” dialog box opens. 6. Navigate in the file system to the SCL file that was created during the generation of the
project data. 7. Confirm your selection with “Open”.
The SCL file is imported. After completion of the import process, the SCL file is displayed in the “External Sources” folder. 8. You need to compile the SCL file before you can use the blocks in your project. 9. To do this, select the SCL file in “External sources” subfolder. 10.Select the “Generate blocks from source” command in the shortcut menu.
STEP 7 creates the S7 blocks based on the selected SCL file. The created blocks are now automatically displayed in the “Program blocks” folder below the selected CPU in the project tree. You can load the function blocks during the next download to the target device.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.4 Executing a function

5.4

Executing a function

5.4.1

Loading functions

Introduction

Regardless of the context in which the CPU function library is running, the loading procedure consists of the following steps:
· Call the “<STEP7Prefix>_Load” instruction in the STEP 7 user program.
· In the Windows context, the loading process checks if a 32-bit or 64-bit process is required and starts the appropriate host. Each CPU function library runs in a separate Windows process (ODK_Host).
· The host loads the CPU function library and calls the “OnLoad()” function and then the “OnRun()” functions.

Note
Loading the same CPU function libraries with a modified <project>.odk file
When you load an CPU function library and subsequently change the <project>.odk file, we recommend that you unload your CPU function library first before you load the newly generated CPU function library. If the “<STEP7Prefix>_Unload” instruction is not executed, both CPU function libraries are in the memory. This can lead to insufficient memory being available for the CPU.

“<STEP7Prefix>_Load” instruction
A CPU function library is loaded by calling the “<STEP7Prefix>_Load” instruction in the STEP 7 user program.

<STEP7Prefix>_Load

REQ

DONE

BUSY

ERROR

STATUS

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.4 Executing a function

The following table shows the parameters of the instruction “<STEP7Prefix>_Load”:

Section Input Output Output Output
Output

Declaration REQ DONE BUSY ERROR
STATUS

Data type BOOL BOOL BOOL BOOL
INT

Description A rising edge activates the loading of the CPU function library. Indicates that the instruction has finished loading the CPU function library. Indicates that the instruction is still loading the CPU function library. Indicates that an error occurred during the loading of the CPU function library. STATUS gives you more information about the possible cause. Provides information about possible sources of error, if an error occurs during the loading of the CPU function library.

Input parameters
An edge transition (0 to 1) at the “REQ” input parameter starts the function.

Output parameters
The following table shows the information that is returned after loading.

DONE 0 0 0 1 1 0

BUSY 0 1 1 0 0 0

ERROR 0 0 0 0 0 1

STATUS 0x7000 =28672 0x7001 =28673 0x7002 =28674 0x7100 =28928 0x0000 =0 0x80A4 =-32604 0x80C2 =-32574
0x80C3 =-32573
0x8090 =-32624 0x8092 =-32622 0x8093 =-32621
0x8094 =-32620

Meaning No active loading
Loading in progress, first call
Loading in progress, ongoing call
CPU 1500 V2.0 and later: CPU function library is already loaded. Loading was performed successfully.
CPU function library could not be loaded. Start the ODK service manually or restart Windows. CPU function library could not be loaded. There are currently not enough resources available from Windows. Reload the CPU function library after a few seconds. CPU function library could not be loaded. The CPU currently does not have enough resources. Reload the CPU function library after a few seconds. CPU function library could not be loaded. An exception occurred during execution of the “OnLoad()” function. CPU function library could not be loaded because the library name is invalid. CPU function library could not be loaded because the CPU function library could not be found. Check the file name and path of the file. CPU function library could not be loaded. The CPU function library was created for the Windows user context, but no user is logged on.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.4 Executing a function

DONE

BUSY

ERROR

STATUS 0x8095 =-32619

Meaning CPU function library could not be loaded due to the following reasons: · The DLL file is not a CPU function library

· An attempt has been made to load a 64-bit application into a 32-bit system

· Dependencies on other Windows DLL files could not be resolved.
Check that the release build of the CPU function library is used. Check whether the “Visual C++ Redistributables” are installed for
the Visual Studio version you are using.

· The CPU does not support the utilized ODK version.

0x8096 =-32618 0x8097 =-32617 0x8098 =-32616 0x809B =-32613
0xF000 0xFFFF =-4096 -1

The CPU function library could not be loaded because the internal identification is already being used by another loaded CPU function library.
CPU 1500 V1.8 and earlier: CPU function library is already loaded. The CPU function library could not be loaded because the CPU function library is currently being unloaded.
CPU 1500 V2.0 and later: The CPU function library could not be loaded and returns an invalid value (the values 0x0000 and 0xF000 – 0xFFFF are allowed) CPU 1500 V2.0 and later: CPU function library could not be loaded. An error occurred during execution of the “OnLoad()” function.

Example

This example describes how the loading and execution of a Windows CPU function library can be implemented for the Windows environment in STEP 7 after communication disturbances.
When Windows is again available the CPU function library is loaded and the execution of the functions is again possible.
A communication disturbance can be caused by the following:
· Windows Restart (or Shut down)
· Windows Log off (if application in user area)
· TerminateProcess/ODK_Host crash
A flag is necessary for this (here: ODK_Loaded), which is set after successful loading and is reset following a faulty execution of the ODK function.
FUNCTION_BLOCK “ODK_AutoLoad” { S7_Optimized_Access := ‘TRUE’ } VERSION: 0.1
VAR ODK_Loaded : Bool;
END_VAL BEGIN
// Loading of the Windows-CPU function library IF NOT #ODK_Loaded THEN
// Toggle request flag if loading is not active

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.4 Executing a function
IF NOT “ODKProject_Load_DB”.BUSY THEN “ODKProject_Load_DB”.REQ := NOT “ODKProject_Load_DB”.REQ;
END_IF;
// Loading of the CPU function library “ODKProject_Load_DB”();
// Set “Loaded” flag if loading is successful IF “ODKProject_Load_DB”.DONE THEN
#ODK_Loaded := true; END_IF; END_IF;
// Execute the ODK function(s) (only in loaded state) IF #ODK_Loaded THEN
// Toggle request flag if function call is not active IF NOT “ODKProjectSampleFunction_DB”.BUSY THEN
“ODKProjectSampleFunction_DB”.REQ := NOT “ODKProjectSampleFunction_DB”.REQ; END_IF;
// Execute the function “ODKProjectSampleFunction_DB”();
// The “Loaded” flag must be reset when // a) An error is present in the communication with Windows (0x80A4) // b) the CPU function library was already unloaded before this function call (0x8096) IF “ODKProjectSampleFunction_DB”.STATUS = 16#80A4 OR “ODKProjectSampleFunction_DB”.STATUS = 16#8096 THEN #ODK_Loaded := false; END_IF; END_IF; END_FUNCTION_BLOCK

5.4.2

Calling functions

Introduction

Once the CPU function library is loaded, you can execute functions via your STEP 7 user program. This call is made from the corresponding “<STEP7Prefix>SampleFunction” instruction.
You can load up to 32 CPU function libraries at the same time.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.4 Executing a function

“<STEP7Prefix>SampleFunction” instruction
A CPU function library is called by the “<STEP7Prefix>SampleFunction” instruction.

REQ myInt myReal

<STEP7Prefix>SampleFunction

DONE BUSY ERROR STATUS myBool

The following table shows the parameters of the instruction “<STEP7Prefix>SampleFunction”:

Section Declaration Data type

Automatically generated parameters

Input

REQ

BOOL

Output

DONE

BOOL

Output

BUSY

BOOL

Output

ERROR

BOOL

Output

STATUS

INT

User-defined parameter

Input

myInt

InOut

myReal

Output

myBool

Description
A rising edge of this input value activates the execution of the CPU function library. This output value indicates that the instruction has finished execution of the CPU function library. This output value indicates that the instruction is still unloading the CPU function library. This output value indicates that an error occurred during the execution of the CPU function library. The STATUS output value provides more information on this. This output value provides information about possible sources of error, if an error occurs during the execution of the CPU function library.
User-defined input tags User-defined input-output tags User-defined output tags

Input parameters
An edge transition (0 to 1) at the “REQ” input parameter starts the function.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.4 Executing a function

Output parameters
The following table shows the information for the output parameters returned after execution.

DONE 0 0 0 1

BUSY 0 1 1 0

ERROR 0 0 0 0
1

STATUS 0x7000 =28672 0x7001 =28673

Meaning No active process
First call (asynchronous)

0x7002 =28674

Continuous call (asynchronous)

0x0000 Function has been executed and returns a value between 0x0000 and

0x6FFF

0x6FFF.

=0 28671 (ODK_SUCCESS = 0x0000)

0x80A4 =-32604

CPU function library could not be executed for the following reasons:
· The “<STEP7Prefix>_Unload” instruction was executed during a function execution. The function execution was aborted at the CPU end. Windows terminates the execution of the function normally. No return value is sent to the CPU.
Wait until the “<STEP7Prefix>_Unload” instruction has ended. Then load the CPU function library again.

· Windows is not available

0x80C2 =-32574
0x80C3 =-32573
0x8090 =-32624 0x8091 =-32623

· ODK service is not running Start the ODK service manually or restart Windows. CPU function library could not be executed. There are currently not enough resources available from Windows. Execute the CPU function library again after a few seconds. CPU function library could not be executed. The CPU currently does not have enough resources. Execute the CPU function library again after a few seconds. CPU function library could not be executed. An error occurred during execution.
CPU function library could not be executed. A “STOP” occurred during the function call.

0x8096 =-32618

CPU function library could not be executed because the CPU function library was not loaded or unloading is not yet finished.

0x8098 =-32616 0x8099 =-32615
0x809A =-32614
0x809B =-32613

CPU function library could not be executed because the function is not supported.
CPU function library could not be executed because the maximum amount of input data (1 MB) was exceeded (declarations with “In” and “InOut”) CPU function library could not be executed because the maximum amount of output data (1 MB) was exceeded (declarations with “Out” and “InOut”) The function returns an invalid value (a value between 0x0000 and 0x6FFF; 0xF000 and 0xFFFF is permitted)

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.4 Executing a function

DONE

BUSY

ERROR

STATUS 0x809C =-32612

Meaning Function uses an invalid data type: · IN_DATA

· INOUT_DATA

· OUT_DATA

0xF000 0xFFFF =-4096 -1

CPU 1500 V2.0 and later: The function could not be executed and returns a value between 0xF000 and 0xFFFF. (ODK_USER_ERROR_BASE = 0xF000)

Note
Call of function(s) influences the cycle time
When you call a function, the function parameters are copied. In particular in the case of large amounts of data or of structured data, this can lead to the cycle time being influenced.

5.4.3

Unloading functions

Introduction

The CPU function library is unloaded by calling the “<STEP7Prefix>_Unload” instruction. Call is made from the STEP 7 user program.
In addition to this call, the CPU function library is also automatically unloaded for the following reasons.
· The CPU is switched off
· Memory reset of CPU
· Windows is restarted
· Logoff off the Windows user (in the context of a Windows user)

Regardless of the context in which the CPU function library is running, the unloading procedure consists of the following steps:
· Call the “<STEP7Prefix>_Unload” instruction in the STEP 7 user program.
· From now on, no new executes can be carried out for this CPU function library. Still active executes are terminated at the CPU end. Windows terminates the execution of the function normally (“Unload” waits). No return value is sent to the CPU.
· The host calls the “OnStop()” and “OnUnload()” functions.
· The CPU function library is being unloaded.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.4 Executing a function

“<STEP7Prefix>_Unload” instruction
A CPU function library is unloaded by calling the “<STEP7Prefix>_Unload” instruction in the STEP 7 user program.

<STEP7Prefix>_Unload

REQ

DONE

BUSY

ERROR

STATUS

The following table shows the parameters of the instruction “<STEP7Prefix>_Unload”:

Section Input Output Output Output
Output

Declaration REQ DONE BUSY ERROR
STATUS

Data type BOOL BOOL BOOL BOOL
INT

Description A rising edge activates the unloading of the CPU function library. Indicates that the instruction has finished unloading the CPU function library. Indicates that the instruction is still unloading the CPU function library. Indicates that an error occurred during the unloading of the CPU function library. STATUS gives you more information about the possible cause. Provides information about possible sources of error, if an error occurs during the unloading of the CPU function library.

Input parameters
An edge transition (0 to 1) at the “REQ” input parameter starts the function.

Output parameter STATUS
The following table shows the information that is returned after unloading.

DONE 0 0 0 1 0

BUSY 0 1 1 0 0

ERROR 0 0 0 0 1

STATUS 0x7000 =28672 0x7001 =28673 0x7002 =28674 0x0000 =0 0x80A4 =-32604
0x80C2 =-32574
0x80C3 =-32573

Meaning No active unloading
Unloading in progress, the first call
Unloading in progress, ongoing call
Unloading was carried out successfully
CPU function library could not be unloaded for the following reasons: · Windows is not available Start the ODK service manually or restart Windows. CPU function library could not be unloaded. There are currently not enough resources available from Windows. Reload the CPU function library after a few seconds. CPU function library could not be unloaded. The CPU currently does not have enough resources. Reload the CPU function library after a few seconds.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.5 Remote debugging

DONE

BUSY

ERROR

STATUS 0x8090 =-32624 0x8096 =-32618 0x809B =-32613
0xF000 0xFFFF =-4096 -1

Meaning An exception occurred during the unloading of the CPU function library. The CPU function library has been unloaded nevertheless.
CPU function library could not be unloaded because the CPU function library was not loaded or unloading is not yet finished.
CPU 1500 V2.0 and later: The CPU function library could be unloaded and returns an invalid value (the values 0x0000 and 0xF000 – 0xFFFF are allowed) CPU 1500 V2.0 and later: CPU function library could be unloaded. An error occurred in the CPU function library during the execution of the “OnUnload()” function.

5.5

Remote debugging
If you use Microsoft Visual Studio as a development environment, you can use the debugger for debugging.
You can use the remote debugger to debug a CPU function library on a target system without Visual Studio. It should be noted that the generated CPU function libraries (DLLs) are loaded into one of the following processes:
· ODK_Host_x86.exe process (32-bit)
· ODK_Host_x64.exe process (64-bit)
The required remote debugger is dependent on the Visual Studio version used on the host system and on the system type (32-bit/64-bit) of the target system.
You can find links to download the remote debugger for the relevant Visual Studio version on the Microsoft website (https://docs.microsoft.com/en-us/visualstudio/debugger/remotedebugging?#download-and-install-the-remote-tools).
After downloading, you can install the remote debugger on the target system.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.5 Remote debugging

5.5.1

Performing remote debugging

Procedure

1. Start the Visual Studio remote debugger on the target system using “Start > All Programs > Visual Studio 20xx > Remote Debugger”.
2. Configure the authentication. Select the “No authentication” option and select the “Allow any user to debug” check box. Observe the security information.
3. With a C++ CPU function library, copy the Visual Studio Debug DLLs from the folder “<installation path VS>VCredistDebug_NonRedist<ApplicationType>Microsoft.<VS version>.DebugCRT” in the target folder. With a managed (C# / VB) CPU function library you can skip step 3. Destination folder with 32-bit Windows and a 32-bit application: <windows install path>System32 Destination folder with 64-bit Windows and a 64-bit application: <windows install path>System32 Destination folder with 64-bit Windows and a 32-bit application: <windows install path>SysWOW64
Note You need the file “ucrtbased.dll”. If this DLL is not present in the target system, copy it from the host in the folder: With 32-bit Windows under Program Files… With 64-bit Windows under Program Files (x86)… …Microsoft SDKsWindows Kits10ExtensionSDKsMicrosoft.UniversalCRT.Debug<Highest available version> RedistDebug<Application type (32/64-bit)>
4. Load the CPU function library on the target system in the folder “C:ProgramDataSiemensAutomationODK1500S”.
Note If the CPU function library is loaded, unload (Page 60) it before copying.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the Windows environment 5.5 Remote debugging
5. Load (Page 54) the CPU function library on the target system. 6. Set the breakpoints in the source code and start the debugger via “Debug > Attach to
Process…”. Select the following settings in the “Attach to Process” dialog: Transport: Remote Qualifier: IP address of the target system and port of the remote debugger. Attach to:
Use the default value “Automatic: Managed (…) code” for managed CPU function libraries. Only for a C++ CPU function library: Click “Select…”, and select the code type “Native” in the “Select Code Type” dialog.

Debugging OnLoad/OnRun
To attach the debugger to the OnLoad() or OnRun() function, incorporate a wait loop at the start of OnLoad().
Example of a wait loop: EXPORT_API ODK_RESULT OnLoad (void) { #if defined _DEBUG // available in debug configuration, only
while (!IsDebuggerPresent()) // wait for debugger
{ Sleep(100);
} #endif
// your code for OnLoad() …

Result

The debugger stops the execution of the code after the activated breakpoint.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the realtime environment

6.1

Creating a CPU function library

6.1.1

Requirements
· ODK is installed. The Eclipse development environment is installed. · You need administrator rights to create and edit an Eclipse project (CPU function library
for the realtime environment).
Note If you have to move the workspace to a different storage location, make sure you copy the entire workspace.
Note SO files (CPU function libraries) The SO files are not know-how-protected. The customer is responsible for the SO files and their know-how protection.
Note Behavior with a large CPU function library for the real-time environment When an exception is thrown for a CPU function library as of about 20 MB for the real-time environment, the CPU may no longer change from “STOP” to “RUN”. Make sure that you have sufficient load memory for backup of the postmortem files. Then switch the CPU off and on again.

6.1.2

Creating a project
To help you develop a CPU function library, an Eclipse Project template is included in the installation of ODK 1500S.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the realtime environment 6.1 Creating a CPU function library

Procedure

To create a CPU project in Eclipse using an ODK template, follow these steps: 1. Start Eclipse as a development environment. 2. In the “File > New” menu, select the command “Project…”
The “New Project” dialog opens.

Figure 6-1 Creating a new project with Eclipse 3. Select the project template “C++ Project for CPU function library (CPU Runtime)” .

Figure 6-2 Selecting a template

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the realtime environment 6.1 Creating a CPU function library

4. Enter a project name. 5. Click “OK” to confirm.

Result

The CPU function library for the realtime environment is created using the project template and sets the following project settings:
· Project settings for generating the SO file
· Automates the generation of the SO and SCL file
The project template sets up the following Project Explorer by default:

Folder / file <project path> def
STEP7 scr_cg_priv src src_odk_helpers
release_so
launches

Description

<project>.odk <project>.scl.additional
<project>.scl
ODK_Types.h ODK_Functions.h ODK_Execution.cpp

ODK interface description S7 blocks that are appended to the <project>.scl file. Although the file is not part of the project template, the code generator processes the file.
Files from this folder may not be edited! S7 blocks
Files from this folder may not be edited! Definition of the ODK base types Function prototypes Implementation of the “Execute” method

<project>.cpp

Function code: This file has always the suffix CPP, regardless of whether you are creating a C or C++ project. Files from this folder may not be edited!

ODK_CpuReadData.h ODK_CpuReadData.cpp ODK_CpuReadWriteData.h
ODK_CpuReadWriteData.cpp ODK_StringHelper.h ODK_StringHelper.cpp

Definition of the helper function for reading classic DBs. Implementation of the helper function for reading classic DBs. Definition of the helper function for reading/writing classic DBs. Implementation of the helper function for reading/writing classic DBs. Definition of the helper function for access to S7String/S7WString. Implementation of the helper function for access to S7String/S7WString.

<project>.so <project>.debuginfo.so <project>.symbols

ODK Application Binary (release version) that must be transferred to the target system. ODK Application Binary (debug version) that is required for the post mortem analysis. Symbol information that is required for the post mortem analysis.

<project>.gdb.launch

Start for the post mortem analysis.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the realtime environment 6.1 Creating a CPU function library
Note Invalid characters in the project name All invalid characters in the project name are automatically replaced by an underscore. These characters are allowed {A…Z, a…z, 1…9, -, _}. “My + first#project” becomes, for example, “My___first_project”.

6.1.3

Generating a CPU function library
The generation of the project data is divided into two automated steps.
· Pre-Build: Generation of the files created by default based on the changed <Project>.odk file
· Build: Generation of the SO file

Procedure

To generate the project data, follow these steps: 1. Save all edited files. 2. In the “Build” menu, select the command “Build Project”.

Note The project data is only generated if the files have been changed.

Result

The generation of the project data is started. The automatically generated files are stored in the file system.
· SO file: Project directory<Project><BuildConfiguration><Project>.so
· SCL file: Project directory<Project>STEP7<Project>.scl

6.1.4

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the realtime environment 6.1 Creating a CPU function library

Procedure

To define the interface description in the <project>.odk file, follow these steps: 1. Open the <project>.odk file. 2. Change the elements depending on your requirements.

Parameter Context Trace
HeapSize
HeapMaxBlockSize SyncCallParallelCount
SyncCallStackSize SyncCallDataSize
STEP7Prefix

Value realtime on
off [4…<Availabl e CPU memory (Page 130)>] k [8…<HeapSiz e>] [1…9] Default=3
[1…1024]k Default=32k [1…1024]k
Default=auto
<String>

Description Specifies that the CPU function library is loaded in the context of the realtime environment (Page 70). Specifies the trace function in the CPU function library. In this case, the CPU function library requires 32 KB if memory as an additional trace buffer. A “GetTrace” function block is created by default for use in a STEP 7. A “GetTrace” function block is created. The trace buffer contains only one trace entry with the contents: trace is off. Specifies a memory in KB that can be used as heap for these realtime applications.
Specifies the maximum memory size in bytes that can be allocated at one time. If a optional parameter and defines the maximum number of parallel calls in this CPU function library. The size of the memory which is reserved for calls in this CPU function library: SyncCallParallelCount * (SyncCallStackSize + SyncCallDataSize) Is a optional parameter and defines the size of the thread stack for a call in this CPU function library. Each new call receives its own stack memory. Is a optional parameter and defines the size of the data area for a call in this CPU function library. The data area contains IN, INOUT and OUT parameters. Each new call receives its own stack memory. The required data size is automatically calculated by the code generator. With an ODK_CLASSIC_DB, 65 KB is applied. Describes the string that precedes your functions and is shown after importing the SCL file in STEP 7. The following characters are allowed: {A…Z, a…z, 1…9, -, _} The project name is entered without spaces by default.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the realtime environment 6.1 Creating a CPU function library

6.1.5

Environment for loading or running the CPU function library
When the SCL file is imported into STEP 7 as an external source, the ODK instructions are created in the selected directory in STEP 7. You can load up to 32 CPU function libraries.
You can load and run your CPU function library in the context of the realtime environment:

Realtime environment
Add the following line of code in your <project>.odk file to use the CPU function library in the context of the realtime environment: Context=realtime
In this context, the CPU function library is not running in a host process at the Windows end, but instead in the realtime environment. Because the CPU function library is loaded synchronously, it should be loaded in a startup OB (e.g. OB 100).
The number of loadable CPU function libraries (Page 130) is limited in the context of the realtime environment.
If the CPU function library has to be loaded in a cyclic OB (for example, OB 1), note the following loading times:

CPU CPU 1505SP CPU 1507S (with SSD)

Small SO file Loading time 0.5 MB 20 ms 0.5 MB 20 ms

Large SO file Loading time 3 MB 70 ms 5 MB 100 ms

Determining the size of the CPU function library in the CPU memory
To determine the required size of the CPU function library in the CPU memory, follow these steps:
1. Open a command line dialog.
2. Enter the following path from the ODK installation folder (the appended option “-l” is a lower-case “L”): eclipse build_toolsx86_64_gcc_pc_elf_11.3.0binx86_64-pc-elf-readelf.exe “<StorageLocationFile.so>” -l
You can see the size of your CPU function library under the heading “Program Headers” in the “MemSiz” column.
Additional administrative memory is required for each CPU function library in addition to the amount specified here. The administrative memory can be calculated as follows:
Administrative memory = SyncCallParallelCount * (SyncCallStackSize + SyncCallDataSize)

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the realtime environment 6.1 Creating a CPU function library

6.1.6

Defining functions and structures of a CPU function library

6.1.6.1

Defining functions a CPU function library

Functions

Functions are defined by the following general lines of code: ODK_RESULT <FunctionName> ([<InOut identifier>] <data type> <tag name>, etc.);
The <project>.odk file contains an example function description by default. You can change this description and/or add more function descriptions. ODK_RESULT MyFunc1([IN] INT param1, [OUT] INT param2);

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the realtime environment 6.1 Creating a CPU function library

<InOut-Identifier>
There are three defined InOut-Identifiers. Use these in the following order: [IN], [OUT], [INOUT] · [IN]: Specifies an input tag. The tag is copied to the function when it is called. This is constant and cannot be changed.
· [OUT]: Specifies an output tag. The tag is copied back after the function has been completed.
· [INOUT]: Specifies an input and output tag. The tag is copied to the function when it is called. This is not constant and can be changed. The tag is copied back after the function has been completed.
<DataType>
The data type defines the type of a tag. The following tables define the possible data types and their method of representation in C++ or STEP 7:
Elementary data types:

ODK data type
ODK_DOUBLE ODK_FLOAT ODK_INT64 ODK_INT32 ODK_INT16 ODK_INT8 ODK_UINT64

SIMATIC data type LREAL REAL LINT DINT INT SINT ULINT

ODK_UINT32 ODK_UINT16 ODK_UINT8 ODK_LWORD

UDINT UINT USINT LWORD

ODK_DWORD ODK_WORD ODK_BYTE ODK_BOOL ODK_LTIME ODK_TIME ODK_LDT

DWORD WORD BYTE BOOL LTIME TIME LDT

ODK_LTOD

LTOD

ODK_TOD ODK_CHAR

TOD CHAR

C++ data type Description

double float long long long short char unsigned long long unsigned long unsigned short unsigned char unsigned long long unsigned long unsigned short unsigned char unsigned char long long long unsigned long long unsigned long long unsigned long char

64-bit floating point, IEEE 754 32-bit floating point, IEEE 754 64-bit signed integer 32-bit signed integer 16-bit signed integer 8-bit signed integer 64-bit unsigned integer
32-bit unsigned integer 16-bit unsigned integer 8-bit unsigned integer 64-bit bit string
32-bit bit string 16-bit bit string 8-bit bit string 1-bit bit string, remaining bits (1..7) are empty 64-bit during in nanoseconds 32-bit during in milliseconds 64-bit date and time of the day in nanoseconds since 01/01/1970 00:00 64-bit time of the day in nanoseconds since midnight
32-bit time of the day in milliseconds since midnight 8-bit character

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the realtime environment 6.1 Creating a CPU function library

Complex data types:

ODK data type ODK_DTL ODK_S7STRING

SIMATIC data type DTL
STRING

C++ data type
ODK_DTL (struct) unsigned char

Description
Structure/class for date and time
Character string: · For SIMATIC and C++:

8-bit character with length max. and act. (2xUSINT) · For other languages:

ODK_CLASSIC_DB VARIANT

[ ]

ARRAY

ODK_CLASSIC_DB (struct) [ ]

native Classic DB (global or based on UDT)
Range of same data types. You can use all data types as an array except ODK_CLASSIC_DB.

User-defined data types:
User-defined data types (UDT) include structured data, especially the names and data types of this component and their order.
A user-defined data type can be defined in the user interface description with the keyword “ODK_STRUCT”.

Example

ODK_STRUCT <StructName>

{

<DataType> <TagName>;

…

}; The following syntax rules apply to the structure: · You can divide the structure into multiple lines. · The structure definition must end with a semicolon. · Any number of tabs and spaces between the elements is permitted. · It is not permitted to use any keywords for the generated language used (for example
“en / eno” as tag name). You can create additional structures within a structure.

<StructName>
Structure names are valid with the syntax and character restrictions of the programming language and as defined for tag definitions in STEP 7.
In STEP 7, the structure name is extended with the STEP 7 prefix.

<TagName> Tag names are subject to the syntax and character restrictions of the programming language.

Open Development Kit 1500S V2.5 SP4

Programming and Operating Manual, 12/2023, A5E35253941-AH

Developing a CPU function library for the realtime environment 6.1 Creating a CPU function library
Example
The following code example explains the definitions of functions and structures. Sort the parameters by: IN, OUT, INOUT. //INTERFACE … ODK_STRUCT MyStruct
{ ODK_DWORD myDword; ODK_S7STRING myString;
}; ODK_RESULT MyFct([IN] MyStruct myInStruct
,[OUT] MyStruct myOutStruct);

6.1.6.2

Use of ODK_CLASSIC_DB as parameter
The ODK_CLASSIC_DB data type may only be used with the InOut-Identifier [IN] and [INOUT]. If a parameter of data type ODK_CLASSIC_DB with InOut-Identifier [IN] or [INOUT] is used, no other parameters, regardless of the data type, can be used with the same InOut-Identifier.
Example
// INTERFACE … // OK: ODK_RESULT MyFunc1([IN] ODK_CLASSIC_DB myDB); ODK_RESULT MyFunc2([IN] ODK_CLASSIC_DB myDB1, [INOUT] ODK_CLASSIC_DB myDB2); // // NOT OK (Code Generator will throw an error): // ODK_CLASSIC_DB not permitted for [OUT] ODK_RESULT MyFunc3([OUT] ODK_CLASSIC_DB myDB); // if ODK_CLASSIC_DB is used for [IN], no other [IN] parameter may be // defined in this function ODK_RESULT MyFunc4([IN] ODK_CLASSIC_DB myDB, [IN] ODK_INT32 myint);
Application example for C++
#include “ODK_CpuReadData.h” … ODK_RESULT MyFunc1 (const ODK_CLASSIC_DB& myDB) {
CODK_CpuReadData myReader(&myDB); ODK_INT32 myInt1, myInt2;
myReader.ReadS7DINT(0, myInt1); myReader.ReadS7DINT(4,

Documents / Resources

SIEMENS 1500S Simatic Controllers [pdf] Instruction Manual
1500S Simatic Controllers, 1500S, Simatic Controllers, Controllers

References

User Manual

SIEMENS 1500S Simatic Controllers

Specifications

Installation

Developing a CPU Function Library

Development of C/C++ Runtime Application

Using Example Projects

FAQs

Documents / Resources

References

Leave a comment

Cancel reply