PLC Next

PLCnext Technology
User manual
UM EN PLCNEXT TECHNOLOGY 2020.0 LTS
User manual
PLCnext Technology
UM EN PLCNEXT TECHNOLOGY 2020.0 LTS, Revision 00 2019-12-04
This user manual is valid for:
Designation Version
PLCnext Technology firmware 2020.0 LTS
Designation Order No.

AXC F 1152 1151412
AXC F 2152 2404267
AXC F 2152 STARTERKIT 1046568
RFC 4072S 1051328
The documentation for PLCnext Technology is now also available online in the PLCnext Technology InfoCenter
in the PLCnext Community. This user manual will not be continued from firmware version 2020.0 LTS.
109324_en_00
PHOENIX CONTACT GmbH & Co. KG • Flachsmarktstraße 8 • 32825 Blomberg • Germany

phoenixcontact.com
Table of contents
Table of contents
1 General information ...................................................................................................................8
1.1 Identification of warning notes ...............................................................................8
1.2 Qualification of users .............................................................................................8
1.3 Introduction............................................................................................................9
1.4 Information about this document..........................................................................10
1.5 Trademarks/licensing information........................................................................10
1.6 Safety notes.........................................................................................................11
1.7 PLCnext Technology product range ....................................................................13
2 Structure of the PLCnext Technology ......................................................................................14

2.1 Core components ................................................................................................14
2.2 Function extensions for internal processes..........................................................16
2.3 Function extensions for external processes.........................................................17
2.4 System manager .................................................................................................18
2.5 PLC manager ......................................................................................................18
2.6 Managing of components ....................................................................................18
2.7 Configuration files................................................................................................19
2.7.1 acf, esm, gds configuration files ...........................................................19
2.7.2 .tic file ...................................................................................................20
2.7.3 Metafiles ..............................................................................................20
2.7.4 Generating configuration files using PLCnext Engineer .......................22
2.7.5 Manual configuration ............................................................................22
2.8 ESM (Execution and Synchronization Manager) .................................................23
2.8.1 Task configuration using PLCnext Engineer ........................................24
2.8.2 Task configuration via configuration files .............................................25
2.9 GDS (Global Data Space) ...................................................................................29
2.9.1 Port-based communication ..................................................................30
2.9.2 Fieldbus connection .............................................................................32
2.9.3 GDS configuration with PLCnext Engineer ...........................................36
2.9.4 GDS configuration using configuration files ..........................................37
2.9.5 Supported data types ...........................................................................42
2.10 RSC (Remote Service Calls) ...............................................................................45
2.11 PLCnext embedded OPC UA server (eUA) .........................................................45
2.11.1 OPC UA ...............................................................................................45
2.11.2 Configuration .......................................................................................45
2.11.3 OPC UA file access ..............................................................................47
2.11.4 Alarms ..................................................................................................48
2.11.5 Subscriptions .......................................................................................48
2.11.6 “GlobalDataSpace” namespace ...........................................................49
109324_en_00 PHOENIX CONTACT 3 / 246

PLCNEXT TECHNOLOGY
2.11.7 Device Integration (DI) namespace ......................................................50

2.11.8 Data types ............................................................................................51
2.11.9 UA server endpoints .............................................................................51
2.11.10 Encryption algorithms ..........................................................................51
2.11.11 Ethernet ports at the controller .............................................................51
2.11.12 Disabling user authentication ...............................................................52
2.11.13 OPC UA Historical Data Access (HDA) ................................................52
2.12 Alarms .................................................................................................................53
2.12.1 IEC 61131 alarm function blocks ..........................................................54
2.12.2 Alarms in C++ programs ......................................................................58
2.12.3 OPC UA server ....................................................................................60
2.13 Notification manager............................................................................................60
2.13.1 Notifications of the PLCnext Technology firmware ...............................62
2.14 Notification Logger ..............................................................................................64
2.14.1 Displaying notifications in the PLCnext Engineer cockpit .....................64
2.14.2 Receiving notifications .........................................................................64
2.14.3 Configuring the Notification Logger ......................................................64
2.14.4 Saving notifications ..............................................................................66
2.15 DataLogger..........................................................................................................67
2.15.1 Data logging .........................................................................................67
2.15.2 Data sink ..............................................................................................67
2.15.3 DataLogger configuration .....................................................................69
2.15.4 Database layout ...................................................................................71
2.15.5 Configuration examples .......................................................................73
2.16 Operating system ................................................................................................75
2.16.1 Directories of the firmware components in the file system ....................75
2.16.2 System time .........................................................................................78
2.16.3 OpenVPN™ client ................................................................................80
2.16.4 IPsec (strongSwan) ..............................................................................80
2.16.5 Text editors ..........................................................................................81
2.16.6 User rights ............................................................................................81
2.16.7 Root rights ............................................................................................82
2.16.8 Linux scripts of the PLCnext Technology firmware ...............................85
2.16.9 LDAP connection .................................................................................86
3 Web-based management (WBM) ............................................................................................91

3.1 Establishing a connection to WBM ......................................................................91
3.2 Licensing information on open source software...................................................93
3.3 Changing the language........................................................................................93
3.4 Login....................................................................................................................93
3.5 Start page – areas and functions .........................................................................95
3.6 “Information” area ................................................................................................96
3.6.1 “General Data” page ............................................................................96
4 / 246 PHOENIX CONTACT 109324_en_00

Table of contents
3.7 “Diagnostics” area ...............................................................................................97

3.7.1 “PROFINET” page ................................................................................97
3.7.2 “Local Bus” page ................................................................................102
3.8 “Configuration” area...........................................................................................107
3.8.1 “PROFICLOUD” page ........................................................................107
3.9 “Security” area ...................................................................................................109
3.9.1 “User Authentication” page ................................................................109
3.9.2 “Certificate Authentication” page ........................................................115
3.9.3 “Firewall” page ...................................................................................123
3.9.4 “SD Card” page ..................................................................................133
3.10 “Administration” area .........................................................................................136
3.10.1 “Firmware Update” page ....................................................................136
3.10.2 “License Management” page .............................................................139
3.10.3 “PLCnext Apps” page .........................................................................144
4 Transferring variable values to the PROFICLOUD .................................................................147

4.1 Creating variables as OUT ports........................................................................147
4.2 Preparing the controller for PROFICLOUD ........................................................148
4.3 Configuring PROFICLOUD................................................................................148
4.4 Displaying an overview of the PROFICLOUD device metrics ............................151
4.5 Displaying the metrics graphically in Grafana® .................................................152
5 Structure of a C++ program ...................................................................................................155

5.1 “ILibrary” and “LibraryBase“ ...............................................................................155
5.2 “IComponent” and “IProgram”............................................................................156
5.2.1 “IComponent” and “ComponentBase” ................................................156
5.2.2 “IProgramComponent” and “IProgramProvider” .................................158
5.2.3 “IProgram” and “ProgramBase“ ..........................................................159
5.2.4 “IControllerComponent” .....................................................................160
5.3 Several component types in the same library ....................................................161
5.4 PLM (Program Library Manager) .......................................................................161
5.4.1 Functions ...........................................................................................162
5.4.2 Configuration .....................................................................................162
5.5 ACF (Application Component Framework) ........................................................163
5.5.1 Libraries .............................................................................................163
5.5.2 Components ......................................................................................164
5.5.3 Configuration .....................................................................................165
5.6 Common classes ...............................................................................................166
5.6.1 Threading ...........................................................................................167
5.6.2 “Ipc” (Inter-process communication) ..................................................168
5.6.3 “Chrono” .............................................................................................168
5.6.4 “Io” .....................................................................................................168

PLCNEXT TECHNOLOGY
5.6.5 “Net” ...................................................................................................168

5.6.6 “Runtime” ...........................................................................................169
5.6.7 “Template Loggable” ..........................................................................169
5.7 Notifications.......................................................................................................171
5.8 Using RSC services...........................................................................................174
5.8.1 RSC Axioline services ........................................................................175
5.8.2 RSC PROFINET services ..................................................................176
5.8.3 RSC device interface services ...........................................................178
5.8.4 RSC GDS services .............................................................................183
5.8.5 Querying notifications ........................................................................192
6 Creating programs with C++ ..................................................................................................194

6.1 PLCnext CLI (PLCnext Command Line Interface) .............................................194
6.1.1 System requirements .........................................................................194
6.1.2 Installing PLCnext CLI ........................................................................195
6.1.3 Installing SDKs without Eclipse® add-in ............................................195
6.1.4 Functions of the PLCnext CLI .............................................................196
6.2 Eclipse® add-in.................................................................................................199
6.2.1 Requirements .....................................................................................199
6.2.2 Installing/updating/uninstalling the Eclipse® add-in ...........................199
6.2.3 Installing SDKs with the Eclipse® add-in for
PLCnext Technology ..........................................................................202
6.2.4 Creating a new C++ project in Eclipse® ............................................203
6.2.5 Creating a program ............................................................................207
6.2.6 Compiling the project .........................................................................208
6.3 Remote debugging ............................................................................................209
7 Creating function blocks and functions with C# ......................................................................210

7.1 Installing the Visual Studio® extension..............................................................211
7.1.1 System requirements .........................................................................211
7.1.2 Installation ..........................................................................................212
7.2 Creating a firmware library.................................................................................213
7.3 Remote debugging of C# code with Visual Studio® ..........................................216
7.3.1 Disabling user authentication .............................................................216
7.3.2 Opening a port and deactivating TLS .................................................217
7.3.3 Debug mode ......................................................................................218
7.4 Supported functions of the PLCnext Technology C# programming system .......222
7.4.1 C# language functions .......................................................................222
7.4.2 Base class libraries ............................................................................223
7.4.3 eCLR runtime functions ......................................................................225
7.5 Supported data types ........................................................................................225

Table of contents
8 Matlab® Simulink® ...............................................................................................................227
9 Importing libraries into PLCnext Engineer ..............................................................................228
A Appendix ................................................................................................................................235
A1 Available data types...........................................................................................235
A2 PLCnext Technology naming conventions.........................................................237
A3 Explanation of terms ..........................................................................................239
A4 PROFINET diagnostic code in WBM .................................................................244

PLCNEXT TECHNOLOGY
1 General information
Read this user manual carefully and keep it for future reference.
1.1 Identification of warning notes

This symbol indicates hazards that could lead to personal injury.
There are three signal words indicating the severity of a potential injury.
DANGER
Indicates a hazard with a high risk level. If this hazardous situation is not
avoided, it will result in death or serious injury.
WARNING
Indicates a hazard with a medium risk level. If this hazardous situation is not
avoided, it could result in death or serious injury.
CAUTION
Indicates a hazard with a low risk level. If this hazardous situation is not avoided,
it could result in minor or moderate injury.
This symbol together with the NOTE signal word warns the reader of actions
that might cause property damage or a malfunction.
Here you will find additional information or detailed sources of information.
1.2 Qualification of users

The use of products described in this user manual is oriented exclusively to qualified appli-
cation programmers and software engineers. The users must be familiar with the relevant
safety concepts of automation technology as well as applicable standards and other regu-
lations.
For programming of applications, familiarity with C/C++, IEC 61131-3 or
MATLAB® Simulink® is assumed.

General information
1.3 Introduction
PLCnext Technology
Demands on automation technology are increasing due to digitization in the industrial sec-
tor. Flexibility, networking, exchange of information, the “Internet of Things” are gaining ever
more importance for modern, flexible and efficient production. Automation systems and
their controllers must become more adaptable and must be able to react ever faster to new
requirements.
To meet the changing demands of industry, Phoenix Contact developed
PLCnext Technology as the basis for a new, open control platform. PLCnext Technology
combines all of the communication properties and advantages of the traditional PLC world
with the openness and flexibility of smart devices. Both the control platform and the cloud
architecture are based on open-source components which are undergoing continuous,
manufacturer-neutral development.
Previously, programming of PLC applications was only possible in the IEC 61131-3 pro-
gramming languages. PLCnext Technology allows developers from various corporate ar-
eas, technology disciplines and generations to work in parallel with and yet independently
of each other on one automation application. And they can do that in the programming en-
vironment to which they are accustomed. Whether with established and proven program-
ming tools such as Microsoft® Visual Studio®, Eclipse®, MATLAB® Simulink® or
PLCnext Engineer. The programming code can be created in the traditional way in accor-
dance with IEC 61131-3, and in C/C++ or Simulink® code.
PLCnext Technology connects and combines traditional PLC programming and high-level
language programming. Thus, different programming systems can be used on one plat-
form.
PROFICLOUD, a professional cloud solution and part of PLCnext Technology, enables you
to not only collect and process data directly on the controller, but to also have it transferred
to the cloud. Therefore, data is more easily available and it can be retrieved and used re-
gardless of the location and time. All performance and energy data of your system is avail-
able anywhere and at any time. Cloud-based services are also available, e.g., for data anal-
ysis, predictive maintenance, etc.
The open PLCnext Technology platform enables you to extend the benefits of conventional
PLCs and provides you with a basis for cutting-edge automation capable of meeting all of
the demands of the IoT world.
Advantages at a glance
– Accelerated startup in comparison to conventional control platforms because several
developers can work on one program in parallel with and yet independently of each oth-
er in different programming languages
– Convenient engineering, thanks to the use of established programming tools such as
PLCnext Engineer, MATLAB® Simulink®, Eclipse®, or Microsoft® Visual Studio®
– Reliable operation because determinism, real-time behavior and cycle-consistent data
exchange are assured regardless of the programming language
– Cost-efficient and flexible, thanks to the use of freely available software from the open
source community
– Future-proof and adaptable, because new functions and future technologies can be in-
tegrated quickly and easily

PLCNEXT TECHNOLOGY
Creating programs with C++

With PLCnext Technology, you can create programs in C++ and import these into
PLCnext Engineer. There, you can instantiate the programs and use them in the same way
as conventional IEC 61131-3 programs in real time. Consistent data exchange with pro-
grams that were created with other high-level languages or IEC 61131-3 is ensured via the
ports of the GDS. This way, the programs can run together in the same tasks.
Phoenix Contact provides an add-in for Eclipse, an SDK (Software Development Kit), as
well as a LibraryBuilder. These tools support you in the use of your C++ program on a con-
troller with PLCnext Technology. The Eclipse® development environment is particularly
suitable because it can be used under both Windows® and Linux, and is commonly used in
C++ programming (see Section “Creating programs with C++” on page 194).
Creating function blocks and functions with C#

Create function blocks and functions in C# with Microsoft® Visual Studio®. You can use an
extension from Phoenix Contact to convert them into libraries, import them into
PLCnext Engineer, and use them for your programming. The function blocks or functions
can be called up in PLCnext Engineer, e.g., in the ST (Structured Text) or LD (Ladder Dia-
gram) code worksheet, and used for your programming.
The IEC 61131 runtime system of the controller (eCLR) is a .Net-based runtime that sup-
ports both IEC 61131-3 and C# code. For this reason, the Visual Studio® development en-
vironment can be used for C# (see Section “Creating function blocks and functions with C#”
on page 210).
MATLAB® Simulink®
Use the PC Worx Target for Simulink (2400041) to create models that are compatible to
PLCnext and can easily be executed as a program in the real-time context of the controller.
1.4 Information about this document

This document describes the PLCnext Technology control platform. It describes the system
and its components and provides instructions on creating, using and managing
PLCnext Technology applications.
Further information,tutorials and support on PLCnext Technology is available in the
PLCnext Community at plcnext-community.net. Sample projectsand applications as well as
the associated documentation can be downloaded at https://github.com/plcnext.
You will find tutorial videos on specific PLCnext topics on the Phoenix Contact Technical
Support Youtube channel.
1.5 Trademarks/licensing information

Trademarks
All product names used are trademarks of the respective organizations.
– MATLAB® and Simulink® are registered trademarks of The MathWorks, Inc.
– Eclipse® is a trademark of the Eclipse Foundation.
– Microsoft® and Visual Studio® are trademarks of the Microsoft Corporation.
– Grafana® is a trademark of Grafana Labs.

General information
Licensing information on open source software

PLCnext controllers work with a Linux operating system.
All license information can be called using the “Legal Information” link on every page of web-
based management (WBM) for controllers:
• Click on the “Legal Information” link on the bottom left of the WBM page.
Licenses for all of the open source software used are shown.
Further information on WBM of the respective controller is available in the corresponding
user manual. The user manual can be downloaded from the product page at
phoenixcontact.net/products.
1.6 Safety notes
NOTE: Risk of unauthorized network access

Connecting devices to a network via Ethernet always entails the risk of unauthorized ac-
cess to the network.
Therefore, please check for the option of disabling active communication channels in your
application (for instance SNMP, FTP, BootP, DCP, HTTP, HTTPS, etc.) or setting pass-
words to prevent third parties from accessing the controller without authorization and
modifying the system.
Due to the communication interfaces of the controller, the controller should not be used in
safety-critical applications unless additional security appliances are used.
Please take additional protective measures in accordance with the IT security require-
ments and the standards applicable to your application (e.g., virtual networks (VPN) for
remote maintenance access, firewalls, etc.) for protection against unauthorized network
access.
On first request, you shall release Phoenix Contact and the companies associated with
Phoenix Contact GmbH & Co. KG, Flachsmarktstrasse 8, 32825 Blomberg in accordance
with §§15ff.AktG (German Stock Corporation Act), hereinafter collectively referred to as
“Phoenix Contact”, from all third-party claims made due to improper use.
For the protection of networks for remote maintenance via VPN, Phoenix Contact offers
the mGuard product series security appliances; further information on this is available in
the latest Phoenix Contact catalog (phoenixcontact.net/products).
Additional measures for protection against unauthorized network access are listed in the
AH EN INDUSTRIAL SECURITY application note. The application note can be download-
ed at phoenixcontact.net/products.

PLCNEXT TECHNOLOGY
NOTE: Risk of unauthorized access to devices

Devices with PLCnext Technology do not feature mechanical access protection and are
therefore at risk of manipulation. Unauthorized access can occur via the following device
interfaces, for example:
– USB ports
– PCI Express interfaces
– Axioline bus
– SD card slot and the SD card contained therein
– Device HMI (touch panel as well as buttons, switches, etc.)
– Ethernet interfaces
To prevent damage due to authorized access, make sure that only authorized access is
possible.
• Protect the interfaces by installing the devices in a control cabinet.
• Secure the control cabinet with a lock.
• Make sure that only authorized persons have access to the control cabinet key.
• Run cables in such a way that they are protected against unauthorized access.

General information
1.7 PLCnext Technology product range
Modifications to hardware and firmware of the devices are not permitted.

Incorrect operation or modifications to the devices can endanger your safety or damage
the devices. Do not repair the devices yourself. If the devices are defective, please con-
tact Phoenix Contact.
Currently, the following products are available with PLCnext Technology:
Description Type Order No.

PLCnext Control for the direct control of Axioline F I/Os. With two AXC F 1152 1151412
Ethernet interfaces. Complete with connector and bus base module.
PLCnext Control for the direct control of Axioline F I/Os. With two AXC F 2152 2404267
Ethernet interfaces. Complete with connector and bus base module.
PLCnext Control with 4 x 10/100/1000 Ethernet, PROFINET control- RFC 4072S 1051328
ler with integrated PROFIsafe safety controller, PROFINET device,
IP20 degree of protection, pluggable parameterization memory
AXC F 2152 starter kit including AXC F 2152 PLCnext Control, volt- AXC F 2152 STARTERKIT 1046568
age switch, digital input and output module, analog input and output
module, potentiometer, switch module, PROFICLOUD license, as
well as a power supply unit, patch cable, country-specific adapter
plugs, and documentation.
Engineering software platform for Phoenix Contact automation con- PLCNEXT ENGINEER 1046008
trollers. PLCnext Engineer is IEC 61131-3-compliant and its func-
tions can be extended using add-ins.
Software add-on for the integration and execution of Matlab Simulink PC WORX TARGET FOR 2400041
models on Remote Field and Axioline controllers SIMULINK
Right-alignable Inline adapter terminal (INTERBUS master) for one AXC F IL ADAPT 1020304
PLCnext Control device for setting up a PLCnext Technology Inline
station
Left-alignable Ethernet interface, for connection to a compatible AXC F XT ETH 1TX 2403115
modular controller from the PLCnext Control range.
Left-alignable INTERBUS master, for the connection of INTERBUS AXC F XT IB 2403018
remote bus components to a compatible modular controller from the
PLCnext Control range.
Ensure that you always use the latest firmware and documentation. The latest firmware
versions and documentation can be downloaded at phoenixcontact.net/products.
Software packages required for programming in C++ with Eclipse® or in C# with
Visual Studio® can be downloaded from the download area for the AXC F 2152 or the
RFC4072S controller.
Sample projects and the associated documentation can be downloaded at
https://github.com/plcnext.

PLCNEXT TECHNOLOGY
2 Structure of the PLCnext Technology
2.1 Core components

PLCnext Technology is an open firmware platform executed on a Linux operating system
with real-time patch. Different firmware components forming the core functions are called
core components. These core components are a fixed part of the PLCnext Technology firm-
ware. They cannot be modified. The core components are divided into the following groups:
– Middleware
– I/O components
– Service components
– System components
Figure 2-1 Core components of the PLCnext Technology firmware
Middleware The middleware section decouples the PLCnext Technology firmware from the operating
system. The GDS (Global Data Space) is part of the middleware and is responsible for a
central function of PLCnext Technology. It enables consistent data exchange between dif-
ferent real-time components. For additional information on the GDS, please refer to Section
“GDS (Global Data Space)” on page 29.
I/O components / The fieldbus manager connects the implemented fieldbus to PLCnext Technology for input
fieldbus manager and output of process data. The following fieldbuses are supported (depending on the de-
vice):
– PROFINET controller
– PROFINET device
– Axioline F master (local bus)

Structure of the PLCnext Technology
– INTERBUS (with AXC F 2152plus AXC F IL Adapt or AXC F XT IB)
Service components The service components provide access to the ESM (Execution and Synchronization Man-
ager), GDS (Global Data Space) and to the following system components:
– OPC UA server
– PROFICLOUD gateway
– Web-based management
– HMI web server (HTML5 web visualization in PLCnext Engineer)
– Accessible via Linux
– SFTP
– VPN
– SSH
– NTP
– Trace controller
System components In the system components, all basic functions of PLCnext Technology are implemented.
– System manager and PLC manager
These components load all the other system components and monitor the stability of
the system.
– ESM (Execution and Synchronization Manager)
The ESM enables IEC 61131-3, C++ and MATLAB® Simulink® programs to be execut-
ed in real time. For creating applications, programming languages can be combined in
any way. For additional information on ESM, please refer to Section “ESM (Execution
and Synchronization Manager)” on page 23.
– User manager
The user manager extends the standard Linux user management function. The various
user roles are managed here. You can only execute operations in the
PLCnext Technology firmware with a defined user role. You can select one or more
user roles with different permissions for each user.
– IEC 61131 runtime
ProConOS embedded CLR is the open IEC 61131 control runtime system for different
automation tasks from Phoenix Contact.
Real-time user programs User programs are not supplied as a standard with the PLCnext Technology firmware; they
are created by the user. These user-defined programs can be created in classic program-
ming languages in accordance with IEC 61131-3, and also in C++ or Matlab® Simulink®. It
is also possible to combine different programming languages.
The easiest way to use PLCnext Technology is to create user programs in programming
languages in accordance with IEC 61131-3, in C++ or using Matlab® Simulink®, and to ex-
ecute these in the real-time environment of the ESM. The user programs are downloaded
to the controller and, after a cold restart of the device, are executed by the firmware.

PLCNEXT TECHNOLOGY
The IN and OUT ports of the GDS guarantee data consistency and ensure seamless data
exchange between tasks and programs.
Figure 2-2 Task handling with ESM and GDS
2.2 Function extensions for internal processes

Users can add their own components function extensions to PLCnext Technology. The
system manager loads and monitors these function extensions (see Section 2.4 “System
manager”). All available PLCnext Technology APIs can be used:
– RSC (Remote Service Call): Each component (system, service, I/O components) fea-
tures a selection of individual services that can be called up and used via RSC (see
Section “RSC (Remote Service Calls)” on page 45).
– Component interface: The firmware calls up the implemented functions of the compo-
nent interface at certain times, e.g., during program startup.
– Data access: Read and write access to the GDS (Global Data Space)

– Common classes: Easy retrieval of system functions, e.g., file operations, socket ser-
vices, threading (see Section “Common classes” on page 166).
Figure 2-3 PLCnext Technology - function extensions for internal processes
2.3 Function extensions for external processes

Function extensions can be used to add new, internal functions. However, it may also be
necessary to incorporate external processes. This may be the case if, for example, exten-
sive software components such as Java® Frameworks or .Net Core® are used. They can
also be integrated as function extensions. Function extensions can be started along with the
PLCnext Technology framework.
Figure 2-4 PLCnext Technology - function extensions for external processes

PLCNEXT TECHNOLOGY
2.4 System manager

PLCnext Technology is an open platform. This means that as a user you can integrate your
own components and programs. During firmware startup, the system manager ensures that
all integrated components and programs are configured and started in the correct order.
Here, all system processes are generated and function extensions are supplemented. A
system component is always started, configured and shut down by the system manager.
2.5 PLC manager

The PLC manager is a firmware component that loads the necessary PLC program code
into the memory and boots up or shuts down the programs. The program code can exist of
an IEC 61131-3 program that was created and sent using PLCnext Engineer. The code can
also be created in C++ or Matlab® Simulink®. C++ and Matlab® Simulink® programs are
available on the controller as program code libraries (shared object, *.so). Configuration
files on the controller are used to determine which libraries the PLC manager is to load and
which programs in these libraries it is to instantiate. The PLC manager is therefore superor-
dinate to the code. It controls booting up and shutting down of the real-time system (ESM)
as well as starting and stopping of data exchange via fieldbuses. If the controller is in the
“stop” state, the real-time tasks monitored by the ESM are not executed. The signals of the
sensors connected to the fieldbus are no longer read as inputs, and the output signals are
no longer sent to the connected actuators.
The PLCnext Engineer software can be used to start the controller in three different modes:
– Cold restart:
During a cold restart, all data is reset.
– Warm restart:
During a warm restart, all data is reset and all remanent data is restored (system start).
Note: In firmware version 1.x, remanent data is only located in the eCLR/IEC program-
ming environment.
– Hot restart:
During a hot restart, the data is neither reset nor restored. All variable values are re-
tained.
2.6 Managing of components

PLCnext Technology is based on components that are included via the “IComponentInter-
face” interface (see Section ““IComponent” and “IProgram”” on page 156).
Application Component The ACF (Application Component Framework) is a part of the system manager and man-
Framework ages the function extensions. The ACF is a framework that enables component-based plat-
form development and configurative composition of the firmware for the devices. It enables
dynamic and configurative integration of user functions into the system. The components
managed by the ACF are thus firmware components and user components that are exe-
cuted independently of the PLC program. The ACF generates the components when boot-
ing the firmware.
For additional information on the ACF, please refer to Section “ACF (Application Compo-
nent Framework)” on page 163.

PLC manager/ One firmware component that is managed by the ACF is the PLC manager (see “PLC man-
Program Library Manager ager” on page 18). It manages the PLC program (real-time user program). The associated
components and libraries that make these user programs available are managed by the
PLC manager via the PLM (Program Library Manager, see 5.4 on page 161). The configu-
ration is executed with a file referenced by /opt/plcnext/projects/Default/Plc/Plm/Plm.config.
The PLC manager generates the components when loading the program.
For additional information on the PLC manager and Program Library Manager, please refer
to Section “PLC manager” on page 18 and ““IComponent” and “IProgram”” on page 156.
Delimitation of ACF and – ACF and PLM use the same ILibrary and IComponent interface (see Section ““ILibrary”
PLM and “LibraryBase“” on page 155 and ““IComponent” and “IProgram”” on page 156).
– ACF and PLM use the same format for configuration files (see Section “Configuration
files” on page 19).
– Only components that are managed via PLM can make programs available that can be
instantiated in ESM tasks (IProgramProvider, see Section 5.2.2 on page 158).
– Only components that are managed via the PLM can be stopped, modified and started
up via download from PLCnext Engineer. This is also the case for ESM tasks and the
programs instantiated therein.
– For components that are managed via the ACF, the firmware must be stopped, the
changed component must be refreshed and after that the firmware must be rebooted.
– Components that are managed via the ACF are retained, even if the PLC program is
shut down, deleted or booted.
2.7 Configuration files

With PLCnext Technology, you can load programs and program instances onto the control-
ler even without using the PLCnext Engineer software. You can, for example, create a pro-
gram in Eclipse® with C++ and transfer it directly to the controller. All of the important and
necessary settings can be configured directly in the configuration files on the controller. The
file system of the controller is accessed via the SFTP protocol. Use a suitable SFTP client
software for this, e.g., WinSCP. The configuration files are XML files. You can edit them
using an editor of your choice. The configuration files are imported after the boot procedure
of the PLCnext Technology firmware. If there are no configuration errors in the configuration
files, the components and program instances are subsequently executed by the ESM.
When PLCnext Engineer is used, all configuration files are created by PLCnext Engineer
and downloaded to the controller.
2.7.1 acf, esm, gds configuration files
acf.config The acf.config and plm.config configuration files contain information on instances of librar-
plm.config ies (shared objects), components and programs, as well as on processes of shared objects
(C++ programs). Both files have the same format.
The information is required by the firmware to load shared objects and to execute compo-
nent instances or programs.
There are two ways to instantiate components:
– Included in Default.acf.config (projects/Default/Default.acf.config). The component is
instantiated when starting the firmware.
– Included in Plm.config (projects/Default/Plc/Plm/Plm.config). The component is instan-
tiated during cold or warm restart of the project.

PLCNEXT TECHNOLOGY
esm.config The esm.config configuration file contains the task configuration, the instantiation of pro-
grams, and assignment to a processor core (one ESM per processor core). For additional
information, please refer to Section “Task configuration via configuration files” on page 25.
gds.config The gds.config configuration file contains the port definition as well as the assignment of IN
and OUT ports. For additional information, please refer to Section “GDS configuration using
configuration files” on page 37.
2.7.2 .tic file
Phoenix Contact recommends creating the .tic files using the PLCnext Engineer software.
The .tic configuration file contains information on the bus configuration with the associated
I/O process data of the IN and OUT ports.
2.7.3 Metafiles
Metadata describes classes and types of components and programs that were created in a
PLCnext Technology application. They are required for using the program in
PLCnext Engineer.
The metafile for the library (*.libmeta) contains links to the metafiles for the incorporated
components (*.compmeta). These, in turn, link to the metafiles of the connected programs
(*.progmeta). The configuration of the GDS data ports (IN or OUT ports) is defined in the
*.progmeta file.
When the PLCnext CLI (PLCnext Command Line Interface, see Section “PLCnext CLI
(PLCnext Command Line Interface)” on page 194) creates the C++ project, the *.comp-
meta, *.libmeta and *.progmeta metafiles are created automatically. The files are inter-
linked, as shown in Figure 2-5.
Figure 2-5 Overview of the metafiles

The LibraryBuilder combines the metadata and the code (*.so) into a library. It can be im-
ported into PLCnext Engineer and used in the same way as an IEC 61131-3 program. Tasks
and flow of data are configured directly in PLCnext Engineer. The PLCnext CLI (see Section
“Functions of the PLCnext CLI” on page 196) generates the metafiles.
Example of a component list and a shared object (*.so) in the *.libmeta metafile:
<?xml version="1.0" encoding="utf-8"?>

<MetaConfigurationDocument
xmlns="http://www.phoenixcontact.com/schema/metaconfig"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
schemaVersion="2.0">
<Library name="CPP_Counter" applicationDomain="CPLUSPLUS" >
<File path="libCPP_Counter.so" />


<ComponentIncludes>
<Include path="CPP_Counter_C/CPP_Counter_C.compmeta" />
</ComponentIncludes>
</Library>
</MetaConfigurationDocument>
Example of a program list in the *.compmeta metafile:

<Component type="CPP_Counter_C" >


<ProgramIncludes>
<Include path="CPP_Counter_P/CPP_Counter_P.progmeta" />
</ProgramIncludes>


<Ports>
<Port name="IP_CppEnable_bit" type="boolean" dimensions="1" attributes="Input|OpcUa"/>
<Port name="IP_CppSwitches_uint8" type="uint8" dimensions="1" attributes="Input"/>
<Port name="OP_CppCounter_uint8" type="uint8" dimensions="1" attributes="Output"/>
</Ports>
-->
</Component>

PLCNEXT TECHNOLOGY
Example of the definition of IN and OUT ports in the *.progmeta metafile:

<Program type="CPP_Counter_P" >
<Ports>
<Port name="IP_CppEnable_bit" type="boolean" dimensions="1" attributes="Input|OpcUa"/>
<Port name="IP_CppSwitches_uint8" type="uint8" dimensions="1" attributes="Input"/>
<Port name="OP_CppCounter_uint8" type="uint8" dimensions="1” attributes="Output"/>
</Ports>
</Program>
2.7.4 Generating configuration files using PLCnext Engineer

The following description applies to all four *.config types (acf.config, plm.config, esm.con-
fig, gds.config). The configuration files are automatically created when the
PLCnext Engineer software is used. During the download, they are saved to the controller
in the respective folder (e.g., /opt/plcnext/projects/PCWE/Plc/Esm for the PCWE.esm.con-
fig file) in the controller file system. This folder is intended for the download from
PLCnext Engineer. The PCWE folder is automatically created and managed by
PLCnext Engineer. Do not store any other files here because PLCnext Engineer com-
pletely deletes this folder prior to the download. When the configuration in
PLCnext Engineer changes and the project is once again downloaded to the controller, the
previous configuration files are overwritten. Manual changes are also lost.
2.7.5 Manual configuration
Note: If you use the Linux command scp without the option -p to copy configuration files
from a Linux PC to the directory /opt/plcnext/projects on the controller, the file permissions
are partly set incorrectly.
You can remedy this by doing the following:
After copying the configuration files, use the Linux command chmod to set the file permis-
sions in such a way that the firmware can delete the configuration files in case of
“Download Changes” (group: “plcnext”, owner: “plcnext_firmware”).
Usually they should be set correctly by using the -p option of the scp command when
copying.
To make manual changes to the configuration files or to create new configuration files, you
can copy the files generated by PLCnext Engineer and rename them. You can then manu-
ally configure these files. To prevent overwriting your own configuration files in the “PCWE”
folder when downloading the project again from PLCnext Engineer, proceed as follows:
• Under /opt/plcnext/projects/ in the file system of the controller, create a new folder and
name it accordingly. E.g., /opt/plcnext/projects/Example/
• Save the files to this folder.
• Include the configuration files via the Include path command (see below example).

The folder can be used for saving additional configuration files and for the manual, configu-
rative extension of the components.
The Include mechanism is used to state which configuration files are to be used for the
configuration. If files are to be included that are not in the folder used for inclusion, the re-
spective path has to be specified. In the following example, all files are included that are in
the same directory as the “Default.gds.config” file, i.e., /opt/plcnext/projects/De-
fault/Plc/GDS (<Include path="*.gds.config” />). If you want to include all config files
that are in the respective folder, replace the specific file name with an * (e.g.
*.gds.config). This results in all files with the same file extension being included.
Example: Include path:
<Includes>
<Include path="*.gds.config" />
<Include path="$ARP_PROJECTS_DIR$/PCWE/Plc/Gds/*.gds.config" />
<Include path="$ARP_PROJECTS_DIR$/Example/*.gds.config" />
</Includes>
In the example, all GDS configuration files from the following directories are included in the
configuration. "$ARP_PROJECTS_DIR$" is a PLCnext Technology environment variable
with the value /opt/plcnext:
– “Default”: /opt/plcnext/projects/Default/Plc/GDS (created by the firmware)
– “PCWE”: /opt/plcnext/projects/PCWE/Plc/GDS (created by PLCnext Engineer)
– “Example”: /opt/plcnext/projects/Example (created by the user)
When editing configuration files, observe the information in Sections “Task configuration
via configuration files” on page 25 and “GDS configuration using configuration files” on
page 37.
2.8 ESM (Execution and Synchronization Manager)

PLCnext Technology also features task handling. The Execution and Synchronization Man-
ager (ESM) performs task handling, monitoring and chronological sequencing of programs
from different programming languages. Each processor core of a controller is managed by
one ESM. One ESM is therefore assigned to one processor core. If a controller has more
than one processor core, then there are also several ESMs (example: controller
AXC F 2152: 2 processor cores and 2 ESMs).
The ESM offers the following advantages:
– Configuration and monitoring of cyclic tasks and idle tasks.
– The execution times of the tasks are available as system variables and can be used for
diagnostics.
– System balancing.
– Multicore systems are supported.
The ESM can also be used to execute programs and program parts in real time that were
created in different programming environments. These can include high-level languages
such as (C++), IEC 61131-3 code, and model-based tools such as Matlab® Simulink®. Pro-
gram parts that were created using different programming languages can also be combined
and processed within a task. The ESM controls the processes and also executes the high-

PLCNEXT TECHNOLOGY
level language programs deterministically in the defined order. To ensure data consistency
between the tasks at all times, all data is synchronized with the GDS whenever a task is
called up (see also Section “GDS (Global Data Space)” on page 29).
Figure 2-6 ESM (Execution and Synchronization Manager)
2.8.1 Task configuration using PLCnext Engineer

You can use the PLCnext Engineer software to easily create and configure tasks. Here, you
can proceed as in a conventional IEC 61131-3 program. The IEC 61131-3 program, or the
program created in a different programming environment and then imported into
PLCnext Engineer, can be instantiated in a task. It does not matter whether the programs
were created with C/C++, IEC 61131-3 or Matlab® Simulink®.
In the PLCnext Engineer “Tasks and Events” editor, you can instantiate a task and assign it
to the desired program instances. A description of this procedure and further information on
task handling with PLCnext Engineer is available in the online help, the PLCnext Engineer
quick start guide (PLCNEXT ENGINEER, Order No. 1046008), and the AXC F 2152 con-
troller user manual (Order No. 2404267). The documentation for the respective products
can be downloaded at phoenixcontact.net/products. You can call the online help from within
PLCnext Engineer.
Figure 2-7 Example: Tasks and program instances in PLCnext Engineer

2.8.2 Task configuration via configuration files
When a project is downloaded from PLCnext Engineer to the controller, the previous con-
figuration files are overwritten with the new configuration files. Section “Manual configura-
tion” on page 22 describes how you can safely store your manually modified configuration
in the controller file system, thus preventing the loss of data.
You can also modify the task configuration, the instantiation of programs and the assign-
ment to a processor core (one ESM per processor core) via configuration files in XML format
without using PLCnext Engineer. All of the important settings can be configured directly in
the configuration file on the controller. To modify the configuration manually, the XML file
can be edited using any editor. The ESM can load one or several configuration files and cre-
ate a joint configuration.
Example of a configuration file:

<EsmConfigurationDocument xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" schemaVersion="1.0" xmlns="http://www.phoe-
nixcontact.com/schema/esmconfig">
<Tasks>
<PreDefinedEventTask name="Cold" eventName="Arp.Plc.Esm.OnColdStart"
confirmed="false" priority="0" watchdogTime="100000000" executionTimeThreshold="0" />
<PreDefinedEventTask name="Warm" eventName="Arp.Plc.Esm.OnWarmStart"
<PreDefinedEventTask name="Except" eventName="Arp.Plc.Esm.OnException"
<IdleTask name="Idle" watchdogTime="100000000" executionTimeThreshold="0" />
<PreDefinedEventTask name="interbus" eventName="Arp.Io.Interbus.OnCycleEnd"
confirmed="true" priority="0" watchdogTime="100000000" executionTimeThreshold="0" />
</Tasks>
<EsmTaskRelations>
<EsmTaskRelation esmName="ESM1" taskName="Cold" />
<EsmTaskRelation esmName="ESM1" taskName="Warm" />
<EsmTaskRelation esmName="ESM1" taskName="Execpt" />
<EsmTaskRelation esmName="ESM1" taskName="Idle" />
<EsmTaskRelation esmName="ESM1" taskName="interbus" />
</EsmTaskRelations>
<Programs>
<Program name="Main1" programType="Main" componentName="Arp.Plc.Eclr" />
</Programs>
<TaskProgramRelations>
<TaskProgramRelation taskName="Cold" programName="Arp.Plc.Eclr/Main1" order="0" />
<TaskProgramRelation taskName="Warm" programName="Arp.Plc.Eclr/Main2" order="0" />
<TaskProgramRelation taskName="Execpt" programName="Arp.Plc.Eclr/Main3" order="0" />
<TaskProgramRelation taskName="Idle" programName="Arp.Plc.Eclr/Main4" order="0" />
<TaskProgramRelation taskName="interbus" programName="Arp.Plc.Eclr/Main5" order="0" />
</TaskProgramRelations>
<TaskEvents />
</EsmConfigurationDocument>
To configure tasks for execution in the ESM (Execution and Synchronization Manager)
using the *.esm.config configuration file, proceed as follows:

PLCNEXT TECHNOLOGY
Defining a task A task is defined between the tags <Tasks> and </Tasks>
Example of defining a task:
<Tasks>
<CyclicTask name="SquareWave_Cycle" priority="0" cycleTime="100000000"
watchdogTime="100000000" executionTimeThreshold="0" />
<CyclicTask name="CPP_Cycle" priority="1" cycleTime="100000000"
<CyclicTask name="PCWE_Cycle" priority="2" cycleTime="100000000"
</Tasks>
<Tasks>
<PreDefinedEventTask name="Cold" eventName="Arp.Plc.Esm.OnColdStart"
</Tasks>
Definition of the task starts with the task type.

• Here, enter the type:
– CyclicTask = Cyclic task
– IdleTask = Idle task
– PreDefinedEventTask = System event task (cold restart, warm restart, hot re-
start, stop, exception)
• Define the tasks using the attributes from the following table:
Attribute Description
name The name attribute defines the task name.
• Enter the task name.
It must be unique. It can only be used once per controller.
priority The priority attribute defines the task priority.
• Enter a value to specify the task priority.
– 0: Highest priority
– 15: Lowest priority
– No priority is indicated for an idle task. It is automatical-
ly lower than the lowest priority.
Within one ESM, each task must be assigned a differ-

ent priority. Two or more tasks in one ESM having the
same priority may lead to unwanted jitter.

cycleTime The cycleTime attribute defines the duration of the task (for cyclic
tasks only).
• Enter the value in nanoseconds.
The minimum value of the AXC F 2152 controller is 1 ms
(1000000 ns). Select a multiple of the minimum value. Depending
on the application, the jitter time for a task may increase as the sys-
tem load increases.
watchdogTime The watchdog monitors whether the task was executed within the
specified time.
• Enter the value in nanoseconds. Value “0” means that there is
no monitoring.
The watchdogTime attribute can be used for cyclic and idle tasks.
EventName The following values are valid for this attribute.
– Arp.Plc.Esm.OnColdStart (cold restart)
– Arp.Plc.Esm.OnWarmStart (warm restart)
– Arp.Plc.Esm.OnHotStart (hot restart)
– Arp.Plc.Esm.OnStop (stop)
– Arp.Plc.Esm.OnException (exception)
Assigning a task Once the task has been defined, it has to be assigned to the desired ESM. Assignment is
defined between the tags <EsmTaskRelations> and </EsmTaskRelations>.
Example: Assigning a task to an ESM
<EsmTaskRelations>
<EsmTaskRelation esmName="ESM1" taskName="SquareWave_Cycle" />
<EsmTaskRelation esmName="ESM1" taskName="CPP_Cycle" />
<EsmTaskRelation esmName="ESM1" taskName="PCWE_Cycle" />
</EsmTaskRelations>
• Assign the task using the attributes from the following table:
esmName The esmName attribute defines the name of the ESM the respective
task is to be assigned to.
• Enter the task name.
Example: ESM1 or ESM2 for a controller with dual core processor.
taskname The taskname attribute defines the task to be assigned.
• Enter the name of the task to be assigned.
Instantiating of programs Once the task is defined and assigned to an ESM, programs can be instantiated. Programs
are defined between the tags <Programs> and </Programs>. The definition of a program
instance is introduced with tag <Program>. Programs that have been programmed in
IEC 61131-3 can only be sent and configured using PLCnext Engineer. The code example
originates from a config file generated using PLCnext Engineer.

PLCNEXT TECHNOLOGY
Instantiating of programs (example):
<Programs>
<Program name="SquareWave" programType="PCWE_SquareWave_P" componentName="Arp.Plc.Eclr" />
<Program name="CPP_Counter" programType="CPP_Counter_P"
componentName="CPP_Counter.CPP_Counter_C-1" />
<Program name="CPP_Counter_P1" programType="CPP_Counter_P"
componentName="CPP_Counter.CPP_Counter_C-1" />
<Program name="PCWE_Counter" programType="PCWE_Counter_P" componentName="Arp.Plc.Eclr" />
</Programs>
• Instantiate programs using the attributes from the following table:
name The name attribute defines the name of the program instance.
• Enter the name of the program instance.
The name must be unique within the controller.
programType The programType attribute defines the program type.
• Enter the program type.
componentName The componentName attribute defines the name of the component
that contains the program.
• Enter the name of the component as it is defined in the
*.acf.config or *.plm.config configuration file. The
“Arp.Plc.Eclr” component is reserved for IEC 61131-3 pro-
grams that were instantiated using PLCnext Engineer.
See Section 6.2.4 “Creating a new C++ project in Eclipse®”
Assigning program in- The program instances have to be assigned to a task. Assignment is made between tags
stances to a task <TaskProgramRelations> and </TaskProgramRelations>.
Assigning program instances to a task:
<TaskProgramRelations>
<TaskProgramRelation taskName="SquareWave_Cycle" programName="Arp.Plc.Eclr/SquareWave"
order="0" />
<TaskProgramRelation taskName="CPP_Cycle" programName="CPP_Counter.CPP_Counter_C-
1/CPP_Counter" order="0" />
<TaskProgramRelation taskName="CPP_Cycle" programName="CPP_Counter.CPP_Counter_C-
1/CPP_Counter_P1" order="1" />
<TaskProgramRelation taskName="PCWE_Cycle" programName="Arp.Plc.Eclr/PCWE_Counter" order="0"
/>
</TaskProgramRelations>

• Assign the program instance to a task using the attributes from the following table.
Attribute Explanation
taskname The taskname attribute specifies the name of the task the program
instance is to be assigned to.
• Enter the name of the desired task the program instance is to
be assigned to.
programName The programName attribute defines the name of the program in-
stance with the prefixed library and component names. The name
is used to select the program instance to be processed in the task.
• Enter the full name in the program instance to be processed.
order The order attribute determines the order in which program in-
stances are processed within a task, starting with 0.
• Enter a number to determine the processing sequence.
The program instance with the digit 0 is processed first. Each num-
ber can only be used once for each task.
2.9 GDS (Global Data Space)

The GDS enables communication relationships and data exchange between tasks and pro-
grams that were created in different programming languages. The GDS also ensures that
inconsistencies as shown in the following example are prevented:
While tasks are being processed and data is being exchanged directly between tasks, read
and write access can overlap due to different cycles and intervals. In the example in
Figure 2-8, task 1 – with medium priority – begins processing and, once completed, outputs
a value. This value is used by task 2 as an input value. Task 2 starts processing using this
input value, and then processing is interrupted by another start of task 1. Task 1 has a
higher priority and is processed again, while task 2 is paused. At the end of processing
task 1, a new value is output that is again sent to task 2 as an input value. Once task 1 is

PLCNEXT TECHNOLOGY
finished, processing of task 2 is continued. However, because the input value has changed
in the meantime, there is a data inconsistency which may lead to problems. The use of the
GDS can prevent such inconsistencies.
Figure 2-8 Example of data inconsistency
2.9.1 Port-based communication

With the GDS, it is easy to establish communication relationships between different pro-
grams. This communication between the PLCnext Technology programs is implemented
via ports. A port presents an endpoint of a component within a PLCnext Technology appli-
cation. Via a port, data can be exchanged with other components (e.g., program instances
and I/O systems). To enable this type of data exchange, the program variables to be ex-
changed or process data of the I/O components are defined as IN or OUT ports.
The data that is written from the tasks to the GDS is written via OUT ports. Tasks that receive
input data read this data from the GDS via IN ports. Using the ports ensures data consis-
tency and correctly functioning communication relationships at all times.

Figure 2-9 Example: Inter-task communication with ESM and GDS
The IN and OUT ports are coupled via buffer mechanisms and synchronized during execu-
tion.
– Start of a task cycle (OnTaskExecuting): The IN ports are read from the GDS buffer by
the program instances to be called in the task.
– End of a task cycle (OnTaskExecuted): The OUT ports are written to the GDS buffer by
the program instances to be called in the task.
The following figure shows the behavior of Task1:
GDS buffer
Figure 2-10 Example: Port communication with Task1 buffer
Data exchange for IN ports and OUT ports takes place at the beginning and at the end of
each task execution. This only concerns data exchange of IN and OUT ports whose pro-
grams have been instantiated in different tasks. Ports within the same task are exchanged
within the task. Furthermore, data exchange is only executed if the program instances are

PLCNEXT TECHNOLOGY
linked via IN and OUT ports. This ensures that the data is always stable and consistent
during execution.
The following figure shows the behavior of Task1 and Task2:
GDS buffer
Figure 2-11 Example: Port communication with Task1 and Task2 buffer
The following applies to the connection of IN and OUT ports:

– OUT ports can be shared within an application. An OUT port can be connected to sev-
eral IN ports.
– An IN port can only be connected to one OUT port.
Further information on connecting ports is available in the PLCnext Engineer online help
(see “Role mapping: Assigning PLCnext ports”).
2.9.2 Fieldbus connection
Connection via IN and OUT ports

In addition to the communication between different tasks, process data from and to field-
buses can also be exchanged via IN and OUT ports. Fieldbus systems also have buffers ,
although these are arranged logically within the fieldbus component itself. Values are writ-
ten to and read from these buffers by the GDS. The fieldbus performs further handling.
Figure 2-12 “Example: Fieldbus communication via IN and OUT ports” shows the behavior
of fieldbus communication via ports.
GDS buffer
Figure 2-12 Example: Fieldbus communication via IN and OUT ports
All components of a PLCnext Technology application that are part of the data exchange as
well as I/O components must be connected via IN and OUT ports. At the beginning of a task,
the task retrieves the data from the buffer. At the end of the task, the calculated values are
actively rewritten to the buffer. Therefore, the buffer is the data exchange area between an
IN port and an OUT port. The IN and OUT port connection between fieldbus components
and tasks shows an analog behavior to the data exchange via ports between several tasks
(see Section 2.9.1 “Port-based communication” on page 30).

By using the IN and OUT ports, the variable values are updated in the task context. The data
is written to or read from the GDS buffer and is available to a task for the entire cycle. Using
the IN and OUT ports secures task-internal data consistency. The fieldbus data is consis-
tent as it comes from the same sampling cycles, and is also consistent within the task cy-
cles. This also applies if programs are interrupted and a fieldbus is updated within this pe-
riod of interruption. The variable value is buffered in the GDS and is available to the task for
the period of time it requires to process all related programs, even with interruption.
When a fieldbus is connected to an ESM task, I/O data can be exchanged via the IN and
OUT ports. For this, declare the variables in the data list of the “PLCnext” node of
PLCnext Engineer as IN or OUT ports. The I/O data is updated in the update cycles of the
ESM task.
Example A cyclic task has an update rate of 30 ms, for example. The user programs of the task con-
Port connection sume the I/O data of the linked I/O variables. The I/O variables are updated at a cycle of
30 ms and are available to the programs. In this way, the programs in the task can also use
the latest values. At the beginning of the task, the data is written from the fieldbus OUT port
to the IN port of the task. At the end of the task, the output data is written to the IN port of the
fieldbus via the OUT port of the task.
Figure 2-13 Fieldbus connection via ports
Connection via resource-global variables
To avoid inconsistent I/O data and the resulting errors, Phoenix Contact recommends to
implement the fieldbus connection via the IN and OUT ports.
Resource-global When creating your application, remember that there is no claim for data consistency when
variables as input using resource-global variables. According to IEC 61131-3, resource-global variables can
be used as an input in all Program Organization Units (POU) of the current resource. Sev-
eral ESM tasks can access the fieldbus I/O data declared as resource-global variables. The
update rate of the resource-global variables always depends on only one task. For the up-
date behavior, an ESM task can be selected. You can make the setting in
PLCnext Engineer:
• Open the respective node in the “PLANT” area for this.

PLCNEXT TECHNOLOGY
• From the “Update task” drop-down list in the “Settings” editor, select the desired task.
Figure 2-14 Selecting “Update task” (in this example: Axioline F)
NOTE: “GLOBALS” task update behavior

If no update task that triggers the update cycle is selected, the GLOBALS task is used
(low priority and update rate of 50 ms). You can set one update task each for the groups
fieldbuses, ESM system variables and the system variables of the web server
(PLCnext Engineer) HMIs.
The priorities in the PLCnext firmware are set to update the I/O of the fieldbuses (Axioline,
PROFINET, INTERBUS, EtherNet/IP, etc.) with the highest priority. Then, ESM tasks are
processed for which a priority has been configured. An exception is the IDLE task; it is pro-
cessed with the lowest priority. The “GLOBALS” task is processed in the priority range
higher than the IDLE task and lower than the other ESM tasks. Other firmware tasks (e.g.,
OPC UA, web server, communication with PLCnext Engineer) are processed with a prior-
ity lower than that of the IDLE task.
Resource-global Usually, resource-global variables are only used once as an output to avoid unintentional
variables as output overwriting of values.
Note: If you use resource-global variables several times as an output, the last value over-
writes the previous values.

Example of fieldbus con- In the example in Figure 2-15, the update rate of the global variable depends on the cycle
nection via resource-glob- time of ESM task 1. The update time of 30 ms for the global variables therefore also applies
al variables to ESM task 2 and other tasks, if applicable. The cycle time of ESM task 2 is 20 ms. Still, it
must process the cycle using the values synchronized by task 1. For task 2, this means that
the data does not exactly correspond to the current process data image of the fieldbus com-
ponents, but that data can be up to 30 ms old.
Figure 2-15 Example: Fieldbus connection via resource-global variables
Interruption of tasks If task 2 from the example in Figure 2-15 has a higher priority than task 1, it might be the
case that task 1 is interrupted by task 2 when updating fieldbus data. Then, task 2, with its
higher priority, is processed. When task 2 is processed, there already is an updated data
image from the fieldbus due to the update rate. The interrupted task 1 is now continued and
accesses the fieldbus data that is still missing. However, this data is not consistent with the
data retrieved before interruption.
Take this behavior into consideration when creating your application. Processing incon-
sistent data can result in errors in the process.
Comparison of connec- Connection via IN and OUT ports:

tions via IN and OUT ports – Fieldbus data is consistent as it was retrieved and written to the buffer at the same time.
and resource-global vari- – Thanks to the GDS buffer, fieldbus data is consistent during task processing.
ables
– The user is not responsible for data consistency as it is ensured via the GDS buffer.

PLCNEXT TECHNOLOGY
– Connecting IN and OUT ports of the task and fieldbus components is complex and less
flexible than using resource-global variables.
To avoid inconsistent I/O data and the resulting errors, Phoenix Contact recommends to
implement the fieldbus connection via the IN and OUT ports.
Resource-global variables:
– At first sight, using resource-global variables seems to be quite easy.
– Update rates and interruptions of tasks due to priority
can result in inconsistencies in the process data image.
– Inconsistent data can result in errors in the application.
– The user is responsible for data consistency, which is not ensured by the system.
2.9.3 GDS configuration with PLCnext Engineer

You can configure the GDS by connecting IN and OUT ports of programs with the
PLCnext Engineer software (see also 9 “Importing libraries into PLCnext Engineer”).
In PLCnext Engineer, select the desired use as an IN or OUT port in the “Data List” editor of
the “PLCnext” node for the respective process data. You can see an overview of all IN and
OUT ports available in the GDS in the “Data List” editor. The programs communicate via the
IN and OUT ports of the GDS. Communication is also possible between IEC 61131-3 pro-
grams and programs that were created using other programming languages (e.g., C++). For
this purpose, the IN and OUT ports must be assigned to one another.
IN and OUT ports are only displayed in the “Data List” editor of the “PLCnext” node.

Figure 2-16 Example: List of all available IN and OUT ports
A detailed description of the procedure and additional information on GDS configuration

with PLCnext Engineer is available in the online help, the PLCnext Engineer quick start
guide (PLCNEXT ENGINEER, Order No. 1046008) and the AXC F 2152 controller user
manual (Order No. 2404267). The documentation for the respective products can be down-
loaded at phoenixcontact.net/products. You can call the online help from within
PLCnext Engineer.
2.9.4 GDS configuration using configuration files
When a project is downloaded from PLCnext Engineer to the controller, the previous
PLCnext Engineer configuration files are overwritten with the new configuration files. Sec-
tion “Manual configuration” on page 22 describes how you can safely store your manually
modified configuration in the controller file system, thus preventing the loss of data.
You can also modify the GDS configuration without PLCnext Engineer, using configuration
files. All of the important settings can be configured directly in the *.gds.config configuration
file on the controller. All configuration files (except *.libmeta) are created by
PLCnext Engineer. To modify the configuration, the XML file can be edited using any editor.

PLCNEXT TECHNOLOGY
You will find the file in the “/opt/plcnext/projects/.../Plc” directory of your controller (see Sec-
tion 2.16.1 “Directories of the firmware components in the file system”). The file system is
accessed via the SFTP protocol. Use a suitable SFTP client software for this, e.g., WinSCP.
The individual connections with their respective IN and OUT ports are defined between the
<Connectors> and </Connectors> tags. A connector is a directed connection from
startPort to endPort. An OUT port is entered as a startPort attribute and an IN port as
an endPort attribute. Within the *.gds.config, each of the ports has its own unique name
that has the following structure:
ComponentInstanceName/GroupName.VariableName
Attribute Explanation
ComponentInstanceName Components of a PLCnext Technology application can be
– Programs
– PROFINET controllers (e.g.,
“Arp.Io.PnC"/"Arp.Io.PnD”)
– The IEC 61131-3 runtime (e.g., Arp.Plc.Eclr.EclrCom-
ponent)
– Or a C++ application, (e.g., Counters.CppCounterCom-
ponent).
Names that start with “Arp...” are specified by the
PLCnext Technology firmware.
The names of the C++ applications are specified by the user
during instantiation.
Exception: When instantiating C++ or Matlab® Simulink®
programs in PLCnext Engineer, the name of the component
instance is specified by PLCnext Engineer.
There can be one or multiple instances of each component.
In the case of a PROFINET device, it is possible to gain ac-
cess by entering the node ID (for more information, please
refer to the online help within PLCnext Engineer).
• Enter the name of the instance here.
GroupName With program instances, the name is specified. The name of
a program instance must be unique within the controller.
• Enter the name of the program instance.
A local bus device is defined based on the position of the de-
vice in the local bus. Position numbering starts with digit 0.
• Enter the position number instead of
GroupName.
VariableName • Enter the name of the IN and OUT ports or the process
data here, depending on the component type.

Examples:
– Program port:
startPort/endPort="Namespace.ComponentInstance/ProgramInstanceA.Frei
gabe"
– Fieldbus port:
startPort/endPort="Arp.Io.AxlC/0.~DO16"
– Component port:
startPort/endPort="ComponentInstance/Freigabe"
There are various types of ports that can be used for data exchange. The port concept can
be used with the following process data:
Description Code with example

Data of the runtime system of the Enter the name of the program instance and the variable name as the port in the fol-
controller lowing format:
runtime system/program instance.variable name
(e.g.: Arp.Plc.Eclr/MainInstance.OUT_PORT_A)
You can use global variables as well as IN and OUT ports.
Data of a high-language project on Enter the name of the program instance as the port and the variable name in the fol-
the controller lowing format (in accordance with the format in the *.acf.config file):
library name.component instance/program instance.variable name
(e.g.: CppCounterLibrary.CppCounterComponent-
1/CppCounterProgram1.IP_CppEnable)
PROFINET process data Enter the name of the PROFINET controller as the port and the process data name in
the following format:
PROFINET Controller/Node-ID.process data name
(e.g.: Arp.Io.PnC/46.~DI8)
Local bus process data Enter the name of the local bus controller as the port and the process data name in the
following format:
Local bus controller/module position.process data name
(e.g.: Arp.Io.AxlC/0.~DO8)
The cycle for updating system variables can also be configured. Resource-global variables
(IEC 61131-3) can be connected with fieldbus variables or variables of other ARP compo-
nents. As these are connections of component-global variables, the events of a perma-
nently defined task (update task) are used for the cyclic update of variable values. You can
configure the update time in PLCnext Engineer:
• Open the respective node in the “PLANT” area for this.

PLCNEXT TECHNOLOGY
• From the “Update task” drop-down list in the “Settings” editor, select the desired task.
Figure 2-17 Selecting “Update task”
You can select an update task for the following variables:
Table 2-1 Update task
Component Variables component tag (config file)

Controller ESM system variables Arp.Plc.Esm
HMI web server HMI system variables Arp.Services.Ehmi
Axioline – Axioline system variables Arp.Plc.AxlC
– Global variables linked to I/O
INTERBUS – INTERBUS system variables Arp.Io.IbM
– Global variables linked to I/O
PROFINET – PROFINET device system variables – Arp.Io.PnD
– PROFINET controller system variables – Arp.Io.PnC
– GlobVars linked to I/O
SPNS Safety and PROFIsafe system variables Arp.Services.SpnsProxy
If you do not explicitly select a task for a component, the “Globals” task is used with a cycle
time of 50 ms (default) (see information box “NOTE: “GLOBALS” task update behavior”
on page 34).
The settings made in PLCnext Engineer are saved to a *.gds.config file and downloaded to
the controller.
The assignment of variables to an update task is made between the
<ComponentTaskRelations> and </ComponentTaskRelations> tags.
Example excerpt from a *.gds.config file. Here, the IN and OUT ports of an application are
assigned to each other:
<GdsConfigurationDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xm-
lns:xsd="http://www.w3.org/2001/XMLSchema" schemaVersion="1.0" xmlns="http://www.phoenixcon-
tact.com/schema/gdsconfig">
<ComponentTaskRelations>

<ComponentTaskRelation component="Arp.Plc.Esm" task="Cyclic100" />

<ComponentTaskRelation component="Arp.Plc.AxlC" task ="Task100ms" />
<ComponentTaskRelation component="Arp.Services.SpnsProxy" task ="Task100ms" />
</ComponentTaskRelations>
<Connectors>
<Connector startPort="Arp.Plc.Eclr/SquareWave.OP_Signal1"
endPort="CPP_Counter.CPP_Counter_C-1/CPP_Counter.IP_CppEnable_bit" />
<Connector startPort="Arp.Plc.Eclr/SquareWave.OP_Signal2"
endPort="Arp.Plc.Eclr/PCWE_Counter.IP_CounterEnable" />
<Connector startPort="Arp.Plc.Eclr/SquareWave.OP_Signal2" endPort="Arp.Io.PnC/20.OUT00" />
<Connector startPort="Arp.Io.PnD/PND_S1_PLC_RUN" endPort="Arp.Plc.Eclr/PND_S1_PLC_RUN" />
<Connector startPort="Arp.Io.PnD/PND_S1_VALID_DATA_CYCLE"
endPort="Arp.Plc.Eclr/PND_S1_VALID_DATA_CYCLE" />
<Connector startPort="Arp.Io.PnD/PND_S1_OUTPUT_STATUS_GOOD"
endPort="Arp.Plc.Eclr/PND_S1_OUTPUT_STATUS_GOOD" />
<Connector startPort="Arp.Io.PnD/PND_S1_INPUT_STATUS_GOOD"
endPort="Arp.Plc.Eclr/PND_S1_INPUT_STATUS_GOOD" />
<Connector startPort="Arp.Io.PnD/PND_S1_DATA_LENGTH"
endPort="Arp.Plc.Eclr/PND_S1_DATA_LENGTH" />
<Connector startPort="Arp.Plc.Eclr/PND_S1_OUTPUTS" endPort="Arp.Io.PnD/PND_S1_OUTPUTS" />
<Connector startPort="Arp.Io.PnD/PND_S1_INPUTS" endPort="Arp.Plc.Eclr/PND_S1_INPUTS" />
<Connector startPort="Arp.Io.AxlC/AXIO_DIAG_STATUS_REG_HI"
endPort="Arp.Plc.Eclr/AXIO_DIAG_STATUS_REG_HI" />
<Connector startPort="Arp.Io.AxlC/AXIO_DIAG_STATUS_REG_LOW"
endPort="Arp.Plc.Eclr/AXIO_DIAG_STATUS_REG_LOW" />
<Connector startPort="Arp.Io.AxlC/AXIO_DIAG_PARAM_REG_HI"
endPort="Arp.Plc.Eclr/AXIO_DIAG_PARAM_REG_HI" />
<Connector startPort="Arp.Io.AxlC/AXIO_DIAG_PARAM_REG_LOW"
endPort="Arp.Plc.Eclr/AXIO_DIAG_PARAM_REG_LOW" />
<Connector startPort="Arp.Io.AxlC/AXIO_DIAG_PARAM_2_REG_HI"
endPort="Arp.Plc.Eclr/AXIO_DIAG_PARAM_2_REG_HI" />
<Connector startPort="Arp.Io.AxlC/AXIO_DIAG_PARAM_2_REG_LOW"
endPort="Arp.Plc.Eclr/AXIO_DIAG_PARAM_2_REG_LOW" />
<Connector startPort="Arp.Io.AxlC/AXIO_DIAG_STATUS_REG_PF"
endPort="Arp.Plc.Eclr/AXIO_DIAG_STATUS_REG_PF" />
<Connector startPort="Arp.Io.AxlC/AXIO_DIAG_STATUS_REG_BUS"
endPort="Arp.Plc.Eclr/AXIO_DIAG_STATUS_REG_BUS" />
<Connector startPort="Arp.Io.AxlC/AXIO_DIAG_STATUS_REG_RUN"
endPort="Arp.Plc.Eclr/AXIO_DIAG_STATUS_REG_RUN" />
<Connector startPort="Arp.Io.AxlC/AXIO_DIAG_STATUS_REG_ACT"
endPort="Arp.Plc.Eclr/AXIO_DIAG_STATUS_REG_ACT" />

PLCNEXT TECHNOLOGY
2.9.5 Supported data types

The programs of a PLCnext Technology application communicate via IN ports and OUT
ports. The combination of the following data types is supported.
When setting the IN and OUT ports with PLCnext Engineer, you can only enter permitted
combinations of data types.
If you implement the configuration without PLCnext Engineer but via the XML configura-
tion file, you have to ensure that only the data type combinations listed in Table 2-2 are
used. If an invalid combination is configured, the startup process of the
PLCnext Technology firmware is interrupted.
Information on the startup behavior of the firmware is available in the Output.log diagnos-
tic file. The file contains status and error messages as well as warning notes that help you
find the source of error. The Output.log file is stored in the controller file system in the
“/opt/plcnext/logs” directory. The file system is accessed via the SFTP protocol. Use a
suitable SFTP client software for this, e.g., WinSCP (see Section ““Template Loggable””
on page 169).
2.9.5.1 Elementary data types
Table 2-2 Supported data type combinations of C++, Simulink® and PLCnext Engineer programs
C++ Simulink® PLCnext Engineer Use in array data type Use in struct data type
Boolean Boolean BOOL  
int8 int8 SINT  
uint8 uint8 USINT  
int16 int16 INT  
uint16 uint16 UINT  
int32 int32 DINT  
uint32 uint32 UDINT  
int64 LINT  
uint64 ULINT  
uint8 uint8 BYTE  
uint16 uint16 WORD  
uint32 uint32 DWORD  
uint64 LWORD  
float32 single REAL  
float64 double LREAL  
Array of primitive data types 

The following data type combinations between C++ programs are supported:
Table 2-3 Supported combinations of IN and OUT ports between C++ programs
StartPort EndPort StartPort EndPort

uint64
Boolean int32
uint8 uint16 int64
uint16 float32
uint32 float64
uint64
char8 uint32
Boolean
int8 uint64
uint32
int16 int64
int32 float64
int64
float32 uint64 uint64
float64
int8
char8 int16
uint16 int32
int8
uint32 int64
uint64 float32
char8 int16 float64
int32
int64 int16
float32 int32
float64 int16 int64
float32
uint8 float64
uint16
uint32 int32
uint64 int32 int64
uint8 int16 float64
int32
int64 int64 int64
float32
float64 float32
float32
float64
uint16
uint16
uint32 float64 float64
2.9.5.2 Connection of structures

In addition to connecting elementary data types and arrays, the GDS also enables the con-
nection of entire structures. Structures are data types that can exist of elements of different
data types. The design of structures can be freely defined.

PLCNEXT TECHNOLOGY
A StructConnector is used for connecting two struct ports. A StructConnector is a manage-

ment object that is used to implement the connection of complete structures and the actual
data transport. The connection logic of two struct ports therefore contains a comparison
based on type definitions. It is checked whether the size of the structure, the data type, the
offset, the dimensions and the number of elements match. It is also checked if the alignment
of the individual struct members is consistent. This is important for determining the binary
compatibility of the structures. The check is implemented without the names of the individ-
ual struct members.
Complete copying The firmware completely copies the structures via memcpy(). Binary compatibility of the
type definitions is required for this method.
To compare the size of the structure types and subsequently, the data types and offsets of
the individual structure fields, a type check is run.
Below figure shows the connection of structures between tasks. Here, the communication
between two programs is implemented via a type “SampleStruct” port.
Figure 2-18 Connection of structures

2.10 RSC (Remote Service Calls)

Function extensions can communicate with the PLCnext Technology core components via
the RSC interface. You can access various functions and data items via the interfaces. For
example, you can gain read and write access to GDS data using the “IDataAccessService”
RSC service.
Figure 2-19 PLCnext Technology - RSC services
ServiceManager You have the option of using the already registered RSC services of the SDK (Software De-
velopment Kit) via the ServiceManager. The ServiceManager acts as the RSC API and is
used to request services.
For additional information on using RSC services, please refer to Section 5.8, “Using RSC
services”.
2.11 PLCnext embedded OPC UA server (eUA)
2.11.1 OPC UA
OPC Unified Architecture (UA) is a standardized protocol for industrial IT and OT commu-
nication. On request, an OPC UA server provides an OPC UA client with process data and
variable values from a running application.
The PLCnext controllers contain an embedded OPC UA server (eUA). In addition to the run-
time, it is integrated in the controller. It enables access to components, programs, function
blocks, structures and variables of PLCnext Technology.
2.11.2 Configuration
If a controller features an integrated OPC UA server, it is displayed in the PLCnext Engineer
software in the “PLANT” area (”OPC UA”). Here, you can configure the OPC UA server. The
configuration is loaded to the controller as part of a PLCnext Engineer project and in form of

PLCNEXT TECHNOLOGY
a configuration file. It contains all parameters for setting the OPC UA server. All users of an
OPC UA must authenticate themselves to the OPC UA server with a user name and a pass-
word. You can create a user via the WBM of the controller (see Section “Web-based man-
agement (WBM)” on page 91). In the course of this, you have to assign the necessary roles:
– DataViewer
– DataChanger
– FileReader
– FileWriter
For additional information on user roles, please refer to Section ““User Authentication”
page” on page 109.
For further information on configuring OPC UA in PLCnext Engineer, please refer to the
PLCnext Engineer online help.
With PLCnext Engineer, the following configurations are possible:

– Defining the server endpoint URI
Define the name of the network node the eUA server is to use in the server URI and in
the endpoint URL.
– Defining a Global Discovery Server:
Define which certificate the server is to use.
– Visibility of variables and alarms for the OPC UA clients:
Due to security reasons, the variables and ports of a program in PLCnext Engineer are
set to not visible by default. Visibility is set in your PLCnext Engineer project. In the
“PLANT” area, open the “OPC UA” node and open the “Basic settings”. Via the “Visibil-
ity of variables” drop-down list, you can set the visibility of variables and alarms for the
OPC UA clients.
Figure 2-20 Setting the visibility of variables
– Privilege settings for data access:

You can configure access of clients to the file system of the server. Read and write ac-
cess for clients to selected folders and files in the file system of the server as well as
creating additional directories and files are possible. Once this option is active, only
PLCnext Technology users with a “FileReader” or “FileWriter” role can read or write
files. The required roles are assigned to the user in the WBM of the controller (see Sec-

tion ““User Authentication” page” on page 109).

The OPC UA server accesses the Linux file system as the “plcnext_firmware” Linux us-
er. It makes no difference which firmware user (WBM) you use to log in as the OPC UA
client, or whether you have deactivated user authentication. All the files and directories
are created as “plcnext_firmware”.
2.11.3 OPC UA file access

All directories and files are displayed in the http://phoenixcontact.com/OpcUA/Files/ name-
space in a tree structure. Via the namespace, the corresponding “NamespaceIndex” can be
determined from the “NamespaceArray”. The “NamespaceIndex” is a numeric value for
identification of the namespace. It is saved in the “NamespaceArray”. Via the “Namespa-
ceIndex” and the “NodeIdentifier”, the released data and directories can be retrieved.
The initial entry point for released directories and files is the “FileSystem” folder of type
“FolderType”. In this folder, released files and directories are displayed in a tree structure,
starting with the symbolic folder indicated in the config file. The nodes are not stored recur-
sively in order to save system resources. This means that not all nodes are loaded directly
upon startup. The next level is only loaded once the OPC UA client opens a node.
File access must be configured and enabled in PLCnext Engineer.
Figure 2-21 “FileSystem” folder
The “NodeIdentifier” is structured as follows:

[Symbolic name]|[directory name]/[file name]

PLCNEXT TECHNOLOGY
Example: OpcUa|OpcUa/Doc/doc.config
Figure 2-22 “NodeIdentifier” structure
2.11.4 Alarms
You can exchange alarm and status messages between a program and the eUA server. For
additional information, please refer to Section “Alarms” on page 53.
2.11.5 Subscriptions
An OPC UA client can subscribe to a list of variables that are then monitored for changes by
the GDS. The variables are checked for changes at a defined interval. If a changed variable
is detected during the cyclic check, the GDS informs the OPC UA server, which forwards
the message to the client. When subscribing to a variable, the client can define a sample
rate, which is then served by the server. You can choose from predefined sample rates.
Sample rates are device-specific. The sample rates for the AXF F 2152 controller are de-
fined as follows, for example:
– 100 ms
– 250 ms
– 500 ms
– 1000 ms
– 2000 ms
– 5000 ms
If an OPC UA client requests a variable with the desired rate of, 600 ms, for example, it will
be assigned to the “500 ms” group. The server assigns the subscription to the group nearest
to the desired value and returns this value to the client as “RevisedSamplingInterval”.

2.11.6 “GlobalDataSpace” namespace

All programs and variables from the IEC 61131 context are displayed in the http://phoenix-
contact.com/OpcUA/PLCnext/GlobalDataSpace/ namespace. Via the namespace, the cor-
responding “NamespaceIndex” can be determined from the “NamespaceArray”. The
“NamespaceIndex” is a numeric value for identification of the namespace. It is saved in the
“NamespaceArray”. Via the "NamespaceIndex” and the "NodeIdentifier", a corresponding
process variable, structure or function block can be retrieved. The “NodeIdentifier” is always
structured as follows:
[component name]/[program name].[variable name]
Example: Arp.Plc.Eclr/PG_AllTypes1.DIntVar
Figure 2-23 “Arp.Plc.Eclr/PG_AllTypes1.DIntVar”

PLCNEXT TECHNOLOGY
Figure 2-24 “Arp.Plc.Eclr/PG_AllTypes1.DIntVar” (Software: UA Expert)
The component name for C++ components is defined in the respective C++ project. It there-
fore differs from the component name from the IEC 61131 context (“Arp.Plc.Eclr”).
2.11.7 Device Integration (DI) namespace

In compliance with the “OPC UA for Devices” OPC UA Companion Specification, the eUA
server provides the following nodes:
Table 2-4 Device Integration node
Node Meaning
DeviceManual Path or URL to the user manual.
Note: The eUA server does not support this node.
Default value: Empty string
DeviceRevision General revision status of the device.
Note: The eUA server does not support this node.
Default value: Empty string
HardwareRevision Hardware revision status, e.g., 02.
Manufacturer Device manufacturer, e.g., “en”, “Phoenix Contact”
Model Name of the model, e.g., “en”, “AXC F 2152”

Table 2-4 Device Integration node

Node Meaning
RevisionCounter Revision status of the static device data, e.g., 2
SerialNumber Device serial number, e.g., 13254768
SoftwareRevision Software version number
e.g., 2019.0 LTS (19.0.0.15906)
2.11.8 Data types

For a mapping table containing the PLCnext Technology data types and the corresponding
OPC UA data type, see Section “Available data types” on page 235.
2.11.9 UA server endpoints

The eUA server offers an endpoint to which the clients can connect. In its URL, you can ei-
ther configure the IP address of the controller or the DNS name. Implement the configura-
tion in the PLCnext Engineer software:
• In PLCnext Engineer, open the “OPC UA” node in the “PLANT” area.
• In the “Basic settings”, either enter the DNS name or the IP address in the input field.
Figure 2-25 Endpoint configuration
2.11.10 Encryption algorithms

You can offer the following encryption algorithms for the endpoints to the OPC UA clients:
– Basic 128 RSA15
– Basic 256
– Basic 256 SHA256
By default, the “Basic128Rsa15” encryption algorithm is not activated as this algorithm is

no longer regarded as secure. However, you can activate this algorithm to be able to con-
nect the eUA server to older OPC UA clients that at most support this algorithm.
2.11.11 Ethernet ports at the controller

Currently, there is no mapping to a certain Ethernet port at the controller. Therefore, a con-
nection is possible via all connections.

PLCNEXT TECHNOLOGY
2.11.12 Disabling user authentication

You can also work without security settings. To this end, deactivate the user authentication
via the web-based management of your controller. For a description as well as safety notes,
see Section 3.9.1 on page 109. When user authentication is disabled, the OPC UA client
does not have to authenticate itself to the OPC UA server. This way, unrestricted access to
the OPC UA server is possible.
2.11.13 OPC UA Historical Data Access (HDA)

Standard OPC UA HA enables the OPC UA clients to access the historical data of the
PLCnext Technology DataLogger. You can call selected variables from a database using
OPC UA HA. To use OPC UA HA for the data of GDS variables, the variables must be pres-
ent in at least one DataLogger session (for further information on the DataLogger, please
refer to Section “DataLogger” on page 67). Please note that only scalars and strings are
supported. If a variable is present in more than one DataLogger session, the session with
the smallest sampling interval will automatically be used.
OPC UA server The OPC UA server capabilities provide the OPC UA client with information on the server
capabilities properties and possibilities. The OPC UA client can access the server capabilities in the in-
formation model of the OPC UA server. The HA-specific OPC UA server capabilities (Histo-
ryServerCapabilities) provide information on access to the historical data. The
AccessHistoryDataCapability node is TRUE. Any other nodes are FALSE. Additional
information is available for the OPC UA client via a ServerCapabilityIdentifier. The HD
(Historical Data) entry informs the OPC UA client about historical data being provided.
OPC UA AccessLevel For GDS variables that are present in a DataLogger session, the HistoryRead bit in the
AccessLevel or UserAccessLevel OPC UA attribute is TRUE. In this way, the historical
data is available and can be read via the OPC UA server.
Retrieving historical data The OPC UA server implements the ReadRaw function in accordance with “OPC UA Speci-
fication 1.03 Part 11”. The ReadRawModified service can be used to retrieve the historical
data. Section 6.4.3 of the specification describes the service. The ReadModified function
is not supported, as only raw data can be read. The isReadModified parameter must
therefore be FALSE.
The following parameters of the ReadRawModified are supported in accordance with the
OPC UA specification:
Parameter Description
ReadRawModifiedDetails Specifies the request of historical data
startTime Start time for the period of data retrieval
endTime End time for the period of data retrieval
numValuesPerNode Maximum number of values that is to be returned for
each node within the period.
Value 0 = No maximum value specified
returnBounds TRUE = Limit values are to be returned
FALSE = Any other cases
Further information, application examples, and error codes can be found in the OPC UA
specification.

2.12 Alarms
In PLCnext Technology, alarms are mapped as messages informing about status changes
in the controller.
The alarms can be transmitted between different components. Possible alarm sources are
the IEC 61131 alarm blocks, but also programs written in C++ or Matlab® Simulink®. A typ-
ical alarm recipient is the OPC UA server, which forwards the messages as OPC UA alarms
to interested OPC UA clients. However, alarm clients that react to alarm messages can also
be written in C++.
Alarms are defined by a complex status. All status changes are sent as a message by the
alarm source. As the status changes are forwarded as OPC UA alarms, the statuses arise
from the definition in the OPC UA specification.
Essential features of the alarm status are:
– Active – The alarm condition is active.
– Acknowledged – The user has seen the alarm condition.
– Confirmed – The user has solved the problem that led to the alarm.
– Severity – Severity of the alarm (from 1 = information to 1000 = severe error).
– Retain – The alarm is to be shown to the user (evaluated by the client).
– Message – Message to be shown to the user.
– AlarmType – Alarm type (can be used for filtering in the client)
– AlarmId – Unique name of the alarm on the device
– Timestamps for a variety of substatuses can be set as an option.
To introduce an alarm to the system, it first has to be registered. This has to be done before
the first use. As a result, you can see in the OPC UA server which alarms can occur.
It is not possible to cancel alarms. However, they are deleted during each cold and warm
restart. This is why alarms have to be registered after each cold or warm restart. Registering
an alarm twice does not trigger an error message.
Some alarms must be acknowledged and sometimes even confirmed. To do so, the “Ac-
knowledge” and “Confirm” methods can be used. These are also messages in
PLCnext Technology. However, they are sent from a client to the alarm source. The alarm
source must process this message. Usually, this results in a new alarm status which, as
usual, is sent to all clients.
Often there is the requirement to add additional information to an alarm, which is available
in the client and can be displayed in the message. For this, there are alternative alarm
blocks that can take on a structure with additional parameters. These parameters must be
entered during registration so that they are known to the client. In the message, the param-
eters can be referenced using placeholders. The following placeholders are supported:
Table 2-5 Placeholders for additional parameters
Placeholder Meaning
{0} Alarm name
The name must be unique within the controller.
{1} Alarm type
{2} First user parameter
{3} Second user parameter

PLCNEXT TECHNOLOGY
The “ALM_ALARM” and “ALM_ALARM_PARAM” function blocks implement defined se-

mantics of the alarms. Via “Requires Acknowledge” and “Requires Confirm”, you can only
specify if the alarm is to be acknowledged or confirmed. For more complex scenarios, you
can write your own alarm blocks. This way you can, for example, check additional condi-
tions, implement a different time behavior or implement several alarms with one block. For
these tasks, the “ALM_CUSTOM_ALARM” block is available. It provides the “Low Level”
methods that were used for implementing the other blocks. The same functions are also
available in C++.
2.12.1 IEC 61131 alarm function blocks

The alarm function blocks are contained in the “PLCnext Controller” library.
Figure 2-26 “Alarming” function blocks
There are three types of alarm function blocks:

1. Standard alarm blocks (“ALM_REGISTER”, “ALM_ALARM”)
2. Blocks with user parameters (“ALM_REGISTER_PARAM”, “ALM_ALARM_PARAM”)
3. User-defined alarm blocks (“ALM_CUSTOM_ALARM”)
Alarm blocks use the “ALM_ALARM” structure for internal data storage. It is used by the
blocks and does not have to be described outside the block.
Standard alarm blocks To register an alarm, you can use the “ALM_REGISTER” function block. A rising edge or
constant TRUE signal at the input introduces the alarm to the system. This function block
must be called until the “DONE” output delivers a TRUE signal. If many alarms are regis-
tered at the same time, a FALSE signal might occur.

Several alarms can be registered in the same PLC cycle. However, if the “DONE” output
outputs a FALSE signal, the registration can only be continued during the next cycle.
Figure 2-27 “ALM_REGISTER” function block
To send alarm statuses, you can use the “ALM-ALARM” function block. With each change
of the “ACTIVE” input, the new status is sent to the OPC UA server. This function block must
be called until the “DONE” output outputs a TRUE signal. If many alarms are transmitted at
the same time, a FALSE signal might occur. In this case, the call must be tried again in the
next cycle.
The “AUTO_ACK” and “AUTO_CONF” inputs can be used to control if alarms require
acknowledgement or confirmation. If both inputs are set to TRUE, the alarm will disappear
as soon as the condition at the “ACTIVE” input changes to FALSE again.
If acknowledgement or confirmation is desired, the function block has to process these re-
quirements. It is therefore required that the function block is called continuously so that it
can internally process these messages.
Figure 2-28 ALM_ALARM function block

PLCNEXT TECHNOLOGY
Blocks with user parame- To send user-defined parameters together with an alarm, you can use extended function
ters blocks:
The user-defined parameters have to be introduced to the server via a structure. You can
define and use a structure of up to ten parameters. The parameters must each have an el-
ementary data type. For “ALM_REGISTER_PARAM”, the names and types of the structure
components are taken from the data type definition (worksheet) as names and types for the
parameters. For the “ALM_ALARM_PARAM” function block, the values from the structure
are transmitted with the alarm status.
Figure 2-29 “ALM_REGISTER_PARAM” function block
Figure 2-30 “ALM_ALARM_PARAM” function block

User-defined alarm blocks Use the “ALM_CUSTOM_ALARM” function block to create your own alarm blocks. This
might be useful if special timing or a specific filter is required, for example. In addition, you
can use the user-defined alarm block to set another semantics of “ACK”, “CONF” or
“RETAIN” or implement several alarms in a combined function block.
The “ALM_CUSTOM_ALARM” function block allows for access to methods of the subordi-
nate alarm system. All methods are implemented as methods of the block.
Figure 2-31 Methods of the “ALM_CUSTOM_ALARM” function block
The following methods send the corresponding messages to the OPC-UA server:
– “SendAcknowledge”
– “SendAddAlarm”
– “SendConfirm”
– “SendStateChange”
Use the following methods to determine if the function block has received the “Acknowl-
edge” or “Confirm” wish:
– “ShouldAcknowledge”
– “ShouldConfirm”
Acknowledging and con- Instead of the OPC UA server, you can also use the “ALM_ACK” and “ALM_CONF” function
firming alarms blocks to acknowledge and confirm any alarm. The alarms are clearly identified by the
“ALARM_ID”.
Figure 2-32 “ALM_ACK” and “ALM_CONF” function blocks

PLCNEXT TECHNOLOGY
2.12.2 Alarms in C++ programs

For programming in C++, the PLCnext Technology SDK provides the “AlarmAccess” class.
It can be used for alarm sources and alarm sinks.
During initialization of PLCnext Technology, the “AlarmAccess” class should be instantiated
and initialized (e.g., in “SetupConfig” of a PLCnext Technology component). C++ programs
can use the instance to send alarms. Using one instance for all alarms makes sense as
many “AlarmAccess” instances would result in a correspondingly large number of mes-
sages in PLCnext Technology, which would strain the system.
The classes can be included using the following headers:
#include "Arp/System/NmPayload/Alarms/AlarmAccess.hpp"
#include "Arp/System/NmPayload/Alarms/AlarmState.hpp"
#include "Arp/System/NmPayload/Alarms/AlarmUserParameter.hpp"
The alarm classes are contained in the Arp::System::NmPayLoad::Alarms namespace. To

use a class, you must create an instance and call the Init method.
using namespace Arp::System::NmPayload::Alarms;
AlarmAccess alarmAccess;
alarmAccess.Init("PHOENIX.CppClient");//unique name for this AlarmAccess instance
The following methods are used for sending messages:

/// Announce a new alarm to the server (e.g. for browsing in OPC UA).
/// the following fields are used:
/// alarmId is a unique name of the alarm instance on the server
/// alarmType is a name of the subtype of DiscreteAlarmType that is generated as a result of
/// this method call
/// severity is a number between 1 and 1000 where 1 is informative and 1000 is a fatal error
/// the user parameters with name and type are mapped to variables of the new AlarmType
/// returns 0 if successful, -1 if not initialized, -2 if empty string parameters
int32 AddAlarm(AlarmState& alarmState);
/// Inform the AlarmServer about a new alarm state

/// (coming alarms, going alarms / changes to sub states).
/// An alarm source can inform about state changes of its alarms.
/// Only the source should call this methods for its alarms.
/// returns 0 if successful, -1 if not initialized, -2 if empty alarmId
int32 NewAlarmState(AlarmState& alarmState);
/// A client can ask for acknowledgement of an alarm instance (if supported by an alarm).
int32 Acknowledge(const String& alarmId);
/// A client can ask for confirmation of an alarm instance (if supported by an alarm).
int32 Confirm(const String& alarmId);
You can use these methods to receive messages:
/// An alarm source the supports acknowledgable alarms should subscribe to

/// acknowledge request by a client.
/// As a result to a call of the handler function the alarm source might change
/// the state of the alarm and call NewAlarmState again.
/// Note: The provided handler function is called by a different thread!
/// returns 0 if successful, -1 if not initialized, -2 no handler function
int32 SubscribeAcknowledge(std::function<void(const String& alarmId, const String& comment, const

String& language, const String& user)> handler);
/// An alarm source the supports confirmable alarms should subscribe to confirm request by a client.
/// As a result to a call of the handler function the alarm source might change
/// the state of the alarm and call NewAlarmState agein.
int32 SubscribeConfirm(std::function<void(const String& alarmId, const String& comment, const
String& language, const String& user)> handler);
/// A client can subscribe to AddAlarm calls

/// (used e.g. by the OPC-UA Server to show the alarms in the address space).
int32 SubscribeAddAlarm(std::function<void(const AlarmState& alarmState)> handler);
/// A client can subscribe to NewAlarmState calls to track the state of alarms.
int32 SubscribeNewAlarmState(std::function<void(const AlarmState& alarmState)> handler);
The alarm status is held in the “AlarmState” structure:

// State with sub states of an alarm.
class AlarmState
{
public:
// unique Id of the alarm instance within the PLC
String AlarmId;
// type of the alarm. Use as key to lookup a localized text for the alarm message.
String AlarmType;
// optional message (if Message is empty the AlarmType is the key retrieval of a translated message)
String Message;
// indication if the alarm condition is true
bool ActiveState;
// timestamp for the last change of ActiveState
DateTime ActiveStateChanged;
// acknowledged state of the alarm (the user has seen the alarm)
bool AckedState;
// timestamp for the last change of AckedStateChanged
DateTime AckedStateChanged;
// confirmed state of the alarm (the user has resolved the problem)
bool ConfirmedState;
// timestamp for the last change of ConfirmedStateChanged
DateTime ConfirmedStateChanged;
// the server wants to hide the alarm
bool SuppressedState;
// timestamp for the last change of SuppressedState
DateTime SuppressedStateChanged;
// severity between 1 and 1000 (1 = information; 1000 = fatal error)
int16 Severity;
// true to indicate that the alarm should be displayed to the client
bool Retain;
// timestamp for the last change of RetainChanged
DateTime RetainChanged;
// timestamp for the last change of AlarmChanged
DateTime AlarmChanged;
// User parameters
std::vector<AlarmUserParameter> UserParameters;
};

PLCNEXT TECHNOLOGY
2.12.3 OPC UA server

The OPC UA server is the typical interface for accessing alarms. Here, alarm messages are
mapped to OPC UA alarms.
Registered alarms In the OPC UA Address Space, you will find the alarms in the “Root/Objects/Server/Alarms”
node. Here, all registered alarms are displayed with their alarm ID. Below, you will see the
alarm status, with “ActiveState”, “AckedState” or “Retain” as OPC UA properties.
Alarm types The alarm types are written as subtypes of the “DiscreteAlarmType”. You will find them in
the OPC UA Address Space under “Root/Types/EventTypes/BaseEventType/Condition-
Type/AcknowledgeableConditionType/AlarmConditionType/DiscreteAlarmType”.
Subscribing to events If you wish to be notified about alarm status changes, you can create an OPC UA subscrip-
tion and subscribe to the “Root/Types/EventTypes/BaseEventType/ConditionType/Ac-
knowledgeableConditionType/AlarmConditionType/DiscreteAlarmType” object. The sub-
scription will then send events about all alarm status changes.
Acknowledging and con- Alarms are acknowledged and confirmed via the standard OPC UA alarm function. Note
firming of alarms that the status change takes place in the alarm source (e.g., in the PLC program). Only after
the alarm source has implemented the request for acknowledgement/confirmation, the
OPC UA server will send the new event with the updated state (“AckedState” = TRUE, or
“ConfirmedState” = TRUE).
Filtering of alarms During OPC UA subscription, you can specify which alarm properties are to be sent with the
event. Here, you can also include the user parameters, so that these values are transmitted
consistently with the alarm from the source to the client.
2.13 Notification manager

The Notification Manager enables sending and receiving notifications between compo-
nents of a controller. Notifications are messages referring to special events. They are iden-
tified via a name and can transport user data (payload). User data is information data with-
out control or protocol information (no process data, no real-time requirements). Both the
PLCnext Technology firmware and user-defined components can send notifications.
A sender can register a notification with a notification name with the Notification Manager
and thus make it known. Then, it can send notifications. One or several recipients subscribe
under one notification name and receive all notifications that are published under this or a
subordinate name. Notification names are structured hierarchically. When a part of the

name is indicated, all subordinate notifications can be received. Communication can be

from one component to one or several recipients. As a basis, the Notification Manager uses
RSC services to transmit messages between the components.
Figure 2-33 Notification Manager
The Notification Manager is suitable for the following scenarios, for example:
– Network settings have been changed
– Network interface up/down (link up/link down: connection established/interrupted)
– New component added
– Recognized error, exception in one component
For additional information on using the Notification Manager in a C++ component, please
refer to Section “Notifications” on page 171. Table 5-15 shows which user role is authorized
to what extent to call the methods of the INotificationLoggerService. User roles not con-
tained in this table do not have access permission. For additional information on user roles,
please refer to Section ““User Authentication” page” on page 109.

PLCNEXT TECHNOLOGY
2.13.1 Notifications of the PLCnext Technology firmware

Table 2-6 Notifications triggered by the firmware
NotificationName SenderName Severity PayloadTypeName PayloadString
Arp.Device.Interface.Ether- Device interface Info Arp::System::NmPayload::Device::Ether- Link state changed: interface {number},
netLinkStateChanged netLinkStatePayload port {number}, status: {"Up"|"Done"}
Arp.Device.Interface.Exten- Device interface Info Arp::System::NmPayload::Device::PciDe- Extension device status: {"OK"|"Diagno-
sionModulesState viceStatePayload sis"|"Error"}
Arp.Device.Interface.Net- Device interface Info Arp::System::NmPayload::Device::Net- Configuration of network interface {num-
workConfigurationChanged workConfigurationChangedPayload ber} changed: {Parameter} = {Value}
Arp.Device.Interface.Net- Device interface Error Arp::System::NmPayload::Device::Net- Configuration of network interface {num-
workConfigurationFailed workConfigurationChangedPayload ber} failed: {Parameter} = {Value}
Arp.Device.Interface.Sd- Device interface Info Arp::System::NmPayload::Device::Sd- sd card state changed: sdCardId {"1"},
CardStateChanged CardStateChangedPayload state {"true"|"false"}
Arp.Io.PnC.ArAbort Arp.Io.PnC Info Arp::System::NmPayload::Io::Profinet- Connection to device aborted: {station-
Stack::MessageWithStationNamePayload Name}
Arp.Io.PnC.ArReady Arp.Io.PnC Info Arp::System::NmPayload::Io::Profinet- "Connection to device established: {Sta-
Stack::MessageWithStationNamePayload tionName}" |
"Connection to device with differences es-
tablished: {StationName}"
Arp.Io.PnC.PnStationStat- Arp.Io.PnC Internal Arp::System::NmPayload::Io::Profinet- Led state changed: Arp.Io.PnC (Control-
eChanged Stack::PnStationStatePayload ler), BF={"On"|"Off"}, SF={"On"|"Off"}
Arp.Io.PnC.ResetToFacto- Arp.Io.PnC Info Arp::System::Nm::StringPayload This station is reset to factory defaults.
ryDefaults
Arp.Io.PnC.SetInterfaceAd- Arp.Io.PnC Info Arp::System::NmPayload::Io::Profinet- Interface address changed to: IP=x.x.x.x
dress Stack::InterfaceAddressPayload Netmask=x.x.x.x Gateway=x.x.x.x IsVola-
tile={"true"|"false"}
Arp.Io.PnC.SetStationName Arp.Io.PnC Info Arp::System::NmPayload::Io::Profinet- The station name is set to: {StationName}
Stack::MessageWithStationNamePayload
Arp.Io.PnS.SystemConfi- Arp.Io.PnS Warning Arp::System::Nm::StringPayload The PROFINET system config file was cor-
gRestored rupt and has been restored. PROFINET
settings (e.g. station name) were reset to
factory defaults.
Arp.Io.PnD.ArAbort Arp.Io.PnD Info Arp::System::Nm::StringPayload "Connection to device established: {Sta-
tionName}" |
"Connection to device with differences es-
tablished: {StationName}"
Arp.Io.PnD.ArReady Arp.Io.PnD Info Arp::System::NmPayload::Io::Profinet- Connection to device aborted: {station-
Stack::MessageWithStationNamePayload Name}
Arp.Io.PnD.PnStationStat- Arp.Io.PnD Internal Arp::System::NmPayload::Io::Profinet- Led state changed: Arp.Io.PnD (Device),
eChanged Stack::PnStationStatePayload BF={"On"|"Off"}, SF={"On"|"Off"}
Arp.Io.PnD.ResetToFacto- Arp.Io.PnD Info Arp::System::Nm::StringPayload This station is reset to factory defaults.
ryDefaults
Arp.Io.PnD.SetInterfaceAd- Arp.Io.PnD Info Arp::System::NmPayload::Io::Profinet- Interface address changed to: IP=x.x.x.x
dress Stack::InterfaceAddressPayload Netmask=x.x.x.x Gateway=x.x.x.x IsVola-
tile={"true"|"false"}
Arp.Io.PnD.SetStationName Arp.Io.PnD Info Arp::System::NmPayload::Io::Profinet- The station name is set to: {StationName}
Stack::MessageWithStationNamePayload
Arp.Plc.Domain.PlcMan- PLC Info Arp::System::NmPayload::Plc::PlcStat- Plc state changed:
ager.StateChanged eChangedPayload {"None"|"Ready"|"Stop"|"Run-
ning"|"Halt"|"Changing","Warning"|"Er-
ror"|"SuspendedBySwitch"|"DcgNotPossi-
ble"|"DcgRealTimeViolation"} ==>
{"None"|"Ready"|"Stop"|"Run-
ning"|"Halt"|"Changing","Warning"|"Er-
ror"|"SuspendedBySwitch"|"DcgNotPossi-
ble"|"DcgRealTimeViolation"}

Table 2-6 Notifications triggered by the firmware

NotificationName SenderName Severity PayloadTypeName PayloadString
Arp.Plc.Esm.Excep- Arp.Plc.Esm Error Arp::System::NmPayload::Plc::Exception- Exception Information typeId={} subTy-
tion.Arp.Plc.Esm InformationPayload peId={} subType={} taskName={} program-
Name={} information={} extendedInforma-
tion={}
Arp.Plc.Gds.ForceMan- Gds Info Arp::System::NmPayload::Plc::ForceInfor- Force mode changed: {"Enabled" | "Dis-
ager.ModeChanged mationPayload abled"}
Arp.Plc.Plm.DcgNotPossible ProgramLibrary- Info Arp::System::Nm::StringPayload DownloadChanges not possible, because
Manager configuration of C++ libraries differs.
Arp.Plc.Retain.RetainMan- RetainManager Error Arp::System::Nm::StringPayload Maximum retain data size exceeded. re-
ager quested: {BytesRequested}, maximum is
{BytesAvailable}|
External Retain data initialization failed
Arp.Service.NotificationLog- NotificationLogger Info Arp::System::NmPayload::NotificationLog- Closing archive '{ArchiveName}'.
ger.ClosingArchive ger::MessageWithArchiveNamePayload This entry is made during download of the
firmware. For the time being, ArchiveName
is always “Default”. Might not be made
during voltage drops (depending on the de-
vice).
Arp.Ser- eUAServer Internal Arp::System::Nm::StringPayload See alarms
vices.Alarms.Log.Acknowl-
edgeRequest.eUAServer
Arp.Ser- eUAServer Internal Arp::System::NmPayload::Alarms::Inter- See alarms
vices.Alarms.Log.AddA- nal::AlarmPayload
larm.eUAServer
Arp.Ser- eUAServer Internal Arp::System::Nm::StringPayload See alarms
vices.Alarms.Log.Confirm-
Request.eUAServer
Arp.Ser- eUAServer Internal Arp::System::NmPayload::Alarms::Inter- See alarms
vices.Alarms.Log.New- nal::AlarmPayload
State.eUAServer
Arp.System.Acf.System- SystemManager Info Arp::System::NmPayload::Acf::System- System starting up. Firmware version
Manager.Startup StartupPayload {"20XX.X (LTS)"}
Arp.System.Acf.System- SystemManager Info Arp::System::NmPayload::Acf::System- SystemManager state changed:
Manager.StateChanged ManagerStatePayload {"None"|"Ready"|"Stop"|"Running"}, er-
ror={"true"|"false"}, warning={"true"|"false"}
Arp.System.Nm.Exception- Error Arp::System::Nm::StringPayload Caught an exception during dispatching
DuringNotify NotificationMan-
notification '{notificationName}': {Exception
ager
Message incl. Call-Stack}
Arp.System.Nm.Subscri- NotificationMan- Warning Arp::System::Nm::NmSubscribeFailed- A subscriber subscribed to not registered

beToNotRegisteredNotifica- ager Payload<Arp::System::Nm::NmSubscri- notification name: {notificationName}
tion beToNotRegisteredPayload>
Arp.System.Nm.Subscribe- NotificationMan- Error Arp::System::Nm::NmSubscribeFailed- A subscriber subscribed to unregistered
ToUnregisteredNotification ager Payload<Arp::System::Nm::NmSubscribe- notification name: {notificationName}
ToUnregisteredPayload>
Arp.System.Watch- SystemWatchdog- Warning Arp::System::NmPayload::SystemWatch- system watchdog state changed: new
dog.WatchdogStatus- ManagerPrimary dog::SystemWatchdogStateChangedPay- state: {0|1|2} plc startup is: {"allowed"|"for-
Changed load bidden"}
0: none
1: NoWatchdog
2: ReasonUnknown

PLCNEXT TECHNOLOGY
2.14 Notification Logger

The Notification Logger enables saving of notifications in a database. The saved notifica-
tions can be displayed and evaluated using external tools. The Notification Logger registers
with the Notification Manager for all configured notifications and thus receives all applicable
messages that are sent. The Notification Logger can be used for analyzing firmware and ap-
plications.
The PLCnext Technology SDK contains helpful classes for the Notification Logger. If you
want to use a class, integrate it into your program via an #include command, (e.g.,
#include Arp/Services/NotificationLogger/Services/INotificationLoggerSe
rvice.hpp). Further information on the classes and their applications is available directly in
the code commentary.
Saved notifications can be queried via RSC interfaces (see Section “Querying notifications”
on page 192).
2.14.1 Displaying notifications in the PLCnext Engineer cockpit

The notifications of a controller are displayed in PLCnext Engineer in the “Cockpit” editor of
your controller.
• In the “PLANT” area, click on the controller (e.g., AXC F 2152).
• Select the “Cockpit” editor.
• Select “Notifications”.
For more detailed information, please refer to the online help for PLCnext Engineer.
2.14.2 Receiving notifications

An archive subscribes to all notifications to be received. Additionally, in an archive, filters
can be used for the notifications subscribed to that refer to their metadata. This way, you can
select which notifications are actually saved. The Notification Logger contains several ar-
chives that enable notifications to be saved for different issues and purposes.
2.14.3 Configuring the Notification Logger

If necessary, you can configure the Notification Logger via a config file in XML format. To
modify the configuration manually, the XML file can be edited using any editor. If you do not
create your own configuration, the standard settings from the settings file will be used.
Changes to the configuration are automatically applied after a restart of the controller.
You will find the configuration files in the /opt/plcnext/projects/Default/Services/Notification-
Logger/*.config directory. The configuration files are imported during the start of the firm-
ware.

A configuration file for the Notification Logger is structured as shown in the following exam-
ple:
<?xml version="1.0" encoding="UTF-8"?>
<NotificationLoggerConfigurationDocument
xmlns="http://www.phoenixcontact.com/schema/notificationloggerconfiguration"
xsi:schemaLocation="http://www.phoenixcontact.com/schema/notificationloggerconfiguration"
<Includes>
<Include path="$ARP_PROJECTS_DIR$/Default/" />
</Includes>
<Archives>
<Archive name="Default"
<Notifications>
<Notification name="Arp" />
</Notifications>
<ExclusionFilter>
<Severity Operator="LE" Threshold="Info" />
</ExclusionFilter>
<Storage path="$ARP_PROJECTS_DIR$/Default/Services/NotificationLogger/archives">
<SizeLimitation>
<FileSizeLimitation MaxFileSize="64MB" />
</SizeLimitation>
<SizeReduction>
<DeleteOldestEntires NumberOfEntriesToDelete="16" />
</SizeReduction>
</Storage>
</Archive>
</Archives>
</NotificationLoggerConfigurationDocument >
• Configure the Notification Logger using the following attributes:
Integrating configuration Configuration files are integrated between the <Includes> and </Includes> tags.
files • Use the Include path attribute to reference further files to be integrated by indicating
their path. The element can occur any number of times.
Defining an archive An archive is defined between the <Archives> and </Archives> tags.
• Define the archive using the following attributes:
Archive name Name of the archive. The name is used as a basis for the file names.
Notification name Name of the notification to be saved to the archive. This element can occur any num-
ber of times.

PLCNEXT TECHNOLOGY
ExclusionFilter Specification of the input filter for notifications. This can refer to any part of the name-
space. All subordinate notifications are recorded. All notifications matching the filter
are discarded and not saved.
– And – AND link of several filter elements. Contains any number of other filter elements.
– Or – OR link of several filter elements. Contains any number of other filter elements.
– Not – Negation of a filter element. Contains exactly one other filter element.
– NotificationName – Regex attribute: Regular expression for the notification name.
Regular expressions are character strings for describing search patterns using a
syntactic standard.
– SenderName – Regex attribute: Regular expression for the sender name of the notification
– Severity – Operator attribute: Comparison function: GT, GE, LT, LE, EQ;
Threshold attribute: Comparison value: Internal, Info, Warning, Error, Critical,
Fatal
Storage Specification of the persistent storage of the archive
– path – Path for saving the archive files
– SizeLimitation – Limitation of file size
– FilesizeLimitation – MaxFilesize attribute: Maximum storage space in bytes; positive integer re-
quired, permitted suffixes: kB (*1024), MB (*1048576)
– SizeReduction – Action for reducing the file size. The action is executed as soon as
SizeLimitation is violated.
– DeleteOldestEntries – NumberOfEntriesToDelete attribute: Number of elements to be deleted,
positive integer
2.14.4 Saving notifications
Saving the notifications The Notification Logger uses one or several archives for registering, saving and querying
notifications. It provides a uniform interface to these archives and enables the configuration
of the archives via the configuration files. The notifications are permanently stored in an
SQLite database. This way, the file is not system-oriented and, after copying it to another
system, can be opened and processed with the appropriate tools. The predefined database
is available on the file system of your controller at /etc/plcnext/logs/default.sqlite. The ar-
chives offer functions for acquiring and filtering of incoming notifications as well as for re-
questing and deleting. Using different archives makes it possible to save notifications for dif-
ferent issues and purposes, e.g.:
– Firmware diagnostics
Short-term saving of firmware events for diagnostics by the service.
– Network diagnostics
Saving of diagnostic messages from network components over a short period for diag-
nosing disconnections or sporadic delays.
– Application diagnostics
Saving notifications of the application program, e.g., malfunctions of machines, refilling
consumables, error messages by integrated aggregates.

2.15 DataLogger
The DataLogger is a service component of the PLCnext Technology firmware. This compo-
nent transfers real-time data from the GDS to a database for recording and storage pur-
poses. When starting and stopping the PLCnext Technology firmware, the DataLogger is
started and stopped automatically. XML configuration files are used for configuration of the
DataLogger. A change of the configuration will be activated after a restart of the firmware.
2.15.1 Data logging
Data sources
The DataLogger can record data from any IN or OUT ports and variables. The following data
sources are available:
Global Data Space IN and OUT ports:
– Type realtime program (C++, IEC 61131-3 and MATLAB® Simulink®) - Task synchro-
nous mode
– Type component
– Global IEC 61131-3 variables
The following data types are supported:
– Elementary data types
Recording mode There are two recording modes available. The recording mode is set in the configuration file
(attribute storeChangesOnly).
– Endless mode
The DataLogger records the data in endless mode. All the ports and variables config-
ured for recording are recorded without interruption (storeChangesOnly="false").
– Save on change
The DataLogger only records the data when they change. If the value stays the same it
is displayed in the data base with “NULL“ (storeChangesOnly="true").
Timestamp The DataLogger provides a timestamp for each value of a port. Only one timestamp is gen-
erated for ports from the same task because this timestamp is identical for all the values of
the task. Time resolution has a precision of 100 ns. It is possible to configure the format of
the timestamp inside the database. It can be displayed as ISO 8601 or as raw 64 bit integer
value. Despite the format, all timestamps are reported using the UTC timezone. The imple-
mentation and internal representation complies to the .NET DateTime class, see Documen-
tation of DateTime Struct on https://docs.microsoft.com.
The timestamp is created in the task cycle via the system time of the controller. It is set at
the start of the task (task executing event) and maps exactly the cycle time of the task,so
that the values of the following task cycles are always one interval apart.
Sampling rate The sampling rate defines the interval the DataLogger uses for recording. It can be freely
set for each recording process (samplingInterval ="50ms").
2.15.2 Data sink

A database can be configured as the target location for data recording (e.g. Datasink
type="db" dst="/opt/plcnext/projects/Services/DataLogger/yourDB.db").
In each cycle, the values of all ports of a task are stored in a ring buffer. Therefore, the ca-
pacity of the ring buffer determines the maximum number of task cycles that can be re-

PLCNEXT TECHNOLOGY
corded before data must be forwarded to the data sink.

Use the publishing interval to specify the frequency for forwarding the collected data from
the ring buffer to the data sink. The publishing interval can be specified in the DataLog-
ger configuration file via the publishInterval attribute in the General XML element. A con-
figuration for a publishing interval of 1 s therefore is: <General
publishInterval="1s"/>. Data publishing from the DataLogger to the data sink is not
performed within the real-time context.
The data to be archived is written to an SQLite database. For each configured DataLogger
a SQLite database is created.
You can use the writeInterval attribute in the configuration file to specify how many data
records are reported to the data sink before these values are written to the file on the SD
card (default value = 1000). When the data sink or the firmware are closed, all the values
that have not yet been transferred are written to the SD card.
Note:
If the value of the attribute writeInterval is low, the resulting high number of write opera-
tions to the SD card might cause performance problems. It is possible that the data cannot
be written to the SD card in the required speed. This may result in the loss of data.
If a faster writeInterval is required, Phoenix Contact recommends to create the data-
base in the RAM (as described in example 3 and 4 in Section 2.15.5, “Configuration exam-
ples”).
If gaps occur during recording of the data, caused by performance problems or memory
overflow, this information will be saved in the data sink. If there is a loss of data it will be dis-
played in the database in the column ConsistentDataSeries. It can contain the values 0 or
1.
– Value 0:
If the value is 0 a data gap occurred during the recording of the preceding data series.
The first data series always has the value 0 because there is no preceding data series
for the reference.
– Value 1:
If the value is 1 the data is recorded without a gap related to the preceding data series.
Therefore the data series tagged with a 1 is consistent to the preceding data series.
Note:
Phoenix Contact recommends the evaluation of the flag ConsistentDataSeries to ensure
that the data is consistent. If ConsistentDataSeries=0 an inconsistency has occurred.
Table 2-7 Example from a database with an indicated data gap
RowId ConsistentDataSeries VarA

1 0 6
2 1 7
3 1 8
4 1 9
5 1 10
6 1 11
7 1 12
8 1 13
9 0 16
10 1 17
11 1 18

In this recording, the first 8 data rows are consistent and without gaps caused by data loss
(ConsistentDataSeries=0). Between rows 8 and 9 a data gap is indicated
(ConsistentDataSeries=0). The rows 9 to 11 are again consistent.
2.15.3 DataLogger configuration

Configure the DataLogger using an XML configuration file. You can configure several Dat-
aLogger sessions. Each configuration file generates a separate DataLogger session. You
can download an exemplary DataLogger configuration file and folder from PLCnext
Github and use it as template. The XML configuration file can be edited using a suitable ed-
itor. Save the edited configuration file under /opt/plcnext/projects/Services/DataLogger/ on
your controller. The file system of the controller is accessed via the SFTP protocol. Use a
suitable SFTP client software for this, e.g., Win-SCP. When starting and stopping the PLC-
next Technology firmware, the DataLogger is started and stopped automatically in this con-
figuration. A change of the configuration will be activated after a restart of the firmware.
A configuration file for the DataLogger is structured as shown in the following example:
<DataLoggerConfigDocument
xmlns="http://www.phoenixcontact.com/schema/dataloggerconfig"
xsi:schemaLocation="http://www.phoenixcontact.com/schema/dataloggerconfig.xsd">
<General name="data-logger" samplingInterval="100ms" publishInterval="500ms" bufferCapacity="10"/>
<Datasink type="db" dst="test.db" rollover="true" tsfmt="Iso8601 maxFiles="3" writeInterval="1000"
maxFileSize="4000000"
storeChangesOnly="false"/>
<Variables>
<Variable name = "Arp.Plc.ComponentName/GlobalUint32Var"/>
<Variable name = "Arp.Plc.ComponentName/PrgName.Uint32Var"/>
<Variable name = "Arp.Plc.ComponentName/PrgName.StuctVar.IntElement"/>
<Variable name = "Arp.Plc.ComponentName/PrgName.IntArrayVarElement[1]"/>
</Variables>
</DataLoggerConfigDocument>
• Configure the DataLogger using the following attributes:
Table 2-8 General XML element
name Unique name of the logging session.
samplingInterval Interval during which the data points of a variable are created. The default value is
500 ms. The following suffixes can be used: ms, s, m, h.
publishInterval Interval during which the data is transferred to the data sink. The default value is
500 ms.The following suffixes can be used: ms, s, m, h.
bufferCapacity Configuration of the buffer capacity. Capacity of data sets for the internal buffer
memory. The default value is 2.

PLCNEXT TECHNOLOGY
Table 2-9 Datasink XML element
type Configuration of the data sink:
db: Database (SQLite)
dst File path and name under which the data sink is to be stored.
Note: The DataLogger does not create folders. If you want to store a data sink under
a specific path, you have to create it first.
rollover true: Once the maximum file size is reached, the file is closed and renamed with an
index starting from 0 (e.g. database.db.0). Then a new file is created. Every file with
an index is closed and can be copied for evaluation. The current data is always logged
in the database that is defined in the attribute dst.
false:
When rollover is set to false and the maximum file size is reached, a configurable
amount of theoldest records is deleted before the record proceeds. The amount of
data to be deleted is configured with the attributedeleteRatio.
deleteRatio Percentage of maximum memory size to be deleted for the logging of new data.
This attribute defines the amount of data that is deleted before new data is written into
the database. The old data is deleted when the value that is defined in maxFileSize
is reached and the attribute rollover is set to false.
The value for deleteRatio must be provided as an unsigned integer value (16 bit). It
must range from 1 to 100. The value corresponds to the percentage of old data to be
deleted.
Example:
1 = 1 % of old data is deleted.
100 = 100 % of old data is deleted.
tsfmt Configuration of the timestamp format
Raw:
The timestamp is stored as 64 bit integer value.
Iso8601:
The timestamp is stored in the ISO 8601 format with microsecond accuracy.
maxFiles Maximum number of rolling files (default value =1).
The rollover attribute must be set to true. When the maximum number of files is
reached, the oldest file will be deleted. The file index of the closed files will be counted
up further.
If the maximum number of files is set to 0 (maxFiles="0") the behaviour corresponds
to a deactivated rollover (rollover="false").
If the maximum number of files is set to a negative number, e.g. -1 the file number lim-
itation is deactivated. This results in logging activity until the memory is full. The de-
fault value is -1.
Note:
When the value for maxFiles is 1, rollover is set to true and the maximum file size
is reached, a configurable amount (attribute deleteRatio) of the oldest data in the
database is deleted. The deleteRatio is related to the maximum file size that is de-
fined with the attribute maxFileSize.

Table 2-9 Datasink XML element
maxFileSize Maximum memory size of the log file in bytes.
storeChangesOnly true: The values are only stored if they change. If a value stays the same, it is defined
as NULL in the database.
false: The values are always stored, even if they do not change.
writeInterval Number of data records the DataLogger collects and writes to the SD card.
The default value is 1000 to keep write access operations to the SD card as low as
possible. In other words, as soon as 1000 data records have been transferred to the
data sink, they are grouped in a block and written to the SD card.
Note:
If the value of the attribute writeInterval is low, the resulting high number of write
operations to the SD card might cause performance problems. It is possible that the
data cannot be written to the SD card in the required speed. This may result in the loss
of data. If there is a loss of data it will be displayed in the database in the column Con-
sistentDataSeries.
Table 2-10 Variables XML element
Variable name Complete name (URI) of a variable or a port whose values are to be recorded.
Example:
Arp.Plc.ComponentName/PrgName.Uint32Var
2.15.4 Database layout

The values of the configured variables are saved in a table inside the SQLite database. The
default path for the database files on your controller is /opt/plcnext. The database files are
saved as *.db files. The file system of the controller is accessed via the SFTP protocol. Use
a suitable SFTP client software for this, e.g., WinSCP.
Copy the *.db files to your PC and use a suitable software tool to open and evaluate the *.db
files (e.g. DB Browser for SQLite).
Depending on your configuration, a table that is created by the DataLogger can consist of
the following columns:
– Timestamp:
Timestamp for the logged variable value.
– Consistent Data Series:
This index shows if there is a inconsistency in the logged data (see
ConsistentDataSeries).
– Task/Variable:
One column for each variable that is configured for data logging. The column name con-
sists of the task name and the variable name
– Task/Variable_change_count:
In case of storeChangesOnly="true" this column serves as change counter. There
is a change counter for every configured variable.

PLCNEXT TECHNOLOGY
Example with attribute storeChangesOnly="false"
Timestamp* ConsistentDataSeries Task10ms/VarA Task10ms/VarB

10ms 1 0 0
20ms 1 1 0
30ms 1 2 2
40ms 1 3 2
50ms 1 4 4
60ms 1 5 4
In this example the logged variables are from the same task. Therefore there are values for
every timestamp.
*In this example the timestamp is simplified. In a *.db file generated by the DataLogger, the
timestamp is either displayed in the ISO 8601 format or as 64 bit integer value in the data-
base. The implementation and internal representation complies to the .NET DateTime
class, refer to Documentation of DateTime Struct on https://docs.microsoft.com to convert
the timestamp into a readable format.
Example with attribute storeChangesOnly="true"
Timestamp* ConsistentData- Task10ms/VarA Task10ms/VarA_ Task10ms/VarB Task10ms/Var-

Series change_count B_change_count
10ms 1 0 0 0 0
20ms 1 1 1 NULL 0
30ms 1 2 2 2 1
40ms 1 3 3 NULL 1
50ms 1 4 4 4 2
60ms 1 5 5 NULL 2
In this example the logged variables are from the same task. Therefore there are values for
every timestamp. When there is no change in the value of a variable in relation to the value
of the preceding timestamp, it is displayed as NULL, meaning that the value has not
changed.
Example with attribute storeChangesOnly="false" and variables from different

tasks
Timestamp* ConsistenDataSeries Task10ms/VarA Task20ms/VarB

10 ms 1 0 NULL
20 ms 1 1 NULL
21 ms 1 NULL 1
30 ms 1 2 NULL

Timestamp* ConsistenDataSeries Task10ms/VarA Task20ms/VarB

40 ms 1 3 NULL
41 ms 1 NULL 2
50 ms 1 4 NULL
60 ms 1 5 NULL
61 ms 1 NULL 3
In this example the logged variables are from different tasks (Task10ms and Task 20ms).
Usually different tasks have different timestamps which affects the layout of the table.
When the variable values of a task are added to the table, the variable values of the other
task are displayed as NULL.
2.15.5 Configuration examples

The following examples show various application scenarios with the associated
DataLogger configurations. Observe the notes for your own DataLogger configuration.
1. Description:
Logging of 10 variables in endless mode from a task with 100 ms. Guaranteed storage
of 1000 collected data records. The last seconds are of interest for evaluation.
Configuration:
rollover="false", maxFileSize="1000000", dst="/opt/plcnext/log.db"
2. Description:
Logging of 10 variables in endless mode from a task with 100 ms. Guaranteed storage
of 1000 collected data records. The last minutes are of interest for evaluation.
Configuration:
rollover="true", maxFileSize="10", dst="/opt/plcnext/log.db"
Note: In example 1 and 2, the data sink first collects the data in a RAM database. The attri-
bute maxFileSize determines the size of this database and therefore how much of the
RAM is used by the DataLogger session. When the value that is determined in
maxFileSize is reached, a copy of the database is written from the RAM to the SD card.
The duration of the writing process to the SD card depends on the sytsem load and the size
of the file. Consider this when configuring maxFileSize. Phoenix Contact recommends to
assign 1 MB as file size. If more historical data is necessary, Phoenix Contact recommends
to split the data into several files with the attribute rollover="true".
3. Description:
High speed data logging of variables in endless mode from a task with 5 ms. The last
seconds are of interest for evaluation.
Configuration:
rollover="false", maxFileSize="1000000", dst="/tmp/log.db"

PLCNEXT TECHNOLOGY
4. Description:
High speed data logging of variables in endless mode from a task with 5 ms. The last
minutes are of interest for evaluation.
Configuration:
rollover="true", maxFileSize="10", dst="/tmp/log.db"
Note: Examples 3 and 4 show a configuration for high speed data logging. Data logging in
the low ms range requires fast write access. This cannot be realized reliably with an SD
card. If data logging faster than >= 5 ms is required, Phoenix Contact recommends to store
the data on the RAM disk due to performance reasons (/tmp/).
Note that in case of a voltage failure or reset all data that is stored on the RAM disk is lost.
Phoenix Contact recommends the usage of an UPS (uninterruptible power supply) to pre-
vent the loss of data.
You must ensure that the required RAM is available for the database.

2.16 Operating system

The PLCnext Technology control platform is based on a Linux operating system with real-
time patch. Linux is a highly reliable open source operating system suitable for applications
that require a high stability. A wide range of open source software is available for the Linux
operating system, which is supported by a large community of users and developers. You
can also use this open software, software blocks, and technologies for your PLC applica-
tions (e.g., SQL server). PLCnext Technology uses the Linux operating system and extends
it by the functions of a PLC such as the cyclic processing of tasks and cycle-consistent data
exchange. Core changes or extensions are not possible. To add functions to the system,
the user must compile and, if necessary, execute installations with “root” rights.
The operating system features the following components and services:
– Firewall (nftables is used for the firewall. The firewall can be configured via the WBM,
see Section 3.9.3 on page 123.)
– OpenVPN
– strongSwan
– SSH/SFTP
– NTP
– DNS
2.16.1 Directories of the firmware components in the file system

PLCnext controllers work with a Linux operating system. You can access the controller via
SFTP or via SSH, view the directories and files in the file system (on the internal parameter-
ization memory and on the SD card), and modify them if necessary.
Directories and files that are provided by Phoenix Contact (also through firmware updates)
are stored on the internal parameterization memory of the controller.
Each PLCnext Control uses an overlay file system in which all user specific settings are
stored (e.g. projects, network configuration). All changes are first made on a RAM disk and
after the changed file is closed, it is stored in the overlay file system.The directory structure
depends on whether you operate the controller with or without an SD card:
Operation without an SD If the PLCnext Control is operated without an external SD card, the operating system stores
card the overlay file system on the internal parameterization memory.
Some controllers have to be operated with an SD card.
• Check this in the user manual of your controller.
Operation with an SD card If the PLCnext Control is operated with an SD card, the operating system stores the overlay
file system on the external SD card with the folder name /upperdir.
By copying /upperdir (an ext4 compatible operating system is required) you can create a
backup of all settings and the project (e.g., network configuration, configured bus configu-
ration, PLCnext Engineer project, etc.). For this purpose all device-related certificates must
be removed.
Phoenix Contact recommends to operate the controller with an external SD card.

PLCNEXT TECHNOLOGY
The following table provides an overview of the major directories on the file system of your
controller.
Table 2-11 Important directories on the internal parameterization memory and the SD card
Directory in the root file system Contents

/usr/local/lib Directory for storing additional open-source libraries that are used by customized
C++ programs.
For additional information on programming the controller with C++, please refer to
Section 6, “Creating programs with C++”.
/usr/share/common-licenses License information on the individual Linux packages of the controller
/opt/plcnext Home directory of the “admin” Linux user and working directory of the device firm-
ware
Files written by the application program are stored in this directory if the specified
file name does not contain a storage path.
/opt/plcnext/config Directory for storing configuration files that are not project-specific.
/opt/plcnext/logs Directory for storing the log files of the Diagnostic Logger as well as the database
of the Notification Logger
This directory contains the output.log file. It contains information on the startup be-
havior of the firmware, status and error messages as well as warning notes that
help you find the source of error.
In addition, you will find the diagnostic log file of the plcnextapp command line tools
(plcnextapp.log) as well as the log files of the UA server (uatrace.log,
uatrace_1.log).
/opt/plcnext/projects Directory for storing project directories and files
/opt/plcnext/projects/PCWE Directory for storing PLCnext Engineer projects
All files and subdirectories in this directory are managed exclusively by
PLCnext Engineer.
• Do not make any changes to this directory.
/opt/plcnext/Security Directory for storing certificates of IdentityStores and TrustStores which are man-
aged via the WBM.
/opt/plcnext/Security/Certificates/ Directory for storing the HTTPS certificate
https


/opt/plcnext/Security/TrustStores Directory for storing the TrustStores configured in WBM
Each subdirectory corresponds to the name of a TrustStore.
A TrustStore directory contains the following subdirectories:
– trusted: The directory contains CA (CA = Certificate Authority) certificates
that are trusted.
– issuers: The directory contains CA certificates that are not automatically
trusted but that are required for creating a certificate chain.
– trusted/crl: The directory contains files with Certificate Revocation Lists
(CRL) for the CA certificates.
– issuers/crl: The directory contains files with Certificate Revocation Lists
(CRL) for issuer certificates.
Please note:
The firmware internally uses the /opt/plcnext/Security/TrustStores/Empty/ Trust-
Store.
• Do not make any changes to the directory, the subdirectories, and the files of
the “Empty” TrustStore.
/opt/plcnext/Security/IdentityStores Directory for storing the IdentityStores configured in WBM
Each subdirectory corresponds to the name of an IdentityStore. An IdentityStore
contains identities (X.509 certificates with associated private key).
An IdentityStore directory contains the following files:
– certificate.pem: The directory in PEM format contains the X.509 certificate of
the identity. The file may additionally contain several certificates of the certifi-
cate chain.
– key.pem: The file in PEM format contains the private key for the certificate.
– tpmkey.pem: The file contains the private key linked to the TPM (Trusted
Platform Module) of the controller.
/opt/plcnext/apps All active apps downloaded from the PLCnext Store to the controller are mounted
in this directory.
Each active app is mounted with the name of the app identifier in a subdirectory.
The entire content of the app container is available in this directory (read-only).
The directory is managed by the PLCnext Store.
Do not make any changes to this directory.
/opt/plcnext/installed_apps Directory for storing all installed app containers
The directory belongs to the PLCnext Store.
/opt/plcnext/appshome Directory for storing and managing app data
The directory is managed by the PLCnext Store and the installed apps.
• Do not make any changes to this directory.
/opt/plcnext/lttng Directory for storing the default configuration files for tracing via LTTng

PLCNEXT TECHNOLOGY

/opt/plcnext/lttng_traces Directory for storing trace files
The directory is created during runtime of the trace controller when the trigger func-
tion for storing the trace files is called for the first time. Each time the trigger func-
tion of the memory is called, a new subdirectory (trace directory) for storing the cur-
rent trace data is created.
The designation of a trace directory is structured as follows:
YYYYMMDD_hhmmss
E.g.: /opt/plcnext/lttng_traces/20190418_190615/<trace_data>
The memory operates as a ring memory. When exceeding the maximum storage
space, the oldest trace directory is deleted.
/opt/plcnext/backup Directory for download changes operations
The directory is used for creating a backup of the project directory (/opt/plc-
next/projects/). In the event of an error, the contents of the backup directory are re-
stored. The backup directory is created following the first successful project down-
load and following every successful project download.
/opt/plcnext/retaining Directory for storing remanent data
/opt/plcnext/shadowing Directory for internal storage of copies of C++ user libraries that have been config-
ured in PLCnext Engineer and downloaded.
/opt/plcnext/profinet Directory for storing temporary PROFINET files
Using SFTP to access the The file system is accessed via the SFTP protocol. SFTP client software is required for this
file system (e.g., WinSCP).
Access to the file system via SFTP requires authentication with a user name and password.
The following access data is set by default with administrator rights:
User name: admin
Password: Printed on the controller
2.16.2 System time
2.16.2.1 NTP (Network Time Protocol)
Server An ntpd (Network Time Protocol daemon) is included in the operating system for time syn-
chronization. It is possible to connect to other NTP servers or to start your own server.
Client The NTP service from ntp.org (Network Time Protocol Project) is integrated into the operat-
ing system. This service can be configured via the /etc/ntp.conf configuration file. As an
admin user, you have sufficient rights to modify the data. You have the option of specifying
IP addresses and names in the configuration. The changes are adopted after restarting the
ntp daemon.
• Execute the sudo /etc/init.d/ntpd script.
The changes made in the configuration file will be active after the next controller restart.
In the standard configuration, the operating system time is synchronized with the Real-Time
Clock (RTC) installed in the hardware.

Additional – You will find a general introduction to the Network Time Protocol daemon (ntpd) at
information https://www.eecis.udel.edu/~mills/ntp/html/ntpd.html.
– You will find a detailed description of the configuration options at
https://www.eecis.udel.edu/~mills/ntp/html/confopt.html.
– The PLCnext firmware contains the NTP utilities (e.g. ntpq and ntpdc) for diagnostic
and monitor purposes.
2.16.2.2 Changing the system time via the shell

As an alternative to synchronization with an NTP server, you can also change the system
time manually via the shell. Authentication with the user name and password is necessary
for SSH access to the shell. The following access data is set by default with administrator
rights:
User name: admin
Password: Printed on the controller.
Requesting the system • Open the shell.

time • Request the system time via the date command.
Setting the system time • Enter shell command sudo date -s "YYYY-MM-DD hh:mm:ss".
– YYYY: Year
– MM: Month
– TT: Day
– hh: Hours
– mm: Minutes
– ss: Seconds
2.16.2.3 Setting the system time in PLCnext Engineer

You can also set the system time using the PLCnext Engineer software. Access with
PLCnext Engineer requires authentication with a user name and password.
• In the “PLANT” area, click on “PLCnext”.
• Select the “Online Parameters” editor.
• Enter the desired values for the date and time in the corresponding input fields.
Figure 2-34 Setting the system time in PLCnext Engineer

PLCNEXT TECHNOLOGY
2.16.3 OpenVPN™ client

With the OpenVPN™ software, you have the option of establishing a virtual private network
(VPN) and therefore a secure connection via an unsecured network. The data is encrypted
with suitable protocols.
All necessary settings can be made under /etc/openvpn. Note that OpenVPN knowledge is
required to make these settings.
For further information, please refer to https://openvpn.net.
2.16.4 IPsec (strongSwan)

IPsec is an encryption and authentication protocol with which VPN connections (Virtual Pri-
vate Networks) can be established. StrongSwan is an implementation of the IKE (Internet
Key Exchange) protocol and can be used for VPN connections via IPsec.
For details, please refer to http://www.strongswan.org.
AXC F 2152 configuration You can edit the /etc/ipsec.conf configuration file with admin user rights.
notes • Use the following commands to start, stop and restart the daemon:
– Start: sudo ipsec start
– Stop: sudo ipsec stop
– Restart: sudo ipsec restart
• Use the following command to call up the status: sudo ipsec status
Configuration examples Configuration example are available at https://wiki.strongswan.org.

2.16.5 Text editors

“Nano” and “Vim” are installed on the controller as text editors. When you are connected to
the controller via the SSH console, you can call the desired editor via the command line.
• To open a file with the desired editor, enter nano <file name> or vim <file name>.
Nano The “Nano” text editor is easy to use and is therefore recommended for inexperienced us-
ers.
Vim The “Vim” text editor has an extended range of functions and is a popular editor in the Linux
environment.
2.16.6 User rights

When a PLCnext user logs into the SSH console with the “admin” user role, the user is also
recognized with the same name and password by the Linux system. The user is therefore
assigned to the “plcnext” Linux group. Files that this user may read, write to and/or execute
are assigned to the “plcnext” group file system.
The “plcnext_firmware” user is another major user in the Linux system. It is permanently in-
tegrated and is used for starting the PLCnext firmware processes. In the Linux system, the
user has the rights to execute all the operations required.
In addition to the Linux user rights, the PLCnext Technology firmware also has its own user
management of which the configuration is described in Section ““User Authentication”
page” on page 109.
Executing Linux commands that require higher rights is made possible for the users via
sudo. Which Linux commands the PLCnext users are allowed to execute via sudo is config-
ured in the Linux system.
The following rights are available:
Table 2-12 User rights
Rights “plcnext” group admin sudo required

Setting and inspecting IP settings (including ifconfig,    (ifconfig)
ping, netstat, etc.)
Configuring the firewall  
Starting/stopping the firewall (init script)   
Inspecting the firewall with nft   
Configuring VPN (IPsec and OpenVPN™) 
Starting/stopping VPN services (IPsec and Open-  
VPN™)
Editing the “Default” PLCnext folder for individual ACF,  
ESM, GDS configurations, and *.so
Starting/stopping the PLCnext Technology firmware  
processes
sudo /etc/init.d/plcnext start|stop|restart
Reading PLCnext log files  
Calling and configuring TOP/HTOP  

PLCNEXT TECHNOLOGY
Table 2-12 User rights
Rights “plcnext” group admin sudo required

Firmware update via update script  
sudo update-plcnext
Configuring the NTP server  
Setting the root password with passwd  
Requesting the system time with date  
Setting the system time with sudo date -s   
Restarting/shutting down the controller with reboot or  
shutdown
Write access to /opt/plcnext and /opt/plcnext/projects  
Recording network traces with tcpdump   
Starting the gdbserver with root rights  
(see also PLCnext Community)
Resetting to factory defaults  
sudo recover-plcnext 1
See also “Factory reset” on page 85
2.16.7 Root rights

PLCnext controllers are supplied with a preset admin user. This enables access to the most
important functions. For some settings, you require advanced rights, e.g., to configure set-
tings for remote debugging of C# code. To this end, create a user with root rights.
NOTE: Risk of damage to equipment

If safety functions are switched off, the controller must not be used for live operation.
• Ensure that there is no risk of equipment damage or personal injury.
NOTE: Changes to the firmware

As a “root” user, you have the right to make any change on the controller. Root rights are
therefore only suitable for qualified application programmers and software engineers with
relevant experience.
• Make sure you do not make changes to the PLCnext Technology firmware.
• Do not supply the device with a password for the root user.
Creating a root user • Configure the connection settings in WinSCP.

• Connect to the controller by entering the IP address of the controller and the password
for the admin user.
• Click “Login”.

Figure 2-35 Connecting WinSCP to the controller (1)
Figure 2-36 Connecting WinSCP to the controller (2)
• Subsequently, open the console by clicking the “Open in PuTTY” button.
Figure 2-37 Opening PuTTY

PLCNEXT TECHNOLOGY
• Log in with the “admin” user name and the controller password. The default password
of the controller is printed on the housing.
Figure 2-38 Logging in as admin user
• Enter the sudo passwd root command.

• Enter the admin password.
• Enter a new password for the root user.
• Confirm the new password by entering it again.
Figure 2-39 Creating a new root user
• Use the su command and the root password to log in as the root user.
• Once you have executed all the activities as a root user, change back to the previous
user role (e.g., admin) using the exit command.
Activating SSH login as The SSH login as a root user is prevented for security reasons. To enable direct login via
root user SSH for the root user, you have to configure this in the sshd_config file.
• Open the file /etc/ssh/sshd_config with a suitable editor.
• Under # Authentication:, enable the commented out PermitRootLogin yes entry.
• Restart the SSH service with /etc/init.d/sshd restart.
Removing the root pass- If the root password is no longer required, remove the password. This prevents unautho-
word rized users from modifying the firmware.
• Enter the sudo passwd -d root command in the shell to remove the password.
Deactivating SSH login as • Open the file /etc/ssh/sshd_config with a suitable editor.
root user • Deactivate SSH login for the root user by changing the PermitRootLogin entry to a
comment again under # Authentication:.
• Restart the SSH service with /etc/init.d/sshd restart.

2.16.8 Linux scripts of the PLCnext Technology firmware
Firmware update As of firmware version 2019.0 LTS, you can update the firmware conveniently via web-
based management of your controller. For older firmware versions, you can start the firm-
ware update via the sudo update-plcnext shell script, which you will find in the file system
of the controller.
• Download the *.zip firmware file from the download area of your controller.
• Unzip the *.zip firmware file.
• Run the *.exe setup file.
• Follow the instructions in the installation wizard.
• Open the SFTP client software (e.g., WinSCP).
• Log in as an administrator.
The following access data is set by default:
User name: admin
Password: Printed on the controller
• Copy the *.raucb update file to the /opt/plcnext directory (home directory of the Linux
user “admin”).
• Open the shell using a command line tool (e.g., PuTTY or Tera Term).
• Log in as administrator.
The name of the update script is the same for every controller: sudo update-plcnext. The
script is available in the directory under /usr/sbin/. Under /usr/sbin/, you will also find
symbolic links with the respective product designation in the name, e.g., sudo update-
axcf2152.
The script executes the following operations:
1. Stopping the PLCnext Technology process.
2. Performing the firmware update.
3. Rebooting the system and deleting the firmware container.
Factory reset You can reset the controller to the default settings using a shell script. Here, a distinction is
made between two types of default settings:
– Type 1: All user-specific data is deleted (settings, programs, users, etc.). The current
PLCnext Technology firmware remains unchanged.
– Type 2: In addition to the user-specific data (type 1), the firmware of the controller is re-
set to default state.
The script is available in the controller file system. The name of the factory reset script is the
same for every controller: sudo recover-plcnext. You will find the script under
/usr/sbin/. When calling the script, specify the desired reset type, e.g., sudo recover-
plcnext 1 for type 1 default settings.
Under /usr/sbin/, you will also find symbolic links with the respective product designation
in the name, e.g., recover-axcf2152 1 for type 1 default settings.
You can also reset your controller to type 1 and type 2 default settings via the device-
specific operating elements (e.g., reset button or operating display). For additional infor-
mation, please refer to the corresponding user manual.
The type 1 default settings can be restored via the “Cockpit” editor in PLCnext Engineer.
Controlling the firmware The plcnext script in the /etc/init.d directory controls the firmware.

PLCNEXT TECHNOLOGY
You can control the firmware with the following commands:
Table 2-13 Shell commands for controlling the firmware
Shell command Description

sudo /etc/init.d/plcnext stop Stops all PLCnext firmware processes
sudo /etc/init.d/plcnext start Starts all PLCnext firmware processes
sudo /etc/init.d/plcnext restart Restarts all PLCnext firmware processes
2.16.9 LDAP connection
2.16.9.1 Description
The LDAP server enables central management of the users in a network (e.g. a Microsoft
Active Directory). The PLCnext user authentication can be connected to an LDAP server. A
central user management allows to manage user accounts, their passwords and group
memberships at a central level. With an LDAP server there is no need to setup user ac-
counts and passwords on every single controller.
The benefits are:
– If a password change is necessary, it only needs to be changed once inside the LDAP
directory and not in every controller.
– New users can be added without the need of configuring every controller.
– New user permissions and rights can be rolled out in a very simple way.
– A blocked user affects the entire system and not only a single controller.
The User Manager supports the TLS protocol for the connection to an LDAP server
(LDAPS, LDAP with StartTLS). It supports the authentication of users against the LDAP
server with user name and password by using the LDAP bind command.
The LDAP authentication is performed in addition to the local user data base. If the authen-
tication is successful for one of the two sources, the authentication is considered success-
ful. No further authentication is necessary.
If the authentication fails because of a wrong or unknown user name or due to a communi-
cation error with the source, the authentication is continued with the next source. The local
user database (managed via WBM, see ““User Authentication” page” ) is always the first
source. After this the LDAP servers are used in the configured order.
If one authentication fails because a wrong password was entered, the login fails and no fur-
ther sources are used.
The User Manager validates the server certificate of the LDAP server. The validity check is
made using a configurable TrustStore which is referenced by its name.
2.16.9.2 Configuration of an LDAP connection

In order to set up an LDAP connection, you need to create an XML configuration file as de-
scribed below.
Overview on configuration options

It is possible to configure up to 10 LDAP server connections. To set up a User Manager
to LDAP connection you have the following configuration options:

Table 2-14 Configuration options
Option Description Default Optional/Mandatory

LDAP host/IP DNS name or IPaddress of the Mandatory
LDAP server
Port TCP port of the LDAP server "389" Optional
timeout The network timeout after a connection at- "10s" Optional
tempt to the ldap server failed
Enable TLS Activate/deactivate TLS "true" Optional
Use StartTLS Usage of StartTLS instead of TLS (this op- "true" Optional
tion only has an effect when TLS is acti-
vated)
TrustStore name Name of the Trust Store, that is used for "ldap" Optional
verification.
cipherList List of permitted TLS cipher suites for the "NORMAL:-VERS- Optional
LDAP connection TLS1.0:-VERS-
TLS1.1:-VERS-
DTLS1.0:-SHA1:-
SIGN-RSA-SHA1:-
SIGN-ECDSA-
SHA1:-RSA"
Base DN DN (Distinguished Name) where Mandatory
the LDAP search for users starts
Search filter LDAP filter that is used for the search for Mandatory
users.
Bind DN DN that is used for the bind before the Optional
search
Bind password Password for the "Bind DN" Optional
Group attributes List of LDAP attributes that save the group Mandatory
membership of a user, e. g. "memberof"
LdapGroup / Mapping configuration of LDAP groups to Optional
Role Mapping PLCnext roles
2.16.9.3 Configuration files

The configuration for the LDAP connection is set using XML configuration files. All of the im-
portant settings can be configured directly in the „Ldap.config“ configuration file on the con-
troller. To modify the configuration, the XML file can be edited using any editor. You will find
the file in the /opt/plcnext/config/System/Um directory of your controller. The file system is
accessed via the SFTP protocol. Use a suitable SFTP client software for this, e.g., WinSCP.
<?xml version="1.0" encoding="UTF-8"?>

<LdapConfigurationDocument
xmlns="http://www.phoenixcontact.com/schema/ldapconfiguration"
xsi:schemaLocation="http://www.phoenixcontact.com/schema/ldapconfiguration"
<LdapServer hostname="192.168.1.40" port="389" order="1">

PLCNEXT TECHNOLOGY
<LdapSecurityOptions tlsEnabled="true" useStartTls="true" trustStore="ldap" />

<LdapSearchOptions baseDN="dc=example,dc=org" searchFilter="(uid=$$USER$$)" />
<LdapLoginOptions bindDN="cn=admin,dc=example,dc=org" bindPassword="admin" />
<GroupAttributes>
<GroupAttribute name="memberOf" />
</GroupAttributes>
<GroupMappings>
<GroupMapping ldapGroup="cn=plcAdmin,dc=example,dc=org" localRole="Admin" />
<GroupMapping ldapGroup="cn=plcReader,dc=example,dc=org" localRole="Viewer" />
</GroupMappings>
</LdapServer>
</LdapConfigurationDocument>
LDAPServer
One configuration file can be filled with the configuration of up to 10 LDAP servers. Every
server is configured with the element <LdapServer> and </LdapServer>. The element
can be extended with the following attributes:
– hostname
Add the host name or the IP address of the LDAP server. This information is obligatory.
– port
The port is chosen automatically. Port 389 for connections without TLS or StartTLS and
port 636 for TLS connections. If necessary you can specify the port where the LDAP
server can be reached.
– order
The server entries are ordered according to the order number (int32) specified in this
attribute. They are sorted and processed according to this order number for an authen-
tication request.
– timeout
The network timeout after a connection attempt to the LDAP server failed. Enter a value
with one of the following units:
– ns (nanoseconds)
– us (microseconds)
– ms (milliseconds)
– s (seconds)
– h (hours)
The LdapServer element can contain the following XML elements for further configuration:
– LdapSecurityOptions
Settings for TLS. The following attributes can be used to specify the settings:
– tlsEnabled: Activate (true) or deactivate (false) TLS for the LDAP server
– useStartTls: Activate (true) or deactivate (false) the usage of StartTLS. When
the usage of StartTLS is deactivated and TLS is activated, a direct TLS connection
to the LDAP server is established.
– trustStore: Specifies the name of the TrustStore for the verification of the LDAP
server certificate. In case the name contains an empty string (""), the certificate
verification is switched off, which means that the connection to the LDAP server is
established without verifying its certificate. In case a TrustStore is empty, the veri-
fication process fails, which means that the connection to the LDAP server cannot
be established at all.

Note:
If a TrustStore is changed that is referenced by an LDAP server configuration (e.g.
by adding certificates for LDAP), a restart must be performed. The changes only
take effect after the restart.
– cipherList
The cipherList attribute configures allowed TLS cipher suites which are support-
ed by the LDAP client to establish a TLS connection to the LDAP server. This set-
ting is only enabled, if TLS or StartTLS is activated. The format must follow the
rules of GnuTLS (https://gnutls.org/manual/html_node/Priority-Strings.html).
A secure setting is established by default (can only be ensured with a recent firm-
ware version). The rules comply with the recommendations of the BSI (TR-02102-
2) with the following exceptions: Curve25519 is enabled, CHACHA20 and
POLY1305 are allowed.
The following cipherString is set by default with firmware version 2020.0 LTS. This
settings disable TLS versions 1.0 and 1.1 and disable the SHA-1 algorithm for
HMAC, PRF and Signature and disable RSA key exchange:
"NORMAL:-VERS-TLS1.0:-VERS-TLS1.1:-VERS-DTLS1.0:-SHA1:-SIGN-RSA-
SHA1:-SIGN-ECDSA-SHA1:-RSA"
Note:
The default value can be subject to change in new firmware versions. The setting
will be updated if new recommendations are published.
If connection issues with your LDAP server occur, consider to use a less secure
configuration, e.g.:
– Enable RSA Key Exchange again:
"NORMAL:-VERS-TLS1.0:-VERS-TLS1.1:-VERS-DTLS1.0:-SHA1:-SIGN-RSA-
SHA1:-SIGN-ECDSA-SHA1"
– Enable SHA-1 again:
"NORMAL:-VERS-TLS1.0:-VERS-TLS1.1:-VERS-DTLS1.0"
– Enable the TLS 1.1 protocol version:
"NORMAL:-VERS-TLS1.0:-VERS-DTLS1.0"
– Enable the TLS 1.0 protocol version and use the "Normal" setting of gnutls:
"NORMAL"
You might also want to restrict algorithms even further for example to comply with
very specific security policies at a particular location.
– LdapSearchOptions
Settings for the user search in the LDAP server. The following attributes can be used to
specify the settings:
– baseDN: The LDAP DN (Distinguished name) that serves as starting point for the
search for users over all child nodes.
– searchFilter: LDAP search filter that is used for the search for users. The vari-
able "$$USER$$" is automatically replaced with the login.
– LdapLoginOptions
Login settings for the LDAP server. Before the user search can be performed, a authen-
tication (bind) is required.
– bindDN:
Distinguished Name of the user the search in the LDAP directory is per-
formed with.
– bindPassword:
Password of the "bindDN" user in the LDAP server.

PLCNEXT TECHNOLOGY
Direct bind to LDAP server without user search

You have the possibility to configure the LDAP server so that the search for the correct user
is not performed in the LDAP. For this purpose a bind with the user name and password that
is entered into the login mask is executed. The bind will be performed with the configured
bindDN. The attribute contains the $$USER$$ placeholder which is replaced with the login
and the password which was entered for the login.
In order to activate the direct bind, proceed as follows:
– Add "$$USER$$" to the attribute bindDN.
Example: bindDN="uid=$$USER$$,dc=example,dc=org"
As a result the settings baseDN, searchFilter and bindPassword will be ignored.

Web-based management (WBM)
3 Web-based management (WBM)

Each PLCnext Technology controller features a web-based management (WBM). In the
WBM, you can access static and dynamic controller information and modify certain control-
ler settings. You can call WBM via every Ethernet interface of the controller.
The WBM systems of controllers with PLCnext Technology all have the same structure and
are generally described in the following. Device-specific additions and deviations are op-
tional and described in the corresponding device user manual.
3.1 Establishing a connection to WBM

To establish a connection to WBM, proceed as follows:
• Open the web browser on your PC.
• In the address field, enter URL “https://IP address of the controller” (example:
“https://192.168.1.10”).
Please note:
WBM can only be called if the controller has a valid IP address. Upon delivery, the con-
troller has IP address 192.168.1.10 (Ethernet interface LAN1 in case of several Ethernet
interfaces).
If there is a PLCnext Engineer HMI application on the controller, entering URL “https://IP
address of the controller” calls the PLCnext Engineer application.
• To call WBM in this case, enter URL “https://IP address of the controller/wbm”.
Initial access: TLS certifi- For secure communication, the controller web server uses a self-signed TLS certificate au-
cate tomatically generated by the controller. Before the controller web server can be accessed,
you must authorize the TLS certificate in your web browser.
Please note:
– The controller generates the TLS certificate during the boot phase.
– The certificate uses the IP address of the Ethernet interface with PROFINET control-
ler function.
– The certificate is used for all Ethernet interfaces of the controller.
– Each IP address of the controller must be authorized in the web browser before a
PLCnext Engineer HMI application can be accessed via this address and therefore
via the corresponding Ethernet interface.
– The certificate is regenerated after the controller is reset to factory settings.
– The certificate and a corresponding private key are available in the following directo-
ries of the controller file system:
– /opt/plcnext/Security/Certificates/https/https_cert.pem
– /opt/plcnext/Security/Certificates/https/https_key.pem

PLCNEXT TECHNOLOGY
Initial access: The PLCnext Technology controller welcome page is shown when the controller web server
Welcome page is accessed for the first time.
Figure 3-1 WBM: Welcome page of the PLCnext Technology controller
The welcome page contains links to the following web content:

– WBM of the controller
– PLCnext Community
– PLCnext website
If you do not want the welcome page to be displayed each time the controller web server
is accessed:
• Enable the “Do not show this page in the future and go directly to the WBM” check
box.
The next time you access the controller web server, the login page of WBM opens, see
Section 3.4.
Alternatively, you can enter URL “https://IP address of the controller/wbm” (example:
“https://192.168.1.10/wbm”) in your browser address field.
In this case, WBM is displayed immediately.
The welcome page remains accessible via URL “https://IP address of the controller/wel-
come”.

3.2 Licensing information on open source software

PLCnext Technology controllers work with a Linux operating system.
All license information can be called up via the “Legal Information” link on every page of
WBM:
• Click on the “Legal Information” link on the bottom left of the WBM page.
Licenses for all of the open source software used are shown.
3.3 Changing the language

You can change the language for the WBM user interface in the top left of the web browser
window.
Figure 3-2 WBM: Changing the language
• Click the “Deutsch” or “English” link to change the language.

WBM then immediately switches to the desired language.
3.4 Login
The WBM login page is displayed when:
– You access WBM for the first time.
– You have enabled the WBM user authentication function, see Section 3.9.1.
If you disable user authentication, login is not necessary to access WBM. In this case, the
WBM start page is displayed when WBM is accessed, see Section 3.5.
Figure 3-3 WBM: Login page

PLCNEXT TECHNOLOGY
Initial access as an admin- When you access WBM for the first time, log in as the administrator.
istrator • Enter the user name “admin” in the “Username” input field.
• Enter the administrator password in the “Password” input field.
The administrator password is printed on the controller. For more detailed information,
refer to the user manual for your controller.
• To open WBM, click on the “Login” button.
The WBM start page opens (see Section 3.5).
Recommended:
• Only use the administrator password for initial login.
• Once you have logged in successfully, change the administrator password to prevent
unauthorized administrator access (see Section 3.9.1).
Please note:
After changing the access data for the administrator, it is no longer possible to log in with
the user name “admin” and the administrator password printed on the controller.
Logging in as a user If WBM user authentication is enabled, log in using your user details.
• Enter your user name in the “Username” input field.
• Enter your password in the “Password” input field.
• To open WBM, click on the “Login” button.
The WBM start page opens (see Section 3.5).

3.5 Start page – areas and functions
Figure 3-4 WBM: Start page
WBM is split into the following areas:

– Information: General device information
– Diagnostics: PROFINET, Local Bus (Axioline, Interbus (Inline))
– Configuration: PROFICLOUD
– Security: User authentication, certificate authentication and firewall
– Administration: Firmware update of the non-safety-related device firmware

PLCNEXT TECHNOLOGY
3.6 “Information” area
3.6.1 “General Data” page

On the “General Data” page, you will find general details about the device, e.g., hardware
and firmware versions, the order number, as well as manufacturer details.
Figure 3-5 WBM: “General Data” page

3.7 “Diagnostics” area
3.7.1 “PROFINET” page

On the “PROFINET” page, you can view information on the controller and the connected
PROFINET devices.
“Overview” tab On the “Overview” tab, you will find information on the current PROFINET function of the
controller and its IP settings.
Figure 3-6 WBM: “PROFINET” page, “Overview” tab
“Status” area In the “Status” area, you can see whether the controller is currently being used as a
PROFINET controller and/or a PROFINET device.
“Controller details” area The current IP settings of the controller are displayed in the “Controller details” area.
Diagnostic information on the connected PROFINET devices are available on the “Device
List” tab.

PLCNEXT TECHNOLOGY
“Device list” The “Device List” tab provides an overview of the configured PROFINET devices. The over-
tab view contains the device names of the PROFINET devices, the current IP settings, the acti-
vation status (TRUE = active, FALSE = inactive) as well as the diagnostic state and code.
Table 3-1 PROFINET diagnostics: Possible diagnostic states
Diagnostic state Description

OK No error
Warning A warning occurred, e.g., “Maintenance Required”, “Maintenance
Demanded”, and “Diagnosis available”.
Error A PROFINET bus error occurred.
AR deactivated AR is deactivated. Diagnosis is not possible.
Figure 3-7 WBM: “PROFINET” page, “Device List” tab
Opening WBM of a Some PROFINET devices feature their own web-based management (WBM). You can
PROFINET device open WBM of a connected PROFINET device via a link on the “Device List” tab.
• In the “Device Name” column, click on the PROFINET device whose WBM you want to
open.
The WBM of the PROFINET device is opened in the web browser in a new tab.
Opening the In the “Device Information” view, you will find certain general information, the current IP set-
“Device Information” view tings as well as diagnostic information for each connected PROFINET device.
• In the “Details” column, click on the button.

The “Device Information” view opens (see Figure 3-8).
Figure 3-8 WBM: “PROFINET” page, “Device List” tab, “Device Information” view
Update frequency for di- Diagnostic data is updated with an update frequency of 1/s. The following information is up-
agnostic data dated:
– Device list: The device list can be recomposed, e.g., after changing and updating the
PLCnext Engineer project.
– Diagnostic data:
– Change of connection status of the PROFINET devices
– Diagnostic state of the PROFINET devices
For additional information on the diagnostic code, please refer to Appendix A 4 on
page 244.

PLCNEXT TECHNOLOGY
“Tree View” tab The “Tree View” tab provides an overview of the configured PROFINET devices. The over-
view contains the device names of the PROFINET devices, their current IP settings, as well
as the diagnostic state of the devices and modules.
Figure 3-9 WBM: “PROFINET” page, “Tree View” tab
PROFINET tree view The PROFINET tree view contains all the PROFINET devices from the device list.
• Click [+] or [-] to open or close the next level of the tree view.
The tree view provides the following information:
Controller level The following information is available on the PROFINET controller level:
– Controller designation
– IP address of the controller
– Number of PROFINET devices
Figure 3-10 Controller level in the tree view

Station level The following information on the PROFINET devices is available on “Station” level:
– Station name
– IP address
– Vendor ID (ID of the device manufacturer)
– Device ID (ID of the device)
– Number of modules (slots)
The following icons provide information on the current diagnostic state of the PROFINET
device:
Table 3-2 PROFINET device icons

Icon Diagnostic state
OK
Warning
Error
Figure 3-11 Station level in the tree view
Module level The following information is available on the PROFINET device module level:
– Module ID number
– Slot number
– Number of submodules
Information on the diagnostic state is currently not available.
Figure 3-12 Module level in the tree view
Submodule level The following information is available on the submodule level of the PROFINET device mod-
ules:
– Submodule node ID
– Submodule ID
– Subslot number
– Submodule type
– Number of submodule elements
Information on the diagnostic state is currently not available.

PLCNEXT TECHNOLOGY
Figure 3-13 Submodule level in the tree view
Further information on the • Clicking on the PROFINET controller opens the “Overview” tab (see ““Overview” tab”
devices and modules on page 97).
• Clicking on the PROFINET devices (“Station”) opens the “Device Information” view of
the corresponding device (see “Opening the “Device Information” view” on page 98).
3.7.2 “Local Bus” page

On the "Local Bus" page, you can view information on the controller and the connected local
bus Axioline or Interbus (Inline) modules. Depending on the connected local bus, the
WBM switches automatically to the Interbus or Axioline view (with extension module
AXC F IL ADAPT (1020304) the Interbus view is activated otherwise the Axioline view is
activated). In case neither Axioline nor Interbus (Inline) are enabled, the Local Bus page is
not visible. If available, the page is visible for all user roles.
Note:
The "Local Bus" page is only available for controllers that support local bus modules.
3.7.2.1 Axioline view
Figure 3-14 WBM: “Local Bus” page, “Local Bus (Axioline)“

Local Bus Module List

The module list provides an overview of the configured Axioline devices. The overview con-
tains the module types, their function and location as well as the diagnostic state and code.
The values shown in the fields “Function” and “Location” can be entered in the software
PLCnext Engineer for the corresponding module.
• In PLCnext Engineer open the “Parameters” editor in the editor's area of the Axioline
module.
• Enter the information in the fields “Function” and “Location”.
Figure 3-15 PLCnext Engineer “Parameters” editor
Local bus diagnostics:

Possible diagnostic states
Table 3-3 Local bus diagnostics: Possible diagnostic states
Diagnostic state Description

OK Module is running without error.
Warning A warning occurred.
Error A local bus error occurred.
Opening the module infor- In the "Module Information" view, you will find certain general and user-specific information
mation view as well as further diagnostic information on the specific module.
• In the “Details” column, click on the button.
⇒ The “Module Information” view opens.

PLCNEXT TECHNOLOGY
For further information on the diagnostic states of the module, refer to the module specific
documentation.
Figure 3-16 Example of a module in Status OK
Figure 3-17 Example of a module in Status Error

Diagnostic Registers
In the Diagnostic Registers table you will find the Diagnostic Status Register and the two Di-
agnostic Parameter Registers.
To decode the error code, consult the Axioline (UM EN AXL F SYS Diag) and device-spe-
cific documentation of your module. You will find it in the download area of your product.
3.7.2.2 Interbus view
Figure 3-18 WBM: “Local Bus” page, “Local Bus (Interbus)“
Local Bus Module List

The module list provides an overview of the configured Interbus devices. The overview con-
tains the Module Description, their ID and Identcode as well as the diagnostic state and
code.
The possible diagnostic states correspond to those of the Axioline view.
Diagnostic Registers
In the Diagnostic Registers table you will find the Diagnostic Status Register and the two Di-
agnostic Parameter Registers.
To decode the error code, consult the Interbus (IBS SYS DIAG DSC UM E) and device-
specific documentation of your module. You will find it in the download area of your product.
Note:
In case of peripheral or user errors the diagnostic registers will not be updated after the error
has been corrected. The Diagnostic view will show the error message even if the error has

PLCNEXT TECHNOLOGY
been fixed. It is necessary to acknowledge the error message by clicking on the “Confirm”
button. After the error has been fixed and confirmed, the error message in the diagnostic
view will disappear.
Figure 3-19 WBM: “Local Bus” page, “Confirm“ button

3.8 “Configuration” area
3.8.1 “PROFICLOUD” page

The “PROFICLOUD” page provides status information on the connection between the con-
troller and PROFICLOUD.
You can also specify if you want to operate the controller with or without PROFICLOUD con-
nection and which PROFICLOUD services you want to use.
Figure 3-20 WBM: “PROFICLOUD” page
Enabling the If you want to operate the controller with PROFICLOUD connection, you have to enable the
PROFICLOUD connection PROFICLOUD service of the controller. When the PROFICLOUD service of the controller is
enabled, the controller tries to establish a connection to PROFICLOUD.
• Enable the “Enable Proficloud Service” check box.
• Click on the “Apply” button.
The PROFICLOUD connection of the controller is enabled.

PLCNEXT TECHNOLOGY
When the PROFICLOUD connection is enabled, you can specify which service you want to
use.
To protect the PROFICLOUD configuration against unauthorized access, see Section
“Blocking the PROFICLOUD access” on page 129.
Enabling the TSD service • To transfer process data from a PLCnext Engineer project to the TSD PROFICLOUD
service, enable the “Enable Time-Series Data (TSD) Service” check box.
Enabling the PLCnext To download apps from the PLCnext Store to the controller, the PLCnext Store service must
Store service be enabled on the device.
• To enable the PLCnext Store service on the device, enable the “Enable PLCnext Store
Service” check box.
Disabling the If you want to operate the controller without PROFICLOUD connection, you have to disable
PROFICLOUD connection the PROFICLOUD service of the controller. In this case, it is not technically possible to es-
tablish a connection between the controller and PROFICLOUD.
• Disable the “Enable Proficloud Service” check box.
• Click on the “Apply” button.
The PROFICLOUD connection of the controller is disabled.

3.9 “Security” area

The security-related settings for the controller are configured in the “Security” area.
3.9.1 “User Authentication” page
Figure 3-21 WBM: “User Authentication” page
User authentication Enable or disable user authentication on the “User Authentication” page. When user au-
thentication is enabled, authentication with a user name and password is required for ac-
cess to certain components of the controller and certain functions in PLCnext Engineer.
When user authentication is disabled, authentication is not necessary to access the WBM,
the OPC UA server of the controller, or to access the controller using PLCnext Engineer. Ac-
cess to the file system via SFTP and access to the shell via SSH requires authentication
(with administrator rights) even if user authentication is disabled.
User authentication is enabled by default. In the delivery state, the “admin” user is already
created with administrator rights.

PLCNEXT TECHNOLOGY
Recommended:
• Only use the administrator password printed on the controller for initial login into
WBM.
• Once you have logged in successfully, change the administrator password to prevent
unauthorized administrator access.
The modified administrator access data is stored in the overlay file system on the internal
parameterization memory. If you operate the controller with an SD card, the overlay file
system is saved to the SD card.
Please note:
Enabled user authentication only provides a limited degree of protection against unautho-
rized network access.
Due to the communication interfaces of the controller, the controller should not be used in
safety-critical applications unless additional security appliances are used.
• Make sure you always operate the controller with the latest firmware version.
• Follow the security advice on unauthorized network access in Section 1.6.
Enabling/disabling user To enable/disable user authentication, proceed as follows:

authentication • Click on the “Enable/Disable” button next to the “User Authentication” check box.
The “Enable/Disable User Authentication” dialog opens.
Figure 3-22 WBM: “User Authentication” page, “Enable/Disable User Authentication”

dialog
• To enable user authentication, enable the “User Authentication” check box.

• To disable user authentication, disable the “User Authentication” check box.
• Click the “Save” button to apply the setting.
User management Via user authentication, the access data of all users who are authorized to access the con-
troller is managed and the required access permissions are assigned to each user.
The access data of all newly created users is stored on the internal parameterization mem-
ory. If you operate the controller with an SD card, the access data is saved to the SD card.
If the SD card is inserted into another controller of the same type, the access data stored on
the SD card is used for access to the controller.
When inserting the SD card into another controller please note:

If you have changed the administrator access data after logging into WBM for the first
time, the modified access data stored on the SD card will be used for access to the con-
troller. In this case, it is no longer possible to log in with the “admin” user name and the
administrator password printed on the device.

Adding a user Proceed as follows to add a user:

• Click on the “Add User” button on the “User Authentication” page.
The “Add User” dialog opens.
Figure 3-23 WBM: “User Authentication” page, “Add User” dialog
• Enter the user name and password into the respective input field.
• To add the user in the user manager, click on the “Add” button.
Note: When assigning a user name and password, note the length limitation of 127 bytes
for passwords and 63 bytes for user names. The characters are encoded using UTF-8
and the number of bytes used depends on which character is entered. Characters are
coded with one (e.g. letters a-z or digits 0-9) to four bytes (e.g. special characters, um-
lauts, etc.). The length limitation therefore limits the number of bytes and not the number
of characters.
Setting a password Proceed as follows to change a user password:

• Click on the “Set Password” button in the line of the desired user on the “User Authen-
tication” page.
The “Set User Password” dialog opens.
Figure 3-24 WBM: “User Authentication” page, “Set User Password” dialog
• Enter the new password in the “New Password” and “Confirm Password” input fields.
• To save the new password, click on the “Save” button.
Modifying user roles You can select one or more user roles with different permissions for each user.
These permissions control access to:
– The controller SD card
– The controller using PLCnext Engineer
– The PLCnext Engineer HMI
– WBM
– The OPC UA server of the controller
To assign one or more user roles to a user, proceed as follows:

PLCNEXT TECHNOLOGY
• Click on the “Modify Roles” button in the line of the desired user on the “User Authenti-
cation” page (see Figure 3-21 on page 109).
The “Modify Roles” dialog opens.
Figure 3-25 WBM: “User Authentication” page, “Modify Roles” dialog
• Enable the check box of the user role(s) that you would like to assign to the user.
You can manage access permission to the PLCnext Engineer HMI application via the
HmiLevel1...10, EHmiViewer and EHmiChanger user roles. The assigned user roles
specify if and to what extend a user can read and write to the HMI application.
For detailed information on the security functions in a PLCnext Engineer HMI application
as well as on handling HMI user roles, please refer to the PLCnext Engineer online help.
• Click on the “Save” button to save the selected user role(s) for the user.

Table 3-4 shows the possible user roles and access permission.
Table 3-4 User roles and their assigned access permissions in the various applications
User role
CertificateManager
Commissioner
Application or
EHmiChanger
UserManager
DataChanger
EHmiViewer
component of the Access permission
EHmiLevelX
DataViewer
FileReader
FileWriter
controller
Engineer
Service
Viewer
Admin
SD card/parameter- SFTP access to the file system with an
ization memory SFTP client
Please note:
Authentication with a user name
and password is always re- 
quired for SFTP access, even
when user authentication is dis-
abled.
Shell SSH access to the shell
Please note:
Authentication with a user name
and password is always re- 
quired for SSH access, even
when user authentication is dis-
abled.
PLCnext Engineer View values in the cockpit (e.g., utilization,

etc.)
      
PLCnext Engineer Transfer a project to the controller  
PLCnext Engineer Start (cold/warm restart) or stop the con-
troller
   
PLCnext Engineer Restart the controller (reboot) 
PLCnext Engineer Reset the controller to default setting type 1 
PLCnext Engineer View online variable values      
PLCnext Engineer Overwrite variables    
PLCnext Engineer Set and delete breakpoints   
WBM View “General Information” page         
WBM Manage users  
WBM Edit TrustStores and IdentityStores  
WBM Configuring the firewall 

PLCNEXT TECHNOLOGY
Table 3-4 User roles and their assigned access permissions in the various applications
User role
CertificateManager
Commissioner
Application or
EHmiChanger
UserManager
DataChanger
EHmiViewer
component of the Access permission
EHmiLevelX
DataViewer
FileReader
FileWriter
controller
Engineer
Service
Viewer
Admin
WBM Update the firmware 
WBM PROFICLOUD status 
WBM Configuring SD card use 
WBM Overview of app licenses used 
WBM Offline activation of licenses 
WBM Installing/Uninstalling apps  
WBM PROFINET diagnostics         
WBM Local Bus diagnostics         
PLCnext Engineer View online variable values
HMI application
  
PLCnext Engineer Overwrite variables
HMI application
 
OPC UA client View online variable values      
OPC UA client Overwrite variables    
OPC UA client Read files 
 1
OPC UA client Write files 

 2
1
FileReaders can only read files via an OPC UA client if the OPC UA file transfer is activated in PLCnext Engineer (for additional information, please
refer to the PLCnext Engineer online help).
2
FileWriters can only write files via an OPC UA client if the OPC UA file transfer is activated in PLCnext Engineer (for additional information, please
refer to the PLCnext Engineer online help).
Removing a user Proceed as follows to remove a user:

• On the “User Authentication” page, click the “Remove User” button in the line of the user
to be removed.
The “Remove User” dialog opens.
Figure 3-26 WBM: “User Authentication” page, “Remove User” dialog

• Click on the “Remove” button to delete the user.
3.9.2 “Certificate Authentication” page

The “Certificate Authentication” page is used to manage certificates for secure controller
communication. For this, the “TrustStores” and “IdentityStores” tabs are available.
Trusted certificates and revocation lists of possible communication partners are stored on
the “TrustStores” tab.
Your own certificates are stored on the “IdentityStores” tab.
The name for each store can be used with the interfaces for TLS communication, e.g.,
TLS_SOCKET block in IEC 61131-3 or TlsSocket class in C++ or C#. The names of the
stores are case-sensitive.
3.9.2.1 “TrustStores” tab

On the “TrustStores” tab, you can create different TrustStores, name them and add certifi-
cates and revocation lists.
Figure 3-27 WBM: “Certificate Authentication” page, “TrustStores” tab
Please note:
The firmware internally uses “Empty” TrustStore. It cannot be changed in WBM.
Adding a TrustStore • To add a TrustStore, click on the button at the end of the TrustStore table.
• In the dialog that opens, enter a name in the “Name” input field.
• Then click on the “Add” button.
Deleting a TrustStore • To delete a TrustStore, click on the button to the right of the TrustStore table.
• In the window that opens, click on the “Remove” button.

PLCNEXT TECHNOLOGY
Renaming a TrustStore • To rename a TrustStore, click on the button to the right of the TrustStore table.
• Click on the “Rename” button.
Creating a TrustStore Each TrustStore is represented by two tables in WBM:

– “Certificates” table:
In this table, you can manage trusted certificates and issuer certificates.
– “CRL Lists”:
In this table, you can manage the revocation lists (CRL - Certificate Revocation Lists)
for the corresponding TrustStore. For this, you store untrusted certificates and issuer
certificates.
Adding certificates and re- You can add certificates and revocation lists to a TrustStore:
vocation lists • To add a certificate, click on the button below the “Certificates” table of the corre-
sponding TrustStore.
⇒ The “Add Certificate” dialog opens (Figure 3-28).
• To add a revocation list, click on the button below the “CRL Lists” table of the cor-
responding TrustStore.
⇒ The “Add CRL List” dialog opens (Figure 3-29).
In the “Certificates” TrustStore table, a distinction is made between the “Issuer Certificate”
and “Trusted Certificate” certificate types.
• Select the desired certificate type from the “Certificate Type” drop-down list.
Possible settings:
– Issuer Certificate
– Trusted Certificate
Figure 3-28 WBM: “Certificate Authentication” page, “TrustStores” tab, “Add Certificate”
dialog, File Upload
Input method • From the “Input Method” drop-down list, select the way a certificate or revocation list is
to be added to the TrustStore.
Possible settings:
– File Upload
– Text Content

“File Upload”:
You can upload a certificate or revocation list.
• To upload a certificate in .pem format, select “File Upload”.
• Click on “Browse”.
• In the file explorer that opens, select the desired certificate.
⇒ The certificate or revocation list is added to the TrustStore.
Figure 3-29 WBM: “Certificate Authentication” page, “TrustStores” tab, “Add CRL List”
dialog, File Upload
“Text Content”
• To add a certificate or revocation list in text form, select “Text Content”.
• Enter the text into the input field.
⇒ The certificate or revocation list is added to the TrustStore.

PLCNEXT TECHNOLOGY
Figure 3-30 WBM: “Certificate Authentication” page, “TrustStores” tab, “Add Certificate”
dialog, Text Content
Deleting certificates and • To delete a certificate or revocation list from a TrustStore, click on the button of the
revocation lists respective certificate or revocation list.
Detail view The detail views provide detailed information on every certificate and revocation list:
• To open the detail view, click on the button of a certificate or revocation list.
⇒ The detail view opens (see Figure 3-31 and Figure 3-32).

Figure 3-31 WBM: “Certificate Authentication” page, “TrustStores” tab, Certificate De-
tails
Figure 3-32 WBM: “Certificate Authentication” page, “TrustStores” tab, Certificate De-
tails
• To close the detail view, click on the “Close” button.

PLCNEXT TECHNOLOGY
3.9.2.2 “IdentityStores” tab

On the “IdentityStores” tab, you can create and manage different IdentityStores.
Each IdentityStore usually contains an RSA key pair and the corresponding key certificate.
As an option, you can add further issuer certificates to an IdentityStore. The “IDevID” and
“OpcUA-SelfSigned” IdentityStores are part of the system and supplied with the controller.
Figure 3-33 WBM: “Certificate Authentication” page, “IdentityStores” tab
Adding an IdentityStore • To add an IdentityStore, click on the button at the end of the IdentityStore table.
• From the “Key Pair” drop-down list, select the way the key pair is to be added.
Possible settings:
– Enter
– Generate
“Enter”
• From the “Input Method” drop-down list, select the way the key pair is to be added to
the IdentityStore.
Possible settings:
– File Upload
– Text Content

For additional information on the input method, please refer to Section “Input method” on
page 116.
Figure 3-34 WBM: “Certificate Authentication” page, “IdentityStores” tab, “Add Identity-
Store” dialog, entering a key pair
“Generate”
The controller automatically generates a key pair.
• From the “Key Type” drop-down list, select the encryption method.
Figure 3-35 WBM: “Certificate Authentication” page, “IdentityStores” tab, “Add Identity-
Store” dialog, generating a key pair
• To add the IdentityStore, click on the “Add” button.
Deleting an IdentityStore • To delete an IdentityStore, click on the button to the right of the IdentityStore table.
Renaming an Identity- • To rename an IdentityStore, click on the button to the right of the IdentityStore table.
Store • In the dialog that opens, enter a new name into the “New Name” input field.
• Click on the “Rename” button.
Detail view The detail views provide detailed information on every key pair, key certificate or issuer cer-
tificate:
• To open the detail view, click on the button of a key pair or certificate (see also
Figure 3-31 “WBM: “Certificate Authentication” page, “TrustStores” tab, Certificate De-
tails”).

PLCNEXT TECHNOLOGY
• To close the detail view, click on the “Close” button.
Figure 3-36 WBM: “Certificate Authentication” page, “IdentityStores” tab, key pair de-
tails
Downloading public keys You can download the content of the public key of a key pair as a .pem file.
or key certificates If a key certificate is available, you can download it as a .crt file.
• Click on the button in the final column of the respective table entry.
• Save the file to a directory of your choice or directly open the file with a suitable tool.
Setting a key pair • To set a key pair, click on the button in the final column of the table entry.
The options for setting a key pair correspond to the options in Section “Adding an Identity-
Store” on page 120.
Setting a key certificate • To set a key certificate, click on the button in the final column of the table entry.
The options for setting a key certificate correspond to the options in Section “Adding an
IdentityStore” on page 120.
Adding issuer certificates • To add an issuer certificate, click on the button below the table of the corresponding
IdentityStore.
• Select an input method. See Section “Adding certificates and revocation lists” on
page 116.
Deleting issuer certifi- • To delete an issuer certificate, click on the button of the certificate.
cates • In the window that opens, click on the “Remove” button.

3.9.3 “Firewall” page

The controller firewall is configured on the “Firewall” page.
You can only open the “Firewall” page if you are logged into WBM as an administrator. For
information on user roles, please refer to Section 3.9.1 on page 109.
Figure 3-37 WBM: “Firewall” page
“Reset” and “Apply” but- – “Reset”: Click on the “Reset” button to reset the firewall to default settings.
tons – “Apply”: Click on the “Apply” button to transfer all the configured firewall settings to the
controller.

PLCNEXT TECHNOLOGY
“System Message” area In the “System Message” area, responses and warnings are displayed. The following sys-
tem messages are possible:
Table 3-5 Possible system messages
System message Description

Status=Ok The configured firewall settings were successfully transferred to the
controller.
Warning A warning of the controller is issued, e.g., if one or several addi-
tional filter configurations are present in the system. The warning
contains the designations of all additionally loaded filter tables.
Error At least one firewall configuration is faulty.
“System Status” area If the firewall is active, you can generate an overview of all enabled firewall rules in a TXT
file in the “System Status” area.
• Click on the “Show Rules” button.
The TXT file with the activated firewall rules is generated and opened.
• To save the TXT file, in the open dialog, click on the “Save to file” button.
The TXT file with the activated firewall rules is saved to the selected directory.
Figure 3-38 WBM: “Firewall” page, “Firewall Active Rules” dialog
“General Configuration” In the “General Configuration” area, you can view the current firewall status (e.g., Current:
area stopped), temporarily activate or deactivate the firewall or permanently activate or deacti-
vate the firewall.
Temporarily activating or deactivating the firewall

• To temporarily activate the firewall, select the “Start” or “Restart” entry from the drop-
down list in the “Status” line.
• To activate the configuration, click on the “Apply” button.

The firewall is activated. This setting is no longer active after a restart of the controller.
• To temporarily deactivate the firewall, select the “Stop” entry from the drop-down list in
the “Status” line.
The firewall is deactivated. This setting is no longer active after a restart of the controller.
Permanently activating or deactivating the firewall:

• To permanently activate the firewall, enable the check box in the “Activation” line.
The firewall is activated. The firewall remains activated even after a restart of the controller.
• To permanently deactivate the firewall, disable the check box in the “Activation” line.
The firewall is deactivated. The firewall remains deactivated even after a restart of the con-
troller.
3.9.3.1 Configuring the firewall

Configuration of the firewall rules is divided into “Basic Configuration” and “User Configura-
tion”. The “Basic Configuration” tab provides predefined firewall rules while you can create
your own firewall rules on the “User Configuration” tab.
“Action” column The options for activating and deactivating the filter rules are available in the “Action” col-
umn on the “Basic Configuration” tab as well as on the “User Configuration” tab.
• Select a setting from the drop-down list in the “Action” column for each firewall rule:
Table 3-6 Settings in the “Action” column
Option Description
Accept Connections are accepted.
The connection request is accepted. The connection can be established.
Drop Connections are dropped.
There is no response to the request. The packet is dropped.
Reject Connections are rejected.
The sender receives a response via the rejected connection.
Continue The rule is not executed.
Choose this option to skip the basic rule and instead use a user-specific
rule for the port. User-specific rules are configured in the “User Configu-
ration” area.
“Basic Configuration” tab

On the “Basic Configuration” tab, the rules that are stored for the firewall upon delivery are
displayed. For each rule, you can select how the respective connections are to be treated.
“ICMP Configurations” In the “ICMP Configurations”, you specify how incoming and outgoing ICMP echo requests
are to be treated. Possible settings:
– “Incoming ICMP requests accepted“
Check box enabled: Incoming ICMP echo requests are accepted.
Check box disabled: Incoming ICMP echo requests are blocked.
The controller cannot be reached using a ping command.

PLCNEXT TECHNOLOGY
– “Outgoing ICMP requests accepted”

Check box enabled: Outgoing ICMP echo requests are accepted.
Check box disabled: Outgoing ICMP echo requests are blocked. Ping commands can-
not be issued by the controller.
“Basic Rules” The “Basic Rules” area provides predefined firewall rules for different incoming connec-
tions, which you can enable or disable in the “Action” column. The configuration baseline is
stored in the file /etc/nftables/plcnext-filter in the controller file system.
The configuration baseline contains the following rules for incoming connections (“Direc-
tion”: “Input”).
• Select an action for each rule (see Section ““Action” column” on page 125):
Table 3-7 Basic rules
Description Protocol Port

NTP (Network Time Protocol) UDP Port 123
Common remoting, e.g., using TCP Port 41100
PLCnext Engineer
SSH connections (e.g., for SSH shell connection TCP Port 22
or SFTP connection)
HTTP TCP Port 80
HTTPS, PROFICLOUD, eHMI (web server for TCP Port 443
eHMI and WBM)
OPC UA TCP Port 4840
®
External mode Matlab Simulink® TCP Port 17725
SNMP (Simple Network Management Protocol) TCP Port 161
PROFINET unicast/multicast ports UDP Ports 34962-34964
The settings are valid for all Ethernet interfaces. A limitation to certain Ethernet interfaces is
specified via a user-specific rule in the “User Configuration” area (see Section “User config-
uration” on page 127).
With some activated firewall rules there is the risk that accessing the controller becomes dif-
ficult for you due to blocked ports. Restoring access permissions can result in the loss of
user data. Therefore, please consider the following notes when configuring basic rules:
Blocking the WBM access:

If you select the “Reject” or “Drop” action for basic rule no. 5 (TCP Port 443 - HTTPS,
PROFICLOUD, eHMI), you can no longer access the WBM of the controller after activat-
ing the rule (“Apply”). Therefore, you can no longer change the firewall rules via the WBM.
– In case of a permanently started firewall (enabled “Activation” check box):
To stop the firewall in this case, you have to reset the controller to the default settings.
For more detailed information, please refer to the user manual for your controller.
Note that during a reset to the default settings, user-specific data (applications, con-
figuration, etc.) is deleted.
Once the firewall is deactivated, you can again access the WBM.
– In case of a permanently stopped firewall (enabled “Activation” check box):
The firewall is stopped after restarting the controller. You can again access the WBM.

Observe the following when using a PROFINET controller:

If you use the controller as PROFINET controller, you have to ensure that with an activat-
ed firewall, “Accept” is selected for basic rule no. 9 (UDP ports 34962-34964 - PROFINET
unicast/multicast ports). Otherwise, establishing a connection to certain PROFINET de-
vices is not possible.
User configuration
In addition or as an alternative to the basic rules, you can define and activate your own, user-
specific firewall rules for different filter categories in the “User Configuration” area. You can
create new rules, delete rules or change the order of rules using the buttons at the end of
the table.
Adding a new rule
Button Function
“New Rule”: Adds a new filter rule
“Delete Rule”: Deletes the selected filter rule
“Move rule up/down”:

Moves the filter rule upwards/downwards.
The order determines the priority of the rules.
Figure 3-39 WBM: “Firewall” page, “User Configuration” tab, “Input Rules”, adding a
new rule
You can define user-specific filter rules for specific ports, protocols and IP addresses for in-
coming (“Input Rules”) and outgoing (“Output Rules”) connections.

PLCNEXT TECHNOLOGY
• For a user-specific filter rule, define the following parameters:
Table 3-8 User configuration
Column Description
Interface You can configure “Input Rules” specifically for an interface.
(“Input Rules” only) • From the drop-down list, select the desired Ethernet interface
to which the filter rule is to be applied.
The “Output Rules” apply to all interfaces.
Protocol • From the drop-down list, select the TCP, UDP, UDPLITE proto-
col or all of them.
From IP • In the “From IP” field, enter an IP address, if applicable. In the
From Port “From Port” field, enter the corresponding ports, if applicable.
The rule applies to connections coming in from this address. You
can specify all ports, selected ports, or a value range.
To IP In the “To IP” field, enter an IP address, if applicable. In the “To Port”
To Port field, enter the corresponding ports, if applicable. The rule applies
to connections going out to this address. You can specify all ports,
selected ports, or a value range.
Comment Here, enter a description of the filter rule.
Action The options described in Section ““Action” column” on page 125
can be used as actions for the filter rules.
Figure 3-40 WBM: “Firewall” page, “User Configuration” tab, “Output Rules”, creating
user-specific firewall rules
• To activate the settings you configured and transmit them to the system, click on the
“Apply” button.
If a configuration is already present on the system, it is overwritten during this process.
• To drop the current configuration and call the basic settings, click on the “Reset” button.
Changing a basic rule To change a basic rule, proceed as follows:

• In the “Basic Configuration” area, set the basic rule to “Continue” in the “Action” column.
This way, this rule is skipped.
• Now, create a new rule in the “User Configuration”, “Input Rules” area.
• Configure the rule for the protocol and the port of the basis rule from the “Basic Config-
uration” area.
Example: You can specify incoming SSH connection requests via TCP port 22 in more
detail by excluding certain IP addresses or exclusively establishing access of some IP
addresses.

Blocking the Access to the “PROFICLOUD” WBM page is not controlled via user authentication (see
PROFICLOUD access Section ““User Authentication” page” on page 109). Each user with access to WBM can also
access the “PROFICLOUD” page and make settings.
To protect the PROFICLOUD configuration against unauthorized access, you can create a
user without access permission to WBM.
However, if WBM access is required, you can also block the connection to PROFICLOUD
via a firewall configuration.
• For this, create a new rule under “User Configuration” using the following parameters:
– Direction: Output
– Protocol: TCP
– Port: 443
– Action: Drop/reject
Take into consideration that due to this firewall rule, HTTPS and HMI connections are also
blocked.
To permanently block the PROFICLOUD access for a user, you have to configure this user
without security permissions (“User Authentication” WBM page). This way, a user cannot
access the “Firewall” WBM page. The user can therefore not activate the firewall rule which
blocks access to PROFICLOUD. If the user changes the configuration on the “Proficloud”
WBM page, this does not have any consequences as the corresponding ports are blocked
by the firewall. The device cannot establish a connection to PROFICLOUD.
⇒ If you want to generally inhibit communication with PROFICLOUD for one user, you
have to configure this accordingly via the firewall and protect the firewall configuration
against unauthorized access.

PLCNEXT TECHNOLOGY
3.9.3.2 Activating another firewall file

In addition to the PLCnext Technology filter table, you can activate other filter tables. This
might be necessary if you require certain functions that are not supported by the WBM con-
figuration. This additional configuration is implemented via independent filter tables. You
have to create the required functions via nftables commands. For this, you can edit a rule
set in Linux using a text editor or load the file to the PC and change it.
Figure 3-41 Example: nftables filter file
In WBM, clicking on the “Show Rules” button in the “System Status” area, displays all the
activated filter tables.

Figure 3-42 WBM: “Firewall” page, “Show rules”, several active filter tables
If an additional filter table is active, this is displayed as a warning message in the “System
Message” area. The warning contains the designations of all additionally loaded filter ta-
bles.
Configuring the firewall with an additional filter table

If you wish to configure the firewall with additional filter tables, you need root rights (see Sec-
tion “Root rights” on page 82) or the user role “Admin” with the command sudo.
• First, empty the active firmware configuration. To do so, enter the following command
in the shell:
root# nft flush ruleset
• Create another independent filter table using command nft add table <family>
<tablename>.
Example: root# nft add table ip loadfilter.
• Add an “Input Chain” of type “filter” and “hook input” to the created table. Use the follow-
ing command:
nft add chain [<family>] <table> <name> { type <type> hook <hook>
[device <device>] priority <priority> \; }
Example: root# nft add chain ip loadfilter input_limiter { type filter
hook input priority 0 \; }
• Limit the network load:

PLCNEXT TECHNOLOGY
– Limit the number of packets and indicate the parameters (icmp, tcp, udp, udplite,
ip) using the following command.
Example: root# nft add rule loadfilter input_limiter icmp type
echo-request limit rate 10/second accept
– Limit the data rate (bytes/second, mbytes/second, mbytes/minute).
Example: root# nft add rule loadfilter input_limiter limit rate 10
mbytes/second accept or
root# nft add rule loadfilter input_limiter limit rate over 10
mbytes/second drop
• When adding a rule, select the Ethernet interface, to which the rule is to be applied (iif
<network interface>).
Example: root# nft add rule loadfilter input_limiter iif eth0 icmp type
echo-request limit rate over 100bytes/minute drop
• To count packets or display the throughput of bytes, use the following commands:
– For all incoming packets:
nft add rule <table> <chain> counter
Example: root# nft add rule loadfilter input_limiter counter
Note:
For “Accept” action: Accepted packets are counted.
For “Drop” action: Blocked (dropped) packets are counted.
– For a certain protocol:
nft add rule <table> <chain> counter ip protocol <protocol>
Example: root# nft add rule loadfilter
• To drop or accept the data traffic for a certain protocol, use the following commands:
nft add rule <table> <chain> ip protocol <protocol> accept/drop
Example: root# nft add rule loadfilter input_limiter ip protocol udp
accept or
root# nft add rule loadfilter input_limiter ip protocol udplite drop
Example of a simple filter file:
table ip loadfilter {
chain input_limiter {
type filter hook input priority 0; policy drop
icmp type echo-request accept
tcp dport ssh accept comment "allow ssh for remote access"
}
chain output_limiter {
type filter hook output priority 0; policy drop;
icmp type echo-request accept
}
}
General nftables commands
Table 3-9 General nftables commands
Command Description
nft list tables List all active filter tables
nft delete/flush/list table <table> Delete/empty/list a filter table
Example: root# nft flush table loadfilter
nft flush ruleset Delete all active filter settings

Table 3-9 General nftables commands
Command Description
Delete a rule
root# nft list table <table> --handle You can delete a firmware rule by means of its handle number. First,
use this command to list the handle numbers of the individual rules.
Example: root# nft list table loadfilter –handle
Then, you can delete the desired rule via its handle number.
nft delete rule [<family>] <table> Example: root# nft delete rule filter input handle 90
<chain> [handle <handle>]
nft -f <filter-file> Load the content of a filter table from a file
Example: root# nft -f loadfilter.rules
nft list table <table> > <file> Save the content of a filter table to a file
Example: root# nft list table loadfilter >
loadfilter.rules
3.9.4 “SD Card” page
The “SD Card” WBM page is only available for the AXC F 2152 controller.
Please also observe the information and warning notes on the optional SD card in the user
manual for the controller.
If the internal parameterization memory is not large enough for your application, the control-
ler can be operated using an SD card, see Section “SD Card (optional)” on page 39.
Please note the following when operating the controller with an SD card:
The SD card can be read with a conventional SD card reader at any time. Sensitive data
on the SD card can be read if you do not physically protect the SD card against unautho-
rized access.
• Ensure that unauthorized persons do not have access to the SD card.
You can activate or deactivate the support of the SD card on the “SD Card“ page.
If support of the SD card is activated, the SD card is recognized during the initialization
phase of the controller.
If support of the SD card is deactivated, the controller does not recognize the SD card.
When operating the controller without an SD card, please note the following:
If support of the SD card is activated and the controller is operated without an SD card,
there is a risk of data theft or data manipulation. Unauthorized persons can insert an SD
card and restart the controller. In this case, the SD card is recognized during the initializa-
tion phase of the controller. If there is an overlay file system on the internal parameteriza-
tion memory, it will be copied to the SD card. The overlay file system on the internal
parameterization memory will be deleted.
Furthermore, all application-specific data will be deleted from the internal parameteriza-
tion memory. Any PLCnext Engineer projects and IP configurations stored there will no
longer be available. The controller accesses the data stored on the SD card.
Recommended:
• Deactivate support of the SD card if the controller is to be operated without an SD
card.
• Make sure that unauthorized persons do not have access to the controller.

PLCNEXT TECHNOLOGY
Figure 3-43 WBM: “SD Card” page
“Status” area In the “Status“ area, you can see whether the controller is currently being used with or with-
out an SD card.
Operation with SD card:
If you operate the controller with an SD card (display in “Status” area: “External SD Card”),
any application-specific data is stored on the SD card. The overlay file system is generated
on the SD card.
Operation without SD card:
If you operate the controller without an SD card (display in the “Status“ area: “Internal SD
Card“), all application-specific data is saved to the internal parameterization memory of the
controller. The overlay file system is generated on the internal parameterization memory.
“Configuration” area You can activate or deactivate the support of the SD card in the “Configuration“ area (default
setting: “Support external SD Card“ is activated).
• Enable or disable the “Support external SD Card” check box.
• To apply the setting, click the “Apply” button.
The setting will not take effect until the controller has been restarted.

• To drop the setting, click the “Reset” button.
When operating the controller without an SD card, please note the following:
If support of the SD card is activated and the controller is operated without an SD card,
there is a risk of data theft or data manipulation. Unauthorized persons can insert an SD
card and restart the controller. In this case, the SD card is recognized during the initializa-
tion phase of the controller. If there is an overlay file system on the internal parameteriza-
tion memory, it will be copied to the SD card. The overlay file system on the internal
parameterization memory will be deleted.
Furthermore, all application-specific data will be deleted from the internal parameteriza-
tion memory. Any PLCnext Engineer projects and IP configurations stored there will no
longer be available. The controller accesses the data stored on the SD card.
Recommended:
• Deactivate support of the SD card if the controller is to be operated without an SD
card.
• Make sure that unauthorized persons do not have access to the controller.
“System Message” area In the “System Message“ area, information on the current configuration status or changes
of the configuration are displayed (“Information“). Potential security risks are displayed as
well (“Warning“).

PLCNEXT TECHNOLOGY
3.10 “Administration” area
3.10.1 “Firmware Update” page

On this page, you can implement a firmware update of the controller in the admin user role.
Figure 3-44 WBM: “Firmware Update” page
To update the controller firmware, proceed as follows:

• Download the firmware file.
It can be downloaded at phoenixcontact.net/products.
• Unzip the *.zip firmware file.
• Run the *.exe setup file.
• Follow the instructions in the installation wizard.
During installation, the update file (*.raucb) and files with device-specific information will be
copied to the selected destination directory.
Noting the installed firm- The firmware version currently installed on the controller is displayed on the “General Data”
ware version page (see Figure 3-5).
• Before updating the firmware, note the installed firmware version so that you can then
check that the firmware update was successful.

Selecting the firmware file • Click on the “Browse...” button.

• In the file explorer that opens, select the *.raucb firmware file to be installed.
• Click on the “Open” button.

The firmware file to be installed is now displayed in WBM (see Figure 3-45).
Figure 3-45 WBM: Firmware file to be installed in WBM

PLCNEXT TECHNOLOGY
Starting the firmware up- • To start the firmware update, click on the “Start Update” button.
date
The update file is transferred to the controller.
Once the file has been successfully transferred, the firmware update is started.
The status of the file transfer and the status of the update process are displayed in the WBM
as progress bars.
Figure 3-46 WBM: Status of the file transfer and the update process
After the firmware update, the controller is restarted automatically.
Please note:
The connection to the controller is interrupted during the firmware update. After the firm-
ware update, the WBM pages opened in the browser are no longer up to date.
Once the controller is fully initialized after the restart, you have to log into WBM again to
update the WBM pages.
The updated firmware version is displayed on the top right corner of every WBM page.

Checking the firmware • After the controller was restarted, log into WBM again.
version • Open the “General Data” page.
• Check whether the correct firmware version is displayed.
If the previously installed firmware version is still displayed after the firmware update (see
“Noting the installed firmware version”), an error occurred during the firmware update.
• In this case, repeat the firmware update.
3.10.2 “License Management” page
3.10.2.1 “View Containers” tab

The “View Containers” tab on the “License Management” page displays the licenses of the
apps from the PLCnext Store, which are installed on the controller.
Figure 3-47 WBM: “License Management” page, “View Containers” tab

PLCNEXT TECHNOLOGY
Table 3-10 “View Containers” tab
Column Description
Container Serial number of the container
A container is used to manage licenses.
Firm Code Identification of the licenser
(here: Phoenix Contact GmbH & Co. KG).
Product Code Unique identification code of the licensed software.

Feature Map The Feature Map specifies with which scope of functions the app
is installed.
Description Name of the licenser or app license
• Click the “Refresh” button to refresh the overview of the licenses on the controller.
Details • Click on the “Details” button to obtain further information on an app license.
Figure 3-48 WBM: “License Management” page, “Details” view
In addition to the information listed in Table 3-10 ““View Containers” tab”, the following fields
can be found in the “Details” window:
Table 3-11 Details
Field Description
Activation Time Date as of when the license is valid.
Expiration Time Date as of when the license is invalid.
Usage period Usage period in days
Status Current status of the license (“License valid” or “License invalid”)

3.10.2.2 “Offline Activation” tab

On the “Offline Activation” tab, licenses can be activated and deactivated offline with license
files provided by the PLCnext Store.
The “Offline Activation Wizard” provides further information on the activation process.
Figure 3-49 WBM: “License Management” page, “Offline Activation”
When buying an app in the PLCnext Store, you will receive a license information file
(“WibuCmLIF”). Save this file on your PC.
Before the installation you have to license the app first.
Offline Activation step 1 - “Create license context”:

• If no container was found, create one:
– You can create a container directly via the standard procedure option 1 (“Create
container”)
or
– you can create a container via option 2 by uploading a “*.WibuCmLIF“ license in-
formation file that you received after buying an app from the PLCnext Store.
Note: Use this option only when you are asked by the licenser to import a specific
“*.WibuCmLIF“ file.

PLCNEXT TECHNOLOGY
• Upload the “*.WibuCmLIF“ that you received after buying an app from the PLCnext
Store. Use “Option 1“ or “Option 2“ as described on the WBM page for the upload.
Figure 3-50 WBM: “License Management”, “Create license context” (1)
⇒ A “*.WibuCmRaC“ license context file will be created.

• Download the license context file and save it on your PC.
Figure 3-51 WBM: “License Management“, “Create license context“ (2)

Switch to the PLCnext Store:

• Upload the “*.WibuCmRaC“ license context file in the PLCnext Store.
⇒ The PLCnext Store will generate a “WibuCmRaU“ (license update) file based on the in-
formation from the uploaded license context file.
• Download the generated update file and save it on your PC.
Offline Activation - step 2 “Upload license update“:
• Upload the “*.WibuCmRaU“ license update by clicking on the “Browse...“ button.
Figure 3-52 WBM: “License Management”, “Upload license update”
Offline Activation step 3 “Create license receipt”:

⇒ A “WibuCmRaR” (license receipt) file is generated and provided for download.
Figure 3-53 WBM: “License Management”, “Create license receipt”

PLCNEXT TECHNOLOGY
• Download the *.WibuCmRaR“ license receipt file from the WBM and save it on your PC.
Switch to the PLCnext Store:
• To complete the offline licensing, upload the license receipt file (“*.WibuCmRaR”) in the
PLCnext Store.
3.10.3 “PLCnext Apps” page
NOTE: Adverse affect on real-time behavior

Do not operate the “PLCnext Apps” page when the controller is in productive operation.
The real-time behavior can be adversely affected.
Before installing a fully limited app, you have to license the app first. Otherwise you will
not be able to start it.
If you want to fully use a partly limited app, you have to license the app first.
Please note:
– It is not possible to execute more than one Solution App on a controller. If there is al-
ready a PLCnext Engineer project on your controller, it will be deleted when installing
a Solution App.
– If there is already a Solution App on your controller, it is not possible to additionally
start a PLCnext Engineer project on your controller. However, the download of the
project is not prevented by PLCnext Engineer.
– Delete a Solution App directly via the PLCnext Store or use the WBM as described in
the following section.
– After resetting your controller to factory default, every app will be deleted, the licenses
will be retained.
On the “PLCnext Apps” page, you can install and uninstall apps. After successful installation
you can also start and stop the apps. Apps are software applications from libraries up to
complete programs that are provided by the PLCnext Store. After registering you can down-
load apps from the PLCnext Store at https://www.plcnextstore.com.

Figure 3-54 WBM: “PLCnext Apps” page
Installing an app To install an app, proceed as follows:

• Click on the “Install App” button.
• In the file explorer that opens, select the app (*.app) to be installed.
• Click on the “Open” button.
The selected app container will now be sent to the controller and installed. After successful
installation the app will be displayed in the “Installed PLCnext Apps” table.
Uninstalling an app • To uninstall an app, click on the button “Uninstall”.
“Installed PLCnext Apps” The table lists all installed apps with further app-specific information. This information is
table read out of the “app_info.json” file that is a part of every app container. The file contains in-
formation such as app name, a unique app ID, the app version, the minimum firmware ver-
sion that is required, the app manufacturer and the license status. The license status indi-
cates if the app is free, partly or fully limited:
– Fully limited app
A fully limited app has to be licensed before usage. It cannot be started without a valid
license.
– Partly limited app
A partly limited app can be used partly , e.g. time restricted use or limited functionality.
It can be started without a valid license but has to be registered for unrestricted usage.
– Free app
A free app can be used for free without restrictions.
Offline licenses are managed on the “License Management” page in the “Administration”
area.
Starting an app Free or partly limited apps as well as apps with valid license can be started by clicking on
the button “Start”.

PLCNEXT TECHNOLOGY
Note that the starting of several applications may require a restart of the controller. You will
be notified of the forthcoming restart by a dialog that opens.
The app status “RUN” is indicated in the column “App Status”.
Stopping an app • To stop an app, click on the button “Stop”.

The App status “STOP” is indicated in the column App-Status.

Transferring variable values to the PROFICLOUD
4 Transferring variable values to the PROFICLOUD

In PLCnext Engineer, you can define variables whose values are to be transferred as a met-
ric to PROFICLOUD. The variable values are stored in PROFICLOUD. The metrics can be
represented graphically using the open platform Grafana®.
4.1 Creating variables as OUT ports

Variables that are to be transferred from a PLCnext Engineer project to PROFICLOUD have
to be created as OUT ports in PLCnext Engineer.
To create a variable in PLCnext Engineer as an OUT port, proceed as follows:
• In the “COMPONENTS” area, click on “Programming”, “Local” and then on “Programs”.
• Double-click on the desired program from which variables are to be transferred to
PROFICLOUD.
• Select the “Variables” editor.
• Enter the variable name and data type.
• In the “Usage” column, select “OUT Port”.
• Enable the check box in the “Proficloud” column.
Figure 4-1 Creating variables as OUT ports
Note that the “Proficloud” check box has to be enabled for at least one OUT port so that
the controller can send data to PROFICLOUD.

PLCNEXT TECHNOLOGY
If you program your program in C++ using the PLCnext Technology Command Line Inter-
face, you have to define the OUT ports of which the values are to be transferred to PROFI-
CLOUD using attributes Output and Proficloud ( //#attributes
(Output|Proficloud)), see Section “Creating IN and OUT ports” on page 159.
Timestamp The controller sets the timestamp for the data that is transferred to PROFICLOUD. In case
of an interrupted Internet connection, the timestamp is not affected. When the Internet con-
nection is interrupted, data is buffered in the controller. Make sure that the controller time is
set to UTC (for additional information, please refer to Section “System time” on page 78).
4.2 Preparing the controller for PROFICLOUD

Before you can transfer metrics to PROFICLOUD, you have to register the controller in
PROFICLOUD and activate the TSD PROFICLOUD service in the WBM of the controller.
To do this, proceed as follows:
Activating TSD in WBM To establish a connection to WBM, proceed as follows:

• Open the web browser on your PC.
• In the address field, enter URL “http://IP address of the controller”
(example: “http://192.168.1.10”).
If there is an HMI application on the controller, entering URL “http://IP address of the con-
troller” calls the application. To call WBM in this case, enter URL “http://IP address of the
controller/wbm”.
For information on WBM (web-based management) of your controller, please refer to Sec-
tion “Web-based management (WBM)” on page 91.
• Open the “PROFICLOUD” page in the “Configuration” area.
• Enable the check boxes for “Enable Proficloud Service” and “Enable Time-Series Data
(TSD) Service”.
On the “PROFICLOUD” WBM page, you can check the connection status to PROFICLOUD
in the “Proficloud Connection State” line of the table.
4.3 Configuring PROFICLOUD

Connection to the PROFI- • Open the web browser on your PC.
CLOUD administration • In the address line, enter URL “https://www.proficloud.net”.
Logging in • Enter your user name and password.

• Click the “Sign In” button to sign into PROFICLOUD.
Adding a controller • To add the controller as a PROFICLOUD device, select the “TSD Device Manager”
PROFICLOUD solution.

Figure 4-2 Selecting the “TSD Device Manager” PROFICLOUD solution
The “Appliances” page opens.
Figure 4-3 “Appliances” page
Registering PLCNEXT • Click on the “Add” button.

TECHNOLOGY • The “Create Appliance” dialog opens.

PLCNEXT TECHNOLOGY
Figure 4-4 “Create Appliance” dialog
• Enter the UUID of the controller in the “UUID” input field.

The UUID of the AXC F 2152 is printed on the side of the device, for example. You will also
find the UUID in WBM in the “Configuration” area on the “PROFICLOUD” page.
• Enter a unique name for the controller in the “Appliance name” input field.
• Click on the “Add” button to save your entries.

4.4 Displaying an overview of the PROFICLOUD device

metrics
When the controller is switched on, the metrics are automatically transferred to
PROFICLOUD.
To display an overview of all of the metrics of a PROFICLOUD device, proceed as follows:
• Select the “TSD Device Manager” PROFICLOUD solution.
The “Appliances” page opens.
• On the “Appliances” page, click on the controller of which the metrics are to be dis-
played.
The “Appliances/device name” page opens.
Figure 4-5 “Appliances/device name” page
The metrics received are shown in the “Metrics” area.

PLCNEXT TECHNOLOGY
4.5 Displaying the metrics graphically in Grafana®

The metrics can be represented graphically using the open platform Grafana®.
To display a metric graphically in Grafana®, proceed as follows:
Establishing a connection • Select the “TSD Device Manager” PROFICLOUD solution.

to Grafana® • Select the “Go to Analytics” entry in the menu.
The Grafana® homepage opens.
Figure 4-6 Grafana®: Homepage
Creating a new dashboard • Click on the “Home” button.

The “Home” page opens.
Figure 4-7 Grafana®: “Home” page
• Click on the “New Dashboard” button to create a new dashboard.

The “New dashboard” page opens.
Figure 4-8 Grafana®: “New dashboard” page
Selecting the display type • Click on one of the buttons to select a display type (e.g., graph, etc.).
An example display opens for the type of graphical display selected (see Figure 4-9).
Selecting a metric • To be able to select the metric to be displayed, click on “Panel Title”.
• Click on the “Edit” button.
Figure 4-9 Grafana®: Example graph; editing Panel Title

PLCNEXT TECHNOLOGY
An area in which you are able to edit the details of the selected graphical display opens
below the example display.
• Switch to the “Metrics” tab.
• Select the metric to be displayed.
Figure 4-10 Grafana®: Selecting the metric to be displayed
• Close the bottom area by clicking on the “X” button.

The selected metric is now displayed graphically.
Figure 4-11 Grafana®: Graphical display of the selected metric

Structure of a C++ program
5 Structure of a C++ program

If you want to consult the PLCnext Technology SDK C++ header files in parallel while
reading this section, first install the necessary tools as described in “Creating programs
with C++” on page 194.
When naming PLCnext Technology components, observe the naming conventions in

Section “PLCnext Technology naming conventions” on page 237.
With PLCnext Technology, programs that were created in different programming languages
can be used together. For instantiation and calling by the PLCnext Technology firmware,
the programs have a uniform basis. This basis applies to all programming languages.
PLCnext Technology follows an object-oriented approach. The following base classes are
relevant for creating a C++ program for the PLCnext Technology platform.
Library LibraryBase class The LibraryBase class is the smallest unit

that can be downloaded. It represents an
*.so file (shared object). One “Library” can
instantiate one or more “Components”.
Component ComponentBase class The ComponentBase class is a collection
of functions (programs) within the
PLCnext Technology platform.
One “component” can instantiate one or
more “programs”. The “Program” in-
stances can interact via their shared
“Component” instance.
Program ProgramBase class With PLCnext Technology, instances of
the ProgramBase class can be performed
in real time.
Here, the IN and OUT ports are published.
The base classes are stored in the Phoenix Contact SDK. Derive from these base classes
to create your application.
Some sample applications programmed in C++ can be found at https://github.com/plcnext.
5.1 “ILibrary” and “LibraryBase“
Using the PLCnext CLI (see Section 6.1, “PLCnext CLI (PLCnext Command Line Inter-
face)”) or the Eclipse® add-in creates the meta configuration files (libmeta, compmeta,
progmeta) required for PLCnext Engineer as well as the following functions with a func-
tional implementation during compiling. If you have special requirements that go beyond
this, the following descriptions will help you understand the functions.
In a shared object (*.so), there can be exactly one library class (singleton pattern). The
PLCnext Technology firmware initializes the *.so after it has been loaded by calling the fol-
lowing function:

PLCNEXT TECHNOLOGY
extern "C" ARP_CXX_SYMBOL_EXPORT ILibrary& ArpDynamicLibraryMain(AppDomain& appDomain);
This function is implemented in such a way that the library class is created and returned as
an interface. The library object implements the “ILibrary” interface by means of derivation
from the “LibraryBase” class. “ILibrary” is defined in header Arp/System/Acf/ILibrary.hpp,
and “LibraryBase” in Arp/System/Acf/LibraryBase.hpp. The “LibraryBase” class especially
implements a “ComponentFactory” with the “IComponentFactory” interface.
The PLCnext Technology firmware can thus create instances of the components when
loading the PLC program. In order for the PLCnext Technology firmware to be able to deter-
mine the necessary information (names of components and program types, program ports),
the library class also has to implement the “IMetaLibrary” interface (include
"Arp/Plc/Commons/Meta/IMetaLibrary.hpp"). This interface then requires the imple-
mentation of the “ITypeInfoProvider” interface (#include
"Arp/Plc/Commons/Meta/TypeInfoProvider.hpp"), whereby the firmware learns the
names of the components and program types as well as their IN and OUT ports.
The “MetaLibraryBase” (#include "Arp/Plc/Commons/Meta/MetaLibraryBase.hpp")
therefore expands the “LibraryBase” class by these interfaces.
The component instances the PLCnext Technology firmware creates are defined in the
*.acf.config and *.plm.config files.
“AppDomain” and “IApplication”

If you use the Eclipse® add-in, the required header files are included automatically.
– “AppDomain”: Arp/System/Core/AppDomain.hpp
– “IApplication”: Arp/System/Acf/IApplication.hpp
The PLCnext Technology firmware is distributed among several operating system pro-
cesses.
“AppDomain” An “AppDomain” represents such an operating system process. If a library is to be used in

several processes, singleton implementation is performed for each process. The “AppDo-
main” class is used for this. Since the PLCnext Technology firmware uses the same mech-
anism for instantiation, initialization and administration of user components as it does for
core components, the “AppDomain” is also used here.
“IApplication” The operating system process is represented by the “IApplication” interface.
5.2 “IComponent” and “IProgram”
5.2.1 “IComponent” and “ComponentBase”

The basic integration of a component into PLCnext Technology is implemented by means
of derivation from the “ComponentBase” class or via the “IComponent” interface. There are
specialized components for various purposes. These specializations are performed by im-

plementing additional interfaces, which are described in the following subsections. To be

able to use the classes, you have to include (#include) the corresponding header files
(.hpp).
– “IComponent”: Arp/System/Acf/IComponent.hpp
– “ComponentBase”: Arp/System/Acf/ComponentBase.hpp
The following “IComponent” operations are called by the ACF or PLM for each component:
– void Initialize(void)
– void SubscribeServices(void)
– void LoadSettings(const String& settingsPath)
– void SetupSettings(void)
– void PublishServices(void)
In the second phase, the project configuration is loaded and set up. If an exception occurs
here, the project configuration is unloaded again and the controller starts with an empty con-
figuration. The ACF or PLM calls the following “IComponent” operations:
– void LoadConfig(void)
– void SetupConfig(void)
Initialize The component instance is initialized via the functions specified below. These have to be
implemented in the component class. For each instantiated component, the
PLCnext Technology firmware calls the following function first:
virtual void Initialize(void);
SubscribeServices Resources that have been allocated and initialized in the Initialize() function have to be
enabled in the Dispose() function. Thereafter, the firmware calls the following function for
each instantiated component.
virtual void SubscribeServices(void);
Here, a component can obtain RSC services that have already been registered.
LoadSettings Subsequently, the LoadSettings() function is called. The path to the settings (“settings-
Path”) can be specified for the respective component instance in the *.acf.config or
*.plm.config configuration file. The format and content of this configuration file have to be
specified by the respective component (type). The PLCnext Technology firmware does not
make any assumptions regarding these.
virtual void LoadSettings(const String& settingsPath);
SetupSettings Once the settingsPath has been specified, the settings can be applied. The following
function is used for this:
virtual void SetupSettings(void);
PublishServices The PLM does not call the PublishServices function. Creating and registering RSC ser-
vices is reserved for the core components.
virtual void PublishServices(void);
LoadConfig/SetupConfig When the project is loaded subsequently, the following functions are called:
virtual void LoadConfig(void);
virtual void SetupConfig(void);

PLCNEXT TECHNOLOGY
ResetConfig The configuration of the components is reset with the following function:
virtual void ResetConfig(void);
The interface is identical for the user program and function extensions. It is simply called at
different times.
– The PLC manager manages components that make user programs available. The PLC
manager configures them in a file referenced by “/opt/plcnext/projects/De-
fault/Plc/Plm/Plm.config”.
– Function extensions are managed by the ACF (Application Component Framework)
and configured respectively in a file referenced by “/opt/plcnext/Default/De-
fault.acf.config”. The ACF generates these components when booting the firmware.
Dispose A component is stopped after calling the following function:

virtual void Dispose(void);
5.2.2 “IProgramComponent” and “IProgramProvider”

A component that can instantiate user programs implements the interfaces “IProgramCom-
ponent” and “IMetaComponent” by means of derivation from the “ProgramComponent-
Base” class. The PLCnext Technology firmware requires these interfaces to instantiate pro-
grams and receive information on their ports.
The PLCnext CLI generates the necessary code. For this, a code is generated for each
component, which then implements the “IProgramProvider” interface. If the //#program di-
rective is prefixed to the header of a program definition, the PLCnext CLI knows which com-
ponent can instantiate which program. The next directive //#component() is used to name
the corresponding component.
//#program
//#component(SampleComponent)
class SampleProgram : public ProgramBase,
The corresponding header files (.hpp) are included (#include) so that the classes can be
used.
– “IProgramComponent”: Arp/Plc/Esm/IProgramComponent.hpp
– “IProgramProvider”: Arp/Plc/Esm/IProgramProvider.hpp
The component implements the “IProgramComponent” interface by means of derivation
from the “ProgramComponentBase” class. In addition, the component creates a private
member variable that is passed to the “ProgramComponentBase” class in the constructor
of the component. This member variable implements the “IProgramProvider” interface by
means of derivation from the “IProgramProviderBase” class.
The “ProgramProvider” makes the following function available for the instantiation of pro-
grams:
IProgram::Ptr CreateProgramInternal(const String& programName, const String& programType)
The PLCnext Technology firmware calls this function when loading the PLC program.

In the process, the following parameters are passed on in the way they are defined in the
*.esm.config files:
programName Instance name of the program
The instance name is configured in the PLCnext Engineer task editor
or manually via the *.esm.config file.
programType Class name of the program
For each component, the *.compmeta and *.progmeta files describe
the programs (type) a component (type) can generate.
5.2.3 “IProgram” and “ProgramBase“

An instantiated user program implements the “IProgram” interface. As a result, a constructor
to which the instance name is passed on and the Execute() function that is called by the
ESM task during each pass are available. The PLCnext CLI creates such a user program
class that inherits the “IProgram” interface from the “ProgramBase” base class by means of
derivation. Furthermore, the PLCnext CLI enables reporting the IN and OUT ports of the pro-
gram to the GDS.
Creating IN and OUT ports The header file of your program (e.g., MyProgram.hpp) must contain the port definition. The
ports are created as public according to the following pattern.
For example:
public:
//#port
//#attributes(Input| ...)
//#name(...)
int myInPort;
A port is specified by an added attribute. The following attributes are available:
Table 5-1 Attributes for port definition
Input The variable is defined as IN port.
Output The variable is defined as OUT port.
Retain The variable name is retained in case of a warm and hot restart
(only initialized in case of a cold restart).
Opc The variable is visible for OPC UA.
Ehmi The variable is visible for the PLCnext Engineer HMI.
(This attribute is currently not implemented. Implementation is
planned.)
Proficloud The variable is visible for PROFICLOUD (for OUT ports only).
Attributes are separated by the “|” separator.

E.g.: //#attributes (Input|Opc|Retain)
From the attributes, the PLCnext CLI generates the metadata. If a variable does not have an
attribute, is can only be used internally by the program.

PLCNEXT TECHNOLOGY
Provide variables you want to connect via the GDS with an Input or Output attribute, de-
pending on the data direction. You can use all other attributes to control the initialization be-
havior or enable visibility in OPC UA or a PLCnext Engineer visualization. You can also use
these additional attributes without the Input or Output attributes. This way, the variable is
visible, but cannot be connected via the GDS. The Proficloud attribute only works in con-
junction with the Output attribute.
The variable name is also used as the port name. If you want to name the port differently in
the GDS, you can use the //#name() directive to enter a different port name.
To be able to use the classes, you have to include (#include) the corresponding header
files (.hpp).
– “IProgram”: Arp/Plc/Esm/IProgram.hpp
– “ProgramBase”: Arp/Plc/Esm/ProgramBase.hpp
5.2.4 “IControllerComponent”
A component created with the PLCnext CLI automatically derives from the
“IControllerInterface” interface. A function extension may need individual lower-priority
threads to perform longer tasks outside of the ESM task. To this end, the component can
implement the “IControllerComponent” interface in addition to “IComponent”.
The “IControllerComponent” interface defines the following two functions:
void Start (void);
void Stop (void);
If the component is managed by the PLC manager (“User Program”):

– During a cold, warm or hot restart of the PLC application, the Start() function is
called after all program objects of the component have been generated. This is an
ideal time to start individual, lower-priority threads the programs delegate tasks to.
– The Stop() function is called when the PLC application is stopped, before the pro-
grams are destroyed. At this point, the threads created can be destroyed again.
If the component is managed by the ACF (Application Component Framework) (“Function
Extension”):
– When the firmware is started (boot or /etc/init.d/plcnext start), the
Start() function is called after all components have been generated. This is an
ideal time to start threads which perform the component tasks.
– When the firmware is stopped (/etc/init.d/plcnext stop), the Stop() func-
tion is called before the components are destroyed.
To use this class, you have to include (#include) the corresponding header file (.hpp).
– “IControllerComponent”: Arp/System/Acf/IControllerComponent.hpp

5.3 Several component types in the same library
Initially, the Eclipse® add-in creates exactly one component type in a library. If several com-
ponent types are to be instantiated in the same library, each component type has to be
added to the factory. To this end, every component type is introduced to the factory by call-
ing the AddFactoryMethod() function in the constructor of the library object. The PLCnext
CLI generates the required code if the //#component directive is prefixed in the header of
the class definition:
//#component
class SampleComponent : public ComponentBase,
There are two ways to instantiate components:

– “Function Extensions”, managed by the ACF, are instantiated through the De-
fault.acf.config (projects/Default/Default.acf.config) file.
– “User Programs”, managed by the PLM, are instantiated through the Plm.config
(/opt/plcnext/projects/Default/Plc/Plm/Plm.config) file.
When used as PLCnext Engineer library, this is performed automatically by
PLCnext Engineer, but it can also be done manually (see Section “Task configuration
via configuration files” on page 25).
There may be several components in a library, but they must all be either
“Function Extension” (ACF) or “User Program” (PLM). Mixing is not possible.
5.4 PLM (Program Library Manager)

The PLM (Program Library Manager) is part of the PLC manager (see “PLC manager” on
page 18). It loads and unloads components during the runtime of the PLCnext Technology
firmware. The PLM controls the entire service life of the component instance in accordance
with the states of the controller and changes of these states by means of the
PLCnext Engineer command:
– Cold or warm restart
– Hot restart
– Reset
– Download (a reset is implicitly performed prior to the download, however, not during
Download Changes)

PLCNEXT TECHNOLOGY
5.4.1 Functions
The PLM takes on the role of creating, configuring and destroying the components that can
instantiate user programs. The application components are controlled as follows:
Table 5-2 “IComponent” (PLM) functions
Calling of “IComponent” User action in PLCnext Engineer

void Initialize() – Restart
– Send project
void SubscribeServices() – Restart
– Send project
void LoadSettings(const – Restart
string & settingsPath) – Send project
void SetupSettings() – Restart
– Send project
void PublishServices() The function is only called by a firmware compo-
nent, not by the PLM.
void LoadConfig() – Restart
– Cold restart
– Warm restart
– Send project
void SetupConfig() – Restart
– Cold restart
– Warm restart
– Send project
void ResetConfig() – Restart
– Cold restart
– Warm restart
– Send project
void Dispose() – Send project
5.4.2 Configuration
PLM configuration The PLM system is configured via a configuration file. “ConfigSettings” provides the path to
the configuration file of the application libraries and components.
Configuration of The AcfConfigurationDocument format is used to configure components that can instantiate
application programs user programs. The Library, Component (name, type, library, isEnabled), and Settings
(path) elements are evaluated by the PLM (see Section “Configuration files” on page 19).

5.5 ACF (Application Component Framework)

The (ACF) Application Component Framework is the foundation for the
PLCnext Technology platform architecture. The ACF is a framework that enables compo-
nent-based platform development and the configurative composition of the firmware for the
devices. It can configuratively distribute the firmware to one or more processes. The ACF
enables the configurative integration of user functions into the system. This way, you can
extend PLCnext Technology devices with your own functions.
The ACF loads the various shared object files, and starts and manages the components
contained therein in the desired sequence. In PLCnext Technology, components are in-
stantiated as classes, so that several instances of one component type can exist. Instantia-
tion is performed via configuration files for the ACF.
5.5.1 Libraries
ACF libraries are loaded dynamically via configuration by the ACF. They serve as the con-
figurative extension of the system by means of platform or user functions. The ACF libraries
must be available as dynamic libraries (“shared object” or *.so) and contain one or more
ACF components. This enables the user to construct the firmware configuratively and add
functions.
ACF libraries must be implemented in accordance with a particular template. The specified
template is necessary to enable the ACF to access the code dynamically. Implementation
consists of the following elements:
– Library class (derived from “LibraryBase”), implemented as a singleton. A library single-
ton is an instance or function that exists exactly once per library, e.g., “ComponentFac-
tory”.
– At least one component class that implements the “IComponent” interface.
– “ComponentFactory”
See Section ““ILibrary” and “LibraryBase“” on page 155 and Section ““IComponent” and “IP-
rogram”” on page 156.
Loading libraries A library is added to the ACF configuration as shown in the following example:
ACF configuration – adding a library
<AcfConfigurationDocument
xmlns="http://phoenixcontact.com/schema/acfconfig"
xsi:schemaLocation="http://www.phoenixcontact.com/schema/acfconfig"
schemaVersion="1.0" >
<Libraries>
<Library name="MyLibraryACF.Library"
binaryPath="$ARP_PROJECTS_DIR$/MyLibrary/libs/libMyLibraryACF.so" />
</Libraries>
</AcfConfigurationDocument>

PLCNEXT TECHNOLOGY
The following table lists explanations of the individual attributes:
XML element Description

<Libraries> List of libraries
Here, libraries are listed that are to be loaded to cre-
ate components.
<Library> Definition of a library
name Name of the library referenced in a component con-
figuration.
binaryPath Binary path of the library that is to be loaded.
5.5.2 Components
Components are classes in the sense of object-oriented programming. They are a part of a
library and provide a public interface to the library. They therefore facilitate access to librar-
ies with coherent functionality, and can be instantiated once or several times.
ACF components enable the PLCnext Technology platform to be extended configuratively.
The ACF components must be implemented in accordance with a particular template. The
ACF components must register with the “ComponentFactory” of the library. Furthermore,
they must implement the “IComponent” interface in order for the ACF to dynamically inte-
grate them into the firmware (see Section 5.2 ““IComponent” and “IProgram””).
ACF components are instantiated once or several times. They are assigned with a system-
wide unique instance name.
Adding a component Components are added to the ACF configuration as shown in the following example code:
Adding a component to the ACF configuration (example):
<AcfConfigurationDocument
xmlns="http://phoenixcontact.com/schema/acfconfig"
xsi:schemaLocation="http://www.phoenixcontact.com/schema/acfconfig"
schemaVersion="1.0" >

<Components>
<Component name="ACFDemo" type="MyLibraryACF.MyComponentACF" library="MyLibraryACF"
settings="/opt/plcnext/projects/MyLibrary/MySettings.xml" />
</Components>
</AcfConfigurationDocument>
The following table lists explanations of the individual attributes:

<Components> List of the components
Here, components are listed that are to be created.
<Component> Definition of a component


name Name of the component
It must be unique throughout the entire system be-
cause all resources in the system are addressed via
the component name.
type Type name of the component
The name is composed of
<namespace>.<class>
A library can provide several component types. Typ-
ically, C++ type names are used here. The name is
used in the code to register components with the
“ComponentFactory”. This is the only dependency
between the system configuration and the source
code.
library Name of the library that contains the component and
was defined under <Libraries>.
<Settings path> Path to the component settings file
If the component requires a project configuration, the
path to the component-specific project configuration
must be specified in the settings file.
5.5.3 Configuration
ACF configuration As there is just one mechanism for the dynamic integration of components, the ACF config-
uration contains both the firmware settings and the project configuration for the user com-
ponents. The difference is in the storage location. The respective *.acf.config file is either in
the directory for the system settings or for the project configuration.
Project configuration The project configuration is transferred to the controller using PLCnext Engineer, or trans-
ferred manually. The configuration consists of the configuration files of the individual com-
ponents and of ACF configuration files (*.acf.config). These add the user components to the
system. An ARP_PROJECTS_DIR environment variable must be defined in the ACF set-
tings for the project directory (/opt/plcnext/projects). PLCnext Engineer requires this for
downloading the project. If an ACF system or service component has a project configura-
tion, the configuration path must be specified in the component settings (*.settings, XML el-
ement <ConfigSettings> with path attribute).

PLCNEXT TECHNOLOGY
The project directory contains at least two subdirectories: “Default” and “PCWE”. The fur-
ther directory structure is constructed in the same way as the Arp component hierarchy.
Figure 5-1 Project directory
– PCWE directory
The “PCWE” folder is intended for the download from PLCnext Engineer. Files that are
stored here will be overwritten during the next download from PLCnext Engineer (see
Section 2.7.4 “Generating configuration files using PLCnext Engineer”).
– Default directory:
The “Default” folder is intended for storing further configuration files and for the manual,
configurative extension of the platform components (see Section 2.7.5 “Manual config-
uration”).
5.6 Common classes

Common classes provide functions that may be helpful for programming. The
PLCnext Technology-specific common classes are made available via the
PLCnext Technology SDK. With the help of the SDK, it is possible to generate high-level-
language programs in C++ for the PLCnext Technology framework. The SDK provides Arp
firmware header files for this (“ARP SDK”). With the help of the ARP SDK, you can use com-
mon classes in your program. If you want to use a class, integrate it into your program via
an include command. Further information on the common classes and their applications
is available directly in the code commentary.
The useful common classes mentioned in the following sections are part of the
Phoenix Contact SDK, for example. The classes are encapsulated in namespaces accord-
ing to their subject areas.

5.6.1 Threading
During threading, parts of a program are executed in parallel. The “Threading” namespace
provides methods for separating a program into several strings for simultaneous execution,
thus improving the performance of the overall system.
NOTE: Error due to changed priority

You can select a Linux priority between 0 and 99. In order to not disturb the structure of
the real-time threads, Phoenix Contact recommends priority 0. Otherwise, the stability of
the firmware cannot be guaranteed. Programs in ESM tasks are intended for performing
time-critical tasks.
“CpuAffinity” “CpuAffinity” is a bit mask in which one bit is available per processor core. The least signif-
icant bit represents processor core 1. If this bit is set, the scheduler may execute the thread
on this processor core. Several bits can be set simultaneously. In this case, the scheduler
decides on which processor core the thread is to be started, and whether it can be executed
in the runtime of another processor core. If the value of the parameter is 0, the scheduler
can execute the thread on any available processor cores.
“Thread” One instance of this class is used to manage one thread, respectively. You must specify the
function or method that is to be executed in a thread during instantiation. If the
Thread::Start method is called, the thread is executed.
The “Thread” class selects a low priority as standard. Phoenix Contact recommends retain-
ing this priority in order not to endanger the priority structure of the various firmware and op-
erating system tasks.
“WorkerThread” In contrast to the “Thread” class, an instance of the “WorkerThread” class is executed cycli-
cally, as soon as the WorkerThread::Start method is executed. You can define cyclic ex-
ecution of the thread via the idletime parameter. The value is specified in ms.
“ThreadSettings” The “ThreadSettings” class is an auxiliary class for passing the following thread parameters
to a constructor of the “Thread” class:
– Name
– Priority
– CPU affinity (which CPU has been released for the execution of the task)
– Stack size (byte size)
“Mutex” Using the “Mutex” class, you can prevent data of several threads being changed simultane-
ously. The “Mutex” class instances can have two statuses:
– Locked
– Unlocked
Once the Mutex:Lock method has been performed, i.e., the call from the method returns,
the data is protected against modification by other threads. This status is retained until the
instance calls the Unlock() command, therefore rescinding the locked status. A call is
blocked until the thread which is in the Lock state is released again. To prevent a “Dead-
lock”, i.e., a status in which a locked thread cannot be unlocked again, you can use the
“LockGuard” class. This class automates Lock and Unlock of a “Mutex” instance.
“RwLock” The “RwLock” class provides a locking mechanism for increasing performance. This class
is useful if several read accesses, but not many write accesses are necessary. The differ-
ence between “Mutex” class instances and this class is that the instances of the “RwLock”

PLCNEXT TECHNOLOGY
class permit several simultaneous read accesses to the locked structure. Write access at
the same time, however, is not allowed. Instances of this class are therefore suitable for any
data that is often read but only rarely updated.
5.6.2 “Ipc” (Inter-process communication)

The “Ipc” namespace (Inter-process communication) encapsulates classes which can be
used to enable the communication between various processes on the same controller.
“Semaphore” Using the “Semaphore” class, semaphores are implemented in order to synchronize pro-
cesses or threads. In principle, semaphores are integer counters. If one of the various Wait
methods is called, the internal counter is lowered by one. If the current value of the counter
is zero when a Wait method is called, the call is blocked until a different thread on the same
semaphore instance calls the Post method (the Post method increases the internal
counter).
“MessageQueue” Using the “MessageQueue” class, data can be exchanged between processes in the form
of messages. The names of “MessageQueue” instances must begin with an “/” because
otherwise, the call from the constructor will lead to an exception. The name of a queue cor-
responds to the file path in Linux.
5.6.3 “Chrono”
The “Chrono” namespace contains classes and functions with which the temporal se-
quences within an application can be controlled and influenced. This includes the high-res-
olution measurement of time elapsed so far, and also the triggering of actions after a prede-
termined period of time.
“Timer” The “Timer” class is a high-resolution chronometer for interval-based execution of methods.
Instances of this class are used to execute one or more methods periodically at a defined
interval. The “Timer” class calculates the next point in time at which the method is to be
called. You only have to implement the methods that are to be called via the Timer definition.
5.6.4 “Io”
The “Io” namespace encapsulates all functions necessary for working with files and folders
within the file system of the underlying operating system.
“FileStream“ The “FileStream” class is for stream-based editing (opening, writing, reading) of files. The
various values in the class define, for example, whether a file is to be overwritten, an already
existing file is to be opened, or a new file is to be created.
5.6.5 “Net”
The “Net” namespace encapsulates all classes and functions that enable network-based
communication between processes on the same controller or separate controllers. For pro-
cesses that run on the same controller, preferably use the functions from the “Ipc” name-
space (see Section ““Ipc” (Inter-process communication)” on page 168).
“Socket” The “Socket” class is an interface for Ethernet-based communication. Use instances of this
class to establish an Ethernet-to-peer connection. Currently, the UPD and TCP protocols
(IPv4) and TLS (TlsSocket class) are supported.

5.6.6 “Runtime”
The “Runtime” namespace encapsulates functions for the manipulation of individual pro-
cesses that are managed by the Arp firmware.
“SharedLibrary” Using the “SharedLibrary” class, shared libraries (.so files) are dynamically published in ap-
plications during runtime, or reloaded. If a library is successfully reloaded with the
SharedLibrary::Load method, the symbols contained (global variables, classes, meth-
ods, functions, etc.) are then known in the current program. The memory area can be re-
quested with GetFunctionAddress in order for the functions of the library to be used in the
program currently running.
Process The “Process” class is a high-level API for creating and managing new processes.
5.6.7 “Template Loggable”

PLCnext Technology provides a log file on the controller file system in which information on
the system behavior of the PLCnext Technology firmware, warnings, error messages, and
debugging messages are logged. You will therefore find valuable information that can help
you in finding the cause of problems.
“Template Loggable” You can include the “Template Loggable<>” template class to automatically apply a tag to
log messages. A tag can be used to determine from which component/program/... the mes-
sage originates.
To use this class, you have to include (#include) the corresponding header file (.hpp).
– “Loggable”: Arp/System/Commons/Logging.h
PLCnext CLI adds the required lines to the program and component.
The following log levels are supported. For each log level, a suitable method can be called.
– Info
– Warning
– Error
– Fatal
Example call:
log.info ("Info!");
Static call Alternatively, you can also perform logging without the “Loggable” class. Messages can be
written without creating a special logger using the root logger with the static “Log” class. The
“root” tag is assigned to the message. The source of the message is thus not visible in the
log file.
Log::Error ("Error!");
It is also possible to pass and format variables. Placeholders in the form {x} are used for the
variables; where x is the index of the variable.
("Variable a={0} b={1}", a, b);

PLCNEXT TECHNOLOGY
Diagnostic log file The “Output.log” diagnostic log file contains status information, warnings, error messages,
and debugging messages. You will find the file in the /opt/plcnext/logs folder on the file sys-
tem of your controller. The file system is accessed via the SFTP protocol. The SFTP client
software is required for this (e.g., WinSCP) (see Section “Directories of the firmware com-
ponents in the file system” on page 75).
The diagnostic log file is configured in such a way that the messages are overwritten once
the maximum file size is reached. When an error occurs, it is therefore recommended that
the file is called and evaluated as soon as possible.
The diagnostic log file contains the following message types:
– Error & Fatal: If messages of the “Error” or “Fatal” type are issued, the controller is
stopped. The errors mainly arise during startup or during execution of a user program.
– Warning: Warnings indicate potentially occurring errors.
– Information: The core components issue messages of the “Information” type. These
provide an overview of the system status.
Example of an “Output.log” diagnostic log file:
A B C D E
18.05.07 08:24:15.830 MyLibrary.MyComponent INFO - 'MyComponent' invoked of object with instance
name 'MyLibrary.MyComponent-1'
18.05.07 08:24:15.831 Arp.Plc.Plm.Internal.PlmManager INFO - Component 'MyLibrary.MyComponent-1' from library
'MyLibrary' created.
18.05.07 08:24:15.831 MyLibrary.MyComponent INFO - 'Initialize' invoked of object with instance name
'MyLibrary.MyComponent-1'
18.05.07 08:24:15.832 MyLibrary.MyComponent INFO - 'SubscribeServices' invoked of object with in-
stance name 'MyLibrary.MyComponent-1'
18.05.07 08:24:15.832 MyLibrary.MyComponent INFO - Component 'AcfDemo' not found!
18.05.07 08:24:15.833 MyLibrary.MyComponent INFO - 'LoadSettings' invoked of object with instance
18.05.07 08:24:15.833 MyLibrary.MyComponent INFO - 'SetupSettings' invoked of object with instance
18.05.07 08:24:15.834 MyLibrary.MyComponent INFO - 'LoadConfig' invoked of object with instance name
18.05.07 08:24:15.834 MyLibrary.MyComponent INFO - 'SetupConfig' invoked of object with instance name
18.05.07 08:24:15.988 MyLibrary.MyComponent.MyProgram INFO - Added Port 'zaehler (of Data Type 8)' of instance
MyLibrary.MyComponent-1/MyProgram1
18.05.07 08:24:15.989 MyLibrary.MyComponent.MyProgram INFO - Added Port 'zaehler (of Data Type 8)' of instance
MyLibrary.MyComponent-1/P1
18.05.07 08:24:16.121 Arp.Io.Axioline.AxiolineComponent INFO - Axioline: Load configuration.
18.05.07 08:24:16.127 Arp.Io.Axioline.AxiolineComponent INFO - AxiolineComponent::LoadPlc() Path=/opt/plc-
next/projects/PCWE/Io/Arp.Io.AxlC/links.xml
A Date of the message in the format DD.MM.YY

B Time of the message in the format hh:mm:ss.ms
C Component that triggers the message
D Message type (log level)
E Message, e.g., info text, error message, debugging message
plcnextapp log file The plcnextapp tool manages apps, e.g. the mounting and unmounting. The plcnextapp tool
is called by the AppManager. The logfile “plcnextapp.log” is used to record status and error
messages that are issued by the plcnextapp tool. You will find the file by default on your con-

troller under /opt/plcnext/plcnextapp.log. The path to the log file is stored in the settings file
apps_settings.json in the field plcnextappLogFile. The size of the log file is limited to
4 MB.
The following log levels are available:
– Trace
– Debug
– Info
– Warning
– Error
– Fatal
A plcnextapp log message has the same structure as described in “Diagnostic log file” on
page 170. It contains the following elements:
– Time stamp
– Root logger name “PLCnextApp”
– log level
– log message
Example log message:
19.04.19 10:33:57.833 PlcnextApp INFO - SettingsManager - Root Logging Test
5.7 Notifications
The Notification Manager is used for registering, sending and receiving notifications be-
tween components of a controller. The header files required for using the Notification Man-
ager are provided via the PLCnext Technology SDK (see Section 6.1, “PLCnext CLI (PLC-
next Command Line Interface)”). The SDK contains classes for the Notification Manager,
classes for user-defined user data (payload) as well as the payload classes of the
PLCnext Technology firmware. If you want to use a class, integrate it into your program via
an #include command, (e.g., #include
<Arp/System/Nm/NotificationManager.hpp>). Further information on the classes and
their applications is available directly in the code commentary.
Defining the structure of To enable correct interpretation of the user data of a notification, the structure of the user
user data data has to be defined. Use “Arp/System/Nm/SpecializedPayload.hpp” for this. User data
with up to 50 fields can be used as a character string.
Example code with two fields:
// Example payload with two payload fields
#include "Arp/System/Nm/SpecializedPayload.hpp"
// Use the class name as template parameter for SpecializedPayload

class UserLoggedInPayload
: public Arp::System::Nm::SpecializedPayload<UserLoggedInPayload>
{
public:
// Inherit base class constructors

using SpecializedPayload::SpecializedPayload;
// Define a convenient constructor to create the payload

// This constructor will be called by a variadic template and perfect forwarding when
// a notification is sent. Therefore this constructor defines the signature of the

PLCNEXT TECHNOLOGY
// function to send a notification.

// Pass a format string for a user visible representation of the payload to the base
// class' constructor. This format string will be used by the NotificationLogger to
// serialize the payload.
UserLoggedInPayload(const String& username, const String& permissions)
: SpecializedPayload("User logged in: {0} (permissions={1})")
{
// Store the values of the parameters in the underlying payload data structure
this->SetFieldvalue(this->fieldIndexUsername, username);
this->SetFieldvalue(this->fieldIndexPermissions, permissions);
}
// Add getters for a type-safe access to the payload fields
String GetUsername() const
{
return this->GetFieldValueAs<String>(this->fieldIndexUsername);
}
String GetPermissions() const

{
return this->GetFieldValueAs<String>(this->fieldIndexPermissions);
}
private:
// Define the fields of the payload type. Each field is accessed by an index.
// The type infomation is used to ensure only valid information is set to the
// payload fields.
// Use direct member intialization here to ensure these members are also intialized
// when the inherited constructors are used.
// The order of these declarations matters, so don't change them.
const size_t fieldIndexUsername = this->AddField<String>();

const size_t fieldIndexPermissions = this->AddField<String>();
};
Registering and sending Before a notification can be sent, it must be registered with the Notification Manager. If a
notifications component that registered a notification is no longer available, it has to unregister the noti-
fication first. Both operations are implemented using the “NotificationRegistration Proxy Ob-
ject”.
Example:
// in UserManager
NotificationManager& nm= NotificationManager::GetInstance();
auto UserLoggedInRegistration = nm.CreateNotificationRegistration<UserLoggedInPayload>(
"Arp.System.Um.Login", "UserManager", Severity::Info);
UserLoggedInRegistration.SendNotification("hans", "admin");
// notification is deregistered automatically in destructor of UserLoggedInRegistration
Metadata of a notification To register a notification, the sender must specify metadata information:
– notificationName:
The notification name defines under which name the notification is published. The parts
of a name are separated by “.” and, to the level of the component, should correspond
to the name of the component to be sent, e.g., “Arp.System.Um.UserLogin”,
“Arp.Plc.Domain.PlcStateChanged”.
– senderName
Name of the component sending the notification.

– Severity:
Information on the severity of the notification. Processing is not affected by the severity.
– Info: General information
– Warning: Warning for the user
– Error: Error without serious impacts
– Critical: Error with medium impact
– Fatal: Error with serious impact
– PayloadTypeId:
Unique identification for the user data type.
⇒ NotificationNameId is returned:
The ID is used for identifying the instance of a notification. It is required for sending and
unregistering a notification.
The status of a notification registration can have the following states:
– Subscribed: A recipient subscribed but has not yet been registered by a component.
Subscribing to a notification that has not yet been registered or already been unregis-
tered is only permitted during startup of the firmware and the controller. Otherwise, an
exception will be triggered.
– Registered: Registered by a component
– Unregistered: Unregistered by a component
The GetNotificationRegistration() method returns the above meta information about
a notification.
Receiving notifications To receive notifications, the recipient must subscribe to the notification name with the
Notification Manager. A NotificationSubscriber object is used for receiving notifications. If a
recipient is no longer to receive notifications, it has to unsubscribe. To make sure this is
done at the end of the recipient's life cycle, it is recommended to use a proxy object as it is
described for registering of notifications.
Example:
// in eHMI
void HandleUserLogins(const Notification& notification)
{
auto payload = notification.GetPayloadAs<UserLoggedInPayload>();
// do something with payload.GetUsername() and payload.GetPermissions()
}
// in some long living object of eHMI

NotificationManager& nm = NotificationManager::GetInstance();
auto UserLoggedIn = nm.CreateNotificationSubscriber("Arp.System.Um.Login");
UserLoggedIn.OnNotification += make_delegate(HandleUserLogins);
// notification is unsubscribed automatically in destructor of UserLoggedIn
Querying information The INotificationManagerInfo interface is the interface for querying information about the
NotificationManager. The following options are available:
– GetNotificationName(): This method returns the notification name.
– GetNotificationNameId(): This method returns the ID of a notification name.
– GetNotificationRegistration(): This method returns the information about a noti-
fication provided during registration (see Section “Metadata of a notification” on
page 172.)
– GetAllKnownNotificationNameIds(): This method returns a list of NotificationNam-
eIds of all known notifications, independent of their status.

PLCNEXT TECHNOLOGY
– GetNotificationsNameIdsByStatus(): This method returns a list of NotificationNa-

meIds of notifications with a certain status.
5.8 Using RSC services

You have the option of using the already registered RSC services of the SDK (Software De-
velopment Kit) via the “ServiceManager”. The “ServiceManager” acts as the RSC API and
is used to request services.
• Use the #include command in the header file to include the “ServiceManager” class
and the desired service interface (e.g., “IDeviceStatusService”).
Example header file: #include ServiceManager.hpp:
#pragma once
#include "Arp/System/Core/Arp.h"
#include "Arp/System/Acf/ComponentBase.hpp"
#include "Arp/System/Acf/IApplication.hpp"
#include "Arp/System/Acf/IControllerComponent.hpp"
#include "Arp/System/Commons/Logging.h"
#include "Arp/System/Rsc/ServiceManager.hpp"
#include "Arp/System/Commons/Threading/WorkerThread.hpp"
#include "Arp/Device/Interface/Services/IDeviceStatusService.hpp"
• Initialize a pointer to the object matching the desired service by calling the
GetService() method of the “ServiceManager”.
• Pass on the name of the corresponding interface as the template argument.
You can place this call in the SubscribeServices() method of your component, for exam-
ple:
Header file (.hpp):
class ExampleComponent : public .....
{
...
private: //services
IDeviceStatusService::Ptr deviceStatusService;
...
}
Source file (.cpp):

#include....
using namespace Arp::System::Rsc;
using namespace Arp ...
void ExampleComponent::SubscribeServices()
{
// Get service handle

this->deviceStatusService = ServiceManager::GetService<IDeviceStatusService>();
}

Please note that execution of RSC services can take some time (in particular Axioline and
PROFINET services). For this reason, avoid direct calls from ESM tasks.
Please note that exceptions thrown by RSC service calls should always be explicitly
caught and handled by RSC clients.
In addition, the underlying type of each RscVariant returned by RSC service calls should
never be assumed, but should always be checked before performing any other operation
on that object.
RSC services are available for the following areas. You will find more detailed descriptions
in the sections specified.
– Axioline services: Read and write access to data and information from Axioline devic-
es (see Section 5.8.1 on page 175)
– PROFINET services: Read and write access to data and information from PROFINET
devices (see Section 5.8.2 on page 176)
– Device interface services: Access to information and properties of the operating sys-
tem and controller hardware (see Section 5.8.3 on page 178)
– GDS services: Read and write access to the GDS data (see Section 5.8.4 on
page 183)
5.8.1 RSC Axioline services
Please note execution of RSC services can take some time. For this reason, avoid direct
calls from ESM tasks.
on that object.
The Axioline RSC services are only available to PLCnext Technology controllers that sup-
port an Axioline local bus.
The Axioline component can be extended via interfaces for Axioline services. You can use
one interface for acyclic communication (PdiRead, PdiWrite). This interface is available
via the RSC protocol. The parameter data, diagnostic information, and status information
(PDI = Parameters, Diagnostics and Information) of an Axioline device can be read or writ-
ten with the RSC service. Acyclic communication is suitable for the exchange of data that
does not recur cyclically.
5.8.1.1 “IAcyclicCommunicationService”
The “IAcyclicCommunicationService” RSC service in the “Arp/Io/Axioline/Services” name-
space for acyclic communication makes the following methods available:
– PdiRead:
Enables parameters, diagnostics and information of an Axioline device to be read
– PdiWrite
Enables parameters, diagnostics and information of an Axioline device to be written
PdiResult PdiRead(const PdiParam& pdiParam, std::vector<uint8>& data)

PdiResult PdiWrite(const PdiParam& pdiParam, const std::vector<uint8>& data)

PLCNEXT TECHNOLOGY
Parameters are necessary for executing PdiRead and PdiWrite. The PdiParam structure
is used for transmitting the input parameters. The structure has the following elements:
uint16 Slot Device number
uint8 Subslot Subdevice number
uint16 Index Object index
uint8 Subindex Object subindex
The return values are written to the PdiResult structure. The structure has the following el-
ements:
uint16 ErrorCode Error code
uint16 AddInfo Error code, further information
Data that is read (PdiRead) and data that is to be written (PdiWrite) is transferred in a type
unit8 vector (data). A description of the data (maximum size, type, etc.) of the object de-
scription is available in the data sheet of the respective Axioline module.
You need the following headers to use the service. Include them via the #include com-
mand:
– Arp\Io\Axioline\Services\IAcyclicCommunicationService.hpp
– Arp\Io\Axioline\Services\PdiParam.hpp
– Arp\Io\Axioline\Services\PdiResult.hpp
System-specific information on the Axioline F system is available in the PLCnext Engineer
online help system, as well as in the user manuals “Axioline F: System and installation” (UM
EN AXL F SYS INST) and “Axioline F: Diagnostic registers and error messages”
(UM EN AXL F SYS DIAG).
The user manuals can be downloaded at phoenixcontact.net/qr/2404267/manual. Further
information is also available in the data sheets of the respective Axioline modules.
5.8.2 RSC PROFINET services
on that object.
The PROFINET component can be extended via interfaces for PROFINET services. You
can use one interface for acyclic communication (RecordRead, RecordWrite). The inter-
face is available via the RSC protocol. The parameter data, diagnostic information, and sta-
tus information (PDI = Parameters, Diagnostics and Information) of a PROFINET device can
be read or written with the RSC service. Acyclic communication is suitable for the exchange
of data that does not recur cyclically.

5.8.2.1 “IAcyclicCommunicationService”
The “IAcyclicCommunicationService” RSC service in the “Arp/Io/ProfinetStack/Control-
ler/Service” namespace for acyclic communication makes the following methods available:
– RecordRead:
Enables parameters, diagnostics and information of a PROFINET device to be read
– RecordWrite
Enables parameters, diagnostics and information of a PROFINET device to be written
RecordResult RecordRead(const RecordParam& recordParam, std::vector<uint8>& data)
RecordResult RecordWrite(const RecordParam& recordParam, const std::vector<uint8>& data)
Parameters are necessary for executing RecordRead and RecordWrite. The “Record-
Param” structure is used for transmitting the input parameters. The structure provides two
ways of addressing a module:
– Version 1: Addressing via the ID
– Version 2: Addressing via an address that is made up of DeviceName, Slot and Subslot
If one version is selected for addressing, the parameters of the other version must be 0 or
empty.
The “RecordParam” structure has the following elements:
uint16 Id Node ID of the submodule
The ID is assigned automatically. It can be viewed in PLCnext Engineer (version 1). For this, open
the submodule list of the PROFINET submodule node.
To determine the ID, you can also use the AddressToID method of the
IAddressConversionService.hpp service.
RscString<512> Device name
DeviceName Name of the device that is to be addressed (version 2)
uint16 Slot Device number (version 2)
uint8 Subslot Subdevice number (version 2)
uint16 Index Object index
uint8 Length Maximum data amount
Specifies the maximum amount of data to be written in bytes (“RecordRead”) or the amount of
data that is to be written to an object (“RecordWrite”).
The return values are written to the “RecordResult” structure. The structure has the param-
eters below. Further information on the parameters is available in the PROFINET specifica-
tion (version 2.3).
– boolean ServiceDone
– uint8 ErrorCode

PLCNEXT TECHNOLOGY
– uint8 ErrorDecode
– uint8 ErrorCode1
– uint8 ErrorCode2
– unit16 AddData1
– unit16 AddData2
Table 5-3 ErrorCode1
Error code Description

0 No errors
0xF0 Internal error
The error can be evaluated more precisely via ErrorCode2.
Further error codes If a value other than 0xF0 or 0 is displayed in the ErrorCode1
element, the error is described in the ErrorCode, ErrorDe-
code, ErrorCode1, ErrorCode2, AddData1, and AddData2
fields by the PROFINET specification.
Table 5-4 ErrorCode2
Error code Description

0x03 “InvalidAddress”
ID or DeviceName/Slot/Subslot is invalid.
0x15 “RecordReadFailed”
RecordRead failed. This error can occur, for example, if sev-
eral devices simultaneously attempt to execute “RecordRead”
on one device.
0x16 “RecordWriteFailed”
RecordWrite failed. This error can occur, for example, if sev-
eral devices simultaneously attempt to execute “RecordWrite”
on one device.
0x17 “Timeout”
No confirmation was received.
Data that is read (“RecordRead”) or data that is to be written (“RecordWrite”) is transferred

in a type unit8 vector (“data”). A description of the data (maximum size, type, etc.) of the ob-
ject description is available in the PROFINET specification (version 2.3).
You need the following headers to use the service. If necessary, include them via the
#include command:
– Arp/Io/ProfinetStack/Controller/Services/IAcyclicCommunicationService.hpp
– Arp/Io/ProfinetStack/Controller/Services/AcyclicCommunicationServiceProxyFacto-
ry.hpp
– Arp/Io/ProfinetStack/Controller/Services/RecordParam.hpp
– Arp/Io/ProfinetStack/Controller/Services/RecordResult.hpp
5.8.3 RSC device interface services

on that object.
The device interface services provide a range of functions for accessing properties of the
operating system and the controller hardware. You can call the information with the follow-
ing interfaces and defined parameters. The following headers are required to use the ser-
vice. Integrate these via #include, if necessary:
– Arp\Device\Interface\Services\IDeviceInfoService.hpp
– Arp\Device\Interface\Services\IDeviceStatusService.hpp
5.8.3.1 “IDeviceInfoService”
The “IDeviceInfoService” RSC interface enables read access to device information. The
status value of a parameter is read with the GetItem() method. The status values of several
parameters are read with the GetItems() method.
RscVariant<512> GetItem(const RscString<512>& identifier)
void GetItems(GetItemsIdentifiersDelegate identifiersDelegate, GetItemsResultDelegate
resultDelegate)
The following parameters are available for calling of information:
Table 5-5 “IDeviceInfoService” - parameters
Parameter Data type Description

General.DeviceClass UInt32 The “DeviceClass” parameter specifies the device class. At the
moment, only “ProgrammableLogicController” is supported.
0: Undefined
1: ProgrammableLogicController
2. BusCoupler
3: Switch
General.VendorName String The “VendorName” parameter indicates the name of the manufac-
turer.
General.ArticleName String The “ArticleName” parameter indicates the device name.
General.ArticleNumber String The “ArticleNumber” parameter indicates the order number of the
device.
General.SerialNumber String The “SerialNumber” parameter indicates the serial number of the
device.
General.Firmware.Version String The “FirmwareVersion” parameter indicates the firmware version
of the device. Here, the 5-level notation (Major, Minor, Patch,
Build, Status) is used.
General.Firmware.VersionMajor Byte “FirmwareVersionMajor”
Info: The firmware version year is indicated without the first two
digits. E.g., “2019” is indicated as “19”.
General.Firmware.VersionMinor Byte “FirmwareVersionMinor”
General.Firmware.VersionPatch Byte “FirmwareVersionPatch”
General.Firmware.VersionBuild UInt32 “FirmwareVersionBuild”
General.Firmware.VersionStatus String “FirmwareVersionStatus”

PLCNEXT TECHNOLOGY
Table 5-5 “IDeviceInfoService” - parameters

General.Firmware.BuildDate String “FirmwareBuildDate”
ISO 8601 format <YYYY>-<MM>-<DD>
General.Firmware.BuildTime String “FirmwareBuildTime”
ISO 8601 format <hh>:<mm>:<ss>
General.Hardware.Version String The “HardwareVersion” parameter indicates the hardware version
of the device.
General.Fpga.Version String The “FPGAVersion” parameter indicates the FPGA version of the
device. Here, the 3-level notation (Major, Minor, Patch) is used.
General.Fpga.VersionMajor Byte “FPGAVersionMajor”
General.Fpga.VersionMinor Byte “FPGAVersionMinor”
General.Fpga.VersionPatch Byte “FPGAVersionPatch”
General.UniqueHardwareId String Sha256 Hash (32byte) hexadecimal coded as string
General.SPNS.Fpga.Version String FPGA version of the SPNS (only for devices with integrated safety
controller)
General.SPNS.Fpga.VersionMajor Byte SPNS FPGA version, major
General.SPNS.Fpga.VersionMinor Byte SPNS FPGA version, minor
General.SPNS.Fpga.BuildVersion Unsigned32 SPNS FPGA build version
General.SPNS.Firmware.Version String SPNS firmware version
General.SPNS.Firmware.VersionMa- Byte SPNS firmware version, major
jor
General.SPNS.Firmware.VersionMi- Byte SPNS firmware version, minor
nor
General.SPNS.Firmware.BuildVersion Unsigned32 SPNS firmware build version
Interfaces.Ethernet.Count Byte The “NoOfNetworInterfaces” parameter indicates the number of
network interfaces.
Interfaces.Ethernet.{adapterIn- String The “Mac” parameter indicates the MAC address of the selected
dex}.{port}.Mac network interface.
AA:BB:CC:DD:EE:FF
adapterIndex= 1, 2, ... port = 0 for the interface, MAC port = 1, 2,
... for the MAC port
5.8.3.2 “IDeviceStatusService”
This RSC interface enables read access to status information. The status value of a param-
eter is read with the GetItem() method. The status values of several parameters are read
with the GetItems() method. Use the deviceStatusService.GetItem("Parameters")
method to call status information.
RscVariant<512> GetItem(const RscString<512>& identifier)
void GetItems(GetItemsIdentifiersDelegate identifiersDelegate, GetItemsResultDelegate
resultDelegate)

The following parameters are available for calling information:

Status.DeviceHealth Byte The “DeviceHealth” parameter indicates the operating status of
the device.
0: OK
1: WARNING
2: ERROR
Status.Cpu.Load.Percent Byte The “CPULoad” parameter indicates the complete processor load
of the device as a percentage.
0% ... 100%
Status.Cpu.{0}.Load.Percent Byte The “CPULoad{Core}” parameter indicates the processor load of
the selected processor core of the device as a percentage.
0% ... 100%
0x64 = 100%
Core = 0, 1, 2, etc.
Status.Memory.Usage.Percent Byte The “MemoryUsage” parameter indicates the complete memory
usage of the device as a percentage.
0% ... 100%
0x64 = 100%
Status.ProgramMemoryIEC. Byte The “ProgramMemoryUsage” parameter indicates the program
Usage.Percent memory usage of the IEC runtime of the device as a percentage.
0% ... 100%
0x64 = 100%
Status.DataMemoryIEC. Byte The “DataMemoryUsage” parameter indicates the data memory
Usage.Percent usage of the IEC runtime of the device as a percentage.
0% ... 100%
0x64 = 100%
Status.RetainMemory.Usage.Percent Byte The “RetainMemoryUsage” parameter indicates the complete re-
tain memory usage of the device as a percentage.
0% ... 100%
0x64 = 100%
Status.RetainMemoryIEC. Byte The “RetainMemoryUsage” parameter indicates the complete re-
Usage.Percent tain memory usage of the device as a percentage.
0% ... 100%
0x64 = 100%
Status.Board.Temperature.Centigrade Int32 The “BoardTemperature” parameter indicates the temperature of
the interior of the device in °C.
Status.Board.Humidity Byte The “BoardHumidity” parameter indicates the relative humidity in
the device.
0% ... 100%
Status.Cpu.Temperature.Centigrade Int32 The “CPUTemperature” parameter indicates the temperature of
the processor in °C (for RFC 4072S only).

PLCNEXT TECHNOLOGY

Status.KeySwitch.Position Byte The “KeySwitch” parameter indicates the position of the run/stop
switch (for RFC 4072S controller only).
0: Switch in stop position
1: Switch in run position
Status.RamDisk.{RamDiskIndex}.Us- Byte The parameter indicates the memory usage of the RAM disc(s) as
age.Percent a percentage (for RFC 4072S controller only).
0% ... 100%
RamDiskIndex = 1, 2,... Number of the RAM disc (currently, only
one RAM disc is supported, so that the index is always 1)
Status.RamDisk.{RamDiskIndex}.Us- UInt32 The parameter indicates the absolute memory usage of the RAM
age disc(s) (for RFC 4072S controller only).
RamDiskIndex = 1, 2,... Number of the RAM disc (currently, only
one RAM disc is supported, so that the index is always 1)
You can also call status information about the LED states via the “IDeviceStatusService” in-
terface.
The colors of the LEDs are represented as follows, normally in the high word (HW) of the
return value:
public enum LedColor : ushort
{
Green = 1,
Yellow = 2,
Red = 4
};
The status of the LEDs is represented as follows, normally in the low word (LW) of the return
value:
public enum LedStates : ushort
{
Off = 0,
On = 1,
Flashing_0_5_Hz = 2,
Flashing_2_Hz = 3,
Alternating_0_5_Hz = 4,
Alternating_2_Hz = 5
}
Table 5-6 LEDs of the IEC runtime system

Status.Leds.Runtime.Run UInt32 Runtime RUN LED (HW= color, LW= status)
Status.Leds.Runtime.Fail UInt32 Runtime FAIL LED (HW= color, LW= status)
Status.Leds.Runtime.Debug UInt32 Runtime DEBUG LED (HW= color, LW= status)
Table 5-7 Axioline LEDs

Status.Leds.Axio.D UInt32 AXIO master D LED (HW= color, LW= status)
Status.Leds.Axio.E UInt32 AXIO master E LED (HW= color, LW= status)

Table 5-8 PROFINET LEDs

Status.Leds.Pnio.Bf_C UInt32 Pnio controller BF LED (HW= color, LW= status)
Status.Leds.Pnio.Bf_D UInt32 Pnio device BF LED (HW= color, LW= status)
Status.Leds.Pnio.Sf UInt32 Pnio controller SF LED (HW= color, LW= status)
You can also call status information about the network states via the “IDeviceStatusService”
interface:
Table 5-9 Network interface

Status.Interfaces.Ethernet. Byte The “Interface Baudrate” parameter indicates the current speed of
{adapterIndex}.{port}Baudrate the interface.
1: 10 Mbps
2: 100 Mbps
3: 1000 Mbps
adapterIndex = 1, 2, ...
port = 1, 2, ...
Status.Interfaces.Ethernet. Byte The “Interface Duplex Mode” parameter indicates the current du-
{adapterIndex}.{port}.Duplex plex mode of the interface.
1: Half duplex
2: Full duplex
port = 1, 2, ...
Status.Interfaces.Ethernet.{adapterIn- Byte The “Interface Link State” parameter indicates the link status of the
dex}.{port}.Link interface.
0: linkDown
1: linkUp
port = 1, 2, ...
5.8.4 RSC GDS services
on that object.
Access to long STRING variables outside the application is limited to 511 bytes. This ap-
plies to reading and writing via the RSC services “IDataAccessService” and
“ISubScriptionService”. These services are used among others by OPC UA,
PLCnext Engineer HMI and the online functions of PLCnext Engineer.

PLCNEXT TECHNOLOGY
5.8.4.1 “IDataAccessService”
During runtime, the function extensions can use the “IDataAccessService” interface to have
read and write access to the GDS data. The service enables asynchronous reading and
writing of one or more ports or even internal variables. For this access, you need the name
of the port(s) that is/are to be read out. The data read can be written to a database, for ex-
ample.
You need the following header to use the “IDataAccessService” service. If necessary, in-
clude it via the #include command:
– Arp/Plc/Gds/Services/IDataAccessService.hpp
Service functions for direct data access:

Read(): This function is used to read the values of the variable addresses passed on.
–
ReadSingle(): This function is used to read the value of the variable address passed
–
on. Only simple variables are supported (no arrays or structures).
– Write(): This function is used to write the values passed on to the variables of the vari-
able address passed on.
– WriteSingle(): This function is used to write the value passed on to the variables of
the variable address passed on. Only simple variables are supported (no arrays or
structures).
ReadItem ReadSingle(const RscString<512>& portName)
Read(ReadPortNamesDelegate portNamesDelegate, ReadResultDelegate resultDelegate)
DataAccessError WriteSingle(const WriteItem& data)
Write(WriteDataDelegate dataDelegate, WriteResultDelegate resultDelegate)
Each port has a unique name within the GDS that is made up as described in Section “GDS
configuration using configuration files” on page 37. You need the complete name (URI) of a
port to address it. For example, the following port addresses are valid:
– ComponentName-1/ProgramName-1.Variable_Name
– ComponentName-1/Global_Variable_Name
– ComponentName-1/ProgramName-1.Array_Variable_Name
– ComponentName-1/ProgramName-1.Array_Variable_Name[index]
– ComponentName-1/ProgramName-1.Array_Variable_Name[startIndex:endIndex]
– ComponentName-1/ProgramName-1.Struct_Variable_Name.Element1.Leaf
– ComponentName-1/ProgramName-1.Struct_Variable_Name.Element1.LeafArray
– ComponentName-1/ProgramName-1.Struct_Variable_Name.Element1.LeafArray[in-
dex]
The following variable types can be read and written:
– Primitive
– DateTime
– StaticString
– IecString
– Enum:
The values of an enum are only transmitted as BaseType.
– Struct:
You can address the entire structure or each element of a structure, even if it is not an
END element.
Information on the layout of the structure can be obtained from the data that is transmit-

ted.
Example:
Struct Test
Int a
Bool b
In C#, you receive an array from object[] containing values of a and b
Object[]
Int
Bool
In C++, you receive each individual element in an RscVariant. The first type Struct Rsc-
Variant contains information, e.g., that it is a type Struct variable with two elements.
Next, the type Int RscVariant with the associated value and the type Bool RscVariant
with the associated value are read.
– Array:
You can address each individual element or the entire array. You also have the option
to address a specific range of an array. Enter the start index and the end index separat-
ed with a colon for this. Example: ComponentName-1/ProgramName-1.Array_Vari-
able_Name[20:30].
5.8.4.2 “ISubscriptionService”
“ISubscriptionService” offers an alternative to the read functions of “IDataAccessService”.
The variables of which the values are to be read are only registered once and can then be
read continuously. The data can be read more rapidly, and, due to the elimination or variable
addressing, also recorded consistently with the task cycle. All variables in the same ESM
task are recorded in the same cycle (with the exception of the “DirectRead” subscription
type). In addition, “ISubscriptionService” provides timestamps that can be used to assign a
clear recording time to each value.
To use the “ISubscriptionService” class, you require the following header file which was de-
clared in the “Arp::Plc::Gds::Services” namespace:
#include "Arp/Plc/Gds/Services/ISubscriptionService.hpp"
• If necessary, include it via the #include command.
Below you will find a description of how to create, start and read a subscription.
Creating a subscription First, you have to create a subscription.

• To create a subscription, use the following function of “ISubscriptionService”:
uint32 CreateSubscription(SubscriptionKind kind)

PLCNEXT TECHNOLOGY
With this function, the type of the desired subscription is passed on. Select one of the fol-
lowing four types:
Table 5-10 Subscription types

Type Description
“DirectRead” The “DirectRead” subscription records the values directly when the ReadValues() function is
called within the context of the thread to be called. The “HighPerformance”, “RealTime”, and
“Recording” subscription types collect the values within the context of the assigned ESM task.
The data is read directly from the respective variable. A copy process is only implemented if
data is also queried. The read data can be from different task cycles.
This subscription can deliver the best performance with the lowest impact on the real time.
Possible use: Asynchronous data acquisition of non-time-critical data.
“HighPerformance” The “HighPerformance” subscription uses a double buffer which contains the last written data
of a variable. The buffer enables almost simultaneous writing and reading of data.
The “HighPerformance” type is consistent with the task cycle. It uses the least memory and
shows the least impact on the real time (compared to the “RealTime” and “Recording” sub-
scription types).
Possible use: Standard type for acquiring data.
“RealTime” The “RealTime” subscription uses a quad buffer which contains the last written data of a vari-
able. The buffer minimizes access times during reading and writing.
The “RealTime” type is consistent with the task cycle. It guarantees fast data access, but re-
quires four times the amount of memory.
Possible use: The subscription is suitable for variables running in very fast tasks and if fast ac-
cess to read files is required.
“Recording” The “Recording” subscription uses a ring buffer that can store several data items of a variable.
This type is consistent with the task cycle and has low impact on the real time. However, de-
pending on the ring size, it requires a lot of memory. By default, the ring size is set to 10. It can
be configured if the CreateRecordingSubsciption() function is used instead of
CreateSubscription().
Possible use: The subscription is suitable for variables running in tasks that are faster than the
task of the user but the user still needs all values.
Adding variables • Add the desired variables to the subscription by calling one of the following functions:
DataAccessError AddVariable(uint32 subscriptionId, const RscString<512>& variableName)
Or
void AddVariables(uint32 subscriptionId, AddVariablesVariableNamesDelegate variableNamesDelegate,
AddVariablesResultDelegate resultDelegate);

Both functions can be called repeatedly for the same subscription. As with “IDataAccess-
Service”, the variables are addressed via their complete name. Some examples are shown
in the following table:
Table 5-11 Examples for variable addressing
Variable addressing Description

ComponentName-1/ProgramName-1.Variable_Name Program variable
ComponentName-1/Global_Variable_Name Component variable (global variable)
ComponentName-1/ProgramName-1:Array_Variable_Name[index] Array element
ComponentName-1/ProgramName- Structure element (leaf)
1:Struct_Variable_Name.Element1.Leaf
ComponentName-1/ProgramName- Array element from a structure
1:Struct_Variable_Name.Element1.LeafArray[index]
ComponentName-1/ProgramName- Extract of array elements
1:Array_Variable_Name[startIndex:endIndex]
Once a variable was added successfully to the subscription, the

DataAccessError::None value is returned. In case of an error, the following return values
might be returned:
Table 5-12 Return values in the event of an error
Name Description
None No error
NotExists The variable does not exist in the system.
NotAuthorized The user does not have sufficient authorization.
TypeMismatch During writing, the value type is not suitable for the respective
port.
PortNameSyntaxError The port address is syntactically incorrect.
PortNameSemanticError The port address is semantically incorrect.
IndexOutOfRange The address contains an array index that is outside the array.
NotImplemented The variable or service function has not yet been imple-
mented.
NotSupported The variable is not supported.
CurrentlyUnavailable The service is currently unavailable.
UnvalidSubscription The specified subscription was not found or is invalid.
The following types are currently supported:

– Primitive
– DateTime
– String (currently, only StaticString and IecString are supported)
– StaticString
– IecString
– Enum
– Struct
– Array

PLCNEXT TECHNOLOGY
Subscribe/unsubscribe Once you created a subscription and configured it with variables, you can activate it with
Subscribe.
• To activate the subscription, call the following service function:
DataAccessError Subscribe(uint32 subscriptionId, uint64 sampleRate);
With call of the function, copying of the variable starts (exception: for the “DirectRead” type,
no data is automatically recorded).
Use the sampleRate parameter to indicate in which time grid the values are to be recorded.
The sampleRate can only be a multiple of the interval time of a cyclic ESM task. If a
sampleRate that does not correspond to this interval time is passed on, the “Subscription-
Service” rounds the value to the next faster value.
Example: Variables from task A and task B are to be recorded:
– Interval time for task A: 10 ms
– Interval time for task B: 8 ms
If you indicate 50 ms for sampleRate, the following is actually recorded:
– Variables from task A at 50 ms (each fifth cycle)
– Variables from task B at 48 ms (each sixth cycle)
If you indicate value 0 for sampleRate, all data is recorded in the interval of the respective
task.
– Variables from task A at 10 ms
– Variables from task B at 8 ms
When a subscription was started, you can pause it via Unsubscribe.

• For this, call the following service function:
DataAccessError Unsubscribe(uint subscriptionId);
If a subscription pauses, no new data is recorded. Existing data is available in the subscrip-
tion.
• To restart recording, call Subscribe again.
GetVariableInfos This service function shows which variables are currently recorded. Therefore, the function
only returns information once Subscribe is called.
The function only returns information on variable sorting. This information is decisive for
reading the data. Each subscription internally sorts the variables, e.g., by assignment to the
ESM task. The data of added variables is therefore not read in the order in which is was
added. The “Read” functions only provide the raw values of the variables but do not give in-
formation on which variable the value is assigned to. At this point, service function informa-
tion is the only option to assign the values to the respective variables. Variable information
is returned in the same order as data for the “Read” functions. Therefore, variable informa-
tion has to be read before the “Read” functions of a subscription are called for the first time.
A matching “Info” function is available for each “Read” function.
• To query all currently recorded variables, call the following function:
DataAccessError GetVariableInfos(uint32 subscriptionId, GetVariableInfosVariableInfoDelegate vari-

ableInfoDelegate);
• To query the data, call the associated “Read” function:
DataAccessError ReadValues(uint32 subscriptionId, ReadTimeStampedValuesValuesDelegate valuesDele-

gate)

• If, in addition to the variable values, you also require the timestamps of the value acqui-
sition, call the following function:
DataAccessError GetTimeStampedVariableInfos(uint32 subscriptionId, GetTimeStampedVariableInfos-

VariableInfoDelegate variableInfoDelegate)
Information on timestamps is returned in addition to information on the variables. A variable

with the name “timestamp” and of the “Arp.Plc:DataType.Int64” data type is always returned
as the first element of an ESM task. This is followed by all information of the variable that is
associated with the ESM task and can be assigned to the timestamp. If there are variables
of several ESM tasks in the subscription, an additional timestamp is returned for each task,
which is followed by the associated information. Here, information is also returned in the
same order as the data that is returned with the following “Read” function:
DataAccessError GetRecordInfos(uint32 subscriptionId, GetRecordInfosRecordInfosDelegate recordIn-
fosDelegate);
ReadValues Once you have started the recording of a subscription, you can query the acquired data. Dif-
ferent “Read” functions are available for this. The “Read” functions only return the variable
values. The values are not assigned to the respective variable. For assigning the values to
the respective variables, you have to call the corresponding “Info” function once (see Sec-
tion “GetVariableInfos” on page 188).
The following “Read” service functions are available:
DataAccessError ReadValues(uint32 subscriptionId, ReadTimeStampedValuesValuesDelegate valuesDele-
gate)
This function returns all values in a static order. The GetVariableInfos() function is used
for assigning the variables.
Example:
– Added variables from task A: a1, a2
– Added variables from task B: b1
ReadValues:
Object[]
a2
a1
b1
The following function returns all values in a static order, including the associated time-
stamps:
DataAccessError ReadTimeStampedValues(uint32 subscriptionId, ReadTimeStampedValuesValuesDelegate
valuesDelegate);
The timestamps are always located before the associated variable values. The number of
timestamps always corresponds to the number of ESM tasks the variables originate from.
By means of the “DateTime” class, which is defined in the Arp namespace and in the
Arp/System/Core/DateTime.hpp header file, the value of the “timestamp” variable can be
converted into a timestamp. The GetTimeStampedVariableInfos() function is used for
assigning the variables.
Example:

PLCNEXT TECHNOLOGY
ReadValues:
Object[]
Timestamp task A
a2
a1
Timestamp task B
b1
The following function returns all values packed in records:
DataAccessError ReadRecords(uint32 subscriptionId, uint16 count, ReadRecordsRecordsDelegate re-
cordsDelegate);
A record, also called data record, contains only the variable data from an ESM task and the
associated timestamp. The timestamps are always located before the associated variable
values. The variable order is always static and does not change during operation. An ESM
task record is created for each ESM task. It contains all corresponding data records of the
respective ESM task. Depending on the subscription configuration, an ESM task record can
contain several data records.
E.g.: A subscription of the “Recording” type with a task interval of 100 ms and a capacity of
10 returns 10 data records after one second. The timestamps are 100 ms apart. However,
a subscription of the “HighPerformance”, “RealTime”, or “DirectRead” type only always re-
turns one data record. By means of the “Read” function, you can read all subscription data
of the “Recording” type at once.
In addition to the static order of variables in the data records, the order of the ESM task re-
cords is static, too. By means of the GetTimeStampedVariableInfos() function, each
value can be assigned a variable. The variable information describes exactly the first ESM
task record and all data records contained therein, from the first timestamp to the final vari-
able information associated with this timestamp.
By means of the “DateTime” class, which is defined in the Arp namespace and in the
Arp/System/Core/DateTime.hpp header file, the value of the “timestamp” variable in the re-
spective data records can be converted into a timestamp.
Example:
– Task A recorded 2 records.

– Task B recorded 1 record.
ReadRecords:
Object[] (ESM task records)
Objects[] (ESM task record A)
Objects[](data record cycle 1)
Timestamp
a2
a1

Timestamp
a2
a1
Objects[] (ESM task record B)
Timestamp
b1
Changing a subscription You can modify two things of an existing subscription:

– The sampling interval used by the subscription to record data.
– The variables that are to be recorded.
The subscription type can only be changed if you delete the subscription and create it again.
To change the sample rate, proceed as follows:
• Stop the subscription by calling Unsubscribe.
• Execute the subscription by calling Subscribe and entering the new sample rate as the
parameter.
Several functions are available for changing the variables to be recorded:
• To delete a variable from a subscription, call the following function:
DataAccessError RemoveVariable(uint32 subscriptionId, const RscString<512>& variableName),

• To add a variable to a subscription, call the following function:
DataAccessError AddVariable(uint32 subscriptionId, const RscString<512>& variableName)
• To add several variables to a subscription, call the following function:
void AddVariables(uint32 subscriptionId, AddVariablesVariableNamesDelegate variableNamesDele-
gate, AddVariablesResultDelegate resultDelegate);
The changes can be made during operation and also to a subscription that is currently re-
cording. To apply the changes, execute Resubscribe.
• To execute Resubscribe, call the following service function:
DataAccessError Resubscribe(uint32 subscriptionId, uint64 sampleRate);
Once Resubscribe was called, the changes are applied to the subscription. As the internal
memories are rebuilt, data loss might occur.
Deleting a subscription If a subscription is no longer required, you have to delete it. If you do not delete the subscrip-
tion, is will be retained until the next restart of the PLC application (warm or cold restart).
To delete a subscription, call the following function:
DataAccessError DeleteSubscription(uint32 subscriptionId)
The internally reserved memory is released and the subscription ID becomes invalid.

PLCNEXT TECHNOLOGY
5.8.5 Querying notifications
on that object.
Saved notifications can be queried via RSC interfaces. You can use filter criteria for the
query in order to specify the query. You can query all archives or the notifications of one spe-
cific archive. To do so, use the
Arp/Services/NotificationLogger/Services/INotificationLoggerService.hpp
interface. Further information on the classes and their applications is available directly in the
code commentary.
Use the QueryStoredNotifications method to query saved notifications. You can limit
the query using the following parameters:
Table 5-13 Parameters

archives String[] List of names of archives to be queried. If this list is empty, all archives
with sufficient access rights are queried.
filter NotificationFilter Specification of the filter for the query (see Section “Configuring the No-
tification Logger” on page 64)
limit int32 Maximum number of notifications to be returned
sortOrder SortOrder Sorting criterion of the query
language String Desired language of user data (de, en_GB, etc.)
Currently not supported
If using RSC, the filters are described by a structure with reference values or regular expres-
sions. The limits are part of the specified area. The individual criteria are ANDed.
Table 5-14 INotificationLoggerService - Struct: NotificationFilter
Field Data type Description

StoredIdLowerLimit uint64 Lower limit of the StoredId (>=1), is ignored if = 0
In the Notification Logger, a notification is clearly identified by a
StoredId (uint64). The StoredId is assigned by the Notification Log-
ger when adding the notification to the input buffer.
StoredIdUpperLimit uint64 Upper limit of the StoredId (>=1, <=18446744073709551615, max.
uint64), is ignored if = 0
NotificationNameRegExp String Regular expression for the notification name. Is ignored if field is empty.
SenderNameRegExp String Regular expression for the sender name. Is ignored if field is empty.
TimestampBefore String Oldest applicable notification. Is ignored if field is empty. The format
complies with ISO 8601 plus indication of microseconds.
YYYY-MM-DDThh:mm:ss.SSSSSS

Table 5-14 INotificationLoggerService - Struct: NotificationFilter

TimestampAfter String Latest applicable notification. Is ignored if field is empty. The format
complies with ISO 8601 plus additional indication of microseconds.
SeverityLowerLimit String Lowest applicable severity. Is ignored if field is empty.
SeverityUpperLimit String Highest applicable severity. Is ignored if field is empty.
The values are returned via the StoredNotification struct object. The object includes the
following fields:

Id uint64 ID of saved notification (StoreId)
Archive String Name of the archive the notification was loaded from.
If the notification is present in several archives, this field contains a list
of archives separated by commas.
NotificationName String Name of the notification
SenderName String Name of the sender
TimeStamp String Timestamp of when the notification was sent. The format complies with
ISO 8601 plus additional indication of microseconds.
Severity String Severity of the notification
Payload String[] Translated and formatted representation of user data
PayloadXml String[] User data as XML
5.8.5.1 Permissions
Table 5-15 shows which user role is authorized to what extent to call the methods of the INo-
tificationLoggerService. User roles not contained in this table do not have access permis-
sion. For additional information on user roles, please refer to Section 3.9.1 on page 109.
Table 5-15 Authorizations for calling of methods of the INotificationLoggerService
User role QueryStoredNotifications DeleteNotifications ListArchives Other

QueryNotifications
Admin    
Engineer   
Commissioner  
Service  
DataViewer  
DataChanger  
Viewer  

PLCNEXT TECHNOLOGY
6 Creating 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 PLCnext CLI (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 complete libraries
– Extensive toolchain based on a console
The PLCnext CLI 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 PLCnext CLI functions in Eclipse®.
6.1 PLCnext CLI (PLCnext Command Line Interface)

The PLCnext CLI (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 PLCnext CLI creates the metadata required for
PLCnext Technology. The LibraryBuilder contained in PLCnext CLI creates a
PLCnext Engineer library from the project.
The use of the Eclipse® add-in requires the installation of PLCnext CLI (Section “Installing
PLCnext CLI” on page 195) . For information on using the Eclipse® add-in, please refer to
Section “Eclipse® add-in” on page 199.
6.1.1 System requirements

• Before starting the installation, ensure that the system requirements are met.
• Download the necessary software.
Operating system
– The PLCnext CLI is available for tMicrosoft® Windows® 10
Linux (Ubuntu 18.04.1.LTS)
Phoenix Contact software

– PLCnext CLI (PLCnext Command Line Interface):

– 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) or using the Eclipse® add-in
(see Section 6.2.3).
PLCnext CLI and PLCnext Technology SDK are available in the download area of your con-
troller at phoenixcontact.net/products.
Some sample applications programmed in C++ can be found at https://github.com/plcnext.
6.1.2 Installing PLCnext CLI
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
Windows® 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”
Is used by the debug script to query user name and password when logging in to
the controller.
• To check if the packages were installed or are being installed and to install them other-
wise, enter the following command:
sudo apt-get install xz-utils python3 build-essential libunwind8 sshpass
• 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 PLCnext CLI 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 PLCnext CLI installation folder]/plcncli
/usr/local/bin/plcncli
E.g.: ln -s /home/plcncli/plcncli /usr/local/bin/plcncli
6.1.3 Installing SDKs without Eclipse® add-in

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

PLCNEXT TECHNOLOGY
• Call the CLI in the console using the following command:

plcncli install sdk –d [Installation path] –p [Path to archive file]
E.g.: plcncli 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 PLCnext CLI automatically makes the
installation known to the CLI.
Introducing an SDK • To introduce already unpacked SDKs to the CLI, enter the following command:
plcncli set setting SdkPaths –a [Path to SDK]
E.g.: plcncli set setting SdkPaths –a C:\CLI\SDKs\AXCF2152\2019_0\
Uninstalling an SDK – To uninstall an SDK, enter the following command:

plcncli set setting SdkPaths –r [Path to SDK]
The uninstalled SDK is removed from the PLCnext CLI, but will stay on the hard drive.
6.1.4 Functions of the PLCnext CLI
CLI features You can execute many functions directly using the Command Line Interface . The CLI pro-
vides 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:\Program
Files\PHOENIX CONTACT\PLCnCLI 2020.0 LTS\plcncli.exe.
If you added the PLCnext CLI to your system "PATH" variable, you can simply use plcncli
everywhere in the console.

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
Short form:
• To add the parameters, prefix “-”.
E.g.: new project -n MyProject1
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
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.
Example: If you do not specify a directory path via the --output option when creating a new
project, a subfolder is created and used in the current directory.

PLCNEXT TECHNOLOGY
CLI command overview The CLI provides the following commands, which you can use to execute the corresponding
functions. :
Table 6-1 CLI command overview
Command Meaning
build Compile a project
generate Generate configuration and code files
get Query information about projects, controllers, settings etc.
set Change settings, e.g., set a project controller
update Update of controllers in the current project
install Install a SDK
new Create new files/projects
deploy Deploy files for production
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

plcncli 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.
CLI template system With the command plcncli new it is possible to add new files or start new complete proj-
ects. These are based on templates and adapted to the current project or preconfigured by
additional parameters.
Currently available is the PLM program project template (via plcncli new project) which
can be extended by additional programs (via plcncli new program) and components (via
plcncli new component).
A second option is the ACF project template (via plcncli new acfproject). Additional
ACF components can be added (via plcncli new acfcomponents).
For more Information about the project types, refer to Section “Structure of a C++ program”
on page 155.
Example: The following example shows an option of how to configure a project up to the complete
Configuring a project 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”:
plcncli 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 set targets --add -n AXCF2152
• Use the following command to generate the necessary metafiles for the project:
plcncli generate config

• Use the following command to generate the necessary code files for the project:
plcncli generate code
• You can also generate metafiles and code files in only one step:
plcncli generate all
• Compile the project:
plcncli build
• Generate a library:
plcncli 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.2 Eclipse® add-in

The Eclipse® add-in for PLCnext C++ programming enables you to use the PLCnext CLI
functions from you familiar C++ development environment.
6.2.1 Requirements
Installing Eclipse® IDE Phoenix Contact recommends the Eclipse® IDE 2019‑09 development environment.
• Download the Eclipse® IDE 2019‑09 software with the “Eclipse IDE for C/C++ Devel-
opers” package from https://www.eclipse.org.
• Copy and unpack the files to any folder.
• You can execute Eclipse® right away.
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 ver-
sion is installed. If you use a 64-bit Eclipse version, you have to use a 64-bit Java version,
too.
Installing PLCnext CLI • Install the PLCnext Command Line Interface according to the information in
Section 6.1.2, “Installing PLCnext CLI”.
Installing SDKs • Install the SDKs according to the information in Section 6.1.3, “Installing SDKs without
Eclipse® add-in”.
6.2.2 Installing/updating/uninstalling the Eclipse® add-in
Installing the add-in • If necessary, uninstall earlier add-in versions (see “Uninstalling the add-in” on
page 201).
• Start Eclipse®.

PLCNEXT TECHNOLOGY
• Open the “Help, Install New Software...” menu.
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 PLCnext CLI under
.../ide-plugins/com.phoenixcontact.plcnext.updatesite.zip.
• Enter a name of your choice in the “Name” input field and confirm with clicking the “Add”
button of the pop-up dialog.

• Disable the “Contact all update sites during install to find required software” check box
in the lower third of the dialog.
Figure 6-3 “Install” dialog
• Click on the “Next” button.

• Read and accept the license 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”
on page 199.
Uninstalling the add-in • Open the “Help, About Eclipse IDE” menu.

PLCNEXT TECHNOLOGY
• Click on the “Installation Details” button.
Figure 6-4 “Help, About Eclipse IDE” menu
• Select the earlier add-in versions and uninstall them.
6.2.3 Installing SDKs with the Eclipse® add-in for

PLCnext Technology
To install and manage your installed SDKs in Eclipse® you can use the PLCnext CLI SDK
settings.
• Select „Window“, „Preferences“.
• Under the „PLCnext“ entry select „SDKs“.

• Now you can see the installed SDKs, Add already unpacked SDKs, install SDKs from
an archive or remove SDKs from the CLI and optionally from the hard drive.
Figure 6-5 Click Eclipse® Installed SDKs
• Click on „Apply and Close“ to apply the changes.
6.2.4 Creating a new C++ project in Eclipse®

This section describes how to create a new C++ project in Eclipse®.
• Open the “File, New, Project...” menu.
Figure 6-6 Creating a new project
The “New Project” window opens (see Figure 6-7).

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

PLCNEXT TECHNOLOGY
• Confirm your selection with “Next”.
Figure 6-7 Selecting a wizard
• Enter a project name in the “Project name” input field.

• For this example select „PLCnext C++ Project“. Please find more information on the
project types in Section “Structure of a C++ program” on page 155
• In the “Toolchains” area, select the “PLCnext C++ Toolchain” entry.

• Confirm with “Next”.
Figure 6-8 Selecting toolchains

PLCNEXT TECHNOLOGY
• Enter a name for the program and component in the corresponding input fields.
Figure 6-9 Entering a name for the program and component
• Select the desired controller and firmware status for the project.
Figure 6-10 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 now finish the wizard and start creating the program.
6.2.5 Creating 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.4 “Creating a new C++ project in Eclipse®“.
The created project has a defined structure in which the C++ program is created.
Figure 6-11 shows an example.
Figure 6-11 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 Section “Structure of a
C++ program” on page 155.
After instantiation of a program, the assigned ESM task calls the Execute() function of the
program instance in each cycle.
Example projects and the associated documentation can be downloaded at

https://github.com/plcnext.

PLCNEXT TECHNOLOGY
6.2.6 Compiling the project
Recommended: Make the following setting so that your files are saved automatically be-
fore 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 button in the
tool bar.
Figure 6-12 “Build Project”

Successful compilation of the project or possible error messages are displayed on the “Con-
sole” tab.
Figure 6-13 Example: “Console”
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::CppRetain’ is undefined [-Winvalid-offsetof]
You can ignore this warning in conjunction with your defined ports or suppress it using the
-Wno-invalid-offsetof CMake parameter.
Successful compilation If compilation was successful, a shared object (*.so) is generated.
Generating a To be able to use the program in PLCnext Engineer, you need the pcwlx library, which was
PLCnext Engineer library 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.3 Remote 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.

PLCNEXT TECHNOLOGY
7 Creating function blocks and functions with C#

The Visual Studio® extension (PLCnext Technology Development Tools for
Visual Studio®) allows for using Microsoft® Visual Studio® for the development of eCLR
firmware libraries in C# and implementing them on PLCnext Technology devices. Further-
more, you can debug the C# code on PLCnext Technology devices.
Our open IEC 61131 control runtime system eCLR for different automation tasks is struc-
tured as follows:
Figure 7-1 Structure of the eCLR programming system
Additional In addition to the information in the following sections, further information is available in the
information online help “eCLR Programming Reference” and the “Readme.txt” text file. Both the online
help and the text file are available in every eCLR project in Visual Studio®.
Figure 7-2 “eCLR-Programming-Reference.chm” and “Readme.txt”
The eCLR programming system consists of the following components:

CIL compiler The CIL compiler is responsible for translating the CIL code (CIL = Common Intermediate
Language). The eCLR CIL compiler is an ahead-of-time compiler. This means that the CIL
code has been fully translated for the platform before being transferred to the controller
(more importantly, before execution). This fulfills an essential requirement for the real-time
capability of the system. The functional scope of the CIL compiler enables the use of many
C # language elements and namespaces of the Base Class Library, which are listed in Sec-
tion “C# language functions” on page 222.
eCLR core libraries The core libraries consist of eCLR base class libraries (mscorlib.dll, System.dll, Sys-
tem.Core.dll) and some eCLR-specific libraries (eclrlib.dll, pcoslib.dll). The eCLR base
class libraries implement the .NET Framework class libraries. An overview of the supported
functions is available in Section “eCLR Base Class Libraries Reference” of the “eCLR Pro-
gramming Reference” online help (see “Additional information” on page 210).
eCLR runtime The eCLR runtime executes the compiled IL code on the controller. The runtime is respon-
sible for object and memory management, metadata processing (e.g., for debugging), as
well as for the transition of managed API calls to native implementation specific to the oper-
ating system. An overview of the eCLR runtime is available in Section “eCLR runtime func-
tions” on page 225.
7.1 Installing the Visual Studio® extension
7.1.1 System requirements

• Before starting the installation, ensure that the system requirements are met and down-
load the necessary software.
Operating system
– Microsoft® Windows® 7
– Microsoft® Windows® 8.1
– Microsoft® Windows® 10
Phoenix Contact software

– PLCnext Engineer (Order No. 1046008):
To use the libraries created with C# for PLCnext Technology devices, you need the engi-
neering software platform for automation controllers.
– PLCnext Technology controller with eCLR as of version 2019.0 LTS (e.g., AXC F 2152)
– Visual Studio® extension installer
The Visual Studio® extension (tools for Visual Studio for PLCnext Technology C# program-
ming) are available in the download area of your controller at phoenixcontact.net/products.
C# development environment
– Microsoft® Visual Studio® 2015 and 2017
Versions: Enterprise, Pro, Community

PLCNEXT TECHNOLOGY
7.1.2 Installation
Installing the • To install the Visual Studio® extension, run the Windows installation program.
Visual Studio® extension This adds the project and element templates and the debug module to Visual Studio®.
• Check if installation was successful by opening the “Tools, Extensions and Updates”
menu in the Visual Studio® development environment.
If the extensions have been successfully installed, they are displayed as shown in
Figure 7-3:
Figure 7-3 “Extensions and Updates” menu
Uninstalling the If you want to uninstall the Visual Studio® extension, proceed as follows:
Visual Studio® extension • Run the Windows installation program of the Visual Studio® extension.
• In the next dialog, select “Remove”.
You can also use the Windows® “Programs and Features” menu to uninstall the
Visual Studio® extension.
• Select the extension from the list.
• Click on “Uninstall”.

7.2 Creating a firmware library

With Visual Studio® you can create functions and function blocks in C#, which you can sub-
sequently import using the PLCnext Engineer software, and use on a PLCnext Technology
device. You first have to create a new project. To do this, proceed as follows:
• In Visual Studio®, open the “File, New, Project...” menu.
• In the dialog that opens, select “Installed, Templates, Visual C#, PLCnext”.
• Select the “Firmware Library” eCLR template from the list.
• Select a storage path and click on “OK”.
A new, empty eCLR library project is created.
Figure 7-4 Creating a new PLCnext library project

PLCNEXT TECHNOLOGY
• Open the “Project, Add New Item” menu.

• In the dialog that opens, select “Installed, Visual C# Items, PLCnext”.
• Select the “Function Block” or “Function” element from the list.
• Click on “Add”.
⇒ By doing so you create a new template for a function or a function block.
Figure 7-5 Adding a “Function Block”
• When you create a function, select a return value in the following dialog.
Figure 7-6 Adding a new “Function” element: selecting a return value
• In the following cases, select the option „By Reference“ in the area
“Kind of Return Value”:
– recommended for complex data types,
– mandatory for generic data types (ANY).
• Create your function block or function in the template.

• Observe the comments in the template.

• Create the entire project by pressing <F6>. Depending on your configuration, a library
in pcwlx format is created in the release or debug directory of the project.
Figure 7-7 Example: eCLR function block template
• Also observe the information in the “Known Issues and Constraints” section of the on-
line help (see “Additional information” on page 210).

PLCNEXT TECHNOLOGY
7.3 Remote debugging of C# code with Visual Studio®

Using the debugging function can result in an unsafe process interruption.
• Ensure that there is no risk of damage to the equipment or personal injury.
The following sections describe the basic steps needed for setting up a remote debug ses-
sion and establishing a direct connection to a running application by means of
Visual Studio®.
Software used
– PuTTY
– WinSCP
– Microsoft® Visual Studio®
– Visual Studio® extension
Please note:
– The following description is based on the default settings. Consider all changes made
by the user.
7.3.1 Disabling user authentication

Currently, the C# debugging function does not feature an interface for logging on to the con-
troller. To debug the C# code, you have to deactivate the user authentication in WBM (web-
based management) of the controller.
For additional information, please refer to Section 3.9.1 on page 109.
• Deactivate user authentication of your controller via WBM.
Figure 7-8 Example WBM for AXC F 2152: Deactivating user authentication

7.3.2 Opening a port and deactivating TLS

Currently, C# debugging via a secure communication connection is not supported. For this
reason, another port has to be opened for communication with the controller. TLS (Trans-
port Layer Security) has to be deactivated on this port.
• Open WinSCP.
• Establish a connection to the IP address of the controller and a user with root rights (see
Section 2.16.7, “Root rights”).
Figure 7-9 Establishing a connection
• Open the /etc/plcnext/device/System/RscGateway/ folder.

• Open the “RscGateway.settings” file.
Figure 7-10 “RscGateway” directory with “RscGateway.settings” file
• Scroll to the line with the “TcpGatewaySettings”.

PLCNEXT TECHNOLOGY
• Insert the line

<TcpGatewaySettings gatewayId="0" tcpPort="41101"
sessionTimeout="300000" encrypted="false" identityStore="IDevID" />
as shown in the figure below:
Figure 7-11 “RscGateway.settings”
• Save and close the file.

• Restart the controller.
7.3.3 Debug mode
Creating/opening a proj- • Create a new project in Visual Studio®. Set it up.

ect • Follow the operating instructions in Section “Creating a firmware library” on page 213
Or
• Open an existing project
Importing a library in • Import the library in PLCnext Engineer (see Section “Importing libraries into
PLCnext Engineer PLCnext Engineer” on page 228).
Activating debug mode To activate debug mode, proceed as follows:

• Connect PLCnext Engineer to the controller.
• In the “PLANT” area, right-click on the controller.

• In the context menu, select “Debug On/Off”.
Figure 7-12 Activating debug mode in PLCnext Engineer
Attaching Visual Studio® • In Visual Studio® open the “Debug, Attach to Process...” menu.
to the process • From the “Transport” drop-down list, select the “eCLR Device” entry.
• Click on the “Find...” button.
• In the “Attach to eCLR” dialog that opens, enter the IP address of the controller and port
number 41101 (e.g., 192.168.1.10:41101).
• Select the image „download.img“ under the following path:
C:\Users\Public\Documents\PLCnext Engineer\Binaries\<Engineer_Pro-
ject_Save_Name>@binary\RES_<GUID>\
e.g.:
C:\Users\Public\Documents\PLCnext Engineer\Binaries\ExampleProj@bina-
ry\RES_551D5BD523B543DBAE68D4541E34F9D4\download.img

PLCNEXT TECHNOLOGY
Figure 7-13 Attaching Visual Studio® to the process
• Confirm your selection with “OK”.

• Click on the “Attach” button.
• Then add breakpoints in Visual Studio.

Execution of the code is stopped at the breakpoint. You can now evaluate the current vari-
able values.
Figure 7-14 Setting breakpoints in Visual Studio
• Use the functions in Visual Studio to jump to the next breakpoint or continue processing
of the code.
Figure 7-15 Continuing code processing or jumping to the next breakpoint
If you want to make changes to the code within the framework of debugging, you have to
disconnect the process connection (“Detach“):

PLCNEXT TECHNOLOGY
• In Visual Studio, select the “Debug, Detach All” menu.
Figure 7-16 Visual Studio® - “Detach All”
• Make changes to the code and save them.

• Recompile the project. To do so, open the “Build, Rebuild Project name” menu.
• Then, switch to PLCnext Engineer.
• PLCnext Engineer recognizes the change. Save the change.
If the inputs/outputs have been changed, errors might occur in PLCnext Engineer. If nec-
essary, correct them in PLCnext Engineer.
• Transfer the project to the controller.

• Then, reconnect Visual Studio to the process (see Section “Attaching Visual Studio®
to the process” on page 219).
For information on the debug functions in PLCnext Engineer and in
Microsoft Visual Studio®, please refer to the associated documentation.
7.4 Supported functions of the PLCnext Technology

C# programming system
7.4.1 C# language functions
Types
All the integrated types are supported with the exception of decimal.
Type system
– Namespaces, structs, classes, interfaces, enumerations, nested types
– Indexers, properties, operations
– Events, delegates, MultiCastDelegates
– Arrays
– Constructors, static constructors, destructors (finalizers)
– Boxing, unboxing, static casts

– Nullable
Polymorphy
– Virtual mechanism (virtual, overwrite, abstract)
– Dynamic casts (as)
Modifiers and keywords

– public, internal, protected, private
– readonly, const, sealed, unsafe
– params, ref, out
– base, this
– explicit, implicit, operator
Operators
– new, sizeof, typeof, as, is
– All unary operators
– All binary operators
– Prefix, postfix and conditional operator
– Cast and index operator
Control structures and statements

– if, else
– switch, case, default (also on strings)
– for, do, while, foreach, break, continue
– goto, return
– using, fixed
– lock
Exceptions
– throw
– try, catch, finally
For additional information, please refer to Section “Known issues and constraints” on
page 225.
7.4.2 Base class libraries

Below you will find a list of the most important classes that have been implemented in the
eCLR base class library, separated by namespaces. A complete list of the implemented
classes with additional information is available in Section “eCLR Base Class Libraries Ref-
erence” of the “eCLR-Programming-Reference.chm” online help (see “Additional informa-
tion” on page 210).
System
All integrated types, as well as the following:
– Char, Boolean, Int32, Single, etc., with the exception of decimal
– All common exception types

PLCNEXT TECHNOLOGY
– Common interfaces such as:

IDisposable, IComparable, ICloneable, IFormatProvider, IFormattable
– String, array, object, valuetype
– Version, DateTime, TimeSpan, TimeZone
– BitConverter, Convert
– GC
– Console
– Uri, UriBuilder
System.Collections
– IEnumerator, IEnumerable, ICollection, IList, IDictionary, IComparer
– ArrayList, Hashtable, Queue
– Comparer, DictionaryEntry
System.Collections.Generic
– IEnumerator<T>, IEnumerable<T>, ICollection<T>, ICollection<T>, IList<T>,
IDictionary<TKey,TValue>, IComparer<T>
– Dictionary<TKey,TValue>, List<T>, Queue<T>
– Comparer<T>, KeyValuePair<TKey,TValue>
System.Globalization
– Calendar, CalendarWeekRule
– CultureInfo
Supported cultures: de-DE, en-US, en-GB, Invariant
Types that support the localized formatting/parsing: all number types, DateTime, Time-
Span
– DateTimeFormatInfo, NumberFormatInfo, NumberStyles, DateTimeStyles
System.IO
– Path, File
– Stream, FileStream, MemoryStream
– BinaryReader, BinaryWriter
– TextReader, TextWriter, StreamReader, StreamWriter, StringReader, StringWriter
System.Security.Cryptography
– CryptoConfig
– HashAlgorithm, MD5, MD5CryptoServiceProvider
System.Text
– StringBuilder
– Encoding, ASCIIEncoding, UTF8Encoding, UnicodeEncoding (big endian and little en-
dian)
System.Threading
– Thread, ThreadPool, ThreadStart, ThreadState
– Monitor (lock)
– WaitHandle, EventWaitHandle, AutoResetEvent, ManualResetEvent, WaitCallback

– Timer, TimerCallback
System.Net
– IPAdress, IPEndpoint, Endpoint, SocketAddress
System.Net.Sockets
– NetworkStream
– AddressFamily, ProtocolType
– Socket, SocketType
7.4.3 eCLR runtime functions
Garbage collection
Memory management is performed by the eCLR. The garbage collector should explicitly
only be called at a specific point in time (application of GC.Collect).
Implicit finalization
The finalizer of each applicable .NET class (implementing ~T()) is called when teh garbage
collector releases the instance. The garbage collector collect function is called automati-
cally. The time of the implicit call cannot be predicted.
Implicit initialization
All the integrated types and value types (struct) are implicitly initialized with their default val-
ues. Reference type instances are implicitly initialized with the value “zero”.
Debug support
– Defining breakpoints
– Evaluation of instance values and local variables, as well as arguments from the current
method
– Providing call stack information
Known issues and constraints

For detailed information, please refer to Section “Known Issues and Constraints” of the
Visual Studio® extension online help (see “Additional information” on page 210).
7.5 Supported data types

The following table illustrates how the IEC 61131-3 data types are linked to the .Net Frame-
work and C#. Variables of data types that are marked with a “+” in the “Attribute data type”
column must have the optional “DataType” attribute for unique assignment.
Table 7-1 Supported IEC 61131-3, .Net Framework, and C# data types
IEC 61131-3 .Net Framework C# Attribute data type

BOOL System.Boolean bool -
SINT System.SByte sbyte -
INT System.Int16 short -

PLCNEXT TECHNOLOGY
Table 7-1 Supported IEC 61131-3, .Net Framework, and C# data types
IEC 61131-3 .Net Framework C# Attribute data type
DINT System.Int32 int -
LINT System.Int64 long -
USINT System.Byte byte -
UINT System.UInt16 ushort -
UDINT System.UInt32 uint -
ULINT System.UInt64 ulong -
REAL System.Single float -
LREAL System.Double double -
TIME System.UInt32 uint +
LTIME System.Int64 long +
LDATE System.Int64 long +
LTOD System.Int64 long +
LDT System.Int64 long +
BYTE System.Byte byte +
WORD System.UInt16 ushort +
DWORD System.UInt32 uint +
LWORD System.UInt64 ulong +
STRING System.Iec61131Lib. -
IecStringEx
ANY System.Iec61131Lib.Any +
ANY_MAGNITUDE System.Iec61131Lib.Any +
ANY_NUM System.Iec61131Lib.Any +
ANY_INT System.Iec61131Lib.Any +
ANY_SIGNED System.Iec61131Lib.Any +
ANY_UNSIGNED System.Iec61131Lib.Any +
ANY_REAL System.Iec61131Lib.Any +
ANY_BIT System.Iec61131Lib.Any +
ANY_ELEMEN- System.Iec61131Lib.Any +
TARY

Matlab® Simulink®
8 Matlab® Simulink®
Matlab® Simulink® is a software program for the model-based development of dynamic
systems.
The “PC Worx Target for Simulink” software add-on (Order No. 2400041) enables the con-
version of Simulink® models into device-specific code for use with Remote Field und Axio-
line controllers. The models converted from Simulink® can be integrated into the PC Worx
and PLCnext Engineer development environments.
The model-based design and versatile simulation possibilities of Simulink® can therefore
also be used for automation projects within PLCnext Technology. A structured model imple-
mentation can be ensured, thanks to the automatic creation of executable code. The import
and configuration options in PLCnext Engineer also enable Simulink® models to be oper-
ated together with programs that have been created in IEC 61131-3 languages or C++. The
combination with other high-level-language programs in the same task and execution in the
real-time context is therefore also possible for Simulink® models. Furthermore, you can also
implement monitoring of model parameters, and optimization of the models during execu-
tion via “external mode”.
For additional information on the add-on and its use, please refer to:
– PC Worx Target for Simulink product page (Order No. 2400041):
phoenixcontact.com/webcode/#1955
– Tutorial videos in the PLCnext Community:
plcnext-community.net/index.php?option=com_content&view=category&lay-
out=blog&id=71&Itemid=339&lang=en

PLCNEXT TECHNOLOGY
9 Importing libraries into PLCnext Engineer

You will find additional information on PLCnext Engineer in the online help and the quick
start guide (PLCNEXT ENGINEER, Order No. 1046008).
Once you have generated a *.pcwlx library from a C++ or C# library, import this library into
the PLCnext Engineer software. In PLCnext Engineer, imported libraries are treated as an
ICE 61131-3 program or as a function or function block, and are processed in tasks.
To import a library into PLCnext Engineer, proceed as follows:
• Open your PLCnext Engineer project or create a new AXC F 2152 template.
• In the “COMPONENTS” area, click on “References”.
• Right-click on “Libraries”.
Adding a library • Right-click to open the “AddUser Library” context menu.
Figure 9-1 “Add User Library” context menu
• In the dialog that opens, select the desired *.pcwlx library.

• Click on “Open”.
The component and program or the function or function block are now available in the
“COMPONENTS” area under “Libraries”.
Figure 9-2 PLCnext Engineer - Libraries

Importing libraries into PLCnext Engineer
Adding functions/function The library is now a part of the PLCnext Engineer project. The POUs (Program Organization
blocks Units) contained therein can be used in the project, for example in the FBD (Function Block
Diagram).
• Open the “Main” code worksheet via the “COMPONENTS” area.
• Open the “Code” program editor.
• Add the new C# function block by dragging it from the “COMPONENTS” area under “Li-
braries” to your code worksheet.
Figure 9-3 Inserting a function block
Assigning inputs/outputs Additional information is available in the Readme.txt file (see “Additional information” on
page 210).
Instantiating a program To instantiate a program contained in a library, proceed as follows:

• In the “PLANT” area, select the “PLCnext” node.

PLCNEXT TECHNOLOGY
• Open the “Tasks and Events” editor.
Figure 9-4 Opening the “Tasks and Events” editor
• In the editor, create a new task or open an existing task.

• Drag and drop the program from the “COMPONENTS” area to the “Name” column be-
low the desired tasks. This way you generate a program instance.
Figure 9-5 Example: CPP_Counter_P1 program instance in the “Task and Event” edi-
tor
The programs in the “COMPONENTS” area are displayed at different locations, depending
on the programming language they were written in.
– Programs that were created in IEC 61131 can be found under “Programming”. A dis-
tinction is made between:
– “Local, Programs”: Programs from the same project are located here.
– “Library name”: Programs from an IEC 61131 library are located here.
– Programs that were created in C++ or Matlab® Simulink® are located under “PLCnext
Components & Programs”, “Library name”, “Component name”.
– Functions and function blocks created with C# are located under “PLCnextBase”.

Figure 9-6 Programs, function blocks and functions in PLCnext Engineer
Assigning IN/OUT ports • In the “PLANT” area, select the “PLCnext” node.
• Open the “Data List” editor.
In the “Data List” editor, all IN and OUT ports saved to the GDS of the controller are dis-
played. The IN and OUT ports of the newly instantiated program are displayed. To use the
IN/OUT ports of the imported library, you must assign the IN and OUT ports of the imported
libraries to the IN and OUT ports of other program instances so that consistent data ex-
change can take place.
Assigning an IN port to an • To assign an IN port to an OUT port, click on “Select IN Port here” in the “IN Port” col-
OUT port umn.

PLCNEXT TECHNOLOGY
The role picker opens. Only the IN ports that you can actually assign to the respective OUT
port are displayed in the role picker.
• Select the IN port that you want to assign to the relevant OUT port in the role picker.
• The IN port is assigned to the OUT port.
• Proceed as described for other IN ports.
Assigning several IN ports • Assign an IN port to an OUT port as described in the previous section.
to an OUT port • To assign further IN ports to an OUT port, you have to duplicate the OUT port.
• Right-click on the OUT port and select the “Duplicate Output Port” option in the context
menu.
Figure 9-7 Duplicating an output port
• To assign an IN port to the duplicated OUT port, proceed as described in the previous
section.
Assigning an OUT port to • To assign an OUT port to an IN port, click on “Select OUT Port here” in the “OUT Port”
an IN port column.
The role picker opens. Only the OUT ports that you can actually assign to the respective IN
port are displayed in the role picker.
• Select the OUT port that you want to assign to the relevant IN port in the role picker.
The OUT port is assigned to the IN port.
• Proceed as described for other OUT ports.

• Observe the instructions in Section 2.9.5 “Supported data types“.
Figure 9-8 “Data List” editor
Once you have assigned all IN and OUT ports to be used, transfer the PLCnext Engineer
project to the controller. Additional information on PLCnext Engineer is available in the on-
line help, the quick start guide (PLCNEXT ENGINEER, Order No. 1046008) and the user
manual for the AXC F 2152 controller (Order no. 2404267).

PLCNEXT TECHNOLOGY

Appendix
A Appendix
A1 Available data types

Table A-1 Available data types
Bits C# IEC 61131 FDCML C++ OPC UA

1 BOOL BOOL Bit/BOOL Boolean Boolean
16 UInt16 WORD Bitstring16 uint16 UInt16
32 UInt32 DWORD Bitstring32 uint32 UInt32
64 UInt64 LWORD Bitstring64 uint64 UInt64
8 Byte BYTE Bitstring8 uint8 Byte
8 Byte BYTE BYTE uint8 Byte
32 Int32 DINT DINT int32 Int32
32 UInt32 DWORD DWORD uint32 UInt32
32 Single REAL Float32 float32 Float
64 Double LREAL Float64 float64 Double
16 Int16 INT INT int16 Int16
64 Int64 LDATE LDATE int64 *
64 Int64 LDATE_AND_- LDATE_AND_- int64 *
TIME TIME
64 Int64 LDT LDT int64 *
64 Int64 LINT LINT int64 Int64
64 Double LREAL LREAL float64 Double
64 Int64 LTIME LTIME int64 *
64 Int64 LTIME_OF_DAY LTIME_OF_DAY int64 *
64 Int64 LTOD LTOD int64 *
64 UInt64 LWORD LWORD uint64 UInt64
8 Byte BYTE Octetstring1 uint8 Byte
16 UInt16 WORD Octetstring2 uint16 UInt16
32 UInt32 DWORD Octetstring4 uint32 UInt32
64 UInt64 LWORD Octetstring8 uint64 UInt64
32 Single REAL REAL float32 Float
16 Int16 INT Signed16 int16 Int16
32 Int32 DINT Signed32 int32 Int32
64 Int64 LINT Signed64 int64 Int64
8 SByte SINT Signed8 int8 SByte
8 SByte SINT SINT int8 SByte
n*8 String STRING StringASCII StaticString *
32 Int32 TIME TIME int32 *

PLCNEXT TECHNOLOGY
Table A-1 Available data types

Bits C# IEC 61131 FDCML C++ OPC UA
32 UInt32 UDINT UDINT uint32 UInt32
16 UInt16 UINT UINT uint16 UInt16
64 UInt64 ULINT ULINT uint64 UInt64
16 UInt16 UINT Unsigned16 uint16 UInt16
32 UInt32 UDINT Unsigned32 uint32 UInt32
64 UInt64 ULINT Unsigned64 uint64 UInt64
8 Byte USINT Unsigned8 uint8 Byte
8 Byte USINT USINT uint8 Byte
16 UInt16 WORD WORD uint16 UInt16
* Not implemented

PLCnext Technology naming conventions
A2 PLCnext Technology naming conventions

When designating PLCnext Technology components, please observe the following con-
ventions. Correct functioning can only be ensured if you adhere to the following specifica-
tions.
A 2.1 GDS ports

A designation
– May not start with a number.
– Must consist of at least two characters.
– May not exceed 128 characters.
– May not contain spaces or tabulators.
– May not start or end with “.”.
– May contain “.” to separate port names from program instances.
– May start or end with “_”.
A 2.2 Library, components and program

A designation
– Has to start with a capital letter.
– May not contain “.”.
A 2.3 Program instances

A designation

PLCNEXT TECHNOLOGY
A 2.4 Component instances

A designation
A 2.5 Processes
A designation
– Has to be unique.
– May not contain “.”.
A 2.6 Tasks
A designation
A 2.7 Namespaces
A designation
– May not contain spaces.
– May not end with “++”.
– Should not contain “_”.

Explanation of terms
A3 Explanation of terms
ACF  Application Component Framework
Application Component The ACF is a central part of the PLCnext Technology system architecture. It enables com-
Framework ponent-based platform development as well as expandability and configurability of the en-
tire system.
 Section 5.5 “ACF (Application Component Framework)”
API  Application Programming Interface
Application Programming An API is an interface that enables the connection of programs to a software system.
Interface
ARP  Automation Runtime Platform
Automation Runtime Plat- In the PLCnext Technology firmware, ARP is used as the root name for namespaces.
form
CLI  Command Line Interface
See PLCnext CLICold re- When the controller is started, all variables are started with their initialization values. Exist-
start ing data is reset.
Component A component is a collection of functions. It may contain one or more programs as well as IN
and OUT ports.
Common classes Common classes are useful classes for operating system functions, e.g., threads, sockets,
chrono, etc. The PLCnext Technology common classes are provided via the
Phoenix Contact SDK.
Connector A connector connects an IN port to an OUT port. An OUT port can be connected to several
IN ports. One connector is used for each connection. A connector can execute additional
tasks such as byte swapping, type casts or bit masking.
Core components The core components form the core function of the PLCnext Technology. They are part of
the firmware and contain the following components:
– Service components (e.g., ESM, system manager, PLC manager, eCLR, etc.)
– System components (e.g., OPC UA server, WBM, etc.)
– I/O components (e.g., fieldbus manager)
– Middleware (e.g., GDS, RSC, common classes, etc.)
CRL Certificate Revocation List

List of certificates that are not trusted.
Data sink A data sink is the location where data is received and stored.
Debugging Localization and diagnostics of errors in programs. The debug mode provides different
functions that support the user during the function test of the program as well as during error
localization and diagnostics (e.g., setting of breakpoints).

PLCNEXT TECHNOLOGY
eCLR ProConOS embedded CLR is the open IEC 61131 control runtime system for different au-
tomation tasks.
ESM  Execution and Synchronization Manager
ESM task  Task
Execution and Synchroni- The Execution and Synchronization Manager is used for real-time task handling. It performs
zation Manager task handling, monitoring and chronological sequencing of programs from different pro-
gramming languages and enables program execution in a real-time context.
 Section 2.8 “ESM (Execution and Synchronization Manager)” on page 23
Function Extensions for An Function Extension for external processes is a component that is created by the user. It
external processes is not processed within the PLCnext Technology framework but directly under Linux.
Function Extensions for Function Extensions for internal processes are components created by the user. These
internal processes components do not run in the real-time context of the PLCnext Technology platform. They
extend the range of functions of the PLCnext Technology platform.
GDS  Global Data Space
GDS buffer A GDS buffer is a memory area used for buffering and transferring data between ESM tasks.
It serves as a data exchange area between IN and OUT ports.
Global Data Space The GDS is the central point for storing all the data that is exchanged between the pro-
grams. Data exchange is implemented via IN and OUT ports that the user can link. The GDS
enables communication relationships and data exchange between tasks and programs that
were created in different programming languages. The GDS also ensures that each task al-
ways uses consistent values.
 Section 2.9 “GDS (Global Data Space)” on page 29
Hot restart All variable values are retained when the controller is started.
IdentityStore The IdentityStore is an identity memory for PLCnext Technology devices. It contains au-
thentication tools, e.g., key pairs, certificates, etc.
IN port  Port
Middleware  Core components
Notification Notifications are messages that can be sent and received by components to point out spe-
cial events. They are identified via a name and can transport user data.
Notification manager The notification manager enables components to send and receive  notifications. It ac-
cepts messages from a sender and forwards them to the registered recipient.
NTP Network Time Protocol

NTP is a protocol for time synchronization in IT systems.
OPC UA server Open Platform Communications Unified Architecture

OPC UA is a standardized protocol for industrial machine-to-machine communication. Ex-
change of process data, variable values, read and write access to file systems, etc. between
OPC UA server and clients is implemented via the protocol.

OUT port  Port
Payload  User data
PC Worx Engineer Engineering software platform for Phoenix Contact automation controllers. PC Worx Engi-
neer complies with IEC 61131-3 and its functions can be expanded using add-ins. The soft-
ware was called PC Worx Engineer up to version 7.2.3. As of version 2019.0 LTS, the soft-
ware is called PLCnext Engineer.
PLC manager The PLC manager is part of the PLCnext Technology firmware. It manages the real-time
programs of the PLC and starts and stops them.
PLCnext CLI  PLCnext Command Line Interface

The PLCnCLI is a command-line interface. It can be used for generating metafiles, C++
header files, for adding IN and OUT ports and generating PLCnext Engineer libraries, for ex-
ample.
PLCnext Community Information platform for PLCnext Technology users with a connected forum for direct con-
tact with PLCnext Technology experts.
See plcnext-community.net.
PLCnext Engineer Engineering software platform for Phoenix Contact automation controllers.
PLCnext Engineer is IEC 61131-3-compliant and its functions can be extended using add-
ins.
PLCnext Store The PLCnext Store is a trade platform for the sale of apps for PLCnext controllers
(PLCnext Engineer libraries, programs, solution apps, etc.).
PLCnext Technology PLCnext Technology is the basis of the new, open control platform from Phoenix Contact.
This new technology enables users to work with various well-established software tools at
the same time, including Visual Studio®, Eclipse®, Matlab® Simulink®, and
PLCnext Engineer. In addition, it facilitates writing of program code in IEC 61131-3 as well
as in C++ or C#. Additional functions from third-party manufacturers or the open-source
community can be added to the Phoenix Contact automation system, merging into one
complete system.
PLM  Program Library Manager
POU Program Organization Unit (POU)

Collective term for the terms “function”, “function block”, and “program” defined in
IEC 61131-3. They are used for modularizing and structuring the PLC program.
Program Library Manager The PLM is part of the PLC manager. The PLM manages components providing user pro-
grams.
PROFICLOUD PROFICLOUD is the cloud solution from Phoenix Contact. Locally or globally distributed
network devices and even the functions of an industrial PROFINET network can simply and
securely be moved to the cloud with PROFICLOUD. Performance data can be accessed
rapidly from sites anywhere in the world.
Port Data between programs is exchanged via the IN and OUT ports. To establish a communi-
cation relationship between the programs, IN and OUT ports have to be connected via con-
nectors.

PLCNEXT TECHNOLOGY
Real-time user program PLC program that can be programmed in IEC 61131-3, C++, or Matlab® Simulink®.
Regular expressions Regex: Character string for describing quantities of character strings using syntactic rules.
Resource-global variables According to IEC 61131-3, resource-global variables can be used in all Program Organiza-
tion Units (POU) of the current resource.
Remote service call Remote service calls are services for the communication between processes and between
devices. They provide the API to enable access to all core components of the
PLCnext Technology firmware.
RSC  Remote service call
SDK  Software Development Kit
Service components  Core components
Service manager The service manager is used to request registered RSC services (components of the SDK)
and integrate them into the process.
SFTP Secure File Transfer Protocol
Shared object A shared object file (*.so) corresponds to a dynamic library (also called shared libraries). It
is downloaded from the firmware to the memory during runtime. Then, the functions in-
cluded can be called. In PLCnext Technology, a shared object file contains the code for the
components and programs to be executed and which where created in C++ or
Matlab® Simulink®.
Software Development Kit The Phoenix Contact SDK contains important toolchains and libraries required for creating
programs.
PLC Programmable logic controller
SSH Secure shell
System components  Core components
System manager The system manager loads and configures the system components and monitors the sta-
bility of the system.
Task A task is a configuration unit for the execution of program instances (e.g., cyclic execution
at fixed intervals).
The following task types are available:
– Cyclic task
– Idle task
– System event task
Task output data At the end of its execution, a task makes its calculated output data available to other tasks
via a buffer. The task output data is the sum of all OUT port variables that are connected to
buffers of I/O systems or to IN ports of program instances in other tasks.

Task input data When being started, a task actively consumes data from the task output buffers of other
tasks, or from the buffers of I/O systems. All user programs within a task therefore use the
same input data during the entire task runtime. The consistent input data image is only up-
dated with the next start of the task.
TSD Time-Series Data
User data User data (payload) is information data in data packets. It does not contain control or proto-
col information.
User manager The user manager manages the different users. Each user has a name and a password.
One or several user roles are assigned to each user.
User program The user creates the user programs in IEC 61131-3, C++, or with Matlab® Simulink®. They
are processed in real-time context via the ESM. Through integration into the ESM, a
user program becomes real-time-capable. Connection to the data exchange area of the
GDS is implemented via IN and OUT ports.
VPN Virtual Private Network
Warm restart All variable values marked with “Retain” in PLCnext Engineer are retained when the control-
ler is started.
WBM  Web-based management
Web-based management You can call web-based management via the web browser of your PC. WBM is used to re-
ceive information about the controller and to configure it (e.g., managing access data and
user roles).

PLCNEXT TECHNOLOGY
A4 PROFINET diagnostic code in WBM

The “PROFINET” page in the WBM “Diagnostics” area of your controller is used to view in-
formation about the controller and the connected PROFINET devices, as well as informa-
tion about their Axioline F local bus devices. The displayed diagnostic code consists of sev-
eral bits that are evaluated individually. The diagnostic state (OK, warning, error) as well as
the corresponding diagnostic text are based on an evaluation of the diagnostic bits. The fol-
lowing section is an excerpt from the “AutomationRuntimePlatform/Source/Arp/Io/Profinet-
Stack/Controller/Services/DiagnosticInfo.hpp” firmware file. It contains the bit description of
the diagnostic code:
/// <summary>
/// Special status of this AR, bitwise coded.
/// - Bit 0: set if not connected
/// - Bit 1: set if data invalid
/// - Bit 2: set if diagnosis is available
/// - Bit 3: set if module difference is available in case of configuration difference
/// - Bit 4: set if AR is deactivated
/// - Bit 5: set if neighborhood information is not available
/// - Bit 6: neighborhood information not unique
/// - Bit 7 - Identify.cnf on alias received, but name of the device is already configured in
another AR
/// - Bit 8: Maintenance Required Information is available
/// - Bit 9: Maintenance Demanded Information is available
/// - Bit 10: Channel or Manufacturer Specific Diagnosis Information are available
/// - Bit 11..15: reserved (shall be 0)
/// </summary>

Please observe the following notes
General terms and conditions of use for technical documentation
Phoenix Contact reserves the right to alter, correct, and/or improve the technical
documentation and the products described in the technical documentation at its own
discretion and without giving prior notice, insofar as this is reasonable for the user. The
same applies to any technical changes that serve the purpose of technical progress.
The receipt of technical documentation (in particular user documentation) does not
constitute any further duty on the part of Phoenix Contact to furnish information on
modifications to products and/or technical documentation. You are responsible to verify the
suitability and intended use of the products in your specific application, in particular with
regard to observing the applicable standards and regulations. All information made
available in the technical data is supplied without any accompanying guarantee, whether
expressly mentioned, implied or tacitly assumed.
In general, the provisions of the current standard Terms and Conditions of Phoenix Contact
apply exclusively, in particular as concerns any warranty liability.
This manual, including all illustrations contained herein, is copyright protected. Any
changes to the contents or the publication of extracts of this document is prohibited.
Phoenix Contact reserves the right to register its own intellectual property rights for the
product identifications of Phoenix Contact products that are used here. Registration of such
intellectual property rights by third parties is prohibited.
Other product identifications may be afforded legal protection, even where they may not be
indicated as such.
PHOENIX CONTACT 245 / 246

246
How to contact us
Internet Up-to-date information on Phoenix Contact products and our Terms and Conditions can be
found on the Internet at:
phoenixcontact.com
Make sure you always use the latest documentation.
It can be downloaded at:
phoenixcontact.net/products
Subsidiaries If there are any problems that cannot be solved using the documentation, please contact
your Phoenix Contact subsidiary.
Subsidiary contact information is available at phoenixcontact.com.
Published by PHOENIX CONTACT GmbH & Co. KG

Flachsmarktstraße 8
32825 Blomberg
GERMANY
PHOENIX CONTACT Development and Manufacturing, Inc.
586 Fulling Mill Road
Middletown, PA 17057
USA
Should you have any suggestions or recommendations for improvement of the contents and
layout of our manuals, please send your comments to:
[email protected]
246 / 246 PHOENIX CONTACT GmbH & Co. KG • Flachsmarktstraße 8 • 32825 Blomberg • Germany
phoenixcontact.com
© PHOENIX CONTACT 2019-12-04
PHOENIX CONTACT GmbH & Co. KG

Flachsmarktstraße 8
32825 Blomberg, Germany
Phone: +49 5235 3-00
Order No. —00
109324_en_00
Fax: +49 5235 3-41200

E-mail: [email protected]
phoenixcontact.com

PLC Next

Uploaded by

Copyright:

Available Formats

PLC Next

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

PLC Next

Uploaded by

Copyright:

Available Formats

PLCnext Technology

UM EN PLCNEXT TECHNOLOGY 2020.0 LTS, Revision 00 2019-12-04

This user manual is valid for:

Designation Order No.

PHOENIX CONTACT GmbH & Co. KG • Flachsmarktstraße 8 • 32825 Blomberg • Germany

2 Structure of the PLCnext Technology ......................................................................................14

109324_en_00 PHOENIX CONTACT 3 / 246

2.11.7 Device Integration (DI) namespace ......................................................50

3 Web-based management (WBM) ............................................................................................91

4 / 246 PHOENIX CONTACT 109324_en_00

3.7 “Diagnostics” area ...............................................................................................97

4 Transferring variable values to the PROFICLOUD .................................................................147

5 Structure of a C++ program ...................................................................................................155

109324_en_00 PHOENIX CONTACT 5 / 246

5.6.5 “Net” ...................................................................................................168

6 Creating programs with C++ ..................................................................................................194

7 Creating function blocks and functions with C# ......................................................................210

6 / 246 PHOENIX CONTACT 109324_en_00

8 Matlab® Simulink® ...............................................................................................................227

9 Importing libraries into PLCnext Engineer ..............................................................................228

109324_en_00 PHOENIX CONTACT 7 / 246

1.1 Identification of warning notes

Here you will find additional information or detailed sources of information.

1.2 Qualification of users

8 / 246 PHOENIX CONTACT 109324_en_00

109324_en_00 PHOENIX CONTACT 9 / 246

Creating programs with C++

Creating function blocks and functions with C#

1.4 Information about this document

1.5 Trademarks/licensing information

10 / 246 PHOENIX CONTACT 109324_en_00

Licensing information on open source software

1.6 Safety notes

NOTE: Risk of unauthorized network access

109324_en_00 PHOENIX CONTACT 11 / 246

NOTE: Risk of unauthorized access to devices

12 / 246 PHOENIX CONTACT 109324_en_00

1.7 PLCnext Technology product range

Modifications to hardware and firmware of the devices are not permitted.

Currently, the following products are available with PLCnext Technology:

Description Type Order No.

109324_en_00 PHOENIX CONTACT 13 / 246

2 Structure of the PLCnext Technology

2.1 Core components

Figure 2-1 Core components of the PLCnext Technology firmware

14 / 246 PHOENIX CONTACT 109324_en_00

– INTERBUS (with AXC F 2152plus AXC F IL Adapt or AXC F XT IB)

109324_en_00 PHOENIX CONTACT 15 / 246

Figure 2-2 Task handling with ESM and GDS

2.2 Function extensions for internal processes

16 / 246 PHOENIX CONTACT 109324_en_00

Figure 2-3 PLCnext Technology - function extensions for internal processes

2.3 Function extensions for external processes

Figure 2-4 PLCnext Technology - function extensions for external processes

109324_en_00 PHOENIX CONTACT 17 / 246

2.4 System manager

2.5 PLC manager

2.6 Managing of components

18 / 246 PHOENIX CONTACT 109324_en_00