Page Comparison

...

• 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, start the XLogic Editor using the corresponding icon in the toolbar. Then select the entry "New Command ...'' from the menu "File''. A new dialog opens that is used to define the name of the command as well as its inputs, outputs, and parameters.

Within this dialog, set the name to "LIMIT ITEM VALUE'' and define the following inputs:

• Input data point: this is the item ID that specifies the input that shall be monitored.

Then, define following outputs:

• Output data point: this is the item ID that specifies the output where the result can be written on.

Finally, define the following parameters:

...

click on the "Edit Script" button.

Image Added

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

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
• Parameter_maxmaxValue: defines the maximum value of the range for the input item
• Parameter_email: defines the e mail address where item values outside the boundaries are reported.

Image Removed

Command flow

The next step to define the command is to add different blocks to define the command flow. In this example the structure can be grouped into three different steps that have to be taken to fulfill all the requirements of the task. First the input value has to be validated, if the numeric input value is "GOOD''. This means that the input item was assigned with a valid item value. The second step is to check, if the specified value is inside a defined value range. The third and last step is the output of the item value. The value can be written on a specified output item or the messages concerning non valid values outside the numeric range can be sent to a email address.

To validate the input three "IF THEN ELSE'' blocks need to be added to the command window and connect them as illustrated in the figure below. Three "IF THEN ELSE'' blocks in combination three "CMD'' blocks are finally used to check and write the output to the defined server item or to write a message to an e-mail address. Please connect the individual blocks as illustrated in the figure below. In the following section the individual blocks and their purpose will be described in detail. All remaining connectors that do not have a link to another block have to be connected to the "CMD END'' block. After the configuration the links of the connectors can be checked over the "Compile'' button.

Image Removed

Check if input value is good

In the first step it has to be checked if the input was assigned with a valid value. For this purpose the first "IF THEN ELSE'' block will be used. For documentation purposes it is possible to add a comment to the block. Via double click on the field "<comment>'' a message box opens, where a comment can be inserted (e.g. Input value good). Via double click on the "<empty>'' field of the "IF THEN ELSE'' block, a new window for the definition of the condition opens. A "Input Item ID'' block and a "IS GOOD'' block have to be inserted to this window. The "ID'' connector of the "Input Item ID'' block has to be connected to the "Item ID'' connector of the "IS GOOD'' block. The  "Output'' connector of the "IS GOOD'' block has to be connected to the "Result'' connector of the "End'' block. Via double click on the "Input Item ID'' block the input "Input_Item_1'' has to be chosen from the drop-down menu. The final condition is illustrated in the figure below. The window can now be closed.

Image Removed

Check the value range

The check for validating the value range is done in two steps. First the lower limit is checked and afterwards the upper limit. Click on the "<comment>'' field of the second "IF THEN ELSE'' block and add a comment (e.g. value greater min). Double click on the "<empty>'' field of the "IF THEN ELSE'' block. In the opened window a "INPUT ITEM VALUE'', "PARAMETER VALUE'' and a "GREATER OR EQUAL'' block have to be added. The "Output'' connector of the "INPUT ITEM VALUE'' block has to be connected to the "Input 1'' connector of the "GREATER OR EQUAL'' block. The "Output'' connector of the "PARAMETER VALUE'' block has to be connected to the "Input 2'' connector of the "GREATER OR EQUAL'' block. Double click on the "INPUT ITEM VALUE'' block and select "Input_Item_1''. Then double click on the "PARAMETER VALUE'' block and select "Parameter_min''. Finally connect the "Output'' connector of the "GREATER OR EQUAL'' block with the "Result'' connector of the "End'' block. Now the input value is checked for the lower limit as illustrated in the figure below. The next step is to check the input value for the upper limit. The window can now be closed.

Image Removed

In the second step the input value has to be checked if it is below the maximum value of the range. Click on the "<comment>'' field of the third "IF THEN ELSE'' block and add a comment (e.g. value lower max). Double click on the "<empty>'' field of the "IF THEN ELSE'' block. In the opened window a "INPUT ITEM VALUE'', a "PARAMETER VALUE'' and a "LESS OR EQUAL'' block have to be added. The "Output'' connector of the "INPUT ITEM VALUE'' block has to be connected to the "Input 1'' connector of the "LESS OR EQUAL'' block. The "Output'' connector of the "PARAMETER VALUE'' block has to be connected to the "Input 2'' connector of the "LESS OR EQUAL'' block. Double click on the "INPUT ITEM VALUE'' block and select "Input_Item_1''. Then double click on the "PARAMETER VALUE'' block and select "Parameter_max''. Finally connect the "Output'' connector of the "LESS OR EQUAL'' block with the "Result'' connector of the "End'' block. After this step the condition should look like in figure \ref{fig:limit_condition_max}. The window can now be closed.

Image Removed

Check if output is set

To write the input item on a server item, it has to be checked if the output item parameter is not optional before the value can be written on the item. For this purpose the fourth "IF THEN ELSE'' block has to be used. Click on the "<comment>'' field of the "IF THEN ELSE'' block and add a comment (e.g. Output item set). Via double click on the "<empty>'' field of the "IF THEN ELSE'' block a window opens to define a new condition. Drag an "ARGUMENT EXISTS'' block into the new window and connect the "EXISTS'' connector with the "Result'' connector of the "End'' block. Double click on the "ARGUMENT EXISTS'' block and select the "Output_Item_1'' from the drop-down menu. The window can now be closed.

Image Removed

Writing the output

After the parameter was checked if it is set and is not optional, the current value can be written to the defined output item. For this purpose the "CMD'' block after the fourth "IF THEN ELSE'' block has to be used. Click on the "<comment>'' field of the "CMD'' block and add a comment (e.g. Write input to output value). Double click on the "<empty>'' field of the "CMD'' block to open the window to define the new condition. Drag a "INPUT ITEM VALUE'' and a "WRITE OUTPUT VALUE'' block to the window and connect the "VALUE'' connectors of both blocks with each other. Double click on the "INPUT ITEM VALUE'' block and select "Input_Item_1''. Additionally click on the "WRITE OUTPUT VALUE'' block and select "Output_Item_1''. Now the value can be written to the output if it is inside the defined value range.  The window can now be closed.

Image Removed

Check if email address is set

As next, it has to be checked whether an email address was set by the user. The two remaining "IF THEN ELSE'' blocks are used to define one for the upper and one for the lower limit. Click on the "<comment>'' field of the "IF THEN ELSE'' block and add a comment (e.g. Email address set). Double click on the "<empty>'' field of the "IF THEN ELSE'' block to open the windows to define new conditions. Add in both windows an "ARGUMENT EXISTS'' block and connect the "EXISTS'' connector with the "Result'' connector of the "End'' block. Double click on the "ARGUMENT EXISTS'' block and select "Parameter_email'' from the drop-down menu. The window can now be closed.

Image Removed

Send email to configured address

Image Removed

For this purpose the two remaining "CMD'' blocks are used to send a message to the defined email address. Click on the "<comment>'' field of the "CMD'' blocks and add a comment ("Value above max'' and "Value under min''). Double click on the "<empty>'' fields of the "CMD'' blocks and add a "PARAMETER VALUE'' block, two "STRING'' blocks and a "SEND EMAIL TO'' block to the upcoming window. Connect the

"Value'' connector of the "PARAMETER VALUE'' blocks with the "Address'' connector of the "SEND EMAIL TO'' blocks. Double click on the "PARAMETER VALUE'' block and select the "Parameter_email'' from the drop-down menu. Connect now the two "STRING'' blocks to the "Subject'' and "Body'' connectors or the "SEND EMAIL TO'' block. Enter meaningful strings to the two "STRING'' blocks of each window (e.g "Value out of range'', "The input value is too high/low''). To send emails the corresponding settings have to be added to the system configuration of the NETx BMSServer. The configuration of the email system is also described in the documentation of the NETx BMS Server.

Saving the command and using the command within the NETx BMS Server

Image Removed

To provide the command to the NETx BMS Server, it has to be compiled. This can be done by clicking the "Save'' icon within the toolbar which saves and compiles the current command. In addition, it is possible to change several options of a command. To open the "Options'' dialog, the entry "Options ...'' within the menu "File'' has to be selected. Within this dialog, basic information about the command can be specified. The flag "Add to Catalog'' defines whether the command shall be visible within the catalog of the XLogic Editor. If activated, the command can be reused in other commands. If the option "Auto-Compile'' is set, the command is automatically compiled whenever the project is saved.

Image Removed

After having compiled the command successfully, close the XLogic Editor and go back to the \productbmsstudio. Afterwards, the new command has to be loaded before it can be used. This can be done by restarting the NETx BMS Server or by loading the command manually by selecting the entry "Load logic module'' within the "Tools'' menu of the NETx BMS Studio. Then, open the "XCommand event definitions'' via the menu "Extensions''. Add a new definition and enter a name for the command within the first column. The next column can be left empty since all variables shall only be used locally. Within the third column, select "ON_INPUT''. This indicates that the command shall be invoked whenever one of the inputs changes. Then, press the "...'' button within the "XCommand'' column. A dialog appears where the command can be selected and configured. Select the "LIMIT ITEM VALUE'' command from the drop down list. Afterwards, specify the different inputs, outputs, and parameters. A possible configuration is shown in the figure above.

After having saved the "XCommand definition'', restart the NETx BMS Server and test the command.

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.

Image Added

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.

Image Added

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).

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.

Image Added

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.

Related articles

...