6Creating programs with C++

With PLCnext Technology, you can also use programs created with C++ in the real-time context of a PLC along with conventional IEC 61131-3 programs. To use programs and pro­gram parts created in C++ within the scope of PLCnext Technology, you need a Software Development Kit (SDK).

With the PLCnCLI (PLCnext Command Line Interface), Phoenix Contact provides you with a tool featuring the following:

Administration of the SDKs

Build environment

Automatic generation of required metadata and configurations

Automatic creation of the completed library

Extensive toolchain based on a console

The PLCnCLI is based on the .NET Core Framework and can be used on Windows and Linux operating systems.

You can use the freely available Eclipse® software with the Phoenix Contact add-in for Eclipse® as the C++ development environment. The add-in allows for easy connection to the PLCnext Technology platform and provides the PLCnCLI functions in Eclipse®.

6.1PLCnCLI (PLCnext Command Line Interface)

The PLCnCLI (in the following also “CLI”) provides the entire toolchain for C++ program­ming on the PLCnext Technology platform as well as a template system for creating proj­ects. Based on the templates, you can develop your applications. Use the CLI to unpack and manage the SDKs. CMake is contained as the build environment and each SDK has its own configuration. A parser integrated in PLCnCLI creates the metadata required for PLCnext Technology. The LibraryBuilder contained in PLCnCLI creates a PLCnext Engineer li­brary from the project.

inset_27.jpg 

 

The use of the Eclipse® add-in requires the installation of PLCnCLI (Installing PLCnCLI) as well as the installation of one or several SDKs (Installing SDKs). For information on using the Eclipse® add-in, please refer to Eclipse® add-in.

6.1.1System requirements

Before starting the installation, ensure that the system requirements are met.

Download the necessary software.

Operating system

The PLCnCLI was tested and released for the following operating systems:

Microsoft® Windows® 10

Linux (Ubuntu 18.04.1.LTS)

Phoenix Contact software

PLCnCLI (PLCnext Command Line Interface):
The CLI is a command line interface. It can be used, e.g., for generating metadata, C++ header files, PLCnext Engineer libraries, and for adding IN and OUT ports. The func­tions can be called using simple commands. An integrated help lists the commands and describes their functions.

PLCnext Technology SDK:

An SDK contains all of the important toolchains and libraries required for creating a pro­gram. The SDK is installed via the CLI (see Section 6.1.3).

PLCnCLI and PLCnext Technology SDK are available in the download area of your control­ler at phoenixcontact.net/products.

Some sample applications programmed in C++ can be found at https://github.com/plcnext.

6.1.2Installing PLCnCLI

Installing in Windows

Run the installation file.

Follow the instructions of the installation wizard.

Phoenix Contact recommends to add the installation directory to the “Path” variable in the environment variables.

Installing in Linux

The following packages are required for installation in Linux:

“xz-utils” 
Required for SDK installation.

“python3”
Required for SDK installation.

“build-essential”
The package contains the major part of the toolchain required for C++ program­ming, e.g., “make”.

“libunwind8”
The “EngineeringLibraryBuilder” requires this library.

“sshpass_1.06-1_amd64.deb”
Is used by the debug script.

To check if the packages were installed or are being installed, enter the following command:

sudo apt-get install xz-utils python3 build-essential libunwind8

Then, run the “PLCnCLI_Setup.sh” file.

Read and accept the “Software License Terms”.

You will then receive a folder named “plcncli” to which the PLCnCLI was unpacked. Like for Windows, Phoenix Contact recommends to introduce the “Executable” file to simplify calling the file in the console.

For this, enter the following command:

ln -s [Path to the PLCnCLI installation folder]/plcncli /usr/
local/bin/plcncli

E.g.: ln -s /home/plcncli/plcncli /usr/local/bin/plcncli

6.1.3Installing SDKs

Download the SDK that is suitable for your controller from the download area of your controller at phoenixcontact.net/products.

Unpack the .zip file.

Call the CLI in the console using the following command:
plcncli.exe install sdk –d [Installation path] –p [Path to archive file]
E.g.: plcncli.exe install sdk -d C:\CLI\SDKs\AXCF2152\2019_0\ -p C:\CLI\pxc-glibc-x86_64-axcf2152-image-mingw-cortexa9t2hf-neon-
toolchain-2019.0.tar.xz

If you install several SDKs, Phoenix Contact recommends to use the “target name/firmware version” folder structure. Installing an SDK using the PLCnCLI automatically makes the in­stallation known to the CLI.

Introducing an SDK

To introduce already unpacked SDKs to the CLI, enter the following command:
plcncli.exe set setting –a SdkPaths [Path to SDK]
E.g.: plcncli.exe set setting –a SdkPaths C:\CLI\SDKs\AXCF2152\2019_0\

To receive a list of all available settings and the set values, enter the following com­mand:
plcncli.exe get setting –a

Uninstalling an SDK

To uninstall an SDK, enter the following command:
plcncli.exe set setting –r [Path to SDK]

The uninstalled SDK is removed from the PLCnCLI, but will be retained in the directory sys­tem.

6.1.4Functions of the PLCnCLI

CLI features

You can execute many functions directly using the Command Line Interface (CLI). The CLI provides the following features, which you can call by means of simple commands:

Creating projects

Managing SDKs

Generating metafiles (*.progmeta, *.compmeta, *.libmeta)

Generating C++ frames and header files

Compiling with CMake

Creating PLCnext Engineer libraries for several controllers and firmware versions

CLI command structure

Use the Command Line Interface to call functions by means of simple commands.

Activate the CLI by calling the plcncli.exe via the shell, e.g., C:\CLI\plcncli.exe.

There is a long and a short form for the commands, which you can use as you like:

Long form:

To add the parameters, prefix “--”.
E.g.: new project --name MyProject1 

CLI_NewProject.png

Short form:

To add the parameters, prefix “-”.
E.g.: new project -n MyProject1

CLI_NewProjectshort.png

The functions are structured hierarchically. For each command, there is another level of commands that specifies the desired function in more detail. Use the --help command to call a description of the individual functions.
E.g.: new project --help

PLCnCLI_Help.PNG

Figure 6-1 Description of functions

If you do not specify all the parameters, the system will use default parameters. The values will be displayed after the command was executed.
If you do not specify a directory path via the --path option, e.g., when creating a project, a subfolder is created and used in the current directory.

CLI command overview

The CLI provides the following commands, which you can use to execute the corresponding functions. To call a command, enter it in the command line after the plcncli.exe call.
E.g., C:\CLI\plcncli.exe new...:

Table 6-1 CLI command overview

Command

Meaning

build

Compile a project

generate

Generate libraries, metafiles and code files

get

Query information about projects, controllers, etc.

set

Make settings, e.g., select a controller

update

Update of controllers in the current project

install

Install SDK

new

Create new files/projects

help

Call additional information about a specific command

version

Show version information

Each command can be specified using additional parameters. Commands consist of the fol­lowing:

CLI call

Level 1

Level 2

Level 3

C:\...plcncli.exe

new

project

-n or --name

If you require information on parameters or additional command levels, you can request them for each level by means of the --help command.

Example:
Configuring a project

The following example shows an option of how to configure a project up to the complete PLCnext library using the CLI:

Open a project folder of your choice:
e.g., C:\Users\<username>\Documents\CLI Projects.

Generate a new project with the project name “Project1”:
\CLI\Plcncli.exe new project –n Project1

Go to the “Project1” project folder:
cd Project1

Select the desired controller for the project (e.g., AXC F 2152):
plcncli.exe set targets --add -n AXCF2152

Use the following command to generate the necessary metafiles for the project:
\CLI\plcncli.exe generate config

Use the following command to generate the necessary code files for the project:
\CLI\plcncli.exe generate code

You can also generate metafiles and code files in only one step:
\CLI\plcncli.exe generate all

Compile the project.:
\CLI\plcncli.exe build

Generate a library:
\CLI\plcncli.exe generate library 

The library and the .so files are located in the “bin” folder of the project.

For additional information on programming the code, please refer to Section 5, “Structure of a C++ program”.

Importing the library

You can then import the generated library in PLCnext Engineer, see Section 9, “Importing libraries into PLCnext Engineer”.

6.2Eclipse® add-in

The Eclipse® add-in for PLCnext C++ programming enables you to use the PLCnCLI func­tions from you familiar C++ development environment.

6.2.1Requirements

Installing Eclipse®

Phoenix Contact recommends the Eclipse® CDT Photon (9.5.2) development environment.

Download the Eclipse® CDT Photon (9.5.2) software with the “Eclipse IDE for C/C++ Developers” package from https://www.eclipse.org.

Copy and unpack the files to any folder.

You can execute Eclipse® right away.

inset_34.jpg 

 

The Java™ Runtime Environment is required for the Eclipse® development environment.

If an error with “error code 13” occurs when Java is started, check if the correct Java version is installed. If you use a 64-bit Eclipse version, you have to use a 64-bit Java version.

Installing PLCnCLI

Install the PLCnext Command Line Interface according to the information in Section 6.1.2, “Installing PLCnCLI”.

Installing SDKs

Install the SDKs according to the information in Section 6.1.3, “Installing SDKs”.

6.2.2Installing/updating/uninstalling the Eclipse® add-in

Installing the add-in

If necessary, uninstall earlier add-in versions (see Uninstalling the add-in).

Start Eclipse®.

Open the “Help, Install New Software...” menu.

Eclipse_InstanewSW.png

Figure 6-2 “Help, Install New Software...” menu

To select the path to the directory of the add-in, click on “Add” in the “Install” dialog (see Figure 6-3).

In the “Add Repository” dialog, click on “Archive” and select the archive of the add-in.

You will find it in the installation folder of the PLCnCLI under
.../ide-plugins/com.phoenixcontact.plcnext.updatesite.zip.

Enter a name of your choice in the “Name” input field and confirm with “Add”.

Disable the “Contact all update sites during install to find required software” check box.

Install_EclipseAddin.PNG

Figure 6-3 “Install” dialog

Click on the “Next” button.

Read and accept the licence agreements.

Click “Finish” to complete the installation.

Restart Eclipse®.

Updating the add-in

To update the Eclipse® add-in, proceed as described in Section Installing the add-in.

Uninstalling the add-in

Open the “Help, About Eclipse IDE” menu.

Click on the “Installation Details” button.

Eclipse_Help.png
Eclipse_InstaDetails.png

Figure 6-4 “Help, About Eclipse IDE” menu

Select the earlier add-in versions and uninstall them.

6.2.3Creating a new C++ project in Eclipse®

This section describes how to create a new C++ project in Eclipse®.

Open the “File, New, Project...” menu.

Eclipse_New.png

Figure 6-5 Creating a new project

The “New Project” window opens (see Figure 6-6).

Select the “PLCnext C++ Project” wizard from the selection list.

Confirm your selection with “Next”.

Eclipse_Wizard.png

Figure 6-6 Selecting a wizard

Enter a project name in the “Project name” input field.

In the “Toolchains” area, select the “PLCnext C++ Toolchain” entry.

Confirm with “Next”.

Eclipse_Toolchains.png

Figure 6-7 Selecting toolchains

Enter a name for the program and component in the corresponding input fields.

Eclipse_Properties.png

Figure 6-8 Entering a name for the program and component

Select the desired controller and firmware status for the project.

Eclipse_select_Target.PNG

Figure 6-9 Selecting the controller and firmware status

You can also change the selection of the desired controller and the corresponding firmware status after the project has been created.

Open the “Project, Properties” menu.

Select the “PLCnext Targets” option.

Remove controllers or add new controllers and their firmware version.

Click the “Finish” button.

You can not start creating the program.

6.2.4Creating a program

To create a C++ program using Eclipse®, which can be imported as a library into PLCnext Engineer, you must first prepare a new project in accordance with the description in Section 6.2.3 “Creating a new C++ project in Eclipse®“.

The created project has a defined structure in which the C++ program is created. Figure 6-10 shows an example.

Eclipse_Projektbaum.PNG

Figure 6-10 Example structure of a C++ project

To create a program, proceed as follows:

Open the *.cpp source file.

Program the code to be executed during each ESM task cycle in the “Execute()” func­tion (see comment //TODO implement program).

For additional information on programming in C++, please refer to Structure of a C++ program.

After instantiation of a program, the assigned ESM task calls the Execute() function of the program instance in each cycle.

inset_35.jpg 

 

Example projects and the associated documentation can be downloaded at https://github.com/plcnext.

6.2.5Compiling the project

inset_36.jpg 

 

Recommended: Make the following setting so that your files are saved automatically before you execute the “Build Project” option:

In Eclipse®, open the “Window, Preferences” menu.

Select “General, Workspace, Build”.

Enable the “Save automatically before build” check box.

Make this setting separately for each workspace.

Switch to the “Project Explorer” to compile the project.

Right-click to open the context menu for the project folder
(in the example: “FirstProject1”).

In the context menu, click on the “Build Project” option or click on the Schaltfläche_Build4Targets.PNG button in the tool bar.

Eclipse_BuildProject.png
Eclipse_Build4Targets.PNG

Figure 6-11 “Build Project”

Successful compilation of the project or possible error messages are displayed on the “Con­sole” tab.

Eclipse_Console.png

Figure 6-12 Example: “Console”

inset_28.jpg 

 

Note regarding compiler warning

For each defined port, you receive the compiler warning:
offsetof within non-standard-layout type.

E.g.: [cmake]: /home/user/Workspace/Counters/intermediate/code/Counters
Library.meta.cpp:22:47: warning: offsetof within non-standard-layout type ‘Counters::Cp­pRetain’ is undefined [-Winvalid-offsetof]

You can ignore this warning in conjunction with your defined ports or suppress it using the -Wno-invalid-off­setof CMake parameter.

Successful compilation

If compilation was successful, a shared object (*.so) is generated.

Generating a PLCnext Engineer library

To be able to use the program in PLCnext Engineer, you need the pcwlx library, which was generated during compilation. The Library Builder automatically generates the pcwlx library within the framework of compilation (“Build Project”). The files are located in the project folder, e.g., C:/Users/<username>/eclipse-workspace/FirstProject1/Bin. Import the library within PLCnext Engineer and assign the programs to a task (see Section 9, “Importing li­braries into PLCnext Engineer”).

6.3Remote debugging

PLCnext Technology has an integrated GDB server. You have the option of setting up a re­mote debugging session using Eclipse®.

A description on how to set up a remote debugging session for a running process is avail­able in the PLCnext Community.