MAEKIA1TP EN v0 - Ekinex · Application manual CODESYS PLC module with KNX interface EK-IA1-TP Release 0.21 - Update: 11/2016 MAEKIA1TP_EN . 1. 1. 2

Application manual

CODESYS PLC module

with KNX interface

EK-IA1-TP

Application manual CODESYS PLC module with KNX interface EK-IA1-TP

Release 0.21 - Update: 11/2016 MAEKIA1TP_EN

© SBS S.p.A. - All rights reserved Page 2

Contents

1 Scope of the document......................................................................................................................... 4

2 Product description............................................................................................................................... 5

2.1 Generic product features ................................................................................................................. 5

2.2 Technical features ........................................................................................................................... 5

2.2.1 Hardware features .................................................................................................................... 5

2.2.2 Software features ..................................................................................................................... 5

3 Switching, display and connection elements ......................................................................................... 7

4 Configuration........................................................................................................................................ 8

4.1 PC hardware and software requirements ......................................................................................... 8

4.2 Software procurement ..................................................................................................................... 8

4.3 Setup of the CODESYS IDE ............................................................................................................ 9

4.3.1 Deployment of the framework project ....................................................................................... 9

4.3.2 Installation of the Group Address import tool from ETS projects ...............................................10

4.3.3 Individual installation of configuration files and libraries ...........................................................11

4.3.3.1 Installation of the device configuration file ...........................................................................11

4.3.3.2 Installation of ekinex KNX PLC libraries ..............................................................................12

4.3.3.3 Installation of system libraries .............................................................................................13

4.3.4 Setup and connection to the ekinex PLC .................................................................................14

5 Commissioning....................................................................................................................................17

6 Function description ............................................................................................................................18

6.1 Creation of a new KNX PLC project ................................................................................................18

6.2 Use of the ekinex ETS2PLC tool .....................................................................................................20

6.2.1 Launch of the ETS2PLC tool ...................................................................................................20

6.2.1.1 Launch of ETS2PLC as an IDE plugin ................................................................................21

6.2.1.2 Launch of ETS2PLC as a standalone program ...................................................................21

6.2.2 Main window ...........................................................................................................................22

6.2.3 Selection of project file (and project) ........................................................................................22

6.2.4 Selection of output file .............................................................................................................23

6.2.5 First import from a project ........................................................................................................24

6.2.5.1 Selection of group addresses .............................................................................................24

6.2.5.2 Display entry details ...........................................................................................................26

6.2.5.3 Name editing ......................................................................................................................26

6.2.5.4 Flag editing ........................................................................................................................27

6.2.6 Subsequent imports ................................................................................................................29

6.2.6.1 Discrepancy types ..............................................................................................................29

6.2.6.2 Discrepancy resolution .......................................................................................................30

6.2.7 Setting the PLC address..........................................................................................................36

6.2.8 Production of the output file .....................................................................................................36

6.3 Description of the KNX PLC library .................................................................................................38

6.3.1 General handling of KNX interface variables ............................................................................38




6.3.2 Function COtabUpdate ............................................................................................................39

6.3.3 Function COisUpdated ............................................................................................................39

6.3.4 Function COcached.................................................................................................................40

6.3.5 Function COread .....................................................................................................................40

6.3.6 Function COmemo ..................................................................................................................40

6.3.7 Function COwrite ....................................................................................................................41

6.4 Warning..........................................................................................................................................41

6.5 Other information ............................................................................................................................41




1 Scope of the document

This application manual describes application details for the A1.0 release of the ekinex® CODESYS PLC module with KNX interface EK-IA1-TP.

The document is aimed at the system configurator as a description and reference of device features and application programming. For further installation, mechanical and electrical details of the device please refer to the technical description datasheet.

Application manual and software tools are available for download either at www.ekinex.com or from other sites as described later in the manual.

Item File name (## = release) Version Device rel. Update Technical datasheet STEKIA1TP_EN.pdf -

A1.0 11 / 2016 Application manual MAEKIA1TP_EN.pdf - Interface tool installer ETS2PLC.msi 1.0

You can access the most up-to-date version of the full documentation for the device using following QR code:




2 Product description

2.1 Generic product features

The ekinex® CODESYS PLC module with KNX interface EK-IA1-TP is a modular device for rail mounting that allows to access data (communication objects) on the KNX bus and operate on them for logic processing.

The device is equipped with an integrated bus communication module and is designed for rail mounting in distribution boards.

The logic processing core is a PLC with a structure and a set of languages that comply to the international IEC 61131-3 standard.

The PLC in its basic version is not meant to have onboard inputs or outputs (as with common industrial automation PLCs): it is specifically targeted to operate on the communication objects that are defined and used in a KNX installation.

The PLC is capable of addressing these objects in a mostly transparent way by seeing them as own internal variables. The binding of these variables to the appropriate communication objects is managed by a firmware library; the definition of these bindings is made through a helper software tool that extracts the references to communication objects from an existing ETS project and compiles the corresponding definitions to be copied into the PLC source code.

Since the access to KNX objects is completely defined on the PLC side, and also because of the extreme flexibility and configurability if its tasks, the device needs not – and indeed does not – have an ETS application program. For this reason, it does not appear in the ETS project as a component.

The programmer and the configurator, however, shall of course have a good awareness of how both sides of the system operate on the common object base, in order to achieve the desired operation and avoid unwanted interference.

The device is powered by the KNX bus line with a 30 VDC SELV voltage and does not require auxiliary power.

2.2 Technical features

2.2.1 Hardware features

CPU ARM CORTEX M3 110MHz

Memory on board 1 MB RAM

1 MB Flash 32 kB FRAM

USB ports 1 - reserved for programming and debug

Ethernet ports none (future expansion)

Serial RS485 ports none (future expansion)

Real-time clock Yes

Power supply through the KNX bus; no auxiliary supply required.

2.2.2 Software features

PLC Runtime Single task CODESYS V3




PLC programming language(s) All CODESYS V3 / IEC 61131-3:

• IL (Instruction List) - Textual

• ST (Structured Text) - Textual

• FBD (Function Block Diagram) - Graphical

• LD (Ladder Diagram) - Graphical

• SFC (Sequential Function Chart) - Graphical

Number of KNX communication objects that can be managed 442

Size of PLC memory* Program ...................... 128 kB Variables ....................... 64 kB

Retentive area ........ 256 Bytes

minimum cycle time 2 ms

* The actual size of PLC memory available to the user might be slightly less depending on usage by the CODESYS runtime.

For further technical information, please also refer to the product datasheet STEKIA1TP_EN.pdf available on the ekinex website www.ekinex.com.

i




3 Switching, display and connection elements

The device connections are shown below:

1) USB connector for the connection to a PC

2) KNX programming pushbutton

3) KNX programming LED

4) Terminal block for KNX bus line

Figure 1: Switching, display and connection elements

The device should be connected to a PC through a common USB cable (Type A to Type B plugs) of good quality; the connection is only needed during the programming phase (and possibly during operation monitoring). The device is powered through the KNX bus; the KNX plug must therefore be connected to an active KNX line during both programming and, obviously, operation.

Since the device has no ETS application program, and therefore there is no need for programming through ETS, the KNX programming pushbutton and LED have currently no purpose; they are provided for future use. However, since the LED is switched on and off by activating the pushbutton, they can be used as a raw check that the internal processor of the device is actually running.




4 Configuration

This section contains the information required in order to correctly:

• verify that the PC to be used for development and programming complies to the required specifications;

• find and download all necessary software tools for development;

• setup a PC with the CODESYS development tools and environment;

• import the framework project, containing all the specific ekinex PLC libraries and device configuration files required by the CODESYS environment;

• setup the PC for the connection to the PLC for programming and online monitoring;

• install and use the ETS2PLC ekinex® software tool to import the KNX communication object definition into the PLC source code.

The development of the user application can, and usually will, be performed mostly offline; the device programming takes place in the commissioning phase.

Warning: please do not connect the device with the USB cable until instructed to do so in the following procedures. Doing otherwise will not harm either the device or the software installation, but may result in different operations to be performed other than those described.

4.1 PC hardware and software requirements

The hardware and software requirements for the development PC, for each tool respectively, are as follows.

• CODESYS development environment: Windows XP/7/8 (32/64 Bit); suitable PC hardware for the used Windows platform.

Further requirements may arise during installation (e.g. Microsoft .NET framework, VisualC++ redistributable packages etc.)

• ekinex ETS2PLC tool: Windows XP/7/8 (32/64 Bit); Microsoft .NET framework 4.0 or newer.

4.2 Software procurement

The required software can be downloaded free of charge from following sources:

• CODESYS development environment (IDE): from the 3S/CODESYS website www.codesys.com. Please follow the instructions on the website to find and download the most recent version available of the development environment, together with available documentation, tutorials and everything else is required for development. Registration is required to access the download: an account can be created free of charge. The installation file should have a name like ”CODESYS V3.x SPx Patch x” (according to latest release numbers) and has a size roughly around 480MB (as of version CODESYS V3.5 SP4 Patch 1). Please be aware that the CODESYS development software is made available by 3S – Smart Software Solutions, under its own terms and conditions. Ekinex is not liable for the software in subject nor it is able to offer specific support regarding its installation or usage, although the ekinex technical service will gladly try to answer customer’s enquiries in this matter to the best of its abilities.

i




• ekinex ETS2PLC tool, ekinex PLC libraries for CODESYS, framework and sample projects: from the ekinex website www.ekinex.com. Please refer to the website page dedicated to the product to find and download the most recent versions available. All required files, which will be referenced in following sections, are grouped together in a single archive file; please extract these files in a convenient location on your PC where you will be able to easily retrieve them during the installation procedure.

4.3 Setup of the CODESYS IDE

The CODESYS IDE (Integrated Development Environment) can be installed from the file downloaded from the 3S website; after installation is finished, a few configuration operations are required in order to be able to address the ekinex KNX PLC.

Please notice: in following section, all references will be made to version CODESYS V3.5 SP4 Patch 1. Other releases might have slight differences such as different menu names, different options etc.

4.3.1 Deployment of the framework project

In order to simplify the deployment of all required libraries and configuration files, a framework project is made available which contains all additional elements which would otherwise require to be installed individually. These elements are:

• the device definition file EK-IA1-TP.devdesc.xml, containing the specification of device capabilities and features

• the system libraries of the specific versions compatible with the device firmware

• the ekinex KNX-PLC library for the management of KNX-specific features

The framework project also already contains all sections which are part of a typical application, ready to be compiled with user application code.

From the IDE, choose menu option File / Project Archive / Extract Archive... and locate the file EkinexKNXTemplateProject.projectarchive contained in the downloaded ekinex distribution archive.

The IDE will ask you where the project should be extracted; you can choose the same directory of the .projectarchive file.




The extraction process will do the following:

• Add the ekinex KNX PLC device to the device repository in the IDE and copy the corresponding definition file accordingly;

• Add the system libraries and the ekinex KNX library to the device repository in the IDE and copy the corresponding definition file accordingly;

• place the template project file EkinexKNXTemplateProject.project in the specified extraction directory.

The template project file can now be copied in the desired work directory of the user, renamed with the actual project name and opened; alternatively, it can be opened directly and then saved to the desired location choosing File / Save Project as. The first method is recommended though, because it prevents accidental overwriting of the original template (which can be recovered by re-extracting it anyway); this way, a new project can be started from the template by simply copying it again.

Once this process is completed the first time, it needs not be repeated anymore (unless possibly the IDE is upgraded or reinstalled). Since all required configuration and library files have been installed, the only file required to start a new project from now on is the EkinexKNXTemplateProject.project project file, which can be kept in a convenient location and copied for every new project.

4.3.2 Installation of the Group Address import tool from ETS projects

In addition to the above procedure, the installation of the application that imports the list of used KNX communication objects from an existing KNX ETS4 project is also required.




This application is installed, and normally used, as a Codesys IDE plugin, but it can also be run standalone, as will later be explained.

In both cases, the application is used (mostly) in the same way; the details are described in a later section.

From the IDE, choose menu option Tools / ...

- to be completed -

4.3.3 Individual installation of configuration files and libraries

Warning: configuration files and libraries are normally installed through the framework project, and do not require any further intervention.

This section is only listed as reference, with the aim of giving the users a few directions in order to check and correct possible configuration problems.

4.3.3.1 Installation of the device configuration file

Open the IDE and choose menu option Tools / Device repository...

Click on the “Install...” button; make sure that the file filter option is set to “Device description files (.devdesc.xml)”, which is not the default, and select file EK-IA1-TP.devdesc.xml contained in the ekinex archive.

i

i




After the import, the device will appear in the list of installed items (under the “PLCs” category):

This procedure needs just be followed once as the environment is first installed; the device will then be available for all subsequent projects.

4.3.3.2 Installation of ekinex KNX PLC libraries

The procedure is very similar to the one described for the device installation.

Warning: in other releases of the environment, the Device Repository feature may not be available: the relevant menu item is named “Tools / Install Device...” and directly opens the device file selection dialog.

i




In the CODESYS IDE, choose menu option Tools / Library repository...

Click on the “Install...” button; make sure that the file filter option is set to “Library files (.library)”, which is not the default, and select file PLC_KNX_lib_vXXX.library contained in the ekinex archive.

After import, the library will appear in the list of installed items (under the “Miscellaneous” category):

Warning: in other releases of the environment, the Library Repository feature may not be available: the relevant menu item is named “Tools / Install Library...” and directly opens the library file selection dialog.

Once the library is succesfully installed, it can be added to an existing project by double-clicking on the Library Manager item on the project tree in the left-hand pane, then “Add library” (see also the sample project creation below).

4.3.3.3 Installation of system libraries

Only ekinex-specific files and libraries are supplied as individual files; system libraries are only supplied as part of the framework project, although their installation would follow the same guidelines. However, the following pictures lists the set of standard libraries required by the ekinex KNX PLC:

i




Please notice that the above picture should be used as a summary reference only; the libraries and respective version numbers might vary in future product releases. It is intended that the correct library and configuration file set for a given device is the one included in the respective framework project.

4.3.4 Setup and connection to the ekinex PLC

In order to allow the connection to the physical device, the Gateway component of the CODESYS system must be configured properly. The Gateway acts as a proxy between the IDE and a PLC device, either physical or virtual, and to this purpose has an interface on both sides.

The interface between the Gateway and the IDE is a TCP/IP channel, which is correctly configured by default; on the device side, the default configuration is initially also TCP/IP. This is appropriate for the connection to the “soft-PLC” / PLC simulator, which comes preinstalled, made available by CODESYS for development; the interface channel to the ekinex KNX PLC, though, is through a USB interface which uses a virtual COM port, which needs to be configured manually.

Apply power to the PLC by connecting it to a KNX bus, then connect it to your PC with the USB cable1.

The operating system should detect the new device and prompt you for the correct driver: choose to specify where to find the driver files on your PC, and select the folder containing the telestar.inf and telestar-win7.inf files from the archive downloaded from the ekinex website.

After the installation completes, a message should report that a vitrual COM port has been created:

1 Please use a good quality cable, possibly with a limited length (< 2m) in order to prevent problems in device recognition or communication.

i




If the message does not appear, open the right-click menu of the “My Computer” icon on the desktop, item “Manage”, then “Device manager” and look into group “Ports (COM & LPT)”. An entry “Telestar USB VirtualCom port (COMx)” shoud be there:

In either case, look for the “(COMx)” part, where the “x” is the number assigned by the system to the PLC port (and should remain unchanged even if the PLC is disconnected and later reconnected).

Close the CODESYS IDE (if open).

Locate the “C:\%programfiles(x86)%\3S CODESYS\GatewayPLC\Gateway.cfg” file2 and open it with a text editor. Locate the lines in the table below and modify / add them as shown, inserting the appropriate COM port number obtained from the step above (in the example COM 5 is used):

Original Modified ...

[CmpRouter]

...

0.MainNet=ether x

0.NumSubNets=1

0.SubNet.0.Interface=BlkDrvShm

1.MainNet=BlkDrvTcp

...

[CmpBlkDrvCom]

...

;Com.0.Port=1

;Com.0.Name=MyCom

;Com.0.Baudrate=115200

;Com.0.EnableAutoAddressing=1

...

...

[CmpRouter]

...

0.MainNet=ether x

0.NumSubNets=1

0.SubNet.0.Interface=BlkDrvShm

1.MainNet=BlkDrvTcp

2.MainNet=BlkDrvCom

...

[CmpBlkDrvCom]

...

Com.0.Port=5 Com.0.Name=RSRCom

Com.0.Baudrate=115200 Com.0.EnableAutoAddressing=1 ...

Once the corrected configuration file is saved, stop and restart the Gateway service through the icon in the system traybar:

2 The unit letter C: may be different according to your installation.




Now start the CODESYS IDE and open a project (such as the basic one just described) configured to use the KNX PLC.

With a double-click on the “Device” icon (the root of the tree in the left-hand pane), the gateway is displayed on the right side.

Click on the “Scan network...” button and a dialog box opens:




The “PLC-KNX” item should appear; if it does not, once the scan is finished try and launch it again with the button on the right. If the scan still fails, check following points:

• the device is still recognized correctly by the system, i.e. it is displayed (in the correct section and without a yellow question mark sign) in the system’s Device Manager; if the device does not appear at all, check if it’s is still connected and powered;

• that the steps described above for gateway configuration have all been correctly performed, with particular focus on the gateway restart operation.

If the device correctly appears on the list, select it and click “OK” to make it the active device; the right pane should appear as in the picture below.

Now the PLC can be accessed by selecting the menu command “Online / Login”.

5 Commissioning

After the device has been programmed according to user requirements, if programming has been made in a separate KNX installation, the device can be connected the final KNX network; no further operation is necessary.




6 Function description

The functionality of the device depends entirely on the application program written by the user.

This section describes the details required for following operations:

• set up a new project using the CODESYS IDE;

• export the group address list from an existing KNX ETS project;

• use the provided library functions to handle the specifics of KNX communication object interface.

6.1 Creation of a new KNX PLC project

As briefly described, after the installation, a project template is made available to be copied for the creation of new projects. Although it is certainly possible to create a project from scratch, correctly adding all dependecies manually, it seems hardly sensible to do so (besides being certainly less convenient).

Start by copying the template project file EkinexKNXTemplateProject.project, extracted during the installation, in your work directory, thereby renaming it with the desired new project name.

Open the project in the Codesys IDE; if you just performed the installation you might want to check that all libraries and devices are correctly installed, as described in previous sections.

When first opening the project, the IDE may warn you that updated versions are available for both the libraries and/or the compiler. It is mandatory that all versions referenced by the project are maintained as proposed; you might want to make sure the checkbox highlighted in the following picture is not selected, in order to avoid future notifications.




Under the “Application” tree, double click on the “GVL” item; this opens the Global variable list. This is the place where the definition of the KNX interface variable will be placed.

In order to import the definition of KNX communication objects from an ETS4 project, the ETS2PLC plgin is used: this plugin is activated by ...

The usage of the import tool is described in detail in a following section.

The Global Variable section built through the import tool is locked in order to prevent unintentional modifications by the user; however, further global variable sections can be added for custom use. As described in the paragraph devoted to the ETS2PLC tool, for instance, a further added global variable section can be used to contain the output of the ETS2PLC application when used standalone.




The PLC_PRG section contains the actual application code. In the sample project, the language preset for the code section is Structured Text, although this is only a convenient placeholder with a very short content. The supplied code section (or POU, Program Organization Unit, in the Codesys terminology) can be replaced with another one with a different language; more POUs, even with different languages, can be added, and their execution is queued by adding them under the MainTask item of the Application tree.

In the picture above, two additional POUs have been added, although the one named My2ndPOU will not be executed because it hasn’t been added under MainTask.

Further details are beyond the scope of this manual; please refer to the documentation of Codesys.

6.2 Use of the ekinex ETS2PLC tool

The ekinex ETS2PLC tool is a program that allows to extract all group address references from an ETS4 project (either in form of a project file or a database) and build the corresponding source code to be embedded into a CODESYS program.

6.2.1 Launch of the ETS2PLC tool

ETS2PLC can be used both as a plugin for the CODESYS environment (which is the default, and preferred, operation mode) and as a standalone application. In either mode, the program works in the very same way.




The difference between the two modes - apart from the obvious ease of use and integration of the plugin mode - is the following:

• in the plugin mode, the user needs not specify a name for the destination source file; actually, the text box where the file name should be entered is not even displayed. The code is directly imported into the CODESYS IDE, in the purposely reserved section with the standard name “GVL” ;

• the code generated by the plugin version cannot be directly edited by the user; this prevents errors caused by unintentional or careless modification.

In order to apply modifications due to changes in the original ETS project, or simply to different decisions of the programmer, the program can be launched again allowing the user to further operate from the point where he left.

If, for some reason, the user wants to either work outside of the IDE, or to generate an editable source file (which can all the same be imported in the PLC program, by explicitly creating its own Global Variable List section), the program executable can easily be launched; in this case, the user is required to specify the name of the destination file.

Any difference in the behaviour of the program between two operating modes will be highlighted in the usage description.

6.2.1.1 Launch of ETS2PLC as an IDE plugin

From the IDE, choose menu option Tools / ...

- to be completed -

6.2.1.2 Launch of ETS2PLC as a standalone program

ETS2PLC can be launched from the icon that has been put on the desktop during installation (unless the user chose otherwise):

When launching the executable file, several parameters can be specified on the command line (both from a command prompt or from the Windows Desktop) which allow to preset e.g. the working files or the project names for the program; these command line parameters are also exploited by the CODESYS IDE for the plugin operation.

The complete list and description of these parameters will be specified later in a dedicated section.




6.2.2 Main window

The program window is made by following sections:

1. ETS project selection

2. List of ETS group addresses found in the project, that will not appear in the output file

3. List of ETS group addresses that will appear in the output file

4. Buttons to select where the group address items will be listed and to resolve discrepancies

5. Output file selection button and name

6. Group address to be assigned to the PLC

6.2.3 Selection of project file (and project)

The first step is usually to select an ETS4 project from which the group address list will be imported.

The project source file can be in the form either of a .knxproj project or a .mdf ETS database; this can be specified through the selector on the left.

A filename can be selected either through the button on the right, or directly writing (or copying / pasting) the desired name in the text box.

After the user has specified the file, the list of the contained projects (only one in the case of a .knxproj) appears in the combo box.




If a project file name is specified on the command line (and possibly also a project name, if the file is a database), then the program automatically attempts to load the specified file. A different file can however be imported anytime.

Assuming that the project file is correctly found, the right pane is filled with the list of all the group addresses used by the Communication Objects contained therein3.

6.2.4 Selection of output file

With “output file”, the PLC source file generated by the program is meant, regardless whether it is an actual file on disk or it is sent directly to the CODESYS IDE in Plugin mode.

The output file can be selected from a command line parameter, in which case no selection box or button will be displayed; otherwise, the selection happens similarly to the project file.

3 Further operations are performed if a source file had been previously loaded; see corresponding section for details.




If the user specifies the name and path of a file which does not exist, the specification is assumed for a new file to be created; otherwise, confirmation is asked if the existing file should be imported.

On positive response, the existing file is read and its contents are imported in the right pane.

If no project file had been previously loaded, all group addresses are listed as entries in the right pane without further processing; otherwise, the two lists are processed as described in the following chapter.

6.2.5 First import from a project

For each imported entry, following data can be customized:

• the name of the corresponding variable in the CODESYS PLC domain

• the KNX flags for the Communication Object associated to the CODESYS PLC variable.

6.2.5.1 Selection of group addresses

The group addresses of the selected project are read and displayed in the selection panes: as a default, all group addresses are initially listed for export, i.e. a PLC variable will be created for each one of them.




The addresses that should be exported can be selected one or more at a time (through the usual Windows operations mouse left click, Shift-click and Ctrl-click) and then moved with the single-arrow buttons in the middle.

Double arrows move the entire address block from one side to another.

In the example pictures, all the addresses except the one named “Value 1” to “Value 4” are moved to the import set.

If some addresses need to be brought back into the non-exported set, they can of course be selected and moved in the very same way.

As a shortcut, an item can also be moved to the other pane:

• with a left double-click, outside the Flags or the Name fields (these are described in the next section);

• through a Drag-and-Drop operation (which also works with multiple selections).




6.2.5.2 Display entry details

The details of an entry can be displayed through the right-click context menu.

A dialog box is displayed which lists all values associated with the entry; the user assigned name can be edited (see also next section).

6.2.5.3 Name editing

A double-click on the on the “New name” field in the right pane allows the user to edit the assigned name for the variable; the proposed name is formed with the information from the group address item, though it can be set to any name desired (within the constraints imposed for the variable names in CODESYS).

The name can also be edited in the entry details dialog described in the previous section.

If an entry item is moved back to the left pane, and later back to the right pane, the setting made by the user to the flags’ value is kept.




If the program is used in stand-alone mode, variable names can also be modified later directly in the source code generated by the tool.

6.2.5.4 Flag editing

An imported entry means that a variable with the corresponding group address must be created in the PLC domain. There is a corresponding KNX Communication Object for each of these variables, in order to allow data exchange on the KNX bus; according to the KNX protocol, it is mandatory for each of these Communication Objects to have a set of flags, which define their behavior with regard to the bus interface.

A double-click on the “Flags” field in the right pane allows the user to edit the flags that will be attributed to the variable in the PLC. The same operation can also be done through the command in the right-click context menu .

All newly exported variables will have the default flag value of C/W/T/U, which essentially means that the PLC variable takes its value from the bus whenever possible, and transmits its new value on the bus after any internal change, but it’s not readable by other devices. For further details see the section that describes the corresponding ekinex function library for the PLC.

The flag editing function brings up a flag selection dialog that allows the user to select the desired flag combination.




The flag editing function can be applied to several items at once: the modifications will be applied to all of the selected items. If any of the flags does not have the same value for all selected objects, its checkbox appears greyed; when confirming the dialog content, flags which have a greyed checkbox will not be modified. A button allows to quickly set the default value for all flags if desired.

If an entry item is moved back to the left pane, and later back to the right pane, the setting made by the user to the flags’ value is kept.




6.2.6 Subsequent imports

When both a project file and data from a previously existing output files are loaded (either by direct choice of the user or because the program is launched as a plugin on an existing project), discrepancies between entries corresponding to a same group address will most probably arise.

Discrepancies may of course only arise when there have been changes on either side of the import: this is most commonly the case when the ETS project has been modified. The output file can only have changed if the program is launched stand-alone (or, in plugin mode, if a different output file has been manually loaded), but this is by far the least frequent occurrence.

To handle such situation, right after the second file has finished loading, the group addresses are compared and discrepancies are marked in the right pane (because the data from the ETS project is assumed to be authoritative and the output data should be adapted to it). The user is warned that no operation is possible until all discrepancies are solved:

Any of the two lists can be reloaded at any time (from the same or a different file); in this case, if both are present, the other list is read back and the comparison process is repeated from scratch.

The following pictures shows an example of all possible discrepancies.

6.2.6.1 Discrepancy types

There are three types of possible discrepancies (roughly in order of importance):

• Data type variations (marked as DPT): the Group Address is referenced in the ETS project with a DataPoint Type different from the one recorded during last import (and used in the PLC).

This is very likely to cause errors during data transmission.




• Name variations (marked as NAME): the current name assigned to the Group Address in the ETS project differs from the one recorded during last import (and used in the PLC).

Even though the name used in the PLC program needs not be related to the name in the ETS project, and thus a change of name in the ETS project is not directly relevant, it is also true that the change of name probably implies that the meaning of the Group Address might have changed. It is therefore important that the user be alerted in order to verify that the PLC is actually still operating on the intended data.

• Deleted entries (marked as DEL): The objects bound to some PLC variables are not present in the ETS project anymore.

Their Group Addresses are unused in the ETS project (otherwise we would fall in one of the previous two types of discrepancy). Technically, it is safe to allow the PLC to have the availability of such communication objects, although it might not make much sense to use them, since no other device on the bus “knows” them. There might be a few reasons to leave them (e.g. they are used in the PLC code which should rather not be modified; they are provisional placeholders for coming expansions; etc. etc.), but it must be taken care that they are properly referenced should they be introduced in the ETS project at a later time. In any case, the user should be made aware of their presence and decide for himself what to do with them.

When a discrepancy of type DPT or NAME exists for a Group Address, two entries for the same Group Address are listed, one in each pane. The resolution of the discrepancies will cause either of the two entries to be removed, according to the type of correction chosen (as will be explained later).

This is not the case for DEL type discrepancies,whose address entries only exist in the right pane.

An entry can also have both a DPT and a NAME discrepancy type; in this case, the more important DPT type is first highlighted, while the NAME discrepancy is first highlighted once the DPT discrepancy is resolved (though both can be displayed and resolved at the same time through the right-click context menu; see corresponding section).

6.2.6.2 Discrepancy resolution

There are different ways to start the resolution of discrepancies: resolution can be started for a group of entries or through the detail panel of a single entry.

The entries that are bound to form a group can be selected as described below.

• The yellow triangle button in the center starts the correction on all discrepancies:

i




• the right-click context menu has an item to correct the single entry that has been clicked on (regardless of a wider selection)4, and another to correct all selected entries:

When the correction is started, a dialog like following is displayed:

4 in this case, the single entry is considered as a group (of one), because the same actions as for an “actual” group apply.




Only the relevant sections of the dialog are highlighted, i.e. those for the types of discrepancies that exist in the group. For each discrepancy, the type of correction can be chosen between following options:

• DPT: the entries can be either removed from import (because they referred to a different object which is no longer valid) or their data type can be adjusted to the new value (because the variation will be adopted in the PLC program). These options are mutually exclusive.

If the entry is removed, the user has the option of keeping previously modified values for flags and / or variable name; these will be stored in association with the project entry (left pane), and therefore will be maintained if that entry shall be selected for import.

• NAME: As for previous case, the entries can be either removed from import, or they can take the new name from the project. These options are mutually exclusive.

• DEL: the entries can be either removed from import, or they can be left in the output file (these options are mutually exclusive). In this case, given the explicit approval of the user, the entries are not removed but their error status is waived5.

It is to be noted that, when correcting entries as a group, the actions performed (for the respective relevant discrepancy) are the same for every entry of the group. If different corrections are required, then the entries must be corrcted one by one or in different sub-groups.

For each type of discrepancy, a “neutral” selection is also possible; if all checkboxes are set as unchecked, no correction is made to the involved entries for that discrepancy type.

5 If one of the files is reloaded, a new comparison between the two lists is performed, and the waived “DEL” error is newly detected and restored.

i




The user must take care to check that all entries removed from the import are no longer referenced in the PLC program, and if they still are, to correct the program accordingly.

Another (limited) way to resolve a discrepancy on a single entry is through the “Details” dialog box; this method has the added bonus that multiple discrepancies are made apparent and can be resolved in a single pass, beside being significantly more informative about the entry on which we are operating. On the other hand, not all the options for resolution are available: specifically, it is only possible to accept the current project values, which allows to fully resolve only DPT and NAME discrepancy types.

Choosing “Show item details” on the right-click context menu for an entry that is marked with a discrepancy brings up the usual information dialog, but with the addition of the mismatching data fields and respective correction buttons:

In the following example, an entry having both a DPT and a NAME discrepancy is shown. From the list, only the DPT error is apparent:

i




Opening the details dialog box shows all existing issues:




Both discrepancies can (and usually will) be resolved immediately; just for the sake of example, though, at first we will only resolve the DPT issue that we noticed in the list.

Clicking the respective button shows that there is no longer a discrepancy in the corrected value.

If we exit the dialog now, the list correctly shows the entry with the only remaining discrepancy. Opening the details dialog also shows the correct information.

In an actual situation, now we would of course resolve the remaining discrepancy and go on with the rest of the processing.




6.2.7 Setting the PLC address

All the group addresses encountered so far are defined in ETS, and therefore they are used by devices that “exist” (i.e. have a physical address) in the KNX project at hand. The PLC though, which has not been defined in the ETS configuration, does not yet have an “identity”, that is, a physical address of its own.

In order for it to communicate on the bus, such physical address must be assigned. It is not essential that this address is “known” within ETS (though of course it is required to be unique); it is essential though that it is known, and used, by the PLC.

For this reason, the physical address of the PLC can be conveniently configured through the corresponding selection boxes; this does a little more than insert a corresponding line in the output file, though it is a convenient reminder.

6.2.8 Production of the output file

Once everything has been modified as desired and all issues are corrected, clicking on the “Export” button will produce the output file, which will either be sent to the Global Variable List section of the CODESYS IDE (in plugin mode) or written to the specified file (in stand-alone mode).

In the following picture there is an example of the output generated by the sample project used in this section: it can be compared with the above pictures for information.




The content of this file is mostly for internal use of the PLC program compiler, although a few elements can be easily recognized.

The variable listing in the first part can easily be modified by the user; for its exact meaning and syntax description, please refer to CODESYS language documentation.

Once the desired result is obtained, the program can be closed.




6.3 Description of the KNX PLC library

The ekinex KNX PLC library contains a few functions that handle the interface variables with regard to their peculiarities as instances of KNX objects.

6.3.1 General handling of KNX interface variables

There are two actual instances of the interface values: those managed by the KNX firmware stack (the KNX objects) and those in the PLC memory area (the PLC variables). These instances are normally kept synchronized by the system:

• if a communication object in the KNX stack changes value, the corresponding variable is automatically updated at the beginning of the cycle.

• if a variable changes value within a PLC cycle, its value is automatically transmitted to the bus at the end of the cycle;

The library functions allow to perform a further operations on these values (such as forcing the value transmission etc.).

KNX objects are sent on the bus or received under definite conditions. This behaviour is well-defined through the use of KNX flags; the flags associated to each variable used are defined during the import phase.

Besides the behaviour defined by flags, which is handled at the KNX communication stack level (also as a lower level with respect to the PLC program), it is also possible to force the transmission or request of data in an explicit way through the library functions which are described later in this section.

The standard behavior of flags is summarized in following table:

C Communication

Acts as a “connection switch” for the object with respect to communication; an object for which the communication flag is not set is effectively isolated from the bus (i.e. can be seen as non-existent from this point of view).

R Read

States that this object is authoritative for any read request that shoud be issued by a device on the bus; this means that the device which contains this instance of the object will be the one (and must be the only one) that responds to a read request.




W Write

Whenever a new value corresponding to the object’s group address is notified on the bus, this flag defines that the object should take on the value.

If the flag is false, the value of the object is unaffected by bus messages.

T Transmit

States that an internally triggered change of value for this object must cause a telegram to be sent on the bus to notify the new value.

If the flag is false, the value can be changed by the device, but modified values are not transmitted outside.

U Update

This flag acts similarly to the Write flag, but with an important distinction. Whereas the Write flag refers to explicit value notifications (which normally occur upon value changes and are “broadcast” for the purpose of keeping all objects up to date), the Update flag causes the value to be modified even in the case that a request for that group address is issued on the bus and a device sends the value (which may not have, and usually hasn’t, changed) in reply. Update allows a sort of “eavesdropping” to take advantage of data exchanges already taking place in order to ensure, at the earliest convenience, that objects are current (e.g. for initialization after startup).

6.3.2 Function COtabUpdate

IN Pointer to PTab Base address of the Group Address definition table

OUT Bool Return value

Initializes or updates the definition of the Communication object table in the KNX stack according to the PLC variable table definition.

This function must be called once at the beginning of the PLC program execution; the input argument is the starting address (named tab_knx in the standard import file) of the object definition table.

// In the variable definition section of the program unit:

initTab: BOOL := TRUE;

//...

IF initTab THEN COtabUpdate(ADR(tab_knx)); initTab := FALSE;

END_IF

6.3.3 Function COisUpdated

IN Pointer to PVar address of the referenced object variable


Returns TRUE if the referenced variable has been updated from the bus since last access.

An associated internal update flag is reset after the function is called (and also when a CORead is performed: see CORead description), and is set when a bus update occurs.




IF COisUpdated(ADR(Switch1_1_3_1)) THEN //...

END_IF

6.3.4 Function COcached



Updates the referenced variable with the value from the KNX stack, without issuing any request on the bus.

The two values would normally be already synchronized, unless a bus update has occurred from the start of the PLC cycle: only in this case COcached actually updates the variable value.

a = Switch1_1_3_1;

COcached(ADR(Switch1_1_3_1)) b = Switch1_1_3_1; IF a <> b THEN

//... END_IF

6.3.5 Function COread



Issues an update request on the bus for the referenced object.

The variable is updated with the value from the KNX stack (same as performing a COcached), and the function returns immediately. When the requested value is received from the bus, the variable will be updated at the next beginning of a cycle, or otherwise it can be monitored with COisUpdated and explicitly read as soon as available.

A call to COread also resets the internal update marker of the object, in order to allow the immediate use of COisUpdated.

a = Switch1_1_3_1;

// Send read request // (also resets update marker)

COread(ADR(Switch1_1_3_1)); // wait for the reply from the bus // ... do something

IF COisUpdated(ADR(Switch1_1_3_1)) THEN b = Switch1_1_3_1;

IF a <> b THEN //... END_IF

END_IF

6.3.6 Function COmemo



Writes the value of the referenced variable to the KNX stack, without issuing any transmission on the bus.




When a variable value is updated by the PLC, the corresponding object is flagged as modified and therefore marked for transmission at the end of the cycle. The COmemo function essentially resets this flag, thus allowing to modify the variable without issuing unneeded transmission requests; the transmission can e.g. be performed later or at scheduled intervals.

start = TIME(); //... IF (TIME() – start) < T#10s THEN

// Accumulate maximum value over period IF ValueA > ValueB_1_3_9 THEN

ValueB_1_3_9 := ValueA; COmemo(ADR(ValueB_1_3_9)); // Prevent untimely transmission END_IF

ELSE // End of period:

// trigger transmission now IF NOT transmissionDone THEN transmissionDone = TRUE;

COwrite(ADR(ValueB_1_3_9)); END_IF

END_IF //...

6.3.7 Function COwrite



Writes the value of the referenced variable to the KNX stack, then force its immediate transmission on the bus.

Normally, whenever a (different) value is written to the variable, this is marked to be transmitted on the bus at the end of the PLC cycle. The COwrite function allows to force transmission immediately, and regardless whether the value has actually changed.

See function COmemo for an example.

6.4 Warning

• Installation, electrical connection, configuration and commissioning of the device can only be carried out by qualified personnel

• Opening the housing of the device causes the immediate end of the warranty period

• ekinex® KNX defective devices must be returned to the manufacturer at the following address: SBS S.p.A. Via Circonvallazione s / n, I-28010 Miasino (NO) Italy

6.5 Other information

• This application manual is aimed at installers, system integrators and planners




• For further information on the product, please contact the ekinex® technical support at the e-mail address: [email protected] or visit the website www.ekinex.com

• ekinex® is a registered trademark of SBS S.p.A.

• KNX® and ETS® are registered trademarks of KNX Association cvba, Brussels

© SBS S.p.A. 2014. The company reserves the right to make changes to this documentation without notice.

Documents

MAEKIA1TP EN v0 - Ekinex · Application manual CODESYS PLC module with KNX interface EK-IA1-TP Release 0.21 - Update: 11/2016 MAEKIA1TP_EN . 1. 1. 2