How to Create a Calculation Using Lua Script

The Lua scripting engine is an integral part of system:inmation and provides a versatile and dynamic tool to create custom data streams, calculate KPI values and to manage existing data items. In this example we will use the Lua scripting capabilities to make a simple calculation using data obtained from Realtime data sources to generate a new stream of values.

For this example we will be creating new objects in the I/O Model tree so it is necessary to log in as an administrator to complete the tasks.

It is helpful to have completed some of the other "How to" examples as we will be creating and using objects that were covered in previous sections (Connector and Generic Item).

We will first create 3 new objects under a Connector object: a Generic Item, a Holder Item and an Action Item
Right click on the Connector object and using the Context menu select Admin → Data Processing → New → Generic Item. Name the Item GenericItem1 and go through the Create Item wizard, setting the generation type to Numeric Value Generator and Function to Sawtooth values as was described in the "Create an Object Simulating Data" section. Leave all other settings as default.
Check that GenericItem1 is visible in the I/O Model tree with a green light and is generating values visible in the Faceplate of the object properties panel.
Next Create a Data Holder Item through the context menu as described above except this time select Admin → New → Data Processing → Data Holder Item.

Figure 1. New Data Holder Item

In the Create Item wizard set the Data Holder name to HolderItem1 and the Archive options Value Storage Strategy to Raw History.

Data Holder items can be used to store real-time data and are useful as the display and storage point for calculated values or values generated by other data sources. Its value can be set by internal or external sources. A Holder Item will display a red light in the I/O Model tree until it has a value to display.

Next Create a Action Item through the context menu as described above, except this time select Admin → New → Data Processing → Action Item.

Figure 2. New Action Item

In the Create Item wizard enter the name as ActionItem1 and leave the other options as default. Click Create and then all three created Items should be visible in the I/O Model tree.

Figure 3. Created Items in the I/O Model Tree

The created HolderItem1 displays a red light in the I/O Model tree as it has not yet received any data. The Action Item is able to execute Lua scripts to calculate and process input data. We will input our data by first creating references to other data sources. This is easily done through dragging and dropping the referenced items to ActionItem1 in the I/O Model tree.

The first reference will be the GenericItem1 that we just created. Drag and drop GenericItem1 onto ActionItem1

Figure 4. Drag and Drop of Generic Item onto Action Item

This opens the Set Object Reference dialogue where the reference can be named and the reference set as a Triggering Link. A Triggering Link will cause the Lua script embedded in the Action Item to execute whenever the value of the referenced item changes

Figure 5. Set Object Reference Dialogue

We will leave the Reference Name as the default Ref1. Click Ok to set the reference
Now we will create a second reference from an OPC DA data item (see previous "How To Connect to an OPC Classic Data Source" ) to our ActionItem1. Expand the OPC DA data source to show the available data items an choose a static Integer data item (or a Bucket Brigade Item if using the Matrikon OPC Server).
Set this value to whatever number you like by double clicking on the Faceplate and writing a value.
Drag and Drop the chosen item onto ActionItem1.

Figure 6. Drag and Drop of I/O Data Item onto Action Item

Another Set Object Reference dialogue opens for this Reference. Leave the reference name as Ref2 and the Triggering Link checkbox selected, then click Ok to set the reference.

Figure 7. Set Object Reference Dialogue for Second Reference

Select ActionItem1 in the I/O Model panel then click on the Object references tab in the Object Properties Panel to view the references, including Item Paths, in the table.

Figure 8. Object References Tab in Properties Panel of Action Item

Click on the properties tab in the ActionItem1 object properties panel and click on the "…" button to enter a new Lua Script Body

Figure 9. Lua Script Body Selection- Object Properties Panel

In the open Lua Script Editor, enter the following script, changing the Core object name in the path to match your system:

function f()
  local var1 = get("Ref1")
  local var2 = get("Ref2")
  local var3 = var1 + var2
  syslib.setvalue("/System/INMWS011/HolderItem1", var3)
  return var3
end

return f

Figure 10. Lua Script Entered into Script Editor

The script defines a function f() that uses the "get" command to retrieve values from the previously defined references "Ref1" and "Ref2". Assigning the referenced values to two different variables (var1 and var2), the addition of the two is then assigned to var3. Using the "set" command we can set the the result of the calculation to our Data Holder Item, HolderItem1 and the Faceplate of ActionItem1. The script then returns the value of function f.
Click Ok to apply the script to ActionItem1.
The script is triggered every time there is a value change in either of the two referred items. As one of the items was a static integer, the script is triggered only when GenericItem1 generates a new value (every 1000 ms).
The ActionItem1 and HolderItem1 should now display green lights in the I/O Model Panel after successful script execution. The returned value of the calculation should be also updating in the Faceplate of the HolderItem1 Object Properties panel.

Figure 11. I/O Model Panel and HolderItem1 Object Properties Panel after Script Execution

This simple example demonstrates how to perform calculations on Realtime data from different sources and then write the calculated values to a new location. The Lua scripting engine allows for much more complicated operations to be performed and some of these operations are covered in more detail in the system documentation and in the Lua scripting Jump Start document.