HTTP- Request

Using http-Requests diverse contents can be called and processed from a web server or can be sent to a server. Therefore, the methods GET and POST are available. The URL (Uniform Resource Locator) is a combination of three different parts (basis URL, target and value object resp contents. Compulsory arrays are name, input object and basis URL. For the evaluation of the answer from a webserver a module is available which can search the answer by regular expressions and based on this can trigger events on the KNX.

Job Name

Required field. Assign a unique name for the job. The name must not contain more than 15 characters.

Gate Group Addresses

By Gate Group Addresses job will be released or blocked. The release object releases or locks the job. It is about an EIS1 object:

Field blank = Job is released.
Field completed, value 1 = Job released.
Field completed, value 0 = job locked.
Field completed, no value = job locked.

As soon as one address is filled in, release will behave respective to the value of the group address. If no value was sent to the address and the address is presently without values, job will be blocked.

Input group address

Required entry. Input object has to be EIS 14. According to its value, several entries in the target objects will be released. In case input objects carries option “wildcard”, releasing EIS 14 value doesn`t play a part.

Error text

If the request did not success normally the server gives out an error text, which job can reproduce as EIS 15 text message.

Protocol

As protocol, „http“ or „https“ (http-secure) is available. Https transmits data encrypted. For doing this, server and client (EIBPORT) have to exchange certificates and keys, so connection buildup will take a longer time as usual.

Basis-URL

Required entry. In this array the address of the server which should be requested must be entered. You can use DNS names or IP addresses. If using DNS name, DNS settings of EIBPORT must be correct, rsp. the DNS server(s) have to be reachable.

DNS request will take relatively long time sometimes. To speed preforming of the job, IP address of the server can be enterd. Then a DNS request will be unnecessary.

If IP address of a DynDNS account varies, maybe IP will differ for a moment from the address, which EIBPORT has stored in his internal DNS schedule. In this case, request will have the incorrect address.

Auth name und Auth password

If necessary, username and password for http authentication can be entered. In case protocol “http” is activated, http basic authentication will be used. Thereby user data and password will be transmitted in uncoded form. „https” uses the same account, certainly transmit of authentication data will be encrypted.

Request Type

A HTTP-Request can be executed in two different ways. It may be selected between

method “GET”, “POST”, “PUT” und “DELETE” select.

GET
Is the most commonly used method to request data from a web server and is also frequently used to transmit data or control commands via URL parameters (The technically correct term for a URL would actually be URI). The actual purpose of GET requests, however, is to request data.
POST
Is used to be able to transmit contents to a server. For example, it can be used to transmit form data causing the server to create new data or change existing data. However, data can also be transmitted in the same way as the "GET" method by transmission via URL parameters. Often, these methods are combined. Via URL, the target of the data which is provided is addressed precisely.
PUT
Is used in a similar fashion as POST. If one proceeded strictly according to definition, POST would be responsible for changing existing data and PUT would be responsible for creating new data. However, the procedure is the same as with POST. For this reason, PUT is frequently not used and all data manipulation commands are transmitted via POST.
DELETE
Is used for deleting data. DELETE is subject to the same limitations as GET. No data is delivered. All parameter setting takes place via URL.

Note: If method „POST“ ist selected the URL may not be completed under „target“ but in array „Basis URL“. The input array for the target definition is available (mx 256 characters) for „POST“ – data.

Content Type

If under „Request Type“ method „POST“ is selected the selection for content type will be released. The combo box defines the encoding of the data being sent via „POST“ method to the server. This array serves to inform the server about the type of data expected. Several data types can be selected:

text/plain
Content of the „Post-Data“ is marked as plain text
text/xml
Content is marked as xml- file
text/html
Content is marked as HTML- file.
application/x-www-form-URL encoded
The server is told that the text is URL encoded.

Special characters will be replaced by according to character strings. More information about this can be found in the web by searching „URL Encoding“.

Note: Some servers require a dedicated data type within the content. Due to this all-data packets with differed content type information will be rejected even if the content complies with the required content type.

Request: URL Targets

Number of targets

You can allocate to every basic URL several targets. In the targets the variable part of the URL could be entered, which alters during the different requests. Maximal 8 targets can be filled in.

Wildcard

If this option is activated, corresponding target will be released by any incoming EIS 14 trigger value.

One job can only containt one wildcard entry.

Trigger value

Determine the EIS 14 value which should trigger the target. EIS 14 has a range from 0-255.

URL

Basic URL will be completed with that data array. To transmit the value objects, which are entered in the following part, the variables „\0“ to „\9“ have to be used. The “backslash” will announce one value object and following digit will determine value object 1-10. “0” will be value object 1 and “9” will be value object 10.

Between basic URL and URL completion, the necessary separation with „/“ (slash) will not be entered automatically. Slash must be set by user, neither at the end of basic URL or at start of URL completion.

Send values

Value objects

Up to 10 value objects can be set. Each of them may contain these EIS types:

EIS 1 (1 Bit)
EIS 5 (2 Byte FP)
EIS 6 (1 Byte)
EIS 9 (4 Byte FP)
EIS 10s (2 Byte value)
EIS 10u (2 Byte unsigned)
EIS 11s (4 Byte value)
EIS 14s (1 Byte value)
EIS 14u (1 Byte unsigned)
EIS 15 (14 Byte Text)

Job Editor Classic - HTTP Request Sending Values

Address

Please enter the group address which handed over the value object.

EIS Type

Depending on what EIS Type is chosen the format entry array behind changed.

Format

According to the EIS Type, the format entry array will be set. The format entry array serves the possibility to give the value object the right formatting. In this way for EIS 1 instead of “1” or “0”, “ON” or “OFF” can be used.

EIS 1: Entering text for „1“ and „0“ is available.
EIS 5 and EIS 9: Factor and offset can be adjusted. Value will be multiplied by “factor” and added by “offset”.
EIS 6: Will be interpreted as percentage value from 0% to 100%. Percent sign will not be transmitted and has to be entered in URL completion if necessary (by “%%”).
EIS 10, EIS 11 and EIS 14: Will be directly passed as text values in URL completion.
EIS 15: Also, these values will passed directly as text values. In this way fully free completions out of EIB/KNX can be realized. EIS 15 allows maximal 14 digits.

Insert Spaces: If a space is inserted after a value object, it must be "%% 20" is entered.

Answer: Response

Up from Firmware Version 0.11.5 the HTTP Request Job provides the possibility to interpret the response from the web server. For this the content of the response file can be searched by regular terms and so the wanted values can be filtered out. The result of the filters can be sent out on up to 4 outputs to a KNX address.

Groups

In order to allocate values to the 4 outputs groups have to be defined within the regular expression. Per group one output is used. The sequence proceeds from the left to the right resp according to the syntax of the regular expression. A group is set by ():

CODE

Expression (Group1=output1)expression(Group2=output2)… etc.

Regular Expression

Due to the complexity of this subject, it would burst this documentation. For more information, please refer to the diverse documentation in the internet. There functionality and use of regular expressions are described comprehensively.
To give an example for use it will be described later.

Flags (Checkboxes above the expression)

These flags serve for changing the behavior of regular expressions. In more complex expressions this will help if for search in several lines. These flags are available:

Case Insensitive:
The upper and lower case is not taken into account.
Dot All:
The expression "." Considered by all the characters. He would not see otherwise line endings. In another context, "Single Line" called.
Multiline:
Must be used if the expression is not valid just for one line but spread over many lines
Extended:
By setting this flag the expression is also valid for „extended characters. So even commented out strings can be searched.
Ungreedy:
Basically, a regular expression tries to provide a maximum number of hits. In some cases, this can be obstructive; setting the flag causes a break after the first hit. If by ". *?" Resolved in the expression itself.

Outputs

As already described above the outputs are operated by groups within the regular expression. A maximum of 4 outputs is allowed. For each address array the access to the ESF data is possible using the arrow.

EIS Types

These EIS types can be used for the outputs. For EIS 1 and EIS 5 special settings are valid.

EIS 1 (1 Bit)
EIS 5 (2 Byte FP)
EIS 6 (1 Byte)
EIS 9 (4 Byte FP)
EIS 10s (2 Byte value)
EIS 11s (4 Byte value)
EIS 14u (1 Byte unsigned)
EIS 15 (14 Byte Text)

EIS 1 (Mode)

If this data type is selected two modes can be used.

Read value:
In this mode the value being detected by the expression will be read and sent.
Match Pattern:
informs if the expression has led to a result.
In case of “yes” it will be sent out a “1”, else a “0”.

EIS 15 (output: format)

If data type EIS 15 is selected, the output can be formatted by control characters. These are the possible ones:

„%f“ = floating point value
„%d“ = decimal value
„%s“ = text value

Data / Length

For data types EIS 1 to EIS 14u the data format and eventually the length has to be set. This is due to the fact that the data may be returning from the server in different formats.

ASCII - Unsigned long decimal The content consists of ASCII characters a 'long' data type, unsigned decimal coded
ASCII - Signed long decimal Signed decimal.
ASCII - Unsigned long hex unsigned hexadecimal.
ASCII - Signed long hex Signed hexadecimal.
ASCII - Unsigned long octal Octal unsigned.
ASCII - Signed long octal Octal signed.
ASCII - Floating-Point floating-point number
Binary - Unsigned integer little endian (whole) number with little endian byte order, and without a sign
Binary - Unsigned integer big endian with big-endian byte order
Binary - Signed integer little endian Little endian signed
Binary - Signed integer big endian Big endian signed
Binary - Floating Point little endian floating point with little-endian
Binary - Floating Point big-endian floating-point number with a big-endian

Moreover, for all binary data the data length has to be set. The data length can be between 1 and 8 bytes.