EIO0000000735 06/2011

Functions and Libraries Introduction

Guide
06/2011

EIO0000000735.04

www.schneider-electric.com

The information provided in this documentation contains general descriptions and/or technical characteristics of the performance of the products contained herein. This documentation is not intended as a substitute for and is not to be used for determining suitability or reliability of these products for specific user applications. It is the duty of any such user or integrator to perform the appropriate and complete risk analysis, evaluation and testing of the products with respect to the relevant specific application or use thereof. Neither Schneider Electric nor any of its affiliates or subsidiaries shall be responsible or liable for misuse of the information contained herein. If you have any suggestions for improvements or amendments or have found errors in this publication, please notify us. No part of this document may be reproduced in any form or by any means, electronic or mechanical, including photocopying, without express written permission of Schneider Electric. All pertinent state, regional, and local safety regulations must be observed when installing and using this product. For reasons of safety and to help ensure compliance with documented system data, only the manufacturer should perform repairs to components. When devices are used for applications with technical safety requirements, the relevant instructions must be followed. Failure to use Schneider Electric software or approved software with our hardware products may result in injury, harm, or improper operating results. Failure to observe this information can result in injury or equipment damage. 2011 Schneider Electric. All rights reserved.

EIO0000000735 06/2011

Table of Contents

Safety Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 1 General Description of Libraries . . . . . . . . . . . . . . . . . . .

Generalities About Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Library Management in SoMachine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5 7 9
10 13

Chapter 2 Libraries Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Schneider Electric Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other Libraries Used in SoMachine . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17
18 24

Chapter 3 Function and Function Block Representation . . . . . . .

Differences Between a Function and a Function Block. . . . . . . . . . . . . . . How to Use a Function or a Function Block in IL Language . . . . . . . . . . . How to Use a Function or a Function Block in ST Language . . . . . . . . . .

27
28 29 32

Chapter 4 Creating Your Own Library . . . . . . . . . . . . . . . . . . . . . . .

Creating Your Own Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

35
35

Chapter 5 How to Find a Function or Function Block with the FFB Finder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Function and Function Block Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

37
37

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

41

EIO0000000735 06/2011

EIO0000000735 06/2011

Safety Information

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

EIO0000000735 06/2011

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

EIO0000000735 06/2011

About the Book

At a Glance
Document Scope This document introduces the libraries, libraries management and functions implementations in SoMachine. Validity Note This document has been updated with the release of SoMachine V3.0. User Comments We welcome your comments about this document. You can reach us by e-mail at techcomm@schneider-electric.com.

EIO0000000735 06/2011

EIO0000000735 06/2011

General Description of Libraries EIO0000000735 06/2011

General Description of Libraries

1
Overview This chapter describes the generalities about libraries and the library management in SoMachine. Whats in this Chapter? This chapter contains the following topics:
Topic Generalities About Libraries Library Management in SoMachine Page 10 13

EIO0000000735 06/2011

General Description of Libraries

Generalities About Libraries

Content of Libraries Libraries provide the following items that are executed in the runtime system of your controller: functions and function blocks data type definitions global variables system variables visualization objects The management of the libraries in a project is done by using Library Managers for the whole project or controller-specific. The installation of libraries on the system (PC) is done in the Library Repository dialog. Library Main Information In the Library Manager and Library Repository, you will find the following information to the libraries:
Information Name Version Company Namespace Category Description name of the library version of the library library belongs to this company short name which can be used in the application libraries are grouped by categories Example M238 PLCSystem 1.0.1.8 Schneider Electric SEC Controller M238

Library Repository The Library Repository is the editor that manages libraries installed in SoMachine. The Library Repository allows you to install or remove libraries. A library can be used in a SoMachine project only if it is installed in the Library Repository. With the installation of SoMachine, a set of libraries is installed by default. You can install new libraries or new versions of existing libraries.

10

EIO0000000735 06/2011

General Description of Libraries

Managing Libraries by Using Library Managers Libraries declared in a project are managed in the Library Manager editor. Within a SoMachine project, 2 different Library Managers are available at 2 different locations for different use cases of libraries:
Use Case Location of the Library Manager

libraries available for the in the POUs window whole project libraries available for a specific controller in the Devices window for each controller, where it is a subnode of the Application node

EIO0000000735 06/2011

11

General Description of Libraries

The figure below shows the Library Manager in the POUs window and the Library Manager in the Devices window on the left-hand side of the SoMachine Program tab:

For more information about library management, refer to CoDeSys online help: Concepts and Base Components / Library Management. For more information about Library Repository, refer to CoDeSys online help: Menu Commands / Installation / Library Repository. For more information about Library Manager, refer to CoDeSys online help: Editors / Library Manager Editor. In SoMachine, features embedded in libraries might be used for the automation as well as for the system (internal). In both cases, libraries are managed with the Library Manager of SoMachine.
12
EIO0000000735 06/2011

General Description of Libraries

Library Management in SoMachine

Organization of the Libraries in the Repository 2 types of libraries exist: Automation libraries: their functions can be used by users in the automation applications (program) System libraries: SoMachine internal libraries, not related to the automation applications (program) SoMachine default Company names: 3S - Smart Software Solution GmbH CAA Technical Workgroup Schneider Electric System The libraries are grouped in the following categories to provide a better overview: (Miscellaneous): libraries not categorized Application: libraries used in the automation applications Communication: libraries used for specific communication features Controller: libraries dedicated to SoMachine controllers Devices: libraries dedicated to distributed devices management (TeSys, Altivar, Lexium) Intern: system libraries for SoMachine internal usage and controller runtime Solution: libraries dedicated to applications solutions (Packaging, Hoisting, Conveying, etc.) System: system libraries for SoMachine internal usage and controller runtime Target: platform-specific libraries Use Cases: libraries a user can select to insert all libraries that belong to one use case Util: libraries providing additional utility functions

EIO0000000735 06/2011

13

General Description of Libraries

Namespace A library namespace is a symbol that allows the unique access to the attached library components (functions, function blocks, variables). The use of namespaces is optional, but necessary if 2 components of 2 different libraries used in the same project have the same name. The full name <namespace>.<component> will then allow a unique access to the correct component.
Case 1 Description There is a function block GEN in the library Util. The namespace of the library Util is Util. An instance of the function block GEN can be declared with or without the library namespace if the name GEN is unique within the project: MyGenerator: Util.GEN; or MyGenerator: GEN; A function block GEN has been created within the project. The use of the library Util namespace will allow the system to access the function block GEN of the library Util. Without namespace, the project function block GEN will be accessed: MyGenerator_Util: Util.GEN; MyGenerator_Project: GEN; Another library, also containing a function block called GEN, is declared in the project with namespace NewLib. The use of the namespace becomes mandatory to identify the correct function block GEN to be accessed: MyGenerator_Util: Util.GEN; MyGenerato_NewLib: NewLib.GEN;

A default namespace is defined for each library. Schneider Electric libraries default namespaces start with the prefix SE. Default namespace of a library declared in a project can be customized in the library Properties editor called from the Library Manager (In the Library Manager of a project, right click on the library then select the Properties field).

14

EIO0000000735 06/2011

General Description of Libraries

Placeholder Placeholder is a mechanism used to manage the compatibility between versions of devices and versions of libraries. When SoMachine or existing devices are upgraded or when new devices are integrated, attached Device Description Files are installed. The Device Description File contains the placeholders that define versions of libraries compatible with the device version. When manually adding a library to a device, use the placeholder to help maintain compatibility between the device version and the library version independent of the version of SoMachine. NOTE: The placeholders are defined in the Device Description Files. When the user creates a new library, there is no placeholder defined in the Device Description Files for this new library. The placeholder mechanism cannot be used when adding this custom library to the device library manager. In a project created with a previous version of SoMachine software, the versions of the libraries declared in the project will be either: kept unchanged for libraries declared with a specified version, automatically updated with the latest versions for libraries declared using the latest version concept (version identified with * in the Library Manager), automatically updated with the versions defined in the controller Device Description File after a controller device update command for libraries declared using the placeholder concept.

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

EIO0000000735 06/2011

15

General Description of Libraries

Different ways to Declare a Library in a Project There are different ways to declare a library in a project. The libraries are automatically declared when adding: a controller: IEC 61131 basic libraries: Standard and Util libraries Controller PLCSystem library Other libraries to manage embedded controller features (for example: M238 High Speed Counting) specific controller features (for example: DataLogManager, Visualization) a fieldbus manager (for example: CANopen or CANmotion manager) a fieldbus device (for example: TeSys, Altivar, Lexium) Some libraries must be added manually (for example: Toolbox and Solution libraries). NOTE: You should use only functions and function blocks documented in the online help or function or function blocks that you have thorougly tested with your application.

16

EIO0000000735 06/2011

Libraries Overview EIO0000000735 06/2011

Libraries Overview

2
Overview This chapter provides an overview of the libraries available in SoMachine. Whats in this Chapter? This chapter contains the following topics:
Topic Schneider Electric Libraries Other Libraries Used in SoMachine Page 18 24

EIO0000000735 06/2011

17

Libraries Overview

Schneider Electric Libraries

Introduction All libraries from Schneider Electric are listed below. NOTE: USER column: YES: Functions and Function Blocks of the library can be used in the users applications (program). NO: Intended only for specific system or administrative functions. Typically, these functions and function blocks have no user documentation. Category: (Miscellaneous) The following table describes the library available in the (Miscellaneous) category:
Name FeatureNotSupported Namespace none Description Virtual empty library used by the system USER NO

Category: Communication The following table describes the libraries available in the Communication category:
Name IoDrvASI refer to AS-Interface (see Modicon M238 Logic Controller, Programming Guide) IoDrvDistributedIo IoDrvModbusSerial Namespace SEN_ASI Description AS-Interface bus management functions bus management functions for distributed I/O on CANopen Modbus devices I/O scanning management for Modbus_IOScanner manager (for further information about Modbus Manager configuration, please refer to online help CoDeSys Programming System Help / Editors / Device Editors / Modbus Configuration Editor / Modbus Device Editor) USER YES

SEN_DIO SEN_MODBUS

NO NO

M2xx Communication refer to Functions to Get/Set Serial Line Configuration (see Modicon M238 Logic Controller, Programming Guide)

SEN_COM

YES Serial Line port configuration getting and setting on M238, M258 and LMC058 controllers

18

EIO0000000735 06/2011

Libraries Overview

Name

Namespace

Description Modem configuration on M238, M258 and LMC058 controllers

USER YES

SEN_MOD Modem refer to Modem Library (see SoMachine, Modem Functions, Modem Library Guide) SEN PLCCommunication refer to PLCCommunication Library (see SoMachine, Modbus and ASCII Read/Write Functions, PLCCommunication Library Guide)

YES Management of explicite data exchanges between controller and devices through Modbus or ASCII protocols NOTE: This library is not supported by the ATV IMC Drive Controller.

Category: Controller The following table describes the libraries available in the Controller category:
Name DataLogging refer to DataLogging Library (see SoMachine, Data Logging Functions, DataLogging Library Guide) Namespace SEDL Description Data logging management of controllers that support file management operations USER YES

The following table describes the libraries available in the Controller ATV IMC category:
Name Namespace Description ATV IMC High Speed Counting management USER YES

SEC_HSC ATV IMC HSC refer to High Speed Counting (see ATV IMC Drive Controller, High Speed Counting, ATV IMC HSC Library Guide) ATV IMC PLCSystem refer to PLCSystem Library (see ATV IMC Drive Controller, System Functions and Variables, ATV-IMC PLCSystem Library Guide) ATV IMC SysLib V2.3 refer to Controller Inside Programming Tool ATV IMC UserLib refer to ATV IMC Template and UserLib Library Guide SEC

ATV IMC System Functions and Variables

YES

SEC_SL23

Functions and Function Blocks for YES compatibility with Controller Inside applications (CoDeSys v2.3) ATV IMC - ATV71 host interface management YES

SEC_USER

EIO0000000735 06/2011

19

Libraries Overview

The following table describes the libraries available in the Controller LMC058 category:
Name LMC058 Expert IO refer to High Speed Counting (see Modicon LMC058 Motion Controller, High Speed Counting, LMC058 Expert I/O Library Guide) refer to Pulse Width Modulation (see Modicon LMC058 Motion Controller, Pulse Width Modulation, LMC058 Expert I/O Library Guide) Namespace SEC_EXP Description USER

LMC058 Expert I/O management YES

SEC_MC LMC058 Motion refer to High Speed Counting (see Modicon LMC058 Motion Controller, High Speed Counting, LMC058 Expert I/O Library Guide) LMC058 PLCSystem refer to PLCSystem Library (see Modicon LMC058 Motion Controller, System Functions and Variables, LMC058 PLCSystem Library Guide) LMC058 Relocation Table SEC

Functions used to get immediate YES motion axis value and to reset the detected error. LMC058 System Functions and Variables YES

SEC_RELOC

System library for Relocation Table (see Modicon LMC058 Motion Controller, Programming Guide) management.

NO

The following table describes the libraries available in the Controller M238 category:
Name M238 ASi Interface M238 HSC refer to High Speed Counting (see Modicon M238 Logic Controller, High Speed Counting, M238 HSC Library Guide) M238 PLCSystem refer to PLCSystem Library (see Modicon M238 Logic Controller, System Functions and Variables, M238 PLCSystem Library Guide) Namespace SEC_ASIITF SEC_HSC Description System library for AS-Inteface bus management M238 High Speed Counting management USER NO YES

SEC

M238 System Functions and Variables

YES

20

EIO0000000735 06/2011

Libraries Overview

Name

Namespace

Description M238 PTO and PWM management

USER YES

SEC_PTOPWM M238 PTOPWM refer to Pulse Train Output / Pulse Width Modulation (see Modicon M238 Logic Controller, Pulse Train Output, Pulse Width Modulation, M238 PTOPWM Library Guide) M238 Relocation Table SEC_RELOC

NO System library for Relocation Table (see Modicon M238 Logic Controller, Programming Guide) management.

The following table describes the libraries available in the Controller M258 category:
Name M258 Expert IO refer to High Speed Counting (see Modicon M258 Logic Controller, High Speed Counting, M258 Expert I/O Library Guide) refer to Pulse Width Modulation (see Modicon M258 Logic Controller, Pulse Width Modulation, M258 Expert I/O Library Guide) Namespace SEC_EXP Description M258 Expert I/O management USER YES

SEC M258 PLCSystem refer to PLCSystem Library (see Modicon M258 Logic Controller, System Functions and Variables, Modicon M258 PLCSystem Library Guide) M258 Relocation Table SEC_RELOC

M258 System Functions and Variables

YES

System library for Relocation Table (see Modicon M258 Logic Controller, Programming Guide) management.

NO

The following table describes the libraries available in the Controller XBTGC category:
Name XBT PLCSystem XBTGC HSC refer to High Speed Counting (see Magelis XBT GC HMI Controller, High Speed Counting, XBT GC HSC Library Guide) Namespace SEC SEC_HSC Description XBT System Functions and Variables XBTGC High Speed Counting management USER YES YES

EIO0000000735 06/2011

21

Libraries Overview

Name

Namespace

Description XBTGC System Functions and Variables

USER YES

SEC XBTGC PLCSystem refer to PLCSystem Library (see Magelis XBTGC, XBTGT, XBTGK HMI Controller, System Functions and Variables, XBT PLCSystem Library Guide) SEC_PTOPWM XBTGC PTOPWM refer to Pulse Train Output / Pulse Width Modulation (see Magelis XBTGC HMI Controller , Pulse Train Output, Pulse Width Modulation, XBTGC Library Guide)

XBTGC PTO and PWM management

YES

Category: Devices The following table describes the libraries available in the Devices category:
Name Altivar Library refer to Altivar Library Guide Namespace SE_ATV Description IEC 61131-3 standard compliant function blocks for the control of ATV variable speed drives Functions SM_Servo_Startup and SM_Stepper_Startup and associated Vizualisation components to ease motion drives and steppers commissioning. USER YES

CANmotion Lexium Library refer to CANmotion Lexium Library Guide

SEM_LXM_SM

YES

Integrated Lexium Library refer to Integrated Lexium Library Guide

SE_ILX

YES IEC 61131-3 standard compliant function blocks for the control of Lexium Integrated Drives IEC 61131-3 standard compliant function blocks for the control of Lexium 32, Lexium 05 and Lexium SD3 drives on CANopen fieldbus YES

Lexium Library refer to Lexium Library Guide

SE_LXM

TeSys Library refer to TeSys Library (see SoMachine, TeSys Motor Starters Functions, TeSys Library Guide)

SE_TESYS

YES Control of TeSys U motor starter-controller and TeSys T motor management system. The library also offers function blocks for generic control of 1 or 2 directions / 1 or 2 speed motors.

22

EIO0000000735 06/2011

Libraries Overview

Category: Solution The following table describes the libraries available in the Solution category:
Name Namespace Description Conveying applications function blocks Hoisting applications function blocks Packaging applications function blocks USER YES

SE_CONV Conveying refer to SoMachine Conveying Application Functions Conveying Library Guide Hoisting refer to SoMachine Hoisting Application Functions Hoisting Library Guide SE_HOIST

YES

SE_PACK Packaging refer to SoMachine Packaging Application Functions Packaging Library Guide

YES

NOTE: The Solution libraries have to be installed from the SoMachine Solution Extension DVD. Category: Util The following table describes the libraries available in the Util category:
Name Toolbox refer to Toolbox (see SoMachine, Miscellaneous Functions, Toolbox Library Guide) Namespace SE_TBX Description Set of utility Functions and Function Blocks complementary to the automatically declared Standard and Util libraries Functions used to get and set the interval of a Cyclic Task. USER YES

SE_TBXADV Toolbox_Advance refer to Toolbox_Advance (see SoMachine, Manage a Cyclic Task Interval, Toolbox_Advance Library Guide)

YES

EIO0000000735 06/2011

23

Libraries Overview

Other Libraries Used in SoMachine

Introduction Libraries from companies other than Schneider Electric that are useful are listed below. NOTE: USER column: YES: Functions and Function Blocks of the library can be used in the users applications (program). NO: Libraries intended for specific system or administrative functions. Typically, these functions and function blocks have no user documentation. 3S - Smart Software Solution GmbH Libraries Libraries available in (Miscellaneous) category (not categorized): some libraries for Modbus TCP system management, not for USER Libraries available in Intern, Intern CAA, Intern CANbus, Intern IODrivers, Intern Visu categories: libraries for FDT, CAA, CANbus, I/O...system management, visualization example, not for USER Libraries available in System SysLibs category: CmpPlcShell, not for USER Libraries available in Use Cases category: container libraries that gather CAA libraries about a common topic (for further information about CAA functions, please refer to CoDeSys Programming System Help / Libraries / System Libraries / CAA Libraries). The following table describes the libraries available in the Intern SoftMotion category:
Name SM3_Basic Namespace SM3_Basic Description USER

Functions for SoftMotion basic management (for YES further information about basic management, please refer to CoDeSys Programming System Help / Libraries / SoftMotion Libraries / SM3_Basic Library) NOTE: This library is only supported on Modicon LMC058 Motion Controller. Functions for SoftMotion CNC management (for YES further information about CNC management, please refer to CoDeSys Programming System Help / Libraries / SoftMotion Libraries / SM3_CNC Library) NOTE: This library is only supported on Modicon LMC058 Motion Controller. SoftMotion system management libraries NO

SM3_CNC

SM3_CNC

SM3_Drive_ 24

EIO0000000735 06/2011

Libraries Overview

System Libraries The following table describes the library available in the (Miscellaneous) category:
Name CmpEventMgr Namespace Description Event system management library USER NO

The following table describes the libraries available in the Application Common category:
Name Standard64 Standard Namespace Standard64 Standard Description Functions for wide characters strings management and long timers IEC programming standard functions and function blocks (for further information about standard functions, please refer to CoDeSys Programming System Help / Libraries / Standard Library). Programming additional functions and function blocks (for further information about additional functions, please refer to CoDeSys Programming System Help / Libraries / Util Library) USER YES YES

Util

Util

YES

Libraries available in Intern category: some of these libraries are for internal system use only. The following table describes the libraries available in the System SysLibs category:
Name Cmp Sys ISys Namespace Description System management libraries USER NO

SysTime SysTime refer to Real Time Clock management (see SoMachine, Getting & Setting Real Time Clock, SysTime Library Guide)

Controller Real Time Clock management

YES

The following table describes the library available in the System SysLibs23 category:
Name Sys23 Namespace Description System management libraries for CoDeSys v2.3 projects migration USER NO

EIO0000000735 06/2011

25

Libraries Overview

CAA Technical Workgroup Libraries The following table describes the libraries available in the Application CAA category:
Name CAA Namespace Description Libraries from CoDeSys Automation Alliance workgroup (for further information about CAA functions, please refer to CoDeSys Programming System Help / Libraries / System Libraries / CAA Libraries). Functions blocks for CANopen fieldbus management from application USER NO

CAA CiA 405 refer to CAA CiA 405 Library (see SoMachine, CANopen Management Functions, CAA CiA 405 Library Guide)

CIA405

YES

The following table describes the library available in the Intern CAA category:
Name CAA Namespace Description USER

NO Libraries from CoDeSys Automation Alliance workgroup (for further information about CAA functions, please refer to CoDeSys Programming System Help / Libraries / System Libraries / CAA Libraries).

26

EIO0000000735 06/2011

Function and Function Block Representation EIO0000000735 06/2011

Function and Function Block Representation

Overview Each function can be represented in the following languages: IL: Instruction List ST: Structured Text LD: Ladder Diagram FBD: Function Block Diagram CFC: Continuous Function Chart This chapter provides functions and function blocks representation examples and explains how to use them for IL and ST languages. Whats in this Chapter? This chapter contains the following topics:
Topic Differences Between a Function and a Function Block How to Use a Function or a Function Block in IL Language How to Use a Function or a Function Block in ST Language Page 28 29 32

EIO0000000735 06/2011

27

Function and Function Block Representation

Differences Between a Function and a Function Block

Function A function: is a POU (Program Organization Unit) that returns one immediate result is directly called with its name (not through an Instance) has no persistent state from one call to the other can be used as an operand in other expressions Examples: boolean operators (AND), calculations, conversion (BYTE_TO_INT) Function Block A function block: is a POU (Program Organization Unit) that returns one or more outputs is always called through an Instance (function block copy with dedicated name and variables) each Instance has a persistent state (outputs and internal variables) from one call to the other Examples: timers, counters In the example below, Timer_ON is an instance of the Function Block TON:

28

EIO0000000735 06/2011

Function and Function Block Representation

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

General Information This part explains how to implement a Function and a Function Block in IL language. Functions IsFirstMastCycle and SetRTCDrift and Function Block TON are used as examples to show implementations. Using a Function in IL Language The following procedure describes how to insert a function in IL language:
Step 1 Action Open or create a new POU in Instruction List language. NOTE: The procedure to create a POU is not detailed here. For more information, refer to the SoMachine global help. Create the variables that the function requires. If the function has 1 or more inputs, start loading the first input using LD instruction. Insert a new line below and: type the name of the function in the operator column (left field), or use the Input Assistant to select the function (select Insert Box in context menu). If the function has more than 1 input and when Input Assistant is used, the necessary number of lines is automatically created with ??? in the fields on the right. Replace the ??? with the appropriate value or variable that corresponds to the order of inputs. Insert a new line to store the result of the function into the appropriate variable: type ST instruction in the operator column (left field) and the variable name in the field on the right.

2 3 4

To illustrate the procedure, consider the Functions IsFirstMastCycle (without input parameter) and SetRTCDrift (with input parameters) graphically presented below:
Function without input parameter: IsFirstMastCycle Graphical Representation

with input parameters: SetRTCDrift

EIO0000000735 06/2011

29

Function and Function Block Representation

In IL language, the function name is used directly in the Operator Column:

Function IL example of a function without input parameter: IsFirstMastCycle Representation in SoMachine POU IL Editor

IL example of a function with input parameters: SetRTCDrift

30

EIO0000000735 06/2011

Function and Function Block Representation

Using a Function Block in IL language The following procedure describes how to insert a function block in IL language:
Step 1 Action Open or create a new POU in Instruction List language. NOTE: The procedure to create a POU is not detailed here. For more information, refer to the SoMachine global help. Create the variables that the function block requires, including the instance name. Function Blocks are called using a CAL instruction: Use the Input Assistant to select the FB (right-click and select Insert Box in context menu). Automatically, the CAL instruction and the necessary I/O are created. Each parameter (I/O) is an instruction: Value to inputs are set by ":=". Values to outputs are set by "=>". 4 5 In the CAL right-side field, replace ??? with the instance name. Replace other ??? with an appropriate variable or immediate value.

2 3

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

In IL language, the function block name is used directly in the Operator Column:
Function Block TON Representation in SoMachine POU IL Editor

EIO0000000735 06/2011

31

Function and Function Block Representation

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

General Information This part explains how to implement a Function and a Function Block in ST language. Function SetRTCDrift and Function Block TON are used as examples to show implementations. Using a Function in ST Language The following procedure describes how to insert a function in ST language:
Step 1 Action Open or create a new POU in Structured Text language. NOTE: The procedure to create a POU is not detailed here. For more information, refer to the SoMachine global help. Create the variables that the function requires. Use the general syntax in the POU ST Editor for the ST language of a function. The general syntax is: FunctionResult:= FunctionName(VarInput1, VarInput2,.. VarInputx);

2 3

To illustrate the procedure, consider the function SetRTCDrift graphically presented below:
Function SetRTCDrift Graphical Representation

The ST language of this function is the following:

Function SetRTCDrift Representation in SoMachine POU ST Editor PROGRAM MyProgram_ST VAR myDrift: SINT(-29..29) := 5; myDay: DAY_OF_WEEK := SUNDAY; myHour: HOUR := 12; myMinute: MINUTE; myRTCAdjust: RTCDRIFT_ERROR; END_VAR myRTCAdjust:= SetRTCDrift(myDrift, myDay, myHour, myMinute);

32

EIO0000000735 06/2011

Function and Function Block Representation

Using a Function Block in ST Language The following procedure describes how to insert a function block in ST language:
Step 1 Action Open or create a new POU in Structured Text language. NOTE: The procedure to create a POU is not detailed here. For more information, refer to the SoMachine global help. Create the input and output variables and the instance required for the function block: Input variables are the input parameters required by the function block Output variables receive the value returned by the function block Use the general syntax in the POU ST Editor for the ST language of a Function Block. The general syntax is: FunctionBlock_InstanceName(Input1:=VarInput1, Input2:=VarInput2,... Ouput1=>VarOutput1, Ouput2=>VarOutput2,...);

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

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

Function Block TON Representation in SoMachine POU ST Editor

EIO0000000735 06/2011

33

Function and Function Block Representation

34

EIO0000000735 06/2011

Creating Your Own Library EIO0000000735 06/2011

Creating Your Own Library

4
Creating Your Own Libraries
Overview SoMachine allows you to save a SoMachine project file (<projectname>.project) as a library file (<projectname>.library) and vice-versa. The library file only includes the objects managed in the POUs window.

EIO0000000735 06/2011

35

Creating Your Own Library

Procedure To create your own library project via the Program tab, proceed as follows:
Step 1 Action The SoMachine Program tab provides 2 different ways to create a new library project: Either by using the File New menu and selecting the Empty Library project template from the Categories Basic Controllers. Or by using the File Save project as... menu and selecting from the Save as type list box the Library file type. Fill in the mandatory fields in the File Project Project information. In your library project create your: functions and function blocks datatype definitions global variables visualization objects libraries NOTE: Only the objects managed in the POUs window will be considered for a library project. NOTE: If you add standard SoMachine libraries to your own library, always use placeholders to reference them. For details on referencing libraries by placeholders refer to the Adding Libraries chapter (see SoMachine, Programming Guide). 4 Execute the command File Save project and install library into library repository. Result: Your library is now installed on your PC and can be added to any project on your PC using the Library manager.

2 3

NOTE: For more detailed information refer to the CoDeSys online help. To check the syntax and find your potential errors, use the command Check all Pool objects in the menu build, before using Save the project as a compiled library or Save project and install library into library repository. It is best to first code your logic in a regular project application and use the tools available to debug your logic, such as breakpoints and inspection of data values. Once a library is compiled, the logic can not be viewed or modified.

36

EIO0000000735 06/2011

FFB Finder EIO0000000735 06/2011

How to Find a Function or Function Block with the FFB Finder

Function and Function Block Finder

Overview SoMachine provides the FFB (function and function block) finder that assists you in finding a specific function or function block even if you do not know its exact name. You can use the function and function block finder in the following programming languages that allow to insert function blocks: CFC LD IL FBD ST

EIO0000000735 06/2011

37

FFB Finder

How to Find a Function or Function Block with the FFB Finder When you are about to create programming code in the editor of the Program tab, go to the place where you want to insert the function block and open the FFB finder as follows: select the menu Edit FFB Finder or right-click at the respective place in the editor and select the command FFB Finder... from the context menu The FFB Finder dialog box opens:

38

EIO0000000735 06/2011

FFB Finder

The FFB Finder dialog box contains the following elements for finding a function or function block:
Element Find what Description In the Find what textbox enter the name of the function or function block you want to insert into your programming code. As wildcards you can use a question mark (?), which replaces none or a maximum of one character, or an asterisk (*), which can replace several characters. If you know the company that created the library which includes the function block you are searching for, you can select the following companies from the Company list: 3S - Smart Software Solutions GmbH CAA Technical Workgroup Schneider Electric System This parameter is by default set to All companies. Match case Include comments in search Check the Match case check box to perform a case sensitive search. By default, this check box is not selected. Check the Include comments in search check box to search for the entered string not only in the names of functions and function blocks but also in the comments that are saved with them. By default, this check box is not selected. Check the Search in project libraries only check box to limit the search on those libraries that are used in the current project. By default, this check box is not selected and the find operation includes all libraries that are installed on the SoMachine PC. Click the Find button or press the ENTER key to start searching for the function or function block.

Company

Search in project Libraries only

Find

Results Returned by the FFB Finder Any function or function block that matches the entered search criteria will be listed in the Results list with the Name of the function or function block as well as the Library it is saved in, its Version, and the Company that created it. A comment, if available, will be displayed in the column on the right side. The column Loaded on the left side indicates whether the library, the function or function block is saved in, is already used in the current project. To display further information on one of the functions or function blocks, select it from the list. In the field below, a graphic of the function / function block with its inputs and outputs will be displayed, as well as a description or any further information, if available.

EIO0000000735 06/2011

39

FFB Finder

Integrating a Function / Function Block into the Programming Code To integrate a function / function block that was found by the FFB Finder in your programming code, select it in the Results list, and either double-click the selected entry in the Results list, or click the OK button. The selected function / function block will be inserted at the place where your cursor is positioned in your programming code and the respective library will be loaded automatically. Repeat this operation whenever you need assistance in finding a specific function / function block.

40

EIO0000000735 06/2011

Index EIO0000000735 06/2011

Index

B C A

C
creating libraries, 35

F
FFB Finder, 37 Function and Function Block Finder, 37 Functions Differences Between a Function and a Function Block, 28 How to Use a Function or a Function Block in IL Language, 29 How to Use a Function or a Function Block in ST Language, 32

L
libraries, 10, 13 library creation, 35 Library Manager, 10 Library Repository, 10

EIO0000000735 06/2011

41

Index

42

EIO0000000735 06/2011