- Mathematical operations on data
- Execute simple calculation, e.g. add two input to create a new value
- Execute advanced calculation, e.g. run a matrix calculation for equipment analytics
- Configurational operations on system:inmation
- Create/Update/Delete objects in all system:inmation model trees
This document applies to the SCI of system:inmation version 1.8.0 Although it is likely that a lot of its content will be applicable for future versions too, check for an updated version of this document should you use a higher version of the SCI.
Figure 1:A GenericItem Running a Lua Script
Figure 2:A GenericFolder Holding a Script Library
- I/O Model
- GenericItem This object type is used to generate data on a periodical basis. It can generate data in various ways, including a Lua script execution.
- ActionItems This object type is used to execute a script on an event trigger. Various triggers can be defined. The most common one being another object changing its value.
- Rule The Rule object type can be used during automatic object discovery to make changes to the discovered object while it is being created in system:inmation. One action type of a rule is the execution of a Lua script.
- I/O Model
- System The tree's top level object. Libraries setup here are available to all objects in the whole system
- Core Libraries setup here are available to all objects below the particular Core object
- Connector Libraries setup here are available to all objects below the particular Connector object
- Datasource Libraries setup here are available to all objects below the particular Datasource object
- I/O Node Libraries setup here are available to all objects below the particular I/O Node object
- Folder Libraries setup here are available to all objects below the particular Folder object
- Luasql (interface to access DBMS)
- More details here
- Lpeg (text data matching)
- More details here
- LuaSocket (socket communication)
- More details here
Figure 3:Create New Folder
Figure 4:Create Folder Wizard Step 1
Figure 5:Lua Jump Start Object Hierarchy
Figure 6:Create New GenericItem
Figure 7:Saw Tooth Common Step
Figure 8:Saw Tooth Generation Type Step
Figure 9:Saw Tooth Archive Options Step
Figure 10:Sinus Common Step
Figure 11:Sinus Generation Type Step
Figure 12:Sinus Archive Options Step
Figure 13:Simulation Items
Figure 14:Create Periodical Calculation
-- get the values of the two simulation itemslocal sin = inmation.getvalue("/System/INMWS011/Examples/Lua/Jump Start/Sinus")local saw = inmation.getvalue("/System/INMWS011/Examples/Lua/Jump Start/Saw Tooth")-- return the sum of the valuesreturn sin + saw
Figure 15:Calculation Code
Figure 16:LuaSense Coding Help
Figure 17:Simple Calc Archive Options Step
Figure 18:Simple Calc Working
Figure 19:Show Watch Items
Figure 20:Watch Items
Figure 21:Watch Items Edited
Figure 22:Update Script Object
Figure 23:Syntax Error in Script
Figure 24:Dedicated Thread Execution
This example configures a set of demo objects that generate simulated process data and (by default) a year of history. The demo is mainly intended to enable you to start working with DataStudio's display types, but it also contains some basic calculations that are explained in the next chapter.
To configure the demo data, first download the Examples_DemoData.xlsx Mass Config file that matches your system:inmation version from the inmation resources page and then follow these steps:
- Start DataStudio and login with administrative rights
Open a new Mass Config display (Menu Open ; Mass Config Sheet, or use the Ctrl+M shortcut). Click the Import Display Content icon in the menu bar.
Figure 25:Icon Menu Import
- Select the downloaded Examples_DemoData.xlsxfile from the Open File dialog and click Ok to load it into the display.
Figure 26:Mass Config of DemoData
- The provided configuration uses Core as name of the Core. This may be different in your environment (default object name of the Core is the name of the machine hosting it), and should be changed to match your system.
Figure 27:Replace Dialogue
- Click Replace All; you should see 27 replacements
Figure 28:Replacement Message
- In the Mass Config display click Simulate to test if the content can be applied to your system now.
Figure 29:Simulate Changes
- You should see 24 successes (this could be less if you already created some of the folders in a previous example).
Figure 30:Simulate Result
- Click Apply to accept the changes. The demo data objects should exist now in the I/O model tree
Figure 31:DemoData Objects
This example configures a set of demo objects that will illustrate how to access a http server outside of system inmation to retrieve data (here freely available information about US airports). This example also shows how Lua scripts can dynamically create objects in the tree hierarchy in addition to dealing with their values.
Figure 32:Lua HTTP Access Objects
This example configures a set of demo objects that illustrate how to access an ODBC data source.
To configure this example first create the SQL environment following these steps:
- Make sure you have first configured the DemoData example shown above.
- Create the sample sql database by either restoring the InmationDataDemo.bak or running the InmationDataDemo.sql provided with this document at a SQL Server instance of your choice (see note below for details of setting up an example SQL server).
- Create a System DSN called InmationDataDemo pointing to the InmationDemoData SQL database (can be found in Administrative tools in the control panel). Double click on ODBC Data Source Administrator (32/64bit, depending on your environment), select the System DSN tab and click Add. Choose an appropriate driver (depending on the SQL Server you are using - ODBC Driver 11 for SQL Server works for MS SQL Express)
- Give the System DSN a name in the dialog and connect it to the SQL Server you are using (it may not appear automatically in the drop-down menu). If using MS SQL Express this will be <hostname>\SQLEXPRESS
- Set up the SQL server authentication using same authentication details as during the SQL server set up (see note below for details of setting up an example SQL server) and click Next.
- Change the default database to InmationDataDemo, click Next and then Finish. Test Data source and then click OK until all dialog windows are closed.
To restore the InmationDataDemo.bak database, open the management studio and right-click on Databases in the left hand panel and select Restore Database. Select Source > Device > "…" and click Add to browse to the .bak file.
Figure 33:Sample SQL Database
The objects needed for the Lua ODBC example are included as part of the Examples_LuaODBC.xlsx Mass Config file used to configure the Lua HTTP Access example. Download the Examples_LuaHttp.xlsx file from the inmation resources page if you haven't already, and open it in the Mass Config display.
After the import and the first run of the DataProcessing scripts included in the import, the I/O model tree should look like this:
Figure 34:Lua ODBC Access Objects
Figure 35:Simulated Density
Figure 36:Generating Sample Data
Figure 37:Folder with Script Libraries
Figure 38:Simple Math Library
Figure 40:Average Quality Check Script
- It is of the type ActionItem, meaning it is executed on an event based trigger, not periodically.
- It uses one passive object references (DI_Out), that is used to simplify the script code (highlighted by the yellow boxes).
- It uses two triggering object references, both causing the script to run whenever they change value, quality, timestamp or any property (highlighted by the orange boxes).
The ProcessData GenItems in the DemoData example generate random values using the GetNextRandomValue function from the SampleHelpers script library in the Examples folder. We use this function again, alongside the inmation.sethistory function to create a year's worth of historical data for the ProcessData items. With this historical data you can start to use the HistoryGrid and HistoryTrend displays in DataStudio.
The CreateHistory ActionItem that runs the Lua script to create the historical data can be found in the Logic Folder in the DemoData Node.
Figure 41:Logic Folder - Create History
Select the CreateHistory ActionItem and open the embedded Lua script.
Figure 42:Create History Script
The script sets the time to start the history. In this case it is a year prior to the current time in milliseconds (variable old, line 6) and the variable step sets the time inteval between each written history data point to 1 min or 60000 ms(line 8).
The for loop on line 17 calls the get_children_paths function in the SampleHelpers library to cycle through each simulation item in the ProcessData folder.
The History values are then set by stepping through each time point from old to now with a time inteval of 1 min between points(line 22). The first value is calculated from the limit values of the ProcessData item (line 21), then new random values are calauted from the last set value by again using the GetNextRandomValueFunction in the SampleHelpers library (line 24).
The script then disables the CreateHistory item to prevent accidental re-execution of the script.
Open a HistoryTrend display for one of the items and select Entire Data to see that the History was set for time period has been set.
Figure 43:HistoryTrend for ProcessData Item
The DemoData example creates a set of simulation items in the I/O model including items that make calculations when new data is produced. So far, all the items described (including Lua scripts and script libraries) were created in the I/O model using the MassConfig display. For the KPI model the items are instead created using Lua scripting.
Select the CreateKPIModel ActionItem in the I/O Model tree (it is in the same Logic folder as the CreateHistory item) and open the Lua script body by clicking on "…" in the object properties panel.
Figure 44:CreateKPIModel ActionItem
The first part of the script embeds the inmation.KpiHelpers library in the script using the require call. The KpiHelpers library is held as a script library in the Examples folder like the Sample.Helpers library described in an earler section.
The paths to the folders in the I/O tree hierarchy are then set using the inmation.gethpath(), getparentpath and getobject commands. Because the script is being executed by the CreateKPIModel object then the paths to these folders are all relative to to its position in the tree.
Figure 45:CreateKPIModel Lua Script - Part 1
The first objects are created in the KPI model, starting with the top-level Enterprise object (More information about KPI Model objects is available here).
The call of the children function on the ProcessData folder object returns all its children as Lua table.
The KPI objects are created using the createGroup function in the KpiHelpers script library that takes object name, class and parent path as arguments. The function first checks if the object already exists before creating the object.
Figure 46:KPIHelpers Script Library
The second part of the CreateKPIModel script cycles through the returned table of ProcessData items and creates GenKPI items in the KPI Model accordingly. The ProcessData simulation items belong to either Reactor 4711 or Reactor 666 and we create "Plant" objects in the KPI model (lines 23 and 25) to order the KPI items in terms of location.
Under each reactor the KPIs are arranged into either "Measurements" or "LabData" dependent on the object name being a Density(D), Pressure(P), Flow(F), Quality(Q) or Temperature(T) measurement (using the Lua string.sub function, the first letter of the object name object name is identified). The "Measurements" and "LabData" folders are created followed by the GenKPIs which are linked to the appropriate simulation item in the I/O Model.
Functions in the KpiHelpers script library are used to create the objects and set the properties.
Figure 47:CreateKPIModel Lua Script - Part 2
After executing the script, the CreateKPIModel object disables itself to prevent accidental re-execution. View the KPI Model to see the created objects and KPI structure.
Figure 48:KPI Model
- calling an external HTTP web service for data
- parsing the returned XML string
- creating objects in the I/O model tree based on the returned data
- updating existing objects value based on the returned data
Figure 49:Lua HTTP Request
Figure 50:Open Source XML Parser Function
Figure 51:Parsing XML
Figure 52:Creating Model Objects
Figure 53:I/O Model Tree after JSON example MassConfig
Figure 54:JSON Processor Script - defining the JSON string
Figure 55:JSON Processing Script – creating and setting values of objects
- Reading from a database
- Writing to a database
Figure 56:ODBC Read Example
Figure 57:Result of Read as current value
Figure 58:Select From Database
Figure 59:Find Objects in the Model Tree
Figure 60:Preparing Insert Statement
Figure 61:Execute Inserts
Figure 62:Written values in SQL database