HTTP Binding

This binding allows using HTTP to bring external data into openHAB or execute HTTP requests on commands.

Supported Things

Only one thing named url is available. It can be extended with different channels.

Thing Configuration

parameter	optional	default	description
baseURL	no	-	The base URL (including protocol http:// or https://) for this thing. Can be extended in channel-configuration.
refresh	no	30	Time in seconds between two refresh calls for the channels of this thing.
timeout	no	3000	Timeout for HTTP requests in ms.
bufferSize	no	2048	The buffer size for the response data (in kB).
delay	no	0	Delay between two requests in ms (advanced parameter).
username	yes	-	Username for authentication (advanced parameter).
password	yes	-	Password for authentication (advanced parameter). Also used for the authentication token when using TOKEN authentication.
authMode	no	BASIC	Authentication mode, BASIC, BASIC_PREEMPTIVE, TOKEN or DIGEST (advanced parameter).
stateMethod	no	GET	Method used for requesting the state: GET, PUT, POST.
commandMethod	no	GET	Method used for sending commands: GET, PUT, POST.
contentType	yes	-	MIME content-type of the command requests. Only used for PUT and POST.
encoding	yes	-	Encoding to be used if no encoding is found in responses (advanced parameter).
headers	yes	-	Additional headers that are sent along with the request. Format is "header=value". Multiple values can be stored as headers="key1=value1", "key2=value2", "key3=value3",
ignoreSSLErrors	no	false	If set to true, ignores invalid SSL certificate errors. This is potentially dangerous.
strictErrorHandling	no	false	If set to true, thing status is changed depending on last request result (failed = OFFLINE). Failed requests result in UNDEF for channel values.
userAgent	yes	(yes )	Sets a custom user agent (default is "Jetty/version", e.g. "Jetty/9.4.20.v20190813").

Note: Optional "no" means that you have to configure a value unless a default is provided, and you are ok with that setting.

Note: The BASIC_PREEMPTIVE mode adds basic authentication headers even if the server did not request authentication. This is dangerous and might be misused. The option exists to be able to authenticate when the server is not sending the proper 401/Unauthorized code. Authentication might fail if redirections are involved as headers are stripper prior to redirection.

Note: If you rate-limit requests by using the delay parameter you have to make sure that the time between two refreshes is larger than the time needed for one refresh cycle.

Attention: baseUrl (and stateExtension/commandExtension) should not use escaping (e.g. %22 instead of " or %2c instead of ,). URLs are properly escaped by the binding itself before the request is sent. Using escaped strings in URL parameters may lead to problems with the formatting (see below).

Channels

The thing has two channels of type request-date-time which provide the timestamp of the last successful (last-success) and last failed (last-failure) request.

Additionally, the thing can be extended with data channels. Each item type has its own channel-type. Depending on the channel-type, channels have different configuration options. All channel-types (except image) have stateExtension, commandExtension, stateTransformation, commandTransformation and mode parameters. The image channel-type supports stateExtension only.

parameter	optional	default	description
stateExtension	yes	-	Appended to the baseURL for requesting states.
commandExtension	yes	-	Appended to the baseURL for sending commands. If empty, same as stateExtension.
stateTransformation	yes	-	One or more transformation applied to received values before updating channel.
commandTransformation	yes	-	One or more transformation applied to channel value before sending to a remote.
stateContent	yes	-	Content for state requests (if method is PUT or POST)
mode	no	READWRITE	Mode this channel is allowed to operate. READONLY means receive state, WRITEONLY means send commands.

Some channels have additional parameters. When concatenating the baseURL and stateExtension or commandExtension the binding checks if a proper URL part separator (/, & or ?) is present and adds a / if missing.

Value Transformations (stateTransformation, commandTransformation)

Transformations can be used if the supplied value (or the required value) is different from what openHAB internal types require.

The relevant transformation service needs to be installed via the Main UI or addons.cfg before use.

Here are a few examples to unwrap an incoming value via stateTransformation from a complex response:

Received value	Tr. Service	Transformation
{device: {status: { temperature: 23.2 }}}	JSONPATH	JSONPATH:$.device.status.temperature
<device><status><temperature>23.2</temperature></status></device>	XPath	XPath:/device/status/temperature/text()
THEVALUE:23.2°C	REGEX	REGEX::(.*?)°

Transformations can be chained by separating them with the mathematical intersection character "∩". Please note that the values will be discarded if one transformation fails (e.g. REGEX did not match).

The same mechanism works for commands (commandTransformation) for outgoing values.

color

parameter	optional	default	description
onValue	yes	-	A special value that represents ON
offValue	yes	-	A special value that represents OFF
increaseValue	yes	-	A special value that represents INCREASE
decreaseValue	yes	-	A special value that represents DECREASE
step	no	1	The amount the brightness is increased/decreased on INCREASE/DECREASE
colorMode	no	RGB	Mode for color values: RGB or HSB

All values that are not onValue, offValue, increaseValue, decreaseValue are interpreted as color value (according to the color mode) in the format r,g,b or h,s,v.

contact

parameter	optional	default	description
openValue	no	-	A special value that represents OPEN
closedValue	no	-	A special value that represents CLOSED

dimmer

parameter	optional	default	description
onValue	yes	-	A special value that represents ON
offValue	yes	-	A special value that represents OFF
increaseValue	yes	-	A special value that represents INCREASE
decreaseValue	yes	-	A special value that represents DECREASE
step	no	1	The amount the brightness is increased/decreased on INCREASE/DECREASE

All values that are not onValue, offValue, increaseValue, decreaseValue are interpreted as brightness 0-100% and need to be numeric only.

number

parameter	optional	default	description
unit	yes	-	The unit label for this channel

number channels can be used for DecimalType or QuantityType values. If a unit is given in the unit parameter, the binding tries to create a QuantityType state before updating the channel, if no unit is present, it creates a DecimalType. Please note that incompatible units (e.g. °C for a Number:Density item) will fail silently, i.e. no error message is logged even if the state update fails.

player

parameter	optional	default	description
playValue	yes	-	A special value that represents PLAY
pauseValue	yes	-	A special value that represents PAUSE
nextValue	yes	-	A special value that represents NEXT
previousValue	yes	-	A special value that represents PREVIOUS
fastforwardValue	yes	-	A special value that represents FASTFORWARD
rewindValue	yes	-	A special value that represents REWIND

rollershutter

parameter	optional	default	description
upValue	yes	-	A special value that represents UP
downValue	yes	-	A special value that represents DOWN
stopValue	yes	-	A special value that represents STOP
moveValue	yes	-	A special value that represents MOVE

All values that are not upValue, downValue, stopValue, moveValue are interpreted as position 0-100% and need to be numeric only.

switch

parameter	optional	default	description
onValue	no	-	A special value that represents ON
offValue	no	-	A special value that represents OFF

Note: Special values need to be exact matches, i.e. no leading or trailing characters and comparison is case-sensitive.

URL Formatting

After concatenation of the baseURL and the commandExtension or the stateExtension (if provided) the URL is formatted using the java.util.Formatter (opens new window). The URL is used as format string and two parameters are added:

• the current date (referenced as %1$)
• the transformed command (referenced as %2$)

After the parameter reference the format needs to be appended. See the link above for more information about the available format parameters (e.g. to use the string representation, you need to append s to the reference, for a timestamp t). When sending an OFF command on 2020-07-06, the URL

http://www.domain.org/home/lights/23871/?status=%2$s&date=%1$tY-%1$tm-%1$td

is transformed to

http://www.domain.org/home/lights/23871/?status=OFF&date=2020-07-06

Examples

demo.things

Thing http:url:foo "Foo" [
    baseURL="https://example.com/api/v1/metadata-api/web/metadata", 
    headers="key1=value1", "key2=value2", "key3=value3",
    refresh=15] {
        Channels:
            Type string : text "Text" [ stateTransformation="JSONPATH:$.metadata.data" ]
}

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)