HTTP Device Core

The HTTP Device Core for Blue Pill, core-protocol-http, allows users to send and to some extend receive and process information via HTTP requests. Effectively, this can help to bridge communication with devices with RESTful APIs where a dedicated device core is not available.

The device core has a basic mode and some more complex features that can come in handy in some cases. It has been designed to align with the feature set of the corresponding HTTP Client device core on the UniSketch platform, but it's far more robust and easy to extend to include new approaches.

Basic Configuration

Each device in the device core has the usual configuration available. Looks like this:

image.png

Cowboy Style

The most straight forward way to use the device core would be to send one-shot triggers cowboystyle. This requires only a minimum of configuration but provides the least amount of long term convenience. This is probably a good place to get started.

image.png

Notice the meta values here - they are essentially the configuration for the individual requests.

Adding a Cowboy Trigger to a panel is basically a matter of combining this parameter with a SKAARHOJ:Trigger master behavior:

image.png

The Meta value fields are the key to the whole thing. They would look like this:

image.png

The meta fields are in fact so called IO references in Reactor and that means you can insert references to device cores, variables, constants etc. For example, some of these values could be derived from a constant like "Behavior:Const:Body". This is important because the value gets parsed and pasting pure JSON into these fields won't work, so to make sure a complex string like JSON gets correctly picked up, it must be prefixed "String:" as you see in the examples.

Now, go have fun, shoot from the hip and see how far you get that way... :-)

Command Configuration

The device core allows you to configure a number of fixed commands too. The advantage is that you can bundle an A and B command into a single action for toggles etc. Also, this is the way you can use meta values with the \p1,\p2, ... placeholders etc. like you can for the TCP and UDP device cores. Finally, it's actually possible to decode some level of status back from the returned content of the device via a regular expression.

Below you see the example from the cowboy style trigger, but with some level of parameterization applied now:

image.png

In reactor this can be applied to a button in this way:

image.png

So to make a similar trigger for off, we can use the same command (2) but change the value of "p2" to 0 instead.

Parsing response and periodic requests

It's possible to parse the response of any request and let a matching part of that response get stored in the device core. This is done by the Matching Return Value field that contains a regular expression. You can study the format of regular expressions elsewhere, but they are basically very powerful and advanced string matching patterns.

Whenever the device core receives feedback from the server it will run the regular expressions set up for the command and if there is a match, it will take the value in parenthesis and store as the status value in the corresponding Status parameter. It's both possible for triggered requests as well as for periodic requests.

Here is an example:

image.png

Now, the return body from this request would look this way:

{
"Agent":{"Model":"3PF","DeviceName":"PowerBOX-E7","MAC":"24:A4:2C:38:DF:E7","SerialNumber":"24A42C38DFE7","JSONVer":"2.2","Time":"1970-01-01T16:51:29+01:00","Uptime":13889,"Version":"2.4.3","OemID":300,"VendorID":0,"NumOutputs":3},
"Outputs":[
{"ID":1,"Name":"PTZ (T8)","State":1,"Action":6,"Delay":2020},
{"ID":2,"Name":"Power output 2","State":0,"Action":6,"Delay":2020},
{"ID":3,"Name":"PoE Switch","State":0,"Action":6,"Delay":2020}
]}

And the regular expression will match exactly the portion of this JSON response that is highlighted in red. All the "\s*" is precautions to make sure any whitespace doesn't throw our parsing off, and there is an assumption that the ID attribute comes before the State attribute, but otherwise it should be a good example of how a regular expression can be built to provide some robustness towards variations. In the above case we have to bypass the Name attribute for example.

The main point is that the value of the State attribute is what we are after, but only when found for ID 1. To capture that value, we enclose it in parenthesis: "....([0-9]+)...."

And this happens every three seconds, so we are essentially monitoring the device for state change - on a single feature! And this also underlines the reason why SKAARHOJ generally integrates device cores custom to each device: There is just not efficient way to get all the state from any device by manually building up a ton of such expressions, capturing only one aspect at a time. And feedback from devices is the holy grails of quality integrations that are not simple pray-and-forget approaches to control.

But... now you have got it for the occasional case where there is only this type of "workaround" to get the job done.

Placeholders

The Body and the Path of requests are subjected to placeholders (see also the TCP and UDP device cores):


Revision #11
Created 25 October 2022 20:34:13 by Kasper
Updated 6 February 2024 11:01:46 by Andreas Hauge Thomsen