Properties for implementing vendor blocks
This article contains statements that can be used when creating vendor blocks – in particular, the statements to create the interface of the vendor block. Moreover, there are some examples illustrating some of the possibilities for the interface.
Information on vendor block |
---|
The interface for a vendor block (= vendor →function block or vendor →function) is created in an ST-object whereas the implementation for a vendor block is created in →C. Restrictions: The following variables are not supported in the interface of vendor blocks:
|
Please observe:
-
This article contains reference documentation of the statements that are designated to create the interface of vendor blocks. Of course, you will need to use other statements as well – for instance, the sections
VAR_INPUT ... END_VAR
,VAR_OUTPUT ... END_VAR
,VAR_IN_OUT ... END_VAR
. See "Supported ST-syntax" for information on these possibilities (or other statements that are not listed here). -
The following files are needed for the implementation:
File
Contents
the H-file
the data type for the vendor block, initialization macros (
INIT
,WINIT
) and – if no C-file is used – the implementation (usually by means of a macro)
See "The structure of the needed H-file", if you are interested in the basic structure of an H-file.an optional C-file
the implementation (if the implementation is not realized within the H-file)
All C-files are appended when the application is built so that one C-file is used for compiling. Therefore, the single C-files might have an impact on other C-files as well. Neuron recommends resetting a define at the end of the C-file, if the define is valid for one C-file only.The fact, whether a C-file will be used, is controlled by the definition
functionHasCFile
within the statement{ ImplementationProperties ( ) }
. See below for more information.optional O-files and/or lib-files
The fact, whether files for additional objects and/or libraries will be used, is controlled by the definitions
additionalObjects
andadditionalLibraries
within the statement{ ImplementationProperties ( ) }
. See below for more information.The creation of the contents of the H-file and the C-file is beyond the scope of this article. See the article "Details: Creating a vendor block" for an instruction on how to have the implementation stubs in the C-/H-file created.
-
The statements
{...}
are also known as →pragmas according to the IEC-standard. The following statements may contain integer literals or →character string literals in pragmas. A character string literal in pragmas may be enclosed in the double quote character"
as well as in the single quote character'
. For the sake of convenience, this article uses the double quote character"
for most of the character string literal in pragmas.
In this article: |
---|
Basic statements
You need to insert one of the following statements as the first line of the ST-object that contains the interface of the required vendor block.
Statement |
Purpose |
---|---|
|
This statement identifies the block as vendor block to be used for a library. This statement has the following effects:
If you want to use a C-file, specify the definition |
|
Observe: Neuron recommends using the
The name specified for the optional definition |
Interface statements
Specify the interface statements to determine the block interface (e.g. background color, height/width).
Do not save any changes done within the interface editor. Usually, you would use the interface editor to create the block interface. But when creating vendor blocks, use the interface editor only to check the interface. |
Syntax |
---|
|
The definitions for IOs { IO_definition_1, IO_definition_2, IO_definition_3 }
are applied to the specified variable of the vendor block, e.g. IO-name_1
. Neuron Power Engineer supports the definitions for IOs for
-
the return value of a function.
The general term will be "variable" in the following description.
IO definition |
Purpose |
---|---|
|
determines the orientation of the specified variable
|
|
determines the position of the specified variable
If the variable is located outside of |
|
determines the alternative name of the specified variable |
The interface definitions, e.g. Interface_definition_1
, are applied to the vendor block.
Interface definition |
Purpose |
---|---|
|
determines the height of the block when the block is inserted into the FBD-editor |
smartWidth := #
|
determines the width of the block when the block is inserted into the FBD-editor |
|
like |
|
determines the minimum height of the block – After the block has been inserted into the FBD-Editor, the block can be made smaller up to the specified minimum height. |
|
determines the maximum height of the block – After the block has been inserted into the FBD-Editor, the block can be enlarged up to the specified maximum height. |
|
determines the minimum width of the block – After the block has been inserted into the FBD-Editor, the block can be made smaller up to the specified minimum width. |
|
determines the maximum width of the block – After the block has been inserted into the FBD-Editor, the block can be enlarged up to the specified maximum width. |
|
determines the number of inputs that are required for the correct functionality of the vendor block There will be a warning, if a call of the block is inserted into an editor and too few inputs of the block call are connected within the FBD-editor or if too few parameters are specified for the block call within the ST-editor. In order to avoid the warning, you must connect or specify the required number of inputs or at least the input which is the last of them.
If you are specifying this definition, the best practice is to add the definition |
|
makes the block to be of a fixed size Subsequently, the specifications for |
|
hides the names of the inputs, outputs, in-outs and the return value of a function |
|
applied for in-out variables (= Neuron Power Engineer displays the user interface of the block as it is in logi.CAD/32. This means that only the input connection point of the in-out variable is displayed in Neuron Power Engineer. It is also possible that other variables are located on the opposite position of the input connection point. This setting is automatically applied when a block with in-out variables is migrated from logi.CAD/32 to Neuron Power Engineer. The interface editor does not provide a matching GUI element for this interface statement. |
|
determines the alternative name for the block |
|
determines the vertical alignment of the block name (or of the alternative name for the block)
See the following examples for alignment. |
|
determines the background color of the block Neuron recommends that you and/or your system integrator do not use yellow shades when designing FBD-elements because the color "Yellow" is used for tracking safe signals when developing safety-related applications. This recommendation applies in particular when you are using the legacy styling. Neuron Power Engineer does not check if colors are already used elsewhere. So the use of the yellow shades by you and/or your system integrator could have the consequence that "yellow" might also identify a non-safe logic as well. |
|
determines the color of the block text; Possible values: see the background color of the block |
|
determines the color of the inputs, outputs, in-outs and the return value of a function; Possible values: see the background color of the block |
safeStyle
|
similar to bgColor but without a value because the background color of the block is automatically determined to be "gold"Neuron recommends to use the property safeStyle only if a block tracks safe signals when developing safety-related applications and the block should be displayed with this gold background color in the smart styling. Do not misuse the property safeStyle for other blocks because the color "Yellow" is used for tracking safe signals when developing safety-related applications. The misuse of the property safeStyle could have the consequence that the color "Gold" might also identify a non-safe logic as well. |
|
determines that the vendor block is an extensible block, which means it can be expanded by additional inputs/outputs (when the block is made larger) |
|
determines the page size when the FBD-logic is displayed within the graphical FBD-editor |
|
determines the layout of the instance name for a function block instance
|
|
add value fields for inputs within the interface and determines the layout of them
|
|
add comment fields within the interface and determines the layout of them
|
Examples with interface statements
The interface of the following example... |
will look like this: |
||||||||
---|---|---|---|---|---|---|---|---|---|
|
Please note the warning icons due to |
||||||||
|
Please note the warning icons due to declared in-outs. |
Statement 'ImplementationProperties' and its definition
The statement { ImplementationProperties ( ) }
is a container for definitions to control the code generation for the vendor blocks – within the application in which the vendor block is created as well as within a library in which the vendor block will be integrated.
Syntax |
---|
|
Definition |
Purpose |
---|---|
Definitions that are affecting the structure of files |
|
|
determines additional objects and/or additional libraries to be integrated when the application is built for the target system Observe: When the library with the vendor block is generated, you are able to specify the following statements within the library configuration (see "Example for library configuration" below):
See the example below for more information. |
|
determines one or more additional required H-files By default, the additional files must be located in the sub-folder |
|
determines to use a C-file as well (besides the H-file) |
|
determines a different POU name as part of file name for the H-file as well as for the C-file (if the definition |
Definitions that are affecting the content of the H-file ( |
|
|
This definition is necessary for the correct code generation of an extensible block (see the interface definition It is sufficient for vendor blocks to only include the definition |
|
determines to add the |
|
maps the vendor block – Consequence: A list of concrete data types is created based on the specified values. For each one of these concrete data types,
Allowed values for both definitions (as a comma-separated list):
|
|
determines that the concrete data type must not be added for the name of the |
Definitions that are affecting the validation when the vendor block is called |
|
|
determines which data types are supported when the inputs/outputs of the vendor block call are connected
Allowed values for both definitions (as a comma-separated list):
Please contact Neuron, if your vendor block is to support the elementary data types |
|
determines that – in the case of a function call – the return value must be assigned to a concrete variableThis definition is useful for functions only. |
What is a generic data type? What are the appropriate elementary data types? See →generic data types
Examples with implementation properties
The following examples are mostly using the system blocks of Neuron Power Engineer to illustrate the usage of the above definitions. Observe that because of internal reasons, the system blocks are using the part CustomNameSpace := Name
instead of the rather recommended statement NAMESPACE ... END_NAMESPACE
statements.
If you are interested in how Neuron has implemented the system blocks and you want to check out the appropriate H- and C-files in detail: Contact Neuron for the sources containing the appropriate system library.
Usually, the sources are a Neuron Power Engineer project containing the system blocks and a library configuration.
Examples affecting the structure of files
Example with 'additionalLibraries' and 'additionalObjects'
Example 1 for interface |
---|
|
The generation of the library MyLibWithVendorBlocks
(see the next example) requires the additional library files additionalLibrary1
and additionalLibrary2
as well as the additional object files additionalObject
and additionalObject2
.
Please observe:
-
The location of these files depends on the statements
COMMON_SOURCE
andSUPPORTED_PTKS
specified within the library configuration. For the following library configuration, the files are searched within the pathproject/MoreFiles/src-code/WindowsX86
Without the statementCOMMON_SOURCE
, the files are searched within the pathproject/src-code/WindowsX86
-
The extension of these files depends on the statement
SUPPORTED_PTKS
as well. For the following library configuration, the filesadditionalLibrary1.lib
andadditionalLibrary2.lib
,additionalObject.o
andadditionalObject2.o
are searched.
Example for library configuration |
---|
|
Special behaviors:
-
If you define the platform
BuiltInPlc
(instead ofWindowsX86
) within the library configuration, the file location depends on the operating system where the library is used. For Windows, the sub-folder isWindowsX86
(as already specified above), for Linux the sub-folder isLinuxX86
. -
If you are using the vendor block directly within the project (in which you have created the vendor block), the additional files are searched starting with the target platform. This means if the platform
BuiltInPlc
is specified within the resource for the project, the additional files are searched within the pathproject/src-code/BuiltInPlc
.
Example with/without 'extraIncludes'
Example for interface |
---|
|
The code generation requires the H-file lcfu_iec61131__GET_TYPE_FROM_VARNAME.h
, the C-file lcfu_iec61131__GET_TYPE_FROM_VARNAME.c
as well as the additional H-files RTSSNS.h
, RTSSNSUtil.h
.
If the library configuration does not specify otherwise, Neuron Power Engineer searches within the path project/src-code
for the additional files.
Example with/without 'functionHasCFile'
Example 1 for interface |
---|
|
The code generation requires the H-file lcfu_iec61131__FIND.h
as well as the C-file named lcfu_iec61131__FIND.c
.
Compare the following copy of the system block that has been slightly modified:
Example 2 for interface |
---|
|
The code generation requires only the H-file lcfu___copies.FIND_COPY.h
. No C-file is required because of the missing definition functionHasCFile
.
Example with/without 'implementationName'
Example for interface |
---|
|
The code generation requires the H-file lcfu_iec61131__CONVERT.h
and the C-file lcfu_iec61131__CONVERT.c
– instead of the H-files lcfu_iec61131__TO_SINT.h
, lcfu_iec61131__TO_INT.h
and the C-files lcfu_iec61131__TO_SINT.c
, lcfu_iec61131__TO_INT.c
.
Please observe:
-
If the first ST-object containing the function
TO_SINT
is saved, Neuron Power Engineer auto-generates the fileslcfu_iec61131__CONVERT.h
and the C-filelcfu_iec61131__CONVERT.c
with the implementation stubs forTO_SINT
. -
If the second ST-object containing the function
TO_INT
is saved later on, Neuron Power Engineer does not update the fileslcfu_iec61131__CONVERT.h
and the C-filelcfu_iec61131__CONVERT.c
to include the implementation stubs forTO_INT
.
If you require different implementation stubs for TO_SINT
and TO_INT
, best practice is to not use the definition implementationName
. Only use the definition implementationName
, if the same implementation is required within the same file.
Examples affecting the content of the H-file
Example with/without 'expandable'
Example 1 for interface |
---|
|
Code required by the code generation |
---|
|
Example 2 for interface |
---|
|
Code required by the code generation |
---|
|
Example with/without 'passConcreteTypeParameter'
Example for interface |
---|
|
Code required by the code generation |
---|
|
Example with 'untypedCFunctionNameWhitelist' and without 'untypedCFunctionNameBlacklist' and with both of them
Example 1 for interface |
---|
|
The following list of concrete data types emerges for SUB
:
Concrete data types because of white list |
Concrete data types after of black list |
---|---|
|
identical because there is no black list |
The code generation requires that __ANY
(instead of __REAL
, __LREAL
, __USINT
etc.) is used within the implementation (e.g. in the H-file).
Code required by the code generation |
---|
|
Compare the following system block that is using the white list and the black list:
Example 2 for interface |
---|
|
The following list of concrete data types emerges for OR
:
Concrete data types because of white list |
Concrete data types after of black list |
---|---|
|
|
The code generation requires that __ANY
(instead of __BYTE
, __WORD
, __DWORD
and __LWORD
) is used within the implementation (e.g. in the H-file) but not for the concrete data type BOOL
.
Code required by the code generation (extract) |
---|
|
Example with 'useUntypedTypeStructure'
Example 1 for interface |
---|
|
Usually, the generic data type ANY_NUM
of the 2nd input would require that the concrete data types are added for the name of the typedef
structure. This is not necessary because of the implementation itself. So useUntypedTypeStructure
is used in the interface.
Code required by the code generation |
---|
|
Compare the following copy of the system block that has been slightly modified: MUL_TIME_Copy
is specified without useUntypedTypeStructure
.
Example 2 for interface |
---|
|
The code generation requires that the concrete data types are added for the name of the typedef
structures. Hence, the names for the structures are:
-
MUL_TIME_REAL
-
MUL_TIME_LREAL
-
MUL_TIME_USINT
-
MUL_TIME_UINT
-
MUL_TIME_UDINT
-
MUL_TIME_ULINT
-
MUL_TIME_SINT
-
MUL_TIME_INT
-
MUL_TIME_DINT
-
MUL_TIME_LINT
Code required by the code generation |
---|
|
Examples affecting the validation when the vendor block is called
Example with 'allowedTypeWhitelist' and without 'allowedTypeBlacklist' and with both of them
Example 1 for interface |
---|
|
The following list of concrete data types emerges for SHL
:
Concrete data types because of white list |
Concrete data types after of black list |
---|---|
|
identical because there is no black list |
These concrete data types are supported when the input IN
of a SHL
block call is connected.
Example for calls of this function |
---|
|
Compare the following system block that is using the white list and the black list:
Example 2 for interface |
---|
|
The following list of concrete data types emerges for LIMIT
:
Concrete data types because of white list – due to |
Concrete data types after of black list – due to |
---|---|
|
|
These concrete data types are supported when the inputs of LIMIT
call is connected. This is valid for all 3 inputs MN
, IN
and MX
.
Observe: Neuron Power Engineer does not support some of the concrete data types (e.g. LTIME
). Otherwise these data types would be contained due to ANY_ELEMENTARY
.
Example for calls of this function |
---|
|
Example with/without 'returnValueMustBeAssigned'
Example 1 for interface |
---|
|
Compare the following copy of the system block that has been slightly modified:
Example 2 for interface |
---|
|
Example for calls of these functions |
---|
|
Function references
The pragma { FunctionReferences }
must be used in a vendor block when functions of a library are called in the C-code of the vendor block. This pragma is needed so that Neuron Power Engineer gets sufficient information on the called functions when building the application that is using the vendor block.
Compare:
-
You do not need to insert this pragma, when only function blocks are called in the C-code of the vendor block.
-
You do not need to insert this pragma for ST/FBD/LD POUs that are calling functions. This pragma is automatically inserted by Neuron Power Engineer when you are specifying these POUs with value
INTERFACE
orDEPLOY
to be part of a library.
Complete the pragma { FunctionReferences }
by the names of the called functions. Separate the function names by the character ",
".
Example for function references |
---|
|
Definitions for variables
It is possible to add some special definitions for declared variables – in addition to the statements/definitions already described under "Supported ST-syntax".
Syntax |
---|
|
Definition for variable |
Purpose |
---|---|
|
defines that temporary values must not be connected to the appropriate in-out |
{ |
specifies the following pieces of additional data (= data elements) for the variable:
See "Defining description, comment, JSON string or type for variables or data types" for details. |
Example with '{REQUIRES_NON_TEMP_VALUE}'
Example for interface of vendor block |
---|
|
Example for call of vendor block (integrated in library) |
---|
|
Additional statements not to be used
The following statements are only included for reference. Do not use these statements for your manually created interfaces.
Syntax |
---|
|
Statement |
Purpose |
---|---|
|
ignores the entire contents of the current ST-object See "Statement to ignore ST-objects" for details on this statement. |
|
At present, this statement is not supported to be used within vendor blocks. |
|
At present, this statement is not supported to be used within vendor blocks. See "Statement to suppress warnings" for details on this statement. |