LUA scripting

Whenever control functionality cannot be added by using the mechanisms mentioned before (e.g. Task definitions), the scripting engine of the NETx BMS Core Server can be used. This scripting engine provides the opportunity to execute LUA scripts that implement the required control functionality.

Using LUA scripts, the user has full access to the functionality of the server – nearly any control functionality can be implemented this way. Moreover, most of the provided functionality can also be changed during runtime and so LUA scripts provides one of the most flexible way to extend the functionality of the NETx BMS Core Server system.
LUA itself is an open source scripting language. There are two main reasons why LUA was chosen as scripting language. First, LUA is very fast and so LUA scripts scale to large systems which is of utmost importance in the building automation domain – LUA scripts can handle thousands of data points. Second, due to the simple syntax of LUA, LUA scripting can easily be learned – even for beginners it is easy to write their own LUA scripts.

However, as it is common for each programming language, some basic training is necessary to write LUA scripts. For the general syntax of the LUA scripting language please refer to www.lua.org. Here, tutorials and how-to's that can be used as a good starting point for beginners can be found.
LUA scripts are stored in normal text files that use the extension ".lua". Within the NETx BMS Core Server, all LUA scripts have to be stored within the script directory of the current workspace:

<WorkspaceDirectory>\ScriptFiles\

While it is possible to write LUA scripts in any file within this directory, the following script is the default LUA script that is loaded by the server at start up:
<WorkspaceDirectory>\ScriptFiles\nxaDefinitions.lua

To avoid that each user must start from scratch when he or she wants to implement some control functionality with LUA scripts, the so called NXA LUA library is already integrated within the NETx BMS Core Server. Using the included functions and event callbacks, the user can access the internal functionality of the server. For example, using appropriate LUA functions, Server Items and Task definitions can manipulated even during runtime. In general, the following LUA functionality is provided by the NXA LUA library:

• Standard functions: These functions can be used at anytime during runtime. Typical examples are functions that change the value of Server Items or functions that can be invoked to retrieve the current workspace name.
• Task handling: These functions are used in combination with tasks.
• NXA functions for KNX In Out Conversion: These functions are used for KNX items, which needs to be converted or only certain bits are used.
• NXA functions for creating custom Server Items: These functions can be used to define user-specific custom items and hierarchies within the Server Item Tree.
• NXA event callbacks: In addition, the NXA library also provides event callbacks that invoked by the server at a specific point in time. A typical example is the "OnInitEvent" callback that is invoked during server start up.
• NXA constants: Furthermore, some constants are also defined in the library that assist the user in programming the required functionality.

In the remainder of this section, these different functions, callbacks, and constants are explained in more detail.