Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Basic architecture

The NETx BMS Server provides the possibility to integrate web content from HTTP server.

The HTTP plugin that implements this functionality creates BMS Server Items which represents the web content of interest. The NETx BMS Server acts as HTTP client. HTTP GET requests are used to retrieve content. The retrieved information is parsed and relevant values are stored within Server Items. On the other hand, write request to these Server Items are sent to the HTTP server using HTTP PUT or POST requests. The web requests are encoding as XML for example.

Installation

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

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

Configuration

The configuration is done using the following configuration files and definition tables:

xio.HTTP.ResourceDefinitions.dat

This definition table can be found within the BMS Studion in "HTTP"  -> "Resource definitions". It defines the encoding and the content that is expected at the web server. Each definition contains the following columns:

  • Name (string, mandatory): it is the key that identifies the resource within the data point definitions. The name can freely be chosen but has to be unique.
  • Type (enum, mandatory): type of encoding. Currently, XML is available.
  • Resource (string, mandatory): it defines the content that is excepted at the HTTP server. The structure and type depends on the used encoding and on the direction (polling or update). A detailed description as well as some examples can be found here.

xio.HTTP.DatapointDefinitions.dat

Here the different data points that shall be represented as Server Items are defined. Each definition contains the following columns:

  • Name (string, mandatory): defines the name of the data point. In combination with path, it has to be unique.

  • Path (string, optional, default ""): defines the structure that is used to represent the data points. In combination within name, it must be unique.

  • Data type (enum, optional, default "STRING"): defines the type of the data point. Allowed values are: BOOL,STR,BYTE,CHAR,INT8,UINT8,INT16,UINT16,INT32,UINT32,INT64,UINT64,FLOAT,DOUBLE,DATE,TIME

  • Access mode (enum, optional, default "R"): defines the access rights of the data point. Allowed values are R (read-only), W (write-only), RW (read and writable).

  • Polling Url (string, optional, default ""): here the URL is specified with is used to retrieve the data point values. The BMS Server makes polling using HTTP GET requests to this URL. If empty, polling is not available.

  • Polling interval (ms) (number, optional, default "5000"): here the polling interval in milliseconds is specified.

  • Polling Resource (string, optional, default ""): here the resource that is used for polling is specified. It must match with the name that is used in the xio.HTTP.ResourceDefinitions.

  • Polling Parameters (string, optional, default ""): here a list of parameters that are used to replace the placeholders within the polling resource ({0}, {1}, ...) can be defined. The parameters have to be separated by comma ,

  • Update Url (string, optional, default ""): here the URL is specified with is used to update the data point values. The BMS Server makes HTTP PUT or POST requests to this URL. If empty, updating the values is not possible.

  • Update Method (enum, optional, default "POST"): here the web update request method is specified. Allowed values are "POST" and "PUT".

  • Update Resource (string, optional, default ""): here the resource that is used for updating is specified. It must match with the name that is used in the xio.HTTP.ResourceDefinitions.

  • Update Parameters (string, optional, default ""): here a list of parameters that are used to replace the placeholders within the update resource ({0}, {1}, ...) can be defined. The parameters have to be separated by comma ,

  • Persistent (bool. optional, default "F"): if enabled, the last data point value is restored after BMS server start up.

  • Historical (bool. optional, default "F"): if enabled, all data point changes are stored within the SQL database. 

  • Synchronize (bool. optional, default "T"): if enabled, the value is synchronized with the backup server if used.

xio.HTTP.cfg

In this configuration file, general settings can be defined. It contains the following settings:

  • xio.Http.TimeOut (number, default: 5000): defines the timeout in milliseconds the server waits for an answer to an HTTP request.
  • xio.Http.ValueTag (string, default. "@value@"): placeholder that is used within the resources. 
  • xio.Http.Language (string, default: ""): specifies the country code which is used for data conversion. If empty, invariant culture is used.

Integration steps

One of the most important step is the definition of the HTTP resource that is expected by the BMS Server. The resource depends on the used encoding and on the direction of the data change (polling or update). 

Parameters

Normally, an HTTP server will host multiple data points values. To avoid that a separate HTTP resource has to be specified for each data point, parameters can be used. The HTTP resource is defined in a generic way using placeholders for parameters. These placeholder are replaced by the parameters values defined within the xio.HTTP.DatapointDefinitions.dat.

XML encoding

XML encoding has to be used when the HTTP server provides the information as XML. The resource definition must be as follows:

  • Polling: for getting data point values out of an XML document, an XPath expression has to be specified. This XPath expression is used to select an XML element and its content. More information about XPath can be found here.
  • Updating: for updating a data point value, the XML fragment that is expected by the HTTP server has to be specified. This XML fragment must contain the "ValueTag" (specified within xio.http.cfg, default @value@).

JSON encoding

JSON encoding has to be used when the HTTP server provides the information as JSON. The resource definition must be as follows:

  • Polling: for getting data point values out of a JSON document, a JPath expression has to be specified. This JPath expression is used to select a JPath element and its content. More information about JPath can be found here.
  • Updating: for updating a data point value, the JSON fragment that is expected by the HTTP server has to be specified. This JSON fragment must contain the "ValueTag" (specified within xio.http.cfg, default @value@).

Example

Suppose there is a HTTP server (192.168.0.10) which acts as interface to different devices that provide data point values. The server provides all information as XML via an URL like http://192.168.0.10/data/current.xml. This XML looks as follows.

<devices>
	<device name="controller1">
		<setpoint>25.5</setpoint>
		<input1>12</input1>
		...
	</device>
	<device name="controller2">
		<setpoint>23.5</setpoint>
		<input1>17</input1>
		...
	</device>
	...
</devices>

To get the setpoint of the controllers, the following XPath definition has to be used:

/devices/device[@name="{0}"]/setpoint/text()

This expression with search for <devices> then for a <device> element that has the attribute "name" equal to parameter {0}, afterwards for <setpoint> and finally returns the text which is 25.5 in our example.

The BMS Server resource definition looks as follows:

In addition, suppose that the value can also be changed by sending an HTTP POST request that contains an XML fragment to the URL http://192.168.0.10/data/update.xml. Suppose that the XML fragment must be as follows:

<devices>
	<device name="controller1">
		<setpoint>21</setpoint>
	</device>
</devices>

The corresponding resource definition looks as follows:

The value tag @value@ will be replaced the value that shall be written.

To use these resource definitions to integrate the setpoints of controller1 and controller2, you can use the following datapoint definitions:

As shown here, the "controller1" and "controller" are used as parameters here. This means that the BMS server will replace {0} by "controller1" and "controller2" respectively. For controller 1, this results in the following XPath  expression and XML fragement:

/devices/device[@name="controller1"]/setpoint/text()
<devices>
	<device name="controller1">
		<setpoint>21</setpoint>
	</device>
</devices>

For controller 2:

/devices/device[@name="controller2"]/setpoint/text()
<devices>
	<device name="controller2">
		<setpoint>21</setpoint>
	</device>
</devices>

The item tree of this example looks as follows:

Available resource definitions for already tested servers

EZR

Room controllers from EZR (http://ezr-home.de/) can be connected to a gateway that provides an HTTP server. For retrieving the current temperature and the setpoint, the following ZIP file can be used:

EZR.zip

It contains the resource definition and an example of some data point definitions.

Telegram

Using the HTTP module, the NETx BMS Server is able to send messages to the messaging service Telegram. The following ZIP file contains the necessary configuration data:

Telegram.zip

More information can be found here.

Sending SMS

To send a SMS via the NETx BMS Server, online SMS services can be used. An example of such a service is https://www.cm.com/. The following ZIP file contains the necessary configuration data:

SMS.zip

  • No labels