Getting Started

Create Simulation Items

In these examples, we will use the DemoData set of simulated process values used in the Lua Scripting Jump Start to demonstrate the in-memory aggregation capabilities. To create these simulated data items in the I/O Model tree use the MassConfig display to import the Examples_DemoData.xlsx file (MassConfig file containing DemoData Items can be found here, be sure to use the version which matches with your version of system:inmation). Match the paths of the simulation Items to your system’s I/O Model structure then click Simulate to verify the paths and Apply to create the items in the I/O Model tree. The tree should look like this:

Created Simulation Items - I/O Model Tree
Figure 1. Created Simulation Items - I/O Model Tree

Buffer functionality in Lua

system:inmation supports in-memory aggregation by buffering real-time values in memory temporarily. Buffers are attached to objects producing time-series data and hold a configurable number of values for a configurable length of time. The general principle of the buffer is that it fills up with values over time then when it reaches capacity, the addition of a new value causes the oldest value in the buffer to be purged. In system:inmation we can create a buffer on an object using the syslib.buffer() Lua function from the inmation Lua library. The syslib.buffer Lua function creates a buffer attached to the object that is producing the values that you wish to aggregate. The function has various configurable arguments, some of which are optional depending on what you want to achieve.

syslib.buffer(object_or_path, “buffer name”, input, duration, size)

In many cases the first step is to create a buffer that will store all the raw values from an item over a defined period of time. So, for example if we wish to calculate the average value every minute for an item that updates every second we would at least need to create a buffer that can contain 60 values and has a duration of 1 minute. For this the buffer function requires the object (or path) supplying the data values, a name for the buffer (entered as a string), the input (relative path to the dynamic property of the object that supplies the values), the duration of the buffer (in ms) and the size (total number of values the buffer can store).

Creating a Buffer

We will create a buffer on the simulated flow item FC4711 in the DemoData set as an example of this:

  1. First create an ActionItem underneath the Core by selecting the Core Object, right clicking and selecting Admin → New → DataProcessing → ActionItem.

  2. In the Create Object wizard, name the object Buffer and in the Lua script body enter the following code:

    local obj = syslib.getobject("/System/CORE/Examples/DemoData/ProcessData/FC4711")
syslib.buffer(obj, "buff", ".ItemValue", 60000, 60)

  3. Click Ok to confirm the Lua script then Create to create the ActionItem in the I/O Model

In this example, we first use the syslib.getobject function to assign the source FC4711 item to the variable obj. The syslib.buffer function is called on the second line with the following arguments:

  • ‘obj’ is defined as the FC4711 I/O item (from the syslib.getobject call on first line)

  • The buffer is assigned the name “buff”

  • The input is the real-time values from FC4711: we use the relative path to the dynamic property “.ItemValue”

  • Duration is set to 60000 milliseconds as we wish to buffer 1 minute of data

  • Buffer size set to 60 as the FC4711 item produces a new value every second, hence 60 values in 1 minute

Once the ActionItem is created, the Lua script is executed, the buffer is created on the specified object and starts to be populated with values…​ How can we now view the items in the buffer then

Retrieving Buffer Contents

The buffer is now created in-memory and is receiving new values. However, how do we now retrieve those values or check that our buffer has been configured correctly? Once a buffer is created on an item we can view the contents using either the syslib.peek or the syslib.tear function:

  1. syslib.peek(object_or_path, "buffer name")

    Retrieves the contents of the specified buffer (on the specified object) and returns four values:

    • Array of buffered data values

    • Array of buffered timestamps

    • Array of buffered qualities

    • Count of items in the buffer

  2. syslib.tear(object_or_path, "buffer name")

    Retrieves and clears the contents of the specified buffer (on the specified object) and returns four values:

    • Array of buffered data values

    • Array of buffered timestamps

    • Array of buffered qualities

    • Count of items in the buffer

A script that periodically retrieves the contents of a buffer has to be executed in a separate object to the one that created the buffer. A periodically run script containing the syslib.buffer() function will recreate the buffer again, emptying it of its values, meaning that any peek or tear retrieval function will only retrieve an empty buffer.

  1. First create an GenItem underneath the Core by selecting the Core Object, right clicking and selecting Admin → New → DataProcessing → Generic Item.

  2. In the Create Object wizard, name the object “Buffer Reader” and click Next.

  3. Click Next on the Limits page to go to the Generation Type section of the Wizard

  4. On the Generation Type page, change the generation type to Lua Script Data Generator and in the Lua script body enter the following code:

    local obj = syslib.getobject("/System/CORE/Examples/DemoData/ProcessData/FC4711")
local values, qualities, timestamps, count = syslib.peek(obj, "buff")
return values

  5. Click Ok to confirm the Lua script and return to the Create Object wizard then click Create to create the object in the I/O Model tree.

Select the “Buffer Reader” object in the I/O Model tree and hover the mouse over the faceplate in the Object Properties panel. The values from the buffer will be displayed.

Retrieving Values from Buffer - Buffer Reader
Figure 2. Retrieving Values from Buffer - Buffer Reader

  • Change the return value in the script to the “timestamps” or “qualities” variables, to return an array containing the buffered timestamp and quality values.

  • Change the return value to “count” to return a count of the total number of items that have been loaded into the buffer since the buffer was created.

The buffer fills up until the size parameter is met, then the newest value is buffered and the oldest value is purged from the buffer.

If the buffer reaches the maximum number of elements (specified by the size argument) before the specified time duration of the buffer is reached then the size argument is respected and buffer size will not increase to match the duration (e.g. if a buffer is attached to an item that produces a new value every second but the duration is set to 60,000 ms and the size to 10: the buffer can only hold 10 values before the oldest value is purged, regardless of the buffer duration). The same is also true is the duration argument is met before the specified size is reached. The buffer will only cover the specified duration (e.g. if a buffer is attached to an item that produces a new value every second but the duration is set to 10,000 ms and the size to 20: the buffer will only cover the 10,000 ms duration and therefore can only hold 11 values before the oldest value is purged).