Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


Overview

This document offers an overview of the function, structure and operation of the Engineering Interface (ENI).

Further details are provided in the following documents:

- ENI Server quick start - overview and first steps

- Online help for ENI Server, ENI Admin, ENI Control (components of the ENI Server Suite) and ENI Explorer

- TwinCAT PLC Control manual or online help for TwinCAT version 2.9


Engineering Interface (ENI)

ENI function

The ENI (TwinCAT Engineering Interface) is used for managing the blocks (objects) of a TwinCAT PLC project in a central independent data storage system, which is also accessible for other users and applications.

The following requirements with regard to data management during the preparation of an automation project are thus met:

Access for various applications to the same project data:

In addition to the programming system, other tools with ENI interface can access a shared database. Examples are external visualisations or ECAD systems etc. requiring the data generated in TwinCAT PLC Control, or which generate data themselves that are required in the programming system.

Multi-user operation:

The current versions of the blocks of a project can be made accessible to a whole group of users. For other users, the blocks checked out by a user are marked as 'in progress' and cannot be modified. Several users can thus work in parallel on the same project without overwriting each other's object versions.

Version management for projects and associated resources (shared objects):

Once an object was checked out of the database, modified and checked in again, a new version of the object is created in the database, although the old versions are preserved and can be retrieved if necessary. A change history is logged for each object and for each complete project. Versions can be checked for differences.

Structure and communication

The ENI serves a data storage system for project data objects. This may be an existing database system or a local file system. The ENI interface is split into a server part and a client part, so that the storage system may reside on another computer (otherwise multi-user operation would not be possible).

ENI Server

The Engineering Interface Server runs as a separate service. HTTP with XML as user data is used as communication protocol. The programs 'ENI Admin' and 'ENI Control' are used for managing and controlling the server. (ENI Server, ENI Admin and ENI Control are part of the ENI Server Suite.)

ENI Client

Clients of the ENI Server may be TwinCAT PLC Control programming systems or other applications requiring access to the database. All clients have the same rights.

Connection between ENI Server and database system (DB)

The ENI does not define its own storage format. Appropriate drivers (database interface) are used for the connection to an existing data management system. Drivers are available for the database systems 'Visual SourceSafe 5.0', 'Visual SourceSafe 6.0', 'Tortoise SVN', and for a local file system. For connecting to other existing storage systems, an ENI Driver Development Kit can be made available to the user.

The data storage system currently served by an ENI Server is specified in ENI Control. The clients of the server can then access this system, and only this system.

HTTP as communications protocol, XML for transfer

The HTTP protocol and the generally accepted standard XML format are used for the data exchange with the ENI server. The HTTP protocol enables operation through firewalls and execution of certain operations via standard tools.

A client C++ DLL (client interface) can be used for encapsulating the protocol in C++ classes, so that access to the ENI Server is not necessarily limited to HTTP and XML software.


Structure of the data storage system (ENI Explorer)

The ENI Server manages the blocks generated by the PLC Control or other clients within a folder structure inside the file storage system. They are stored as objects and identified by a type and access rights. In addition, a version history is kept for each object, if this feature is supported by the database. Within a folder, the object name and type have to be unique.

ENI Explorer

Like Windows Explorer, the ENI Explorer is an independent program that can be connected with the required ENI Server via the associated ENI access data. Like ENI Server, ENI Admin and ENI Control it is part of the ENI Server Suite. The ENI folder/object structure can be displayed in ENI Explorer and the required database functions can be called up directly, independent of the data management system and of TwinCAT PLC Control. Object type, access rights, current check-out status and user are displayed.

Integration into TwinCAT PLC Control

TwinCAT PLC Control is a potential client of the ENI Server. For each project, the connection to the ENI Server can be defined. The required project blocks can then be created as objects in the data management system. To this end, they are assigned to one of the three object categories. Objects are stored fully, i.e. in addition to the block content, block properties such as access rights are also transferred via the XML format. For each object category, automated exchange with the data management system can be defined.

XML format for the objects

The following example shows the representation of a block in XML format. It includes, for example, information about: block name (<name>), block type (<pou>), path of the block in the object organiser structure (<path>), access rights for the eight possible user groups (<accesslevels>), and the block content in the declaration part (<interface>) and program part, which in this case is written in structured text (<ST>,<body>).

<?xml version="1.0"
encoding="ISO-8859-1"?>
<pou>
    <accesslevels> rw,rw,r,rw,r,rw,rw,rw
</accesslevels>
    <path> \/languages </path>
    <name> ST_EXAMPLE </name>
    <flags> 4 </flags>
    <interface>
        <![CDATA[PROGRAM ST_EXAMPLE
        VAR
            YVAL: INT := -250;
            BOTTOM: INT := -250;
            RUN_STRING: STRING(20) := 'Start';
            OFFSET: INT := 2;
        END_VAR
        ]]>
        </interface>
        <st>
            <body>
                <![CDATA[RUN_STRING:='Start';
                IF (YVAL < 0) THEN
                    YVAL := YVAL + OFFSET;
                    BOTTOM := YVAL + OFFSET;
                END_IF
                ]]>
            </body>
        </st>
</pou>

ENI object categories

Different data object categories are distinguished for administration via the ENI interface:

  1. Project-specific objects: blocks that were created specially for a particular project.
  2. Shared objects: blocks that are usually used in several projects, e.g. block libraries.
  3. Automatically generated compilation objects: Data that are only generated during processing by an application, e.g. symbol files that are created during compilation of a project (i.e. they do not directly correspond to an object!)
  4. Local objects (are not managed within the data storage system)

Objects are assigned to one of the categories (1, 2 or 4) as part of the project options (automated) or object properties (individual).

The ENI parameters can be configured separately for each of the object categories 1-3.

Project structure in the data storage system

In the associated data storage system and therefore "in the ENI" under the "root" that was configured in ENI Control, one or several paths and folders are created for each project, in which the project blocks are represented as objects (for example, a separate folder could be defined for each ENI object category).

Each project object is allocated a data type. As a result, the block names transferred from the TwinCAT PLC Control are allocated a type-specific extension and a type symbol, thus representing the objects outside the programming system.

Operation of the ENI interface in TwinCAT PLC Control

In TwinCAT PLC Control, the ENI can be activated as a project option. Dialogs are then available for the following functions:

  1. Specification under project options of whether and for which ENI object category a newly created object should be assigned.
  2. Configuration of the type of connection to the ENI in the project options for each of the three ENI object categories (project objects, shared objects, compilation files):
  • Access data: port; access rights; project in the ENI storage area, with which the current project is associated)
  • Specification of the type and timing of the exchange with the data storage system (e.g. calling of objects from the database whenever a project is opened, or checking out for each started modification, etc.)
  3. Individual allocation of an object to an object category (see above) in the object properties of each object
  4. Input of user name and password via a database login dialog (project menu) for accessing the data management system
  5. Database commands in the project menu, for individual objects or for the whole project:
  • Call / call all
  • Check out / check out all
  • Check in / check in all
  • Undo checkout / ... for all objects
  • Version history for the object or project
  • Display changes
  • Label version
  • Insert shared objects (from the database system into the local project)
  • Refresh status


ENI Admin and ENI Control

Certain settings can only be made locally at the ENI server. The programs 'ENI Admin' and 'ENI Control' are available for this purpose. Like ENI Server and ENI Explorer, they are installed with the ENI Server Suite, indicated by an icon in the system tray of your computer.

For starting ENI Admin (ENIAdmin.exe), the administrator password has to be entered. The program is used to define users, user groups, access rights and the administrator password, for licence management and for displaying the object data types.

The ENI administrator password is required for starting ENI Control (ENIService.exe). The program is used for setting up the appropriate database driver during installation. It also enables specific stopping and restarting of the ENI service (which is usually started automatically), or to run it via a different user account. In addition, certain communication parameters (communication timeout, port etc.) of the server/client connection can be changed. An event log is also available.


Overview: Quick start and first steps

This document contains a short overview of the ENI functionality and instructions for the installation and first configuration of the ENI Server regarding the connection of a TwinCAT PLC Control project to a database. The programs required for managing the ENI Server, i.e. ENI Admin, ENI Control and ENI Explorer, are installed with the server.

ENI overview

ENI is the ENgineering Interface of TwinCAT PLC Control. It consists of a server and a client part.

The ENI Server runs as a separate service. Typical clients are one or several programming systems and other tools requiring access to the same resources, which are managed within a shared data storage system (DB). When working with the PLC Control, this enables version management for projects, multi-user operation, and access to the project objects for external programs.

Supported database systems

The server concept enables a shared database to be installed on a remote computer. As standard, the ENI Server currently supports a local file system and the database systems 'Visual SourceSafe 5.0', 'Visual SourceSafe 6.0' and 'Tortoise SVN'.

However, the ENI Server can also be adapted to other database systems. The associated description can be found in the ENI Driver Development Kit — Programmer's Guide (not included with this documentation).

Communication with the ENI Server

TCP/IP is used as client/server protocol. Detailed information about communication can be found in the following documents:

- ENI Client Development Kit – Programmers Guide (not included with this documentation)

- ENI Driver Development Kit, XML format for ENI objects (not included with this documentation).

ENI in TwinCAT PLC Control:

The use of ENI in TwinCAT PLC Control is optional. Further information about this project option can be found in the user manual for TwinCAT PLC Control, version 2.9.

Installation and start-up:

The ENI Server is installed with the setup. After the installation and after each computer restart, the ENI Server service is started automatically, and its availability is indicated by an icon in the system tray. The icon is displayed as long the ENI Server is running.

Administration

The ENI Server is managed via the programs ENI Control and ENI Admin: ENI Control is used to specify basic server settings that cannot be changed during operation, e.g. database connection, communication settings etc. It can also be used to start and stop the ENI Server. ENI Admin can be used to configure users, groups and access rights during operation, and to execute licence management functions.

The ENI programs can be opened via the start menu or via a menu coupled with the ENI icon. The latter is called up by right-clicking on the icon in the system tray (bottom right). Here you will also find the 'event log', which may also be started from ENI Control.

QuickStart

Preparation

  1. Install the database that is to be served via the ENI service, following the installation guide provided with the database. Ideally, the database should be installed on the same computer as the ENI Server.
  2. Start the database.
  3. Create a database
  • 'Local file system' database: Create a new empty folder.

Pre-installation information

Mode and licence:

  • 'Server' mode: A licence is required. Standard database drivers are available, depending on the licence. The server can be addressed via any computer within the network. Apart from tool cooperation, this is used for distributed development.

The connection between client and ENI Server requires TCP/IP.

Administrator rights on the computer are required.

During installation, you will be asked for an ENI administrator password. During the initial installation, this request may be acknowledged with OK (without inputting a password).

The installation also includes installation of the programs ENI Admin and ENI Control, which are used for managing and handling the ENI. The program ENI Explorer is also installed.

Installation

  1. Insert the installation CD.
  2. During installation, the program ENI Control for setting up the database connection is called up: The first dialog to appear is 'Enter Administrator Password'. If the software has not been installed before, close the dialog with OK, without inputting a password. If ENI Control had already been installed, a valid administrator password has to be entered. This will open the 'Database' dialog, in which the user can set the driver for the required data management system and the "root" path for object storage in the selected database as described below.

Name | Description
Select Database Driver A list of all installed drivers appears in the check box next to 'Select Database Driver'. If the required driver is not listed, click on the first button next to the list and select the associated driver file on the computer. Which drivers are available depends on which ENI licence is installed. The licence-free version of the ENI Server Suite includes only the driver for a local file system. The following driver files are currently available, depending on the licence:
  • "File System Driver" (ENIDrvFileSystem.edd, local file system)
  • "SourceSafe 5.0" (ENIDrvSourceSafe5.edd)
  • "SourceSafe 6.0" /ENIDrvSourceSafe6.edd)
  • "Tortoise SVN" (ENIDrvSVN.edd)
Location of 'srcsafe.ini' | Only for 'Visual SourceSafe 5.0' or. '..6.0': Set the path in the SourceSafe ini file located in the SourceSafe installation folder. A browse dialog can be used for setting the path. Open the dialog by double-clicking on the input field.
Root project Enter the project path, which was created here for the database,

- for 'File System Driver': e.g. "D:\project1\...."

- for 'Visual SourceSafe 5.0' or. '..6.0': e.g. "$/project1".

Under this folder, one or more folders for storing the objects to be managed can later be created via an associated definition in the TwinCAT PLC Control project options. Alternatively, the folders can be created in advance directly in the database. In this case, they can already be selected during configuration.
ENI user | Special user account used by the ENI Server for internal tasks. This account must be created in the user administration of the database.
ENI password | The password for the above-mentioned user account.

Close the dialog with OK.

  3. The installation routine for the ENI Server will now start. If successful, a user configuration can now be created via ENI Admin: An account is pre-defined by default, with an associated "DefaultUser" entry in the 'User Name' column.

Please note the following regarding the user definition:

  • If a user account is created via ENI Admin, an associated account (with identical name and password) must exist in the database. Otherwise the user account cannot be used. For Visual SourceSafe, for example, Visual SourceSafe Admin is used for user administration.
  • Each user account should be assigned to a group. Select the required group, click on 'Edit' and add the associated user accounts to the group.
  4. Closing ENI Admin completes the installation routine; ENI Server should have started automatically on your system and be ready to use. In this case, 'Running' will be displayed under 'Current status' in ENI Control, and the ENI icon in the system tray will be active.

Start

  • After successful installation, and subsequently after each computer restart, the ENI Server service is started automatically, and the ENI icon in the system tray will be active.
  • ENI Control or ENI Admin have to be started explicitly, but they cannot run at the same time. After the installation, these programs appear in the ENI Server start menu, although they can also be accessed via the menu that opens when right-clicking on the ENI icon in the system tray.

Connecting a TwinCAT PLC Control project

Connecting a project with the ENI Server:

1. Start TwinCAT PLC Control and open any project.

2. - Select the command 'Project' 'Options' 'Project database'.

  • Activate the option 'Use project database (ENI)'.
  • Click on 'Configure ENI...'.
  • In the 'Project objects' category, configure the ENI connection as follows:
Name | Description
TCP/IP address | Address of the computer on which the ENI Server is installed; e.g. "localhost"
Port | Number of the port to which the ENI Server is tuned. Default: 80
Project name | Name or path of the project as it should appear in the database under the path entered under root in ENI Control for database connection (e.g. "project1\project objects" -> will appear, for example, in Visual SourceSafe under $/project1/project objects, if "$/" was defined as root.)

Leave the remaining settings unchanged.

3. Click on 'Continue' and enter the same information for this introductory example in the categories 'Shared objects and compilation files' as under 'Project objects'.

4. Close the option dialogs with OK. You will be asked to log on to the ENI Server: Enter the name and password for a valid user account.

5. While the project is now connected with the database, the blocks themselves are still "local". For transferring them to the database, select the command 'Project' 'Database link' 'Multiple specification' and select the 'Project' database option in the object properties dialog. In the tree that appears select all blocks you would like to place in the database and confirm with OK:

6. The selected blocks are now connected with the database via the connection configured in the 'Project objects' option dialog. For these blocks, all typical database functions are now available in the context menu.


Database: Tortoise SVN

Installation Procedure:

Download: Tortoise SVN, Version: 1.5.9

ENI Control settings:

Driver is copied into the default path C:\Program Files\Beckhoff\TwinCAT ENI Server\Drivers during the installation.

Communication settings

Run the ENIControl.exe, click on Communication Tab, make the settings as shown in Figure 1.

Figure 1: Communication settings in ENI Control

Database settings

Run the ENIControl.exe, click on Database Tab, browse for the ENIDrvSVN.edd and install the driver copied into the above mentioned path. Before proceeding with the settings, a SVN repository should be created.

Figure 2: Local Repository settings in ENI Control.

Repository Settings:

Conceptually speaking, a Subversion repository is a sequence of directory trees. Each tree is a snapshot of how the files and directories versioned in your repository looked at some point in time. These snapshots are created as a result of client operations, and are called revisions.

There are two options for storing data in SVN repositories. In other words, there are two types of repositories that can be laid.

  1. Native Filesystem (FSFS)
  2. Berkeley Database (BDB)

Create Repository:

  1. Open the windows explorer
  2. Create a new folder and name it e.g. SVNRepository
  3. Right-click on the newly created folder and select TortoiseSVN -> Create Repository here....
    A repository is then created inside the new folder. Don't edit those files yourself!!!. If you get any errors make sure that the folder is empty and not write protected.
  4. During this process of creation, one can choose between the two mentioned types of Subversion databank.

Figure 3: Repository creation

Local Access to Repository:

To access your local repository you need the path to that folder. Just remember that Subversion expects all repository paths in the form file:///C:/SVNRepository/. Note the use of forward slashes throughout. (see Figure 2 for example)

To access a repository located on a network share you can either use drive mapping, or you can use the UNC path. For UNC paths, the form is file://ServerName/path/to/repos/. Note that there are only 2 leading slashes here. (see Figure 4 for example).

Figure 4. Repository on another Network PC.

Warning

Do not create or access a Berkeley DB repository on a network share. It cannot exist on a remote filesystem. Not even if you have the network drive mapped to a drive letter. If you attempt to use Berkeley DB on a network share, the results are unpredictable - you may see mysterious errors right away, or it may be months before you discover that your repository database is subtly corrupted.

Tip

If you really need to access a repository through a network share, create the repository with fsfs (Native filesystem) format. If you need to provide server access as well, you will need Subversion Server 1.1 or higher.