Reference Manual

MN912020EN, version 6

SMP Gateway SoftPLC

For use with SMP Gateway software version 8.2R1 or later.
All brand and product names appearing in this document are the trademark or registered trademark
of their respective holders.

© 2021 Eaton – All rights reserved.

The information in this document is subject to change without notice.

Eaton’s Energy Automation Solutions

1990 5 th Street
Suite 220
Levis, Quebec
Canada G6W 5M6
Phone: +1.877.834-0009 or +1.800.815-2258
Fax: +1.514.227.5256
Email: [email protected]
Web: http://www.Eaton.com/smartgrid

Technical Support: [email protected]

MN912020EN, version 6
 EAS-SA QF-MKT-02 Rev.02

Contents
1 Introduction 1
1.1 Intended Audience .................................................................................................1
1.2 Overview ...............................................................................................................2
1.3 Related Documentation .........................................................................................2
1.4 Getting Assistance .................................................................................................3

2 Principles of Operation 5
2.1 The CODESYS Environment ................................................................................5
2.1.1 Supported Version of CODESYS ...........................................................5
2.1.2 Legacy Versions Support ........................................................................5
2.1.3 Installing many CODESYS versions on a single computer ....................5
2.2 The SMP Gateway as an IEC 61131-3 Device ......................................................6
2.2.1 The SoftPLC (CODESYS) Component ..................................................6
2.2.2 SMP Config and the SMP Gateway Configuration (PAR) File ..............6
2.2.3 Automatic Symbol Generation in CODESYS using
PLCopenXML .........................................................................................7
2.3 Secure Communications between CODESYS and the SMP Gateway ..................7

3 Setup 9
3.1 Installing the CODESYS IDE ...............................................................................9
3.2 Starting CODESYS for the First Time ................................................................ 10
3.3 Installing the SMP Gateway Device Description Files........................................ 10
3.4 Installing the SMP Library for CODESYS ......................................................... 11
3.5 Upgrading the SMP Gateway Software ............................................................... 11

4 SMP Gateway Configuration 13

4.1 Defining a SoftPLC (CODESYS) Instance ......................................................... 13
4.2 Defining the SoftPLC Logic Data Points ............................................................ 15
4.3 Subscribing to SMP Gateway Physical Data Points ............................................ 17
4.4 Using Automation Functions to Enhance the SoftPLC Logic ............................. 17
4.5 Publishing Logic Data Points through Slave Protocols ....................................... 18
4.6 Allowing CODESYS IED Communications with SMP Gateway ....................... 18

SMP Gateway SoftPLC Reference Manual ●i

EAS-SA QF-MKT-02 Rev.02

4.6.1 Allowing Direct CODESYS Communications through the

SMP Gateway Firewall ......................................................................... 18
4.6.2 Preventing Direct CODESYS Communications with the
SMP Gateway ....................................................................................... 19
4.6.3 Setting up a Passthrough Connection for CODESYS
Communications ................................................................................... 19
4.6.4 Setting up a Redirection Connection for CODESYS in
SMP Connect ........................................................................................ 20

5 Project Configuration 23
5.1 Creating a New CODESYS Project..................................................................... 23
5.2 Importing the Data Points .................................................................................... 24
5.3 PLC Logic and Tasks Definition ......................................................................... 25

6 Application Deployment 27
6.1 Establishing the Passthrough Connection between CODESYS and the
SMP Gateway ...................................................................................................... 27
6.2 Configuring the CODESYS Connection to the SMP Gateway ........................... 27
6.3 Debugging the Application on the SMP Gateway ............................................... 30
6.4 Creating an Embedded Boot Application ............................................................ 30
6.4.1 Creating a boot application embedded in the SMP Gateway
configuration file ................................................................................... 30
6.4.2 Creating a boot application that is separated from the
SMP Gateway configuration file: .......................................................... 31
6.5 Uploading the configuration file on the SMP Gateway ....................................... 32

7 Appendices 35

Appendix A - Tutorial: The Sample Project A-1

Testing the Sample Project without Following the Tutorial ........................................................... A-1
Opening the Sample Project ........................................................................................................... A-1
The Main_Task Task ...................................................................................................... A-2
The PLC_MAIN Program .............................................................................................. A-2
The ST_PROGRAM Program ........................................................................................ A-3
Running the Sample Application in Debug Mode .......................................................................... A-3
Testing the Sample Application on the SMP Gateway ................................................................... A-4
Editing the sample application ....................................................................................................... A-4
Troubleshooting instructions .......................................................................................................... A-5

Appendix B - CODESYS (SoftPLC) Master Component Reference B-1

General Settings ............................................................................................................................. B-1
Logic Point Settings ....................................................................................................................... B-2
Analog Inputs ................................................................................................................. B-2

ii ● Contents
 EAS-SA QF-MKT-02 Rev.02

Binary Inputs .................................................................................................................. B-4

Analog Outputs............................................................................................................... B-5
Binary Outputs................................................................................................................ B-7
Subscribed Point Settings ............................................................................................................... B-8

SMP Gateway SoftPLC Reference Manual ● iii

 EAS-SA QF-MKT-02 Rev.02

Tables
Table B-1 General settings ........................................................................................................ B-2
Table B-2 Logic analog input settings ....................................................................................... B-4
Table B-3 Logic binary input settings ....................................................................................... B-5
Table B-4 Logic analog output settings ..................................................................................... B-7
Table B-5 Logic binary input settings ....................................................................................... B-8
Table B-6 Subscribed data point settings .................................................................................. B-9

SMP Gateway SoftPLC Reference Manual ●v

 EAS-SA QF-MKT-02 Rev.02

1 Introduction

The SMP Gateway SoftPLC runtime system allows users to solve operational process issues, such
as circuit breaker control and load-balancing, by creating sophisticated automation scripts.
Configured using the CODESYS development platform and the SMP Config application, it
supports the following IEC 61131 programming languages:
 Instruction List (IL)
 Structured Text (ST)
 Function Block Diagram (FBD)
 Continuous Function Chart (CFC)
 Ladder Diagram (LD)
 Sequential Function Chart

Note: The Automation Functions optional component is also available on most

SMP Gateway models, and allows the creation of logic data points whose values
are updated using logic expressions. It also provides users with simple
automation capabilities, such as Best-of and Input-Latching functions, and many
others.

For additional information, refer to the SMP Gateway Automation Functions

Reference Manual, MN912018EN, and to the SMP Gateway User Manual,
MN912001EN.

1.1 Intended Audience

This reference manual is intended for users who need to install and set up the SMP Gateway
SoftPLC runtime system, along with its corresponding configuration tools and software libraries.
The reader must be familiar with the SMP Gateway environment before proceeding with the
remainder of this document. You can acquire this information by reading the SMP Gateway User
Manual, MN912001EN, which is provided with the SMP Gateway Software and Tools.
The reader should also be familiar with the CODESYS IDE. Regarding this topic, refer to the
CODESYS document entitled User Documentation: CODESYS V3, Installation and First Start.

SMP Gateway SoftPLC Reference Manual •1

EAS-SA QF-MKT-02 Rev.02

1.2 Overview
This manual is divided into the following chapters:
 This chapter gives an overview of this document’s contents and purpose.
 Chapter 2 presents the concepts at the core of the SMP Gateway SoftPLC runtime system.
 Chapter 3 describes how to install and set up the CODESYS IDE, the SMP Gateway device
description files, and the SMP Library for CODESYS.
 Chapter 4 explains how to use SMP Config to configure the SoftPLC system component on
the SMP Gateway, including the definition of the data points that will be used by your
SoftPLC logic and tasks.
 Chapter 5 covers CODESYS project configuration, including project creation, automatic
symbol definition through data point import, and PLC logic coding and task definition.
 Chapter 6 describes how to connect the CODESYS IDE to the SMP Gateway, debug the
SoftPLC application, create the boot application and upload it to the SMP Gateway.
 Reference information, such as the description of all SoftPLC system component settings and
an overview of the sample CODESYS project provided by default with SMP Config, is
available in the various appendices.

1.3 Related Documentation

For additional information, refer to the following documentation that is provided with the
corresponding products.

For the CODESYS IDE:

 User Documentation: CODESYS V3, Installation and First Start, Document Version 10.0,
Smart Solutions Software GmbH.

For the SMP Library for CODESYS:

 SMP Library for CODESYS Reference Manual, MN912021EN.
This document describes in detail the functions and function blocks implemented by the
SMP Library for CODESYS.

For the SMP Gateway:

 SMP Gateway User Manual, MN912001EN.
This document describes all the steps required to configure any model of SMP Gateway, and
to test its configuration. It also explains how to connect the SMP Gateway to a master station
and to substation IEDs, and describes the advanced features of the gateway.
 Protocol Common Concepts Reference Manual, MN912003EN.
This document describes the concepts and settings that are common to the protocol
components used by all SMP Gateway models to communicate with most substation IEDs and
control centers.
 SMP Gateway Automation Functions Reference Manual, MN912018EN.
This reference manual provides all the information required to install and set up an instance of
the Automation Functions component in the SMP Gateway.

2● Chapter 1: Introduction
 EAS-SA QF-MKT-02 Rev.02

1.4 Getting Assistance

If you have any question regarding the performance, application or testing of any component of
this Eaton product, do not hesitate to contact us. Our staff will be pleased to assist you.
Technical Support
Eaton’s Energy Automation Solutions

Email: [email protected]
Phone: +1.877.834-0009 or +1.800.815-2258

Business hours are from 8 a.m. and 5 p.m. CST, Monday to Friday.

SMP Gateway SoftPLC Reference Manual •3

 EAS-SA QF-MKT-02 Rev.02

2 Principles of Operation

This chapter presents the concept at the core of the SMP Gateway SoftPLC runtime system. You
should read this chapter carefully and make sure you understand these concepts before going
further with the configuration chapters.

2.1 The CODESYS Environment

CODESYS (COntroller DEvelopment SYStem) is a comprehensive software tool for industrial
automation technology. Basically, it consists of two parts: the programming system (the IDE) and
the runtime system (which is implemented in the SMP Gateway as the combination of the
SoftPLC component and the SoftPLC application).
The runtime system turns the SMP Gateway into an IEC 61131-3 controller programmable with
CODESYS. Integrated compilers make sure that the program code is processed at optimal speed.

2.1.1 Supported Version of CODESYS

Version 7.0 and later of the SMP Gateway software supports version 3.5 SP2 of CODESYS.

2.1.2 Legacy Versions Support

Versions 6.1, 6.2 and 6.3 of the SMP Gateway software supports version 3.4 of CODESYS.
Versions 6.0 and earlier of the SMP Gateway Software and Tools support CODESYS version 2.3.
These legacy versions are out of the scope of this document. To learn how to configure the
SMP Gateway SoftPLC for these versions, refer to these versions’ corresponding documentation.

2.1.3 Installing many CODESYS versions on a single computer

It is sometimes necessary to install more than one CODESYS version on a single computer
because SMP Manager can manage SMP Gateways that are using different SMP Software and
Tools versions, which do not use the same CODESYS versions.
The CODESYS versions must be installed in separate directories, the default path name suggested
at the installation must be modified to include the version number. Following are a few
application examples:
 When installing CODESYS version 2.3.7.3, which is used with SMP Gateways’
Software and Tools versions 6.1, 6.2 and 6.3, a 2.3 suffix must be added to the default
installation path (C:\program files(x86)\3S CoDeSys 2.3).

SMP Gateway SoftPLC Reference Manual •5

EAS-SA QF-MKT-02 Rev.02

 When installing CODESYS version 3.4 SP4 Patch 1, which is used with SMP Gateways’
Software and Tools versions 6.1, 6.2 and 6.3, a 3.4 suffix must be added to the default
installation path (C:\program files(x86)\3S CoDeSys 3.4).
 When installing CODESYS version 3.5 SP2, which is used with SMP Gateways’
Software and Tools versions 7.0 and later, no suffix should be added to the default
installation path (C:\program files(x86)\3S CoDeSys).

2.2 The SMP Gateway as an IEC 61131-3 Device

The main function of an SMP Gateway is to perform data acquisition and reporting based on the
master-and-slave protocols model.
Master protocols retrieve data from RTUs and IEDs, before storing it into a built-in database
called the Real-Time Data eXchange (RTDX).
Data stored in RTDX is used by system components, such as the SoftPLC or the Automation
Functions component, which process the data and re-inject the resulting data in RTDX.
Slave protocols can then subscribe to the RTDX data, and report updates to control centers and
master stations.
From the CODESYS perspective, the SMP Gateway is considered as an IEC 61131­3 device
nodes; the IEC 61131-3 gateway node is the computer hosting the CODESYS IDE and the
SMP Tools. This fact must be understood to properly configure the connection between the
CODESYS IDE and the SMP Gateway (see “Configuring the CODESYS Connection to the
SMP Gateway”, page 27).

2.2.1 The SoftPLC (CODESYS) Component

The SoftPLC (CODESYS) is the system component that makes the bridge between RTDX and the
SoftPLC application. It initializes and manages the data points created specifically as outputs for
the SoftPLC application, and subscribes to the existing data points that are used as inputs by the
SoftPLC application logic. It also starts the SoftPLC application at system startup.
The SoftPLC component is configured using SMP Config (see “SMP Gateway Configuration”,
page 13).

2.2.2 SMP Config and the SMP Gateway Configuration (PAR) File
The SMP Gateway components, functions and data point settings are defined and specified using
SMP Config, and stored in the SMP Gateway configuration (PAR) file. This is also the case for
the SoftPLC (CODESYS) component.
To simplify application deployment, a feature is provided to embed the SoftPLC application
designed using the CODESYS IDE within the SMP Gateway configuration file. As a result, the
SoftPLC application is uploaded to the SMP Gateway when you upload the configuration file on
the SMP Gateway. To make it work properly, all you have to do is to edit the CODESYS project
(and application) from the SMP Config, as described in Chapter 5.
Embedding the SoftPLC application within the SMP Gateway configuration file is the preferred
approach for developing CODESYS applications on the SMP Gateway; the configuration and
design instructions provided in this manual are based on this scenario. However, it is still possible
to keep the CODESYS project separated from the configuration file. In such “standalone”
scenario, the SoftPLC (CODESYS) component still acts as the bridge between the SoftPLC
application and RTDX, but you must upload and start the SoftPLC application separately, through
the CODESYS IDE.

6● Chapter 2: Principles of Operation

 EAS-SA QF-MKT-02 Rev.02

2.2.3 Automatic Symbol Generation in CODESYS using

PLCopenXML
To simplify the symbol definition and initialization in the SoftPLC application, SMP Config
generates a PLCopenXML file that contains the settings of all points defined in the SoftPLC
component.
When you open the CODESYS IDE through SMP Config, the latter notifies the user that it
generated the PLCopenXML file and provides its location. Importing this file in the CODESYS
project automatically generates (or updates) the corresponding symbol definitions and
initialization code.
This process is explained in details in the “Importing the Data Points” section, page 24.

2.3 Secure Communications between CODESYS

and the SMP Gateway
To ensure continued secure operation of the SMP Gateway, Eaton recommends that users of the
SoftPLC runtime system conform to the following security practices:
 The CODESYS IDE should only access the SMP Gateway through an authenticated
Passthrough connection.
 Access to the CODESYS port on the SMP Gateway should be controlled through firewall
settings.
The setup instructions provided in this manual follow these recommendations.

SMP Gateway SoftPLC Reference Manual •7

 EAS-SA QF-MKT-02 Rev.02

3 Setup

This chapter explains how to install and setup the CODESYS integrated development environment
(IDE), along with the SMP Gateway device description files and the SMP Library for CODESYS.

3.1 Installing the CODESYS IDE

The CODESYS for the SMP Gateway disc contains the installer for CODESYS V3.5 SP2.

Note: CODESYS requires the Microsoft .NET Framework 3.5, which is not provided
with the installer. However, the installer can download it from the web and
perform the installation, if the computer is connected to the Internet.

If this is not the case, contact your system administrator to have the .NET
Framework 3.5 installed prior to the CODESYS installation.

To install the CODESYS IDE:

 From the CODESYS for the SMP Gateway installation package, open the Welcome.htm file
in a web browser.
 In the left pane of the Welcome window, click Installing.
 In the Installing window, click the CODESYS Workbench link to start the installation
process.
 Follow the on-screen instructions, until you reach the Select Features window.
 Clear all check boxes except CODESYS V3 and CODESYS Gateway.
 If you must convert existing CODESYS projects to the latest version, also select CODESYS
Converter.

SMP Gateway SoftPLC Reference Manual •9

EAS-SA QF-MKT-02 Rev.02

 Click Next and proceed with the remaining installation instructions.

3.2 Starting CODESYS for the First Time

Some setup operations must be performed when starting CODESYS for the first time.

To start CODESYS for setup purposes:

 On the Windows taskbar, click start.
 Point to All Programs, then 3S CODESYS, then CODESYS, and then click CODESYS
V3.5 SP2.

Note: If you don’t start CODESYS using the specific shortcut, you can get a dialog
asking which profile you want to start: normal or composer dedicated. The
second one is used only to edit projects, you cannot debug neither run it.

CODESYS starts and initialize the Component Manager.

 In the Choose Default Environment Settings window, select the Standard environment
settings and then click Start.

3.3 Installing the SMP Gateway Device

Description Files
A device description file (*.DevDesc.xml) defines a specific hardware object (formerly known
as a “target”) that runs a SoftPLC application.
Eaton provides the following device description files on the CODESYS for the SMP Gateway disc:
 SMP16.DevDesc.xml.
This file contains the device description for SMP 16 gateways.
 SMP4DP.DevDesc.xml.
This file contains the device description for the SMP 4/DP.
 SMPSG4000.DevDesc.xml.
This file contains the device description for SMP SG-4000 gateways.

To install SMP Gateway device description files in the CODESYS IDE:

 In CODESYS, from the Tools menu, choose Device Repository and click on Install.
 Browse the CODESYS for the SMP Gateway disc down to the following folder:

.\PC\Gateway\
 Select the device description file that corresponds to your SMP Gateway model, and then
click Open.

CODESYS will confirm the success of the installation process.

 Repeat for additional device description files, if required.

10 ● Chapter 3: Setup
 EAS-SA QF-MKT-02 Rev.02

3.4 Installing the SMP Library for CODESYS

The SMP Library for CODESYS (SmpLib.library) contains all the data types, functions, and
function blocks providing access to the SMP Gateway Real-Time Data eXchange (RTDX).

To install the SMP Library for CODESYS:

 In CODESYS, from the Tools menu, choose Install library Repository, than click on
Install.
 Browse the CODESYS for the SMP Gateway disc down to the following folder:

.\PC\Gateway
The file will not be visible, since only compiled library files are displayed by default.
 In the Files of type box, select Library files to reveal the file.
 Select the SmpLib.library file, and then click Open.

CODESYS will confirm the success of the installation process.

 Close the CODESYS IDE.

3.5 Upgrading the SMP Gateway Software

The final configuration step is to ensure that you are using the proper version of the SMP Gateway
Software & Tools.
To run a CODESYS V3.5.2 application on the SMP Gateway, the SMP Gateway must run version
7.0 or later of the SMP Gateway firmware. The same version of the SMP Tools is required to
setup the SoftPLC component.
To install the latest version of the SMP Tools, refer to the “Installing SMP Tools” section of the
corresponding installation guide of your SMP Gateway (ex. the SMP 4DP Installation Guide, for
the SMP 4/DP).
To update the SMP Gateway software, refer to the SMP Gateway User Manual.
You are now ready to configure the SoftPLC component, and to create and design your
SMP Gateway SoftPLC application.

Note: Additionally, make sure the SMP Gateway license contains the P-SSMP-0201
SoftPLC Runtime System option.

SMP Gateway SoftPLC Reference Manual • 11

 EAS-SA QF-MKT-02 Rev.02

4 SMP Gateway
Configuration

Before proceeding with the creation of the SoftPLC application within the CODESYS IDE, some
SMP Gateway configuration operations must be performed using SMP Config:
 An instance of the SoftPLC (CODESYS) component must be created and added to the
SMP Gateway configuration file.
 The data points that will be created for and updated specifically by the SoftPLC instance
(called the logic data points) must be defined.
 The SoftPLC must subscribe to physical data points produced by other SMP Gateway
components and that will be required by the SoftPLC application logic (either as inputs
or outputs).
 You can use the SMP Gateway Automation Functions to enhance the SoftPLC application
logic, if required.
 SMP Gateway slave components can subscribe to the SoftPLC logic data points, so they can
make them available to the SCADA, or any other control center or master station.
 Finally, you will have to allow the CODESYS IDE to communicate with the SMP Gateway
through its built-in firewall, via a Passthrough connection.
These operations, which are performed using SMP Config are described in details in the following
sections.

Note: It is assumed that the reader has sufficient knowledge of the SMP Config tool
and SMP Gateway protocol components. For additional information on these
topics, refer to the SMP Gateway User Manual.

4.1 Defining a SoftPLC (CODESYS) Instance

The SMP Gateway configuration (PAR) file must contain an instance of the SoftPLC(CODESYS)
system component to run a SoftPLC application.

To define a SoftPLC (CODESYS) instance:

 From SMP Manager, select the SMP Gateway that will run the SoftPLC application.
 From the Tools menu, choose SMP Config.
 In the left pane of SMP Config, under the System branch, click SoftPLC (CODESYS).

SMP Gateway SoftPLC Reference Manual • 13

EAS-SA QF-MKT-02 Rev.02

 In the right pane, assign a name to the new instance, and then press ENTER.

The new instance appears in the left pane.

Note: There can only be one instance of the SoftPLC (CODESYS) component in a
single SMP Gateway configuration; also, there can only be one SoftPLC
application per SoftPLC component instance.

 In the left pane, expand the SoftPLC instance branch and select the General branch.

 In the Device Prefix cell, type the prefix that will be added before the name of all logic data
points of this instance.

Note: By default, the Device Prefix is set to plc_. The sample project provided by
Eaton uses this prefix. If you want to use the sample project, you should keep
this default value; if you want to change it, you will also need to update the
sample project logic code.

 Unless you want to temporarily deactivate the SoftPLC component, make sure the Enabled
option is selected.
 By default, the Start Embedded Boot Application setting is selected; this means that the
SoftPLC component expects the SMP Gateway configuration (PAR) file to contain the
SoftPLC application, and will start it upon system startup or restart. This mode is very useful
to deploy a stable and debugged version of the SoftPLC application. This allows also the
creation of the SoftPLC template that includes everything, including the boot project.
Additionaly, it enables the user to close the SoftPLC port in the firewall, thus providing a
secure running environment. Indeed, when working with a stable version, the direct access is
acheived via a passthrough connection.

If you want to upload it manually using the CODESYS IDE, clear the Start Embedded Boot
Application check box; the SoftPLC application and the CODESYS project will then be
managed separately from the configuration file. This mode is very useful for new
development and debugging of an SoftPLC application. When in full development, we
recommend to open the SoftPLC port in the firewall to stream line the debugging process. We
strongly recommend to close the SoftPLC port on an SMP in production for security reason;
a passthrough connection can then be used.
 By default, the Restart SMP when Exception Occurs setting is not selected; when selected,
this parameter means that an exception on a SoftPLC task will cause a restart of the SMP. For
example, an exception can be caused by a division by zero or when the CODESYS watchdog
is triggered. When an exception happens, an entry is added to the Reset log, indicating that an
exception occurred, regardless of the status of the Restart SMP when Exception Occurs
setting.

14 ● Chapter 4: SMP Gateway Configuration

 EAS-SA QF-MKT-02 Rev.02

4.2 Defining the SoftPLC Logic Data Points

The logic data points that will be created by the SoftPLC component and used as part of the
SoftPLC application logic must be defined first in the SMP Gateway configuration (PAR) file.

To define a logic analog input:

 Still in SMP Config, under the SoftPLC instance branch, expand the Logic Points branch, and
then select the Analog Inputs branch.

 In the right pane, click in the Name cell of the first empty row.
 Type the name of the logic point.

Note: The full name of the point will be preceded by the SoftPLC instance prefix.

 (Optional) In the Symbol cell, type the name of this data point to be used in the corresponding
CODESYS project. Array type symbols are accepted (e.g.: AI1[x]), a table will be created
when the XML file is generated.

If this setting is left unspecified, the Name setting will also be used as the symbol in
CODESYS.
 Edit other point settings (ex. Scale, Offset, etc.) as required.

For additional information about these settings, see “Analog Inputs”, page B-2.
 (Optional) In the Description cell, type some indications about the purpose of this point or its
use in the SoftPLC application logic.
 Repeat for all logic analog inputs.

To define a logic binary input:

 Still in SMP Config, under the SoftPLC instance branch, expand the Logic Points branch, and
then select the Binary Inputs branch.

 In the right pane, click in the Name cell of the first empty row.
 Type the name of the logic point.

Note: The full name of the point will be preceded by the SoftPLC instance prefix.

 (Optional) In the Symbol cell, type the name of this data point to be used in the corresponding
CODESYS project. Array type symbols are accepted (e.g.: BI2[x].

If this setting is left unspecified, the Name setting will also be used as the symbol in
CODESYS.

SMP Gateway SoftPLC Reference Manual • 15

EAS-SA QF-MKT-02 Rev.02

 Edit other point settings (ex. Scale, Offset, etc.) as required.

For additional information about these settings, see “Binary Inputs”, page B-4.
 (Optional) In the Description cell, type some indications about the purpose of this point or its
use in the SoftPLC application logic.
 Repeat for all logic binary inputs.

To define a logic analog output:

 Still in SMP Config, under the SoftPLC instance branch, expand the Generated Points
branch, and then select the Analog Outputs branch.

 In the right pane, click in the Name cell of the first empty row.
 Type the name of the logic point.

Note: The full name of the point will be preceded by the SoftPLC instance prefix.

 (Optional) In the Symbol cell, type the name of this data point to be used in the corresponding
CODESYS project. Array type symbols are accepted (e.g.: AO1[x]).

If this setting is left unspecified, the Name setting will also be used as the symbol in
CODESYS.
 Edit other point settings (ex. Scale, Offset, etc.) as required.

For additional information about these settings, see “Analog Outputs”, page B-5.
 (Optional) In the Description cell, type some indications about the purpose of this point or its
use in the SoftPLC application logic.
 Repeat for all logic analog outputs.

To define a logic binary output:

 Still in SMP Config, under the SoftPLC instance branch, expand the Generated Points
branch, and then select the Binary Outputs branch.

 In the right pane, click in the Name cell of the first empty row.
 Type the name of the logic point.

Note: The full name of the point will be preceded by the SoftPLC instance prefix.

 (Optional) In the Symbol cell, type the name of this data point to be used in the corresponding
CODESYS project. Array type symbols are accepted (e.g.: BO1[x]).

16 ● Chapter 4: SMP Gateway Configuration

 EAS-SA QF-MKT-02 Rev.02

If this setting is left unspecified, the Name setting will also be used as the symbol in
CODESYS.
 Edit other point settings (ex. Allow Open/Close, Allow Pulse, etc.) as required.

For additional information about these settings, see “Binary Outputs”, page B-7.
 (Optional) In the Description cell, type some indications about the purpose of this point or its
use in the SoftPLC application logic.
 Repeat for all logic binary outputs.

4.3 Subscribing to SMP Gateway Physical Data

Points
Some physical data points, which are mostly provided by master protocol components, may be
required as “inputs” of your SoftPLC application. To receive data updates for these points through
RTDX, the SoftPLC component must subscribe to them.

Note: SoftPLC application “inputs” are not to be confused with “input data points”. The
SoftPLC component can also subscribe to output data points, whose values will
be used as inputs of the application. Similarly, logic data points are considered as
“outputs” of the SoftPLC application, although most of the times they will be
defined as input data points.

To subscribe the SoftPLC component to a physical data point:

 Still in SMP Config, under the SoftPLC instance branch, expand the Subscribed Points
branch, and then select the branch corresponding to the type of point to subscribe to.

For example, to subscribe to a physical analog input, select the Analog Inputs branch.

 In the right pane, click in the Name cell of the first empty row.
 Type the name of the logic point, including its own device prefix.
 (Optional) In the Symbol cell, type the name of this data point to be used in the corresponding
CODESYS project. Array type symbols are accepted (e.g.: SAI[x]).

If this setting is left unspecified, the Name setting will also be used as the symbol in
CODESYS.
 Repeat for all subscribed data points.

4.4 Using Automation Functions to Enhance the

SoftPLC Logic
The Automation Functions component is a software component that was developed for the
SMP Gateway product line. It provides basic hard-coded automation capabilities that are simpler

SMP Gateway SoftPLC Reference Manual • 17

EAS-SA QF-MKT-02 Rev.02

to implement than a SoftPLC application, but which can also enhance SoftPLC functionalities,
without typing additional lines of code.
The Automation Functions component is configured using SMP Config and works exclusively
with RTDX data points: it is not an additional library for the CODESYS environment.
To use the Automation Functions component with your SoftPLC application, create an
Automation Functions instance and define the functions you want the SMP Gateway to perform
on existing data points or new logic data points created by this component; then, subscribe the
SoftPLC component to these “automated” data points.
For additional information on the Automation Functions component, refer to the SMP Gateway
Automation Functions Reference Manual.

4.5 Publishing Logic Data Points through Slave

Protocols
You can make the logic data points available to any master station or control center that is
connected to the SMP Gateway via a slave protocol component, by subscribing this slave protocol
component to the logic data points.
A slave protocol instance must be created and configured in the SMP Gateway configuration
(PAR) file for each control center or master station.
To configure a slave protocol instance, the following operations must be performed:
 Create the slave protocol instance and configure its general settings. General settings are
parameters that are shared by most slave protocol components.
 Configure the protocol-specific settings of the slave.
 Subscribe the slave to the logic data points and any other data point of the RTDX database.
 Provide protocol-specific settings for the subscribed data points.
 Configure a communication link and assign it to the slave protocol.

Note: This procedure is presented in details in the SMP Gateway User Manual.

4.6 Allowing CODESYS IED Communications with

SMP Gateway
By default, the SMP Gateway is protected by a built-in firewall, which allows communications
with specific users, computers and programs, including those with the SMP Tools.
During the SoftPLC application development and testing process, we recommend to open the
CODESYS port (TCP 11740) via the predefined rule to accelerate the development. When the
development is completed, we recommend to close that port for security reason. When the port is
closed, you can still access the SoftPLC with the CODESYS IDE via a Passthrough connection.
See the following section to learn how to do that.

4.6.1 Allowing Direct CODESYS Communications through the

SMP Gateway Firewall

18 ● Chapter 4: SMP Gateway Configuration

 EAS-SA QF-MKT-02 Rev.02

Please note that this direct access should be blocked as soon as the system is put in
production.

To allow direct CODESYS communications through the SMP Gateway firewall:

 In SMP Config, expand the Firewall branch, and then the Rules branch.
 In the CODESYS row, select Allow.
 You can further restrict the access if you want, but this is not as good as closing the SoftPLC
port and using a passthrough connection. To restrict the access, in the Accessible From cell,
select Specific Computer or Subnet.
 In the Specific Computer or Subnet cell, type the IP address of the computer that runs
the CODESYS IDE.

4.6.2 Preventing Direct CODESYS Communications with the

SMP Gateway

To block direct CODESYS communications through the SMP Gateway firewall:

 In SMP Config, expand the Security branch, the Firewall branch, and then select the Rules
branch.
 Under Services, in the CODESYS row, clear the Allow checkbox.

You will need to configure a Passthrough connection to allow the CODESYS IDE to connect to
the SoftPLC.

4.6.3 Setting up a Passthrough Connection for CODESYS

Communications
Passthrough connections are encrypted and require users to authenticate themselves with the
SMP Gateway. By defining such a connection for the CODESYS IDE and blocking the
CODESYS TCP port (11740) in the SMP Gateway built-in firewall, you prevent all unauthorized
access to the SMP Gateway and the CODESYS runtime system it runs.

To set up a Passthrough connection for CODESYS communications:

 In SMP Config, expand the Connections branch, the TCP/IP branch, and then select
the Masters branch.
 In the right pane, click in the Name cell of the first empty row.
 Type a name, such as CODESYS, for the TCP/IP connection that will be configured for
passthrough.
 In the IP address cell, type 127.0.0.1 to indicate that the target is the SMP Gateway itself.
 In the Port Number cell, type 11740.

SMP Gateway SoftPLC Reference Manual • 19

EAS-SA QF-MKT-02 Rev.02

 In the left pane, expand the Passthrough branch, and then select the Connections branch.
 In the right pane, click in the IED Name cell of the first empty row.
 Type a name, such as CODESYS, for the Passthrough connection.
 In the Connection cell, select the TCP/IP master connection that you defined previously
(named CODESYS in our example).

4.6.4 Setting up a Redirection Connection for CODESYS in

SMP Connect
As the CODESYS IDE will connect to the Passthrough Server of the SMP Gateway, rather than
directly to the CODESYS runtime system through port 11740, you must set up a redirection
connection in SMP Connect, the SMP Tool used to establish passthrough connections between a
PC and the SMP Gateway.

To set up a redirection connection for CODESYS in SMP Connect:

 Start SMP Connect.
 From the Control menu, choose IED Application Settings.
 In the IED Application Settings window, click Add.
 In the window that appears, type CODESYS, and then click OK.
 Select CODESYS from the Application List.
 Click the Apply base settings for arrow button, and then choose TCP/IP Application.
 Under Application Settings:
 Select Start the application manually.
 Under Local Communication Settings:
 Specify whether SMP Connect is to use a virtual serial loopback, a real serial loopback,
or a TCP/IP loopback connection to communicate with the NVT. Most manufacturers’
tools use a serial (virtual or real) connection. However, if you are using a terminal
emulator program such as Microsoft HyperTerminal to communicate with the device, you
can use a TCP/IP loopback connection.
 Click Configure to specify the redirection connection settings:
 In the Port box, type the number of an unused port; you cannot use TCP port11740,
as the CODESYS IDE uses this port.

For example, you can use the 3333 port.

Note down this port number, as it will be required while specifying the
SMP Gateway connection settings in the CODESYS IDE.

20 ● Chapter 4: SMP Gateway Configuration

 EAS-SA QF-MKT-02 Rev.02

 Click OK.

 Click OK to close the IED Application Settings window.

SMP Gateway SoftPLC Reference Manual • 21

 EAS-SA QF-MKT-02 Rev.02

5 Project Configuration

The SoftPLC component provides the RTDX data points required by the SoftPLC application, but
not the application itself; the latter must be designed in a CODESYS project using the CODESYS
IDE.
In this chapter, the reader will learn how to perform the following operations:
 Create a new CODESYS project and attach it to an SMP Gateway configuration file.
 Import the SoftPLC data points in the CODESYS project, to simplify the definition and
initialization of the corresponding symbols in the application.
 Create a new CODESYS project and manage it separately from the configuration file.
Finally, the reader will also get guidelines and tips on how to design and code the SoftPLC
application.

Note: Eaton recommends the insertion of the SoftPLC application into the
SMP Gateway configuration file once the debugging phase is completed, and this
chapter provides the information and instructions corresponding to this scenario.

If you want to manage the SoftPLC application (and the related CODESYS
project) separately from the SMP Gateway configuration file, the process will
differ.

5.1 Creating a New CODESYS Project

As described previously, the SoftPLC component is configured by default to start the SoftPLC
application; for that matter, the application must be embedded into the SMP Gateway
configuration file.
SMP Config allows users to attach a CODESYS project to an SMP Gateway configuration file to
facilitate the insertion of the application into the file. It is however possible to use the CODESYS
project separately from the configuration file.

Note: For SMP Config CODESYS integration to work properly, the proper version of the
CODESYS IDE must be installed (refer to the “Supported Version of CODESYS”
section, page 5).

To create a CODESYS project and attach it to the SMP Gateway configuration file:
 In SMP Config, select the SoftPLC instance branch.
 Type an instance name in the Name cell located in the right pane.

SMP Gateway SoftPLC Reference Manual • 23

EAS-SA QF-MKT-02 Rev.02

 From the Tools menu, choose Edit CODESYS Project.

Note: If you defined SoftPLC logic data points or subscribed the SoftPLC to existing
data points, an information message is displayed to notify the user that it should
import these points to its CODESYS project, using the PLCopenXML file
automatically generated by SMP Config; instructions on how to perform such
import are provided in section 5.2, below.

Take note of the name and location of the file, and then click OK.

 CODESYS may prompt you for a version profile. Simply click Continue to select the
version profile. The user should not select a Composer Dedicated version.

The CODESYS IDE opens the sample project provided by Eaton.

Note: If you want to use the sample project provided by Eaton, before developing your
own application, refer to “Appendix A - Tutorial: The Sample Project”, page A-1.
Otherwise, the following sections assume that you will replace most of the
sample project code with your own application code.

Important: If you use the sample project code as a launching pad to start your own
project, remember that some parts of the project code must remain
unmodified in order to ensure a successful integration with the SMP
Gateway. Details are provided in the “Appendix A - Tutorial: The Sample
Project.

When editing the sample application, pay attention to the following details:
 Make sure to keep the sequence logic in PLC_MAIN PRG; this is mandatory for a successful
SMP Gateway integration.
 Make sure to keep the CheckBounds function which is used to validate runtime “ARRAY
out of bound” errors; we recommend that you implement any other POUs for implicit checks
(refer to CODESYS documentation for that matter).
 If you need global variables, create a new object, do not use
SMP_global_symbols_declaration.
 Take time to update the SMP_LOG, SMP_STAT and SMPINIT_PLC to match your
project.

5.2 Importing the Data Points

When you start the CODESYS IDE from SMP Config, the latter automatically generates a
PLCopenXML file that contains all the information required by the CODESYS IDE to generate
the symbol definition and initialization code for the logic and subscribed data points of the
SoftPLC component.
By importing the content of this PLCopenXML file in the CODESYS project, you skip the tedious
and error-prone task of having to define and initialize these symbols manually.

To import data points in the CODESYS project:

 Still in the CODESYS IDE, select the Application branch.

24 ● Chapter 5: Project Configuration

 EAS-SA QF-MKT-02 Rev.02

 From the Project menu, choose Import PLCopenXML.

 Select the file mentioned by SMP Config when you opened the CODESYS project from it,
and then click Open.
 In the Import PLCopenXML window, make sure the SMP_global_symbols_declaration
and SMP_MAP_SYMBOLS items are selected, and then click OK.
 If CODESYS indicates that any of the imported items already exists in the project,
select Replace the existing object. Do the same for all subsequent conflicts, and then
click OK.

The existing versions of these items will be replaced in the CODESYS sample project by new
ones that contain all the declarations and symbols of your own logic and subscribed data
points.

5.3 PLC Logic and Tasks Definition

Once the project is created and the data points are imported, the final and more important step is to
define the SoftPLC logic and tasks.
By default, all new projects created through SMP Config are based on the sample project
described in “Appendix A”, which contains one task (Main_Task) and two programs
(PLC_MAIN and ST_PROGRAM).
Unless you need more tasks and/or programs, we recommend that you keep the existing
task/program structure and replace the sample code by your own. However, the PLC_MAIN
structure must remain unmodified to ensure successful integration with the SMP Gateway.
Essentially, the logic that is performed on a regular basis is found in the ST_PROGRAM program;
the sample already documents which sections could be replaced/removed and which ones are
mandatory.
For additional information, refer to the description of the default sample project, in “Appendix A -
Tutorial: The Sample Project”, page A-1.

SMP Gateway SoftPLC Reference Manual • 25

 EAS-SA QF-MKT-02 Rev.02

6 Application Deployment

Once the SoftPLC component and application are properly configured, they can be deployed on
the SMP Gateway.
This chapter explains how to perform the following deployment-related operations:
 Connect the CODESYS IDE to the SMP Gateway.
 Debug the SoftPLC application on the SMP Gateway through the CODESYS IDE.
 Create a boot application and embeds it in the SMP Gateway configuration to allow the
SoftPLC component to automatically start the SoftPLC application at the SMP Gateway
startup or restart.
 Upload the SMP Gateway configuration file, which also includes the SoftPLC settings,
application and boot code, on the SMP Gateway.

6.1 Establishing the Passthrough Connection

between CODESYS and the SMP Gateway
Unless you want to connect the CODESYS IDE directly to the SMP Gateway, you will first need
to establish the Passthrough connection using SMP Connect.

To establish the Passthrough connection between the CODESYS IDE and the
SMP Gateway:
 Start SMP Connect.
 Select the passthrough connection you defined previously for the CODESYS IDE.
 From the Control menu, choose Connect to IED.
 In the IED Application Selection window, select the CODESYS IDE application defined
previously.
 If you configured the CODESYS IDE to be started up manually, start it now.

6.2 Configuring the CODESYS Connection to the

SMP Gateway
To connect the CODESYS IDE to the SMP Gateway, you must define the communication channel
between them, known in CODESYS as the network path. Only one network path is active at a
time.

SMP Gateway SoftPLC Reference Manual • 27

EAS-SA QF-MKT-02 Rev.02

As stated previously, Eaton recommends implementing this communication channel through a

Passthrough connection, rather than connecting CODESYS directly to the SMP Gateway 11740
TCP port.

Note: Typically, devices running IEC 61131-3 applications (controllers) are accessible
through a network gateway. When defining the network path to an SMP Gateway
running a SoftPLC application, the SMP Gateway is considered as both the
network gateway and the PLC device.

To connect the CODESYS IDE to the SMP Gateway:

 Start CODESYS from SMP Config (from the Tools menu, choose Edit CODESYS Project).
 In the Devices pane on the left, expand the CODESYSProj branch, and then double-click the
branch of SMP Gateway to connect (ex. Device (SMP 4DP/SMPSG-4250)).

All settings for the selected device are displayed in the right pane, in a specific Device
window/tab.
 Click in the Communication Settings tab.

 Click Add gateway.

 Accept the default settings by clicking OK.

Note: Unlike previous versions of the SMP Gateway firmware, version 7.0 does not
host a CODESYS gateway; make sure that you selected the CODESYS Gateway
feature when you installed the CODESYS IDE (see “Installing the CODESYS
IDE”, page 9).

 Select the newly created gateway node, and then click Add device.
 If the CODESYS IDE connects to the SMP Gateway through a passthrough connection:
 Type 127.0.0.1:<port> as the node address, where <port> is the loopback connection
port as defined in SMP Connect for the CODESYS IDE.
 In the Assignment mode box, select IP Address using TCP.

28 ● Chapter 6: Application Deployment

 EAS-SA QF-MKT-02 Rev.02

 Before clicking OK, make sure that the passthrough connection established using
SMP Connect is still alive; otherwise, reestablish it.

 If the CODESYS IDE connects to the SMP Gateway directly:

 Type the IP address of the SMP Gateway.
 In the Assignment mode box, select Automatic.

 Click OK.

The SMP Gateway will appear under the gateway branch, represented by its serial number
(ex. SMP700035), a node address between brackets, and the (active) label.

SMP Gateway SoftPLC Reference Manual • 29

EAS-SA QF-MKT-02 Rev.02

 If the (active) label is not present, select the SMP Gateway branch, and then click the Set
active path button on the top right side of the screen.
CODESYS is now ready to communicate with the SMP Gateway SoftPLC runtime.

6.3 Debugging the Application on the

SMP Gateway
Once the CODESYS IDE is properly connected to the SMP Gateway, you can test and
troubleshoot the SoftPLC application.

To debug the application on the SMP Gateway:

 If applicable, make sure that the passthrough connection is established between the
CODESYS IDE and the SMP Gateway, using SMP Connect (see Setting up a Redirection
Connection for CODESYS in SMP Connect, page 20).
 In SMP Config, from the Tools menu, choose Edit CODESYS Project.
 In CODESYS, from the Online menu, choose Login.

If asked to download the application on the SMP Gateway, click Yes.

You can now use the Debug menu commands to insert breakpoints and debug the application.

6.4 Creating an Embedded Boot Application

For the SoftPLC component to be able to start the application on SMP Gateway startup, the
application must not only be included in the SMP Gateway configuration file; boot code must also
be added to the application. From the CODESYS perspective, this operation is called creating a
boot application.

6.4.1 Creating a boot application embedded in the SMP Gateway

configuration file
Note: Before proceeding with the boot application creation, make sure you selected
the Start Embedded Boot Application setting in the SoftPLC component
General settings, in SMP Config.

 Start CODESYS from SMP Config (from the Tools menu, choose Edit CODESYS Project).
 Make sure that you are not currently connected to the SMP Gateway.

You will know that you are connected if the Login command is not available from the Online
menu, and both Device and Application branches are highlighted in green in the Devices
pane, as shown in the following picture:

 If you are currently connected to the SMP Gateway, choose Logout from the Online menu.

30 ● Chapter 6: Application Deployment

 EAS-SA QF-MKT-02 Rev.02

 Make sure any change made to the CODESYS project prior to the boot application creation
was properly saved; if in doubt, save it by choosing the Save Project command from the File
menu.

This verification is important, because SMP Config compares the timestamps of the
CODESYS project and the boot application, to ensure that the boot application contains the
latest code changes.
 From the Online menu in CODESYS, choose Create boot application.

Note: We strongly recommend that you execute the Create boot application
command twice since user experience has shown that, most of the time, the
Workbench does not generate the right boot application after the first
command execution.
CODESYS builds the project application.
 In the Save As window, make sure the File Name is Application; this is the default file
name. The complete path, including the file name, must remain unchanged to ensure the
proper embedding of the boot application in the SMP Gateway configuration file.
 Click Save.
 Do not save the CODESYS project. As stated previously, SMP Config compares the
timestamps of the CODESYS project and the boot application; if you save the project after
you create the application, SMP Config will believe that the application is not up-to-date and
will display a warning message.
 Close CODESYS.
 Back in SMP Config, save the configuration file (from the File menu, choose Save).

The SMP Gateway configuration (PAR) file now contains the boot application, and is ready to
be uploaded to the SMP Gateway.

Note: As stated several times throughout this document, this approach only works if
you embed the application (and the accompanying boot code) in the
SMP Gateway configuration file. Otherwise, you need to create the boot project
on the SMP yourself; the procedure is described in the following section.

6.4.2 Creating a boot application that is separated from the

SMP Gateway configuration file:

Note: Before proceeding with the boot application creation, make sure that the Start
Embedded Boot Application setting in the SoftPLC component General
settings, in SMP Config, is not selected.

 Start CODESYS from SMP Config (from the Tools menu, choose Edit CODESYS Project).
 Make sure that you are connected to the SMP Gateway

You will know that you are connected if the Login command is not available from the Online
menu, and both Device and Application branches are highlighted in green in the Devices
pane, as shown in the following picture:

SMP Gateway SoftPLC Reference Manual • 31

EAS-SA QF-MKT-02 Rev.02

 If you are not currently connected to the SMP Gateway, choose Login from the Online menu.
 Make sure any change made to the CODESYS project prior to the boot application creation
was properly saved; if in doubt, save it by choosing the Save Project command from the File
menu.

This verification is important, because SMP Config compares the timestamps of the
CODESYS project and the boot application, to ensure that the boot application contains the
latest code changes.
 From the Online menu in CODESYS, choose Create boot application.

Note: We strongly recommend that you execute the Create boot application
command twice while user experience has shown that, most of the time, the
Workbench does not generate the right boot application the first time.
CODESYS sends download information to the SMP Gateay for the project application.
 Do not save the CODESYS project. As stated previously, SMP Config compares the
timestamps of the CODESYS project and the boot application; if you save the project after
you create the application, SMP Config will believe that the application is not up-to-date and
will display a warning message.
 Logout from the SMP Gateway and Close CODESYS.
 Back in SMP Config, save the configuration file (from the File menu, choose Save).

The SMP Gateway configuration (PAR) file does not contain the boot application. The boot
application was sent directly to the SMP Gateway; the SMP Config file is ready to be
uploaded to the SMP Gateway.

6.5 Uploading the configuration file on the

SMP Gateway
Once the SoftPLC application is properly created, all you need to do is to upload the
SMP Gateway configuration file on the SMP Gateway. If you used the method where the
application is embedded in the SMP Configuration file, it will be uploaded with the file.
However, if you created a boot application that is separated from the SMP Gateway configuration
file, the boot application is loaded directly from CODESYS in the SMP Gateway; you still need to
upload the SMP Gateway configuration file on the SMP Gateway.

To upload the PLC application to the SMP Gateway:

 In SMP Manager, select the SMP Gateway.
 From the Update menu, choose Send Configuration File.

32 ● Chapter 6: Application Deployment

 EAS-SA QF-MKT-02 Rev.02

 Select the SMP Gateway configuration file that contains the boot application or simply the
newly created SoftPLC component in the case when the boot application is separated from the
configuration file , and then click Open; click Yes to confirm the file upload.
 Once the file is transferred, restart the SMP Gateway.

The PLC application will be started by the SMP Gateway application.

SMP Gateway SoftPLC Reference Manual • 33

 EAS-SA QF-MKT-02 Rev.02

7 Appendices

SMP Gateway SoftPLC Reference Manual • 35

 EAS-SA QF-MKT-02 Rev.02

Appendix A - Tutorial: The Sample Project

This appendix presents the sample CODESYS project that SMP Config provides by default in the
SMP Gateway configuration file. It also explains how to debug and test it on an SMP Gateway.

Testing the Sample Project without Following the Tutorial

This tutorial is targeted at new users who are not much familiar with the SMP Gateway SoftPLC
application configuration and setup process.
If you want to run the sample project application on the SMP Gateway without following the
entire tutorial, proceed as follow:
 From SMP Manager, select the SMP Gateway that will host the sample application.
 From the Tools menu, choose SMP Config.
 In the left pane of SMP Config, under the System branch, click CODESYS (SoftPLC).
 In the right pane, assign a name to the new instance (ex. Tutorial), and then press ENTER.
 Save the configuration file (from the File menu, choose Save).
 Upload the configuration file on the SMP Gateway, and restart it.

The sample application will be started as soon as the SMP Gateway will complete its own
startup.

Opening the Sample Project

The sample project is included in all new project created by opening CODESYS from
SMP Config.

To open the sample project:

 From SMP Manager, select the SMP Gateway that will host the sample application.
 From the Tools menu, choose SMP Config.
 In the left pane of SMP Config, under the System branch, click CODESYS (SoftPLC).
 In the right pane, assign a name to the new instance (ex. Tutorial), and then press ENTER.

The new instance appears in the left pane.

 The provided default settings are compatible with the sample project, and you do not need to
define any data point in the SoftPLC component: the sample project contains all required
symbol definitions and initialization code.

However, if you want to debug or run the sample application on the SMP Gateway, you must

SMP Gateway SoftPLC Reference Manual • A-1

EAS-SA QF-MKT-02 Rev.02

allow CODESYS access through the SMP Gateway firewall, as described in section 4.6,
page 18.
 In the left pane, select the Tutorial instance branch.
 From the Tools menu, choose Edit CODESYS Project.

Note: Do not use the PLCopenXML file provided by SMP Config, even if SMP Config
suggests you to do so. The symbols used in the sample project are already
properly initialized and are not present in the SMP Gateway configuration file.

If you import the PLCopenXML file, these symbols will be deleted and the sample
project will no longer work.

 CODESYS may prompt you for a version profile. Simply click Continue to select the version
profile. The user should not select a Composer Dedicated version.

The CODESYS IDE opens the sample project provided by Eaton.

The sample project contains one task (Main_Task) and two programs (PLC_MAIN
and ST_PROGRAM). These elements are presented in the sections that follow.

The Main_Task Task

Main_Task is a cyclic task that calls the PLC_MAIN program twice a second (every 500
milliseconds). This task must remain cycle based, to guarantee proper integration in the SMP
Gateway startup sequence; if necessary, the interval may be modified, up to a value of 3000 ms.

The PLC_MAIN Program

The PLC_MAIN program is divided into three parts:

 The first part is the initialization code, where RTDX data points are mapped to CODESYS
symbols; it is executed first and only once. In situations where you use this sample project as
a launching pad to start your own project, to guarantee a successful integration with the SMP
Gateway, the initialization code’s structure must remain intact. The critical elements for
which the structure must remain intact are listed below:
IF (SMF_CANMAPPLC(0) AND CODESC_INIT = FALSE) THEN
SMF_INITPLC ('Application Name is Sample', 'Author is Eaton', 'Description is a
sample program', '1.0', LIBVERSION, T#10S);
SmpMapSymbols();
CODESYS_INIT:=TRUE;
ELSE
IF (SMF_CANSTARTPLC(0) AND CODESYS_MAP = FALSE) THEN
CODESYS_MAP:=TRUE;
ELSIF (SMF_CANSTARTPLC(0) AND CODESYS_MAP = TRUE) THEN

ST_PROGRAM();

END_IF
END_IF

A-2 ● Appendix A - Tutorial: The Sample Project

 EAS-SA QF-MKT-02 Rev.02

 The second part contains startup code; it will be executed once, after the SMP Gateway
startup is completed. At this point, all data points are properly mapped to CODESYS
symbols, and all system and protocol components are started and running.
 The last part is the one that will be executed forever after: it only calls the ST_PROGRAM.

The ST_PROGRAM Program

The ST_PROGRAM contains the sample application logic code. It essentially performs the
following operations:
 Calculate the current second within the hour, and stores it in the AI_OUT_SEC_OF_HOUR
logic analog input.
 Invert the state of the BI_OUT_INVERT_CONTROL logic binary input.
 Once every minute, it deactivate local control operations on the SMP Gateway, by performing
a control operation on the _smp___localControl system data point; the sample
application is subscribed to this point.
 Change the value of the AI_OUT_CONTROL_COUNT logic analog input when a control
operation is performed on the BO_OUT_COUNTER_UPD logic binary output; an open
operation decreases the value, a close operation increases the value, and a pulse operation
resets it to 0.
 Once every minute, perform a control operation on the AO_OUT logic analog output.
 Update various logic counters and statistic entries, and publishes messages through log
entries.

Running the Sample Application in Debug Mode

You can run the sample project on the SMP Gateway that runs the SoftPLC component, which
means that it must use an SMP Gateway configuration file that contains such a component
instance.
You should note that to debug the application, you do not need to embed the application in the
configuration file: the application will be uploaded by CODESYS when it will connect to the
SMP Gateway.

To run the sample application in Debug mode:

 Close CODESYS for now, if it is currently open.
 Make sure that the CODESYS is open in the firewall (SMP Config Security
FirewallRulesCODESYS Allow cell checked). We are using a direct access, not the
passthrough.
 Back in SMP Config, choose Save from the File menu.

If you have not generated the boot application yet, or if it is not up-to-date with the
CODESYS project, some warnings will still be pending. Nevertheless, you can proceed with
the save operation.
 Using SMP Manager, upload the configuration file on the SMP Gateway.
 Re-open CODESYS from SMP Config.
 The communication channel between the CODESYS IDE and the SMP Gateway must be
defined. To do that, refer to the section Configuring the CODESYS Connection to the
SMP Gateway, page 27,

SMP Gateway SoftPLC Reference Manual • A-3

EAS-SA QF-MKT-02 Rev.02

 Now that the path to the SMP Gateway is active, from the Online menu, choose Login.

If the login operation fails, make sure the SMP Gateway is running properly; verify, using
SMP Log, that the SoftPLC component was properly started.
 When asked to download the sample application on the SMP Gateway, click Yes.
 From the Debug menu, choose Start.

You can now use the Debug menu commands to insert breakpoints and debug the application.

Testing the Sample Application on the SMP Gateway

To test the sample application on the SMP Gateway, you must add boot code to the application,
and embed the resulting package in the SMP Gateway configuration file; you will then only have
to upload the updated configuration file to the SMP Gateway and restart it to let the SMP Gateway
start and run the sample application.

To test the sample application on the SMP Gateway:

 In CODESYS, choose Save Project from the File menu.
 If you are currently connected to the SMP Gateway, choose Logout from the Online menu.
 From the Online menu, choose Create boot application.

CODESYS builds the project application.

Note: You do not have to create the boot application if you did not make any change to
the project; the boot application for the sample project is already embedded in
the SMP Gateway configuration file by default.

 In the Save As window, make sure the File Name is Application.app; this is the default
file name and it must not be changed to ensure the proper embedding of the boot application
in the SMP Gateway configuration file.
 Click Save.
 Do not re-save the CODESYS project.
 Close CODESYS.
 Back in SMP Config, make sure you selected the Start Embedded Boot Application general
setting in the SoftPLC component settings.
 Save the configuration file (from the File menu, choose Save).
 Upload the configuration file on the SMP Gateway, and restart it.

The sample application will be started as soon as the SMP Gateway will complete its own
startup.

Editing the sample application

When editing the sample application, pay attention to the following details:
 Make sure to keep the sequence logic in PLC_MAIN PRG; this is mandatory for a successful
SMP Gateway integration.

A-4 ● Appendix A - Tutorial: The Sample Project

 EAS-SA QF-MKT-02 Rev.02

 Make sure to keep the CheckBounds function which is used to validate runtime “ARRAY
out of bound” errors; we recommend that you implement any other POUs for implicit checks
(refer to CODESYS documentation for that matter).
 If you need global variables, create a new object, do not use
SMP_global_symbols_declaration.
 Take time to update the SMP_LOG, SMP_STAT and SMPINIT_PLC to match your
project.

Troubleshooting instructions
When troubleshooting your newly implemented project, we advise you to:
 Look at the SMP Gateway’s SMP Stats  \System\SoftPLC\<SoftPLC instance name > , to
get information about the current state of the SoftPLC application.
 When debugging, always put a Breakpoint in the CheckBounds function to catch quickly any
issue. Do the same for any other implicit check functions that you have implemented.

SMP Gateway SoftPLC Reference Manual • A-5

 EAS-SA QF-MKT-02 Rev.02

Appendix B - CODESYS (SoftPLC) Master

Component Reference

This appendix provides, as reference, a description of all settings that must be specified for the
SoftPLC, using SMP Config.

General Settings
General settings specify the general behavior of the SoftPLC component instance.

Setting Description
Device Prefix A string used as a prefix for all logic data points created by the SoftPLC
component instance. This prefix must be unique, along all components that
also create data points, to ensure that all point names in the system are
unique.
Note: CODESYS does not support data points names longer than 39
characters, if longer data point names are used in SMP Config, the
user must select the Standard mode with compatibility support and
define Alternate names in order to send these Alternate name to
CODESYS.
Range: 1 to 67 ASCII characters.

Enabled Indicates if this SoftPLC component instance is currently enabled. Clear this
checkmark to temporarily deactivate the execution of SoftPLC component
application.
Range: checkmark / no checkmark
Default value: checkmark (enabled)

Start Embedded Boot A checkmark indicates that the SoftPLC application will be embedded
Application within the SMP Gateway configuration (PAR) file, along with its
corresponding boot code, allowing the SoftPLC application to run
automatically at the SMP Gateway startup.
Range: checkmark / no checkmark
Default value: no checkmark

SMP Gateway SoftPLC Reference Manual • B-1

EAS-SA QF-MKT-02 Rev.02

Setting Description
Restart SMP when A checkmark indicates that an exception on a SoftPLC task will cause a
Exception Occurs restart of the SMP Gateway. Examples of what can cause an exception can
be a division by zero or when the CODESYS watchdog is triggered.
When an exception occurs, an entry will be added to the Reset log,
indicating that an exception occurred, regardless of the status of the Restart
SMP when Exception Occurs setting.
Range: checkmark / no checkmark
Default value: no checkmark

Table B-1 General settings

Logic Point Settings

Logic data points are created by the SoftPLC component, to be used and updated by the SoftPLC
application. When they are defined using SMP Config, the settings of these points are exported to
a PLCopenXML file that can then be imported in the CODESYS project.
This section presents the settings that must be specified for logic data points of all types.

Analog Inputs
The following table presents the settings that are specific to logic analog inputs of the SoftPLC
component.

Setting Description
Name The name of the logic analog input point, which must be unique within the
SoftPLC component. This name is preceded by the Device Prefix, as
specified in the general settings. The device prefix, coupled with the name,
ensures that every point managed by the system has a unique name.
The following characters cannot be used as part of the name: the comma (,),
the quotation mark ("), the semicolon (;) and the grave accent (`).
Note: CODESYS does not support data points names longer than 39
characters, if longer data point names are used in SMP Config, the
user must select the Standard mode with compatibility support and
define Alternate names in order to send these Alternate name to
CODESYS.

Range: 1 to 131 ASCII characters (including the prefix).

B-2 ● Appendix B - CODESYS (SoftPLC) Master Component Reference

 EAS-SA QF-MKT-02 Rev.02

Setting Description
Symbol The name of the logic analog input point, as it will be used in the
CODESYS application code.
If no Symbol is specified, the Name setting will be used instead, unless it
contains invalid characters per CODESYS syntax rules: if this is the case,
the Symbol setting becomes mandatory. A Symbol can be the name of a
RTDX point, it must also be unique on the whole set of symbols, not only
on a single type.
Only the following characters are allowed as part of the symbol: A-Z, a-z,
0­9, and the underscore (‘_’); however, consecutive underscores are not
allowed.
Arrays are supported and are written as follow: logic_
analog_input_name[x]. For a specific symbol, the same position should not
be used twice. An Array can use the same index twice, and the Array must
be of the same type. Also, the dimension of the Arrays must match (example
a[1] with a[2] is good but a[1] and a[2,1] is not valid).
Range: 0 to 31 ASCII characters. For arrays, the maximum is set
to 3 dimensions.

Disabled A checkmark indicates that this point is ignored by the SoftPLC component.
Range: checkmark / no checkmark
Default value: no checkmark

Scale Scaling factor used to convert 32-bit values (raw) to significant engineering
units (floating point) and vice versa. The conversion depends on the format
of the value, as provided by the parent function. The following equation is
used:
Floating-point value = (raw value * scale) + offset
Range: –3.4E38 to 3.4E38, not 0.0
Default value: 1.0

Offset Offset value used to convert 32-bit values (raw) to significant engineering
units (floating point) and vice versa. See the Scale setting above.
Range: –3.4E38 to 3.4E38
Default value: 0.0

SMP Deadband Only floating-point value changes greater than the deadband value are
reported, unless the value itself is smaller than the deadband. This ensures
that small variations around 0 are reported so that, for example, reported
values do not remain fixed at .01 when they are, in fact, 0. A value of 0 for
this setting implies that all variations, no matter how small, are reported.
Range: 0.0 to 3.4E38
Default value: 0.0

Units Units that are displayed with this point’s values in the various SMP Tools,
or through the SMP Gateway web server.
Allowed values: As shown in the drop-down list
Default value: ** Undefined **

SMP Gateway SoftPLC Reference Manual • B-3

EAS-SA QF-MKT-02 Rev.02

Setting Description
Description An optional point description, which is displayed in the various SMP Tools,
or through the SMP Gateway web server, to provide additional information
about this point at runtime.
Range: 1 to 63 ASCII characters.

Table B-2 Logic analog input settings

Binary Inputs
The following table presents the settings that are specific to logic binary inputs of the SoftPLC
component.

Setting Description
Name The name of the logic binary input point, which must be unique within the
SoftPLC component. This name is preceded by the Device Prefix, as
specified in the general settings. The device prefix, coupled with the name,
ensures that every point managed by the system has a unique name.
The following characters cannot be used as part of the name: the comma (,),
the quotation mark ("), the semicolon (;) and the grave accent (`).
Note: CODESYS does not support data points names longer than 39
characters, if longer data point names are used in SMP Config, the
user must select the Standard mode with compatibility support and
define Alternate names in order to send these Alternate name to
CODESYS.

Range: 1 to 131 ASCII characters (including the prefix).

Symbol The name of the logic binary input point, as it will be used in the CODESYS
application code.
If no Symbol is specified, the Name setting will be used instead, unless it
contains invalid characters per CODESYS syntax rules: if this is the case,
the Symbol setting becomes mandatory. A Symbol can be the name of a
RTDX point, it must also be unique on the whole set of symbols, not only on
a single type.

Only the following characters are allowed as part of the symbol: A-Z, a-z,
0­9, and the underscore (‘_’); however, consecutive underscores are not
allowed.
Arrays are supported and are written as follow: logic_
analog_input_name[x]. For a specific symbol, the same position should not
be used twice. An Array can use the same index twice, and the Array must be
of the same type. Also, the dimension of the Arrays must match (example
a[1] with a[2] is good but a[1] and a[2,1] is not valid).

Range: 0 to 31 ASCII characters. For arrays, the maximum is set

to 3 dimensions.

B-4 ● Appendix B - CODESYS (SoftPLC) Master Component Reference

 EAS-SA QF-MKT-02 Rev.02

Setting Description
Disabled A checkmark indicates that this point is ignored by the SoftPLC component.
Range: checkmark / no checkmark
Default value: no checkmark

On-Delay. Specify how long, in milliseconds, the point must keep its “on” state,
following a low-to-high transition, for the corresponding transition to be
considered valid.
Default value: 0 (low-to-high transitions reported immediately)

Off-Delay Specify how long, in milliseconds, the point must keep its “off” state,
following a high-to-low transition, for the corresponding transition to be
considered valid.
Default value: 0 (high-to-low transitions reported immediately)

Description An optional point description, which is displayed in the various SMP Tools,
or through the SMP Gateway web server, to provide additional information
about this point at runtime.
Range: 1 to 63 ASCII characters.

Table B-3 Logic binary input settings

Analog Outputs
The following table presents the settings that are specific to logic analog outputs of the SoftPLC
component.

Setting Description
Name The name of the logic analog output point, which must be unique within the
SoftPLC component. This name is preceded by the Device Prefix, as specified in
the general settings. The device prefix, coupled with the name, ensures that every
point managed by the system has a unique name.
The following characters cannot be used as part of the name: the comma (,), the
quotation mark ("), the semicolon (;) and the grave accent (`).
Range: 1 to 39 ASCII characters (including the prefix).

SMP Gateway SoftPLC Reference Manual • B-5

EAS-SA QF-MKT-02 Rev.02

Setting Description
Symbol The name of the logic analog output point, as it will be used in the CODESYS
application code.
If no Symbol is specified, the Name setting will be used instead, unless it
contains invalid characters per CODESYS syntax rules: if this is the case,
the Symbol setting becomes mandatory. A Symbol can be the name of a RTDX
point, it must also be unique on the whole set of symbols, not only on a single
type.

Only the following characters are allowed as part of the symbol: A-Z, a-z, 0­9,
and the underscore (‘_’); however, consecutive underscores are not allowed.
Arrays are supported and are written as follow: logic_ analog_input_name[x].
For a specific symbol, the same position should not be used twice. An Array can
use the same index twice, and the Array must be of the same type. Also, the
dimension of the Arrays must match (example a[1] with a[2] is good but a[1] and
a[2,1] is not valid).

Range: 0 to 31 ASCII characters. For arrays, the maximum is set to 3

dimensions.

Disabled A checkmark indicates that the point is ignored by the SoftPLC component.
Range: checkmark / no checkmark
Default value: no checkmark

Scale Scaling factor used to convert 32-bit values (raw) to significant engineering units
(floating point) and vice versa. The conversion depends on the format of the
value, as provided by the parent function. The following equation is used:
Floating-point value = (raw value * scale) + offset
Range: –3.4E38 to 3.4E38, not 0.0
Default value: 1.0

Offset Offset value used to convert 32-bit values (raw) to significant engineering units
(floating point) and vice versa. See the Scale setting above.
Range: –3.4E38 to 3.4E38
Default value: 0.0

SMP Deadband Only floating-point value changes greater than the deadband value are reported,
unless the value itself is smaller than the deadband. This ensures that small
variations around 0 are reported so that, for example, reported values do not
remain fixed at .01 when they are, in fact, 0. A value of 0 for this setting implies
that all variations, no matter how small, are reported.
Range: 0.0 to 3.4E38
Default value: 0.0

Units Units that are displayed with this point’s values in the various SMP Tools, or
through the SMP Gateway web server.
Allowed values: As shown in the drop-down list
Default value: ** Undefined **

B-6 ● Appendix B - CODESYS (SoftPLC) Master Component Reference

 EAS-SA QF-MKT-02 Rev.02

Setting Description
Description An optional point description, which is displayed in the various SMP Tools, or
through the SMP Gateway web server, to provide additional information about
this point at runtime.
Range: 1 to 63 ASCII characters.

Table B-4 Logic analog output settings

Binary Outputs
The following table presents the settings that are specific to logic binary inputs of the SoftPLC
component.

Setting Description
Name The name of the logic binary output point, which must be unique within the
SoftPLC component. This name is preceded by the Device Prefix, as specified
in the general settings. The device prefix, coupled with the name, ensures that
every point managed by the system has a unique name.
The following characters cannot be used as part of the name: the comma (,), the
quotation mark ("), the semicolon (;) and the grave accent (`).
Range: 1 to 39 ASCII characters (including the prefix).

Symbol The name of the logic binary output point, as it will be used in the CODESYS
application code.
If no Symbol is specified, the Name setting will be used instead, unless it
contains invalid characters per CODESYS syntax rules: if this is the case,
the Symbol setting becomes mandatory. A Symbol can be the name of a RTDX
point, it must also be unique on the whole set of symbols, not only on a single
type.

Only the following characters are allowed as part of the symbol: A-Z, a-z, 0­9,
and the underscore (‘_’); however, consecutive underscores are not allowed.
Arrays are supported and are written as follow: logic_ analog_input_name[x].
For a specific symbol, the same position should not be used twice. An Array can
use the same index twice, and the Array must be of the same type. Also, the
dimension of the Arrays must match (example a[1] with a[2] is good but a[1]
and a[2,1] is not valid).

Range: 0 to 31 ASCII characters. For arrays, the maximum is set to 3

dimensions.

Disabled A checkmark indicates that this point is ignored by the SoftPLC component.
Range: checkmark / no checkmark
Default value: no checkmark

SMP Gateway SoftPLC Reference Manual • B-7

EAS-SA QF-MKT-02 Rev.02

Setting Description
Open/Close Allowed A checkmark indicates that open/close control operations can be performed on
this point.
Range: checkmark / no checkmark
Default value: no checkmark

Pulse Allowed A checkmark indicates that pulse control operations can be performed on this
point.
Range: checkmark / no checkmark
Default value: no checkmark

Repeat Count A checkmark indicates that open/close control operations can be performed on
Allowed this point.
Range: checkmark / no checkmark
Default value: no checkmark

On-Delay. Specify how long, in milliseconds, the point must keep its “on” state, following
a low-to-high transition, for the corresponding transition to be considered valid.
Default value: 0 (low-to-high transitions reported immediately)

Off-Delay Specify how long, in milliseconds, the point must keep its “off” state, following
a high-to-low transition, for the corresponding transition to be considered valid.
Default value: 0 (high-to-low transitions reported immediately)

Description An optional point description, which is displayed in the various SMP Tools, or
through the SMP Gateway web server, to provide additional information about
this point at runtime.
Range: 1 to 63 ASCII characters.

Table B-5 Logic binary input settings

Subscribed Point Settings

Subscribed data points are existing physical points created by other SMP Gateway components
and that are used by the SoftPLC application.
You subscribe the SoftPLC component to these data points by defining them in the Subscribed
Point sub-branches; subscription settings are exported in the same PLCopenXML file as for logic
data points.
Although subscribed data points are defined by point type, the settings are the same for all points,
are presented in the following table:

Setting Description
Name The name of the subscribed data point, including its corresponding Device Prefix.
This point must either be an SMP Gateway system data points, or a physical data
points produced by a master or system component.
Range: 1 to 39 ASCII characters (including the prefix).

B-8 ● Appendix B - CODESYS (SoftPLC) Master Component Reference

 EAS-SA QF-MKT-02 Rev.02

Setting Description
Symbol The name of the subscribed data point, as it will be used in the CODESYS application
code.
If no Symbol is specified, the Name setting will be used instead, unless it contains
invalid characters per CODESYS syntax rules: if this is the case, the Symbol setting
becomes mandatory.
Only the following characters are allowed as part of the symbol: A-Z, a-z, 0­9, and the
underscore (‘_’); however, consecutive underscores are not allowed. Arrays are
supported and are written as follow: logic_ analog_input_name[x]. For a specific
symbol, the same position should not be used twice.
Range: 0 to 31 ASCII characters. For arrays, the maximum is set to 3
dimensions.

Disabled A checkmark indicates that this point is ignored by the SoftPLC component.
Range: checkmark / no checkmark
Default value: no checkmark

Table B-6 Subscribed data point settings

SMP Gateway SoftPLC Reference Manual • B-9