Page tree
Skip to end of metadata
Go to start of metadata

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

By default, the TCP port for oBIX is not opened within the Windows firewall. Therefore, it is necessary to define an appropriate Windows firewall rule in order to access the oBIX from a remote computer.

Using the oBIX interface

After having enabled the oBIX interface, all data points within the item sub trees NETx\XIO, NETx\VIRTUAL, NETx\Module, NETx\API, NETx\Custom, NETx\Aliases are available as oBIX objects. 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. 

Of course, it is also possible to access a data point via its URL directly. This can be via the following URL:

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

For example, to access the BACnet Object "Analog_Output_0" of a BACnet device called "Demo_Case_Small", the following URL can be used:

https://<IP address BMS server>:<port>/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="https://<IP address BMS server>:<port>/obix/XIO/BACnet/Demo_Case_Small/Analog_Output_0/Analog_Output_0" is="obix:Point" writable="false"/>

If the data point is writable, the value can be changed via http PUT.

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. 

Although there exists an ETS app called "Web service exporter", the NETx Server is not using it for the oBIX interface. All required information is provided by the export of our own "NETx BMS App Secure". Thus, in order to use the NETx Server as web service gateway, the ETS project has to be imported via the "NETx BMS App Secure".

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


  • No labels