All about Add-On Instructions
Add-on instructions are generally a small, tested, pocket of code that the user wants to reuse multiple times in program(s). This tutorial will go into best practices of add-on instructions, how the add-on instructions work, and it will go through creating a custom add-on instruction.
There are some best practices for add-on instructions, which are listed below.
Testing: Add-on instructions cannot be changed online so make sure whatever instruction the program is using is tested and will work in a production environment. Again, add-on instructions cannot be changed online.
Single Level: It is good practice to write only a single level of add-on instructions, meaning that you should not have add-on instructions within add-on instructions, even though it is possible.
Naming: It is good practice to name add-on instructions with a consistent prefix. For example, “ao_IO_DigitalOutput” would be an add-on instruction for a digital output. When add-on instructions have a consistent prefix, it is easy to distinguish them against other data types. For example, there also might be a User Defined Datatype (UDT) named “IO_DigitalOutput”.
Building your First Add-on Instruction – Digital Output
To add a new add-on instruction into the program, right click on the add-on instruction in the project explorer, and click “New Add-On”. A popup will come up asking to specify the name of the add-on instruction. For this tutorial, it will be named “ao_IO_DigitalOutput”.
After the name is specified, click ok, then the “Add-On Instruction Definition” window will come up as seen in Figure 2 below.
This holds a lot of “metadata” for the add-on instruction like name and description. The add-on instruction can also be configured for a different type of program, for example, a function block diagram. There is also revision information for the add-on instructions.
The parameter tab is the most important window when creating an add-on instruction. In this window, the input and output values are created for the add-on instruction. In Figure 3 below, “EnableIn” and “EnableOut” tag were already in there, and the other parameters were created.
Each of the parameters will be an attribute inside of the add-on instruction data structure. Each instance of the add-on instruction will have the exact same data structure. To inspect the columns of the parameters:
Name – The name of the parameter
Data Type – The data type for the parameter. Depending on what the usage is, the types will be limited. Input and output parameters have to be basic data types. InOut parameters can be virtually any valid data type.
Alias For – This is for specifying an alias for the parameter. The alias has to be a local tag within the add-on instruction. Local tags will be discussed later.
Default – This is for specifying a default value that will be set for each instance creation. This is especially useful if you have a lot of instances. If a parameter is usually “10” other than a couple of instances, the user can specify the default and only change the instances that are unlike the rest. It is not very useful if the parameter is required because the user will have to supply a tag other than a constant value.
Style – The style that the user wants this data in.
Required (Req) – If checked, a tag is required to specify this parameter in each instance. If not checked, the tag will be a constant value in the instance. If a parameter is not required, the user can still access the tag in preceding or succeeding logic. Basically, the unrequired parameter is still inside the instance data structure so it can be read or written at any point in the logic.
Visible (Vis) – If checked, the parameter will be visible in the add-on instruction block. If left unchecked, it will be hidden. If the user doesn’t absolutely need the parameter to be visible in the add-on instruction, it is best practice to have it invisible (unchecked). If a parameter is an output parameter and is a Boolean type, the parameter will show up as a little output flag next to the add-on instruction instance.
Description – The description of the parameter. These descriptions as visible inside the add-on instruction logic. It is very good practice to put text in for descriptions unless the tag name is all that is needed to describe the parameter; it rarely is.
External Access – This is almost always set automatically through the set of other attributes of the parameter. Selection options are Read Only and Read / Write.
Usage – There are three types of usage parameters: input, output, and InOut
Input – Must be basic data types (BOOL, INT, or DINT). Input parameters can be read-only or read/write and they can be accessed from the outside of each instruction instance. Input parameters are how the rest of the program interacts with the instances of the add-on instructions.
Output – Must be basic data types (BOOL, INT, or DINT). Output parameters are Read Only. They can be accessed outside the add-on instruction but can only be written inside of the add-on instruction. Output parameters are usually what the add-on instruction is calculating, or logically controlling.
InOut -These are tag references ONLY. They are required to be required meaning an external tag must be referenced for these parameters. They can be of any valid data type. They can be read and written only internally in the add-on instruction. The InOut parameters do not show up within the add-on instruction instance data structure. This is an important concept to grasp because most people do not use this usage type correctly.
For our first add-on instruction, create the add-on instruction as shown in figure 3.
Local Tags Tab
The local tags tab as seen in Figure 4 is to specify local tags for the add-on instruction, and they can be of any valid data type. These tags are only available to be accessed inside the add-on instruction logic. These local tags are great for temporary data registers the add-on needs to complete the logic. For example, if an add-on instruction needs a one-shot instruction, which would be a great local tag application.
For our first add-on instruction, we will just be using the input and output parameters in our logic, so no need for local tags this time.
Figure 5 above shows the Scan Modes tab, and there are three “modes” that each add-on instance can be in. Each mode can have a separate routine and has access to all the local tags and parameters inside the add-on instruction. The prescan and post-scan routines are outside the scope of this tutorial and are rarely used. The EnableInFalse routines are commonly used when the add-on instruction instance has logic in front of it. This is because the some of the data may need to be cleared when the logic in front of the instruction yields false.
For our instruction, we will not have any of these supplemental mode routines.
This tab is used to generate a signature for the add-on instruction. The ID is a checksum of the entire instruction, so if anything changes down the road the id will change with it. It also keeps a signature history of the add-on instruction for additional revision control.
Change History Tab
This simply tracks the changes detected in the add-on instruction. No picture needed.
In the help tab seen above in Figure 7, the user can specify additional text to help his or her predecessors. The help file will be visible if the instruction is highlighted in the program and the user presses the F1 key.
Add on Routine
This is a simple but useful routine. When the automatic command comes in if the output is not in manual override by the force bits, the output will come on. When the force INT is a value of 1, the output is forced off, and when the output is 2 the output is forced on.
If you’re following along with your first add-on instruction, make sure your logic looks like the one seen in Figure 8.
Seen in Figure 9 above, in the main routine, two instances of the new add-on instruction were created. As seen in the figure, Output1. Cmd is True and the add-on instruction Output parameter is also True. If the force parameter is changed from zero to 1, Output1.output is off, and so on. It is working exactly as expected.
To see what is happening inside the add-on instruction. Highlight the instruction, right click on it, and click “Open Instruction Logic” as seen in Figure 10 below.
Once that is clicked the user is taken inside of the instance and the user can view what is taking place. The background is gray meaning that the user cannot edit the rungs online as seen in figure 11 below.
Hopefully, this gives you a nice jump on creating some of your own add-on instructions and see the value and power in reusable code. I encourage you to start small and build small building blocks – eventually, they will turn into a beautiful “house” of code. Make sure you test along the way.