openHAB HTTP Actions and HTTP binding

opeenHAB being a vendor and technology agnostic smarthome software provides the posibility to use HTTP to do the following among other things

• Import values from external devices
• Pull data from openhab API
• Update modify and delete values using HTTP POST / DELETE / PUT

You can do this with

• HTTP Actions or
• HTTP binding

openHAB API

openHAB comes with a very well documented API that you can use to make tests and make sure that your HTTP query is correct before even attempting to setup the HTTP binging or rules with HTTP Actions. Here’s how you can play with it.

After you login to openHAB as administrator, navigate to Developer Tools –> API Explorer. Here you will be presented with all the tags you can use for your HTTP requests. Let’s expand Things.

We will only play with GET requests as we don’t want to update / modify anything. So, let’s expand the GET /things/{thingsUID}

Click on Try it out and type the thingUID. Where do you get it ? Simply go to a Thing you configured and copy its Identifier. In the image below you see the identifier of a battery power zwave node

Enter the thingUID and click Execute.

You get a few interesting things in the response. The Request URL and also the headers which you will have to use in order to successfully pull that info.

The request headers are

accept: application/json
Authorization: Bearer

You also get the reply with the requested info in json format

You can copy the json reply into a parser in order to decide what information you need to pull (if not all)

I choose only properties.zwave_lastwakeup which shows the last time the device woke up and connected to the zwave controller.

Note: Make sure you have installed the JSONPath transformation from Settings –> Bindings

HTTP Actions

Actions are predefined methods that are called from openHAB rules and scripts. They are automatically imported and can be used to execute openHAB-specific operations or to send commands or data to external hardware or services. There are a set of built in core Actions and optional installable Actions. HTTP actions are a subset of the Actions you can execute within openHAB (Logging, Exec, Voice etc). You can use them out of the box without any additional installation in openHAB rules and scripts.

When we pull the value we want from the HTTP request, we need to store it in an Item ((remember what Items are?)

Let’s create one.

Then we create a Rule as follows:

val headers = newHashMap("Authorization" -> "Bearer oh.openhabAPI.XXXXXXXXXXXX", "WWW-Authenticate"-> "Basic")
val test_api =sendHttpGetRequest("http://192.168.XXX.XXX:8080/rest/things/zwave:device:2ba53c7e1c:node47",headers,1000)

var String status = transform("JSONPATH", "$.properties.zwave_lastwakeup", test_api)
sendCommand(Node47_Status,status)

We basically construct the headers based on the test we did in the API explorer above. I ignored the accept header as I received the value of it anyway.

After the Bearer you need to put your unique API Key. You get it by going to you openHAB admin profile and click on Create new API token. You need to provide your User name, Password, Token Name and Token Scope (optional). Once you create the token, please keep it somewhere safe as this gives access to openHAB api.

Since openHAB v3 it is mandatory to provide an authentication mechanism therefore I use “WWW-Authenticate” -> “Basic”.

Once you save the rule, you can run it now to verify it works (Ctrl+R)

You can check the events.log to verify that the command has been sent to the Item but you can also verify it from the GUI.

HTTP Binding

We can accomplish the same using the HTTP Binding. This is something you have to install by going to Settings –> Bindings.

openHAB documentation is quite comprehensive as to what that binding can accomplish but we will use it only to demostrate we can pull some information from the openHAB API. Obviously you can do much more.

This binding support only one Thing. Once the binding is installed, we can add it manually through the Things menu. Make sure you tick the Show advanced checkbox and leave the rest in their default values.

Again the headers are the same as we configured in the HTTP Actions section.

Now it’s time to configure the channel. Make sure again you select the Show advanced checkbox.

The State URL Extension appends the Node UID to the URL we configured for the HTTP Thing.

Once we created the Channel we need to link it with an Item.

By default all the channels will be refreshed every 30 seconds (you can change it in the Thing configuration) so you can go to the Item linked to the channel and verify it got the value.

Summary

We have seen two ways we can use HTTP to get information into Items through openHAB API. You can always check the openhab.log and events.log in case you have issues and also increase the logging for the HTTP Binding.