[huesync] Hue Play HDMI Sync Box Binding - Initial contribution

[pgfeller]

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

• ☠️ Binding skeleton created for org.openhab.binding.huesync
• 🔎 skeleton mDNS discovery implemented
• communication infrastructure
  • 🔎 mDNS device discovery - use API to get device information
  • 🔐 SSL Handshake & 🔎 Discovery
  • 🤝 Device registration
  • 👋 Device unregistration (remove thing)
  • ⛔ solve timing problems during shutdown
  • 📜 improve handling of configuration update(s)
• CI/CD & Code maintainability
  • ⛔ Fix CI validation errors
  • ⚠️ Fix PR CI validation warnings
  • 🗨️ check feasibility of re-using resources for log & exception messages ✅
  • 🗨️ check feasibility of using AuthenticationStore ✅
• Implementation
  • 🔌 device status polling
    • 🐞Solve handling of invalid tokens (automatic re-registration)
    • 🐞Investigate and resolve "Bad Request" warning
    • 🐞 Investigate and resolve partial device information during "poll"
  • 📦 Create device state DTO
    • Device status
    • HDMI input/output status
    • Commands
  • Channels
    • 📜 update/revert icons to use basic icon set
    • Create .channel xml declaration/poc for device information
    • Create .channel xml declaration prototype for HDMI input/output status
    • ➕ HDMI input/output channels (read only)
    • ➕ "execution" API infrastructure added ...
      • ➕ Add support to switch ambilight on / off
      • ➕ Add support to select mode
      • ➕ Add support to select HDMI source added
      • ➕ Add support for HDMI active channel
      • ➕ Add support to adjust brightness
      • ➕ Add support for intensity channel
  • 📜 Documentation
    • README
    • PR in Docu-Repo to add binding icon

---

ℹ️: 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.

[openhab-bot]

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]

@pgfeller I will start to look at this tomorrow.

[pgfeller]

@andrewfg Thanks! Take your time - progress will be slow unfortunately; as free time is a rare commodity ...

[lsiepel]

Completed the review. Many relative small changes are required. When all comments are addressed (please do so by thumbs up or writing a comment, not by resolving comments), i'll look over it again and we are ready to merge this.

[lsiepel]

Don't log from the exception itself, better to log when it occurs and base it on how it is handles.

[lsiepel]

Handle the TODO

[pgfeller]

@lsiepel Thank you for the fast review! I'll work on the findings as soon as possible. I'll split the work into multime commits - as I can sometimes not allocate a lot of time to work on the project. Once I've addressed all feedback I'll send you a message. I'll not mark the comments as resolved, but add a comment (e.g. commit id).

[openhab-bot]

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/52

[lsiepel]

When looking at some resolved comments, i noticed some new and wanted to share them right away.

Besides these i want to point you to the coding guidelines regarding logging:
https://www.openhab.org/docs/developer/guidelines.html#f-logging

[lsiepel]

Each sentence on its own line

Suggested change

	To communicate with the sync box, you need to couple the thing with the hardware (registration). The thing will start this process automatically. To complete the registration you just press the "coupling" button on the sync box for 3 seconds.:
	To communicate with the sync box, you need to couple the thing with the hardware (registration).
	The thing will start this process automatically.
	To complete the registration you just press the "coupling" button on the sync box for 3 seconds.:

[pgfeller]

Thanks! The logging is still no my todo -... but I'll have a look at the guidelines. The markdown mistake I make every time. I wonder if the linter could mark them as error as well - so that you and other reviewers do not need to waste time on such trivialities. Same goes for naming conventions - as every project I'm working on uses different conventions and sometimes I do not work on one of them for a while it is easy to do it wrong (and if I read the coventions every time again, the timeslot is already over ...).

The CI/CD and linter of the project already has a very high quality. I'm not familiar with the stack used - but maybe the investment in some more linter rules would increase productivity and review overhead. Do you know who is the maintainer of the pipeline? Then I could ask if that's easy to achieve - or a bigger project.

Something else the README: I had a look at the Hue binding README as a reference and noticed, that it used some images for visualization. We removed them from the README; but honestly if possible I would like to re-introduce them - as it seems other bindings do so as well and I realy think the documentation looks better without them. Would it be acceptable to re-introduce them?

https://www.openhab.org/addons/bindings/hue/#philips-hue-binding

[lsiepel]

Confectrician did a lot of work on the documentation/linter. I use vscode and it markes all the issue by default (atleast i'm not aware that i added an extension). Maybe the static code analysis can be extended to cehck the thing-structure.xml files for naming convention. If you can make the life easier for contributers and maintainers, your are very welcome!

Regarding the images i prefer that you leave them out.