openhab-addons
openhab-addons copied to clipboard
openhab
[huesync] Hue Play HDMI Sync Box Binding - Initial contribution
This binding integrates the Play HDMI Sync Box into openHAB. The integration happens directly through the Hue HDMI Sync Box API.
The binding is using mDNS to discover HDMI Sync devices in the local network. The LED on the Sync Box must be white or red. This indicates that the device is connected to the Network. If the LED is blinking blue, you need to setup the device using the official Hue Sync App.
Community discussion thread: Philips HDMI Sync API
Closes #10218
Credits
- Marco Kawon: The code is based on his work - but the binding code was refactored/re-implemented. The refactoring is done to implement functionality step-by-step, so that I understand the code and in the hope to simplify it a bit to improve maintainability (and as a learning exercise for me).
- Andrew Fiddian-Green: Code review and technical support/advice
- April_Wexler (Kai): Testing
Tasks
- [x] ☠️ Binding skeleton created for org.openhab.binding.huesync
- [x] 🔎 skeleton mDNS discovery implemented
- [x] communication infrastructure
- [x] 🔎 mDNS device discovery - use API to get device information
- [x] 🔐 SSL Handshake & 🔎 Discovery
- [x] 🤝 Device registration
- [x] 👋 Device unregistration (remove thing)
- [x] ⛔ solve timing problems during shutdown
- [x] 📜 improve handling of configuration update(s)
- [x] CI/CD & Code maintainability
- [X] ⛔ Fix CI validation errors
- [X] ⚠️ Fix PR CI validation warnings
- [x] 🗨️ check feasibility of re-using resources for log & exception messages ✅
- [x] 🗨️ check feasibility of using
AuthenticationStore✅
- [x] Implementation
- [x] 🔌 device status polling
- [x] 🐞Solve handling of invalid tokens (automatic re-registration)
- [x] 🐞Investigate and resolve "Bad Request" warning
- [x] 🐞 Investigate and resolve partial device information during "poll"
- [x] 📦 Create device state DTO
- [x] Device status
- [x] HDMI input/output status
- [x] Commands
- [x] Channels
- [x] 📜 update/revert icons to use basic icon set
- [x] Create .channel xml declaration/poc for device information
- [x] Create .channel xml declaration prototype for HDMI input/output status
- [x] ➕ HDMI input/output channels (read only)
- [x] ➕ "execution" API infrastructure added ...
- [x] ➕ Add support to switch ambilight
on/off - [x] ➕ Add support to select
mode - [x] ➕ Add support to select HDMI source added
- [x] ➕ Add support for HDMI active channel
- [x] ➕ Add support to adjust brightness
- [x] ➕ Add support for intensity channel
- [x] ➕ Add support to switch ambilight
- [ ] 📜 Documentation
- [x] README
- [ ] PR in Docu-Repo to add binding icon
- [x] 🔌 device status polling
ℹ️: The 1st version will not support all possible functions - as the basic setup can be done via the official App ➡️ - I'll focus on status information and commands that are most relevant for automation in this PR.
This pull request has been mentioned on openHAB Community. There might be relevant details there:
https://community.openhab.org/t/philips-hdmi-sync-api/111679/39
@andrewfg Thanks! Take your time - progress will be slow unfortunately; as free time is a rare commodity ...
@andrewfg Hi Andrew,
I hope you are fine!
I'm not sure if you're following the progress of the implementation from time to time. I've finished most of the infrastructure that I plan to use in the binding. Next I'll will implement the most important channels that are relevant for automation (this PR will not support all the available options the API provides).
I'm a little bit unhappy - as I do not manage to provide/declare all the relevant information in the .xml definitions to automatically create a nice semantic model. Is this a limitation (no problem - but then I can stop to investigate) ... - or do I miss something in the .xml structure?
I've found that there is an advanced configuration option in the UI to add channels from the equipment (very cool). I will use this in the readme to show how to structure things (here comments are also very welcome - as I'm still not familiar enough with the semantic types and properties etc ...
I think the biggest problem of OH is, that most people (including me) are not aware how powerful it is what it is capable of ... e.g. today I learned that it is possible to use f7 and other icons via advanced UI configuration ...
with kind regards, Patrik
I'm a little bit unhappy - as I do not manage to provide/declare all the relevant information in the .xml definitions to automatically create a nice semantic model. Is this a limitation (no problem - but then I can stop to investigate) ... - or do I miss something in the .xml structure?
I am not sure what you think is missing? Perhaps have a look at the example below..
https://github.com/openhab/openhab-addons/blob/main/bundles/org.openhab.binding.neohub/src/main/resources/OH-INF/thing/thing-types.xml
Thank you for the example; I've also checked the .xsd definitions - but it seems that I've already added all the info I can. When the equipment/items are automatically created it does not look as nice as I would like to have it ... but that's not a huge problem. With the manual configuration I've added to the readme the representation in the model looks nice.
I'll keep it as is for the moment and continue with channel implementations to get functionality into the thing 🙂. I already use the alpha for some 1st simple automation tasks 👍.
Let me know if you see something I should change from a Java/openHAB framework perspective ... the infra is approaching its final shape; so I do not see any major gaps anymore in that area.
Commit 742872d is related to the following proposal/issue raised in the doc repository: #2276
➡️ simplify contribution with a lightweight environment depending on minimal configuration
➡️ might be that those files (.vscode) will not be merged, but be part of the documentation in the end. Subject to discussion ...
This pull request has been mentioned on openHAB Community. There might be relevant details there:
https://community.openhab.org/t/philips-hue-hdmi-sync-box/156352/1
@wborn & @andrewfg
Hi Andrew & Wouter,
I'm not familiar with the OH release planning process - I've added the binding to the OH 4.3 scope - as I'm confident that it will be ready by then. But how is the scope of a release planned/discussed/decided? Is there a place to propose and discuss what is in scope for a (maintenance) release?
For some users it might even be of interest if the binding is available in the next 4.2.x maintenance release 🤔. But to be honest, I've no idea how big the user base is - and I have it available of course for me 😋. The core features I need/use are almost complete and I already use what is implemented in a productive 4.2 setup. I would like to have it in the distro and add/fix based on requests and actual user needs and contribute elsewhere, where I miss things and could be of use.
The README is a pain point of mine - as I configure purely using the UI - but no config files anymore. I can describe the UI configuration - but if the file based configuration is a must I'll have to search for a volunteer to help me ...
There are a few minor open things I need to find out:
- Are special steps required that the binding is proposed to be installed based on mDNS discoveries done by OH?
- How can I make sure that there'll be the proper icon displayed in the binding list (somehow it's a no go for me without - well, one of many quirks of an old developer 😄; too much attention on details - but here I can forget pareto ...).
Thank you for your feedback and help. Highly appreciated. I hope you could follow my changes and have an eye on them from time to time - so I hope the final review will not end up with big surprises and/or refactoring needs. But we'll see ...
with kind regards, Patrik
... CI/CD failed with the following message:
[PR-openHAB-Addons] $ /bin/bash -xe /tmp/jenkins11467203783432675087.sh
+ rm -rf /var/jenkins_home/maven-repositories/2/org/openhab
+ rm -rf /var/jenkins_home/jenkins-built-in/maven-repositories/2/org/openhab
[PR-openHAB-Addons] $ /bin/bash /tmp/jenkins15520827243838903017.sh
From https://github.com/openhab/openhab-addons
* branch main -> FETCH_HEAD
Building add-on: org.openhab.binding.huesync
[EnvInject] - Injecting environment variables from a build step.
[EnvInject] - Injecting as environment variables the properties file path 'reactor.properties'
[EnvInject] - Variables injected successfully.
Parsing POMs
Downloaded artifact https://repo.maven.apache.org/maven2/org/openhab/openhab-super-pom/maven-metadata.xml
ERROR: Processing failed due to a bug in the code. Please report this to the issue tracker (https://jenkins.io/redirect/report-an-issue).
java.lang.IllegalArgumentException: Malformed \uxxxx encoding.
at java.base/java.util.Properties.loadConvert(Unknown Source)
at java.base/java.util.Properties.load0(Unknown Source)
at java.base/java.util.Properties.load(Unknown Source)
Locally I do not see any problems - will investigate as soon as I find time; but have no experience with maven other than using it in a trivial way to build locally. Not sure if it is caused by a change of mine - or a general build issue 🤔.
@wborn : Do you have an idea (I'll look at the encoding of my files - but that should be handled automatically and did not change - or at least it should not have...).
Do you have an idea (I'll look at the encoding of my files - but that should be handled automatically and did not change - or at least it should not have...).
It seems to be due to a bug in the Jenkins Artifactory plugin, see https://github.com/jfrog/jenkins-artifactory-plugin/issues/913.
I'm not familiar with the OH release planning process - I've added the binding to the OH 4.3 scope - as I'm confident that it will be ready by then. But how is the scope of a release planned/discussed/decided? Is there a place to propose and discuss what is in scope for a (maintenance) release?
We only assign the milestone when PRs get merged so they show up in the release notes. It depends on everyones availability what gets reviewed/merged. We usually only merge bug fixes to maintenance releases.
Are special steps required that the binding is proposed to be installed based on mDNS discoveries done by OH?
I see you already added a discovery method to the addons.xml file for this. If it doesn't work, see the documentation and the hue addons.xml file for more details and an example.
How can I make sure that there'll be the proper icon displayed in the binding list (somehow it's a no go for me without - well, one of many quirks of an old developer 😄; too much attention on details - but here I can forget pareto ...).
The UI will show the add-on image if one using the add-on ID (huesync) exists in the /images/addons dir of the openhab-docs repo.
Do you have an idea (I'll look at the encoding of my files - but that should be handled automatically and did not change - or at least it should not have...).
It seems to be due to a bug in the Jenkins Artifactory plugin, see jfrog/jenkins-artifactory-plugin#913.
Thank you - this information saves me a lot of time; as I do not need to investigate.
Hi Wouter & Andrew,
thank you also for the other information and explaining the release process and how to make sure the binding will get a nice image. As I've noticed you already removed the (wrongly) assigned milestone 👍.
I'll complete the remaining features I consider necessary for an MVP; and depending on the interest of the community to help with testing (and hopefully the README) we'll see about the timeline.
It also depends on the number of issues found during code review. I hope @andrewfg did have a look from time to time what's going so that I'm not too far from acceptable code. What's your opinion about including IDE specific things in the repository? I've started to include the necessary task configuration(s) and scripts for VS Code on Linux - as makes it easier to setup/start if someone wants to contribute. But as this is just one possible IDE and OS it might be better to check and update the documentation on how to develop or contribute to a binding 🤔. What is your opinion on that?
➡️ I assume that I can not update/release a version on the market place as long as the build agent is broken (I would prefer not to use a local build for that...). But as the jenkins issue affects the whole repository I hope this can be resolved in the near future.
hope @andrewfg did have a look from time to time what's going
I was looking at it from time to time, but unfortunately not in great detail. I am currently in France at the Olympics, so I could look at it in more detail in about 10 days..
I was looking at it from time to time, but unfortunately not in great detail. I am currently in France at the Olympics, so I could look at it in more detail in about 10 days..
Very nice - I watched the end of the opening ceremony (the Laser-Show was very impressive to watch on TV; I assume on-site it was even more impressing). I hope you've a lot of fun! No need to hurry - I'm using the binding in my personal setup and it seems pretty stable. I do not get a lot of feedback on the marketplace version, nor questions - so either it works well - or there is not a high demand for the implementation. But I still think the binding will add value to the platform. But with that background and the info from @wborn Wouter I would like to target 4.3 release if possible. I'm not aware of the schedule - but I think (hope) that it should be possible to achieve a 1st version until then.
Pain points are the readme (textual configuration), there I'm looking for some contribution/help - and at the moment there are no unit tests ... most of the logic is based on core infra, which is tested and serialization/deserialization that should be stable as well. And as like many developers, also for me tests are not my favorite thing to do in my private projects (I work in the medical field & have plenty of them during daytime 🙂). Let's see if any are needed to accept the PR and if so, what area we identify as a "must" to have tests ...
Enjoy the rest of the games and stay safe!
The last commit will be probably a controversial one; I'm very interested to get your opinions. I do not use the classic icons anymore for the channel definitions, but the "Material Design Icons" to give the UI a more modern appearance:
@kaikreuzer - what do you think and what's the proper place for a discussion if mdi could be part of the core (feature request, community channel, this PR ...)? As the classic icon set seems a bit outdated & mdi would also provide more icons ...
Together with the change from Florian PR 2614, that enables html in the description the thing channels are nicely represented in the main UI imho 🙂.
The last commit will be probably a controversial one; I'm very interested to get your opinions. I do not use the classic icons anymore for the channel definitions, but the "Material Design Icons" to give the UI a more modern appearance:
IMO Bindings should not need to know or care about the UI. I know there are some corner cases. The UI knows best how to render (with or without icons, configured icon set etc) the binding settings.
@kaikreuzer - what do you think and what's the proper place for a discussion if mdi could be part of the core (feature request, community channel, this PR ...)? As the classic icon set seems a bit outdated & mdi would also provide more icons ...
What do you mean with ‘part of the core’? Core API’s provide a IconProvider interface. It is used by https://community.openhab.org/t/iconify-icon-provider-4-0-0-0-5-0-0-0/149990 and (without knowing the terms of use) you can create a material design icon provider and publish it in the marketplace.
Thank you for your feedback!
I agree that there should be a strong separation of concerns in the architecture. But the current .xml schema definition includes the option to add meta information about the semantic (tags) as well as look:
IMO Bindings should not need to know or care about the UI. I know there are some corner cases. The UI knows best how to render (with or without icons, configured icon set etc) the binding settings. [1]
The classic icon set included in the distribution I remember well from the days I used the 1st available UI to define my pages. But today the main UI seems to be the default to enhance the user experience - especially for users that do not configure a minimal system with text configuration.
What do you mean with ‘part of the core’? Core API’s provide a IconProvider interface.
Yes - I'm aware; but my wording might be wrong and I might also have gaps in my understanding of the architecture. I did not check the code history - but I assume this API is a newer concept and that basic icons are part of an installation without the need to install an additional provider. I know that there are users traditional sitemaps and that the classic icons should not be removed to avoid breaking existing setups and thing configurations.
The other approach would be to decouple the property completely from any icon set - but that would require to define a comprehensive list of devices and device parts (e.g. hdmi input) - which we would have for free with mdi. As it is meta information it is optional and up to the UI if and how to use it.
In my opinion Main UI is the default UI for new users and for my (subjective) taste the old icons do not fit the modern look of the UI and also the list of available icons is limited. That's why I would like to trigger this discussion and attached the screenshot - as the more modern look, together with the right tags for the semantic model, the binding auto-detection would improve/modernize the feel of the application and hopefully make it more appealing to new users.
I'm curious what @florian-h05 Florian things about this topic - as UI expert.
I would like to target 4.3 release if possible. I'm not aware of the schedule - but I think (hope) that it should be possible to achieve a 1st version until then.
I would expect it a few days before the Christmas holidays, but we haven‘t discussed an exact date yet.
I do not use the classic icons anymore for the channel definitions, but the "Material Design Icons" to give the UI a more modern appearance:
The UI knows best how to render (with or without icons, configured icon set etc) the binding settings.
I am hesitant here what opinion to have here. Whilst I agree that bindings should not need to know (too much) about the UI, I agree that it would be nice to have more icons available than with the classic icon set. I have just looked up the docs and they are pretty clear about the category field: https://next.openhab.org/docs/developer/bindings/thing-xml.html#thing-categories Main UI is our default UI, it even has the org.openhab.ui package name and Main UI is in fact the only one making use of the category field — but it still is called category and not icon …
Lastly I would consider this a type of a architectural decision, the other options named here, especially extend the possible values and map between the value and icons of different sets would also allow the UI to show icons for channels matching their device „theming“ (iOS, Android, Aurora). So IMO this is a nice option that should be seriously considered — wrt to the implementation we would have a JS file in the assets of Main UI that would provide mapping between the categories and Framework7/Material Design icons and a function that accepts a category name and returns the icon name according to the selected theme, that would be pure JS and then a few lines of Vue changes to use this logic in the thing view.
what do you think and what's the proper place for a discussion if mdi could be part of the core (feature request, community channel, this PR ...)?
It does not need to be — it is actually already a part of the UI and bundled with it and can be used like material:iconname.
BTW, no matter how we decide here, but I would not accept the use of Iconify icons by the openHAB code base, what is used by openHAB needs to be bundled with it IMO.
I am hesitant here what opinion to have here. Whilst I agree that bindings should not need to know (too much) about the UI, I agree that it would be nice to have more icons available than with the classic icon set.
One does not prevent the other. Totally agree that it would be nice to have a large choice of icon sets. I would propose that this is configured as a system wide setting (by the user). IMO allowing each binding to hard code their own icon set would be the wrong direction and will probably lead to a sub par experience to users.
Not sure if it makes any sense, but if the classic icon set can be used as base and there is a mapping to their mdi counterpart, it would not be hard to render the icon from the icon set chosen by the user. Isn't that how the iconprovider / and iconify already work?
I would propose that this is configured as a system wide setting (by the user).
The iconset is determined by the theming setting of the UI: iOS, Android or Aurora, but to be alte to show classic icons for channels a new config option should probably be added to the UI.
IMO allowing each binding to hard code their own icon set would be the wrong direction and will probably lead to a sub par experience to users.
My proposal is, to extend the available categories (i.e. update the docs with new ones) and introduce a mapping from categories to iconsets inside the UI. It should be done inside the UI because it obviously is a UI-thing which icons to render for which category.
Isn't that how the iconprovider / and iconify already work?
TBH I am not sure how the IconProvider is used, that doesn't really matter for Main UI, because Main UI only loads Classic icons from the openHAB server through the IconServlet. Material icons and iOS/Aurora theme icons are part of the UIs assets and are included in the UI.
My proposal is, to extend the available categories (i.e. update the docs with new ones) and introduce a mapping from categories to iconsets inside the UI. It should be done inside the UI because it obviously is a UI-thing which icons to render for which category.
Yeah, that sounds like a better proposal then adding the icons directly in the channel html.
I would expect it a few days before the Christmas holidays, but we haven‘t discussed an exact date yet.
That sounds like plenty of time - but I assume the sooner the binding is merged, the more testing it will get by the community. So I'll try to finish the remaining work as soon as possible. In terms of features it is almost complete (MVP). I'll ask, if someone else needs additional functionality - but for my purposes and understanding the common automation use cases should be covered.
I have just looked up the docs and they are pretty clear about the category field: https://next.openhab.org/docs/developer/bindings/thing-xml.html#thing-categories Main UI is our default UI, it even has the org.openhab.ui package name and Main UI is in fact the only one making use of the category field — but it still is called category and not icon …
I would consider a revision of the .xml schema - as the category tag should not be used to define the look, also the semantic information is represented in a way not intuitive for me, using the tagging mechanism. A comprehensive list of device types and connectors (maybe even with a mechanism to add additional types) that could be mapped in the UI to the desired icon set, or theme would allow to achieve the goal of proper decoupling and a mapping. For MainUI the default icon set(s) could be discussed separately - as well as the mapping mechanism used:
Lastly I would consider this a type of a architectural decision, the other options named here, especially extend the possible values and map between the value and icons of different sets would also allow the UI to show icons for channels matching their device „theming“ (iOS, Android, Aurora).
If that area is touched a robust mechanism to handle state dependent icons would be nice as well - but maybe we should keep the changes small and incremental (if we decide to do something in that area at all).
I agree completely - but OH architecture is a bit beyond my understanding and the scope of the binding; it includes architectural decisions and potential .xml extension/changes (with all the implications, like backward compatibility - or migration ...). But I'm happy to contribute to the discussion ...
In my opinion the 1st impression (also visually) has a big influence, when you evaluate a software - you will not grasp the power nor potential in the short amount of time of you are willing to spend (me included) to evaluate the options. You'll judge on how complex you feel it is and if you like the look and feel. So I try to make the visual appearance of the discovery results as visually appealing as possible ...
... that sounds like a better proposal then adding the icons directly in the channel html.
I agree with @lsiepel, that the visual representation should not be the concern of the thing definition. But the current category field is defined for this purpose - which would bolster the argument to create a revision of the definition that takes the development and new capabilities added to the system within the last 10 years into account. Especially the semantic model - which is difficult to grasp for beginners and therefore good defaults would simplify the setup (add the thing from the inbox and click on create equipment ... - you only need to select the parent item).
If we use an icon set as default, it needs to be part of the distribution; or UI respectively. A far as I know, that is possible to do with iconify if we decide to do so (as there is an optional offline provider for the icons already).
If we'll follow up the icon/category/semantic .xml I would be happy to be part of the discussion - but I do not think that even if we follow up, that a decision will be taken before 4.3.
➡️ I'll revert the code, to use the default basic icon set/categories.
Note: Writing this response took me a while and I just noticed that there are new replies; I've not updated the text - so some of it might be redundant.