Proposal for a change to binding strings

[Chris Jackson]

The following is a proposal to change the binding string format in openHAB to make it more standard, readable and easier for binding implementers. I know that this is likely to be a contentious suggestion since it does change the binding configuration, and it may be one for ESH/openHABv2, but I thought I’d throw it out there in case anyone had any thoughts :) I personally think it would be great to get a roadmap started for these projects so that people can see what the future holds and work towards its implementation.

Overview

This outlines some proposed changes to the current binding structure within openHAB. It does not change the core binding structure, and in fact should make bindings easier to implement. The aim is to make it easier for binding implementers, and for users to configure items.

While the current use of binding configuration strings provides a flexible format to support item configuration within the binding, it is not standardised across bindings, and is difficult to implement within a configuration GUI. Such a GUI, or it’s backend, would need to produce the binding strings which would be difficult given their non standard nature. Additionally, these binding strings then need to be deconstructed within the binding - not a difficult task, but still one that needs to be implemented.

The proposal outlined here is to standardise the string format, and pass a dictionary of configuration items to the binding. This removes the task of deconstructing the binding string from the binding, and standardises it by putting it within the item provider.

If used with the GUI configuration proposal, which would allow bindings to provide information on their status, including detection of new devices, a semi automated (man in the loop) system can be devised to detect new devices and add them to the openHAB configuration.

Detail

Currently the GenericItemProvider reads the items from the model, and dispatches the strings in full to the binding along with the item name. Within the binding the string is deconstructed and each component processed accordingly.

The binding string format within the model would be changed to a JSON format (other formats could be used, however JSON provides a simple way to define structures in a human readable format). The binding string would then include the argument name as well as the parameter (eg “Direction”:”OUT”). Within the GenericItemProvider, this JSON string is parsed into a dictionary, and then passed to the binding for processing as before.

Examples of an existing item binding string versus a new item binding string -:

{ snmp=“<[192.168.2.111:public:.1.3.6.1.4.1.4526.11.16.1.1.1.3.1.2:10000] }

Becomes

{ snmp=“direction”:”IN”,”address”:”192.168.2.111”,”community”:”public”,”oid”:”1.3.6.1.4.1.4526.11.16.1.1.1.3.1.2”,”update”:”10000” }

The naming of arguments is largely up to the binding author to choose, however it may be appropriate to specify some commonly used arguments globally to standardise where possible. This again makes it easier for the users to write the strings. 

BindingConfigReader

/**

* This method is called by the {@link GenericItemProvider} whenever it comes

* across a binding configuration string for an item.

* 

* @param context a string of the context from where this item comes from. Usually the file name of the config file

* @param item the item for which the binding is defined

* @param bindingConfig the configuration string that must be processed

* 

* @throws BindingConfigParseException if the configuration string is not valid

*/

public void processBindingConfiguration(String context, Item item, String bindingConfig) throws BindingConfigParseException;

Becomes -:

/**

* This method is called by the {@link GenericItemProvider} whenever it comes

* across a binding configuration for an item.

* 

* @param context a string of the context from where this item comes from. Usually the file name of the config file

* @param item the item for which the binding is defined

* @param bindingConfig the configuration string dictionary that must be processed

* 

* @throws BindingConfigParseException if the configuration string is not valid

*/

public void processBindingConfiguration(String context, Item item, Dictionary<String, ?> bindingConfig) throws BindingConfigParseException;

I understand that this does mean changing all bindings and therefore may not be popular. However the change (to the binding at least) is quite small and I think it would significantly enhance the system. It’s easier for users to understand as the binding string reads in a more understandable way and it’s more flexible since the binding author can add more parameters without the constraint of putting parameter ‘x’ in position ‘y’. It’s also simpler to implement for the binding authors.

Of course, there’s nothing to stop bindings doing this now, and if we look at the zWave binding, this is very similar to what is done there (zwave=“<nodeId>[:<endpointId>][:command=<command>[,parameter=<value>][,parameter=<value>]…]”). Effectively, this proposal is to standardise on such a system to allow openHAB to grow…

It’s probably also worth adding that it’s probably possible to support both systems in order to ease the transition - old bindings would still work, but new bindings should be written to use the new system. Again, I’m happy to look at this if the feedback is positive…

[Ben Jones]

I think this has a lot of merit. I would be happy to update any of my bindings to use this new structure.

[Jan-Piet Mens]

> { snmp="direction":"IN", ...

I know nothing on openHAB internals, but looking it this from a user's
perspective, my first thought is: "why isn't this just plain, valid JSON?".

{

"address": "192.168.2.111",
"community": "public",

"direction": "IN",

"oid": "1.3.6.1.4.1.4526.11.16.1.1.1.3.1.2",
"update": "10000"
}

Regards,

-JP

[Davy Vanherbergen]

+1 It will be some work to update the bindings, but I'm in favor of the idea.  

[Romain Bourdy]

That wouldn't work this way, let's say we have Onewire  IN and KNX OUT, how would you write it ?

My 0.02$ :)

-RB

[Pauli Anttila]

I fully agree this proposal as well. Actually when I saw JSON format on EnOcean binding, I planned to propose this too. 

I would update "my" bindings to support new structure as well.

To make configuration GUI live easier, should there be an interface to query supported parameters and limits from the bindings? Of course this can be handled separately, but dedicated interface could handle different binding versions automatically on future.

Br,

Pali

2014-02-18 1:32 GMT+02:00 Ben Jones <ben.j...@gmail.com>:

I think this has a lot of merit. I would be happy to update any of my bindings to use this new structure.

--
You received this message because you are subscribed to the Google Groups "openhab" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openhab+u...@googlegroups.com.
To post to this group, send email to ope...@googlegroups.com.
Visit this group at http://groups.google.com/group/openhab.
For more options, visit https://groups.google.com/groups/opt_out.

[Chris Jackson]

Easy - it can be done in the same way as it is now -:

{ "binding":"knx","direction":"IN",.....} { "binding":"onewire","direction":"OUT",.....}
 

--

[Manolis N]

I also like the value-key pair approach on the item bidning, and see various benefits, including the GUI configuraiton Chris is talking about. 

Furthermore, I would like to suggest the following concept among those lines:

-make any value-key pair valid, in the item definition (in the binding or outside the bidning definition) and propagate this data in the core, to allow any item to carry anykind of metadata, for future use.

for example, I would like to add metadata to some items, such as, location in the house, or latlon if these are on remote locations.

Then (in the future) we could have a map, or a house layout image, which displays the items on their location, usefull for UI navigation and quick state view purposes. If this is served over the rest-api, (or from a dedicated bundle) then it's only a matter of UI presentation to take advantage of it. 

btw what I am describing I guess could be made possible by combining two binders on one item ? if yes, do you think it makes sense to implement a generic metadata bundle, that is used for storing meta data only? and consumed by other bundles if needed? 

[Chris Jackson]

Hi Pali,

Yes - you're absolutely right about the configuration description.... I've proposed two solutions, and I think the final is a combination of the two...

 

My initial thought, and one that is now partly implemented in HABmin, was an XML file that allows description of the binding parameters (https://github.com/cdjackson/HABmin/wiki/Binding-descriptor-files). I think this is fine for most 'static' data, but I think there is also a need for dynamic data to be provided as well. eg, a binding string might require a list of applicable interfaces, and this data is dynamic. For this, I posted a proposal for a configuration interface in early December - I'm happy to post this again...
 

Chris

 

-----Original message-----
From: Pauli Anttila <pauli....@gmail.com>
Sent: Tue 18-02-2014 14:54
Subject: Re: [openhab] Re: Proposal for a change to binding strings
To: ope...@googlegroups.com;

[Karel Goderis]

+1

Also, we could craft some common helper-functions to validate JSON tuples etc. 

I also like the idea of adding additional metadata to an Item state stored in a bindingprovider. That way some other functions - which are copied/re-used from binding to binding - (e.g. style getXYZbyABC()) can be made common. That is, you could query the bindingprovider for a list of Items that match a certain condition, like all items where "update" equals "10000" etc. 

And like anyone else, no problem to adjust bindings I wrote in the past

K

[Kai Kreuzer]

Hi Chris and all,

Thanks for sharing your ideas! A few comments from my side:

- The original idea was to have the binding config strings in the item file as simple as possible, so that it is easily human readable and can nicely fit in a single line. Nonetheless, I agree that it would be nice to have some syntax of different bindings.

- The binding config strings are definitely not meant to be supported through GUIs. Instead, every binding has a config class that implements the BindingConfig interface - GUIs should handle this object in deserialized form, e.g. as JSON.

- As this topic is related to the very core architecture, I would suggest to continue the discussion at http://eclipse.org/forums/index.php?t=thread&frm_id=271. We already started another discussion around binding configuraiton there (where I am still waiting for a response ;-))

- For Eclipse SmartHome, we are currently thinking about a much bigger enhancement to support auto-discovery and GUI-support for device handling. These new concepts might render your suggested change obsolete. We will very soon start an according discussion at the Eclipse Forum.

Best regards,

Kai

[Chris Jackson]

Hi Kai,

Thanks for the response.

- The original idea was to have the binding config strings in the item file as simple as possible, so that it is easily human readable and can nicely fit in a single line. Nonetheless, I agree that it would be nice to have some syntax of different bindings.

But surely having a standard for these strings makes life easier for everyone? The strings as they stand are IMHO NOT easily human readable since you can't tell what the different elements are without referring to the documentation. Making the strings self describing makes them a bit longer, but for sure makes them easier to read.

 

- The binding config strings are definitely not meant to be supported through GUIs. Instead, every binding has a config class that implements the BindingConfig interface - GUIs should handle this object in deserialized form, e.g. as JSON.

But again, having a simple standard should make it easier for bindings to implement (doesn't it). If everyone does there own thing it's messy, and we can't use a standard configuration system. Using a standard system also means we can standardise on the code, thus making it easier for implementers. I don't know the details of your thinking for the BindingConfig interface, but I really think it makes sense to try and standardise the strings.

 

- As this topic is related to the very core architecture, I would suggest to continue the discussion at http://eclipse.org/forums/index.php?t=thread&frm_id=271. We already started another discussion around binding configuraiton there (where I am still waiting for a response ;-))

I've not seen this. I thought the system sent an email - I'll take a look :) I agree this is ESH related, but since it also impacts the bindings I thought it was worth posting it here as well.

 

- For Eclipse SmartHome, we are currently thinking about a much bigger enhancement to support auto-discovery and GUI-support for device handling. These new concepts might render your suggested change obsolete. We will very soon start an according discussion at the Eclipse Forum.

I would think these are complimentary - I think no matter what, it's a good idea to standardise strings. I completely agree that autodiscovery and GUI handling are necessary (this is what is now done in HABmin for the zwave binding). However, my personal feeling is that autodiscovery is something that should be 'man in the loop'. So, the system auto discovers, and presents a list of new devices/items that the user can then decide to add (or not) and how they should be displayed.

Cheers

Chris