LUA2: Limit Item Value

Owned by Wolfgang Granzer
Last updated: Aug 31, 2016

This example shows the functionality of an item value which is limited to a minimum and maximum boundary. The minimum and maximum value can be defined by the user. Additionally it is possible to define an email address where the user is notified when the input value is outside the upper or lower boundary. The value can also be written to an output item, when the value is inside the defined value range.

The functionality of the example is based on the idea to limit the output for a specific server item. The user has to specify the minimum and maximum value which defines the range in which the input values are accepted. The definition of the example provides additionally two optional parameter. First an output item can be defined, where correct values are forwarded too. Second it is possible to specify an email address, to inform the user about values of the item which are outside the defined range. In the following section the example is solved in a step by step tutorial and every single step is described in detail.

To use this tutorial, please do the following steps in advance:

  • Install the NETx BMS Server. The setup can be found here at our website.
  • Create a new BMS server workspace and integrate some data points that you want to monitor.

Creating a new LUA function

First, we will create a new LUA function which verify the item value and sends an e mail if it is out of limit. Within the toolbar of the NETx BMS Studio, click on the "Edit Script" button.

Afterwards, you can select the LUA file that you want to manipulate. Select "nxaDefinitions.lua" to open the main LUA file.

LUA code can be split into different files to organize it. The "nxaDefinitions.lua" is the main file which is loaded by the NETx BMS Server automatically. All other LUA files must be imported by using the "Require" statement at the beginning of "nxaDefinitions.lua".

Then start to implement a new LUA function called "LimitValue". You can implement it at any location outside other functions. Paste in the following code:

function LimitValue(minValue, maxValue, email)

	local currentValue = nxa.SourceValue()

	if (currentValue ~= nil and currentValue >= minValue and currentValue <= maxValue)
   	then
		nxa.WriteDestinationValue(currentValue)
    else
		if (email ~= nil)
		then
			xcon.SendEmailTo(email, "Value out of range", "The input value with ID " .. nxa.SourceItemID() .. " is out of range")
		end
	end
end

The function takes the following parameters:

  • minValue: defines the minimum value of the range for the input item
  • maxValue: defines the maximum value of the range for the input item
  • email: defines the e mail address where item values outside the boundaries are reported.

First, current value which triggers the LUA function is stored within the local variable currentValue. To achieve this, the built-in function nxa.SourceValue() is used. Afterwards, the value is evaluated. First, it is verified whether it is not nil. nil means that there is no valid value – this is the case when the Item Quality is not GOOD (e.g. the device that provides the item is offline). Then, the value is compared to the minimum and maximum limits that are provided as function parameter. If the condition evaluates to true, the current value is forwarded to the destination item. This is done using the built-in function nxa.WriteDestinationValue(value) which writes the value that is provided as parameter 1 to the item which is defined within the task.

If the condition evaluates to false, an e mail shall be sent if an e mail address is specified. First, it is verify whether an e mail is specified i.e. whether it is not nil. To send an e mail, the LUA function xcon.SendEmailTo(email, subject, body, attachment(optional)) is used. The first parameter is the e mail address. In our example, it is provided by the third parameter of the LUA function LimitValue. The second parameter is the subject of the e mail, the third the body, and the forth is an optional file as attachment. The subject and body are strings. As body, LUA string concatenation using .. is used in order to include the Item ID that triggers the tasks using nxa.SourceItemID().

After having finished the LUA implementation, save LUA function and restart the LUA engine using the buttons within the toolbar of the LUA script editor.

Configuring the e mail system

In order to send an e mail, the connection to an SMTP e mail server has to be configured. This is done within the System Parameter within the Server menu of the NETx BMS Studio. At the bottom of the configuration file, the SMTP host (IP address), SMTP port number and the authentication information (TLS, user name , password) have to entered. The following screenshot shows the configuration of the gmail SMTP server.

Create a task definition to use the LUA function

What is still missing the usage of the LUA function. In order to trigger a LUA function whenever a data point changes its value, a Task can be used. To define a Task, open the "Task Definitions" within the "Extensions" menu of the NETx BMS Studio and create a definition. The column "Source Item ID" specified the item which shall trigger the LUA function. This means whenever the value of the item that is specified here is written, the task is trigger. The value of this item can be retrieved within LUA using the function nxa.SourceValue() – the item ID with the function nxa.SourceItemID(). The next column specified an optional destination item. The selected Item can be accessed within LUA using nxa.WriteDestinationValue(value) and nxa.DestinationItemID(). The next three columns are used to define when the task shall be trigger:

  • On receive: the task is triggered when a value is received from the field bus (e.g. from KNX or BACnet).
  • On sent: the task is triggered when a value is sent to the field bus (e.g. to KNX or BACnet)
  • On set: the task is triggered when the value is updated by the server (e.g. due to setting a value within the visualization or by receiving a value from the field bus).

Normally, all three columns are set to "T" (true) since a task shall always be triggered when a value is changed. Setting one of them to false is only used in special use cases.

The next column can be used to specify an optional delay. The column "Command" defines the action that shall be triggered by the task. To execute a LUA function "SCRIPT" has to be used. The last column "Parameter" finally defines the LUA function that shall be invoked when "SCRIPT" is used as command type. Here, the LUA function including the parameters have to be entered. In following screenshot shows how our LUA function LimitValue can be used to monitor the item NETx\VAR\Numeric\Item1. As destination item, NETx\VAR\Numeric\Item2 is used. 50 is used as lower limit and 100 as upper limit. The e mail address that shall be used is defined as third parameter. The second definition shows how the function can be used without using the e mail functionality.

After having defined the your task, save the definition. Since the Task Definitions are live ones, they are automatically reloaded – a server restart is not necessary. Now test the new tasks. For the given example, set NETx\VAR\Numeric\Item1 to 70. Since it is between 50 and 100, the value 70 is also written to NETx\VAR\Numeric\Item2. If NETx\VAR\Numeric\Item1 is set to 40, an e mail is sent since the value is below the specified limit.