Binding Development: Best Practices for Polling

Hi,

I’ve developed a PJLink binding (see this thread: New PJLink Binding for controlling multiple projector brands/models).

Because of a recent request of a user, I’m thinking about polling the projectors status regularly to be able to see changes made via the devices remote/device buttons. I’m confident that I could develop that somehow, but I’d prefer to do it the ‘OpenHAB way’.

Is there some documentation or another binding that shows how to do polling in the preferred way? Is there some builtin architecture to use for that in OpenHAB?

Thanks for reading through this!

Best Regards,
Nils

https://www.eclipse.org/smarthome/documentation/development/bindings/thing-handler.html#polling-for-a-state

1 Like

Thanks a lot, @Confused ! Seems like I did not read the docs carefully enough… That helps a lot :slight_smile:

One more question: Is there some general guideline about how often to poll? Or should the polling interval be configurable at thing level?

Best Regards,
Nils

No, this depends largely on the device and what makes sense for the user. For example when a device only updates its status once a minute it doesn’t make sense to poll faster. When it’s a device where the user can take action and then something should happen, for example a light switch, faster pooling makes sense.

Most bindings use a refresh configuration option on the thing. This allows the user to set the time. Consider why the user might want to change the refresh time. Ask yourself what use cases might be there to have different refresh times. For example a default refresh of 30 seconds might be enough for most use cases. But sometimes the user wants to have a quicker update because some action is taken on the change than the user could configure a faster refresh time.

Interestingly the documentation mentioned just calls the cancel in dispose. In general in the code I’ve seen in bindings this call is guarded with a null check. My recommendation would be to follow that pattern:

@Override
public void dispose() {
    if (pollingJob != null) {
        pollingJob.cancel(true);
        pollingJob = null;
    }
}
2 Likes

Thank you @hilbrand for the detailed answer!

I’ve chosen to have the interval configurable on the thing (defaulting to 5 seconds), as the binding is supposed to support many different brands and models and they might have varying reponse/processing times. Some models might even have trouble keeping up with e.g. 1 second intervals, so those users can disable polling or do it less frequently. On the other hand, users who want to react quickly to changes on the device can try to lower the interval length.

Best Regards,
Nils

@hilbrand about @nils.schnabel his comment in the PJLink topic “I could develop support for Class 2 features and test it with the JBMIA test tool, but I would only do so if there is a chance that the binding is ever being merged. I won’t invest that much more effort as long as it is unclear whether the binding can be accepted.”

His new binding is waiting for 2 reviews (from developer with write access) since September in GitHub. It would be a waste to keep this binding and a lot of other bindings with the same status in “the void”. The problem is probably review capacity but this isn’t positive for potential new contributors to Openhab.

Is there any way to streamline this process to get more contributors code in the add-ons repo in a more swiftly manner?

Exactly. Look at the openhab2 maintainers team on GitHub and you’ll find out that there are 4 maintainers only and those are mostly core contributors, too.

I once propose a staging concept (staging repo) but that was not accepted. Maybe you have another idea.

There are several aspects that could help. Yes more reviewers will help, but reviewing new bindings is just very intensive to do, and that is hard to change if we want to keep some kind of level of quality. For example I think it will take me about 4 hours to do an intensive initial review of a new binding and I know most of the pitfalls. What makes it harder is most binding developers have limited programming experience and make lots of small errors, sloppy programming, copy-pasting all over the place. And all those things are important to not have a single binding bring down OH once it runs resulting in bad experiences and even more support questions. So we try to take a good look at the code. But these things result in a lot of review time and iterations.

Having said that there are other things that could improve. For example it would ease the review process if the analysis report messages that the build process puts in a report are directly added into GitHub as review comments. We could even add some more common issues I see regularly to it. I want to look into how this could be made possible with the pull request. This could lift some of the burden of the reviewers. Because reviewing is one thing, what also costs time is the re-review process. Once a developers fixes things, it needs to re-reviewed. Since this mostly takes several iterations it can takes weeks (due to availability) before this completes.

While having the binding merged is great. It’s already possible to distribute the binding to users. At the moment this can be done through the Eclipse Market Place. That way users can already easily install the binding from within openHAB. I use it for new bindings and new features/bug fixes on existing bindings. While the Eclipse Market Place is going away due to changes related to the core there should be something similar become available. And I hope that will also make it easier to have pr pending bindings available.

Related to this specific binding. Technically it was first a wip, which means no reviews. So September isn’t completely accurate. Also with the recent changes to core, which has taken a lot of effort for the core developers that are also reviewers they simply hadn’t time to do reviews only adding more review request to the backlog, and yes that comes back to more reviewers would be great. Even with this: merging bindings still takes a long time…

In the end a binding will be merged at some point, but contributors shouldn’t think to lightly about having their binding merged and need to have some patience. I don’t know if we ever can speed it up. What I did was when I first contributed my first binding is to review other bindings, with the idea if those bindings are reviewed the actual reviewers have more time for my binding. In the process I actually learned a lot about how openHAB works (although I can image not everybody wants to do that).

I quickly looked at a few other open source home automation projects and their approach regarding code contributions. Most of them use auto CI pipelines and often just one accept from a write access developer to get a PR in the development branche. Thats a little bit to easy I agree :slight_smile:

The manual review distincts Openhab from other frameworks and also gives it an advantage in terms of stability / code quality. But this comes at a price of speed. So the idea of already spreading it through the Market place (which hopefully will be continued after the ESH>Openhab transition) could be a good platform for the “staging” of new add-ons.

I think this should be promoted a little bit more so new contributors can see their work being used in a more swiftly manner.

That would be a great step forward I think and would give some relieve for the maintainers.