oBIX (Open Building Information eXchange) is a web service standard which is maintained by OASIS. The propose of oBIX is to provide a uniform web service interface for building automation systems and their devices and data points. Using well-defined communication services and data encoding schemes like HTTP and XML, oBIX can be used to provide an easy but flexible interface to management clients that are not aware of the details of underlying communication typically used within the building automation domain. In addition, oBIX is also defined within the new KNX Web Service (KNX WS) specification as one possible protocol binding. More information about oBIX can be found at the official oBIX website.

The NETx BMS Server now provides a new oBIX interface which can be used to map any data point to an oBIX object. This includes all physical data points that are already integrated within the NETx BMS Server (KNX, BACnet, Modbus, SNMP, Opera/Fidelio, ...) as well as virtual data points like virtual and custom server items. The oBIX interface for the NETx BMS Server supports the following features:

• oBIX 1.1 interface supporting HTTP binding and XML encoding
• Security support using TLS 1.2 and basic authentication
• Support for oBIX watches
• Conform to KNX Web Services which provides the possibility to use the NETx BMS Server as a standard conform KNX Web Service gateway

Installation

The interface is implement as a plugin for the NETx BMS Server. Therefore, it has to be installed via the Extension Manager. To do so, open the Extension Manager via the BMS Studio using the menu "Extensions". Select the "oBIX and KNX WS" interface and press install as shown in the following screenshot:

After having installed the interface, restart the NETx BMS Studio.

Configuration

By default, the oBIX interface is deactivated. In order to use, it has to be activated and configured first. Open the driver configuration within the menu "Modules" --> "oBIX" within the NETx BMS Studio. Within the configuration dialog, the following settings can be changed:

• Enable oBIX: this option activated the oBIX interface for the current workspace. Default is false.
• Local TCP Port: here the local TCP port for oBIX communication is defined. This port has to be open within the local firewall. Default is 9000.
• Enable https (TLS): if activated, the oBIX interface is only accessible via https using TLS 1.2. Due to security reasons, it is strongly recommended to use this option. Default is true.
• User name: here the user name for basic authentication can be defined. If specified, the oBIX interface is only accessible after a successful authentication via http authentication. Basic authentication is only possible if https (TLS) is activated. Due to security reasons, it is strongly recommended to enable basic authentication. 
• Password: if a user name is defined, a password has to be specified. Due to security reasons, at least 8 characters have to be specified.
• Certificate CN: if https (TLS) is activated, a common name for the TLS certificate has to be specified. This name is used to find the appropriate TLS certificate within the Windows certificate store. If no certificate is found, the oBIX interface generates a self-signed certificate automatically.
  
  

Using the oBIX interface

After having enabled the oBIX interface, all data points within the following branches of the item trees are available as oBIX objects:

• NETx\XIO
• NETx\Module
• NETx\API
• NETx\Custom
• NETx\Aliases
• NETx\VIRTUAL

As defined by oBIX, the main entry point is the oBIX lobby object with is accessible via the following URL:

http(s)://<IP address BMS server>:<port>/obix

Via the lobby object, all further obix objects are accessible and can be browsed by oBIX clients. It is also possible to add oBIX watches as well as change the values of writable data points via http put requests.

• http(s) GET: the oBIX interface will respond with all oBIX objects including their URLs as XML.

Each data point can be accessed by its URL:

http(s)://<IP address BMS server>:<port>/obix/<Item ID>

Read a data point

Upon http(s) GET to the data point's URL, the oBIX interface will respond with the oBIX object encoded as XML.

Example

• NETx Server's IP address: 172.16.10.10
• oBIX interface TCP port: 9000
• data point of interest: NETx\XIO\BACnet\Demo_Case_Small\Analog_Output_0\Analog_Output_0

Following URL is used to access the data point

http://172.16.10.10:9000/obix/XIO/BACnet/Demo_Case_Small/Analog_Output_0/Analog_Output_0

Using http GET, the oBIX interface will respond with the oBIX object encoded as XML. For the BACnet analog output object, this may look like the following XML fragment:

<real name="Analog_Output_0" val="0" href="http://172.16.10.10:9000/obix/XIO/BACnet/Demo_Case_Small/Analog_Output_0/Analog_Output_0" is="obix:Point" writable="false"/>

Write a data point

To write a data point, issue an http(s) PUT with an XML body containing the new value: the oBIX interface will set the data point value as provided in the XML body and return the updated object.

Example

• NETx Server's IP address: 172.16.10.10
• oBIX interface TCP port: 9000
• data point of interest: NETx\XIO\KNX\Demo_Wall_IP_Router\01/0/004 (BOOL)

Following URL is used to access the data point

http://172.16.10.10:9000/obix/XIO/KNX/Demo_Wall_IP_Router/01/01*0/01*0*004

Issue an http PUT with the following XML code in the body:

<bool val="true" />

The oBIX interface will set the value to true and return the new value in an XML code.

Basically, it is possible to reuse a modified GET response in the PUT request.

Subscribe to changes of a data point

Subscription to changes of a data point is done by the following steps:

1. Create a watch service.

   • Issue a POST request to the following URL to obtain the URL of the watch service

     http(s)://<IP address BMS server>:<port>/obix/watchService/make

   • The returned XML body provides the URL of the watch service in the href attribute. This will be referenced as <watch-url> from here on.
2. Add data points to the watch service.
   • Issue a POST request to <watch-url>/add and provide the data points to watch in the XML body.
3. Poll the watch service for changes.
   • Issue a POST request to <watch-url>/pollChanges.

Example

• NETx Server's IP address: 172.16.10.10
• oBIX interface TCP port: 9000
• data point of interest: NETx\VIRTUAL/TestPath/TestItem (INT16)

To create the watch service, issue a POST request to

http://172.16.10.10:9000/obix/watchService/make

The response body is like

<obj name="watch3" href="http://172.16.10.10:9000/watch3" is="obix:Watch">
    <op name="add" href="watch3/add" in="obix:WatchIn" out="obix:WatchOut"/>
    <op name="remove" href="watch3/remove" in="obix:WatchIn" out="obix:Nil"/>
    <op name="delete" href="watch3/delete"/>
    <op name="pollRefresh" href="watch3/pollRefresh" out="obix:WatchOut"/>
    <op name="pollChanges" href="watch3/pollChanges" out="obix:WatchOut"/>
    <reltime name="lease" val="PT1M" href="watch3/lease" writable="true"/>
</obj>

Next, add the data point to the watch service, by issuing a POST request to the path provided in the add operation:

http://172.16.10.10:9000/watch3/add

with following body:

<obj>
    <list name="hrefs">
        <uri val="VIRTUAL/TestPath/TestItem"/>
    </list>
</obj>

The response body looks like

<obj href="http://172.16.10.10:9000/" is="obix:WatchOut">
    <list name="values">
        <int name="TestItem" val="123" href="TestItem/" is="obix:Point" writable="true"/>
    </list>
</obj>

To poll for changes, issue a POST request to 

http://172.16.10.10:9000/watch6/pollChanges

If no changes are reported, the response body has an empty list tag:

<obj href="http://172.16.10.10:9000/" is="obix:WatchOut">
    <list name="values"/>
</obj>

If changes apply, they are reported as tags inside the list tag:

<obj href="http://172.16.10.10:9000/" is="obix:WatchOut">
    <list name="values">
        <int name="TestItem" val="1234" href="TestItem/" is="obix:Point" writable="true"/>
    </list>
</obj>

Using the NETx Server as a KNX Web Service gateway

Since all data points under the sub tree NETx\XIO are available as oBIX objects, all KNX data points are mapped to oBIX objects, too. However, this mechanism only provides a simple oBIX mapping which is not fully complying with the KNX Web Service standard.

Therefore, the oBIX interface is also providing a second entry point for all KNX data points. This second oBIX tree is complying with the KNX Web Service standard and can be accessed via the following URL:

http(s)://<IP address NETx server>:<port>/installations

Assuming that the NETx Server is hosting a ETS project called "Demo_Case_Small", the following response will be provided by the oBIX interface:

<list name="installations" href="https://<IP address NETx server>:<port>/installations/" of="obix:ref /knx/Installation">
	<ref name="Demo_Case_Small" href="Demo_Case_Small/" is="/knx/Installation"/>
</list>

All further oBIX objects are accessible via the "href" attribute. As defined by the KNX Web Service standard, the appropriate KNX specific oBIX contracts are also accessible. 

Security considerations

If access to the oBIX interface is not limited to a protected internal LAN, it is strongly recommended to activate https (TLS) in combination with basic authentication. Although the oBIX interface is using state-of-art TLS encryption based on TLS 1.2, the overall security can not be guaranteed since it also depends on other factors that are not within the responsibility of the NETx Server. This includes a correct Windows Firewall setting, the use of a strong password, protected access to the Windows PC and other factors that are within the responsibility of the end user.

Article applies to the following products:

• NETx BMS Platform
• NETx Multi Protocol Server
• NETx BMS Server 2.0