| Table of Contents |
|---|
Basic architecture
It is possible to integrate web content from one ore more HTTP(S) servers.
...
The driver is implemented as a plugin. Therefore, it has to be installed via the Extension Manager. To do so, stop the NETx Server and open the Extension Manager via the 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 studio.
...
The configuration is done using the following configuration files and definition tables:
xio.HTTP.ResourceDefinitions.dat
This definition table can be found within the studio in "HTTP" -> "Resource definitions". It defines the encoding and the content that is expected at the web server. Each definition contains the following columns:
...
.
...
A detailed description
...
can be found
...
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.
...
within
...
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 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 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 server start up.
...
Historical (bool. optional, default "F") ( NETx BMS Server 2.0 only): 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.
the reference manual.
Integration steps
| Anchor | ||||
|---|---|---|---|---|
|
...
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@).
URL encoded
URL encoded can be used to send value via URL parameters. URL encoded is only available for updating resources. The resource definition must be as follows:
Polling: Not allowed
Updating: for updating a data point value, an URL parameters string must be provided. It will be appended to the update URL and must have the form: "<parameter1 name>=<parameter1 value>&<parameter2 name>=<parameter2 value>&...". The URL parameter string must contain the "ValueTag" (specified within xio.http.cfg, default @value@). Suppose the update URL is "http://192.168.0.1/cmd/switch.xml" and the URL parameter string within the resource definition is "id=ceiling_light&state=@value@". If the item value "1" is written the HTTP plugin will initiate a GET request with the URL "http://192.168.0.1/cmd/switch.xml?id=ceiling_light&state=1"
Text encoded
Text encoded can be used to retrieve and send values from HTTP servers that provide any kind of text in their responses. The resource definition must be as follows:
Polling: for getting data point values from any text document, the regular expressions has to be specified. This regular expression is used to parse the HTTP response and extract the information that shall be set as data point value. The regular expression must contain a matching group (denoted by "()" ) – otherwise the full match will be taken as data point value. Consider the response is as follows: "The data point value is 25%". To retrieve the value "25", the regular expression ".* ([0-9]+)%" can be used.
Updating: for updating a data point value, the text that shall be sent to the HTTP server must be specified. The text must contain the "ValueTag" (specified within xio.http.cfg, default @value@). E.g. "any text. Datapoint value is @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.
...
The 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:
...
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 "controllercontroller2" are used as parameters here. This means that the server will replace {0} by "controller1" and "controller2" respectively. For controller 1, this results in the following XPath expression and XML fragement:
| Code Block | ||
|---|---|---|
| ||
/devices/device[@name="controller1"]/setpoint/text() |
| Code Block | ||
|---|---|---|
| ||
<devices>
<device name="controller1">
<setpoint>21</setpoint>
</device>
</devices> |
For controller 2:
| Code Block | ||
|---|---|---|
| ||
/devices/device[@name="controller2"]/setpoint/text() |
| Code Block | ||
|---|---|---|
| ||
<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
...
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 set point, the following ZIP file can be used:
It contains the resource definition and an example of some data point definitions.
...
For the NETx BMS Server 2.0, you can use the HTTP module to send messages to the messaging service Telegram. The following ZIP file contains the necessary configuration data:
More information can be found here.
Sending SMS
The NETx BMS Platform and NETx Multi Protocol Server have build-in support for sending SMS via the Messenger plugin.
For the NETx BMS Server 2.0, you can use the HTTP module to send a SMS via online SMS services. An example of such a service is https://www.cm.com/. The following ZIP file contains the necessary configuration data:
Article applies to the following products:
NETx BMS Platform
NETx Multi Protocol Server
NETx BMS Server 2.0