Documente Academic
Documente Profesional
Documente Cultură
Design Guidelines
Version 2.00
B&R Library
Design Guidelines
V2.00
I Versions
Version Date Comment Edited by
1.20 Mar 14, 2014 Release
2.00 Mar 10, 2015 Second Edition
Table 1: Versions
II Table of Contents
1 Motivation.................................................................................................................... 3
2 Vision ........................................................................................................................... 3
3 Objectives ................................................................................................................... 3
5 Terminology ................................................................................................................ 4
6 Rules ............................................................................................................................ 5
6.1 Naming conventions ............................................................................................................................. 5
6.1.1 General information......................................................................................................................................... 5
6.1.2 Libraries, Function blocks, Functions, Variables, Type definitions .................................................................. 6
6.2 Function blocks ..................................................................................................................................... 8
6.3 Functions............................................................................................................................................. 13
6.4 Enable/Execute behavior and status information ............................................................................... 14
6.5 Parameter ........................................................................................................................................... 20
6.6 User specific commands ..................................................................................................................... 22
6.7 Error handling...................................................................................................................................... 24
6.8 Strings ................................................................................................................................................. 25
6.9 Cycle time violations and memory allocation ...................................................................................... 25
7 Compatibility ............................................................................................................. 26
1 Motivation
Software technology in Automation Studio from the user's point of view is largely shaped by librar-
ies. As a result, the terms technology and libraries are significantly interrelated or even often used
synonymously.
How these libraries are designed will therefore influence the user's experience when interacting
with these products and ultimately justifies the need for shared guidelines.
2 Vision
These guidelines are intended to support the development of software technology so that it...
• is easy to understand
• can be configured and put into operation as intuitively as possible
• is of the highest possible quality
3 Objectives
The objective of these guidelines is to optimize the quality of the user experience by ensuring...
In addition, software quality should also be improved through the use of...
4 PLCopen guidelines
5 Terminology
The following section will define some of the most important terms concerning libraries.
6 Rules
6.1 Naming conventions
ID Rules
6.1.1 Upper camel case must be applied for names if not defined differently.
To resolve ambiguities, e.g. pos, it must be clear from the context which word is meant.
Otherwise the full name must be used.
Keywords which are typically used in several programming languages are not allowed to
be used for any names. Even not with changed upper/lower case.
6.1.5
Examples:
• Access, bit, case, else, if, exit, goto, int, return, static, void, while.
ID Rules
If a library is designed for SG4, SG3 and SGC targets, then only one library name shall be
defined. Here,
6.1.8
• 8 characters can be used for the library name and
• 9 characters are significant for the function block names.
Examples:
• MTBasics, MTFilter, GmcAcp10Ax, MpRecipe, MpData
Function block names are composed of the full library name and the function name.
6.1.10
Examples:
• MTBasicsDelayTime, MTFilterLowPass, MpRecipeXml, MpDataRecorder
Constant names start with the library prefix in lower case. The following name is written
in capital letters, single words are separated with “_”. Constant names are limited to 32
characters.
6.1.11 Constants valid for more libraries: prefix + descriptive variable name
Constants valid for one certain library: library name + descriptive variable name
Examples:
• mtBASICS_POSITIVE_DIRECTION, mpRECIPE_ERR_INVALID_FILENAME
Structure types are written in Upper Camel Casing style and end with the name Type.
Data types valid for one certain library: library name + name + Type
6.1.12
Data types valid for one function block: function block name + name + Type
Function block internal structures: function block name + Internal + Type
Examples:
• MTFilterParameterType, MpRecipeXmlHeaderType
Enumeration types are written in the same style as we have defined for structure types
in (6.1.12). The word Type is replaced by Enum.
6.1.13
Examples:
• MTFilterTypeEnum, MTBasicsPWMModeEnum, MpRecipeXmlLoadEnum
The enumeration type elements are written in the same style as we have defined for con-
stants in (6.1.11). These elements are limited to 32 characters, too.
6.1.14
Examples:
• mtPULSE_MIDDLE, mpRECIPE_XML_LOAD_HEADER
Enable/Execute input
An enable or an execute input are used to set the function block busy. These commands work to-
gether with some defined status information outputs. The exact behavior of these variables and
how they are used on the most suitable is described in section 6.3.
Internal memory
Function blocks may have an internal memory, see (6.2.10).
ID Rules
Each function block has an enable or an execute input with the corresponding standard
6.2.1
status information outputs. The interaction of these variables is described in (6.4).
6.2.2 Input and output variables are written in Upper Camel Casing style.
6.2.3
Commands and
parameters these Additional
commands need information
More examples
6.2.4
6.2.5 When the FB is disabled all output variables are set to zero.
It is preferred that structures are directly integrated into the function block interface. If nec-
6.2.7
essary, pointers to structures are also allowed.
When Enable or Execute is set all parameters in the orange area are taken into account.
Update only acts on the parameters directly above.
6.2.9
A command is accompanied by the values the command needs. The values are written
above the command input.
6.2.10
Every function block has an internal structure called “Internal”. It contains data needed
6.2.11
while the function block is active. The structure type is defined according to (6.1.12).
6.2.12 Variables of this internal structure are also written in Upper Camel Casing.
6.3 Functions
• No Enable/Execute input
Functions are executed every function call.
• No internal memory
If information must be stored for the next function call, then a function block must be used
instead.
ID Rules
If functions have no return value they should return StatusID indicating the status of the
6.3.2
operation.
If functions have a useful return value they do not provide any StatusID. An error is indi-
6.3.3
cated by a “safe” return value.
Graphical representation
6.3.4
Behavior of Enable
• This functionality shall be used to switch on and off the function block like a power supply.
When it is switched on additional commands shall be used to perform some action.
• It should not be used to short term stop the FB execution, e.g. when you want to hold a
control loop. A Hold command shall be used instead.
• Status outputs like Active show that the FB is switched on, initialized and ready to perform.
Behavior of Execute
• This functionality shall be used to trigger a specific function or process. The FB is only exe-
cuted as long as this process is active.
• For the user it is important to know when the process ends. Therefore, status outputs like
Done are installed to show this event.
The advantage is that applications get easier to program and it allows a precise management of
command sequences to control machine actions.
ID Rules
• These status outputs are always related to an enable or execute input. Therefore,
they are located in the upper part (orange) of the FB interface (see 6.2.3).
6.4.1
• They have a defined hierarchy and functionality.
Depending on the configuration the following standard status outputs must be used:
Execute
Enable
It is important that this order from top to down must be maintained at the FB outputs.
A Busy – Active combination makes sense when e.g. the FB works together with a hard-
ware where it needs time to initialize and to shut down this device. Another case is when
an asynchronous process is executed in the background for some initialization purpose.
6.4.3
1…Initialization
2…Exit
It is also possible to use Active without Busy. One such example would be a simple FB
running on the PLC only, e.g. MTFilterLowPass.
6.4.4
6.4.5
6.4.6
6.4.7
1…If Execute is reset before these outputs are set, they remain high only for one cycle.
• Done can also be used to reset Execute. This kind of handshake is frequently used
in many applications.
6.4.8
1…If Execute is reset before these outputs are set, they remain high only for one cycle.
6.5 Parameter
Definition
• Parameters are used to identify a characteristic, a feature, a measurable factor that helps to
define a system.
• Parameters are constant values. They only change internally when confirmed by a certain
command like Enable, Update, SetOut.
ID Rules
An error during an update procedure together with the command Enable is treated like an
error that cannot be automatically cleared (see 6.4.6).
6.5.1
1…Sometimes the update procedure takes more than one cycle. Especially, when hard-
ware or asynchronous functionalities are involved.
6.5.2
1…If Update is reset before UpdateDone is set, it remains high only for one cycle.
• UpdateDone can also be used to reset Update. This kind of handshake is frequent-
ly used in many applications.
In the white part of a function block user specific commands may appear. To make sure that these com-
mands have the same functionality three command classes are defined below.
ID Rules
The following pool of command names which are associated with frequently used func-
tionalities should be used.
6.6.1
Power Hold
Home Reset
Stop QuickStop
6.6.2
Typical applications:
• Action with fixed execution time.
• No feedback necessary that command execution has finished.
Examples:
• Set or reset of an output variable
6.6.3
Typical application:
• Action that is started and stopped with the same command.
Examples:
• Keep the output variable constant as long as command is set.
6.6.4
1…If Command is reset before CmdDone is set, it remains high only for one cycle.
Typical applications:
• Action that is started with a certain command, maybe its duration is unknown and it
is important to know when its execution has finished successfully.
Examples:
• Start of a tuning procedure.
ID Rules
6.7.3 It is not allowed to use StatusID and ErrorID for one FB.
The error identification is written to StatusID or ErrorID. This number is given as DINT
value. Its 32 bit format is as follows:
31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
Sev C R Facility Code
6.7.5 StatusID combines error, warning and any other information identification.
Constants should be used to represent error or status numbers. Here, the notation is ac-
cording to (6.1.11). A constant name which represents an error number should contain the
abbreviation ERR, warnings the abbreviation WRN.
6.7.7
Examples:
• mpRECIPE_ERR_INVALID_FILENAME , mtERR_INVALID_PARAMETER,
mtBASICS_WRN_OUTPUT_IN_SATURATION.
6.8 Strings
ID Rules
If a string should be written into a given buffer and the buffer size is too small, an addition-
6.8.2
al output variable beside the ErrorID shall indicate the necessary buffer size.
ID Rules
To avoid cycle time violations function calls that may lock the system are not allowed.
Examples:
• Access to AR-registry
• Access to protected resources
6.9.1
• Usage of device open
• Usage of malloc
• Access to areas that are protected by semaphores
One way to avoid this problem is to use the Asynchronous function call manager (Asy-
fuma).
Allocation and deallocation of memory in the cyclic part of a function block is not allowed
because it causes memory fragmentation.
6.9.3 If memory is provided by the user, its size must also be given as an input value.
7 Compatibility
The interface of a function block is defined by its input and output variables as well as by the varia-
bles of the internal structure (see 6.2.11).
Compatible changes
The interface and functionality of the function blocks are not affected by the change.
Examples:
• Adding functions and/or function blocks to the library
• Adding data types or constants
Incompatible changes
The interface or the functionality of the function blocks are affected by the change.
Incompatible changes may require the application to be modified, which in turn requires a new
Build. This may take a considerably longer amount of time.
Examples:
• Changes to the name
o of a function or function block
o of input or output parameters
o of data types or constants
• Changes to the value of a constant
• Any changes to the internal variables
ID Rules
7.0.1 Only compatible changes must be made to Automation Runtime specific libraries.
Incompatible changes can be made to B&R standard libraries. However, any such chang-
es must be clearly communicated to the user. One possible way to denote an incompatible
library change is by adjusting the version number accordingly.
8.2 Labels
The label indicating whether a PV should be synchronized or if a library or function block is capable
of redundancy is done using pragmas in the .fun file. The following pragmas are available:
Pragma Description
In essence, only variables that are not being synchronized must be labeled.
8.2.1 Examples
FUNCTION_BLOCK fun1
VAR_INPUT
var_in_01 : {REDUND_REPLICABLE} INT;
var_in_02 : {REDUND_UNREPLICABLE} USINT;
var_in_03 : USINT;
END_VAR
VAR_OUTPUT
var_out_01 : {REDUND_UNREPLICABLE} USINT;
var_out_02 : USINT;
END_VAR
VAR_IN_OUT
var_inout_01 : INT;
var_inout_02 : {REDUND_UNREPLICABLE} USINT;
var_inout_03 : USINT;
END_VAR
VAR
var_01 : {REDUND_UNREPLICABLE} USINT;
var_02 : USINT;
END_VAR
END_FUNCTION_BLOCK
VAR
i_state : UINT; (*internal variable*)
END_VAR
END_FUNCTION_BLOCK
• PV elements that are only relevant locally (i.e. pointers, handles, idents, etc) are not permit-
ted to be tracked at all.
• These elements are not to be tracked in connection with function blocks that return data as
a result or as a temporary value that can or should be different on the two controllers. One
such example of this would be the amount of available memory.