EcoStruxure Machine Expert

Functions and Libraries User Guide

EIO0000002829.03
12/2023

www.se.com
Legal Information
The Schneider Electric brand and any trademarks of Schneider Electric SE and its
subsidiaries referred to in this guide are the property of Schneider Electric SE or its
subsidiaries. All other brands may be trademarks of their respective owners.
This guide and its content are protected under applicable copyright laws and
furnished for informational use only. No part of this guide may be reproduced or
transmitted in any form or by any means (electronic, mechanical, photocopying,
recording, or otherwise), for any purpose, without the prior written permission of
Schneider Electric.
Schneider Electric does not grant any right or license for commercial use of the guide
or its content, except for a non-exclusive and personal license to consult it on an "as
is" basis. Schneider Electric products and equipment should be installed, operated,
serviced, and maintained only by qualified personnel.
As standards, specifications, and designs change from time to time, information
contained in this guide may be subject to change without notice.
To the extent permitted by applicable law, no responsibility or liability is assumed by
Schneider Electric and its subsidiaries for any errors or omissions in the informational
content of this material or consequences arising out of or resulting from the use of the
information contained herein.

As part of a group of responsible, inclusive companies, we are updating our

communications that contain non-inclusive terminology. Until we complete this
process, however, our content may still contain standardized industry terms that may
be deemed inappropriate by our customers.

© 2023 – Schneider Electric. All rights reserved.

Table of Contents
Safety Information.......................................................................................5
About the Book ............................................................................................6
General Description of Libraries ...............................................................9
Generalities About Libraries ........................................................................9
Library Management ................................................................................13
Library Referencing Methods.....................................................................13
Introduction ........................................................................................13
Direct Version .....................................................................................14
Newest Version...................................................................................15
Placeholder Mechanism ......................................................................16
Forward Compatible Libraries ..............................................................18
Using Libraries .........................................................................................20
Different Ways to Declare a Library in a Project ....................................20
Adding Libraries to a Project ................................................................21
Updating Libraries and Library References ...........................................21
Check Library Compatibility..............................................................24
Library Manager Editor.............................................................................26
Library Manager Editor ............................................................................26
Add Library.............................................................................................30
Properties...............................................................................................32
Try to Reload Library ..............................................................................33
Exporting Library Files ..............................................................................34
Placeholders...........................................................................................35
Library Repository..................................................................................36
Version Mapping Tab ..............................................................................39
Library Updates Tab................................................................................40
Create Your Own Library .........................................................................43
General Information ..................................................................................43
Step 1: Setup the Project...........................................................................43
Step 2: Fill-in the Project Information .......................................................43
Step 2.1: Decide Whether Your Library Should Be Forward
Compatible ..............................................................................................46
Step 3: Reference Other Libraries, if Needed ..............................................47
Step 3.1: Use Placeholder References .......................................................48
Step 4: Design and Program the Library Modules........................................48
Step 5: Design the Interface ......................................................................49
Step 6: Implement Error Handling Routines ................................................49
Step 7: Set up a Reasonable Deployment (Usage Restriction) .....................49
Function and Function Block Representation ......................................50
Differences Between a Function and a Function Block.................................50
How to Use a Function or a Function Block in IL Language ..........................51
How to Use a Function or a Function Block in ST Language.........................54
Glossary .....................................................................................................57
Index ...........................................................................................................59

EIO0000002829.03 3
Safety Information

Safety Information
Important Information
Read these instructions carefully, and look at the equipment to become familiar
with the device before trying to install, operate, service, or maintain it. The
following special messages may appear throughout this documentation or on the
equipment to warn of potential hazards or to call attention to information that
clarifies or simplifies a procedure.

The addition of this symbol to a “Danger” or “Warning” safety label indicates that an
electrical hazard exists which will result in personal injury if the instructions are not
followed.

This is the safety alert symbol. It is used to alert you to potential personal injury
hazards. Obey all safety messages that follow this symbol to avoid possible injury or
death.

! DANGER
DANGER indicates a hazardous situation which, if not avoided, will result in death or serious
injury.

! WARNING
WARNING indicates a hazardous situation which, if not avoided, could result in death or
serious injury.

! CAUTION
CAUTION indicates a hazardous situation which, if not avoided, could result in minor or
moderate injury.

NOTICE
NOTICE is used to address practices not related to physical injury.

Please Note
Electrical equipment should be installed, operated, serviced, and maintained only
by qualified personnel. No responsibility is assumed by Schneider Electric for any
consequences arising out of the use of this material.
A qualified person is one who has skills and knowledge related to the construction
and operation of electrical equipment and its installation, and has received safety
training to recognize and avoid the hazards involved.

EIO0000002829.03 5
 About the Book

About the Book

Document Scope
This document describes the libraries, libraries management and functions
implementations in EcoStruxure Machine Expert.

Validity Note
This document has been updated for the release of EcoStruxure™ Machine Expert
V2.2.
The characteristics that are described in the present document, as well as those
described in the documents included in the Related Documents section below,
can be found online. To access the information online, go to the Schneider Electric
home page www.se.com/ww/en/download/.
The characteristics that are described in the present document should be the
same as those characteristics that appear online. In line with our policy of constant
improvement, we may revise content over time to improve clarity and accuracy. If
you see a difference between the document and online information, use the online
information as your reference.

Related Documents
Document title Reference

Cybersecurity Best Practices CS-Best-Practices-2019-340

Cybersecurity Guidelines for EcoStruxure EIO0000004242

Machine Expert, Modicon and PacDrive
Controllers and Associated Equipment

EcoStruxure Machine Expert CommonPouTypes EIO0000004561

Library Guide

EcoStruxure Machine Expert Programming EIO0000002854 (ENG);

Guide
EIO0000002855 (FRE);

EIO0000002856 (GER);

EIO0000002858 (SPA);

EIO0000002857 (ITA);

EIO0000002859 (CHS)

Schneider Electric Software Installer User Guide EIO0000002848 (ENG);

EIO0000002849 (FRE);

EIO0000002850 (GER);

EIO0000002852 (SPA);

EIO0000002851 (ITA);

EIO0000002853 (CHS)

6 EIO0000002829.03
About the Book

Product Related Information

WARNING
LOSS OF CONTROL
• Perform a Failure Mode and Effects Analysis (FMEA), or equivalent risk
analysis, of your application, and apply preventive and detective controls
before implementation.
• Provide a fallback state for undesired control events or sequences.
• Provide separate or redundant control paths wherever required.
• Supply appropriate parameters, particularly for limits.
• Review the implications of transmission delays and take actions to mitigate
them.
• Review the implications of communication link interruptions and take actions
to mitigate them.
• Provide independent paths for control functions (for example, emergency
stop, over-limit conditions, and error conditions) according to your risk
assessment, and applicable codes and regulations.
• Apply local accident prevention and safety regulations and guidelines.1
• Test each implementation of a system for proper operation before placing it
into service.
Failure to follow these instructions can result in death, serious injury, or
equipment damage.

1 For additional information, refer to NEMA ICS 1.1 (latest edition), Safety
Guidelines for the Application, Installation, and Maintenance of Solid State Control
and to NEMA ICS 7.1 (latest edition), Safety Standards for Construction and
Guide for Selection, Installation and Operation of Adjustable-Speed Drive
Systems or their equivalent governing your particular location.

WARNING
UNINTENDED EQUIPMENT OPERATION
• Only use software approved by Schneider Electric for use with this
equipment.
• Update your application program every time you change the physical
hardware configuration.
Failure to follow these instructions can result in death, serious injury, or
equipment damage.

Terminology Derived from Standards

The technical terms, terminology, symbols and the corresponding descriptions in
this manual, or that appear in or on the products themselves, are generally
derived from the terms or definitions of international standards.
In the area of functional safety systems, drives and general automation, this may
include, but is not limited to, terms such as safety, safety function, safe state, fault,
fault reset, malfunction, failure, error, error message, dangerous, etc.

EIO0000002829.03 7
 About the Book

Among others, these standards include:

Standard Description

IEC 61131-2:2007 Programmable controllers, part 2: Equipment requirements and tests.

ISO 13849-1:2023 Safety of machinery: Safety related parts of control systems.

General principles for design.

EN 61496-1:2013 Safety of machinery: Electro-sensitive protective equipment.

Part 1: General requirements and tests.

ISO 12100:2010 Safety of machinery - General principles for design - Risk assessment
and risk reduction
EN 60204-1:2006 Safety of machinery - Electrical equipment of machines - Part 1: General
requirements

ISO 14119:2013 Safety of machinery - Interlocking devices associated with guards -

Principles for design and selection

ISO 13850:2015 Safety of machinery - Emergency stop - Principles for design

IEC 62061:2021 Safety of machinery - Functional safety of safety-related electrical,

electronic, and electronic programmable control systems

IEC 61508-1:2010 Functional safety of electrical/electronic/programmable electronic safety-

related systems: General requirements.

IEC 61508-2:2010 Functional safety of electrical/electronic/programmable electronic safety-

related systems: Requirements for electrical/electronic/programmable
electronic safety-related systems.

IEC 61508-3:2010 Functional safety of electrical/electronic/programmable electronic safety-

related systems: Software requirements.

IEC 61784-3:2021 Industrial communication networks - Profiles - Part 3: Functional safety

fieldbuses - General rules and profile definitions.

2006/42/EC Machinery Directive

2014/30/EU Electromagnetic Compatibility Directive

2014/35/EU Low Voltage Directive

In addition, terms used in the present document may tangentially be used as they
are derived from other standards such as:

Standard Description

IEC 60034 series Rotating electrical machines

IEC 61800 series Adjustable speed electrical power drive systems

IEC 61158 series Digital data communications for measurement and control – Fieldbus for
use in industrial control systems

Finally, the term zone of operation may be used in conjunction with the description
of specific hazards, and is defined as it is for a hazard zone or danger zone in the
Machinery Directive (2006/42/EC) and ISO 12100:2010.
NOTE: The aforementioned standards may or may not apply to the specific
products cited in the present documentation. For more information concerning
the individual standards applicable to the products described herein, see the
characteristics tables for those product references.

8 EIO0000002829.03
General Description of Libraries

General Description of Libraries

Overview
This chapter describes the generalities about libraries and the library management
in EcoStruxure Machine Expert.

Generalities About Libraries

Content of Libraries
Libraries are collections of objects that you can link to your application. You can
use the objects contained in libraries in the same way as objects that you have
defined in the project.
Libraries can contain the following objects:
• POUs (such as function blocks or functions)
• Interfaces and their methods and attributes
• Data types (such as enumerations, structures, aliases, and unions)
• Global variables, constants, and parameter lists
• Text lists, image pools, visualizations, and visual elements
• External files (such as documentation)
• Cam tables
• Objects from the ETEST plugin (for example, Test Cases)
For managing libraries in a project, use a Library Manager. The Library
Manager editor is described in the Library Manager Editor chapter, page 26. The
installation of libraries is accomplished during the installation of those elements
(devices, solutions, controllers) you select to install with the Schneider Electric
Software Installer. You can manage user-defined libraries via the Library
Manager and the Library Repository directly within EcoStruxure Machine
Expert.

EIO0000002829.03 9
 General Description of Libraries

Library Information
In the Library Manager, you find the libraries included in your project / library and
in the Library Repository, you find the available libraries. Depending on the
selected library, different information is available:

Information Description Example

Name Name of the library TcpUdpCommunication

Version Version of the library 1.1.10.0

Company The primary provider or group name defined by the Schneider Electric
primary provider of the library, as shown in the
Library Manager and Library Repository dialog
box.
Namespace The default namespace of the library for accessing TCPUDP
functions of the library.
NOTE: Good practice is to use the default
namespace as the namespace used in your
application.
If qualified-access-only is set as library attribute, the
usage of the namespace in your application is
mandatory.

Category The category (or categories) which this library Communication

belongs to, as shown in the Library Manager and
Library Repository dialog box.

Namespace
A library namespace is a symbol that allows the unique access to the attached
library components (functions, function blocks, variables…). The namespace is
necessary when two components of two different libraries used in the same
project have the same name. The usage of the namespace in your application is
mandatory if the library has set the attribute qualified-access-only . To ensure
unique access to the correct component, use the full name <namespace>.
<component> format, including the namespace.

Case Description

1 There is a function block GEN in the library Util. The namespace of the library Util is Util.
An instance of the function block GEN can be declared with or without the library
namespace if the name GEN is unique within the project:

MyGenerator: Util.GEN;

Or MyGenerator: GEN;

2 A function block GEN has been created within the project. The use of the library Util
namespace will allow the system to access the function block GEN of the library Util.
Without namespace, the project function block GEN will be accessed:

MyGenerator_Util: Util.GEN;

MyGenerator_Project: GEN;

3 Another library, also containing a function block called GEN, is declared in the project
with namespace NewLib. The use of the namespace becomes mandatory to identify the
correct function block GEN to be accessed:

MyGenerator_Util: Util.GEN;

MyGenerato_NewLib: NewLib.GEN;

A default namespace is defined for each library.

10 EIO0000002829.03
General Description of Libraries

Library Repository
The Library Repository is the editor that manages libraries installed in
EcoStruxure Machine Expert. The Library Repository allows you to install or
remove user-defined libraries as well as other library types, such as application
libraries, device libraries, or other libraries. A library can be used in an
EcoStruxure Machine Expert project only if it is installed in the Library
Repository. With the installation of EcoStruxure Machine Expert, a set of libraries
is installed by default in the System library repository. You can install new libraries
or new versions of existing libraries either via the Library Repository dialog box,
or by using the Schneider Electric Software Installer (refer to the Schneider
Electric Software Installer User Guide).
The paths to the folders where the (System and User) repositories are located
are configured in the Tools > Options > Directories (Devices, Libraries, ...)
dialog box.

Protection of Libraries
The following methods exist to protect your library:

Method Description

Source code protection When a library is prepared in “compiled-library” format, the source code
of the library modules is no longer visible after the library is integrated
into a project.

Signing A certificate is used for the signing of library projects (*.compiled-library-

v3). The signing can be enforced by means of a setting in the Security
Screen dialog. Then for generating a compiled library, you need a
certificate suitable for code signing in your user profile. See also Save
Project As Compiled Library.

For library projects that have to be compatible with EcoStruxure Machine

Expert < V2.0 (*.compiled-library), only less secure signing is possible
with a private key and a corresponding token. These methods should
only be used for reasons of compatibility. Settings are configured in the
Project Information on the Signing tab.

Integrity check When the option Integrity check is selected in the Project Settings >
Security dialog box, the project file is stored in a proprietary format. The
integrity of the file is verified each time the project is loaded.

Encryption using When the option Encryption is selected in the Project Settings >
password or certificate Security dialog box, the project file is encrypted by password or
certificate according to your individual requirements. For further
information, refer to the Menu Commands Online Help.

Licensing You can protect libraries by means of a license (dongle or soft container).
License-protected libraries can be installed in the library repository.
However, for use in the project, the valid license has to exist on the
computer.

EIO0000002829.03 11
 General Description of Libraries

Managing Libraries by Using Library Managers

Libraries declared in a project are managed in the Library Manager editor.
An EcoStruxure Machine Expert project can include more than one controller.
Therefore, different Library Managers are available. In general, two intended use
cases of the same Library Manager object exists:

Use Case Location of the Library Manager

One Library Manager for each controller to handle the controller- In the Tools tree (see EcoStruxure Machine Expert,
specific and the application-specific libraries. Programming Guide) below the Application node for each
controller
Library Manager nodes for user-specific POUs which are used in In the Tools tree (see EcoStruxure Machine Expert,
more than one controller of the same EcoStruxure Machine Expert Programming Guide) below the Global node.
project.

For more information about library management, Library Repository and Library
Manager Editor, refer to Library Management, page 26.
For more information on finding a function or function block of libraries with the
FFB Finder, refer to How to Find a Function or Function block with the FFB Finder
(see EcoStruxure Machine Expert, Programming Guide).

12 EIO0000002829.03
Library Management

Library Management
Overview
This chapter provides information to help you managing libraries and library
versions of referenced libraries.

Library Referencing Methods

Overview
This section provides general information about library referencing methods, their
advantages, and disadvantages as well as their use in EcoStruxure Machine
Expert.

Introduction
Overview
Both projects and libraries themselves can use external functionalities which are
stored in other, separate libraries. To use those functionalities, these separate
libraries have to be included into the project in the Library Manager as referenced
libraries. Libraries which are referenced by libraries used in a project (application
project) or library (library project) are referred to as indirectly referenced libraries.
These indirectly referenced libraries are included automatically when compiling
and cannot be used in a project itself.
Depending on the used referencing method, the possibility and/or affect of a
modification of the library version varies. Changing an indirect referenced library
version for example is not possible.
Instead, the library versions are changed by the different library management
mechanisms.
Libraries can be referenced in various ways:
• Direct version, page 14
• Newest version, page 15
• Placeholder mechanism, page 16
• Forward compatible library (FCL), page 18

EIO0000002829.03 13
 Library Management

Direct Version
Overview
A simple method for referencing libraries is to define explicitly within the Library
Manager of an application or library project which library and exact library version
should be used.
If a library X embeds another library Z using a direct reference, then library Z will
be loaded exactly in the version that is embedded by library X.
This can lead to several versions of the same library being loaded in one Library
Manager of a project.
NOTE: The method allows referencing several versions of a library within the
same project. Although this method is advantageous for certain types of
libraries, care must be taken when applying it to others to avoid complications.
Therefore, this method is generally discouraged except where indicated.

WARNING
UNINTENDED EQUIPMENT OPERATION
• Verify whether the versions of the libraries contained in your program are
correct, after updating the software.
• Verify whether the versions of the updated libraries are consistent with your
application specifications.
Failure to follow these instructions can result in death, serious injury, or
equipment damage.

14 EIO0000002829.03
Library Management

Example
Situation: The following libraries are added in the Library Manager:

Library Version

Library X 1.0.0.0

Library Y 1.0.0.0

Library Z 1.0.0.0

Dependencies:

Library... Requires Library Z in Version...

X 1.0.1.0
Y 1.0.2.0

Assuming that library Z was added in all libraries as a direct library version, this
would mean:
• Library Z will be loaded in three different versions:
◦ The POUs of the project are directly using the functionalities of version
1.0.0.0.
◦ The POUs of library X are using the functionalities of version 1.0.1.0.
◦ The POUs of library Y are using the functionalities of version 1.0.2.0.
• This can cause potential compiler errors, for example, if the system tries to
exchange data between the POUs of library Z used by library X and between
the POUs of library Z used by library Y. This can occur, even if the data
structure is identical.
• This can cause a potentially unnecessary increase of the application size as
both versions of the libraries may be included in the build.
• When the library reference is a direct version reference, a change of the
indirect library dependencies is not possible after the library creation.

Newest Version
Overview
This referencing method is similar to the direct version referencing method.
Instead of an exact library version, a symbol (*) is defined as referenced library
version. Every time when compiling, the newest locally installed version of a
library is used in the project as referenced library version.
NOTE: When a new version of a library gets installed in the library repository,
all projects and libraries referencing this library with the newest version will get
changed without further notice when compiled. Usually this behavior is not
desirable in your application because it may introduce unintended changes,
either during build or during program execution.

WARNING
UNINTENDED EQUIPMENT OPERATION
• Verify whether the versions of the libraries contained in your program are
correct, after updating the software.
• Verify whether the versions of the updated libraries are consistent with your
application specifications.
Failure to follow these instructions can result in death, serious injury, or
equipment damage.

EIO0000002829.03 15
 Library Management

Example
Situation: The following libraries are added in the Library Manager:

Library Version

Library X 1.0.0.0

Library Y 1.0.0.0

Library Z 1.0.0.0

Dependencies:

Library... Requires Library Z in Version...

X 1.0.1.0
Y 1.0.2.0

Additionally the following library version is installed in the Library Repository:

On Computer A On Computer B

Library Z version 1.0.3.0 Library Z version 1.0.2.0

Assuming that library Z was added by using the newest version method, this
would mean:

On Computer A: On Computer B:

Library X uses Library Z version 1.0.3.0. Library X uses Library Z version 1.0.2.0.

Library Y uses Library Z version 1.0.3.0. Library Y uses Library Z version 1.0.2.0.

Placeholder Mechanism
Overview
A placeholder in the Library Manager is a reference to a definite library version.
Placeholders simplify the maintenance of library hierarchies.
Consequent usage of placeholders allows you to modify libraries at a lower level
of the dependencies hierarchy (such as updates or bug-fixing) and avoids the
need to adapt libraries of the higher levels or to adapt the device descriptions.
The search order for the placeholder resolution is (highest priority first):
1. Placeholder definition in the Placeholders dialog box of the Library
Manager of the application
2. Placeholders defined in device descriptions of the devices used
3. Placeholders defined by plugins
4. Placeholders dialog box of the Library Manager in the Global node of the
Tools tree
The result is displayed in the Effective Version column of the Library Manager
Editor, page 26. Further information is provided in the tooltip of the symbol.
If the placeholder is not resolved after the steps have been executed, the library is
marked with the symbol not resolved in the Library Manager editor list and
the library will not be included in the compile.

16 EIO0000002829.03
Library Management

Configure the resolution of a placeholder in the Placeholders dialog box.

WARNING
UNINTENDED EQUIPMENT OPERATION
• Verify whether the versions of the libraries contained in your program are
correct after updating the software.
• Verify whether the versions of the updated libraries are consistent with your
application specifications.
Failure to follow these instructions can result in death, serious injury, or
equipment damage.

NOTE: With compiler versions of EcoStruxure Machine Expert V2.2 and later,
the library profile is ignored for placeholder resolution. Placeholders which are
not resolved by the Placeholders dialog box, a device description, or a plugin
code become Unbound placeholders and the latest available version of the
library is used.
NOTE: Library names and placeholder references are case-sensitive.

Example
Precondition: The placeholder SysLib is defined and resolved in the device
description of different devices.

Device description defining placeholder Resolution of placeholder SysLib

SysLib

Device A (V1.0.0.0) SysLibA (V1.0.0.0)

Device A (V1.0.1.0) SysLibA (V1.0.1.0)

Device B (V2.1.0.0) SysLibB (V1.0.0.0)

Device B (V2.2.0.0) SysLibB (V1.0.1.0)

Using the placeholder SysLib in an application:

In your application, you have added the placeholder SysLib to the Library
Manager.

If... Then...
If device A with version V1.0.0.0 is implemented Then the library SysLibA with version V1.0.0.0
in your application. is referenced in the Library Manager because
the placeholder Syslib is resolved by the device
description of device A.

If device B with version V2.2.0.0 is implemented Then the library SysLibB with version V1.0.1.0
in your application. is referenced in the Library Manager because
the placeholder Syslib is resolved by the device
description of device B.

If neither device A nor device B are implemented Then the placeholder is not resolved by a
in your application. device.

In this case, perform the placeholder resolution

in the Placeholders dialog box in the Library
Manager.

EIO0000002829.03 17
 Library Management

Using the placeholder SysLib in another library:

In our example we assume that the libraries SysLibA and SysLibB contain the
property Placeholder with the value SysLib. Because of this, SysLib is added
when adding the library SysLibA or SysLibB.
Since there is no device in the library project that defines the placeholder
resolution, the placeholder is treated as an Unbound placeholder. The default
resolution for unbound placeholders is the latest version of the added library which
is installed in the available library repositories. You can adjust the resolution of a
placeholder in the Placeholders dialog box.
Later, when the library is used in an application, the placeholder will be resolved
as described in the Overview, page 16. The definition of the placeholder resolution
performed in the Placeholders dialog box is exclusively valid for the library project
itself.

Forward Compatible Libraries

Overview
A forward compatible library (FCL) is developed in such a way that its
functionalities are forward compatible. This means that every version of a forward
compatible library contains all functionalities of the previous version and a newer
library version can be easily used in existing projects without any changes.
Dependencies to libraries (library X uses library Z) are read as minimum
compatible version.
If a library X requires another, forward compatible library Z, for example in version
1.0.0.0, library X will work with version 1.0.0.0 or any newer version of library Z.
Only one single version of a forward compatible library is selected and used in a
project Library Manager on request (when clicking the Automatic button). This
compatible version of the library selected in the Version mapping tab, page 39 of
the Library Manager is used in the direct and indirect references in the libraries
within this project.
This referencing method has the following advantages:
• It supports a parallel independent development process of several libraries.
• It eases library updates by forward compatible development ruleset.
It is assumed, that once a version of a library is marked as a forward compatible
library, then all future versions will also be forward compatible.
For detailed information about creating forward compatible libraries, refer to
Create Your Own Forward Compatible Library, page 46.

18 EIO0000002829.03
Library Management

Example
Situation: The following libraries are added in the Library Manager:

Library Version

Library X 1.0.0.0

Library Y 1.0.0.0

Library Z 1.0.0.0

Dependencies:

Library... Requires Minimum Version of Library Z...

X 1.0.1.0
Y 1.0.2.0

On the local system the following versions of library Z are installed:

• 1.0.0.0
• 1.0.1.0
• 1.0.2.0
• 1.0.3.0
Assuming that the installed versions of library Z are marked as forward
compatible, this would mean:
• Only one version of library Z is loaded.
• Compatible versions of library Z in this project are 1.0.2.0 and 1.0.3.0, which
meet the minimum required dependencies.
• You can configure which version is to be used in this case (however, it makes
sense to use the newest installed compatible version).
• After clicking the Automatic button in the Version mapping tab of the
project, version 1.0.3.0 of library Z will be chosen because it is the newest
installed compatible version.
• The POUs of the projects of library X and library Y use the same versions of
POUs of library Z.
• The exchange of POUs from library Z between the project and other libraries
is possible.

EIO0000002829.03 19
 Library Management

Advanced Example
Situation:
• A new version 1.0.3.1 of library Z uses some features of a system library
referenced via placeholder SysLib.
• This System library is compatible to controller A since version 2.0.0.0. This is
indicated in library Z version 1.0.3.1 by a minimum controller firmware, page
46 requirement.
This would mean:
• If a project uses controller A version 1.0.0.0, the following libraries are
compatible:
◦ 1.0.2.0
◦ 1.0.3.0
• If a project uses controller A version 2.0.0.0, the following library is
compatible:
◦ 1.0.3.1
• When clicking the Automatic button in the Version mapping tab, version
1.0.3.1 of library Z will be selected, if the controller A used in the project has
been updated to version 2.0.0.0.
Otherwise version 1.0.3.0 of library Z will be selected.

Using Libraries
Overview
This section provides information on situations you can encounter, when adding
libraries to an existing EcoStruxure Machine Expert project, updating libraries or
creating a forward compatible library.

Different Ways to Declare a Library in a Project

Overview
There are different ways to declare a library in a project. Some libraries are
automatically declared when adding the following:
• a controller:
◦ IEC 61131 basic libraries: Standard and Util libraries
◦ Controller PLCSystem library
◦ Other libraries to manage embedded controller features
• specific controller features
• a fieldbus manager
• a fieldbus device
Some libraries must be added manually.
NOTE: Some functions and function blocks are not intended to be used within
your program, but may be required by the system or by a device. You should
use only functions and function blocks that are documented as program
applicable, or functions or function blocks that you have thoroughly tested with
your application.

20 EIO0000002829.03
Library Management

Adding Libraries to a Project

Overview
To add a new library to an EcoStruxure Machine Expert project, open the Library
Manager editor and proceed as described in the Library Manager Editor chapter,
page 30. If a library has a Placeholder property defined, add it by using the Add
Library dialog box to help ensure that the correct placeholder resolution is used. If
no placeholder is used, you can add a definite library directly by specifying a direct
version.
NOTE: If a library or a later version of the library is forward compatible, it will
be automatically recognized by EcoStruxure Machine Expert and be
respected in the automatic update mechanism (Automatic button in the
Version mapping tab).

Updating Libraries and Library References

Overview
This topic describes the situations you can encounter when updating libraries.

EIO0000002829.03 21
 Library Management

Update Project Dialog Box

When opening an existing project in EcoStruxure Machine Expert, the Update
project dialog box is displayed, if one of the following elements has been installed
on the local system:
• A newer compiler version.
• A newer visualization profile, style, or symbol.
• A newer device version.
• A newer library version of one of the used libraries.
A forward compatible library (FCL) exists in the project where a device
version does not meet the device version constraints. Thus, not the latest
library is used in the project. For further information, refer to the chapter Step
2.1: Decide Whether Your Library Should Be Forward Compatible, page 46.

The following effects occur when you update your libraries using the Libraries tab
of the Update Project dialog box:

22 EIO0000002829.03
Library Management

If... Then...
If you deselect the option Update libraries from the Libraries tab, • No existing library reference is changed.
and you click Update. • A manual update of the libraries can be executed in the
Version mapping tab of the Library Manager.
• Legacy libraries are listed in the Version mapping tab, but
marked as legacy, if a newer, forward-compatible library
version exists.
• The Update project dialog box is displayed again next time
you open this project.
You can omit this by deselecting the option Check for
updates when opening this project in the Update project
dialog box or in the Project Settings.
NOTE: If you have selected the option Update devices in the
Update project dialog box, libraries referenced in the project
as placeholders will be updated to the corresponding
placeholder resolutions defined by the devices to be updated,
even if the option Update libraries has not been selected.

If you select the option Update libraries with the default option • The directly referenced libraries are updated.
Update all libraries (incl. Libraries declared with direct or • The libraries with at least one forward compatible library
newest version), and you click Update. version installed in the Library Repository and the version
mapping of former legacy versions are updated to the newest
forward compatible library version.
NOTE: There are libraries which will not be updated. This
concerns libraries which are listed and gray colored in the
Library Manager as required library via a reference in the
device description.

If you select the option Update libraries with the option Update all • The forward compatible libraries are updated to the newest
forward compatible libraries (keep existing legacy mappings) forward compatible library version.
from the list, and you click Update.
• The legacy libraries are converted into forward compatible
libraries. They are updated to the newest forward compatible
library version.
NOTE: There are libraries which will not be updated. This
concerns libraries which are listed and gray colored in the
Library Manager as required library via a reference in the
device description.

If you select the option Update all forward compatible libraries • The forward compatible libraries are updated to the newest
(replace existing legacy mappings) from the list, and you click forward compatible library version.
Update. • The legacy libraries are converted into forward compatible
libraries. They are updated to the newest forward compatible
library version.
• The libraries with at least one forward compatible library
version installed in the Library Repository and the version
mapping of former legacy versions are updated to the newest
forward compatible library version.
NOTE: There are libraries which will not be updated. This
concerns libraries which are listed and gray colored in the
Library Manager as required library via a reference in the
device description.

If you click Cancel. • No existing library reference is changed.

• Legacy libraries are listed in the Version mapping tab, but
marked as legacy, if a newer, forward compatible library
version exists.
• A manual update of the libraries, the device, the visualization,
or the compiler can be executed in the project.
• The Update project dialog box is displayed again next time
you open this project.
You can omit this by deselecting the option Check for
updates when opening this project in the Update project
dialog box or in the Project Settings.

EIO0000002829.03 23
 Library Management

Manual Library Update

If Then...
If you want to update forward compatible libraries manually, This manual update can be executed in the Version mapping tab
of the Library Manager.

Using the Automatic button for updating has the following effects:
• The forward compatible libraries are updated to the newest
forward compatible library version.
• The legacy libraries are converted into forward compatible
libraries and are updated to the newest forward compatible
library version.
For updating only one library, right-click on the respective library in
the Version mapping tab and select Edit version mapping
(selected library).

If you want to update non-forward compatible libraries manually, This manual update can be executed in the Libraries tab of the
Library Manager:
1. In the Libraries tab, right-click a library and execute the
command Properties.
Result: The Properties dialog box is displayed.
2. In the Properties dialog box, select one of the versions
installed on the local system from the Specific version list,
and click OK.

Manual Device Update

When manually updating a device description using Update Device..., the
following libraries are updated too:
• Libraries which are automatically included by the device.
• Libraries which are included as placeholders and are resolved by devices.
• Forward compatible libraries.
To update a device (see EcoStruxure Machine Expert, Programming Guide), right-
click the device in the Devices tree and select Update Device...

Project Created with Previous Version

In a project created with a previous version of EcoStruxure Machine Expert
software, the versions of the libraries declared in the project are modified as
follows:
• The library versions are kept unchanged for libraries declared with a direct
version, page 14.
• They are automatically updated with the newest version, page 15 for libraries
declared using the newest version method (version identified with * in the
Library Manager).
• They are automatically updated with the versions defined in the controller
Device Description File after a controller device update command for libraries
declared using the placeholder mechanism, page 16.

Check Library Compatibility

Overview
The Check Library Compatibility command allows you to verify whether the
open library project is compatible with the installed version of this library.
By default, the command is not available in the menus. Add this command via the
Tools > Customize menu.

24 EIO0000002829.03
Library Management

Step Action Comment

1 In the Menu tab of the Customize dialog box, –

expand the Build node.

2 Select an empty subnode, and click the Add Result: The Add Command dialog
command... button. box opens.

3 In the Add Command dialog box, select –

Categories: > Build.

4 From the Commands: list, select the command –

Check Library Compatibility.

5 Click OK. Result: The Add Command dialog

box closes and the Build node of
the Customize dialog box contains
the option Check Library
Compatibility.

6 Select the option Check Library Compatibility, Result: The Customize dialog box
and click the OK button. closes.
7 Restart EcoStruxure Machine Expert. Result: The Check Library
Compatibility command is
available in the Build menu.

In the Messages view, appropriate messages are reported for the following cases.
They mean that the interface of a POU has been modified:
• Adding or removing inputs and outputs of function blocks, functions, or
methods
• Modifying the data type of inputs and outputs
• Modifying the implemented interfaces of a method

EIO0000002829.03 25
 Library Manager Editor

Library Manager Editor

Library Manager Editor
Overview
Double-click a Library Manager node in the Tools tree to open the Library
Manager in an editor view.
The Library Manager editor view consists of four parts:
• The upper part, displaying libraries included in the project.
• The lower left part, displaying particular modules of the library selected in the
upper part.
• The lower right part, displaying further information on the module selected in
the lower left part in different tabs.
• A toolbar with buttons and commands.

26 EIO0000002829.03
Library Manager Editor

Description of the Upper Part

The upper part of the view provides a list of the libraries included in the project. If a
library depends on other libraries (referenced libraries), these referenced libraries
are automatically integrated.
The following information is provided:

Parameter / Symbol Description

Name The library names in the list consist of the following elements:

<placeholder name> = <library name>, <version>

(<company>)

<placeholder name>: If the entry of the list is a placeholder library

for a linked library, then the placeholder name is inserted at the
beginning of the line, separated by an = (equals sign) character.

<library name>: Name of the library that is used in the Library

Repository.

<version>: The version of the library when it was referenced for the
first time.

<company>: The vendor of the library (optional).

Namespace The default setting for the namespace of a library is <library name>.
An exception is made by libraries that have another namespace in
their Project Information. Use the library namespace (see
EcoStruxure Machine Expert, Programming Guide) as a prefix of the
identifier separated by a . (dot) character:

<namespace>.<library module identifier>

NOTE: If the library has the property LanguageModelAttribute
> qualified-access-only, you must access the library module in
the application code by using the namespace. Qualified (unique)
access is required.
You can modify the standard namespace for local use (within the
project) in the Properties dialog box, page 32.

Effective Version Version of the library after the resolution. This version is used in the
project.

The Effective Version is displayed for placeholder libraries if the

Library Manager has been opened from the Devices tree.

Example: 3.5.10.0
NOTE: For placeholder libraries, the effective version is
determined by the search order listed in Placeholder Mechanism,
page 16.
NOTE: For FCL libraries, the effective version is determined by
the version configured in the Version Mapping tab of the Library
Manager, page 39.

This tooltip symbol informs you about the resolution of the selected
placeholder library, which deviates from the default.

Example when the Library Manager is in the Devices tree: The

placeholder is explicitly redirected to this version (see the
Placeholders dialog box, page 35).

Example when the Library Manager is in the Global node of the

Tools tree:

In the 'Device 1' device, the placeholder is resolved to

VisuElemsAlarm 1.0.0.0 (System).

Library that is signed with a trusted certificate.

Library that is signed with a trusted certificate, but references at least

one unsigned library.

Library that is signed with a private key and token.

Library that is not signed, or signed with an untrusted or expired

certificate. In the case of an untrusted certificate, the Trust Certificate
command is provided in the context menu.

Library is not resolved and will not be included in the compile.

EIO0000002829.03 27
 Library Manager Editor

Parameter / Symbol Description

Library that is defined as optional and not available.

Library whose status is being determined.

Licensed library for which no valid license is available.

Library symbol for a library that cannot be loaded because its signature
(encryption) could not be verified.

Libraries that have been automatically added to a project by adding a certain

device or object, are displayed in gray; those that have been added manually by
using the Add library... command are displayed in black.
If a library has dependencies on other libraries (referenced library, page 13), those
are automatically included - if available - and are displayed with icon for
referenced libraries in a subtree of the entry. Expand or collapse a subtree by
clicking the respective plus or minus sign.

Description of the Lower Part

In the lower left part of the editor, the particular modules of the library selected in
the upper part (the libraries list) are displayed in a tree structure.
The lower right part of the editor can contain the following tabs:

Tab Description

Documentation The information provided in this tab is library-specific information that

is provided in the library file.

For user documentation on Schneider Electric libraries, refer to the

Library Guide documents provided in the EcoStruxure Machine Expert
online help. For third-party libraries, refer to the corresponding
documents from the third party.

When creating a library, consider the items listed in the chapter Create
Your Own Library, page 43.

Inputs/Outputs The components of the selected library module are listed in a table
with variable Name, data Type, Inherited from, Address, Initial
value, and Comment, as defined in the library.

Graphical Graphical representation of the module.

Library Parameters This tab is available when a Global Parameter List is selected. For
modifying library parameters, execute the command Library
Parameters... to open the Library Parameters dialog box.
NOTE: Library parameters can only be displayed and configured
in the Library Manager of applications.

28 EIO0000002829.03
Library Manager Editor

Buttons and Commands

The following commands, which are provided in the editor view when one or
several libraries are selected, correspond to those of the libraries. This is, by
default, available in the menu bar as long as the Library Manager editor is active:

Command Description

Add library To include a library into the project

The precondition is that the library is installed on the local system. A

message appears in case of trying to insert a library which is already
available in the project, page 30.

Delete library To delete the library selected in the library list from the project.

Properties To edit general settings about the selected library such as the
namespace version handling, visibility and accessing. Refer to the
Properties... chapter, page 32.

Details To display a dialog box with details about the library (general
information, contents, properties, license information).

Try to reload library If a library has not been found, then select it and execute this
command, page 33 to attempt to reload it into the project.

Placeholders To redirect any placeholder and library group to a different version.

Refer to the Placeholders... chapter, page 35.

Library parameters Opens the Library Parameters dialog box that allows you to display
and configure the parameters of the libraries that are available in the
Library Manager of the Application node for each controller.
NOTE: Library parameters can only be displayed and configured
in the Library Manager of applications.

Library repository To define library locations and to install or uninstall libraries. Refer to
the Library Repository chapter, page 36.

Icon legend Opens the Information dialog box with a legend of the icons that
display the status of a library in the list of integrated libraries.

Summary Opens the Library Summary dialog box that displays the libraries
referenced in the project in a tree structure including the libraries that
are referenced by these libraries.

Select a library and execute the command Display all occurrences in

library hierarchy and close dialog or double-click a library to
highlight in the Library Manager editor the libraries that reference or
use the selected library.

Display of the libraries:

• Managed Library: Name and version of the library
• Number of Occurrences: Number of locations where this library
is referenced by other libraries
When you click the plus sign of a library, the libraries that reference
this library are displayed in the next sublevel.

Command Description

Trust certificate Available in the context menu of a library selected in the Library
Manager editor, in which the library has been signed with an untrusted
certificate. The command turns the untrusted certificate into a trusted
certificate and the prepended icon changes from to .

Export library Available in the context menu of a library selected in the Library
Manager editor: Opens the default dialog box for saving the library file
in the file system.

EIO0000002829.03 29
 Library Manager Editor

Add Library
Overview
Two types of Add Library commands are available:
• The Add Library command.
• The Add library without placeholder resolution command.

Add Library Command

The Add Library command is accessible in the Libraries menu and in the
Library Manager editor by clicking the Add Library button. It opens the Add
Library dialog box that allows you to add libraries to the Library Manager and
then integrate them into your application. For each library, a suitable referencing
method is by default selected. To modify this default referencing method, refer to
the Add library without placeholder resolution Command, page 31.
The Add Library dialog box provides the following elements and functions:

Element / Function Description

Search function In the line above the library list, enter a string to find in the list (such as
library names or library POUs).

Groups the displayed libraries by library category.

Lists the displayed libraries in alphabetical order.

Library column The libraries installed in the library repository are listed. By default, the
libraries are grouped by library category.

Company column Indicates the vendor of the library.

NOTE: If you cannot find a specific library in the Add Library dialog box, but
the library is available in the Library Repository, this library may be blocked
for this device in the device description.
For further information, refer to Library Management, page 13.

30 EIO0000002829.03
Library Manager Editor

Add library without placeholder resolution Command

By default, this command is not available in the Libraries menu. To display it,
activate the option Show obsolete command “Add libraries without
placeholder resolution” in the Advanced tab of the Tools > Options >
Libraries dialog box. It displays an extended Add Library dialog box that allows
you to modify the default referencing method that has been assigned to the library
by the vendor.
NOTE: Add the correct version of your library. In the event that several
EcoStruxure Machine Expert library versions are installed, add the library
version that is displayed when you select Location = System in the Library
Repository dialog box, page 36. For additional information, see the guidelines
for creating libraries, page 43.
This extended Add Library dialog box consists of two tabs:
• The Library tab allows you to assign a direct reference for the selected
library.
• The Placeholder tab allows you to enter a placeholder or select a
placeholder from the list of available placeholders and add it to the library as
placeholder resolution.
The dialog box provides the following functions and options to support you in
selecting the suitable library:
• The same search function as in the Add Library dialog box.
• Option Group by category to group the displayed libraries by library
category when the option is selected or in alphabetical order when the option
is unselected.
• Option Display all versions (for experts only) to display the installed
versions of the libraries indented below the selected library entry when the
option is selected.
The Library Repository button opens the Library Repository dialog box, page
36 that allows you to add libraries that are not yet installed on the local system.

EIO0000002829.03 31
 Library Manager Editor

Properties
Overview
In the Library Manager editor view, click the Properties button to open the
Properties dialog box for the selected library. It allows you to configure the
namespace, version handling, availability, and visibility of library references.
Properties dialog box for a library:

Properties – TcpUdpCommunication Library, x.x.x.x (Schneider Electric)

General: Version:

Namespace: TCPUDP Specific version: x.x.x.x

Default library: ... Newest version always

Visibility:

Only allow qualified access to all identifiers.

If the current project is referenced as a library by another project:

Publish all IEC symbols to that project as if this reference would have been included there directly.

Hide this reference in the dependency tree.

Optional (if the library is missing, no error will be reported).

OK Cancel

NOTE: Before working on library projects and modifying namespaces, version

and visibility settings, read the guidelines for creating libraries, page 43.

General Area of the Dialog Box

Parameter Description

Namespace The namespace of the library is displayed.

The default namespace of the library for accessing functions of the

library.
NOTE: It is a good practice to use the default namespace in
accordance with your application.
For further information, refer to the Library Manager editor view
description, page 27.

Default library If a library placeholder is selected in the Library Manager, this field
contains the name of the library which replaces the placeholder if no
device-specific library is available. Refer to the Placeholder tab.

Version Area of the Dialog Box

Configure the version of the library that is used in the project if the selected library
is not a library placeholder:

Parameter Description

Specific version Enter the version or select one from the list that is used in the project.
To be used for container libraries, page 47.

Newest version always The latest version found in the library repository is used. The modules
used can change because a more recent version of the library is
available. To be used for interface libraries, page 47.

For common libraries, do not specify version constraints, but use a

placeholder reference, page 48.

32 EIO0000002829.03
Library Manager Editor

Visibility Area of the Dialog Box

The settings of the Visibility area are of interest as soon as the library is included
and referenced by another library. By default, they are deactivated:

Parameter Description

Only allow qualified If this option is enabled, the usage of the namespace is mandatory.
access to all identifiers
If the current project is NOTE: Modify the following settings if you intend to create a
referenced as a library
library project. It has the effect that the selected library is
by another project. referenced in the new library.

Publish all IEC symbols If the present project is a container library, activate this option for the
to that project as if this selected library to make its objects visible at the top level later in the
reference would have project.
been included there
directly Symbolic access to library modules:

<namespace of container library>.<module name>

NOTE: Only activate this option if the present project is a
container library, not containing own modules, but just including
other libraries for packaging them. This packaging for example
allows you to include multiple libraries in a project at once just by
including the container library. In this case, it can be desired to
have the particular libraries on top level of the Library Manager
of the project.
This option is relevant if a library B was added to a library A inside a
project that uses library A:

If the option is activated, you can access components of library B by

using the namespace of library A.

Example: NamespaceLibA.ComponentOfLibB

If this option is deactivated, the contents of the selected library is

accessed uniquely by using the namespace. For unique access to a
module from the selected library, the namespace of the present library
and the namespace of the selected library are prefixed to the module.

Unique symbolic access to the library module:

<NamespaceLibA>.<NamespaceLibB>.<ComponentofLibB>

Hide this reference in If this option is activated, the selected library is not displayed (later in a
the dependency tree project) in the Library Manager as a library reference. This allows you
to include hidden libraries into a library. This requires careful use
because if library detected error messages are issued, it may be
difficult to identify the causing library.

If this option is deactivated, the selected library is displayed as a library

reference (later in a project).

Defining the Library as Optional

Parameter Description

Optional (if the library is If this option is activated, the selected library is handled as optional.
missing, no error will be When downloading the project which references the library, no error is
reported) detected, even if the library is not available in the library repository.

Try to Reload Library

Overview
If a library included in a project is for any reason not available at the defined path
when opening the project in the programming system, an appropriate message
will be generated.

EIO0000002829.03 33
 Library Manager Editor

After you have made the library available again, execute the Try to Reload
Library command in the Library Manager editor view when the library entry is
selected. The command is also available in the context menu if you right-click a
library entry. Thus, the library can be reloaded without the necessity of leaving the
project.

Exporting Library Files

Overview
You can export a library from the Library Manager of a project or from the Library
Repository to save it to the hard disk.

Exporting a Library from the Library Manager

To export a library from the Library Manager, proceed as follows:

Step Action Remark

1 Open the Library Manager of an application in a project. –

2 Select a library in the upper part of the Library Manager –

editor.
3 Execute the command Export Library... from the Libraries Result: The Export Library dialog box opens.
menu, or right-click the library and execute the command
Export Library... from the contextual menu.

4 Enter a file name. –

5 Select an entry from the Save as type list. If the selected library is linked in the project not only as a
compiled library, but also in source format, then one of the
two file types is available for selection:
• Compiled library files (*.compiled-library)
• Library files (*.library)

6 Click the Save button. –

Exporting a Library from the Library Repository

To export a library from the Library Repository, proceed as follows:

Step Action Remark

1 Open the Library Repository from the Tools menu. –

2 Select a library in the Installed Library list. –

3 Click the Export... button. Result: The Export Library dialog box opens.

4 Enter a file name. –

5 Select an entry from the Save as type list. If the selected library is linked in the project not only as a
compiled library, but also in source format, then one of the
two file types is available for selection:
• Compiled library files (*.compiled-library)
• Library files (*.library)

6 Click the Save button. –

34 EIO0000002829.03
Library Manager Editor

Placeholders
Overview
In the Library Manager editor view, click the Placeholders button to open the
Placeholders dialog box. It provides information about the placeholders available
in the project with their definition for resolution and allows you to assign a
resolution that is valid for the open project.
NOTE: Carefully consider the possible effects of changing the library
referencing. Also consider the guidelines for creating libraries, page 43.
Placeholders
Set all unresolved unbound placeholders to the newest available versions

Name Library Info

BreakpointLogging Breakpoint Logging Functions, 3.5.17.0... Resolved by Essentials (3.5....
CAA Behaviour Model CAA Behaviour Model, 3.5.19.0 (CAA Te... Resolved by device
CAA CANopen Manager CAA CANopen Manager, 4.1.0.0 (CAA T... Unbound placeholder
CAA CANopen Stack CAA CANopen Stack, 4.1.0.0 (CAA Tec... Unbound placeholder
CAA CiA405 CAA CiA405, 4.1.0.0 (CAA Technical W... Unbound placeholder
CAA Device Diagnosis CAA Device Diagnosis, 3.5.19.10 (CAA T... Resolved by device
CAA Tick CAA Tick Extern, 3.5.17.0 (CAA Technical... Resolved by device
CAA TickUtil CAA TickUtil Extern, 3.5.17.0 (CAA Tec... Resolved by device
CAA Types CAA Types Extern, 3.5.17.0 (CAA Techni... Resolved by device
CDS_MemMan CoDeSys Memory Manager, 3.5.18.0 (3S... Resolved by Essentials (3.5....
CmpApp CmpApp, 3.5.17.0 (System) Resolved by device
CmpAsyncMgr CmpAsyncMgr, 3.5.17.0 (System) Resolved by device
CmpErrors CmpErrors, 3.3.1.40 (System) Resolved by device
CmpEventMgr CmpEventMgr, 3.5.17.0 (System) Resolved by device
CmpEventMgr Implementation CmpEventMgr Implementation, 3.5.17.0 (... Resolved by device
CmploMgr Implementation CmploMgr Implementation, 3.5.17.0 (Syst... Resolved by device
CmpLog CmpLog, 3.5.17.0 (System) Resolved by device
CmpER CmpER, 3.5.1.0 (System) Resolved by device
OK Cancel

Element Description

Name Identifier of the placeholder

Library Resolution for the project

To switch to another version of the library, double-click the cell to edit

the placeholder resolution. A list of the available versions of the
selected library is displayed below the entry Other versions of
<library>.

To assign another library, execute the command Other library.... The

Browse Library dialog box opens for searching and, if necessary, for
installing the desired library.

Info Type of placeholder resolution:

• Resolved by device description
• Resolved by license mechanism
• Resolved by plugins
• Free placeholder resolved by <special library with fixed version>

Set all unresolved Click to resolve unresolved placeholder libraries in the Library
unbound placeholders Manager. The latest available version will be used.
to the newest available
versions

EIO0000002829.03 35
 Library Manager Editor

Library Repository
Overview
Open the Library Repository dialog box via the Tools > Library Repository...
command or by clicking the Library repository button in the Library Manager
editor.
A library repository is a database for libraries which have been installed on the
local system in order to be available for EcoStruxure Machine Expert projects.
NOTE: A library project *.library, which is stored in a library repository, cannot
be opened there for editing or viewing in the programming system.
The dialog box shows the defined library Locations (repositories) and the
installed libraries.
It allows you to:
• Add, modify, or remove repositories
• Install, uninstall, and export libraries
The Library Repository dialog box contains the following elements:

Parameter Description

Location list Select a directory on the local system where library files are stored.

Select System to display the standard libraries provided by

EcoStruxure Machine Expert in the Installed libraries list.

Select User to display those libraries you defined by yourself in the

Installed libraries list.
Company list Select a name to display those libraries provided by a primary provider
(or group name defined by the primary provider) in the list of Installed
libraries.

To display the libraries available at the selected Location, select (All

companies) from the list.

Installed libraries list The list shows libraries that are available at the selected Location
from the selected Company by their names (title), version number,
and company name as provided by the project information of the
library.

Group by category Activate the option Group by category to sort the Installed libraries
option list according to the library categories. The category names are
displayed as nodes which can be folded or unfolded to show/hide the
libraries.

Deactivate this option to list the libraries alphabetically.

Edit Locations... button Refer to the paragraph Library Locations (Repositories), page 36.

Install... / Uninstall Refer to the paragraph Library Installation and Uninstallation, page 38.
buttons
Export... button Opens the dialog box for saving the library project to the local file
system. The data type is *.library or *.compiled-library (depending
on the type of the selected library).

Find... button Refer to the paragraph Find Libraries, page 38.

Details... / Refer to the paragraph Further Information on Particular Libraries,

Dependencies... buttons page 39.

Library Profiles... button Opens the Library Profiles dialog box. With compiler versions of
EcoStruxure Machine Expert V2.2 and later, library profiles are ignored
for placeholder resolution.

Library Locations (Repositories)

You can use several repositories to manage libraries. The defined repositories are
shown in the Location list. By default, it contains the entries System for standard

36 EIO0000002829.03
Library Manager Editor

libraries provided by EcoStruxure Machine Expert and User for those libraries that
you defined.
To edit the path or name of a repository, click the Edit Locations... button.
The Edit Repository Locations dialog box displays:

The Edit Repository Locations dialog box contains the following elements:

Parameter Description

Repositories list Lists the defined locations. They are searched later for a library in the
given order from up to down.

Move up / Move down Modifies the order of the libraries. The selected location is moved up or
buttons down in the list.

Consider that the setting Location: <All locations> displays the libraries of the
previously defined locations. No installation is possible in this view.

Defining a New Repository or Modifying Path and Name of an

Existing Repository
Click the Add... button of the Edit Repository Locations dialog box to add a new
repository. The Repository Location dialog displays.
To modify an existing repository, select the respective entry in the Edit
Repository Locations dialog box, and click the Edit... button. The Repository
Location dialog box displays.
The Repository Location dialog box contains the following elements:

Parameter Description

Location box Enter the path of the new repository or edit the path of the selected
repository.

To browse for a folder or to create a new folder, click the ... button.

Verify that the selected folder is empty.

Name box Enter a symbolic name for the location, for example Libraries for
System1.

NOTE: The folder that is selected as a repository folder has to be empty. The
System repository is not editable. This is indicated by the entry being
displayed in italic font.

EIO0000002829.03 37
 Library Manager Editor

Removing an Existing Repository

To remove a repository, select it in the Edit Repository Locations dialog box,
and click the Remove button. A message is displayed asking you whether just the
entry in the list should be deleted, or if also the folder containing the library files
should be removed from the file system.

Library Installation and Uninstallation

You can include those libraries in a project that are installed on the local system
(Library Repository). As a precondition for the installation, it must be assigned at
least a Title, Version info, and a Company name in the Summary tab of the
Project Information dialog box.
To install a library, select the repository to which the library should be added in the
Library Repository dialog box, and click the Install... button.
The Select Library dialog box opens. This is a standard dialog box for browsing
for a file. By default, the Files of type filter is set to Compiled library files. You
can modify the filter to Library files, or to All files.
Select the desired library and click Open. The library is added to the list of
installed libraries in the Library Repository dialog box.
If you select a library which cannot be installed because it does not provide the
obligate Project Information (title, version, company), an appropriate message
displays.
To uninstall a library, select it in the list of installed libraries in the Library
Repository dialog box, and click the Uninstall button.

Find Libraries
To search for a library in the specified storage location, click the Find button in the
Library Repository dialog box. The Find Library dialog box opens. It allows you
to search for function blocks and the corresponding libraries.
Find Library dialog box

38 EIO0000002829.03
Library Manager Editor

Enter the search string for the function block and the corresponding libraries. In
addition, you can also enter the wildcards * and ?.

Further Information on Particular Libraries

To display further details for the selected library, select the line of the library
containing the version, and click the Details... button. A Details dialog box
displays, providing further information from the Project Information of the library.
To get even more detailed information, click the More... button.
To display the dependencies concerning other libraries for the selected library,
select the line of the library containing the version and click the Dependencies...
button. A Dependencies dialog box displays, listing those libraries which are
included in the selected library with Title, Version, and Company information.
References working via placeholders are listed according to the following syntax:
#<placeholder name>.
For details on library placeholders, refer to the Placeholder Mechanism chapter,
page 16.

Version Mapping Tab

Overview
The Version mapping tab of the Library Manager allows you to edit the version
mapping for forward compatible libraries (FCL), page 18.
The Version mapping tab consists of three tables:
• The upper table lists the forward compatible libraries that are included in the
EcoStruxure Machine Expert project.
It also lists legacy libraries if a newer, forward compatible version of these
libraries exists. Legacy libraries are libraries that have been created with a
SoMachine version 3.1 or less and that are not forward compatible. You can
recognize these libraries by the entry Legacy in the Configured version
column of the table.
It also lists legacy libraries if a newer, forward compatible version of these
libraries exists. Legacy libraries are not forward compatible. You can
recognize these libraries by the entry Legacy in the Configured version
column of the table.
• The two lower tables provide further information on the library selected in the
upper table. The left table displays dependencies on other forward compatible
libraries and the right table displays dependencies on device descriptions and
whether the compatibility criteria have been met.
The Library Manager of the Tools tree compares the device descriptions
with the root devices (controllers) in the Devices tree. If the Library Manager
is inside a library, it compares the device descriptions with the devices
containing the attribute MinimumControllerFirmware which can be defined in
the Project Information dialog box, page 46.

EIO0000002829.03 39
 Library Manager Editor

Changing the Version of a Library

The Version mapping tab of the Library Manager allows you to edit the version
mapping of the libraries in different ways:
• You can automatically perform the version mapping for the libraries listed in
the table by clicking the Automatic button. This has the following effects:
◦ The forward compatible libraries are updated to the newest forward
compatible library version available.
◦ The legacy libraries are changed into forward compatible libraries and are
updated to the newest forward compatible library version available.
• You can perform the version mapping for one specific library manually. To
achieve this, right-click the library and execute the command Edit version
mapping (selected library). Then you can select the dedicated version
number to be used for this library.
• Alternatively, you can click the Configured version column to open a list
displaying the available versions. Select the desired version from the list.

Library with Unresolved Dependencies

FCL libraries with unresolved dependencies are displayed with a red background
in the upper table. Select this library to display further information about required
dependencies and compatible versions in the lower table. Unresolved
dependencies are marked red in the lower table. For example, if no compatible
device version is used in the project, then the line Accepted device description
is marked red. If a required library dependency is missing, then the line Required
forward compatible libraries and the unfulfilled library dependency are marked
red.

Unsupported Devices
If a device is listed in the device dependencies details table as compatible, but is
not installed in the version of EcoStruxure Machine Expert that you are using, then
the text Unsupported device is displayed in the line, together with the device ID.

Library Updates Tab

Overview
The Library Updates tab of the Library Manager allows you to configure folders
where new or updated libraries are stored in order to facilitate the updating
process.
You can search, install, and reference updates for libraries within an EcoStruxure
Machine Expert project. In the Library Manager editor view, click the Library
Updates tab. The menu in the tab Library Updates allows you to decide whether
a referenced library is automatically updated.

40 EIO0000002829.03
Library Manager Editor

Configuring Folders for Library Updates

In order to configure folders where you can store new libraries or libraries that
should be installed or updated, proceed as follows:

Step Action

1 In the Library Updates tab of the Library Manager, click Configure Library Sources.

Result: The dialog box Tools > Options > Library Updates opens, showing a list of
Available Library Sources.

2 Click Add to add a folder to the list of Available Library Sources.

Result: The dialog box Library Source opens.

3 Enter a Name for the new library source and browse to the Location of the folder in the
network.
4 Select the option Include Subfolders when searching for updates to extend your
search.
5 Select the option Only install released libraries from this source if you want only
released libraries to be shown.
6 Select your preferences concerning open or compiled library types:
• Prefer Compiled: If a library is available as open and as compiled library, the
compiled version is considered.
• Prefer Open: If a library is available as open and as compiled library, the open
version is considered.
• Compiled only: Compiled libraries are considered.
• Open only: Open libraries are considered.

7 Click OK.

Result: The selected folder is added to the list of Available Library Sources. You are
returned to the Library Updates tab of the Library Manager.

Verifying the Folders

In order to verify whether new libraries or library updates are available in the
specified folders, click Check for Updates in the Library Updates tab.
Result: The specified folders are scanned for new library updates and the results
are displayed in a list:

Forward compatible libraries (FCL, page 18) are considered for the updating
process. Non-forward compatible libraries are ignored.
If a library detected in the folder is of a later version than the referenced library, the
library is presented as a library update.

EIO0000002829.03 41
 Library Manager Editor

Installing Detected Updates

In order to install the updates that have been detected, proceed as follows:

Step Action

1 From the list of detected libraries in the tab Library Updates, select the libraries you
want to be updated or click the Select all button.

2 Click the Update Selected Libraries button.

Result: The libraries are updated or installed. The procedures that are performed are
indicated in the Messages view.

42 EIO0000002829.03
Create Your Own Library

Create Your Own Library

General Information
Overview
For compatibility reasons, consider the guidelines described in the following
chapters when creating a library.
When creating a library, consider the following main items:
• Define a library name that is consistent with the contents of your library
(required).
• Use a familiar and as far as possible consistent project structure (optional).
• Fill in the Project Information (required).
• Select a unique library namespace (required).
• Use the appropriate mechanism, depending on the methodology chosen, for
referencing other libraries (required).
• Design usable external and internal interfaces (required).
• Implement an error handling routine (required).
• Use the appropriate method (protection) for deployment (required).
• Follow a naming convention for code that helps to read and debug (optional).
When creating a library project, follow the steps described in the following
chapters.

Step 1: Setup the Project

Overview
Create a new library project by executing the commands File > New Project.... In
the New Project dialog box, select, Library from the Project type list, and define
the name and details as described in the New Project section of the EcoStruxure
Machine Expert online help.

Step 2: Fill-in the Project Information

Overview
Specify information on the project in the Project > Project Information dialog
box. This dialog box consists of several tabs. Pieces of information required for
creating your own library are described here.

Summary Tab
Specify the following information in the Summary tab of the Project Information
dialog box:

Parameter Description

Company Obligatory: Enter a company for the project.

Title Obligatory: Enter a name for the project.

EIO0000002829.03 43
 Create Your Own Library

Parameter Description

Version Obligatory: Enter a version for the project.

Released Select the option to help protect the library from later modifications.

When you later attempt to save the library, you are prompted when this
flag has been set to Yes, and asked if you wish to reset the flag:
• If you click Yes, the flag is reset.
• If you click No, the flag is preserved and the project is not saved.

Default namespace Allows you to make each symbol unique, even if the same symbol
name is used in different libraries

If you do not define a namespace, the library name is used as

namespace. It is better to define a unique one. After the library has
been included in a project, you can still modify the namespace in the
Properties dialog box of the Library Manager - if necessary.

For enforcing the namespace, see the separate section in this chapter.

Library Categories Provides helpful sorting of the entries in the Library Repository and
Library Manager

If possible specify another category than Miscellaneous from the

following categories:
• Application libraries which must be inserted explicitly in a
project. Designed for direct access from end-user code.
• Internal libraries which are automatically inserted in a project
and normally should not be inserted or removed manually.
• System libraries depending directly on the runtime system or
implement parts of it. They should not be inserted directly in the
project, but be referenced by other libraries. They are not
intended to be included in the user application directly. (No
resource management is provided like, for example, deleting of
resources on the controller in order to get serial interfaces closed
before a further download is done).
NOTE: When you create a new library, define the library
categories by external description files *.libcat.xml.

Author Enter the name of the author of this project.

Description Enter a short description of the library content.

Automatically generate
NOTE: When calling these POUs, prefix them with the
‘Library Information
corresponding library namespace. For calling the POUs of the
POUs’
project POUs tree, prefix them with the namespace __Pool.
Automatically generate
‘Project Information
POUs’

WARNING
UNINTENDED EQUIPMENT OPERATION
Do not use the parameters "Automatically generate ‘Library Information POUs’"
and "Automatically generate ‘Project Information POUs’" unless you modify the
namespace as directed above.
Failure to follow these instructions can result in death, serious injury, or
equipment damage.

Enforcing the Namespace

It can be enforced that the namespace must be preceding in any case when
accessing library modules or variables, from the application as well as from
another library. For this purpose, set the property LanguageModelAttribute
(Text) :='qualified-access-only' in the Properties tab.
Key name: LanguageModelAttribute
Type: Text

44 EIO0000002829.03
Create Your Own Library

Value: qualified-access-only (see figure below).

Compile errors are detected if a library module or variable is used without
preceding namespace.
Properties tab: Settings for enforcing the namespace:

Properties Tab
List of configurable properties:

Property Type Value Description

Author Text <author name> Author of the library version

Company Text <company name> Serves to filter the libraries in the

Add Library dialog box

DefaultNamespace Text <namespace> Worldwide unique namespace

prefix

Description Text <description> Short description on the scope of

the library

ForwardCompatibleLibrary Boolean TRUE|FALSE This library is a forward

compatible library (FCL).

LanguageModelAttribute Text 'qualified-access-only' Symbols of this library can only

be accessed via the namespace
prefix

Project Text <library project name> # Name of the library project

Title Text <library name> # Name of the library

Version Text <library version> Version of the library

Released Boolean TRUE|FALSE Library must not be modified

after release
Placeholder Text <placeholder> The placeholder that is used for
referencing this library when
adding the library using the Add
Library dialog box.

IsContainerLibrary Boolean TRUE|FALSE This library follows the rules for a

container library

EIO0000002829.03 45
 Create Your Own Library

Property Type Value Description

IsInterfaceLibrary Boolean TRUE|FALSE This library follows the rules for a

container library

IsEndUserLibrary Boolean TRUE|FALSE This library is especially

designed regarding the needs of
an end user

Step 2.1: Decide Whether Your Library Should Be Forward

Compatible
Overview
When creating your own library, you can decide in the New Project dialog box
whether the library should be forward compatible or not (refer to the New Project
section of the EcoStruxure Machine Expert online help).
You can also make an existing library forward compatible.
Set the attribute ForwardCompatibleLibrary in the Project Information of your
library project to create your own forward compatible library. For further details,
refer to the procedure below.
NOTE: Setting the ForwardCompatibleLibrary key means that your library and
its subsequent versions meet the following requirements:
• The functionality of a previous version is available in a later version.
• The POUs of the previous versions are available.
• The behavior of the POUs is identical in the previous and the later
versions of your library.
• The visibility of the POUs of the previous version is equal or greater than
in the later version.
• Names and data types of your inputs and outputs are unchanged in the
different versions.
NOTE: If the library project includes a device that does not meet the version
constraints, the Update Project dialog box, page 22 will be displayed each
time the project is opened.
Additionally, an optional attribute (MinimumControllerFirmware) can be set if a
device dependency exists. The attribute indicates the necessary minimum
firmware version for the supported controllers. It is necessary if a library uses
POUs from another library that is referenced as a placeholder and the placeholder
resolution is not a forward compatible library.
The MinimumControllerFirmware attribute consists of a manufacturer and device
identification number, as well as the necessary minimum firmware version.

Procedure
NOTE: The following procedure describes the steps that are necessary for
creating a forward compatible library.

46 EIO0000002829.03
Create Your Own Library

Step Action

1 In the menu Project > Project Information open the Project Information dialog
box, select the Properties tab, and enter or choose the following entries:
• Key field: ForwardCompatibleLibrary
• Type field: Boolean
• Value field: True
2 Click Add for adding the key to the Project Information of your library.

3 If required, also add the optional attribute MinimumControllerFirmware.

In the File Project > Project Information enter or choose the following entries:
• Key field: MinimumControllerFirmware
• Type field: Text
• Value field: device category “/” vendor and device id “/” version, for example
4096/1003 0082/1.33.2.0
If several devices shall be considered in the MinimumControllerFirmware attribute,
then the identification numbers have to be entered into the Value field together,
separated with a |.

For example:
• 4096/1003 0082/1.33.2.0|4096/1003 009D/1.35.1.1

Step 3: Reference Other Libraries, if Needed

Overview
When you include other libraries, define their visibility and the version to be used.

Visibility
In the Properties, page 32 of each referenced library, define the behavior when
being inserted in a project along with its parent library.
Consider whether a referenced library should be hidden (not visible in the Library
Manager), or if it is useful to create a container library (a library project containing
library references):

Hidden library Deactivate the visibility of the library in the Library Manager
below the parent library by selecting the option Hide this
reference in the dependency tree in the Properties dialog
box, page 32.

Thus, hidden libraries can be available in a project.

Container library A container library (*_Cnt.library) is a library project which does

not define modules, but references other libraries. With
container libraries, the access to the modules of these libraries
is simplified.

Create a container library if you want to include a set of

libraries in a project at one time by including that container
library. In this case, you can simplify the access to the modules
of these libraries by making them top-level libraries. This allows
you to leave out the namespace of the container library in the
access path.

To achieve this, select the option Publish all IEC symbols to

that project as if this reference would have been included
there directly in the Properties dialog box, page 32.

Select this option only for a container library.

EIO0000002829.03 47
 Create Your Own Library

Version Constraints
• Interface libraries are referenced with the constraint newest. To achieve this,
select the option Newest version always in the Properties dialog box, page
32 after you have added the library to the Library Manager.
• Common libraries are referenced by a placeholder reference. This provides
consistent relationships between different libraries. An update of an indirectly
referenced library does not require modifications of each affected library but a
modification of the placeholder definition, page 35.

Step 3.1: Use Placeholder References

Overview
For referencing common libraries, use placeholder references.
Use library placeholders to make a project compatible for interchangeable target
devices or for different compiler versions. When adding a library to a project,
consider using a placeholder instead of a specific library version. Then the
required version of a library is referenced, according to the valid definition of the
placeholder resolution.
The search order for the placeholder resolution is (highest priority first):
1. Placeholder definition in the Placeholders dialog box of the library manager
(s) of the application(s)
2. Placeholders defined in device descriptions of the devices used
3. Placeholders defined by plugin code
4. Placeholders dialog box of the Library Manager in the Global node of the
Tools tree.
NOTE: This is the final and effective resolution. Modify it only after careful
consideration.

Step 4: Design and Program the Library Modules

Consideration
NOTE: Select a library structure that suits the intended usage. For example,
the structure of folders and POUs can be grouped according to the
functionalities of the library or according to the data type.
Make sure to create a documentation for the library. You can, for example,
append a document file, such as a .pdf file, to the library.
For further information on how to provide library documentation, refer to the
Library Development Summary part of the EcoStruxure Machine Expert online
help.

48 EIO0000002829.03
Create Your Own Library

Step 5: Design the Interface

Overview
Basically distinguish 2 types of library interfaces:

Interface Description

External interfaces (user interfaces) Are accessed by the end-user application. Use
a reduced set of parameter types so that other
programmers need not work with troublesome
or complicated data types like pointers or the
ADR() operator.

Internal interfaces All other interfaces

If applicable, reuse the common behavior model to build function block interfaces
for end users.
For further information, refer to the CommonPouTypes Library Guide.
Mark libraries especially designed for the usage by end users with the property
IsEndUserLibrary (refer to the End-User Libraries section of the Library
Development Summary part of the EcoStruxure Machine Expert online help).

Step 6: Implement Error Handling Routines

Overview
Consider the following for creating efficient error handling routines:
• Only error codes that you have documented should be returned.
• Do not simply return error codes that have passed through from other
libraries, but document them in your routines and return a proper code as the
documented source.

Step 7: Set up a Reasonable Deployment (Usage

Restriction)
Overview
In order to help protect the library source, set up an appropriate protection and
access rights for the library. Then, use an appropriate type of usage restriction.
• Supply the library in compiled format (*.compiled-library). Therefore, the
project source cannot be restored. For this purpose, execute the File > Save
Project As Compiled Library... command.
• Increase the restrictions of the access rights for user Everyone. For further
information, refer to the description of the project user management.
• Reserve the right for viewing the content of the objects Project Information
and Library Manager. For further information, refer to Access Control.
• Restrict the usage of the library to certain platforms or devices: you can
implement a check code which has the effect that the library will work if the
appropriate device is used.

EIO0000002829.03 49
 Function and Function Block Representation

Function and Function Block Representation

Overview
Each function can be represented in the following languages:
• IL: Instruction List
• ST: Structured Text
• LD: Ladder Diagram
• FBD: Function Block Diagram
• CFC: Continuous Function Chart
This chapter provides functions and function blocks representation examples and
explains how to use them for IL and ST languages.

Differences Between a Function and a Function Block

Function
A function:
• is a POU (Program Organization Unit) that returns one immediate result.
• is directly called with its name (not through an instance).
• has no persistent state from one call to the other.
• can be used as an operand in other expressions.
Examples: boolean operators (AND), calculations, conversion (BYTE_TO_INT)

Function Block
A function block:
• is a POU (Program Organization Unit) that returns one or more outputs.
• needs to be called by an instance (function block copy with dedicated name
and variables).
• each instance has a persistent state (outputs and internal variables) from one
call to the other from a function block or a program.
Examples: timers, counters

50 EIO0000002829.03
Function and Function Block Representation

In the example, Timer_ON is an instance of the function block TON:

How to Use a Function or a Function Block in IL Language

General Information
This part explains how to implement a function and a function block in IL
language.
Functions IsFirstMastCycle and SetRTCDrift and Function Block TON are
used as examples to show implementations.

Using a Function in IL Language

This procedure describes how to insert a function in IL language:

Step Action

1 Open or create a new POU in Instruction List language.

NOTE: The procedure to create a POU is not detailed here. For more information,
refer to Adding and Calling POUs (see EcoStruxure Machine Expert,
Programming Guide).

2 Create the variables that the function requires.

3 If the function has 1 or more inputs, start loading the first input using LD instruction.

4 Insert a new line below and:

• type the name of the function in the operator column (left field), or
• use the Input Assistant to select the function (select Insert Box in the context
menu).

5 If the function has more than 1 input and when Input Assistant is used, the necessary
number of lines is automatically created with ??? in the fields on the right. Replace the
??? with the appropriate value or variable that corresponds to the order of inputs.

6 Insert a new line to store the result of the function into the appropriate variable: type ST
instruction in the operator column (left field) and the variable name in the field on the
right.

EIO0000002829.03 51
 Function and Function Block Representation

To illustrate the procedure, consider the Functions IsFirstMastCycle (without

input parameter) and SetRTCDrift (with input parameters) graphically
presented below:

Function Graphical Representation

without input parameter:

IsFirstMastCycle

with input parameters:

SetRTCDrift

In IL language, the function name is used directly in the operator column:

Function Representation in POU IL Editor

IL example of a function
without input parameter:

IsFirstMastCycle

IL example of a function with

input parameters:

SetRTCDrift

52 EIO0000002829.03
Function and Function Block Representation

Using a Function Block in IL Language

This procedure describes how to insert a function block in IL language:

Step Action

1 Open or create a new POU in Instruction List language.

NOTE: The procedure to create a POU is not detailed here. For more information,
refer to Adding and Calling POUs (see EcoStruxure Machine Expert, Programming
Guide).

2 Create the variables that the function block requires, including the instance name.

3 Function Blocks are called using a CAL instruction:

• Use the Input Assistant to select the FB (right-click and select Insert Box in the
context menu).
• Automatically, the CAL instruction and the necessary I/O are created.
Each parameter (I/O) is an instruction:
• Values to inputs are set by ":=".
• Values to outputs are set by "=>".

4 In the CAL right-side field, replace ??? with the instance name.

5 Replace other ??? with an appropriate variable or immediate value.

To illustrate the procedure, consider this example with the TON Function Block
graphically presented below:

Function Block Graphical Representation

TON

In IL language, the function block name is used directly in the operator column:

Function Block Representation in POU IL Editor

TON

EIO0000002829.03 53
 Function and Function Block Representation

How to Use a Function or a Function Block in ST

Language
General Information
This part explains how to implement a Function and a Function Block in ST
language.
Function SetRTCDrift and Function Block TON are used as examples to show
implementations.

Using a Function in ST Language

This procedure describes how to insert a function in ST language:

Step Action

1 Open or create a new POU in Structured Text language.

NOTE: The procedure to create a POU is not detailed here. For more information,
refer to Adding and Calling POUs (see EcoStruxure Machine Expert, Programming
Guide).

2 Create the variables that the function requires.

3 Use the general syntax in the POU ST Editor for the ST language of a function. The
general syntax is:

FunctionResult:= FunctionName(VarInput1, VarInput2,.. VarInputx);

To illustrate the procedure, consider the function SetRTCDrift graphically

presented below:

Function Graphical Representation

SetRTCDrift

The ST language of this function is the following:

Function Representation in POU ST Editor

SetRTCDrift PROGRAM MyProgram_ST

VAR myDrift: SINT(-29..29) := 5;
myDay: DAY_OF_WEEK := SUNDAY;
myHour: HOUR := 12;
myMinute: MINUTE;
myRTCAdjust: RTCDRIFT_ERROR;
END_VAR
myRTCAdjust:= SetRTCDrift(myDrift, myDay, myHour, myMinute);

54 EIO0000002829.03
Function and Function Block Representation

Using a Function Block in ST Language

This procedure describes how to insert a function block in ST language:

Step Action

1 Open or create a new POU in Structured Text language.

NOTE: The procedure to create a POU is not detailed here. For more information
on adding, declaring and calling POUs, refer to the related documentation (see
EcoStruxure Machine Expert, Programming Guide).

2 Create the input and output variables and the instance required for the function block:
• Input variables are the input parameters required by the function block
• Output variables receive the value returned by the function block

3 Use the general syntax in the POU ST Editor for the ST language of a Function Block.
The general syntax is:

FunctionBlock_InstanceName(Input1:=VarInput1, Input2:
=VarInput2,... Ouput1=>VarOutput1, Ouput2=>VarOutput2,...);

To illustrate the procedure, consider this example with the TON function block
graphically presented below:

Function Block Graphical Representation

TON

This table shows examples of a function block call in ST language:

Function Block Representation in POU ST Editor

TON

EIO0000002829.03 55
Glossary
A
application:
A program including configuration data, symbols, and documentation.

B
byte:
A type that is encoded in an 8-bit format, ranging from 00 hex to FF hex.

C
CFC:
(continuous function chart) A graphical programming language (an extension of
the IEC 61131-3 standard) based on the function block diagram language that
works like a flowchart. However, no networks are used and free positioning of
graphic elements is possible, which allows feedback loops. For each block, the
inputs are on the left and the outputs on the right. You can link the block outputs to
the inputs of other blocks to create complex expressions.

control network:
A network containing logic controllers, SCADA systems, PCs, HMI, switches, ...
Two kinds of topologies are supported:
• flat: all modules and devices in this network belong to same subnet.
• 2 levels: the network is split into an operation network and an inter-controller
network.
These two networks can be physically independent, but are generally linked by a
routing device.

F
FB:
(function block) A convenient programming mechanism that consolidates a group
of programming instructions to perform a specific and normalized action, such as
speed control, interval control, or counting. A function block may comprise
configuration data, a set of internal or external operating parameters and usually
1 or more data inputs and outputs.

function block diagram:

One of the 5 languages for logic or control supported by the standard IEC 61131-
3 for control systems. Function block diagram is a graphically oriented
programming language. It works with a list of networks where each network
contains a graphical structure of boxes and connection lines representing either a
logical or arithmetic expression, the call of a function block, a jump, or a return
instruction.

function:
A programming unit that has 1 input and returns 1 immediate result. However,
unlike FBs, it is directly called with its name (as opposed to through an instance),
has no persistent state from one call to the next and can be used as an operand
in other programming expressions.
Examples: boolean (AND) operators, calculations, conversions (BYTE_TO_INT)

EIO0000002829.03 57
 I
IEC:
(international electrotechnical commission) A non-profit and non-governmental
international standards organization that prepares and publishes international
standards for electrical, electronic, and related technologies.

IL:
(instruction list) A program written in the language that is composed of a series of
text-based instructions executed sequentially by the controller. Each instruction
includes a line number, an instruction code, and an operand (refer to IEC 61131-
3).

INT:
(integer) A whole number encoded in 16 bits.

L
LD:
(ladder diagram) A graphical representation of the instructions of a controller
program with symbols for contacts, coils, and blocks in a series of rungs executed
sequentially by a controller (refer to IEC 61131-3).

P
POU:
(program organization unit) A variable declaration in source code and a
corresponding instruction set. POUs facilitate the modular re-use of software
programs, functions, and function blocks. Once declared, POUs are available to
one another.

S
ST:
(structured text) A language that includes complex statements and nested
instructions (such as iteration loops, conditional executions, or functions). ST is
compliant with IEC 61131-3.

symbol:
A string of a maximum of 32 alphanumeric characters, of which the first character
is alphabetic. It allows you to personalize a controller object to facilitate the
maintainability of the application.

system variable:
A variable that provides controller data and diagnostic information and allows
sending commands to the controller.

V
variable:
A memory unit that is addressed and modified by a program.

58 EIO0000002829.03
Index
C
cybersecurity
protection of libraries .......................................... 11

F
functions
differences between a function and a function
block ...............................................................50
how to use a function or a function block in IL
language .........................................................51
how to use a function or a function block in ST
language .........................................................54

L
LanguageModelAttribute.................................. 27, 44
libraries ..................................................................9
Library Manager ......................................................9
library protection ................................................... 11
Library Repository ...................................................9

P
protection of libraries ............................................. 11

U
Update Project dialog box.....................................22

EIO0000002829.03 59
Schneider Electric
35 rue Joseph Monier
92500 Rueil Malmaison
France
+ 33 (0) 1 41 29 70 00
www.se.com

As standards, specifications, and design change from time to time,

please ask for confirmation of the information given in this publication.

© 2023 Schneider Electric. All rights reserved.

EIO0000002829.03