Details: Creating a vendor block

How to create a →vendor block:

  1. Create a new ST-object within the project: For instance, open the context menu, select New and ST-Object. In the dialog, enter any object name. This instruction uses the name TestVendor for the ST-object.

  2. Copy the following code, and paste it into the opened editor for the ST-object. (warning) Do not save the pasted code yet.

    {CustomImplementation}
    NAMESPACE com.oem1.lib1
      FUNCTION TestVendor01
        { ImplementationProperties (functionHasCFile; ) }
        VAR_INPUT
          in1 : INT;
          in2 : BOOL;
        END_VAR
        VAR_OUTPUT
          out1 : BOOL;
        END_VAR
      END_FUNCTION
    END_NAMESPACE

    Explanation of the statements necessary for the vendor block:

    Replacement or additional statement

    Purpose

    {CustomImplementation}

    This statement identifies the block as vendor block to be used for a library.
    (info) Due to this statement, vendor blocks in C-code are also called CustomImpl blocks in the everyday language of Neuron.

    FUNCTION TestVendor01
    { ImplementationProperties (functionHasCFile; ) }

    functionHasCFile is an optional keyword. This keyword is only required, if your vendor block uses your own C-code. The instruction assumes that this is the case.
    The keywords would not be required, if a vendor block is realized by macros in the H-file only.

    (info) The statement { ImplementationProperties ( ) } is a container for other keywords as well. See "Properties for implementing vendor blocks" for those possibilities.

  3. Adjust the code as requested.
    Mind the following:

    • Neuron recommends the usage of a namespace as specified in the above code, just adjust the name com.oem1.lib1 according to your needs. Always specify the namespace before you save the ST-object because the namespace is part of the C structure and function name.  

    • If you want to create a vendor function block instead of a vendor function, change the keyword FUNCTION to FUNCTION_BLOCK and the keyword END_FUNCTION to END_FUNCTION_BLOCK.

    • Adjust the rest of the code so that it fits your need: For example, change the names of the function or function block, of the inputs and of the outputs. Or change the data type of the inputs and of the outputs.  Or add new inputs and outputs as known from the ST-editor.

      Neuron recommends you to declare all types of variables within the interface – in particular, if the values of the variables should be kept for the block from one execution of the application to the next one. So you will avoid problems that might occur otherwise when updating the changed application by using the resource manager (also known as reloading the application). 

      If you do declare variables just within a C-file and some belated changes of the block logic are needed, Neuron recommends you to create a new block containing the changed logic – instead of actually changing the block. Subsequently, it will be possible to use the resource manager for updating the changed application.
      Neuron Power Engineer does not prevent the change of a block with variables only contained in the C-file. If you make such changes and use the resource manager to update the changed application, unexpected errors might occur. For example, the application might be executed wrongly or it might be terminated, the PLC might even be terminated. In such cases, best practice is to build the application anew and then to load it onto the PLC.

  4. When the code is complete, save the ST-object.

    Result (when the implementation stubs have not been generated yet): Neuron Power Engineer generates 2 files with the required implementation stubs.

    File

    Name of file for above code

    Details

    the C (source) file

    lcfu___COM.OEM1.LIB1.TESTVENDOR01.c

    This file is only auto-generated, if functionHasCFile has been specified.

    the H-file

    lcfu___COM.OEM1.LIB1.TESTVENDOR01.h

    If you are interested in the basic structure of an H-file, read the article "The structure of the needed H-file".

    (info) These files are located in the newly created folder src-code on the same level as the ST-object. Mind the capital letters of the POU names within the file names. This is important, if you are using the created library with the vendor block on a Linux computer. If you are using the library just on a Windows computer, the POU names with lower letters (in the file names) would be of no consequence.
    If the folder src-code is not visible, the value for the configuration variable lc3.src_code.filter.enable has to be changed. Contact your Neuron Power Engineer administrator for this configuration change.
    (info) The auto-generated implementation stubs for the vendor block are decorated with a preceding comment (DO NOT MODIFY THIS SECTION). Observe the following:

    1. Do not delete this preceding comment (DO NOT MODIFY THIS SECTION) in the H-/C-files.
      Reason: When you change the interface of the vendor block and save the ST-object later again, the implementation stubs are automatically updated as long as the preceding comment is still included in the H-/C-file.

    2. Do not include any of your code in the auto-generated implementation stubs with the preceding comment (DO NOT MODIFY THIS SECTION).
      If you do so anyway, your code will be overwritten as it has been placed in the auto-generated implementation stubs. There will be no prompt before saving the ST-object containing the vendor block.

    3. The parts outside the auto-generated implementation stubs will not be touched by Neuron Power Engineer so that your code in the H-/C-file will not be overwritten when later saving the ST-object containing your vendor block again.

    4. Observe that the auto-generated implementation stubs for some types of vendor blocks are not decorated with the preceding comment (DO NOT MODIFY THIS SECTION). In this case, the update of the implementation stubs does not take place as described above. So, if you modify an already saved ST-object containing such a vendor block and save this ST-object again, it is likely that the ST-object is not in sync with the generated files anymore.

      These affected vendor blocks are:

      • vendor blocks created during the Simulink import

      • vendor blocks created during the migration from logi.CAD/32

      • vendor blocks created when using a Neuron Power Engineer before version 3.25.0

      Example for such a vendor block: In Neuron Power Engineer version 3.23.0, you have declared a CustomImplementation function with a data type as the return value of this function and you saved the ST-object containing this vendor block. This saving action created the C-/H-files with the implementation stubs but without the preceding comment (DO NOT MODIFY THIS SECTION). Later on, you used the data type in the function and you saved this change. Due to the missing preceding comment (DO NOT MODIFY THIS SECTION), the C-/H-files with the implementation stub were not updated. Workaround in Neuron Power Engineer version 3.25.0 or later: Rename the automatically generated files to a unique name. Save the ST-object containing the vendor block to again create the H-/C-file with the implementation stubs. But these stubs are decorated with the preceding comment (DO NOT MODIFY THIS SECTION). Finally, transfer your code to the newly generated C-/H-files and delete the renamed C-/H-files.

  5. Close the editor for the ST-object.

  6. Recommended: Clean the project.

  7. Start to create the required code: Enter the C-code in the C-file and/or enter the macros in the H-file.
    Observe the following:

    1. If you are declaring variables with a →generic data type within the interface of the vendor block, you must also adapt the auto-generated implementation stubs and/or use the statement { ImplementationProperties ( ) } and some of its definitions within the interface.

    2. If you are calling functions of a library in the C-code of the vendor block, you must use the pragma { FunctionReferences } within the interface.

    3. Use POU-unique names (when possible, project- and POU-unique) for all C-identifiers that are available in a global namespace. Details on the reason for this can be found under "The dos and don'ts when working", section "When creating blocks with C-code".

    The following articles will assist you in creating the H-file and using the statements/pragmas in the interface:

See "Creating your library using the vendor block", if you want to deploy the vendor block along with a library.