zenon manual

Installation and updates -

zenon Software Platform
v.15
© 2025 Ing. Punzenberger COPA-DATA GmbH

All rights reserved.

Distribution and/or reproduction of this document or parts thereof in any form are permitted solely
with the written permission of the company COPA-DATA. Technical data is only used for product
description and are not guaranteed properties in the legal sense. Subject to change, technical or
otherwise.
Table of contents

1 Welcome to COPA-DATA help ............................................................................................................... 7

2 Installation zenon Software Platform ................................................................................................... 8

3 System requirements ................................................................................................................................ 9

3.1 Operating systems............................................................................................................................................9
3.1.1 Windows Operating Systems (1/2) ................................................................................................................ 10
3.1.2 Windows Operating Systems (2/2) ................................................................................................................ 12
3.1.3 Linux ........................................................................................................................................................................... 14
3.1.4 Linux-based container (Docker) ...................................................................................................................... 15
3.1.5 Windows-based Docker ..................................................................................................................................... 15
3.2 System requirements when using DirectX ........................................................................................... 15
3.3 User authorization ......................................................................................................................................... 16
3.4 Hardware requirements............................................................................................................................... 17
3.4.1 Engineering Studio ............................................................................................................................................... 18
3.4.2 Service Engine ........................................................................................................................................................ 20
3.4.3 Report Engine ......................................................................................................................................................... 22
3.4.4 Smart Server ............................................................................................................................................................ 24
3.4.5 Smart Client ............................................................................................................................................................. 24

4 Platform setup .......................................................................................................................................... 25

4.1 zenon Software Platform standard installation .................................................................................. 25
4.1.1 Start window ........................................................................................................................................................... 26
4.1.2 Component selection .......................................................................................................................................... 27
4.1.3 Further details of components ........................................................................................................................ 31
4.1.4 Configuration and installation ......................................................................................................................... 33
4.1.5 Installation and finishing .................................................................................................................................... 39
4.1.6 Backup and Restore - Persistence Instance ................................................................................................ 41
4.2 Installing additional components ............................................................................................................ 41
4.3 Uninstalling components ............................................................................................................................ 42
4.4 Silent installation and uninstallation ...................................................................................................... 43
4.4.1 Silent installation with CLI app ........................................................................................................................ 44
4.5 Error treatment ............................................................................................................................................... 47
4.6 Windows Updates.......................................................................................................................................... 48
4.7 Virus scan .......................................................................................................................................................... 49
4.8 File Structure.................................................................................................................................................... 49
 4.9 Install older version, if zenon 15 is already installed (64-bit operating system).................... 51
4.10 Free ports .......................................................................................................................................................... 51
4.11 Licensing preview versions ......................................................................................................................... 53

5 Version change and build updates ...................................................................................................... 53

5.1 Build update IIoT Services .......................................................................................................................... 56
5.2 Compatibility ................................................................................................................................................... 57

6 Software and paths for installation and operation ......................................................................... 60

7 Installation of Service Engine ................................................................................................................ 64

7.1 Installation ........................................................................................................................................................ 65
7.2 System requirements and operating systems..................................................................................... 65
7.2.1 System requirements when using DirectX .................................................................................................. 65
7.2.2 File Structure ........................................................................................................................................................... 66
7.2.3 Free ports ................................................................................................................................................................. 68
7.2.4 Exceptions for anti-virus ..................................................................................................................................... 70
7.2.5 Firewall setup .......................................................................................................................................................... 70
7.3 Hardware requirements............................................................................................................................... 73
7.3.1 Paths for setup and operation ......................................................................................................................... 75
7.3.2 Demo licenses and Demo mode ..................................................................................................................... 76
7.3.3 Service Engine under Windows Embedded Standard ............................................................................ 78
7.4 How do you establish whether the Service Engine computer has reached its limits? ........ 78
7.5 Uninstall Service Engine .............................................................................................................................. 79

8 Report Engine ........................................................................................................................................... 80

8.1 Installation and updates .............................................................................................................................. 80
8.1.1 Start window ........................................................................................................................................................... 82
8.1.2 Component selection .......................................................................................................................................... 84
8.1.3 Selection and installation ................................................................................................................................... 88
8.1.4 Updates ..................................................................................................................................................................... 88
8.1.5 Upgrade information ........................................................................................................................................... 89

9 IIoT Services ............................................................................................................................................... 89

9.1 Installation ........................................................................................................................................................ 90
9.1.1 Installation: Standalone vs. parallel vs. virtual machine ......................................................................... 93
9.1.2 Steps after installing Windows ........................................................................................................................ 95
9.1.3 Kubernetes ............................................................................................................................................................... 95
9.1.4 Update paths .......................................................................................................................................................... 96
9.1.5 Compatibility........................................................................................................................................................... 96
9.2 Getting Started .............................................................................................................................................104
 9.2.1 Getting Started Guide (Windows) ............................................................................................................... 104
9.2.2 Getting Started Guide (Docker) .................................................................................................................... 123

10 Smart Server & Smart Client................................................................................................................ 146

11 Web Visualization Service .................................................................................................................... 146

12 HTML Web Engine ................................................................................................................................. 146

13 Service Engine for Docker- installation and operation ................................................................ 147

13.1 General.............................................................................................................................................................147
13.2 System requirements..................................................................................................................................147
13.3 Configuration & Operation ......................................................................................................................147
13.4 Logging of Service Engine in container environment ....................................................................149
13.5 docker-compose.yml ..................................................................................................................................149
13.5.1 Hardware connectors & ports ...................................................................................................................... 150
13.6 .env file .............................................................................................................................................................151
13.7 IOT2050 ...........................................................................................................................................................155

14 Service Engine for Linux - installation and putting into operation........................................... 155
14.1 Installation on the Linux computer .......................................................................................................156
14.1.1 Setting up the APT repository ....................................................................................................................... 156
14.1.2 Installation of the Service Engine package .............................................................................................. 157
14.1.3 Access rights ........................................................................................................................................................ 158
14.1.4 Licensing ................................................................................................................................................................ 161
14.1.5 Checking the state of the installation and licensing ............................................................................ 162
14.2 Installation of Linux components of the zenon Software Platform - Summary ...................162
14.3 .NET installation on Linux .........................................................................................................................163
14.3.1 Set up APT repository for .NET ..................................................................................................................... 163
14.3.2 Installation of .NET 8 ......................................................................................................................................... 164
14.3.3 Check for previously-installed .NET versions .......................................................................................... 165
14.3.4 .NET environment variable ............................................................................................................................. 165
14.3.5 Uninstallation ....................................................................................................................................................... 166
14.4 Commissioning of a zenon project on Linux computers ..............................................................166
14.4.1 Manual installation ............................................................................................................................................ 166
14.4.2 Installation via Device Management .......................................................................................................... 167
14.5 Starting Service Engine ..............................................................................................................................171
14.6 Uninstallation ................................................................................................................................................172

15 FAQ ............................................................................................................................................................ 172

16 Technical support ................................................................................................................................... 173
Welcome to COPA-DATA help

1 Welcome to COPA-DATA help

GENERAL HELP
If you cannot find any information you require in this help chapter or can think of anything that you
would like added, please send an email to [email protected].

LICENSES AND SERVICES

If you find that you need other zenon services or licenses, our staff will be happy to help you. Email
[email protected].

PROJECT SUPPORT
You can receive support for any real project you may have from our customer service team, which
you can contact via email at [email protected].

SUPPORT & SERVICES

Hungry for more information? Want to get your zenon questions answered fast and easy or trouble
shoot yourself?

Visit our new Self Service Portal (https://selfservice.copadata.com/) to access hundreds of checklists
and FAQs created by zenon experts. Access thousands of technical posts and get involved in
our zenon community forum. Search all bugfixes and product changes to keep track of what has
changed.

ZENON ACADEMY
If you want to learn about zenon, this is the right place. Easily increase your zenon knowledge, book
online or face-to-face courses (https://www.zenon-academy.com/) and receive your zenon
Certificates.

ZENON VIDEO TUTORIALS

You can find practical examples for project configuration with zenon in our YouTube channel
(https://www.copadata.com/tutorial_menu). The tutorials are grouped according to topics and give an
initial insight into working with different zenon services. All tutorials are available in English.

7 | 173
Installation zenon Software Platform

2 Installation zenon Software Platform

During the first installation of zenon, the installation routine automatically starts and leads you
through the entire installation process. If the autoplay of media is disabled in the operating system of
the computer, the installation routine will not start automatically. Start the installation by executing the
START.exe file in the root folder of your zenon installation medium.

Hint
The autoplay of media can be enabled in the settings of your
operating system.
 Press the Windows key + I to open the Windows settings
dialog.
 Enter Turn AutoPlay on or off in the input field.
This opens the system configuration dialog.
 Select the Use AutoPlay for all media and devices option.

Notes for the installation:

 Before installing zenon:
 All current operating system updates must be installed
Note: If you always use the latest version (Service Pack) of your operating system, you
not only avoid compatibility issues but also security problems.
 There must not be a restart pending
 During the installation of zenon, the COPA-DATA Multiple Network Protocol Driver
(cdprotdrv.sys) is installed. To start the driver, the operating system must be restarted after
installation.

Attention
As of version 7.10, zenon cannot be installed on systems that already have the
Microsoft SQL Server Data Engine (MSDE) installed. This affects all systems on
which zenon version 6.01 or 6.20 have been installed.

8 | 173
System requirements

Information
If you receive an error message during installation stating that a service cannot
be started, then:
 First reboot the computer
 Then start the zenon setup again

3 System requirements
Changes due to Service Packs, Hotfixes or Patches from Microsoft can cause incompatibilities and
affect the functionality of the software. In this case, COPA-DATA will provide an updated version of
zenon as soon as possible. In this case you can get more information from COPA-DATA support:
[email protected].

Attention
Note when configuring the project:
 For the optimal display ofzenon in the Service Engine, the standard setting
(corresponds to 100%) is recommended for the Windows display. Higher
values can lead to graphic elements, symbols, texts, etc. not being
displayed correctly.
 Windows themes can overlay elements in Service Engine. Ensure, when
configuring a project, that there is an appropriate distance from the
elements to the screen edge.

Note: Host names can be up to 128 characters long.

3.1 Operating systems

In this node, you will find information about different operating systems supported by the zenon
Software Platform version 15.

9 | 173
3.1.1 Windows Operating Systems (1/2)
Supported operating systems and minimum required Windows Service Pack/version:
Operating system Engineering Studio Service Engine Logic Service Report Engine

Windows 10 Only x64 from version 21H2 From version 21H2 From version 21H2 Only x64 from version 21H2
(Pro, Enterprise)

Windows 10 Only x64 from version 2021 From version 2021 From version 2021 Only x64 from version 2021
(IoT) Enterprise LTSC

Windows 11 Only x64 from version 21H2 From version 21H2 From version 21H2 Only x64 from version 21H2
(Pro, Enterprise)

Windows 11 Only x64 from version 2024 From version 2024 From version 2024 Only x64 from version 2024
(IoT) Enterprise LTSC

Windows Server 2019 Only x64 from version 2019 From version 2019 From version 2019 Only x64 from version 2019
(All editions with the exception of Core)

Windows Server 2022 Only x64 from version 2022 From version 2022 From version 2022 Only x64 from version 2022
(All editions with the exception of Core)

Windows Server 2025 Only x64 from version 2025 From version 2025 From version 2025 Only x64 from version 2025
(All editions, with the exception of Core)
 Attention
Only Intel processor architecture is supported for the operation of zenon on
Windows operating systems.

LTSC VERSIONS

An overview of LTSC versions and their Equivalent GA Channel releases can be found on the Microsoft Homepage
(https://learn.microsoft.com/en-us/windows/whats-new/ltsc/).
3.1.2 Windows Operating Systems (2/2)
Supported operating systems and minimum required Windows Service Pack/version:
Operating system Smart Server Smart Client HTML Web Engine IIoT Services
Web Visualization Service

Windows 10 From version 21H2 From version 21H2 From version 21H2 From version 21H2
(Pro, Enterprise)

Windows 10 From version 2021 From version 2021 From version 2021 From version 2021
(IoT) Enterprise LTSC

Windows 11 From version 21H2 From version 21H2 From version 21H2 From version 21H2
(Pro, Enterprise)

Windows 11 From version 2024 From version 2024 From version 2024 From version 2024
(IoT) Enterprise LTSC

Windows Server 2019 From version 2019 From version 2019 From version 2019 From version 2019
(All editions with the exception of Core)

Windows Server 2022 From version 2022 From version 2022 From version 2022 From version 2022
(All editions with the exception of Core)

Windows Server 2025 From version 2025 From version 2025 From version 2025 From version 2025
(All editions, with the exception of Core)
 Attention
Only Intel processor architecture is supported for the operation of zenon on
Windows operating systems.
3.1.3 Linux
Supported operating systems and zenon services for native Linux:
Hardware Operating system Service Engine for Linux Logic Service

PC Ubuntu 24.04, amd64 X X

Debian 11, arm64 X X

Raspberry Pi 4 Raspberry Pi OS 11, arm64 X X

Siemens IoT2050 Siemens Industrial OS 3.2.3, arm64 X X

Key:
X: supported

--: not supported

REQUIREMENTS

To be able to run Service Engine in a Linux environment, the following applies:

 zenon projects can only be run for the operating systems listed in the table.
 For Service Engine, a 64-bit operating system is required.
System requirements

3.1.4 Linux-based container (Docker)

Supported zenon apps for amd64 and arm64 Docker containers:
 Service Engine for Linux
 zenon Diagnosis Server for Linux
 HTML Web Engine

 IIoT Services:
 Data Hub
 Data Storage
 Certificate Management
 Identity Service
 Identity Management
 Platform Configuration
 IIoT API
 Persistence Service
 Service Configuration Studio
 Device Management
 Proxy Service

Information
Service Engine is tested by COPA-DATA in a Docker environment. Service Engine
can also be used on other container environments, e.g. kubernetes.

3.1.5 Windows-based Docker

Windows Docker Container supports the Service Engine.

3.2 System requirements when using DirectX

The following minimum requirements must be met when using DirectX hardware or DirectX software:

Note: For extensive projects or several projects loaded at the same time you will need accordingly
faster/stronger hardware. The minimum requirements can increase as a result of this.

15 | 173
System requirements

Parameter Minimum requirements Recommended

CPU: Single core with SSE2 support. Quad Core or more cores

Graphics adapter: DirectX 11 mainstream graphics Dedicated DirectX 11 AMD or

card. nVidia high-end graphics card
(DirectX hardware
only) Note: When an integrated
graphics chip is used in particular,
it is possible, depending on the
driver used, that there are
impairments to the display quality
and considerable performance
impairments.

Graphics memory: At least 1 GB VRAM 2 GB VRAM or more

(DirectX hardware Note: The size that is actually

only) needed depends on the number
of screens called up and the
elements displayed.

Graphics card driver: The graphics card manufacturer's most recent driver.

(DirectX hardware
only)

Operating system: DirectX Hardware and DirectX Software only work on operating systems
with DirectX 11.1 support.
If the system does not support DirectX 11.1, it is automatically switched
to Windows based .

The current DirectX-Service Engine must be installed. For zenon it is

installed together with the setup. It must be manually installed for Smart
Client.

You can check the DirectX hardware compatibility of the graphics card and the driver with the
dxdiag.exe of the Windows operating system.
As of Windows 8: All supported versions of DirectX are displayed in the Display tab under Feature
Levels. For example, DirectX 11 is displayed as 11.0.

3.3 User authorization

Windows administrator rights are required for installation.

Standard Windows user rights are required for ongoing operation. The user account control (UAC)
can be activated at the highest security level.

16 | 173
System requirements

Attention
Keep in mind that Windows user rights settings are not overridden by internal
security software.

3.4 Hardware requirements

In this node, you can find the hardware requirements for the individual versions of Engineering Studio
and Service Engine, Report Engine, as well as Smart Server and Smart Client. This information
represents the requirements for a system with average complexity and project size. When a zenon
service has additional restrictions, this is documented accordingly in the relevant node of the Help.

Supported processor architectures are listed in the chapters on the respective operating systems (on
page 9).

For your planning, also take into account consumption of zenon independent system resources such
as the size of the storage medium, main memory, CPU performance, etc.

Attention
Graphics cards with at least 1 GB of VRAM and DirectX support are required.
Shared-memory graphics cards may require too much working memory and may
thus lead to considerable performance impairments. Note the System requirements
when using DirectX (on page 15) node. The recommended configuration from this
node is to be noted for the use of Multi-Touch.

ENGINEERING

Engineering Studio uses a Microsoft SQL Server as an SQL Server and has higher hardware
requirements than Service Engine. If Engineering Studio and Service Engine are to be running on a
system simultaneously, the requirements increase.

Information
In Service Engine, an automatic check is carried out to determine whether the
computer has sufficient hardware and operating system resources for the current
process.

For further information, see the Service Engine node in the System integrity
monitoring node.

17 | 173
System requirements

PERFORMANCE OPTIMIZATION

Note that all information stated only constitutes the minimum requirements for your system. Better
hardware equipment improves the performance of zenon considerably.
 Equip your hardware - both clients and most of all the server - with sufficient memory (RAM).
 Optimize the hardware for data backup, for example with fast SSD data storage.
 Match the hardware of the clients and the network to one another. A system is only as
powerful as its weakest component.
 Optimize your network architecture, for example with the use of cabling with a high data
transfer rate and corresponding devices (switches and routers).
 When using a virtual environment, ensure that the virtual system is correspondingly
configured with performance optimization.

3.4.1 Engineering Studio

The minimum requirements are based on a complete installation of Engineering Studio. For extensive
projects or several projects loaded at the same time you will need accordingly faster/stronger
hardware. The minimum requirements can increase as a result of this.
Hardware Minimum requirements Recommended

CPU Single core with SSE2 support. Quad Core

Memory At least 4 GB More than 8 GB

Note: The memory requirements depend on

the number of projects and the configuration
scope within a project. The more projects you
have simultaneously available in memory, the
more memory you need.

Storage medium 40GB of free memory is required to install the

entire zenon Software Platform.

The following applies for individual

installations:
 Engineering Studio: 10 GB
 Service Engine: 6 GB
 Report Engine: 7 GB
 Reporting Studio: 4 GB

18 | 173
System requirements

Hardware Minimum requirements Recommended

 Smart Server: 2 GB

 Smart Client: 3 GB

 IIoT Services: 10 GB
 License Management: 1 GB

In addition, free memory is required for

projects.

Monitor resolution Full HD or higher Dual-monitor system:

Each with full HD
Attention: You can set your screen resolution or higher
resolution to lower resolutions if your monitor
supports it. Note, however, that with a lower
resolution not all dialogs and information will
be visualized in full. Some dialogs, e.g. the
filter of the AML/CEL image, are difficult to
operate or possibly non-operable at a height
of less than 850 pixels.

Graphics adapter Dedicated graphics card with at least 1 GB of High-end graphics card
VRAM.

Operation with an on-board graphics card is

possible, but only with considerable
performance impairments.

Cards with shared memory lead to

considerable performance impairments and
should not be used. Note the System
requirements when using DirectX (on page 15)
node.

Input devices Standard keyboard or standard mouse.

USB interface or For the installation, regardless of installation

DVD drive medium.

The installation is also possible via network.

Installation files can also be downloaded from
the customer area of the COPA-DATA
website.

Parallel or USB In case of dongle licensing required for

interface dongle. For network dongle only required for
the dongle server.

19 | 173
System requirements

Hardware Minimum requirements Recommended

Network 10 Mbit/s with TCP/IP protocol for Remote 1000 Mbit/s

connection Transport, network dongle, project backups
(optional) on central file server, multi-user capable
Engineering Studio, etc.

Note: When using comprehensive multi-user projects, note the information in the hardware
requirements node.

3.4.2 Service Engine

Minimum requirements refer to a complete installation of the Service Engine.

For extensive projects or several projects loaded at the same time you will need accordingly
faster/stronger hardware. The minimum requirements can increase as a result of this.
Hardware Minimum requirements Recommended

CPU Single core with SSE2 support. Quad Core

Memory at least 4 GB More than 8 GB

Note: Projects with large amounts of data,

network projects, several parallel projects and
projects in redundant operation require more
memory.

Storage medium 40GB of free memory is required to install the

entire zenon Software Platform.

The following applies for individual

installations:
 Engineering Studio: 10 GB
 Service Engine: 6 GB
 Report Engine: 7 GB
 Reporting Studio: 4 GB
 Smart Server: 2 GB

 Smart Client: 3 GB

 IIoT Services: 10 GB
 License Management: 1 GB

In addition, free memory is required for

projects.

20 | 173
System requirements

Hardware Minimum requirements Recommended

Attention: If you log historical data (e.g.

archived data or alarm/CEL data), there will
need to be sufficient memory available or the
configuration has to ensure that the historical
data is evacuated or deleted.

Monitor resolution Full HD or higher

Attention: You can set your screen

resolution to lower resolutions if your monitor
supports it. Note, however, that with a lower
resolution not all dialogs and information will
be visualized in full. Some dialogs, e.g. the
filter of the AML/CEL image, are difficult to
operate or possibly non-operable at a height
of less than 850 pixels.

Graphics adapter Dedicated graphics card with at least 1 GB of High-end graphics

VRAM. card

Operation with an on-board graphics card is

possible, but only with considerable
performance impairments.

Cards with shared memory lead to

considerable performance impairments and
should not be used. Note the System
requirements when using DirectX (on page 15)
node.

Input devices Keyboard and/or mouse. Operation via

touchscreen is also possible. There are many
individual, customizable touch keyboards
available for the touchscreen. In addition,
there is the possibility of Multi-Touch
operation.

USB interface  For installation.

Installation also possible via network or
(optional) other storage media.
 For dongle. Network dongle also
available.

Network 64 kBits/s for standard Client/Server projects. 1000 Mbits/s full

connection duplex for standard

21 | 173
System requirements

Hardware Minimum requirements Recommended

(optional) Client/Server projects.
100 Mbit/s full duplex for redundant
operation.

Remote Minimum requirements: Dial-up modem with 1 Mbit/s full duplex.

connection 9600 Bit/s.
(optional)

WAN connection Any desired conncetion via router, e.g. per

(optional) ISDN or DSL. Data transfer is slower in a WAN
than in a local network for technical reasons.
Be sure to check the possible data transfer
rates of your WAN technology already at the
time when you create the project.

Message Control Please refer to the Message Control node for

(optional) the requirements.

Interfaces The necessary interfaces depend on the

(optional) requirements of the PLC and/or the bus
connection, for example serial RS-232 or
RS422/485 interfaces, ISA/PCI slots, etc.

3.4.3 Report Engine

The following prerequisites are applicable for work with Report Engine:

HARDWARE
Report Engine Server:
Parameter Recommended Minimum

CPU CPU XEON CPU i7

(maximum 24 cores/4 sockets)

RAM 64GB or larger 32 GB

Free memory 1TB or more 1 TB

(depending on the data to be
saved)

Engineering computer:

22 | 173
System requirements

Parameter Recommended Minimum

CPU CPU i7 or more powerful CPU i7

RAM 64GB or larger 32 GB

Free memory 1TB or more 2 GB

(depending on the data to be
saved)

Monitor (pixels) Full HD or higher 1024 x 768

CONNECTORS
The following is applicable for the Service Engine Connector:
 Timeout: is independent of the report timeout.
Default: 5 minutes (can be configured)
 Variables: Only variables that are listed in metadata are requested
 String variable: maximum of 4000 characters

The performance of a Connector depends on the:

 Performance of the Report Engine server
 Performance of the Service Engine server
 Service Engine server load (connector runs with lower priority)
 Network performance and network load

PROJECTS AND FILTERS

Reports can generally be created throughout several projects.

Attention
Archive data can only be evaluated if the variables and archive configuration are
in the same project.

This means: For example, in an integration project, if a variable from a

subproject is archived in an archive, then Report Engine cannot access this
variable.

SCHEDULES
 Calendar days in months are limited to 1 - 28 (corresponds to February in non-leap years)
 The "Month end" event is not available

23 | 173
System requirements

Information
Do not use zenon color palettes for dynamic limit values for zenon projects
whose data is to be exported for Report Engine. Limit values cannot be
dynamically changed in Report Engine. Information from color palettes can
therefore not be evaluated. This can lead to illegible graphics.

3.4.4 Smart Server

The minimum requirements are based on a complete installation of Smart Servers. For extensive
projects or several projects loaded at the same time you will need accordingly faster/stronger
hardware. The minimum requirements can increase as a result of this.
Hardware Minimum requirements Recommended

CPU Single core with SSE2 support. Quad Core

Memory At least 4 GB More than 8 GB

Storage medium At least 2 GB of free hard drive space. More than 2 GB

of free memory
space.

Network 10 Mbit/s full duplex. 1000 Mbit/s full

connection duplex.

Remote Minimum requirements: Dial-up modem with 9600 1 Mbit/s full

connection Bit/s. duplex.
(optional)

3.4.5 Smart Client

The minimum requirements are based on a complete installation of Smart Client. For extensive
projects or several projects loaded at the same time you will need accordingly faster/stronger
hardware. The minimum requirements can increase as a result of this.
Hardware Minimum requirements Recommended

CPU Single core with SSE2 support. Quad Core

Memory At least 4 GB More than 8 GB

24 | 173
Platform setup

Hardware Minimum requirements Recommended

Storage medium At least 3 GB of free space for Smart Client plus More than 10 GB
space for the projects.

Network 10 Mbit/s full duplex. 1000 Mbit/s full

connection duplex.

Remote Minimum requirements: Dial-up modem with 9600 1 Mbit/s full

connection Bit/s. duplex.
(optional)

Graphics adapter 64 MB dedicated memory. Cards with shared

memory can lead to performance loss. Note the
System requirements when using DirectX (on page
15) node in relation to this.

4 Platform setup
In this node, you can find detailed information on setup for apps and components of the zenon
software platform.

4.1 zenon Software Platform standard installation

zenon will automatically start its installation routine and guide you through the whole installation
process when the zenon installation medium is connected. Alternatively, it is possible to start the
installation by executing START.exe in the root folder of your zenon installation medium.

The zenon software platform is available in different embodiments with different names. Product
names and the scope may differ from the standard installation described.

Notes:
 Administrator rights are required for the installation process on the computer!
 A restart may be necessary during installation.
Close all other programs before installation.
 The minimum screen resolution for the setup is 1280 x 800 pixels.

25 | 173
Platform setup

4.1.1 Start window

You are given general information about the zenon Software Platform in the start window.

The information in the left window shows you the current status of the installation process. You switch
to the next respective window with the Next button.
You can get help on installation by clicking on the Help symbol at the top right.

1. From the drop-down list at the top right, select the desired language for installation.
The following languages are available:
 German
 English
 Italian
 French
 Spanish
 Czech
 Japanese
 Korean
 Chinese
 Russian
Note: The language can be changed at any time during the setup.

26 | 173
Platform setup

2. Clicking on the Next button opens the window with the license conditions.
3. Confirm the license conditions by activating the corresponding checkbox.
If you do not accept the license conditions, you cannot install the product.
You can also print the license conditions out by clicking on the Print button.
4. Clicking on the Next button opens the privacy policy.
Read the privacy policy carefully.
You can print out the privacy policy by clicking on the Print button.
5. Activate the checkbox for the privacy policy.
This will confirm that you have read this. If you do not accept the privacy policy, the product
cannot be installed.
6. Clicking on the Next button opens the window to select the desired product.
Note: The Next button is only available if you have agreed to the license conditions by
activating the checkbox.

4.1.2 Component selection

Select the desired components. It is only possible to select components that have not already been
installed. If you want to carry out a reinstallation, you must first uninstall the previously-installed
components using the Windows Apps application or the Control Panel.

27 | 173
Platform setup

INSTALLATION PACKAGES
There are 6 collections of packages available for installation. By default, only the pre-selected
components are installed, as well as components that you choose to be installed. You can individually
add or remove further components before installation by using the Customize button.

Note: If an exclamation mark is shown for a package, this indicates incompatibility for the installation.
For example, already-installed components that do not permit the installation of a further version. In
this case, select the adjusted installation.
Package Components

Engineering Studios Installs Engineering Studio a Reporting Studio.

Preselected:
 Engineering Studio
 Reporting Studio
 IIoT Services communication components
 License Manager

Optional:
 Service Engine
(pre-selected)
 Report Engine
 Smart Client
 Smart Server
 IIoT Services

Service Engine Installs Service Engine.

Preselected:
 Service Engine
 IIoT Services communication components
 License Manager

Optional:
 Engineering Studio
 Report Engine
 Reporting Studio
 Smart Client

28 | 173
Platform setup

Package Components
 Smart Server
 IIoT Services

Reporting & GraphQL Installs Report Engine and the GraphQL Interface.

Preselected:
 Report Engine
 IIoT Services
 License Manager

Optional:
 Engineering Studio
 Service Engine
 Reporting Studio
 Smart Client
 Smart Server
 IIoT Services communication components

Attention: The Report Engine 14 cannot be installed in

parallel with a Report Engine version 10, 11 or 12 on the same
computer. If one of these versions already exists on the
system, a corresponding message is displayed when you
select it in the setup. The installation of Report Engine 14 is
only possible after the uninstallation of Report Engine 10, 11 or
12. Versions of Analyzer 3.40 or older can be installed in
parallel with Report Engine 14.

IIoT Services Installs IIoT Services .

Preselected:
 IIoT Services
 License Manager

Optional:
 Engineering Studio
 Service Engine
 Report Engine
 Reporting Studio

29 | 173
Platform setup

Package Components
 Smart Client
 Smart Server
 IIoT Services communication components

Smart Client Installs Smart Client.

Preselected:
 Smart Client

 License Manager

Optional:
 Engineering Studio
 Service Engine
 Report Engine
 Reporting Studio
 Smart Server
 IIoT Services
 IIoT Services communication components

Smart Server Installs Smart Server.

Preselected:
 Smart Server
 License Manager

Optional:
 Engineering Studio
 Service Engine
 Report Engine
 Reporting Studio
 Smart Client
 IIoT Services
 IIoT Services communication components

30 | 173
Platform setup

4.1.3 Further details of components

Expand the components to get a more detailed description.

ENGINEERING STUDIOS
Theme Description

Solution Engineering Contains all apps that are necessary for the creation,
maintenance and further development of your
automation and reporting solution. Work on all your
projects without programming ability being necessary.

Data acquisition Connect to equipment in heterogeneous production

landscapes. Any relevant data can be captured, saved ,
compressed and called up again for further use. Validate
your data at the collection stage already and transfer it to
other systems. The data can be saved in local files or in
central databases.

Visualization & Control Machines, processes, complex systems and production

sites can be visualized, monitored and operated in real
time.

31 | 173
Platform setup

SERVICE ENGINE
Theme Description

Data acquisition Connect to equipment in heterogeneous production

landscapes. Any relevant data can be captured, saved ,
compressed and called up again for further use. Validate
your data at the collection stage already and transfer it to
other systems. The data can be saved in local files or in
central databases.

Visualization & Control Machines, processes, complex systems and production

sites can be visualized, monitored and operated in real
time.

REPORTING & GRAPHQL

Theme Description

Analytics & Reporting Includes the server and the app for creating your own
reporting solution. Create customized reports, simple
calculations and comprehensive KPIs from historical data.

Data management Process and contextualize data within the software

platform. Use interfaces to provide data to third party
systems.

IIOT SERVICES
Theme Description

Web based solutions Extend your projects with platform independent

Automation Services.

Data management Process and contextualize data within the software

platform. Use interfaces to provide data to third party
systems.

Cross-site networking Implement cross-site projects and connect machines,

processes and systems across sites by using platform
independent services.

32 | 173
Platform setup

Attention
Installation packages can be installed with the recommended components with a
click. To do this, select the components you want and click on Install.

You can use the Adjust button to adjust the installation packages individually and
to install several packages.

4.1.4 Configuration and installation

DEFAULT INSTALLATION
To install a package with the preselected components:
1. Select the desired package.
2. Click on the Install button.
The installation is started.
Note: Your computer may need to be restarted after installation. If the installation process is
not automatically continued after a restart, restart the zenon setup.
3. Follow the instructions of the wizard.

CUSTOMIZED INSTALLATION
You can adjust the packages individually.

To install an adjusted package:

1. Select the desired package.
2. Click on the Customize button.

33 | 173
Platform setup

The dialog to adjust the installation is opened.

The recommended components have been pre-selected by default.

3. In the Components tab, select or deselect the desired components.

Components can only be deselected if they are not required by another component.
Components that have already been installed cannot be deselected.
Note: Information about installation status, requirements, and dependencies of components
are dynamically displayed to you as a tool tip if you hover the mouse over the checkbox for
the components.
4. If necessary, configure the paths for installation of the selected components in the Options
tab.

34 | 173
Platform setup

Enter the root folder in the installation directory. All selected components are installed in this
path.
Once you have installed an app in the installation directory, you can no longer change this
path for future installations.

Note: If the path cannot be changed, you get a notification if you hover the mouse over the symbol
for the selection of the path.
1. Clicking on the Select Path button opens the dialog to select the required folder. This
configuration is only possible if no objects have been installed that require the installation
location.
2. Note: The configuration is validated on entry. A corresponding warning notice is shown in
the event of an error.
3. If necessary, activate the Harden Installation option in the Options tab.
In this case, note the additional configuration of connections (on page 36) necessary after
installation.
Note: You can only activate this option if there is no other version of the zenon Software
Platform on the device.
4. Click on the Install button.
The installation is started.
Note: Your computer may need to be restarted after installation. If the installation process is
not automatically continued after a restart, restart the zenon setup.

35 | 173
Platform setup

5. Follow the subsequent setup instructions.

Attention
If there is already a version of IIoT Services on the system, it is strongly
recommended that the data from this installation be backed up before an
update. You can find information about this in the Backup and Restore –
Persistence Instance section.

4.1.4.1 Hardening zenon

Activating the Harden installation option has the following effect:
 TCP/IP communication is restricted:
 zenon only permits local access.
 The SQL Server only permits local access.
 The firewall rules only allow zenon services to have local access.
 Access permissions for the zenon project folders are limited:
 A new SoftwarePlatformAccess user group is created.
Members of this group are:
- the user currently logged in
- the SYSTEM
user - the LOCAL_SERVICE user
 Access to the folders is restricted to members of the SoftwarePlatformAccess and
Administrators groups.

Note: Setting permissions for files and folders takes effect immediately. The token for access by the
user currently logged in is not updated. This means that the new permissions only take effect when
the user logs in again. The setup requests a restart at the end of the installation to force the current
user to log out and log in again.

Distributed engineering: Activating the Harden installation option also has an impact on
distributed engineering in particular due to its restrictions. You must adjust the SQL Server, firewalls
and connection to your requirements after installation. You can find information about the
configuration of hardened systems in the Help in the Security - distributed engineering with hardened
systems node.

ADJUSTMENT IN THE STARTUP TOOL

When zenon is installed, exceptions are created in the Windows firewall by the setup. They are
configured for applications and services that open a TCP Listening Port.

36 | 173
Platform setup

After installation, configure the exceptions in the Windows firewall to be more restrictive, suitable to
their environment and the required apps and services.

On multi-homed systems with multiple network cards, zenon apps and services open the TCP
Listening Port for all network cards present in the system by default. However communication
throughout all network cards is often not necessary and not desirable.

After installing zenon, configure the TCP Listening Ports for the respective services and apps,
according to their environment and requirements. Use the Startup Tool to do this. Only allow
communication between the network card or IP address that is absolutely necessary for this. If you
allocate a service to the Loopback adapter or the IP address 127.0.0.1, you only allow local
communication. This way, local Diagnosis Server access to local diagnosis clients can be limited, for
example.

Note the following for platform functionalities that are independent of the configuration of the
services:
Service Platform functionality

Administration Service Provides general functionalities for the operation of

37 | 173
Platform setup

Service Platform functionality

zenon.

DB Service The database service is only needed by Engineering

Studio. If you want to use distributed engineering, the
service must be able to communicate via the network.

Driver Operations Manager The Driver Operations Manager administers the local
driver instances of Service Engine. It must be contactable
from outside.

License Transfer Service For Remote Licensing of zenon components, they must be
able to communicate via the network. The service can also
be limited again after concluding the licensing.

Logging Service For Remote Logging via the Diagnosis Viewer, the service
must be contactable via the network.

Network Service This service must be reachable via the network for the use
of :
 zenon network
 Smart Client

Remote Transport Service Serves to manually transfer Service Engine files from an
external instance of Engineering Studio.

The service must be reachable via the network for this.

With local instances of Engineering Studio, the service can
only be operated locally.

Report Engine Licensing Service For Remote Licensing of Report Engine, this service must
be able to communicate via the network. The service can
also be limited again after concluding the licensing.

SCADA Service Engine Connector This service must be able to be contacted via the network
if Report Engine, IIoT Services or remote Service Engine
drivers:
 are used with a remote instance
 access online data of a Service Engine

Smart Server This service is necessary for the operation of the Smart
Server.
Recommendation: Operate it as a separate instance,
separate from Service Engine.

Smart Server Tunneling This service is necessary for the operation of the Smart

38 | 173
Platform setup

Service Platform functionality

Server.
Recommendation: Operate it as a separate instance,
separate from Service Engine.

SNMP Trap Service This service must be reachable via the network when
using zenon SNMP services.

4.1.5 Installation and finishing

During installation, you are informed of the installation progress and the current installation stage in
the progress bar.

The installation process may take some time. Do not turn your computer off in this time. Please also
ensure that your computer is not automatically put into sleep mode.

INSTALLATION IS COMPLETED
At the end of installation, you will receive a message about the success of the installation.

If IIoT Services has been reinstalled or updated:

1. Check or activate the license for the installed IIoT Services components using the Open
License Manager button.

39 | 173
Platform setup

2. Use the Start Configuration button for the following cases:

a) Initial configuration of a new installation of IIoT Services.
b) Adjustments to an existing configuration for pre-existing installations of IIoT Services.

CANCEL INSTALLATION
You can cancel the installation by clicking on the Cancel button.
Before canceling the installation there is a security query.
Possible actions:
 Yes: The installation is canceled.
The dialog for an invalid installation is shown.
 No: The installation is continued.

CANCELED OR INCORRECT INSTALLATION

If an error occurs during installation or the installation was canceled, this is shown in a dialog.
You have the option of creating a detailed log with the System Information Collector. You can also
send this log to COPA-DATA Support if needed.
Procedure:
1. Click on the Collect system information for Support button.

40 | 173
Platform setup

The System Information Collector is started. Relevant data is collected.

You will receive information on where the file was saved.
2. Use the information from the System Information Collector file for a reinstallation.
3. If necessary, send the file to your COPA-DATA support.
4. Attempt the installation again.

POSSIBLE CAUSES OF ERRORS

Important possible causes for a cancellation:

 A pending update to the Windows operating system.
 The SQL server required for Engineering Studio could not be installed.

4.1.6 Backup and Restore - Persistence Instance

The following applies for the Persistence Instance:
 The Persistence Service should be backed up before every update of the IIoT Services. This is
a precaution.
 A restore of the backup is only necessary in rare cases. This is the case, for instance, if a
problem occurs during an update.

You can find detailed information on this in the Backup and Restore – Persistence Instance node.

4.2 Installing additional components

You can install components of the zenon software platform that you have not yet installed at any
time, via the Setup.

To do this:
1. Start the Setup for the zenon software platform.
Because there are already components on the system, the page with the available
components is opened immediately.
Note: Information about installation status, requirements, and dependencies of components
are dynamically displayed to you as a tool tip if you hover the mouse over the checkbox for
the components.
2. Select the desired components by clicking on the respective checkbox.
If a further component is needed for a component, this is automatically selected too.
3. Click on Install.

The selected components are installed.

41 | 173
Platform setup

Note: You uninstall components using the Windows Apps app or the Control Panel.

4.3 Uninstalling components

To uninstall the zenon software platform or individual components:

Uninstall complete software platform:

 Open the Windows Apps settings.
 Click on the zenon Platform Setup entry.
 Click on Uninstall.
 Confirm the confirmation prompt.

All components of the zenon software platform are uninstalled.

Uninstall components:
 Open the Windows Apps settings.
 Click on the zenon Platform Setup entry.
 Click on Change.
The dialog to select the components is opened.
 Select the desired components.
 Click on Uninstall.

The selected components are uninstalled.

BEHAVIOR WITH DIFFERENT VERSIONS

For components of the zenon Software Platform that were installed in different versions or upgraded
to a higher version:
Components can only be changed in the version in which they were installed or to which they were
upgraded.

Example:

Components of versions 11 and 12 are available on the system.

 The Report Engine was installed in version 11. An upgrade to version 12 has not been made.
This means that it can only be removed via the version 11 installer.
 The Report Engine was installed in version 11. It was then upgraded to version 12. This means
that it can only be removed by the version 12 installer.

42 | 173
Platform setup

When calling up the Windows functionality for modifying and uninstalling apps, only those
components that have been installed with or updated to the selected version are offered for
modification for the zenon Software Platform.

4.4 Silent installation and uninstallation

zenon can also be installed and uninstalled silently (Silent Installation) and (Silent Remove).

As part of Silent Installation, it is possible to exclude certain standard components from the installation
specifically:
 Firewall rules: The CDPROP_INSTALLFIREWALL parameter decides whether rules for the
firewall are set.
 Codemeter Software: Can be configured using the PREREQUISITES_ argument for the
ISFeatureInstall parameter. Codemeter is not installed if the argument is not used.
Attention: This argument is applicable for all Prerequisites. Other Prerequisites are also not
installed in this case!

Information
All zenon versions from 7.10 on support silent installation and uninstalling.

PASSWORD CONVENTIONS FOR SA USERS

The random password created during a standard installation for the user SA on the SQL Server can
be replaced with your own password. To do this, use an individual password for the argument
CDP_SQLADMINPW= (Version 10 onwards) or CDPROP_SQLADMINPASSWORD= (before version 10).

Rules:
 Default length: 20 characters
 Permitted characters:
 Letters: A - Z, a - z
 Digits: 0 - 9
 Special characters: !@$?#%&*
 Composition:
 at least 1 lower case letter
 at least 1 upper case letter
 at least 1 number
 at least 1 special character

43 | 173
Platform setup

Attention
A user-defined password is not validated.

4.4.1 Silent installation with CLI app

Initiation of silent installation can be carried out with the following parameters:
 /silent -silent /s -s
 /quiet -quiet /q -q

For example:
 SoftwarePlatform.exe -s CDP_WORKLOAD="WlSmartClient"

 SoftwarePlatform.exe /quiet CDP_WORKLOAD="WlFullSoftwarePlatform"

 SoftwarePlatform.exe /silent CDP_WORKLOAD="WlEdgeServices"

CDP_WORKLOAD does not make sense for installations that are not silent. The argument is therefore
also not supported and is ignored.

SOFTWAREPLATFORM.EXE

Initiate installation via command line. The following parameters are available for the
softwareplatform.exe CLI app:

Parameter Arguments Description

CDP_WORKLOAD= Workload to be installed. Entry is mandatory for silent. Is

ignored with non-silent.
Must correspond to the ID from
WorkloadsSetup.config. The name and path of the
configuration file can be
Example: WlSmartClient for a
defined individually with the
SmartClient installation. CDP_WORKLOADCONFIG_P
Attention: Workloads only, no ATH= parameter.
features! Incorrect IDs or IDs that do
not exist lead to the installation being
aborted.

CDP_WORKLOADCON Path to the storage location. Optional parameter.

FIG_PATH= Specifies an individual storage
Example:
location and name of the
CDP_WORKLOADCONFIG_PATH=" workload configuration file.

44 | 173
Platform setup

Parameter Arguments Description

C:\Users\User\Desktop\My
If the parameter is not
Workload\workload.config"
specified or the file does not
exist in the specified path, the
default file
WorkloadSetup.config is used.

CDP_INSTALLFIREWALL=  1: is installed Information on whether

 0: is not installed firewall rules are installed.

Default:1

CDP_INSTALLDEMO=  1: is installed Information on whether the

 0: is not installed demo project is also to be
installed. Is only transferred to
Default:1 MSI.

CDP_LANGUAGE=  1031: German Selection of the language. Is

 1033: English only transferred to MSI.

 1034: Spanish
 1036: French
 1040: Italian
 1041: Japanese
 1042: Korean
 1049: Russian

Default:1033

CDP_SQLPATH= Path to SQL. Path for SQL installation, as in

empty: Standard path GUI.

Default: empty

CDP_INSTALLDIR= Path to 64-bit zenon installation zenon software platform

folder. installation folder for 64-bit
components
Default: default installation path

CDP_SQLADMINPW= Any desired password. SQL administrator password.

Must comply with SQL guidelines

45 | 173
Platform setup

Parameter Arguments Description

CDP_POSTINSTALLEXE= Whether PostInstall.exe is executed

after installation:
 1: is executed
 0: is not executed

Default:0

CDP_POSTINSTALLARGS Default:empty Arguments for PostInstall.exe.

=

CDP_SERVICEHUB_PW= Any desired password. Password for Certificate

Management.
ServiceGrid

CDP_SQLADMINPW= Any desired password. Password for SQL server

instance of Service Engine.

CDP_SQLADMINPW_REP Any desired password. Password for SQL server

ORTING= instance of Report Engine .

CDP_NOREBOOT= Values: Configuration of whether the

computer is restarted. Is used
 1: Restart is not performed.
when updating IIoT Services.
After installation,
SucesssReboot (3010) is
output. The new start must be
carried out manually.
 0: Restart is performed.

BUILDUPDATE

The BuildUpdate CLI app is used for updating the IIoT Services services of a version or for the
upgrade of the IIoT Services services to the next major version. To this end, the following parameters
are available with the attendant arguments:
Argument Description

/silent Carries out silent installation of the build update.

/iacceptlicenseagreement Carries out installation for the most recent build versions
(preview, beta). This argument only updates the services of
the same major version. With this argument, you confirm that
you have read the license agreement (EULA) and accept it.
This consent is mandatory for the continuation of the

46 | 173
Platform setup

Argument Description
installation process.
 Syntax: [Name of the build update].exe /silent /
iacceptlicenseagreement
 Example: SoftwarePlatform15PreviewBuild386011.exe
/silent / iacceptlicenseagreement

/upgradeiiotservices Optional argument for upgrade to new major version. If a

more recent main version is included in the build update, you
can update the previous version of IIoT Services already
installed to the new major version with this additional
argument.
 Syntax: [Name of the build update].exe /silent /
iacceptlicenseagreement /upgradeiiotservices
 Example: SoftwarePlatform15PreviewBuild386011.exe
/silent / iacceptlicenseagreement /upgradeiiotservices

SILENT UNINSTALLATION

Uninstallation must be carried out using the same SoftwarePlatform.exe that was used for installation.
Because this is saved in a folder with an execution-specific GUID, the following lines are also logged
with each successful installation.

"For uninstalling of the currently installed producty via CommandLine use:"

"For silent uninstall C:\\ProgramData\\Package Cache\\{bundleProviderGuid}\\SoftwarePlatform.exe
/silent /uninstall"
"For uninstall via UI C:\\ProgramData\\Package Cache\\{bundleProviderGuid}\\SoftwarePlatform.exe
/uninstall"

In doing so, {bundleProviderGuid} is always replaced with the execution-specific GUID. The full path to
the EXE is thus given in the LOG file.

In principle, all actions are documented in the LOG. Certain queries that are displayed as GUI
feedback during normal installation are written here in the LOG file.

4.5 Error treatment

CHECK BEFORE INSTALLATION

The system requirements are checked before installation. If the requirements are not met, you are
shown these on a separate page with notices on how to rectify this.

47 | 173
Platform setup

ERROR DURING INSTALLATION

You will receive an error message if there are errors during installation.

If you need help from the Technical Consulting department of COPA-DATA:

1. If possible, create a screenshot of the error message.
2. Navigate to the %Temp%/SoftwarePlatform folder.
3. Here you can find the log files of the installation.
4. Create a ZIP file with the content of the folder.
5. Forward the file and the screenshot to [email protected].

If you have already closed the error message window, you can find the log files with the installation
information for the SQL Server in the folder:
C:\Program Files\Microsoft SQL Server\150\Setup Bootstrap\Log

Hint: The file summary.txt provides information for troubleshooting.

Information

Firewalls: zenon automatically configures the firewall installed with Windows

during installation. Firewalls from other providers must be properly configured
by the user.

FREQUENT SOURCES OF ERROR DURING INSTALLATION:

 The virus scanner is active and blocks the installation because the scanner thinks it’s a virus.
Solution: Separate the system from the network, disable the virus scanner, carry out the
installation.
 The firewall was not configured correctly. Solution: Separate the system from the network,
disable the firewall, carry out the installation.
 Erroneous SQL-installation on the system. Solution: Create project backups; if possible,
uninstall SQL server, rename the SQL folder, and restart installation.

4.6 Windows Updates

Attention: Automatic Windows updates influence the installation.
The setup automatically detects whether Windows updates are being installed in the background at
the time or have been installed beforehand, and shows you a notice text.

If an update of the Windows operating system is carried out while the zenon setup is running, it
can cause problems during the zenon installation.

48 | 173
Platform setup

To prevent this:
 Deactivate the automatic Windows update during the time of installation.
 Carry out the Windows update before starting the zenon installation.
 Restart the computer after the update has been carried out.

4.7 Virus scan

Anti-virus software can slow down or even prevent the installation of zenon.

Note: If the anti-virus software you use leads to problems during installation, deactivate the anti-virus
software for the duration of the installation. The computers concerned can be exposed to higher risks
during this time. Activate your anti-virus software immediately after the installation of zenon.

4.8 File Structure

The special file structure is created or extended during the installation.

The zenon program files are stored in a folder that is specified during installation.

Additionally the installation asks for a folder for the SQL databases of the projects. The storage
medium for project archiving (SQL, screens etc.) must have enough free space, because all current
and future project data is stored there.
Folder Path

Program folder 32-bit system:

%ProgramFiles(x86)%\COPA-DATA\zenon Software Platform
15

%CommonProgramFiles(x86)%\COPA-DATA

64-bit system:

%ProgramFiles%\COPA-DATA\zenon Software Platform 15

%CommonProgramFiles%\COPA-DATA

Program data folder, %ProgramData%\COPA-DATA\zenon1500

for example global symbols,
print templates, LOG files, etc.

49 | 173
Platform setup

Folder Path

Database folder (SQL) %ProgramData%\COPA-DATA\SQL2022

System folder %ProgramData%\COPA-DATA\System

Settings Engineering Studio and %Users%\UserName\AppData\Local\COPA-DATA\zenon\Engi

profiles neering Studio

Settings for Diagnosis Viewer %Users%\UserName\AppData\Local\COPA-DATA\zenon\Diag

View

DEFINITION SERVICE ENGINE FOLDER AND DATA FOLDER

SERVICE ENGINE FOLDER

Engineering Studio generates Service Engine files in the Service Engine folder, or they are transferred
to this folder by means of Remote Transport. The Service Engine folder is created or updated when
compiling a project in Engineering Studio. This folder can be configured in Engineering Studio with
the Service Engine folder project property. With remote transfer, the Service Engine folder is defined
in the Remote Transport settings.

DATA FOLDER

Service Engine saves all data files that were created in Service Engine such as alarm files, archive files,
etc. in the data folder. The data folder is created as a subfolder of the Service Engine folder by
default. The folder is automatically assigned the name of the computer that Service Engine is running
on. You can change this save location in the project properties (General/Data folder).

Hint: Never set the data folder to a removable device such as an USB stick or a network device. It is
recommended that the data is recorded locally and backed up externally.

Attention
If the defined path does not exist or is not available, no more data is written
from Service Engine. This means a complete loss of data. Service Engine can still
be operated but must be restarted as soon as the path is available again. The
availability of the folder can be checked via the system driver variable
[Systeminformation] Service Engine folder not available .

50 | 173
Platform setup

4.9 Install older version, if zenon 15 is already installed (64-bit

operating system)
If, on a 64-bit operating system, after installation of zenon 15, a version of zenon with a version
number lower than 7.10 is installed, the 64-bit services must be registered again after the installation
via the command line. Registration can be carried out using a batch file or manually.

Registration with a batch file:

1. Copy the file named Register.bat from the zenon installation medium.
2. You can find this in the following folder: ...\AdditionalSoftware\Register Admin Service and Log
Service (x64)\
3. Execute the file on the respective computer as an administrator.

manual registration:
1. Run the command line with administrative rights
2. Go to the folder %ProgramFiles%\Common Files\COPA-DATA\zenAdminSrv
3. Start the service zenAdminSrv.exe with the parameter -service
4. Go to the folder %ProgramFiles%\Common Files\COPA-DATA\zenLogSrv
5. Start the service zenLogSrv.exe with the parameter -service

Example
zenAdminSrv:
 Folder: C:\Program Files\Common Files\COPA-DATA\zenAdminSrv
 Command: zenAdminSrv.exe -service

zenLogSrv:
 Folder: C:\Program Files\Common Files\COPA-DATA\zenLogSrv
 Command: zenLogSrv.exe -service

4.10 Free ports

zenon and zenon Logic require certain communication ports to communication in the network. If
other apps, for example an already-installed SQL Server, occupy these ports, communication from
zenon can be affected. Many ports in zenon can be changed using the Startup Tool or properties in
Engineering Studio.

51 | 173
Platform setup

This is how you check the port assignments:

1. Enter netstat -a -n -o in the command line.
You can reach the command line in Windows:
 Windows key + R
 Enter cmd and confirm with OK
 A DOS input window pops up
 Enter the command netstat
2. A list of all currently used TCP/IP and UDP ports will pop up.
3. Check the listening ports (states: LISTEN) if the process ID (PID) from the ports needed by
zenon and zenon Logic corresponds with the apps from zenon and zenon Logic.
These PIDs can be read in the Windows Task Manager. To do this, open the Windows Task
Manager and switch to the Services tab.

4. If another software uses these ports, reconfigure this software.

You can see which ports zenon and zenon Logic use in the Table of port assignments by
zenon and zenon Logic. Here you can also see if ports can be customized in these apps.

PORT SETTINGS BY ZENON AND ZENON LOGIC

App Description Ports Transport
log

stratonrt[k].exe Logic Service polling  1200-1210 TCP

communication and Logic
Studio.

stratonrt[k].exe  4500-4510 TCP

stratonrt[k].exe zenon Logic Redundancy.  7000-7010 TCP

stratonrt[k].exe Logic Service -  9000-9010 TCP

spontaneous
communication.

zennetsrv.exe zenon Network service.  1100-1100 TCP

zensyssrv.exe zenon Transport service.  1101 TCP

zendbsrv.exe zenon Database service.  1103 TCP

zenAdminsrv.exe zenon management  50777 TCP

service.

zenLogSrv.exe zenon logging service.  50780 TCP

52 | 173
Version change and build updates

App Description Ports Transport

log

CodeMeter.exe Code Meter Dongle  22350 (changeable TCP

service. but must not be
changed)

WkSvW32.exe WibuKey Network service.  22347 (fixed) TCP

Zenrt32.exe Message Control with  5060: SIP UDP

Voice over IP.  4000: RTP
 4001: RTCP (fixed)

SIP and RTP can be

configured using
Engineering Studio. RTCP is
automatically set by the
system.

zenHelpService.exe zenon Help provisioning  50790 TCP

service

4.11 Licensing preview versions

The following time-limited licenses are available for zenon preview programs. They have a fixed expiry
date.
If a preview version is installed, it needs an internet connection. The licensing will fail if this is not
present.
In this case, the timestamp can be updated manually.
To do this:
1. Open the command line.
2. Enter: %programfiles(x86)%\CodeMeter\Runtime\bin\cmu32.exe --time-update

The timestamp is updated and the license is valid.

5 Version change and build updates

In zenon, you can change to new versions for example, from 10 to 11. Or you can install updates
within a version.
 New versions can be installed in parallel with existing versions. They mainly offer new
features.

53 | 173
Version change and build updates

 Build updates modify a previously installed version. They mainly fix bugs.

With each setup for new build or new versions, you receive a link to the COPA-DATA website with the
changes between the previous version and the newly-installed one.

BUILD UPDATE
An update only updates those files which are more current than the previously installed files. All
projects and individual settings will remain unchanged. Build updates can contain changes for all
installed components. When calling up the setup, the components that have been changed and the
version to which they have been changed are shown.

Note: Build updates may have lower quality assurance standards than release versions.

Note: Build updates can only be installed locally. Installation on network paths (UNC) is not possible.

VERSION CHANGE
If you want to install a new version of zenon, start the installation routine. The new version is being
installed parallel to the old one. All projects and individual settings will remain unchanged. Projects
aren´t converted to the new version during installation. The respective project is converted when it´s
being opened for the first time in Engineering Studio. A dialog box notifies you about this procedure.
The old version is automatically backed up. If you want to use only the most up-to-date version, use
the Windows control panel software deinstallation routine to remove the old version.

Attention
If an installation involves changing the SQL server (for example, from zenon 10
to zenon 11 or higher), all projects or the workspace must be backed up before
the installation. This backup is read back after the installation. For details see also
section Multi-user projects/Update with change of SQL servers.

If you want to use multiple versions of zenon simultaneously, you have to manage them using the
Startup Tool. You can start only one version at a time. You can select which version you want to run
using the Startup Tool that automatically adjusts all necessary settings. You can find details in the
Startup Tool node.

54 | 173
Version change and build updates

Information
New versions always bring about structural changes. Projects and settings
remain untouched during installation. If you open Engineering Studio for the first
time, projects are converted to the new version. Simultaneously, an automatic
backup of the old version is created.

Converted projects cannot be edited in legacy versions. From version 6.2 on,
Engineering Studio is able to generate projects for different Service Engine
versions.

Important tips for converting projects can be found in the revision text and in
the Project conversion node.

MULTI-USER PROJECTS

To ensure a change to a new zenon version in multi-user projects without data loss:
1. Check in all checked out elements on all Clients by clicking Apply changes.
Nothing must be checked out. This is true for all projects.
2. Install the new zenon version on the server computer.
3. Convert all server projects to the new version.
To do this, load each project on the server computer into Engineering Studio and accept the
conversion.
4. Install the new zenon version on the client computers.
5. Load the projects to the clients.

CHANGE THE SQL SERVER

If an installation involves changing the SQL Server (e.g. from zenon 8.20 to zenon 15), additional steps
are needed.
These steps are carried out:
 after all projects are checked in
 before the new version is installed

Procedure when changing the SQL Server:

1. Check in all checked out elements on all Clients -> Apply changes.
2. On the multi-user server, open Engineering Studio in the original version.
3. Create backups of all projects which you want to edit or open with the new version:
 either as single project backups
 or as backup of the complete workspace

55 | 173
Version change and build updates

4. Install the new version on the Server.

5. Convert all Server projects to the new version by loading the previously created project
backups one time in Engineering Studio.
6. Install the update on every Client.
7. Transfer the projects from the multi-user Server to the Clients
Keep in mind the new name of the SQL instance.

The projects are converted, synchronized and ready for use.

Attention: Make sure that the settings of the firewall allows the data traffic between the multi-user
Server and the Clients.

5.1 Build update IIoT Services

As of version 12, IIoT Services versions can also be updated when installing a build update. Updates
are also possible for different builds of a minor release.
In this case, when calling up the setup, an option for an update of the IIoT Services version to the
current version is offered.

Procedure:
 Checkbox for upgrade of IIoT Services is deactivated:
IIoT Services is not updated. They remain in the version already installed on the system.
 Checkbox for upgrading IIoT Services is activated:
 IIoT Services is updated to the current version.
 The task performs a silent installation of the IIoT Services setup without rebooting.

56 | 173
Version change and build updates

 If the installation is successful, a button for manual reboot is offered at the end.
Do a reboot before starting IIoT Services. This ensures the correct operation of all
services.

Information
An update of the IIoT Services version can only take place in a build update within
the zenon major version.

The following applies for zenon versions 12 and 14: IIoT Services can be updated
up to version 14.3 at the most.

5.2 Compatibility
Compatibility in zenon concerns:
 Service Engine: Cooperation of different Service Engine versions.
 Engineering Studio: Up-converting existing projects to new Engineering Studio versions.
 Engineering Studio: Creating Service Engine files for different Service Engine versions in
Engineering Studio.

SERVICE ENGINE
Service Engine online compatibility enables Service Engine systems to work together in the zenon
network, as well as via Smart Clients.

The following is applicable here: The version of the client Service Engine must be the same or higher
than the version of the server Service Engine.
For example:
 An 8.20 client can work together with an 8.10 server.
 An 8.00 client does not work together with an 8.10 server. In this case, the client Service
Engine must be upgraded to version 8.10 or higher.

Note: When using the server and standby server, the same zenon version must be used on both of
them.

The current Service Engine can load projects of the following versions:
 6.20 SP4
 6.21 SP0
 6.21 SP1
 6.22 SP0

57 | 173
Version change and build updates

 6.22 SP1
 6.50 SP0
 6.51 SP0
 7.00 SP0
 7.10 SP0
 7.11 SP0
 7.20 SP0
 7.20 Sp0[current build no.]
 7.50 SP0
 7.60 SP0
 8.00 SP0
 8.10 SP0
 8.20 SP0
 10.00
 11.00
 12.00
 14.00
 15.00

Due to the multi-project administration, projects from different versions can be loaded. For example,
the integration project can be from version 8.20, a subproject from version 8.10 and another
subproject from version 7.60.

ENGINEERING STUDIO
Engineering Studio can open projects from the previous versions in each new version. These can be
edited further in the new version. If adjustments are required by the user, information can be found in
the current revision text and in the Project conversion node. When opening a project with a lower
version number in a higher Engineering Studio version:
 the project is automatically converted
 a backup of the project is automatically created

58 | 173
Version change and build updates

Attention
There is no backward compatibility between Engineering Studio versions.
Backward compatibility is only ensured between Engineering Studio and Service
Engine.

That means:
 Converted projects can no longer be opened in a Engineering Studio with a
lower version number.
 The project backup created during conversion can still be opened and
edited.

Also avoid transferring projects via XML import from newer to older versions.
This can lead to undesirable results. Drivers in particular can perform differently
than expected.

COMPATIBILITY BETWEEN ENGINEERING STUDIO AND SERVICE ENGINE

With Engineering Studio, Service Engine files can be created for different versions of Service Engine.
The Service Engine version therefore does not need to correspond to the Engineering Studio version.
This backward compatibility is particularly suited for use of mixed systems.

For example: A project that has been configured with Engineering Studio version 10.00 and
compiled for version 8.00 can also be started with Service Engine version 8.00.

Attention
If possible, the same version of Engineering Studio and Service Engine should
always be used, or a newer version of Service Engine. Configurations of
properties that are not available in older versions can lead to unwanted results in
older versions of Service Engine. The same is applicable for Create Service
Engine files for and driver Configuration.

CREATE SERVICE ENGINE FILES

To create Service Engine files for earlier versions in Engineering Studio:

1. Select the project in the project tree.
2. Navigate to the General section in project properties.
3. Open the Create Service Engine files for property drop-down list.
4. Select the desired version from the drop-down list.

59 | 173
Software and paths for installation and operation

Attention: In order to ensure consistency of Service Engine files, all Service Engine files must be
newly created each time this property is changed. The configurations for all drivers are converted.
Settings that do not exist in the configured version are set to the default setting.

ERROR CREATING SERVICE ENGINE FILES AND MICROSOFT OFFICE 365

In certain configurations, an error may occur when creating Service Engine files:
 You can create Service Engine files on a computer with:
 Windows 10
operating system and
 Office 365.
 The creation of Service Engine files has failed and is ended with an error message.

This is caused when an incorrect version of a program library by VBA is loaded.

Solution:
1. Go to the folder: %AppData%\Microsoft\FORMS.
2. Delete the file zenone32.box.
3. This file is created new automatically by the zenon.

The creation of Service Engine files is possible again.

XML
Data exported in XML is then available for import into later Engineering Studio versions.

Exception: If data from the RGM is saved in Service Engine directly as an XML file using the export
function, this cannot be reimported.

Recommendation: Avoid transferring projects via XML import from newer to older versions. This
can lead to undesired events in Engineering Studio and Service Engine.

6 Software and paths for installation and operation

Paths for zenon:
 Installation
 Engineering Studio
 Service Engine

60 | 173
Software and paths for installation and operation

Info
You can display many standard paths with the help of the set command:
 start the command line (enter cmd in the Windows start area)
 enter command set
 by pressing the Enter key, the default folder for Windows and zenon are
displayed

Note: Because absolute paths can differ in different operating systems, paths are always displayed as
Windows environment variables in this node. For example %ProgramData% instead of
C:\ProgramData.

INSTALLATION
During installation, paths are set for:
 Installation directory zenon Software Platform 32-bit
 Installation directory zenon Software Platform 64-bit
 Engineering Studio SQL database
 Report Engine SQL database

Adjust the path of the installation directory to install all selected components there.

Attention
Once a zenon component has been installed in an installation directory, the path
cannot be subsequently changed.

The setup needs administrator rights; this is also applicable when changing the installation paths.

REQUIREMENTS

The installation paths of the required third-party software match the standard paths of the respective
manufacturer and cannot be changed during setup.

The additional software packages that need to be installed depend on the type of installation:
 Engineering Studio
 Service Engine
 Smart Client

 Logic Service

61 | 173
Software and paths for installation and operation

Requirements Enginee Service Smart Logic

ring Engine Client Service
Studio

Microsoft .NET 8.0 X X X --

Microsoft SQL Server 2022 Express X -- -- --

(Bei Report Engine Standard Edition)

Microsoft Visual C++ 2022 Redistributable X X X X

Microsoft .NET Core Hosting Bundle 6.0.3 X X X X

CodeMeter Runtime Kit 8 X X -- X

Microsoft Web Deploy 3.6 -- -- -- --

Visual Basic for Applications | VBA 7.1 X X X --

Visual Basic for Applications Language Pack | X X X --

VBA 7.1

COPA-DATA Multiple Network Protocol Driver X X -- X

Key:
X: supported

--: not supported

Notes:
 Microsoft Visual Studio Tools for Applications (VSTA 2.0) is not required and is not installed
during setup. It can be installed separately using the Startup Tool. To do this, the
VSTA_AddOn.exe file must be on the system.

 Microsoft Visual Basics for Applications (VBA) is not required and is not installed during
setup. It can be installed separately using the Startup Tool. To do this, the VBA_AddOn.exe
file is provided on the system with the setup.

ZENON

The installation of Engineering Studio sets two paths:

 Engineering Studio:
 32-bit systems: %ProgramFiles(x86)%\COPA-DATA\zenon Software Platform [Version]
 64-bit systems: %ProgramFiles%\COPA-DATA\zenon Software Platform [Version]

62 | 173
Software and paths for installation and operation

These paths can be customized during the installation.

 zenon SQL folder:
 version 14 and higher: %ProgramData%\COPA-DATA\SQL2022\
These paths can be customized manually via zenDB.ini.

ENGINEERING STUDIO
In Engineering Studio, the following paths are used by default:
Object Path

Workspace %CD_USERDATA%

For example: C:\Users\Public\Documents\zenon_Projects

Projects %CD_USERDATA%

For example: C:\Users\Public\Documents\zenon_Projects

Hint for shortcuts: highlight the project -> Ctrl+Alt+D

SQL folder of the %ProgramData%\COPA-DATA\[SQL folder]\[GUID]\FILES

project
Hint for shortcuts: highlight the project -> Ctrl+Alt+E

project.ini %ProgramData%\COPA-DATA\[SQL folder]\[GUID]\FILES\zenon\system

zenon6.ini %ProgramData%\COPA-DATA\System

For example: C:\ProgramData\COPA-DATA\System

Backup %ProgramData%\COPA-DATA\[SQL folder]\GUID]\BACKUP

%ProgramData%\COPA-DATA\[SQL folder\GUID]\FILES\[Projects]

Compiled files %CD_USERDATA%\[Workspace]\[Project]\RT

External files %CD_USERDATA%\[Workspace]\[Project]\RT\FILES\...

Note: In the project adjustable via property File storage.

System files Windows system folder.

SERVICE ENGINE
In Service Engine, the following paths are used by default:

63 | 173
Installation of Service Engine

Object Path

Projects %CD_USERDATA%\[Workspace]\[Project]\RT

External files %CD_USERDATA%\[Workspace]\[Project]\RT\FILES\...

Exported archives, %CD_USERDATA%\[Workspace]\[Project]\Export

Chronological Event
List and Alarm Note: Is created at the first export.
Message List

System files Windows system folder.

ZENON LOGIC
Paths for zenon Logic are created in the same way as zenon paths.

7 Installation of Service Engine

The procedure for putting Service Engine into operation for the first time depends on whether the
device you are operating is a turn-key device with Service Engine installed or a device on which
Service Engine must be installed. If Service Engine is already installed on the device, only the desired
project needs to be copied to the Service Engine device.

To do this:
 Save your project files on an external data medium.
 Use Drag&Drop or Copy&Paste to transfer these to your Service Engine device.

or
 Get the project from the server on the Service Engine device.
 Create a Client using the network topology.

Note: This is also possible by means of remote transport.

If Service Engine is not yet installed on the device, it must first be installed. You can read how this
works in the zenon standard installation (on page 25) node.

A license is required after installation of Service Engine in order to put it into operation. The license is
transferred with the License Manager.

Note: The storage medium of the device you are operating may stop working after many years of
use in a harsh industrial environment. To avoid loss of data, it makes sense to ensure that you have a

64 | 173
Installation of Service Engine

redundant environment. This redundancy is implemented with a server and a Standby Server.
Implement this redundancy with the zenon network. With this redundancy design, a server and a
Standby Server are used, to guarantee fail safety.

7.1 Installation
For the installation of Service Engine, start the installation process from your zenon installation
medium.

This process automatically starts when the zenon installation medium is connected and guides you
through the whole installation. Alternatively, it is possible to start the installation by executing the
START.exe file in the root folder of your zenon installation medium.

Information
You can find further information in the Installation and updates (on page 8)
node in the zenon standard installation (on page 25) node.

7.2 System requirements and operating systems

A detailed overview of supported operating systems and the required software and hardware can be
found in the installation and updates (on page 8) node.

7.2.1 System requirements when using DirectX

The following minimum requirements must be met when using DirectX hardware or DirectX software:

Note: For extensive projects or several projects loaded at the same time you will need accordingly
faster/stronger hardware. The minimum requirements can increase as a result of this.
Parameter Minimum requirements Recommended

CPU: Single core with SSE2 support. Quad Core or more cores

Graphics adapter: DirectX 11 mainstream graphics Dedicated DirectX 11 AMD or

card. nVidia high-end graphics card
(DirectX hardware
only) Note: When an integrated
graphics chip is used in particular,
it is possible, depending on the
driver used, that there are
impairments to the display quality
and considerable performance

65 | 173
Installation of Service Engine

Parameter Minimum requirements Recommended

impairments.

Graphics memory: At least 1 GB VRAM 2 GB VRAM or more

(DirectX hardware Note: The size that is actually

only) needed depends on the number
of screens called up and the
elements displayed.

Graphics card driver: The graphics card manufacturer's most recent driver.

(DirectX hardware
only)

Operating system: DirectX Hardware and DirectX Software only work on operating systems
with DirectX 11.1 support.
If the system does not support DirectX 11.1, it is automatically switched
to Windows based .

The current DirectX-Service Engine must be installed. For zenon it is

installed together with the setup. It must be manually installed for Smart
Client.

You can check the DirectX hardware compatibility of the graphics card and the driver with the
dxdiag.exe of the Windows operating system.
As of Windows 8: All supported versions of DirectX are displayed in the Display tab under Feature
Levels. For example, DirectX 11 is displayed as 11.0.

7.2.2 File Structure

The special file structure is created or extended during the installation.

The zenon program files are stored in a folder that is specified during installation.

Additionally the installation asks for a folder for the SQL databases of the projects. The storage
medium for project archiving (SQL, screens etc.) must have enough free space, because all current
and future project data is stored there.

66 | 173
Installation of Service Engine

Folder Path

Program folder 32-bit system:

%ProgramFiles(x86)%\COPA-DATA\zenon Software Platform
15

%CommonProgramFiles(x86)%\COPA-DATA

64-bit system:

%ProgramFiles%\COPA-DATA\zenon Software Platform 15

%CommonProgramFiles%\COPA-DATA

Program data folder, %ProgramData%\COPA-DATA\zenon1500

for example global symbols,
print templates, LOG files, etc.

Database folder (SQL) %ProgramData%\COPA-DATA\SQL2022

System folder %ProgramData%\COPA-DATA\System

Settings Engineering Studio and %Users%\UserName\AppData\Local\COPA-DATA\zenon\Engi

profiles neering Studio

Settings for Diagnosis Viewer %Users%\UserName\AppData\Local\COPA-DATA\zenon\Diag

View

DEFINITION SERVICE ENGINE FOLDER AND DATA FOLDER

SERVICE ENGINE FOLDER

Engineering Studio generates Service Engine files in the Service Engine folder, or they are transferred
to this folder by means of Remote Transport. The Service Engine folder is created or updated when
compiling a project in Engineering Studio. This folder can be configured in Engineering Studio with
the Service Engine folder project property. With remote transfer, the Service Engine folder is defined
in the Remote Transport settings.

67 | 173
Installation of Service Engine

DATA FOLDER

Service Engine saves all data files that were created in Service Engine such as alarm files, archive files,
etc. in the data folder. The data folder is created as a subfolder of the Service Engine folder by
default. The folder is automatically assigned the name of the computer that Service Engine is running
on. You can change this save location in the project properties (General/Data folder).

Hint: Never set the data folder to a removable device such as an USB stick or a network device. It is
recommended that the data is recorded locally and backed up externally.

Attention
If the defined path does not exist or is not available, no more data is written
from Service Engine. This means a complete loss of data. Service Engine can still
be operated but must be restarted as soon as the path is available again. The
availability of the folder can be checked via the system driver variable
[Systeminformation] Service Engine folder not available .

7.2.3 Free ports

zenon and zenon Logic require certain communication ports to communication in the network. If
other apps, for example an already-installed SQL Server, occupy these ports, communication from
zenon can be affected. Many ports in zenon can be changed using the Startup Tool or properties in
Engineering Studio.

This is how you check the port assignments:

1. Enter netstat -a -n -o in the command line.
You can reach the command line in Windows:
 Windows key + R
 Enter cmd and confirm with OK
 A DOS input window pops up
 Enter the command netstat
2. A list of all currently used TCP/IP and UDP ports will pop up.
3. Check the listening ports (states: LISTEN) if the process ID (PID) from the ports needed by
zenon and zenon Logic corresponds with the apps from zenon and zenon Logic.
These PIDs can be read in the Windows Task Manager. To do this, open the Windows Task
Manager and switch to the Services tab.

68 | 173
Installation of Service Engine

4. If another software uses these ports, reconfigure this software.

You can see which ports zenon and zenon Logic use in the Table of port assignments by
zenon and zenon Logic. Here you can also see if ports can be customized in these apps.

PORT SETTINGS BY ZENON AND ZENON LOGIC

App Description Ports Transport
log

stratonrt[k].exe Logic Service polling  1200-1210 TCP

communication and Logic
Studio.

stratonrt[k].exe  4500-4510 TCP

stratonrt[k].exe zenon Logic Redundancy.  7000-7010 TCP

stratonrt[k].exe Logic Service -  9000-9010 TCP

spontaneous
communication.

zennetsrv.exe zenon Network service.  1100-1100 TCP

zensyssrv.exe zenon Transport service.  1101 TCP

zendbsrv.exe zenon Database service.  1103 TCP

zenAdminsrv.exe zenon management  50777 TCP

service.

zenLogSrv.exe zenon logging service.  50780 TCP

CodeMeter.exe Code Meter Dongle  22350 (changeable TCP

service. but must not be
changed)

WkSvW32.exe WibuKey Network service.  22347 (fixed) TCP

Zenrt32.exe Message Control with  5060: SIP UDP

Voice over IP.  4000: RTP
 4001: RTCP (fixed)

SIP and RTP can be

configured using
Engineering Studio. RTCP is
automatically set by the
system.

zenHelpService.exe zenon Help provisioning  50790 TCP

69 | 173
Installation of Service Engine

App Description Ports Transport

log
service

7.2.4 Exceptions for anti-virus

zenon needs a range of services and operations that anti-virus programs could categorize as
potentially dangerous.

Examples of this:
 Communication with CodeMeter --> USB dongle
 Loading VBA or VSTA code
 Embedding ActiveX elements in screens
 Frequent file access, for example for archiving, CEL, AML...

Note: There are compatibility problems with Ahnlabs V3 virus scanner. If zenon refuses to start and
displays an error message, put V3 into Game-Mode or uninstall V3.

7.2.5 Firewall setup

zenon uses a number of ports. These must be activated in security measures, such as a firewall, and
accessible during operation.

PORTS USED
For communication within zenon, only TCP ports are used; no UDP ports are used. zenon requires the
following ports in the network:
Service File Task TCP
port

Network service zenNetSrv.exe Service Engine communication. 1100

Transport service zenSysSrv.exe Data transfer by means of Remote 1101

Transport (Engineering Studio).

Smart Server zenWebSrv.exe On-site logging machine between 1102

Smart Client and Service Engine.

Port numbers can be changed individually via the Listening ports tab in the Startup Tool. In this case,
the measuring range must be adapted manually.

70 | 173
Installation of Service Engine

Furthermore, zenon and Report Engine services use a range of default ports.

DEFAULT PORTS

ZENON
Application Startup Tool naming Standard port

Administration Service zenAdminSrv.exe 50777

Note: Only local connections are permitted,

regardless of the settings of the network
card or IP address.

DB Service zenDBSrv.exe 1103

Driver Operations Manager Driver zenDrvOpsManager.exe 50787

Note: Only local connections are permitted,

regardless of the settings of the network
card or IP address.

Driver Operations Manager SE zenDrvOpsManager.exe 50786

Note: Only local connections are permitted,

regardless of the settings of the network
card or IP address.

License Transfer Service zenLicTransfer.exe 50784

Logging Service zenLogSrv.exe 50780

Network Service zenNetSrv.exe 1100

Remote Transport Service zenSysSrv.exe 1101

Report Engine License Service zrsLicSrv.exe 50779

SCADA Service Engine Connector zrsConnector.exe 50778

Smart Server zenWebSrv.exe 1102

Smart Server Tunneling zenWebSrv.exe 8080

SNMP Trap Service zenSnmpTrapSrv.exe 50782

Help Service zenHelpService.exe 50790

SQL Browser Service, sqlbrowser.exe 1434

(for distributed engineering in Engineering

71 | 173
Installation of Service Engine

Application Startup Tool naming Standard port

Studio)

ZENON LOGIC
Application Standard port

Assigned port for zenon Logic or straton depends on the project and 1200 - 1210
service.
4500 - 4510
e.g.: First zenon Logic project used 1200 and 9000, second project 1201
7000 - 7010
and 9001 etc.
9000 - 9010

REPORT ENGINE
Application Standard port

Administration Service 50777

Analyzer Connector Service 50778

Analyzer License Service 50779

Reporting Studio 50781

DRIVERS
Application Standard port

Driver Simulation 6000 - 6020

Process Gateway OPC Server 135

Process Gateway SNMP 161

Process Gateway Modbus 502

Process Gateway IEC60870-5 104 slave 2404

Process Gateway DEC 5555

Process Gateway DNP3 Slave 20000

IIOT SERVICES
Application Standard port

IIoT API 9400

72 | 173
Installation of Service Engine

Application Standard port

Certificate Management (general) 9410

Certificate Management (dedicated port for connection to Data Hub) 9412

Data Hub 9411

Configuration Backend 9420

Identity Service 9430

Identity Management 9431

Note: zenon drivers that communicate by means of Ethernet use TCP and may therefore require
permissions in the firewall in this case, depending on the port used. Therefore you must ensure that
you can share the necessary ports.

7.3 Hardware requirements

One of the requirements for putting Service Engine into operation is that the setup (on page 60) has
been completed successfully. A valid license is also necessary. If this license is missing, Service Engine
can only be started for a limited time period in demo mode (on page 76).

The minimum requirements are listed in the following table. These are based on a complete
installation of Service Engine. For extensive projects or several projects loaded at the same time you
will need accordingly faster/stronger hardware. The minimum requirements can increase as a result
of this.
Hardware Minimum requirements Recommended

CPU Single core with SSE2 support. Quad Core

Memory Windows 8: from 512 MB. Windows 8: 4096 MB

Note: Projects with large amounts of data,

network projects, several parallel projects and
projects in redundant operation require more
memory.

Storage medium 2 GB free space for Service Engine installation

plus additional space for the projects.

Attention: If you log historical data (e.g.

archived data or alarm/CEL data), there will
need to be sufficient memory available or the
configuration has to ensure that the historical
data is evacuated or deleted.

73 | 173
Installation of Service Engine

Hardware Minimum requirements Recommended

Monitor resolution VGA with 1280 x 800 pixels.

Graphics adapter 64 MB dedicated memory. Cards with shared

memory can lead to performance loss. Note
the System requirements when using DirectX
(on page 15) node in relation to this.

Input devices Keyboard and/or mouse. Operation via

touchscreen is also possible. Many individual,
customizable touch keyboards for the
touchscreen are available for you.

USB interface  For installation.

Installation also possible via network or
(optional) other storage media.
 For dongle. Network dongle also
available.

Network 64 kBits/s for standard Client/Server projects. 100 Mbits/s full duplex
connection for standard
100 Mbit/s full duplex for redundant
(optional) Client/Server projects.
operation.

Remote Minimum requirements: Dial-up modem with 1 Mbit/s full duplex.

connection 9600 Bit/s.
(optional)

WAN connection Any desired conncetion via router, e.g. per

(optional) ISDN or DSL. Data transfer is slower in a WAN
than in a local network for technical reasons.
Be sure to check the possible data transfer
rates of your WAN technology already at the
time when you create the project.

Message Control Please refer to the Message Control node for

(optional) the requirements.

Interfaces The necessary interfaces depend on the

(optional) requirements of the PLC and/or the bus
connection, for example serial RS-232 or
RS422/485 interfaces, ISA/PCI slots, etc.

74 | 173
Installation of Service Engine

7.3.1 Paths for setup and operation

Paths for zenon:
 Setup
 Service Engine

Information
You can display many standard paths with the help of the set command:
 start the command line (enter cmd in the Windows start area)
 enter command set
 Press the Enter key to display standard folders for Windows and zenon

Note: As absolute paths differ in different operating system, the paths are displayed as Windows
environment variables in this node. For example %ProgramData% instead of C:\ProgramData.

SETUP
During setup, paths are set for required third-party software and the Service Engine folder.
Setup requires administrator rights, which also applies to changing the installation paths. You can
read more information about prerequisites in the Installation and updates (on page 8) node, in the
Software and paths for installation and operation (on page 60) node.

SERVICE ENGINE
Service Engine uses the path that is set in zenon6.ini for projects. This path can be set using the
Startup Tool as well as using the Remote Transport from a Engineering Studio.
Object Path

Project [user-defined path]\[project]\RT

External files [User-defined path]\[project]\RT\FILES\...

Exported archives, [User-defined path]\[project]\Export

Chronological Event List
and Alarm Message List Note: Is created at the first export.
System files Windows system folder.

ZENON LOGIC
Paths for zenon Logic are created in the same way as zenon paths.

75 | 173
Installation of Service Engine

7.3.2 Demo licenses and Demo mode

Each installation contains:
 Demo licenses: Allows you to test a component for a certain time period.
Demo licenses follow the rules for licenses with a time quota.
Note: Engineering Studio can be started the first 30 times with a duration of 30 minutes
each. It switches to demo mode after this.
 Demo mode: Allows you to start a component and use it for a certain period of time. It is
closed again afterwards.
Engineering Studio duration: 10 minutes
Service Engine duration: 30 minutes

Each installation contains at least one demo license. This has a pre-defined duration or number of
permitted starts. If these are used up, the component can continue to be used in demo mode, but it
is automatically ended after running for a defined duration however. You can find out what usage
period is available in the License Manager. To do this, open the details of the license in the License
Manager tab.

COPA-DATA components:
 Engineering Studio with Logic Studio as a service
Demo license:
 30 Starts, with a duration of 30 minutes each
 10 minutes, if the number of demo starts has been used up
 Service Engine und Logic Service:
Runtime period for demo licenses:
 43200 minutes on hardware computers
 1440 minutes for virtual machines
 30 minutes if the time allocation has been used up
 Logic Studio (as an integrated solution in Engineering Studio)
Term for demo licenses:
 256 TAGs
 120 minutes
 Process Gateway and OPC DA Server

 Smart Server and Smart Client

 HTML Web Engine

 Report Engine
 Certificate Management
 IIoT API

76 | 173
Installation of Service Engine

 Identity Service

Demo licenses have their own software dongles. These cannot be used for other licenses. The last
existing demo license cannot be deactivated using the License Manager.

The remaining duration and the number of the starts that are still possible for demo licenses and
demo mode are shown in the start screen and in the version and license information.

To administer existing demo licenses:

1. Open the License usage tab.
2. Select the desired demo license.
3. Select the desired component.
4. Click on the button at the far right of the list.
The button turns green in color and the license is now being used.

MISSING DEMO LICENSE

If no demo license is available on your computer, then:
1. Open the License Manager.
The activation of a demo license is offered to you on the start screen. You only find demo
licenses in this area. Component licenses that have already been obtained are not displayed
here.
2. Select the desired demo license.
The license is activated and can be used immediately by clicking on it. Only one demo license
can be activated at the same time. If a new demo license is activated, the previous one is
deactivated.

Note: If there is also no demo license available in License Manager, contact your COPA-DATA sales
partner.

Hint
You can use demo licenses to test components and editions. To do this, place
the demo license at the first location of the license list in the License Manager.
This license is used the next time the component is started.

77 | 173
Installation of Service Engine

7.3.3 Service Engine under Windows Embedded Standard

The minimum requirements relate to an installation of Service Engine adapted to the Windows
Embedded Standard 7 SP1 operating system with platform update. The hardware must be accordingly
more powerful for extensive projects.

This table only states the figures that are different to the standard installation. The other parameters
correspond to the figures described in the Hardware requirements for Service Engine (on page 20)
node.
Hardware Minimum requirement Recomme
nded

Memory  512 MB.  204

8
Note: Projects with large amounts of data, network MB
projects, several parallel projects and projects in
redundant operation require more memory.

Storage medium  2 GB of free memory on C:\ drive before the  80

installation of .NET Framework GB
800 MB of free memory after the installation of the
.NET Framework
 plus memory space for the projects, archives, etc.

Attention: If you log historical data (e.g. archived data or alarm/CEL data), there will need to be
sufficient memory available or the configuration has to ensure that the historical data is evacuated or
deleted.

7.4 How do you establish whether the Service Engine

computer has reached its limits?
The system is at the limit of its CPU load if the Windows Task Manager reports:
 That a logical processor has a lasting load of more than 80% and
 The CPU speed is close to the maximum

This is also the case if the stated overall CPU load is low.

78 | 173
Installation of Service Engine

Example: The illustration shows a situation in which a logical processor is constantly under a high
load of 80%. However, because the CPU speed has not achieved peak values (2.8 GHz of a nominal
3.30 GHz), this system can be seen as just about powerful enough.

If the computers continually work with a high load, it is recommended that they are operated in an
air-conditioned environment.

Note: In the zenon network, the Standby Server needs the highest CPU capacities, because it must
process both the tasks of the server and those of the client. If a CPU load that is too high is detected,
the zenon project should be scaled to several projects and distributed to further servers. You can find
more information in the Multi-Project Administration node.

7.5 Uninstall Service Engine

To uninstall Service Engine:
1. Open the Control Panel.
2. Click on Programs.
3. Click on Programs and Features.
4. Select zenon 15 in the programs.

79 | 173
Report Engine

5. Click on Uninstall.
6. Follow the uninstall wizard.

8 Report Engine
This section provides information for installing the Report Engine.

8.1 Installation and updates

The installation of Report Engine consists of several components:
 Report Engine server: Central SQL server.
 Reporting Studio: Application to administer Report Engine and to create reports. It must be
installed on the engineering computer.
 Additional applications

Attention
Ensure that you have the appropriate licenses.

Note: For each user, up to three different devices at the same time per license are
permitted.

You can find the hardware and software requirements in the Prerequisites node.

NOTES
Note the following before installation:
Theme Description

User authorizations: Local administrator rights are required for the installation of Report
Engine.
Ensure that, after installation, there is at least one user who can log
into Report Engine.

Attention: The user who carries out an installation is automatically

created as the first user for Report Engine. After installation, only this
user can login to Report Engine and add further users.
For example: User 1 is the local administrator and carries out the

80 | 173
Report Engine

Theme Description
installation. Report Engine is used by User 2 however. User 1 must add
User 2 in the Reporting Studio after installation.

ISOs and restart: The content of ISO images must be copied to a local storage medium
before the installation and setup can be started from here.
The inclusion of an ISO image and the installation of Report Engine by
the mounted driver cannot be completed successfully if a restart is
required during installation.

Licensing: Licensing is carried out using the License Manager. This can be started
from Reporting Studio or from the operating system directly.

.NET Framework 4.8: .NET Framework 4.8 must already be installed and running on the
target computer in order to carry out the installation successfully.
Otherwise, an error notification from the Report Engine setup will show
up and the installation process will be canceled.

Remote installation: The installation medium must be on the local computer. Network
drives may not be available punctually for a reboot during installation.
For remote installations and virtual installations, copy the content of
the installation medium to a temporary folder on the computer and
start the setup.

Server: The Report Engine server and the Domain Controller must not be
installed on the same computer.

IIoT Services Some components need a connection to the IIoT Services in order to
connect with the Service Engine. You can configure this with the IIoT
Services Connection Wizard.

SQL Server If the SQL Server Management Studio (SSMS) is to be available, it must
Management Studio: be installed manually.

Wizards Several wizards are available for Report Engine. They work with
different Report Engine versions and zenon versions. For details, read
the Report Engine wizard compatibility node.

PERFORMING THE INSTALLATION

To install Report Engine components:
1. Connect the installation medium to the computer or copy its contents to a local folder.
If Autorun does not automatically start the setup, use the file named start.exe.
The zenon Software Platform setup is opened.
2. Select the desired language from the drop-down list.

81 | 173
Report Engine

3. Accept the license conditions.

4. Click on the Next button.
5. Accept the data protection agreement.
6. Click on the Next button.
7. Select the desired components.
Note: For the installation of the Report Engine Server, a Data Hub for IIoT Services must also
be installed. This is regardless of whether there is already a Data Hub in the system. The
Report Engine server uses the Data Hub to establish the connection to IIoT Services.
In an additional dialog, you are requested to issue a user name and password for access to
the Data Hub. Attention: Note the password in a secure place. It cannot be displayed or
recovered later.
8. Click on the Next button.
The installation or the update will start.
9. Follow the instructions given to you by the installation wizard.
10. After successful installation, configure the connections to IIoT Services.

Notes on update: When switching version, the version of the assemblies contained in the database
is checked before the update of the structure. If the version to be installed is more recent, the SQL
elements contained are updated.

INSTALLATION ON THE CLIENT

Only a current browser is needed on the client. The language that is set in the browser determines
the language for Report Launcher. The language for Reporting Studio is stipulated in the options in
Reporting Studio.

8.1.1 Start window

You are given general information about the zenon Software Platform in the start window.

82 | 173
Report Engine

The information in the left window shows you the current status of the installation process. You switch
to the next respective window with the Next button.
You can get help on installation by clicking on the Help symbol at the top right.

1. From the drop-down list at the top right, select the desired language for installation.
The following languages are available:
 German
 English
 Italian
 French
 Spanish
 Czech
 Japanese
 Korean
 Chinese
 Russian
Note: The language can be changed at any time during the setup.
2. Clicking on the Next button opens the window with the license conditions.

83 | 173
Report Engine

3. Confirm the license conditions by activating the corresponding checkbox.

If you do not accept the license conditions, you cannot install the product.
You can also print the license conditions out by clicking on the Print button.
4. Clicking on the Next button opens the privacy policy.
Read the privacy policy carefully.
You can print out the privacy policy by clicking on the Print button.
5. Activate the checkbox for the privacy policy.
This will confirm that you have read this. If you do not accept the privacy policy, the product
cannot be installed.
6. Clicking on the Next button opens the window to select the desired product.
Note: The Next button is only available if you have agreed to the license conditions by
activating the checkbox.

8.1.2 Component selection

Select the desired components. It is only possible to select components that have not already been
installed. If you want to carry out a reinstallation, you must first uninstall the previously-installed
components using the Windows Apps application or the Control Panel.

84 | 173
Report Engine

INSTALLATION PACKAGES
There are 6 collections of packages available for installation. By default, only the pre-selected
components are installed, as well as components that you choose to be installed. You can individually
add or remove further components before installation by using the Customize button.

Note: If an exclamation mark is shown for a package, this indicates incompatibility for the installation.
For example, already-installed components that do not permit the installation of a further version. In
this case, select the adjusted installation.
Package Components

Engineering Studios Installs Engineering Studio a Reporting Studio.

Preselected:
 Engineering Studio
 Reporting Studio
 IIoT Services communication components
 License Manager

Optional:
 Service Engine
(pre-selected)
 Report Engine
 Smart Client
 Smart Server
 IIoT Services

Service Engine Installs Service Engine.

Preselected:
 Service Engine
 IIoT Services communication components
 License Manager

Optional:
 Engineering Studio
 Report Engine
 Reporting Studio
 Smart Client

85 | 173
Report Engine

Package Components
 Smart Server
 IIoT Services

Reporting & GraphQL Installs Report Engine and the GraphQL Interface.

Preselected:
 Report Engine
 IIoT Services
 License Manager

Optional:
 Engineering Studio
 Service Engine
 Reporting Studio
 Smart Client
 Smart Server
 IIoT Services communication components

Attention: The Report Engine 14 cannot be installed in

parallel with a Report Engine version 10, 11 or 12 on the same
computer. If one of these versions already exists on the
system, a corresponding message is displayed when you
select it in the setup. The installation of Report Engine 14 is
only possible after the uninstallation of Report Engine 10, 11 or
12. Versions of Analyzer 3.40 or older can be installed in
parallel with Report Engine 14.

IIoT Services Installs IIoT Services .

Preselected:
 IIoT Services
 License Manager

Optional:
 Engineering Studio
 Service Engine
 Report Engine
 Reporting Studio

86 | 173
Report Engine

Package Components
 Smart Client
 Smart Server
 IIoT Services communication components

Smart Client Installs Smart Client.

Preselected:
 Smart Client

 License Manager

Optional:
 Engineering Studio
 Service Engine
 Report Engine
 Reporting Studio
 Smart Server
 IIoT Services
 IIoT Services communication components

Smart Server Installs Smart Server.

Preselected:
 Smart Server
 License Manager

Optional:
 Engineering Studio
 Service Engine
 Report Engine
 Reporting Studio
 Smart Client
 IIoT Services
 IIoT Services communication components

87 | 173
Report Engine

8.1.3 Selection and installation

Report Engine is automatically installed durig a complete installation of the components for Reporting
& GraphQL.

To install the Report Engine only:

1. Select Reporting & GraphQL and click on the Adjust button.
The dialog to customize the installation is opened.
The standard packages have already been pre-selected.
2. Deselect Service Engine.
3. Select Report Engine.
All other required packages are selected automatically.

To install the Reporting Studio only:

1. Deselect all default entries.
2. Activate the Reporting Studio , Metadata Editor and License Management.

Notes:
1. Packages can only be deselected if they are not required by any other package.
Already-installed packages cannot be deselected.
2. If necessary, configure the paths for installation in the Options tab.
3. The computer may be restarted automatically during installation.

8.1.4 Updates
In zenon, you can change to new versions for example, from 10 to 11. Or you can install updates
within a version.
 New versions can be installed in parallel with existing versions. They mainly offer new
features.
 Build updates modify a previously installed version. They mainly fix bugs.

With each setup for new build or new versions, you receive a link to the COPA-DATA website with the
changes between the previous version and the newly-installed one.

BUILD UPDATE
An update only updates those files which are more current than the previously installed files. All
projects and individual settings will remain unchanged. Build updates can contain changes for all
installed components. When calling up the setup, the components that have been changed and the
version to which they have been changed are shown.

88 | 173
IIoT Services

Note: Build updates may have lower quality assurance standards than release versions.

Note: Build updates can only be installed locally. Installation on network paths (UNC) is not possible.

8.1.5 Upgrade information

Note: An upgrade is a higher-level configuration or version. For example, if Analyzer 3.40 or an older
version, and Report Engine 10 or a later version are installed in parallel, this is not an upgrade.

UPGRADE WITHOUT SQL SERVER SWAP

The upgrade can be done through the setup.

Note: Create a backup before upgrading.

UPGRADE WITH SQL SERVER SWAP

To perform an upgrade:
1. Create a backup of the Report Engine version you are using.
2. Reinstall the backup file on a newly installed system with Report Engine 10 or higher.
3. If you want more than just an upgrade (Example: linked servers, users, permissions,...), the
Migration Tool can be used.

8.1.5.1 Database structure

The database structure has been changed to version 12.

9 IIoT Services
In this section you will find information for installing IIoT Services and for the initial setup on Windows
or Docker.

89 | 173
IIoT Services

9.1 Installation
It is recommended to always install the latest IIoT Services release. Existing installations can be upgraded within the recommended update paths (on page
96).

INSTALLATION VARIANTS OF THE IIOT SERVICES

IIoT Services offer the same range of functions in all installation options.

Please note the following differences:

IIoT Services IIoT Services IIoT Services
(Docker on Windows) (Docker on Linux) (Windows native)

Application area  Test environments  Test environments  Test environments

 Productive  Productive environments
environments

Host operating system Windows Linux Windows

Method of installation Configuration files Configuration files As native Windows application via an ISO file.

The installation of the IIoT Services is integrated in the

Setup of the software platform (on page 25).

Internal services Docker services as a Linux Docker services as a Linux Windows Services
container container

Monitoring of internal  Windows  With Shell Windows Management Console.

IIoT Services

IIoT Services IIoT Services IIoT Services

(Docker on Windows) (Docker on Linux) (Windows native)
services PowerShell
No GUI available.
 With GUI via Docker
Dashboard

Minimum number of  1 computer for the  1 computer for the IIoT 1 computer for the IIoT Services and all clients (Windows
computers for test IIoT Services and all Services (Linux host host OS)
environment clients (Windows OS)
host OS)
 1 computer for
clients (Windows
host OS)

Minimum number of  1 dedicated  1 dedicated computer  1 dedicated computer for the IIoT Services.
computers for produtive computer for the for the IIoT Services.
 Separate computers for clients.
environment IIoT Services.
 Separate computers
 Separate computers for clients.
for clients.

Note: The installation options of IIoT Services are basically the same for the administration in the Service Configuration Studio.
IIoT Services

Attention: Fixed user context in "Docker on Windows"

A IIoT Services installation in Docker Desktop for Windows Docker on Windows

is started in a fixed user context.

Example: User A installs IIoT Services using Docker Desktop for Windows.
 User A has access to IIoT Services through their user account.

 User B does not have access to IIoT Services through their user account
on the same computer.

Hint: You can get around this limitation on a test system by using a shared user
account.
IIoT Services

9.1.1 Installation: Standalone vs. parallel vs. virtual machine

In general, it is recommended to install IIoT Services as standalone applications on a dedicated
computer.

STANDALONE INSTALLATION
With a standalone installation, other than IIoT Services, no further zenon services are installed.

Standalone installation is recommended for:

 All installation options of IIoT Services (Docker and Windows native)
 All computer types (physical computer and VMs)
 All uses (test systems and productive systems)

Standalone installation ensures a clear separation of connected communication partners in IIoT

Services networks.

PARALLEL INSTALLATION
In a parallel installation, both IIoT Services as well as other zenon services are installed on the same
computer.

Parallel installation is only recommended for separately documented cases. An example of this is the
test environment in the Getting Started Guide for the IIoT Services (Docker on Windows) installation
option (on page 104).

INSTALLATION ON A VIRTUAL MACHINE

Attention
If you run IIoT Services on a virtual machine with Docker containers: First check
whether AVX commands are supported by the underlying hypervisor.

93 | 173
IIoT Services

9.1.1.1 Build update IIoT Services

As of version 12, IIoT Services versions can also be updated when installing a build update. Updates
are also possible for different builds of a minor release.
In this case, when calling up the setup, an option for an update of the IIoT Services version to the
current version is offered.

Procedure:
 Checkbox for upgrade of IIoT Services is deactivated:
IIoT Services is not updated. They remain in the version already installed on the system.
 Checkbox for upgrading IIoT Services is activated:
 IIoT Services is updated to the current version.
 The task performs a silent installation of the IIoT Services setup without rebooting.
 If the installation is successful, a button for manual reboot is offered at the end.
Do a reboot before starting IIoT Services. This ensures the correct operation of all
services.

Information
An update of the IIoT Services version can only take place in a build update within
the zenon major version.

The following applies for zenon versions 12 and 14: IIoT Services can be updated
up to version 14.3 at the most.

94 | 173
IIoT Services

9.1.2 Steps after installing Windows

For a Windows installation, it is recommended to secure access to the IIoT Services Root Certificate
accordingly. Detailed information on this can be found in the Read authorization for the self-signed
root certificate node.

PROTECT MONGODB FILE AGAINST UNAUTHORIZED CHANGES

The Mongod.cfg file is available to all users, including users without administrator rights.

Attention
When using IIoT Services after a Windows Native installation, the respective
MongoDB file Mongod.cfg must be protected accordingly.

Save the file with a write protection function to reduce the risk of unauthorized
changes.

9.1.3 Kubernetes
In the Docker installation option, the IIoT Services services are installed in Linux containers. This meets
the requirements for operating IIoT Services in a Kubernetes cluster.

In particular, you should note:

 The configuration files docker-compose.yml and .env provided with IIoT Services can be
used as a foundation for creating Kubernetes configuration files.
 You must create customized Kubernetes configuration files for your specific environment.

The following application scenarios are possible:

 self-hosted Kubernetes cluster (on-premise)
 third-party hosted Kubernetes cluster of cloud providers such as Amazon (Amazon
Kubernetes Cluster), Google (Google Kubernetes Engine) or Microsoft (Azure Kubernetes
Service)

By using the Kubernetes container management, you can provide, scale and manage containers
automatically.

Hint
The use of IIoT Services in a Kubernetes cluster requires relevant prior
knowledge and is generally recommended only for enterprise environments.

95 | 173
IIoT Services

9.1.4 Update paths

The following update paths are recommended for IIoT Services:
 Version 2.0 to 2.1
 Version 2.x to 10.0
 Version 10.0 to 10.x
 10.x to higher versions

Available configurations will be automatically carried over during the update. It is recommended to
perform a backup of Persistence Instance before every version update.

9.1.5 Compatibility
The IIoT Services typically connect zenon applications and third-party applications to one another. It
must be ensured that all connected applications are compatible with one another.

The following applies for a IIoT Services installation:

 Install the most recent version of the IIoT Services.
 The IIoT Services version must be at least just as high as the version of the connected zenon
applications.
 All connected zenon applications must be compatible with the installed IIoT Services version.

Information
Backward compatibility:

The IIoT Services support components of the zenon software platform from version
10 and higher.

9.1.5.1 Renaming of Service Grid to IIoT Services

With version 12, the Service Grid and its Services and components were renamed to IIoT Services. The
graphical user interface of the IIoT Services and apps (programs) and the help have been adjusted
accordingly.

96 | 173
IIoT Services

Previous versions up to and including From version 12

11.2

Service Grid IIoT Services

Service Grid Hub Controller Certificate Management

Service Grid API IIoT API

Service Grid Persistence Persistence Service

Service Grid Studio Service Configuration Studio

Service Grid Proxy Proxy Service

Service Grid Gateway IIoT Services Gateway

Service Grid Egress Connector Data Hub Driver

Service Grid Ingress Connector IIoT Services Gateway components.

9.1.5.2 Compatibility of version 12 with previous versions

With version 12, the connection between Engineering Studio project configurations to IIoT Services
and communication between the individual services was simplified.

For existing project configurations in Engineering Studio, it is expressly recommended that the
connections to the IIoT Services and the configuration for individual services are reconfigured.

You can find detailed information on the configuration in the IIoT Services - configuration in
Engineering Studio section.

9.1.5.3 Compatibility of version 11.2 with previous versions

From version 11.2 and higher, the individual services of IIoT Services are addressed using a central
URL. The addressing of services was by means of port numbers in previous versions. The default port
number for IIoT Services is 9443. This port number can be adjusted by means of configuration.

If the central IIoT Services URL is entered in a web browser, Service Configuration Studio starts.

COMPATIBILITY NOTE - IIOT SERVICES 11.2

The following is applicable in order to work seamlessly with a zenon installation with IIoT Services:
 Service Engine or Engineering Studio in version 11 communicate with IIoT Services version
11.2 or higher:

97 | 173
IIoT Services

Build 111398 or higher for Service Engine or Engineering Studio must be installed.
The following configurations must also be updated:
 Service Node Configuration Tool
When entering a Connection setting, add the /hub-controller sub-path to the central
URL.
Example: https://hostname.local/hub-controller
Attention: From version 12, the Service Node Configuration Tool has been replaced
with the IIoT Services Connection Wizard.
 Configuration in Engineering Studio
It is not necessary to specify a subpath for configurations in Engineering Studio. The
same URL is used for Identity Service and Data Storage. Entering the central URL is
sufficient. The URL of the corresponding properties must be configured as URL + port.
Examples:
URL for Identity Service (Network property group, Identity Service, property: URL)
URL for Data Storage (Network property group, Data Storage, property: URL)
hostname.local:9443

9.1.5.4 IIoT Services update

You can migrate a IIoT Services installation to a higher version with little effort.

How to perform an update:

1. Back up the existing Persistence Instance.
2. Stop the IIoT Services.
3. Reinstall IIoT Services in accordance with the installation option.
 IIoT Services (Docker): The ENV file for the new version must be configured with the
necessary values. Afterwards, the IIoT Services are initialized with the
docker-compose.yml.
 IIoT Services (Windows-native): Carry out the setup of the new version.
4. Restart the IIoT Services.

You have now updated the IIoT Services.

98 | 173
IIoT Services

Hint
Existing certificate bundles of an old IIoT Services version are usually compatible
with the new version and do not need to be issued again.

The Persistence Instance with all configurations of the IIoT Services is migrated
automatically.

The backup of the Persistence Instance is a security precaution. This means that a
restore is possible in the event of an error.

9.1.5.5 Update MongoDB

From version 12, the update of MongoDB has been made much simpler for the user. MongoDB
persistence instances can thus be updated to the most recent version that is used by the IIoT Services.
Subsequent change is not possible.

Please also note the Backup and restore – persistence instance node in order to back up your data
before an update.

Note: Ensure that the database version and compatibility version correspond to the supplied
database version if you are using your own database.

UPDATE FOR WINDOWS (NATIVE)

The updating of MongoDB for Windows operating systems is fully integrated into the setup. No
additional manual steps are necessary.

UPDATE FOR DOCKER

With an update of previous versions to version 12.x or version 14.x, the following is necessary:

The following requirements are necessary for updating MongoDB in a Docker environment:
 The tool CopaData.ServiceGrid.Tools.PersistenceManagementCli.exe is installed on the
computer running Docker Desktop for Windows.
 The installation is done by running PersistenceManagementCli.x64.msi.
The data are stored in the following folder:
%programfiles%\zenon\zenon Platform 15\IIoT Services\PersistenceManagementCli.
 The MongoDB Command Line Database Tools are installed.
 The PATH environment variable has been extended with the path to the MongoDB
Command Line database tools (see previous step), e.g.:
C:\Tools\mongodb-database-tools-windows-x86_64-100.7.0\bin

99 | 173
IIoT Services

 The current version of the IIoT Services is installed and running.

 The ENV file with the current settings and the docker-compose .YML file for the new version
are available in their own Windows folder.
 Port 27017 is available on the computer for connecting to the MongoDB database.

RUN UPDATE

In the Docker environment, do the following:

1. Open an elevated PowerShell.
2. Navigate to the storage location of the CLI, e.g. (default path): %programfiles%\zenon\zenon
Platform 15\IIoT Services\PersistenceManagementCli.
3. Enter the following command:
CopaData.ServiceGrid.Tools.PersistenceManagementCli.exe docker upgrade
 The tool starts and guides you through the update process step by step. Necessary
parameters are queried. The update process is continued after the necessary parameters are
entered. In addition, information and a log are displayed directly in the tool.

9.1.5.6 Login to the Identity Service after an update or upgrade

After an update or upgrade of the IIoT Services version, it may happen that logging in to the Identity
Service in the web browser is no longer possible.

In this case, clear the cache of your web browser. In addition, you can call up the login screen in a
private window of the web browser.

9.1.5.7 IIoT Services Gateway

The IIoT Services Gateway connects IIoT Services to zenon applications. It also ensures compatibility
between different release versions.

Information
Generally speaking, you should always use the version of IIoT Services Gateway
that corresponds to the installed version of IIoT Services.

VERSION CHECK
Different versions of IIoT Services and IIoT Services Gateway can communicate with one another on
the basis of a common protocol.

100 | 173
IIoT Services

For communication, a check is carried out to see which version of the protocol is used by the
individual components. The check is successful if all components use the same major version of the
protocol. Minor versions can be different. If the major version is different for a component,
communication is no longer possible.

Example:
 Components with 20.00 can communicate with 20.10.
 Components with 20.10 cannot communicate with 30.10.

9.1.5.7.1 Installation
For the connection between zenon applications and IIoT Services, the appropriate version of the IIoT
Services Gateway must be selected and installed.

The following applications use the IIoT Services Gateway:

 Service Engine
 Engineering Studio
 Report Engine
 Reporting Studio

Important: You must always execute both installers (x86 and x64) on each client. This way, you
ensure that these clients can connect to the IIoT Services.

Tip
Check the installation:

Under Apps and features, the Windows operating system shows a separate
entry for each installed version of the IIoT Services Gateway.

9.1.5.7.2 Configuration

PRIOR CONSIDERATIONS

Several versions of the IIoT Services Gateway can be installed on a computer at the same time. The
system cannot use these versions at the same time however. Only one version of the IIoT Services
Gateway can ever be centrally configured and used.

These processes can install a IIoT Services Gateway:

 Installation of zenon applications via the platform setup.

101 | 173
IIoT Services

 Build update of installed zenon applications.

 Installation of the IIoT Services Gateway via two separate installers (x64 and x86).

In practice, several versions of the IIoT Services Gateway are typically installed on a computer at the
same time.

Hint
Use several versions alternately:

You can use several versions of the IIoT Services Gateway alternately on one
computer. For each change, you must configure the respective required version
of the IIoT Services Gateway manually in zenon6.ini.

DEFAULT CONFIGURATION

By default, zenon applications always connect to IIoT Services via the most-recently-installed version
of the IIoT Services Gateway.

The default configuration covers the usual application purposes and therefore does not generally
need to be adjusted manually by the user.

MANUAL CONFIGURATION

Manual configuration of the IIoT Services Gateway by the user is only required in a few cases.

You can use the manual configuration in the zenon6.ini file to define for your system which version of
the IIoT Services Gateway is used to connect zenon applications to IIoT Services.

General requirement:

Several versions of the IIoT Services Gateway are installed on the computer.

Manual configuration can, for example, be necessary in the following cases:

 Subsequent downgrade of a zenon installation
 Parallel installations of different zenon versions on one computer
 Connection from zenon applications to different versions of the IIoT Services
 The zenon version used does not support the latest version of the IIoT Services Gateway.
 The connection should be established with a current IIoT Services Gateway to the IIoT
Services of an older version.

102 | 173
IIoT Services

Hint
Restart applications and services:

You must restart the following components after manual configuration of the
IIoT Services Gateway:

 All zenon apps connected to the IIoT Services: Service Engine, Engineering
Studio and Reporting Studio
 The Windows service for the Report Engine service node (if you are using
Report Engine): zanMQTTClientxxxx

The new configuration is only effective after restarting these applications and
services.

9.1.5.7.3 Configuration in zenon6.ini

The IIoT Services Gateway is configured centrally in the %cd_system%zenon6.ini file. This setting is
applicable for all zenon applications installed on the computer.

The default configuration is as follows:

[ServiceGridGateway]

Version=LAST

In this configuration, zenon applications connect to the most recent version of the IIoT Services
Gateway that is installed on the computer.

Example of configuration for version 11.0:

[ServiceGridGateway]

Version=11_0

In this example, zenon applications connect to IIoT Services Gateway 11.

SYNTAX

The syntax for manual configuration of the version is "MM_N". The first two figures "MM" define the
version number of the major release. The last figure "N" defines the minor release.

103 | 173
IIoT Services

Hint
Configure the figure for the minor release:

The last figure must always be given, including for major releases, such as IIoT
Services Gateway 11 for example. In this case, you must configure the value
"11_0".

9.2 Getting Started

In this node, you can find detailed information on putting IIoT Services into operation in Windows and
Docker environments.

9.2.1 Getting Started Guide (Windows)

In this node, you will learn how to install IIoT Services on a Windows computer and initially configure
it.

Information
These instructions were written on an operating system in English.

9.2.1.1 System requirements

Please note the system requirements for installing IIoT Services.

GENERAL

You can find information on installation via setup in the Installation and update (on page 8) section in
the Installation (on page 90) node.

REQUIREMENTS

Pay attention to the following points to ensure error-free installation and execution:
 Working internet connection.
 Windows administrator rights.
 Sufficient hardware resources.

Hardware requirements in detail:

104 | 173
IIoT Services

Hardware Minimum requirements Recommended

CPU Dual Core Quad Core

RAM memory 8 GB 8 GB or more.

Storage medium 10 GB 40 GB or more.

You can find the required storage space for further zenon components in the Installation and update
(on page 8) section in the Engineering Studio (on page 18) node.

RECOMMENDED OPERATING SYSTEMS

 Docker on Linux
 Windows 10
 Windows 11

You can find further information on supported operating systems in the Installation and update (on
page 8) section in the Windows operating systems (2/2 (on page 12)) node.

Note: Update your Windows operating system to the latest version.

BROWSER

The following browsers are supported:

 Google Chrome
 Mozilla Firefox
 Microsoft Edge
 Apple Safari

Note: Always use the most recent version of the respective browser.

9.2.1.2 Further requirements

To check your Windows installation, the following requirements must be met:
 An installation of Service Engine and Engineering Studio.
 Make sure that the version of IIoT Services Gateway is installed that corresponds to the
version of IIoT Services to be installed.
 Ensure that this installation is licensed accordingly.

105 | 173
IIoT Services

Info
This installation can be present on a dedicated computer or on the same
computer as the Windows installation.

9.2.1.3 Configure IIoT Services

In this node, you can find further information on the following topics:
1. Install zenon (on page 106)
2. Activate the licenses for IIoT Services (on page 107)
3. Configure IIoT Services (on page 109)
4. Configure HTTPS trust setting
5. Summary and next steps (on page 110)

9.2.1.3.1 Install zenon

Carry out the following steps to install zenon:
1. Open the ISO file.
2. Open the START.exe file in the drive provided.
3. Carry out the further installation steps. Information can be found in the zenon Software
Platform standard installation (on page 25) node and the Configuration and installation (on
page 33) node.
Note: Select IIoT Services in the Components installation step. The License Manager
component is included by default. All other components are optional.

106 | 173
IIoT Services

4. After the necessary restart of the computer, make sure that you mount the ISO file again.
Otherwise the installation will not be carried out correctly.

Note: Do not close the Installation successful window. You still need it to activate the licenses and to
configure IIoT Services .

Attention
If you have nevertheless unintentionally closed the Installation successful
window, you can continue configuration via the Service Configuration Studio
home page and zenon License Manager.

Name Sample values Description

Service https://mycomputer.mydomain You can continue the

Configuration .com:9443 configuration of IIoT Services in
Studio Service Configuration Studio.
System-specific value*

* Replace mycomputer.mydomain.com in the URLs with your computer’s FQDN (on page 122).

9.2.1.3.2 License management of IIoT Services

You have several options for licensing. Use either
 the supplied demo licenses or

107 | 173
IIoT Services

 your own zenon licenses

Here is how you install the demo license (on page 76):
1. Click, in the Installation successful window, in the 1. Activate license for IIoT Services section,
on the Open License Manager button.
2. In the License management window that opens, click on Advanced options.
3. Then click on Advanced license administration.
4. Activate the necessary licenses for Data Hub, IIoT Services API, Identity Service and Asset
modeling. To do this, move the slider to the right. The green background shows that the
license has been activated.
5. Use the arrow buttons to move the activated licenses upwards.
6. Close the dialog by clicking on the Close button.

You can also use your own, pre-existing zenon licenses. You can find information about licensing in
the Licensing node in the Licensing in a few steps node.

108 | 173
IIoT Services

Attention
All zenon components that you use in conjunction with IIoT Services must also
be licensed.

You can find information in relation to this in the Licensing node in the Licensing
components - overview node.

9.2.1.3.3 Create administrator account

You configure the administrator account with the following steps.
1. Click, in the Installation successful window, in the 2. Configure IIoT Services section, on the
Start Configuration button.

Note: In Service Configuration Studio, you can continue the configuration of the platform at
a later point in time by clicking on the Platform Configuration button. The configuration is
continued from the point where it was stopped.
2. In the Platform Configuration window, click on the Get started button.
3. Enter a user name in the Create administrator account window.
4. Enter a password. Note the given password criteria. If the password criteria are adhered to,
the font color changes to green.
5. Enter the password again. If the two entries of the password match, the Create administrator
account button is activated.

6. Click on this button. The creation of the administrator account is thus completed.

109 | 173
IIoT Services

Note: This user is also authorized to configure IIoT Services and to create further users

Attention
Note the password in a secure place. If the password is forgotten, there is no
possibility to retrieve it.

9.2.1.3.4Summary and first steps

Here you can find a summary with the installation details as well as a note about the next steps.

You can use the arrow keys to switch the view in the dialog, in order to display additional,
topic-specific information. On each page of the summary, the topic displayed is linked to the zenon
Help.

The following views are available:

1. Summary of the installation
2. Trust relationship via HTTPS certificate
3. Connection of zenon projects to IIoT Services
4. Connection of zenon Report Engine to IIoT Services
5. Manage users and groups from the IIoT Services Identity Service
6. Manage zenon installations using Device Management

110 | 173
IIoT Services

Tip
Create the link for Service Configuration Studio as a bookmark in your browser.

Name Sample values Description

Service Configuration https://mycomputer.mydomain.co In Service Configuration Studio, only

Studio m:9443 users with administrator rights can
fully administer the IIoT Services.
System-specific value*

* Replace mycomputer.mydomain.com in the URLs with your computer’s FQDN (on page 122).

9.2.1.4 Configuration
In this node, you can find information on setting up the following components:
1. Engineering Studio
2. Service Engine
3. IIoT API

9.2.1.4.1 Engineering Studio

The connections must be configured beforehand in order for Engineering Studio and Service Engine
to be able to communicate with IIoT Services.

9.2.1.4.2 Connection to IIoT Services

CREATE CONNECTION FOR A PROJECT

To do this, carry out the following steps:
1. Highlight the project in Engineering Studio.
2. Go to the Network node in the project properties.
3. Go to property group IIoT Services settings.
4. Activate the Activate IIoT Services checkbox.
This activates the configuration of the IIoT Services connection settings property as well as
the ... button.
5. Click on the ... button . The IIoT Services Connection Wizard is started.
6. Enter the URL of your IIoT Services installation and follow the instructions in the wizard.

111 | 173
IIoT Services

Skip the step for Report Engine.

7. Once the IIoT Services Connection Wizard has been successfully configured, you will find the
used IIoT Service URL and the Client-ID in the input field of the connection settings.

Note: You can find further information on the IIoT Services Connection Wizard in the IIoT Services
Connection Wizard node in the Welcome section.

9.2.1.4.3 Configure variables

In order to use variables in IIoT Services, they must be configured for it in Engineering Studio.

Only variables with simple data type are supported.

To configure variables:
1. Select the desired variable.
2. Open the Authorization/eSignature group in the properties.
3. Switch to the IIoT Services settings subgroup.
4. Configure the variable for use in IIoT Services.

Configurable properties:
Access permission

Access right of a variable in IIoT Services. Select from drop-down list:

 None: Variable is not available in IIoT Services.
 Read-only: IIoT Services has read access to this variable.
 Read-write: IIoT Services have read and write access to this variable.

Note: For reasons of security, access permission should only be set to the extent that they are
actually required.

9.2.1.4.4Starting Service Engine

Start Service Engine after configuration:
1. Save the project with all the changes.
2. Click on the Generate changed Service Engine files button.
3. Click on the Start Service Engine button.

112 | 173
IIoT Services

9.2.1.4.5 Identity Management

In Identity Management, you administer users, groups, resources and privileges.

Assign the Administrator user the right to access Service Engine via IIoT Services.

To do this, follow the instructions in the following chapters.

9.2.1.4.6Creating a group and adding users

To create a user group:
1. Navigate in Service Configuration Studio to the Identity Management menu item.
2. Click on the Groups submenu.
3. Click on the Add Group button.
4. Assign the group name Users.
5. Click on Add.

The Users user group has been created.

To add a user to the Users user group:

1. Select the Users group.
2. Click on the Add user button.

113 | 173
IIoT Services

3. Select the Administrator user.

Note: The Administrator user is displayed in the list as admin admin (first name; last name).
4. Click on Add.

You have thus added the Administrator user of the Users user group.

9.2.1.4.7 Add resource and add role

To add the Service Engine resource to the Users user group:
1. Ensure that Service Engine has been started.
2. Navigate in Service Configuration Studio to the Identity Management menu item.
3. Click on the Access Control submenu.
4. Select the Users user group under Groups.
5. Click on the Add Resources button.
6. Select your project in the overview.
7. Click on the Add button.

You have thus added the resource to the Users user group.

To assign the necessary role to the resource:

1. Click on the ... button under Assigned Resources .
2. Select Manage roles.
3. Select the following permission: Data Read.
4. Click on the Submit button.

You have thus assigned the necessary role to the resource. Tthe Administrator user can access the
released variables in Service Engine via IIoT API.

114 | 173
IIoT Services

9.2.1.4.8 IIoT API

In Service Configuration Studio, you access the IIoT API as a user. With the IIoT API, you can retrieve
data from the IIoT Services.

There are two possibilities:

 For test purposes, you access the IIoT API manually in Service Configuration Studio.
 In a productive environment, a client application automatically accesses the IIoT API. To do
this, you need an accordingly programmed 3rd party application.

9.2.1.4.9User authorization
For a manual query using the IIoT API, you must authorize yourself. To authorize a user in the IIoT
API:
1. Ensure that Service Engine has been started.
2. Open the Service Configuration Studio.
3. Go to the IIoT API button.

115 | 173
IIoT Services

4. Click on the green Authorize button. A window opens.

Note: You are not authorized by default. The icon shows an opened lock.
5. Ensure that the value for the client_id field is set to swagger_demo_api.
6. Activate the following checkboxes:
 iiotServicesAPI
 dataStorageAPI
Note: You thus determine the scope of the application.
7. Click on the Authorize button.
8. After successful authorization, the system shows the message Authorized.
9. Click on the Close button. Authorization remains active.
Note: If you are authorized, you will see the locked icon.

Info
You can find the complete list of IIoT API error codes in the Troubleshooting
node in the IIoT API error codes node.

9.2.1.4.10 Test 1: Query available project

With this test, you check to see which projects you can use in Service Engine.

116 | 173
IIoT Services

SELECT ENDPOINT
1. Ensure that Service Engine has been started.
2. Start Service Configuration Studio.
3. Go to the IIoT API button.
4. Ensure that the user authorization for the IIoT API (on page 115) is available.
5. Check whether the value REST v1.0 is set as API version in the header.
6. Go to the DataSourcesApi category.
7. Go within the category to the line with the /api/v1/datasources endpoint.

You must configure this endpoint for the following query.

117 | 173
IIoT Services

QUERY PROJECT
1. Click on the blue GET button in the line. This expands the endpoint.
2. Click on the Try it out button.
3. Click on the Execute button.
4. Copy the dataSourceId into a text file. You need this value for the following test.
Note: It is identical to the project ID of your project.

RESULT
The query shows the available project.

Note: Ensure that the project is in the Online state.

Note for programmers

Code sample: Response body

{
"dataSources": [
{
"name": "ZENON14_DEMO",
"dataSourceId": "d3058681-c6a8-4b2e-908d-610676fce605",
"state": "Online"
}
]
}

9.2.1.4.11 Test 2: Query available variables and variable values

With this test, you will access the variables and variable values enabled in the zenon project via IIoT
Services.

OPEN ENDPOINT
1. Ensure that Service Engine is running.
2. Ensure that the user authorization for the IIoT API (on page 115) has been carried out.
3. Start Service Configuration Studio.
4. Go to the IIoT API menu item.
5. Check whether the value REST v1.0 is set as API version in the header.

118 | 173
IIoT Services

6. Go to the Variables API category.

7. Go to the the line with the /api/v1/datasources/{dataSourceId}/variables/query} endpoint.

You must configure the query in this endpoint.

CONFIGURE QUERY
1. Click on the green Post button.
2. Click on the Try it out button. You have thus activated the input field for the dataSourceId.
3. Enter the dataSourceId (identical to the zenon project ID).
Note: You have thus defined the target project for the query. (Example: Initial query (on
page 121))
4. Change the following points in the Query specification:
a) fields: Replace the predefined "string" with "name", "value".
You thus define the data fields for the query.
b) nameFilter: Replace the predefined "string" with "*".
You use this placeholder to query all values unfiltered. (Example: custom query (on page
121))
5. Then click on Execute to perform the query.
6. The query is acknowledged as follows: "Code 200" "Ok. Returns the queried variables.”
7. The "Response body" section shows the query result. (Example: query result (on page 122)).

119 | 173
IIoT Services

The query result shows the released variables and their variable values from the specified zenon
project.

9.2.1.4.12 Query specifications

You can find the query specifications in this section.

120 | 173
IIoT Services

9.2.1.4.13 Initial query

Code Sample:
{
"fields": [
"string"
],
"nameFilter": {
"variableNames": [
"string"
]
}}
Initial query

9.2.1.4.14 Custom query

Code Sample:
{
"fields": [
"name", "value"
],
"nameFilter": {
"variableNames": [
"*"
]
}}
Query of variables and variable values

121 | 173
IIoT Services

9.2.1.4.15 Query result

Code Sample:
{
"variables": [
{
"name": "MY_VARIABLE",
"value": "1"
}
]
}
The shared variable and the variable value are in the "Response body" section.

9.2.1.5 Appendix
In this node, you can find further information on the following topics:
1. Determine FQDN (on page 122)
2. Monitoring services (on page 122)
3. Test environment vs. productive environment (on page 123)

9.2.1.5.1 Determine Fully Qualified Domain Name

To determine the FQDN of the Windows computer:
1. Open the Command Prompt app via the Windows search function.
2. Enter the ipconfig /all command.
3. In the Command Prompt, you will find the lines Hostname and Primary DNS suffix of your
computer.
4. Join the hostname and the primary DNS suffix together with a dot to determine the FQDN.
Example: computer-name100.companyname.internal.
You have thus determined the FQDN.

9.2.1.5.2 Monitor services

All services in IIoT Services are automatically started by the operating system. Use the following steps
to check the status of IIoT Services services:
1. Open the Command Prompt app via the Windows search function.

122 | 173
IIoT Services

2. Enter services.msc.
3. Confirm the entry with Enter. This then opens the console for the administration of services.
4. You can find the services at: zenon and service names.
5. All zenon services must in principle be in running state.
Note: Data Storage can also be in exited status if it is not being used.

9.2.1.5.3 Test environment vs. productive environment

The test environment described in this guide is quicker and easier to set up than a typical productive
environment.

The basic differences are:

Test environment Productive environment

Installation option  IIoT Services  IIoT Services (Windows native)

(Windows native)
 IIoT Services (Docker on Linux)

Number of  A computer for IIoT  A computer for IIoT Services

computers Services and all clients
 Dedicated computers for clients

Network topology All applications run on the The applications run on different
same computer. computers.

The computers can be distributed over

different remote locations.

Passwords It is possible to use For all logins, it is essential that you assign
predefined passwords in a your own secure passwords.
protected test environment.

9.2.2 Getting Started Guide (Docker)

This guide describes how you install and initially configure the IIoT Services on the Docker
containerization software. It explains the installation of IIoT Services on Docker for Windows. It can
also be used for Docker for Linux and other container solutions such as Podman or Kubernetes.

The container images supplied by COPA-DATA are based on Linux and can be run on Docker for
Windows as well as on Docker for Linux and other container platforms.

The target group is users who have little or no experience with Docker.

123 | 173
IIoT Services

Info
These instructions were written on an operating system in English.

9.2.2.1 System requirements

Note the following system requirements to install IIoT Services:
 General
Docker, Engineering Studio and Service Engine are installed on one computer.
 Browser
The following browsers are supported:
 Google Chrome
 Mozilla Firefox
 Microsoft Edge
 Apple Safari
Note: Always use the most recent version of the respective browser.
 Storage space
For the installation of IIoT Services, at least 6 GB of free storage space is required on the
storage medium.
You can find the required storage space for further zenon components in the Installation and
update (on page 8) section in the Engineering Studio (on page 18) node.

 Requirements
Ensure that the following points have been met:
 Sufficient resources for the smooth operation of all installed applications (CPU, RAM,
storage space).
 The CPU must support hardware virtualization.
 CPU hardware virtualization must be activated in the BIOS.
 Working internet connection.
 Ensure that you have Windows administrator rights on the computer.

9.2.2.2 Further requirements

To check your Docker installation, the following requirements must be met:

124 | 173
IIoT Services

 An installation of Service Engine and Engineering Studio.

 Ensure that the version of IIoT Services Gateway is installed that corresponds to the version of
IIoT Services to be installed.
 Ensure that this installation is licensed accordingly.

Information
In this guide, the entire installation is carried out on one computer.

Attention
If you run IIoT Services on a virtual machine with Docker containers:

First check whether AVX commands are supported by the underlying hypervisor.

9.2.2.3 System architecture

In this guide, the entire installation is carried out on one computer. This includes Service Engine and
Engineering Studio as a native Windows installation and at the same time IIoT Services as a Docker
installation.

Note: You can obtain the container images from Docker Hub (https://hub.docker.com/u/copadata).

SHORT DESCRIPTION OF DOCKER

Docker is a technology for the container-based execution of software applications. The applications
run in containers independently of the host operating system. The container images supplied by
COPA-DATA are based on the Linux operating system. Thanks to the Windows Subsystem for Linux 2
(WSL 2), such Linux containers can also be executed on a Windows host operating system.

The Hyper-V hardware visualization layer from Microsoft hosts the Windows operating system and
the Windows Subsystem for Linux 2 (WSL 2).

125 | 173
IIoT Services

9.2.2.3.1 Installation of Docker for Windows

Before you can install the IIoT Services for Docker on a Windows host system, you must first install
Docker for Windows and the Windows Subsystem for Linux (WSL) 2 from Microsoft. Proceed in the
following way:
1. Ensure that hardware virtualization (on page 145) is activated for the CPU.
2. Configure an elevated PowerShell (on page 145). The is a PowerShell with administrator
rights. You can use it to subsequently initialize and administer IIoT Services.
3. Download the current version of Docker for Windows from the Docker manufacturer’s web
site (docker.com) (https://www.docker.com/).
4. Install Docker for Windows with the WSL2 engine.
5. Follow the link shown to https://aka.ms/wsl2kernel.
6. Download the WSL2 Linux kernel update package for x64 machines.
7. Install the update package
8. Start Docker for Windows.
9. Check whether Docker has been configured for the use of Linux containers. This is the default
setting of Docker.

9.2.2.4 Basic configuration of ENV file

In order to install IIoT Services, you must adapt the ENV file supplied by COPA-DATA. You will find
this file in a package that you can download from the COPA-DATA website.

You can download the configuration files for IIoT Services from the COPA-DATA
(https://www.copadata.com/en/downloads/product-downloads/) website.

The following content of the download is relevant for putting it into operation:
 IIoT Services configuration files: .env and docker-compose.yml
 One PDF file: IIoT Services

To download the configuration files:

1. Go to the COPA-DATA (https://www.copadata.com/en/downloads/product-downloads/)
website.
2. You must log in to the COPA-DATA website with your user account for this download.
Registration is free.
3. Then filter for IIoT Services in Select Category
4. Download the ZIP file with the appropriate version of IIoT Services (Docker).

126 | 173
IIoT Services

Carry out the following steps to configure the ENV file:

1. Create a working directory. This is used to store the Docker configuration files.
Note: Under Windows, you can use C:\iiot-servicesas the working directory.
Note: Under Linux, you can use /home/<user>/iiot-servicesas the working directory.
2. Unzip the ZIP file into your working directory. There you will find the ENV file.
3. Open the ENV file with a text editor.
4. Enter the values for the corresponding configuration entries in the ENV file.
5. Save the changes.
6. Check whether the .env file still contains the leading period (".").
Note: Some file operations in the Windows operating system can remove the dot. In this
case, rename the file from "env" to ".env".

CONFIGURE ENV FILE

The following entries are necessary for the configuration of the ENV file.
Entry Sample values Description

Datenbank

Persistence_Username= iiot_user You can choose the usernames

yourself.

Persistence_Password= iiot_Changeme123! You can define the password

yourself.

Note: Note the minimum

password requirements!

Persistence_Uri= Optional entry; is not needed

Machine settings

MACHINE_HOSTNAME= mycomputer.mydomain.com Frequent configuration errors

on MACHINE HOSTNAME are:
System-specific value:
 Use of capital letters
 Determine the FQDN
host name of your
Windows computer. (To
do this, use the
command line command
ping localhost)

 FQDN must be entered

127 | 173
IIoT Services

Entry Sample values Description

in continuous lowercase
letters.

9.2.2.5 Commissioning
Once you have entered the configuration values into the ENV file, you can initialize IIoT Services.

To do this, carry out the following steps:

1. Download Docker images (on page 128)
2. Initialize IIoT Services (on page 128)
3. Start and monitor services

9.2.2.5.1 Download Docker images

Carry out the following steps to download the Docker images:
1. Start Docker.
2. Ensure that the ENV file (on page 126) has been fully configured.
3. Open the elevated PowerShell. (Windows) or a terminal (Linux).
4. Change to your working directory where you have saved the Docker configuration files.
5. Download the containers with the command.
docker compose pull
This downloads the images from hub.docker.com (https://hub.docker.com/u/copadata).

9.2.2.5.2 Initialize IIoT Services

Then carry out the following steps to initialize IIoT Services:
1. Start the containers with the command
docker compose up -d
2. Windows only: If necessary, confirm the Windows firewall enable for IIoT Services.
Note: The firewall blocks the services until they are approved. This can lead to timeouts. The
initialization will fail as a result. In this case, you must restart the initialization.
3. Check if all containers are in the Running state.
docker ps -a

128 | 173
IIoT Services

Note: Under Windows, you can also check the state of the container in the Docker
Dashboard.

9.2.2.5.3 Installation of Docker for Linux

In this section, you can find brief instructions for the installation of Docker for Ubuntu.
1. Install Docker.
2. To do this, follow the detailed installation instructions on the provider's website
(https://docs.docker.com/engine/install/ubuntu/).
 Information about other distributions is also available on this website.
 Keep in mind the requirements for installation.
 Configure your computer. To do this, follow the further instructions in this Getting Started
Guide.

9.2.2.6 Configure IIoT Services

In this section, you will find information on the following topics:
1. Create administrator account (on page 129)
2. Summary and next steps (on page 131)

9.2.2.6.1 Create administrator account

After the first installation of the IIoT Services, use the following steps to configure the administrator
account.
1. Open the following address in the browser https://mycomputer.mydomain.com:9443 and
follow the steps set out.

129 | 173
IIoT Services

2. In the Platform Configuration window, click on the Get started button.

3. Enter a user name in the Create administrator account window.
4. Enter a password. Note the given password criteria. If the password criteria are adhered to,
the font color changes to green.
5. Enter the password again. If the two entries of the password match, the Create administrator
account button is activated.

6. Click on this button. The creation of the administrator account is thus completed.

Note: This user is also authorized to configure IIoT Services and to create further users

Attention
Note the password in a secure place. If the password is forgotten, there is no
possibility to retrieve it.

130 | 173
IIoT Services

9.2.2.6.2 Summary and next steps

Here you can find a summary with the installation details as well as a note about the next steps.

You can use the arrow keys to switch the view in the dialog, in order to display additional,
topic-specific information. On each page of the summary, the topic displayed is linked to the zenon
Help.

The following views are available:

1. Summary of the installation
2. Trust relationship via HTTPS certificate
3. Connection of zenon projects to IIoT Services
4. Connection of zenon Report Engine to IIoT Services
5. Manage users and groups from the IIoT Services Identity Service
6. Manage zenon installations using Device Management

Tip
Create the link for Service Configuration Studio as a bookmark in your browser.

Name Sample values Description

Service Configuration https://mycomputer.mydomain.co In Service Configuration Studio, only

Studio m:9443 users with administrator rights can
fully administer the IIoT Services.
System-specific value*

* Replace mycomputer.mydomain.com in the URLs with your computer’s FQDN (on page 122).

131 | 173
IIoT Services

9.2.2.7 Configuration
In this section, you will find information for setting up the following components:
1. Engineering Studio
2. Service Engine
3. IIoT API

9.2.2.7.1 Engineering Studio

The connections must be configured beforehand in order for Engineering Studio and Service Engine
to be able to communicate with IIoT Services.

9.2.2.7.2 Connection to IIoT Services

CREATE CONNECTION FOR A PROJECT

To do this, carry out the following steps:
1. Highlight the project in Engineering Studio.
2. Go to the Network node in the project properties.
3. Go to property group IIoT Services settings.
4. Activate the Activate IIoT Services checkbox.
This activates the configuration of the IIoT Services connection settings property as well as
the ... button.
5. Click on the ... button . The IIoT Services Connection Wizard is started.
6. Enter the URL of your IIoT Services installation and follow the instructions in the wizard.
Skip the step for Report Engine.
7. Once the IIoT Services Connection Wizard has been successfully configured, you will find the
used IIoT Service URL and the Client-ID in the input field of the connection settings.

Note: You can find further information on the IIoT Services Connection Wizard in the IIoT Services
Connection Wizard node in the Welcome section.

9.2.2.7.3 Configure variables

In order to use variables in IIoT Services, they must be configured for it in Engineering Studio.

132 | 173
IIoT Services

Only variables with simple data type are supported.

To configure variables:
1. Select the desired variable.
2. Open the Authorization/eSignature group in the properties.
3. Switch to the IIoT Services settings subgroup.
4. Configure the variable for use in IIoT Services.

Configurable properties:
Access permission

Access right of a variable in IIoT Services. Select from drop-down list:

 None: Variable is not available in IIoT Services.
 Read-only: IIoT Services has read access to this variable.
 Read-write: IIoT Services have read and write access to this variable.

Note: For reasons of security, access permission should only be set to the extent that they are
actually required.

9.2.2.7.4 Starting Service Engine

Start Service Engine after configuration:
1. Save the project with all the changes.
2. Click on the Generate changed Service Engine files button.
3. Click on the Start Service Engine button.

133 | 173
IIoT Services

9.2.2.7.5 Identity Management

In Identity Management, you administer users, groups, resources and privileges.

Assign the Administrator user the right to access Service Engine via IIoT Services.

To do this, follow the instructions in the following chapters.

9.2.2.7.6 Creating a group and adding users

To create a user group:
1. Navigate in Service Configuration Studio to the Identity Management menu item.
2. Click on the Groups submenu.
3. Click on the Add Group button.
4. Assign the group name Users.
5. Click on Add.

The Users user group has been created.

To add a user to the Users user group:

1. Select the Users group.
2. Click on the Add user button.

134 | 173
IIoT Services

3. Select the Administrator user.

Note: The Administrator user is displayed in the list as admin admin (first name; last name).
4. Click on Add.

You have thus added the Administrator user of the Users user group.

9.2.2.7.7 Add resource and add role

To add the Service Engine resource to the Users user group:
1. Ensure that Service Engine has been started.
2. Navigate in Service Configuration Studio to the Identity Management menu item.
3. Click on the Access Control submenu.
4. Select the Users user group under Groups.
5. Click on the Add Resources button.
6. Select your project in the overview.
7. Click on the Add button.

You have thus added the resource to the Users user group.

To assign the necessary role to the resource:

1. Click on the ... button under Assigned Resources .
2. Select Manage roles.
3. Select the following permission: Data Read.
4. Click on the Submit button.

You have thus assigned the necessary role to the resource. Tthe Administrator user can access the
released variables in Service Engine via IIoT API.

135 | 173
IIoT Services

9.2.2.7.8 IIoT API

In Service Configuration Studio, you access the IIoT API as a user. With the IIoT API, you can retrieve
data from the IIoT Services.

There are two possibilities:

 For test purposes, you access the IIoT API manually in Service Configuration Studio.
 In a productive environment, a client application automatically accesses the IIoT API. To do
this, you need an accordingly programmed 3rd party application.

9.2.2.7.9 User authorization

For a manual query using the IIoT API, you must authorize yourself. To authorize a user in the IIoT
API:
1. Ensure that Service Engine has been started.
2. Open the Service Configuration Studio.
3. Go to the IIoT API button.

136 | 173
IIoT Services

4. Click on the green Authorize button. A window opens.

Note: You are not authorized by default. The icon shows an opened lock.
5. Ensure that the value for the client_id field is set to swagger_demo_api.
6. Activate the following checkboxes:
 iiotServicesAPI
 dataStorageAPI
Note: You thus determine the scope of the application.
7. Click on the Authorize button.
8. After successful authorization, the system shows the message Authorized.
9. Click on the Close button. Authorization remains active.
Note: If you are authorized, you will see the locked icon.

Info
You can find the complete list of IIoT API error codes in the Troubleshooting
node in the IIoT API error codes node.

9.2.2.7.10 Test 1: Query available project

With this test, you check to see which projects you can use in Service Engine.

137 | 173
IIoT Services

SELECT ENDPOINT
1. Ensure that Service Engine has been started.
2. Start Service Configuration Studio.
3. Go to the IIoT API button.
4. Ensure that the user authorization for the IIoT API (on page 115) is available.
5. Check whether the value REST v1.0 is set as API version in the header.
6. Go to the DataSourcesApi category.
7. Go within the category to the line with the /api/v1/datasources endpoint.

You must configure this endpoint for the following query.

138 | 173
IIoT Services

QUERY PROJECT
1. Click on the blue GET button in the line. This expands the endpoint.
2. Click on the Try it out button.
3. Click on the Execute button.
4. Copy the dataSourceId into a text file. You need this value for the following test.
Note: It is identical to the project ID of your project.

RESULT
The query shows the available project.

Note: Ensure that the project is in the Online state.

Note for programmers

Code sample: Response body

{
"dataSources": [
{
"name": "ZENON14_DEMO",
"dataSourceId": "d3058681-c6a8-4b2e-908d-610676fce605",
"state": "Online"
}
]
}

9.2.2.7.11 Test 2: Query available variables and variable values

With this test, you will access the variables and variable values enabled in the zenon project via IIoT
Services.

OPEN ENDPOINT
1. Ensure that Service Engine is running.
2. Ensure that the user authorization for the IIoT API (on page 115) has been carried out.
3. Start Service Configuration Studio.
4. Go to the IIoT API menu item.
5. Check whether the value REST v1.0 is set as API version in the header.

139 | 173
IIoT Services

6. Go to the Variables API category.

7. Go to the the line with the /api/v1/datasources/{dataSourceId}/variables/query} endpoint.

You must configure the query in this endpoint.

CONFIGURE QUERY
1. Click on the green Post button.
2. Click on the Try it out button. You have thus activated the input field for the dataSourceId.
3. Enter the dataSourceId (identical to the zenon project ID).
Note: You have thus defined the target project for the query. (Example: Initial query (on
page 121))
4. Change the following points in the Query specification:
a) fields: Replace the predefined "string" with "name", "value".
You thus define the data fields for the query.
b) nameFilter: Replace the predefined "string" with "*".
You use this placeholder to query all values unfiltered. (Example: custom query (on page
121))
5. Then click on Execute to perform the query.
6. The query is acknowledged as follows: "Code 200" "Ok. Returns the queried variables.”
7. The "Response body" section shows the query result. (Example: query result (on page 122)).

140 | 173
IIoT Services

The query result shows the released variables and their variable values from the specified zenon
project.

9.2.2.7.12 Query specifications

You can find the query specifications in this section.

141 | 173
IIoT Services

9.2.2.7.13 Initial query

Code Sample:
{
"fields": [
"string"
],
"nameFilter": {
"variableNames": [
"string"
]
}}
Initial query

9.2.2.7.14 Custom query

Code Sample:
{
"fields": [
"name", "value"
],
"nameFilter": {
"variableNames": [
"*"
]
}}
Query of variables and variable values

142 | 173
IIoT Services

9.2.2.7.15 Query result

Code Sample:
{
"variables": [
{
"name": "MY_VARIABLE",
"value": "1"
}
]
}
The shared variable and the variable value are in the "Response body" section.

9.2.2.8 Appendix
Here you can find information on the following topics:
1. Test environment vs. productive environment (on page 143)
2. Determine FQDN (on page 122)
3. Check CPU hardware virtualization (on page 145)
4. Elevated PowerShell (on page 145)

9.2.2.8.1 Test environment vs. productive environment

The test environment described in this guide is easier to set up than a typical productive environment.

The fundamental differences are:

Test environment Productive environment

Installation option IIoT Services (Docker on  IIoT Services (Windows native)

Windows)  IIoT Services (Docker on Windows)

Number of A computer for IIoT Services  A computer for IIoT Services

computers and all clients  Dedicated computers for clients

Network topology All applications run on the The applications run on different computers.
same computer.
The computers are usually distributed across
different remote sites.

Multi-user system Not suitable as a multi-user Suitable as a multi-user system.

143 | 173
IIoT Services

Test environment Productive environment

system.

Passwords It is possible to use predefined For all logins, it is essential that you assign
passwords in a protected test your own secure passwords.
environment.

9.2.2.8.2 Installation options for IIoT Services

Here you can find an overview of the different types of installation of IIoT Services, as well as the
instructions that you can use for the installation.
Type of installation Instruction

Windows on-premises installation Getting started guide - Windows (on page 104)

Installation of Docker on Windows Follow the instructions in this guide (on page 126)

Installation of Docker on Linux Follow the instructions in this guide (on page 129)

Docker in the cloud Follow the basic steps in this guide and adapt the
configuration files for your preferred cloud platform.

Kubernetes Follow the basic steps in this guide and adapt the
configuration files for Kubernetes.

9.2.2.8.3 Determine Fully Qualified Domain Name

To determine the FQDN of the Windows computer:
1. Open the Command Prompt app via the Windows search function.
2. Enter the ipconfig /all command.
3. In the Command Prompt, you will find the lines Hostname and Primary DNS suffix of your
computer.
4. Join the hostname and the primary DNS suffix together with a dot to determine the FQDN.
Example: computer-name100.companyname.internal.
You have thus determined the FQDN.

144 | 173
IIoT Services

9.2.2.8.4 Check CPU hardware virtualization

To check whether the CPU hardware virtualization has been activated:
1. Open the Task-Manager.
2. Click on the Performance tab.
3. Go to the CPU category there.
4. If your system is correctly configured, you will find the Virtualization: Enabled entry under the
CPU graph.

9.2.2.8.5 Elevated PowerShell

An elevated PowerShell is a PowerShell with administrator rights. You can use it to subsequently
initialize and administer IIoT Services.

To create an elevated PowerShell:

1. Make sure that you have Windows administrator privileges on the test computer.
2. Create this link to your
desktop:%SystemRoot%\system32\WindowsPowerShell\v1.0\powershell.exe

145 | 173
Smart Server & Smart Client

3. Right-click on the link to open the context menu.

4. Select the Run as Administrator option.
5. The elevated PowerShell is started.

10 Smart Server & Smart Client

The necessary components for the installation are included in the platform setup (on page 25).
1. Start the setup.
2. Follow the procedure until you reach the Components (on page 27) dialog.
3. In this dialog, select the desired subcomponents for the Smart Client component.
4. Click on Customize to define the subcomponents in detail.
The dialog for selecting the components to be installed is displayed.
5. Select the appropriate subcomponents for the installation.
6. Click on Install to start the installation process.

Detailed information on the configurations required to operate the Smart Server and the Smart Client
can be found in the Commissioning Smart Server and Smart Client section.

11 Web Visualization Service

The components required for the operation of the Web Visualization Service are included in the
platform setup.
 You can find general information on WVS in the Web Visualization Service node.
 You can find detailed information for the commissioning and configuration necessary for this
in the Infrastructure node in the Web Visualization Service (WVS) section.

12 HTML Web Engine

You can find information on putting the HTML Web Engine into operation in the Infrastructure node
in the HTML Web Engine section.

146 | 173
Service Engine for Docker- installation and operation

13 Service Engine for Docker- installation and operation

In this section, you can find information for setting up Service Engine components in a Docker
environment.

13.1 General
The Service Engine is available as an Ubuntu and Debian based Docker image. These images contain
both the Service Engine and Logic Service components.

Available images:
 amd64 architecture
 arm64 architecture

This guide describes how to install Service Engine using a Docker environment. Service Engine can
also be used on other container environments, e.g. kubernetes.

13.2 System requirements

Usage in a container environment requires a Docker installation. To install Docker on your device,
follow the instructions on the official Docker website (https://docs.docker.com/engine/install/).

Attention
Make sure to select the correct operating system for the Docker installation

13.3 Configuration & Operation

Follow these steps to start-up Service Engine and its components in a Docker environment:
1. For easy installation, download the data provided from the COPA-DATA website
(https://productdownloads.copadata.com/en/product-downloads/). Please note that login is
required to download.
2. Copy the docker-compose folder included in the download package to the target device on
which you want to run the Service Engine as a Docker container.
The docker-compose folder already contains two directories: data and logs.
 Folder data
The data folder contains the zenon6.ini file. The zenon6.ini file defines the start function
parameter of Service Engine.

147 | 173
Service Engine for Docker- installation and operation

Note: The storage location can be configured in the .env file with the CONFIG_PATH=
entry.
 Folder logs
The logs folder is empty. This is the location of the LOG files created by the Diagnosis
Server when running in Service Engine.

Note: The storage location can be configured in the .env file with the LOGGING_PATH=
entry.
3. Configure the .env file entries:
 Specify the appropriate license series and license server for the components used. The
license function parameters are configured in the .env file with the following entries:
 - RUNTIME_LICENSE_SERIAL=
Serial number of Service Engine.
- RUNTIME_LICENSE_SERVER=
License Server address for Service Engine.
- PROCESSGATEWAY_LICENSE_SERIAL=

Serial number of Process Gateway(s).

- PROCESSGATEWAY_LICENSE_SERVER=
License Server address for the Process Gateway(s).
- LOGIC_LICENSE_SERIAL=

Serial number of the Logic Service.

- LOGIC_LICENSE_SERVER=
License Server address for the Logic Service.
4. zenon project data:
a) Create the Service Engine files for your project, in Engineering Studio.
b) Copy the contents of the Service Engine folder folder to the data directory.
c) Adapt the zenon6.ini file entries in the data directory to your project:
[PATH]

VBF30=/etc/copa-data/[Project name]

[Default]

DEFANWENDUNG30=[Project name]
5. Pull and start the Service Engine with the docker compose up command.
6. After initialization, you will see a running Service Engine container and a running Logging
Server container.

148 | 173
Service Engine for Docker- installation and operation

7. In the Getting Started (on page 104) section, you can find detailed information about putting
IIoT Services into operation as additional components in a container environment.

Information
If additional ports are required for the specific project, e.g. ports for drivers or
process gateways, add them to the list of forwarded ports in the
docker-compose.yml file before starting the Service Engine container.

13.4 Logging of Service Engine in container environment

In this section, you will find information about logging and connecting to the Diagnosis Viewer of the
zenon software platform.

DOCKER LOGS

You can see the LOGs in the command line output or with the docker logs service-engine command.
If your zenon project contains a zenon Logic project and the Docker container is configured to listen
on port 1200, you can also connect to Logic Studio using Logic Service via local port 1200. If Service
Engine cannot find the configured license or project, corresponding LOG entries are created. In this
case, the Service Engine will be terminated.

DIAGNOSIS VIEWER

To check Service Engine logs, use the Diagnosis Viewer. Connect the Diagnosis Viewer to the zenon
Diagnosis Server, which runs alongside Service Engine in a separate Docker container.

 Use the localhost and port 50780.

 You might need to stop the zenon Diagnosis Server on your local machine before connecting
to the Docker-based Logging Server.

13.5 docker-compose.yml
The docker-compose.yml file is the configuration file that is interpreted by the Docker environment.
This section provides information on manual adjustments to operate your Service Engine to run in a
Docker environment.

Two packages are offered for download in the download area of the COPA-DATA web site
(https://productdownloads.copadata.com/en/product-downloads/). Both packages contain a
corresponding docker-compose.yml file:
 Service Engine for Docker and use of the Device Agent of the Device Management in IIoT
Services:

149 | 173
Service Engine for Docker- installation and operation

docker-compose.yml file contains configured volumes.

 Service Engine for Docker without use of the Device Agent of the Device Management in IIoT
Services:
docker-compose.yml file is configured with Bind mounts.

Information
It is strongly recommended that the current Docker Compose version V2 is used.

You can find detailed information about the differences and information on the
migrations in the official Docker documentation
https://docs.docker.com/compose/releases/migrate/.

CONTAINER REGISTRY

The image name copadata.azurecr.io/ is used by default in the docker-compose.yml file. The
Container images are thus obtained from the Azure Container Registry.

Alternatively, you can obtain the container images from the Docker Hub. To do this, change the
image names in copadata/.

13.5.1 Hardware connectors & ports

Hardware connections are specified with the devices option.

devices:

- "/dev/ttyUSB0:/dev/ttyUSB0" # connect USB device

- "/dev/sda:/dev/sda" # connect hard disc

volumes:

 devices:
Specify the path of the host device and the path under which the device should be available
in the container.
Example: "/dev/ttyUSB0:/dev/ttyUSB0" connects the ttyUSB0 device from the host to the
same path in the container.
 /dev/ttyUSB0:
Path to the USB device or other hardware device on the host system. The path must be
correct.
example: /dev/ttyUSB0 for a USB device or /dev/sda for a drive.

150 | 173
Service Engine for Docker- installation and operation

ADJUSTMENTS FOR TCP & UDP COMMUNICATION

For operation in a Docker environment with the standard bridge network, the start of the container
must be adjusted accordingly for communication via TCP or UDP:
 The incoming TCP port must be mapped externally with the following command when
communicating via TCP:
- 20000:20000
 The incoming UDP port must be mapped externally with the following command when
communicating via UDP:
- 20000:20000/udp
 For serial communication:
 The external serial interface must be mapped. The following is applicable:
For example for COM2: -> /dev/ttys1, COM3 -> /dev/ttys2
 Example of docker-compose.yml entry for mapping the COM6 (container) to the COM6
(host) for the service-engine container:
service-engine:
devices:
- "/dev/ttyS5:/dev/ttyS5"

13.6 .env file

The .env file contains the basic function parameters for installing and operating Service Engine in a
Docker environment.

The .env file allows developers to set environment variables. Environment variables in the .env file are
referenced with the $ sign followed by the variable name in the docker-compose.yml files.

The .env file provided contains commented entries that explain the use of each entry.

VERSION SPECIFIC SETTINGS

Parameter Description

TAG_VERSION= Version of the Service Engine, to be installed.

 [empty] or latest: installs the latest available version
 [Version number].[Number Minor-Release].[0].[Build-Number]

Example: 12.0.0.106805

151 | 173
Service Engine for Docker- installation and operation

PROJECT SPECIFIC SETTINGS

Parameter Description

ALWAYS_WAIT= Optional environment variable in order to not start

Service Engine automatically from the Container:
 No environment variable or no value
configured: Service Engine is automatically
started when the Container is started.
 Environment variable configured: If the
environment variable ALWAYS_WAIT= has
been configured with a value, Service Engine
is started by the DeviceAgent service. In
this case, Service Engine is not automatically
started when the container is started.

CONFIG_PATH= Custom storage location for Service Engine files.

 The zenon6.ini files must be present in the
same directory.
 In addition, generated Service Engine files
from the Service Engine folder must be
located in this folder.

Example: CONFIG_PATH=/etc/copa-data

LOGGING_PATH= User-defined storage location for the LOG files of

zenon Diagnosis Server.

Example: LOGGING_PATH=/var/log/copa-data

152 | 173
Service Engine for Docker- installation and operation

Parameter Description

CA_CERT_0= CA certificate in .pem format from 0..N. Each CA

certificate contains its own number, starting with 0.

Use the command cat for your certificate file and

copy the result to the environment variable.

CA_CERT_0="-----BEGIN CERTIFICATE----

MI....

-----END CERTIFICATE----"

Note: If you transfer more than the CA_CERT_0,

you must also add this to the compose.yml file.

Example:
CA_CERT_1: ${CA_CERT_1}
(add CA_CERT_0 after)

NETWORK_PASSWORD_CRYPT_KEY_BA Key for encrypted communication in the zenon

SE= network for the Linux device.

RUNTIME_LICENSE_SERIAL= Licensing of Service Engine.

Serial number of the Service Engine license. A valid
license is required to start Service Engine.

153 | 173
Service Engine for Docker- installation and operation

Parameter Description

RUNTIME_LICENSE_SERVER= License Server address.

PROCESSGATEWAY_LICENSE_SERIAL= Licensing of Process Gateway(s).

Serial number of the Process Gateway(s) license(s).
A valid license is required to start the Process
Gateway(s).

PROCESSGATEWAY_LICENSE_SERVER= License Server address.

LOGIC_LICENSE_SERIAL= Licensing of Logic Service.

Serial number of the Logic Service license. A valid
license is required to start Logic Service.

LOGIC_LICENSE_SERVER= License Server address.

USE_LOCAL_LICENSE= Optional environment variable to implement the

licensing only with the License.inifile.
 No environment variable or no value
configured: Content of the License.ini file of
the container is overwritten with the values
of the environment variables for licensing.
Note: if none of the environment variables
are configured for licensing, the content of
the License.ini-file of the container is also not
overwritten. If environment variables for
licensing are only given in part, the
information that is displayed in an
environment variable is transferred to the
License.ini file of the container. Missing
licensing information is transferred to the
License.ini file of the container with an empty
value.
 Environment variable configured: If the
environment variable
USE_LOCAL_LICENSE= is configured with a
value, licensing is only possible by means of
the License.ini file. License information that is
contained in the environment variables are
not transferred to the License.ini file of the
container.

154 | 173
Service Engine for Linux - installation and putting into operation

GENERAL
Parameter Description

CONTAINER_EXIT_ON_SE_CLOSE= Optional environment variable to also close the container

when closing Service Engine.

If the environment variable

CONTAINER_EXIT_ON_SE_CLOSE= is configured with a
desired value, the container is also ended when Service
Engine is ended.

13.7 IOT2050
IOT205 devices do not automatically install all recommended packages. This installation must be
executed manually. If you install Service Engine in a Docker environment on an IOT2050 device, you
must execute the following commands:
 sudo apt install iptables slirp4netns
 sudo apt install zenon-grpc-system-access

14 Service Engine for Linux - installation and putting into

operation
Generally:
 The installation is run as a Superuser on the Linux computer.
 User and user group: zenon (will be created automatically during installation).
 Pay attention to whether you are installing Service Engine on the Linux computer for the first
time. Create a backup of the zenon6.ini file of the Linux computer if you have already
installed Service Engine.
 Folder for zenon project data:
/etc/copa-data/
This folder must contain the following subfolders and file.
 RT subfolder with the Service Engine files

 ServiceGrid subfolder with the connection details (Certificate Bundles) and relevant
certificates.

155 | 173
Service Engine for Linux - installation and putting into operation

 zenon6.ini
Note: You can find further information in the Configuration of the zenon6.ini file (on
page 167) section.

LOGIC SERVICE
The files required for Logic Service are installed with the zenon Software Platform.
You can find these files in the Windows computer in the following folder:
%ProgramFiles(x86)%\COPA-DATA\zenon Software Platform 15\Engineering\Linux\x86\Ubuntu_20_04

14.1 Installation on the Linux computer

The following steps are necessary for commissioning IIoT Services on a Linux computer. You can find
a detailed description in the linked sections.
1. Set up APT repository (on page 156)
2. Install Service Engine Linux packages on a Linux computer (on page 157)
3. Verify and adjust access rights of the Linux installation (on page 158)
4. License installation (on page 161)
5. Register and start service (on page 171)

OPTIONAL INSTALLATION

Optionally, install the following IIoT Services on your Linux computer:

1. Device Management
Transports zenon projects automatically to Linux computers.
2. IIoT API & IIoT Services Gateway (on page 100)
Offers additional functionalities of the supported services via API, e.g. alarm
acknowledgment.

Information
You can find further Linux packages for components of the zenon software
platform on github
(https://github.com/COPA-DATA/service-engine-linux-how-to).

14.1.1 Setting up the APT repository

Carry out the following steps to set up the APT repository on your Linux computer:

156 | 173
Service Engine for Linux - installation and putting into operation

1. Log in to the Linux computer.

 Log in directly to the Linux computer with a physical keyboard, mouse and screen.
 Connect to your Linux computer via ssh with a remote session.
2. Download the repository GPG key.
To do this, execute the following command:
wget -O- https://repository.copadata.com/zenon/15/release/copadata-archive-keyring.gpg.key
| gpg --dearmor | sudo tee /usr/share/keyrings/copadata-archive-keyring.gpg > /dev/null
3. Add the APT repository to the list of remote repositories. In doing so, ensure that you are
using the correct hardware for your Linux computer:
 For computers with an amd64 processor, execute the following command:
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/copadata-archive-keyring.gpg]
https://repository.copadata.com/zenon/15/release/ noble main" | sudo tee
/etc/apt/sources.list.d/copa-data.list
 For computers with an arm64 processor, execute the following command:
echo "deb [arch=arm64 signed-by=/usr/share/keyrings/copadata-archive-keyring.gpg]
https://repository.copadata.com/zenon/15/release/ bullseye main" | sudo tee
/etc/apt/sources.list.d/copa-data.list
Note: If the arch= is not configured, a warning is displayed during the update of the
available packages.
4. Update the local index file for the repository.
To do this, execute the following command:
sudo apt update

14.1.2 Installation of the Service Engine package

The installation is carried out via the command line interface and applies to both amd64 or arm64
architectures.

Perform the following step to install Service Engine on your Linux computer:

sudo apt install service-engine

This command installs Service Engine and all associated software packages on your Linux computer.

Hint
Ensure that the system also installs the locales-all andiiot-cli packages, as these
packages are required for the proper functioning of Service Engine. These
packages are installed by default together with the service-engine package.

157 | 173
Service Engine for Linux - installation and putting into operation

14.1.3 Access rights

The zenon platform on Linux operating systems consists of several processes, for example:
 service-engine
 zenon-logging-server
 iiot-cli
 zenon driver
 Process Gateways
 zenon Logic field bus driver

These processes must be in a position to exchange files with one another. An example is the
zenon6.ini file. The services service-engine and zenon-logging-server at least must have read and
write access to this file. With the iiot-cli app, the access rights can be updated for the zenon project
files. When executing the transport of zenon projects with the iiot-cli app, the corresponding
authorizations are automatically set correctly. For execution, the iiot-cli app also needs read and write
access rights for the project configuration.

To keep data from each process separate, not all processes run with the same user.

FILE-BASED ACCESS RIGHTS

zenon for Linux uses the setgid bit for a folder that belongs to the zenon group. The effect is that
each file or each folder that is created within such a folder also belongs to the zenon group.
Regardless of whether the user is a member of this group or whether it is the user’s main group.

There are access permissions that can be issued for files or folders. These access permissions do not
take into account whether the user is permitted to do something, but instead the access permissions
are given to the file itself.

Example: setuid bit for root.

OPERATING AUTHORIZATIONS FOR ZENON FOLDER

To deploy zenon on Linux operating systems, the Linux services should be a part of the zenon user
group. As a result, all files can be read and written.

The simplest way to achieve this is the use of the iiot-cli tool to update your project. If this is not
possible (in a Docker environment for example), issue the access rights manually:
 Your CD_SYSTEM folder and your project folder (VBF30) must be accessible with read/write
access rights for the zenon group. To do this, execute the following commands:
CD_SYSTEM=${CD_SYSTEM:-/etc/copa-data}
sudo chown $USER:zenon -R $CD_SYSTEM

158 | 173
Service Engine for Linux - installation and putting into operation

find $CD_SYSTEM -type f -exec chmod 660 {} \; # we need to be able to read and write
all files
find $CD_SYSTEM -type d -exec chmod 770 {} \; # we need to be able to list and add
files
chmod g+s $CD_SYSTEM
 If your VBF30 folder is not in the CD_SYSTEM path, you must also carry out the same steps
for your VBF30 folder. To do this, execute the following commands:
VBF30=/path/to/VBF30
sudo chown $USER:zenon -R $CD_SYSTEM
find $VBF30 -type f -exec chmod 660 {} \; # we need to be able to read and write all files
find $VBF30 -type d -exec chmod 770 {} \; # we need to be able to list and add files
chmod g+s $VBF30

ALC (ACCESS CONTROL LISTS)

zenon for Linux operating systems does not use any Access Control Lists.

14.1.3.1 IOT2050
Note the following requirements for an IOT2050 Device mit Siemens Industrial OS:
1. If the command sudo apt update is executed on the IOT2050 Device mit Siemens Industrial
OS after importing the bunch of keys, the following error message can be shown:

The following signatures couldn't be verified because the public key is not available:
NO_PUBKEY <key>.
To solve this problem, the file permissions for
/usr/share/keyrings/copadata-archive-keyring.gpg must be set to rw-r--r--.
 To do this, execute the ls -lah /usr/share/keyrings/copadata-archive-keyring.gpg
command, for example.
 If the access permissions do not correspond to -rw-r--r--, you can apply minimum
access permissions with the command sudo chmod oga+r
/usr/share/keyrings/copadata-archive-keyring.gpg.
 Execute the sudo apt update command again and check whether the packages can be
updated.
2. If you execute the command sudo apt install service-engine on the IOT2050 Device mit
Siemens Industrial OS, this error message might be shown:

159 | 173
Service Engine for Linux - installation and putting into operation

The following packages have unmet dependencies: ...

Carry out the following steps to rectify this problem:
a) Switch to the following folder with the command cd /etc/apt
b) If not yet present, create a file with the name sources.list. To do this, use the command
sudo touch „sources.list“.
c) Open the file with an editor of your choice. To do this, use the command sudo nano
„sources.list for example.
d) Add the following content to the file:
deb http://ftp.at.debian.org/debian bullseye main
e) Save the file and execute the commands sudo apt update and sudo apt upgrade.
f) Execute the command sudo apt install service-engine again and check whether the
packages can be updated.
3. If you attempt to start Service Engine with a project on the IOT2050 Device mit Siemens
Industrial OS, there may be an error message saying that the project file could not be found.

To rectify this problem, you must adjust the access permissions of your project. To do this,
execute the following commands:
a) Repair the access permissions:
if [ -z "$CD_SYSTEM" ]; then
CD_SYSTEM=${CD_SYSTEM:-/etc/copa-data}
sudo chown $USER:zenon -R $CD_SYSTEM
find $CD_SYSTEM -type f -exec chmod 660 {} \; # we need to be able to read and write
all files
find $CD_SYSTEM -type d -exec chmod 770 {} \; # we need to be able to list and add
files
chmod g+s $CD_SYSTEM
b) Use the command sudo usermod -a -G zenon $USER to add your user to the zenon
group. Start Service Engine again and check whether the project files can now be found

Hint
You can find the latest information in the COPA-DATA Repository
(https://github.com/COPA-DATA/) in sectionzenon Service Engine on Linux -
Getting Started
(https://github.com/COPA-DATA/service-engine-linux-how-to?tab=readme-ov-fi
le#zenon-service-engine-on-linux---getting-started).

160 | 173
Service Engine for Linux - installation and putting into operation

14.1.4 Licensing
A valid license is required for the operation of Service Engine on your Linux computer.

Attention
If you start Service Engine on your Linux computer without a valid license, the
Service Engine start will fail.

LICENSING VIA COMMAND LINE - AUTOMATION

As an alternative to the configuration of the .INI file, you can also carry out the licensing with the
command line tool LicenseManagerAutomation. Note that .NET must be installed on the Linux
computer (on page 163) for the execution of this tool.

This tool is called up with LicenseManagerAutomation

Information
You can find more detailed information in relation to this in the Licensing via
command line - automation section.

LICENSING VIA MANUAL INI ENTRY

Perform the following steps to license Service Engine on your Linux computer:
1. Make sure that your Linux computer has a functioning network connection to your license
server.
2. Open the /etc/copa-data/License.ini file, for example, with the nano program or another text
editor.
Execute the following command to open the License.ini file with nano:
sudo nano /etc/copa-data/License.ini
3. Add the necessary licensing configurations to the License.ini file.
Please note: Inputs for Linux are case sensitive
 Service Engine-related entries:
[Runtime]
SERIAL0 = Serial number of the license according to the license certificate
SERIAL0_LOCATION = Computer name of the licensing server under which the
licensing server can be reached in the network.
 Logic Service-related entries:
[LogicRuntime]
SERIAL0 = Serial number of the license according to the license certificate
SERIAL0_LOCATION = Computer name of the licensing server under which the

161 | 173
Service Engine for Linux - installation and putting into operation

licensing server can be reached in the network.

SERIAL0_LOCATION = <machine name of the license server>
 Process Gateway-related entries:
[ProcessGateway]
SERIAL0 = Serial number of the license according to the license certificate
SERIAL0_LOCATION = Computer name of the licensing server under which the
licensing server can be reached in the network.

Information
You can find further information in relation to this in the License.ini section.

14.1.5 Checking the state of the installation and licensing

If Service Engine is running as a service, the state of the Service Engine and the Device Agent, as well
as the state of the licensing, can be checked with the following command:

sudo systemctl status serviceEngine.service

14.2 Installation of Linux components of the zenon Software

Platform - Summary
Perform the following steps to install all Linux-based components of the zenon Software Platform on
your Linux computer:
1. Copy the appropriate package to your client.
You can request the necessary packages for Service Engine from your sales partner.
2. Install the IIoT Services Gateway
service-grid-gateway-*.deb
To do this, execute the following command:
sudo apt install [package name]
Note: This installation is mandatory if you want to connect the Service Engine with the IIoT
Services.
3. Install
service-engine-*.deb
Start the service.
4. Optional: Install the diagnosis Server
zenon-logging-server
Check your installation using the command sudo systemctl status zenLogSrv.service

162 | 173
Service Engine for Linux - installation and putting into operation

5. Optional:
Delete the installation packages. To do this, enter the following command:
sudo apt autoremove
6. Optional:
Register Service Engine as a service. To do this, enter the following commands:
 sudo systemctl enable serviceEngine
 sudo systemctl start serviceEngine
Note: If there are no zenon projects installed on the Linux computer, the following error
message will be displayed when starting:
ServiceEngine initialization terminated with error - -1 / load of project failed
7. Optional:
Check your installation. To do this, enter the command:
sudo systemctl status serviceEngine

14.3 .NET installation on Linux

Install the .NET runtime environment using the platform package administration if possible. On a
platform on which the .NET runtime environment cannot be installed by means of package
administration, it may be possible to install .NET with an installation script.
1. Set up APT repository (on page 163)
2. Install .NET Linux packages on the Linux computer (on page 164)

Information
You can find detailed information on .NET for Linux on the Microsoft homepage
(https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu#register-the
-microsoft-package-repository).

14.3.1 Set up APT repository for .NET

Before installing .NET, carry out the following commands in order to add the Microsoft package
signing key to the list of trusted keys and the package repository.

# Get Ubuntu version

declare repo_version=$(if command -v lsb_release &> /dev/null; then lsb_release -r -s; else grep -oP
'(?<=^VERSION_ID=).+' /etc/os-release | tr -d '"'; fi)

163 | 173
Service Engine for Linux - installation and putting into operation

# Download Microsoft signing key and repository

wget https://packages.microsoft.com/config/ubuntu/$repo_version/packages-microsoft-prod.deb -O
packages-microsoft-prod.deb

# Install Microsoft signing key and repository

sudo dpkg -i packages-microsoft-prod.deb

# Clean up

rm packages-microsoft-prod.deb

# Update packages

sudo apt update

Attention
We recommend that you only use one repository to administer all your .NET
installations. If you have previously installed .NET with the Ubuntu repository,
you must clear the system of .NET packages and configure the APT so that the
Ubuntu feed is ignored.

14.3.2 Installation of .NET 8

Execute the following command to install Service Engine on your Linux computer:

sudo apt install [package name]

Replace [package name] with the name of the .NET package that you would like to install. To install
.NET SDK 8.0, for example, use the command sudo apt install aspnetcore-runtime-8.0.
.NET version Product Type Package name

8 ASP.NET Core Runtime aspnetcore-runtime-8.0

8 .NET Runtime dotnet-runtime-8.0

8 .NET SDK dotnet-sdk-8.0

164 | 173
Service Engine for Linux - installation and putting into operation

14.3.3 Check for previously-installed .NET versions

You can use a Terminal to check which versions of .NET runtime are currently installed. To do this,
open a Terminal and execute the following command:

dotnet --list-runtimes

The result is an output similar to the following example.

Microsoft.AspNetCore.App 5.0.0 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]

Microsoft.AspNetCore.App 6.0.0 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]

Microsoft.NETCore.App 5.0.0 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]

Microsoft.NETCore.App 6.0.0 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]

Microsoft.NETCore.App 7.0.0 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]

Microsoft.NETCore.App 8.0.0 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]

Hint
The which dotnet command can be used to display the installation path.

14.3.4 .NET environment variable

When starting in Service Engine using Linux, a check is carried out to see whether the
DOTNET_ROOT environment variable has been set. If this is not configured, the following two paths
are used:
 /usr/lib/dotnet/shared/Microsoft.NETCore.App
 /usr/lib/dotnet/shared/Microsoft.AspNetCore.App

If .NET has been installed using an install script, the environment variable must be set accordingly. In
the environment variable, the save location of the .NET installation must be declared.

Additional information:
 Install .NET on Linux by using an install script or by extracting binaries
(https://learn.microsoft.com/en-gb/dotnet/core/install/linux-scripted-manual)
 Deploy .NET apps on ARM single-board computers
(https://learn.microsoft.com/en-us/dotnet/iot/deployment)

165 | 173
Service Engine for Linux - installation and putting into operation

14.3.5 Uninstallation
If you have installed .NET via a package manager, uninstall it in the same way with the following
command:

sudo apt-get remove [package name]

Example: sudo apt-get remove aspnetcore-runtime-8.0.

14.4 Commissioning of a zenon project on Linux computers

The following options are available for commissioning a zenon project for Service Engine on Linux:
 Manual installation (on page 166)
 Installation via IIoT Services Device Management (on page 167)

14.4.1 Manual installation

Carry out the following steps to install a zenon project manually on a Linux computer:
1. Copy the Service Engine data from a Windows computer (on page 166).
2. Adapt the zenon6.ini file on the Linux computer (on page 167).

14.4.1.1 Copy zenon project data to a Linux computer

Copy the zenon project data to your Linux computer.
1. To do this, generate all Service Engine files in Engineering Studio on the engineering
computer.
2. On the engineering computer, go to the saving location of the files you generated. This
corresponds to configuring the Service Engine folder property in Engineering Studio.
3. Copy all the data of the folder to a folder on the Linux computer.
Default: /etc/copa-data/RT
4. Check the permissions for the folder. To do this, enter the following command:
sudo chown zenon:zenon -R /etc/copa-data/

Attention
If the project contains content that is not supported on the Linux operating
system, the project will not start correctly. You can find an overview in the Scope
of functions node.

166 | 173
Service Engine for Linux - installation and putting into operation

14.4.1.2 Configuration of the zenon6.ini file

Customize the zenon6.ini to your Linux system.
1. Go to the saving location of the zenon6.ini file. To do this, enter the following command:
cd /etc/copa-data
2. Correct the permissions for the zenon6.ini file. To do this, enter the following command:
sudo chown zenon zenon6.ini
3. Show the current zenon6.ini. To do this, enter the following command:
cat /etc/copa-data/zenon6.ini
4. Configure the following entries with an editor of your choice:
 [Default]
Defanwendung30= zenon project name on the Linux computer.
 [PATH]
VBF30= Path of the current project database. This path corresponds to the folder with
the copied Service Engine files.
 Optional: Customize the parameters for the Diagnosis Service. localhost is given by
default.
[LOGGING_SYSTEM]
Config= Parameter for connection with the respective diagnosis server.

Attention
When a package is installed, you will be asked if the zenon6.ini file should be
overwritten by a default file. If this file is overwritten, any customizations made
so far to this file must be configured again.

14.4.2 Installation via Device Management

Carry out the following steps to install a project via Device Management on your Linux computer:
1. Install IIoT Services certificate
2. Installing Device Agent
3. Prepare the project in Engineering Studio for Device Management.

14.4.2.1 Installing <NAME_SERIVCE_GRID> certificate

The following steps are only important if you are using the standard HTTPS certificate or another
self-signed HTTPS certificate for communication with IIoT Services, e.g.Device Management. As the

167 | 173
Service Engine for Linux - installation and putting into operation

default IIoT services HTTPS certificate is not trusted, you must add the corresponding certificate to the
list of trusted certificates.

If you already have a running installation of IIoT Services on the Linux computer and this IIoT Services
already uses a trusted certificate, it is not necessary to install the certificate again.

Hint
As an alternative to manual installation of a certificate, certificates can also be
generated directly on the Linux client via the IIoT Services CLI.

Carry out the following steps to install the IIoT Services certificate on your Linux computer:
1. Open Service Configuration Studio and download the certificate to your local computer.
Note: If your Linux computer has a graphical user interface and a browser, you can
download Service Configuration Studio directly on the Linux computer.
2. Transfer the certificate to the Linux computer using a suitable mechanism such as scp, ftp or
network file sharing.
Note: You can find further information on scp on the ubuntu manual website
(https://manpages.ubuntu.com/manpages/trusty/man1/scp.1.html).
3. Copy the certificate file on the Linux computer to the /usr/local/share/ca-certificates
directory. The name of the certificate file is of no importance.
4. Update the system's trusted certificates with the following command:
sudo update-ca-certificates
This updates the certificates of the Linux computer and adds the certificate for IIoT Services
to the list of trusted certificates.
5. Check the installed certificate. To do this, execute the following command:
curl 'https://[url-of-iiot-services]:[port-of-iiot-services]
Example:

Information
You can find detailed information on the certificate handling of IIoT Services in
the Certificate Management and Certificates sections.

14.4.2.2 Installing Device Agent

For registration, the Device Agent is automatically downloaded via the IIoT Services CLI by the Device
Management Service.

You can find general requirements for the installation of the IIoT Services CLI on Linux systems in the
Setting up the APT repository (on page 156) section.

168 | 173
Service Engine for Linux - installation and putting into operation

Ensure that there is appropriate trust between the device and IIoT Services.

Note: For a trust relationship, it may be necessary to install the corresponding Root CA certificate.
Installation of the Root CA is necessary if your current certificate was generated by the IIoT Services
during the initial setup. You can find more detailed information in the nodes Certificates (for general
information about certificates) and Trust relationships.

Then carry out the following steps to install IIoT Services CLI on a Linux Device:
1. Update the list of the zenon software packages available. Execute the following command:
sudo apt update
2. Install the command line interface on the Linux device. Execute the following command:
sudo apt install iiot-cli-15-0
3. Carry out the installation of the Device Agent service. To do this, enter the following
command:
a) If you have web access for authentication on the Linux device:
iiot-cli device setup-agent [URL to the IIoT Services]:Port -n [Name of the device]
The name of the device is optional.
Example: iiot-cli device setup-agent https://iiot-docu-v8.testenv.local:9443 -n
LinuxDevice
b) If you do not have web access for authentication on the Linux device:
iiot-cli device setup-agent https://iiot-docu-v8.testenv.local:9443 -n LinuxDevice
--use-device-code
The --use-device-code command tag is used for authorization via the Identity Service
in Service Configuration Studio.
The URL and code for this authorization is visualized in the command line.
After successful authorization, installation on the Linux device will be complete.
4. If you have installed more than one version of IIoT-CLI , you can switch between the versions.
To do this, execute the following command:
sudo update-alternatives --config iiot-cli
Then follow the instructions of CLI.
5. Check the status of the device agent:
 Check the connection status of the device in the Device Management user interface in
Service Configuration Studio. The Linux device must display the status online.
 On the Linux computer, the status of the device agent is checked with the following
command:
sudo systemctl status device-agent.service

169 | 173
Service Engine for Linux - installation and putting into operation

Information
Ensure that the following language settings (Locales) are installed on your
system:

- en_US.UTF-8

- UTF-8/en_US.UTF-8

- UTF-8

If these Locales are missing, it can happen that the Device Agent is closed with
the following error message:

terminate called without an active exception Aborted

Attention
For Siemens IOT2050 devices, the package zenon-grpc-system-access must be
installed. This is necessary for correct communication between Device Agent and
Service Engine.

The following options are available:

 Use the --install-recommends parameter when installing Service Engine:
sudo apt install service-engine --install-recommends
 Install the package manually by executing the following commands:
sudo apt update
sudo apt install zenon-grpc-system-access

DEVICE AGENT LINUX SERVICE

The Device Agent as a Linux service has the following name: device-agent.service

The Device Agent can be started and stopped via the Linux services (systemctl). The Device Agent is
automatically started by default when the system is started.
 Start Device Agent: sudo systemctl start device-agent.service

Stop Device Agent: sudo systemctl stop device-agent.service

170 | 173
Service Engine for Linux - installation and putting into operation

14.4.2.3 Preparing zenon projects in Engineering Studio for Device

Management
The deployment of packages is implemented in Engineering Studio with a wizard.

You can find detailed information for the transfer of a project from Engineering Studio in the Device
Management node in the IIoT Services - configuration in Engineering Studio node.

14.5 Starting Service Engine

To register manually, enter the following command: sudo systemctl enable serviceEngine

Start Service Engine on your Linux client with the following command: sudo systemctl start
serviceEngine

RESTARTING

Enter the following command to restart a running Service Engine on your Linux client: sudo systemctl
restart [Service Name]

Example: sudo systemctl start serviceEngine

171 | 173
FAQ

14.6 Uninstallation
Perform the following steps to uninstall the zenon installation on your Linux computer.
1. Go to the appropriate folder. To do this, enter the following command:
sudo apt remove [package name]
Example: sudo apt remove service-engine
This deletes all the content installed with the package.
2. Repeat this step for all installed packages.
3. The zenon6.ini file will not be deleted. Enter the following command to also delete the
configuration file:
sudo apt purge [package name]

15 FAQ
Errors during the installation mostly occur when the replacement or creation of files is prevented by a
virus scanner or by existing installations. Here you can find the most frequent reasons for installation
errors and their solution.

ZENON
Problem Solution

Installation is terminated. Deactivate the virus scanner. Close unnecessary

programs.
Typical error message: Error 1304. Error
writing to file...

Demo projects were installed but are not Check the computer name. The computer:
displayed. New projects cannot be created.
 must not consist of more than 128
characters
 must be in accordance with the convention
of the NetBIOS computer name

Error message that a service cannot be  first reboot the computer

started.  then start the zenon setup again

172 | 173
Technical support

SQL SERVER

GENERAL
Problem Solution

The installation is unsuccessful because the The installation of SQL Server is not possible if the
password does not meet the requirements. security requirements do not permit a password
length of 20 characters (A-Z, a-z, 0-9 and special
characters). Each character can only be used once.

16 Technical support

BASIC SUPPORT
If you need support for the installation, our employees in Technical Consulting would be happy to
help you.

User with basic support can reach the hotline at the following e-mail address:
[email protected].

ADVANCED AND PREMIUM SUPPORT

If you have an Advanced or Premium service agreement, please use the telephone number or email
address provided in that. Our sales employees ([email protected]) will gladly assist you, if you
want to upgrade your free basic service agreement to an Advanced or Premium service agreement.

173 | 173