[argoclima] Initial contribution #15481

mbronk · 2023-08-22T23:53:10Z

This PR adds a new binding for ArgoClima HVAC devices.

Please refer to the included README.md for details of this binding's objectives.

Notably, the Connection modes section illustrates various modes this binding operates in.

Exemplary supported device:

Argo Ulisse 13 DCI Eco (WiFi model): User Manual | Installation Manual | WiFi Guide

Highlights (for reviewers)

The most notable items I suggest to focus on during the review are the binding modes which spawn a separate HTTP server thread(s), and a custom HTTP client
- Rationale: see README.md
- Notable classes: RemoteArgoApiServerStub.java | PassthroughHttpClient.java
Since it started as a DYI project (with no initial plans to upstream), I did not start any separate thread in the OpenHab community.
- If this is required for a new binding to get landed and the review process kicked off, I'd appreciate guidance.

Testing / development status

For what it's worth, I've been using this binding myself for a while now, and haven't noticed any anomalies, so as far as I subjectively perceive it, I consider it quite stable and fairly complete. No extensive multi-user large-scale testing has been performed though!
Outside of addressing any feedback stemming from review, I'm not currently planning any major functionality extensions. A.k.a. a 1.0 RC1 :)

Thank you in advance for all your feedback and guidance!

lsiepel

First pass, only looked at the readme and metadata, will try to look at the other files when i have some more time.

Most looks good, mainly some textual comments and some questions.

bundles/org.openhab.binding.argoclima/README.md

bundles/org.openhab.binding.argoclima/src/main/resources/OH-INF/thing/thing-types.xml

bundles/org.openhab.binding.argoclima/.gitignore

lsiepel

Allmost half way, my time is up for now, didn't want to hold it back.

Impressed about the extensive documentation. It is a bit overwhelming, but it helps.

bundles/org.openhab.binding.argoclima/scripts/download_ota_fw_files.py

...clima/src/main/java/org/openhab/binding/argoclima/internal/ArgoClimaTranslationProvider.java

...n/java/org/openhab/binding/argoclima/internal/configuration/ArgoClimaConfigurationLocal.java

.../java/org/openhab/binding/argoclima/internal/configuration/ArgoClimaConfigurationRemote.java

...in/java/org/openhab/binding/argoclima/internal/configuration/ArgoClimaConfigurationBase.java

...ava/org/openhab/binding/argoclima/internal/configuration/IScheduleConfigurationProvider.java

lsiepel

Finished the last part. Did leave some comments, but overall this seems a very solid (but complex) contribution.

Consider my review as an extra set of eyes to speed up the merge proces. I'm no maintainer, so there might be more feedback, or corrections to mine (don;t hope so).

...in/java/org/openhab/binding/argoclima/internal/configuration/ArgoClimaConfigurationBase.java

...n/java/org/openhab/binding/argoclima/internal/configuration/ArgoClimaConfigurationLocal.java

...in/java/org/openhab/binding/argoclima/internal/configuration/ArgoClimaConfigurationBase.java

...main/java/org/openhab/binding/argoclima/internal/device/api/protocol/elements/TimeParam.java

...n/java/org/openhab/binding/argoclima/internal/device/api/protocol/elements/WeekdayParam.java

.../java/org/openhab/binding/argoclima/internal/device/passthrough/RemoteArgoApiServerStub.java

...lima/src/main/java/org/openhab/binding/argoclima/internal/handler/ArgoClimaHandlerLocal.java

lsiepel · 2023-09-04T17:09:51Z

Hey @lsiepel, I know you're likely very busy with other things, but could you do me a favor and indicate (tentatively) when 🕐 would you be able to find a few minutes to take a final sweep through the latest comments and update their status? 🙏

Reason I'm asking is - while I tried to apply all the comments - I'm not 100% sure if I addressed everything, and would like to complete this phase, before I'm out for a short vacation next week (so that I leave it in a mergeable state). Let me know if it is realistic for you to take a look this week. Thank you in advance!

Give me a week max

lsiepel

LGTM Thank you for this binding.

It might take some time, but a maintainer will pick this up and review / merge this eventually.

mbronk · 2023-11-10T08:40:01Z

Hey @jlaur - sorry for bothering you... Since you're had some fly-by interactions with this PR (and are a maintainer), would you happen to know what might be the typical ETA for a new binding review novadays?
I do absolutely realize it's a community effort, and happy to wait as long as required - just making sure this PR didn't fall through the cracks and is on someone's radar still.

[joke] On that occasion, to lighten the mood... any chance to get it merged before christmas 😀 ? [ref: Duke Nukem] :) [/joke]

jlaur · 2023-11-11T10:32:53Z

would you happen to know what might be the typical ETA for a new binding review novadays?

My algorithm for calculating that is broken. 😄 You can have a look at recent merged PR's with label "new binding" to get an impression. Unfortunately our capacity is a bit low, but eventually someone will pick up your PR and start a review. A few things in general that can have an impact on the time for completing a review of a new binding:

Size: I created a PR of similar size on February 9th: [energidataservice] Initial contribution #14376. It was merged on July 3rd, so ~5 months. 10k lines is a rather large PR in comparison with other PR's.
Quality: Will not do any comparisons or references here, but obviously a PR requiring many (perhaps major) comments to be resolved will take longer than a very clean and high quality PR.
Speed of addressing comments: Once a review gets started, the momentum can be kept by addressing comments quickly. It will be easier for a reviewer to check resolutions and provide new feedback when still fresh in mind compared to picking up a PR with months old comments. This is not to be underestimated.
Compliance: If there are many disagreements between the contributor and maintainer, this can prolong the process. What can help here is being reasonable and keeping a good tone, since reviewers are also human. 😉 This makes it easier to reach good compromises. Not everything can be discussed though since there are some guidelines and openHAB architecture/ways of doing things that must be followed. It only happens very rarely that a PR is rejected because of disagreements, usually we reach an agreement and the PR is merged.

Personally I probably won't be able to pick it up for the time being since I'm involved in some other ongoing rather large PR's, and I prefer to not have too many open at the same time because I then risk becoming the bottleneck and momentum is lost.

mbronk · 2023-11-11T15:06:48Z

Thanks for such a thorough reply! Much more info than I had hoped for, appreciate it!
I was actually looking at some typical PR processing times myself, but failed to filter by new binding, so drew wrong conclusions... My bad!

Since 5+ months is not unprecedented, I'll stop getting worried for a while (till err... christmas? 😁 ).

And as for:

10k lines is a rather large PR

Yeah, I know. But also... java 😉

holgerfriedrich

Thanks for the contribution!
This is not a full review, just a few comments.

In addition to my comments, the following things need improvement:

javadoc is currently broken, at least the errors need to be fixed (mvn javadoc:javadoc|grep error:) - mainly & and < to be escaped.....

SAT is fine, warnings are fine, i18n seems ok

....argoclima/src/main/java/org/openhab/binding/argoclima/internal/ArgoClimaConfigProvider.java

...n/java/org/openhab/binding/argoclima/internal/configuration/ArgoClimaConfigurationLocal.java

...ava/org/openhab/binding/argoclima/internal/configuration/IScheduleConfigurationProvider.java

...main/java/org/openhab/binding/argoclima/internal/device/api/protocol/elements/TimeParam.java

mbronk · 2023-12-22T13:30:48Z

@holgerfriedrich Thanks fot the review. Fixed the javadocs errors (sorry for the miss!). Do you need me to address all javadoc warnings as well?

BTW. I had to extend pom.xml to add @implNote and @apiNote support. Is this typical/expected?
(I was thinking the plugin should inherit configuration from top-level, but it didn't work for me... not sure if it is my setup-specific or if I made an error somewhere...)

holgerfriedrich · 2023-12-22T13:40:35Z

@holgerfriedrich Thanks fot the review. Fixed the javadocs errors (sorry for the miss!). Do you need me to address all javadoc warnings as well?

No, warnings are ok. I have not checked, but most of the warnings should be undocumented elements. This is expected.
I just wanted to make sure that the javadoc build does not fail.

BTW. I had to extend pom.xml to add @implNote and @apiNote support. Is this typical/expected? (I was thinking the plugin should inherit configuration from top-level, but it didn't work for me... not sure if it is my setup-specific or if I made an error somewhere...)

If I got it correctly, you branched quite a wile ago. Those tags are now defined in pom.xml on top level (since ~2 months). Before, we had it on binding level.
Just fetch upstream/main and rebase.

mbronk · 2023-12-22T13:51:07Z

BTW. I had to extend pom.xml to add @implNote and @apiNote support. Is this typical/expected?

If I got it correctly, you branched quite a wile ago. Those tags are now defined in pom.xml on top level (since ~2 months). Before, we had it on binding level. Just fetch upstream/main and rebase.

Yup, that did it. I did a quick check and saw it on GH main, but it didn't occur to me it might not bee there for ages, so didn't check on my local copy... Thx for the pointer!

bundles/org.openhab.binding.argoclima/pom.xml

lsiepel

Thanks, LGTM.

I prefer another @openhab/add-ons-maintainers to have a second look. Not necessarily all files, the readme and the ThingHandlers will probably be enough to get a good understanding and provide some feedback.

lsiepel · 2024-06-28T16:46:23Z

@jlaur if you have some spare time, would be nice if you can look at this pr for a moment

bundles/org.openhab.binding.argoclima/src/main/resources/OH-INF/thing/thing-types.xml

jlaur · 2024-06-28T19:29:30Z

if you have some spare time, would be nice if you can look at this pr for a moment

I took at very quick look at the README which lead me straight to the thing type definition. I have posted a few comments there, as some of these things will be hard to change later without introducing breaking changes.

However, if the intention with your request is to have review comments added and fixed by tomorrow, I'm afraid this is too late and too out of context. I also doubt @mbronk would have time to even react on the comments I already posted, so please feel free to ignore.

Unit hint for Number:Dimensionless should be added (see #16614), so you could either commit those changes if @mbronk will not be able to respond, or it can be added in a follow-up PR.

lsiepel · 2024-06-28T20:18:50Z

if you have some spare time, would be nice if you can look at this pr for a moment

I took at very quick look at the README which lead me straight to the thing type definition. I have posted a few comments there, as some of these things will be hard to change later without introducing breaking changes.

However, if the intention with your request is to have review comments added and fixed by tomorrow, I'm afraid this is too late and too out of context. I also doubt @mbronk would have time to even react on the comments I already posted, so please feel free to ignore.

Unit hint for Number:Dimensionless should be added (see #16614), so you could either commit those changes if @mbronk will not be able to respond, or it can be added in a follow-up PR.

Thanks! My request was more about the overall complexity by looking at the readme and the handler. I would have merged it if you didnt have significant feedback at those areas.
Your current feedback about channel id's is minor, but altogether enough to postpone a merge. So this will propably not make it into 4.2. Maybe you can revisit the handler on a later time after 4.2 is done.

jlaur · 2024-06-28T20:30:11Z

Your current feedback about channel id's is minor, but altogether enough to postpone a merge. So this will propably not make it into 4.2. Maybe you can revisit the handler on a later time after 4.2 is done.

The channel type id's can be changed later on using update instructions, but it's really minor anyway, and doesn't violate naming convention. However, the thing type id, although also minor, cannot be changed later.

I would focus first on getting the modelling right (from the start), the implementation can always be refactored if it turns out to be too complex (for example). So I trust your review, and you can still consider merging this for 4.2. I believe strictly it doesn't have to be tomorrow even though we have feature freeze. The feature freeze s is mostly to avoid introducing regressions in existing bindings with last-minute changes. So if you and @mbronk would agree on the thing type id proposal, this is a small change, and there could still be a few days to do that (XML, constants, README).

bundles/org.openhab.binding.argoclima/scripts/download_ota_fw_files.py

Signed-off-by: Mateusz Bronk <[email protected]>

Contents: [argoclima] 1st round of review remarks (editorials) [argoclima] 2nd round of review remarks (config) showCleartextPasswords --> includeDeviceSidePasswordsInProperties (default: NEVER) [argoclima] i18n: Missing localization added Adds i18n for dynamic Channels and Thing statuses (incl. exceptions) [argoclima] 3rd round of review remarks [argoclima] 4th round of review remarks Renamed localDevicePort --> hvacListenPort Used instanceof pattern matching (where applicable) Demoted device communication logs to TRACE (non-review feedback) Added missing indirect command intercept in STUB mode [argoclima] Fixed typos in docs (README, diagrams) [argoclima] Post-review corrections: javadoc, etc. [argoclima] Bump version to 4.2.0-SNAPSHOT [argoclima] README.md minutiae [argoclima] Channels rename to lower-case-hyphen [argoclima] CP header update to 2024 [argoclima] Review remarks (password hashing extracted + minutiae) Signed-off-by: Mateusz Bronk <[email protected]>

Signed-off-by: Mateusz Bronk <[email protected]>

mbronk · 2024-06-29T06:58:34Z

The channel type id's can be changed later on using update instructions, but it's really minor anyway, and doesn't violate naming convention. (...) So if you and @mbronk would agree on the thing type id proposal, this is a small change, and there could still be a few days to do that (XML, constants, README).

@jlaur - I do agree with the proposed renames (less boilerplate, less typing). I had them globally-unique 'just in case', to avoid weird x-tenancy issues at development time... but as there are none... yeah, it can/should be shortened.

Given short timelines... behold...

The plan ™️ 😉

You guessed right I won't have time to properly apply (and test) this change in full just today (only have about 1 hour free before I head off for a short weekend getaway).
But - it's a straightforward one I can try to apply (=change, make things compile again) very quickly.

This would be a not-yet-tested code, but in a "frozen" state already with all the CI complete and such.
When I'm back from a short family trip, I'd be able to test and around Monday, give you a works 👍 / doesn't work 👎 .
Worst-case, the last commit can be reverted, or the changeset skips 4.2. Best case... what I'll commit today passes the "quality" checks and would become mergable on Monday.
@lsiepel , @jlaur - What do you think? OFC not a good engineering practice, but... sounds like a plan? 😁

lsiepel · 2024-06-29T07:06:34Z

The channel type id's can be changed later on using update instructions, but it's really minor anyway, and doesn't violate naming convention. (...) So if you and @mbronk would agree on the thing type id proposal, this is a small change, and there could still be a few days to do that (XML, constants, README).

@jlaur - I do agree with the proposed renames (less boilerplate, less typing). I had them globally-unique 'just in case', to avoid weird x-tenancy issues at development time... but as there are none... yeah, it can/should be shortened.

Given short timelines... behold...

The plan ™️ 😉

You guessed right I won't have time to properly apply (and test) this change in full just today (only have about 1 hour free before I head off for a short weekend getaway). But - it's a straightforward one I can try to apply (=change, make things compile again) very quickly.

This would be a not-yet-tested code, but in a "frozen" state already with all the CI complete and such. When I'm back from a short family trip, I'd be able to test and around Monday, give you a works 👍 / doesn't work 👎 . Worst-case, the last commit can be reverted, or the changeset skips 4.2. Best case... what I'll commit today passes the "quality" checks and would become mergable on Monday. @lsiepel , @jlaur - What do you think? OFC not a good engineering practice, but... sounds like a plan? 😁

Take your time, as it is a new binding I think we can merge it after the milestone. It should just be well tested.

mbronk · 2024-06-29T07:19:01Z

Take your time, as it is a new binding I think we can merge it after the milestone. It should just be well tested.

Oh, I'm not at all proposing skipping a testing phase. Given the nature of the changes (renames-only) though, early next week is an actual possibility (not cutting corners) - just can't make any guarantees today.

For me it is still far better to try (best-effort) to intercept 4.2 (b/c it's incremental for me) than to do the whole nine yards on 4.3 or later...

* Thing type ID renames: argoclima-local -> local, argoclima-remote->remote * Dropped '-channel' suffix from channel type IDs * Added % unit hint to eco-power-limit Signed-off-by: Mateusz Bronk <[email protected]>

mbronk · 2024-06-29T07:51:25Z

As mentioned - changes suggested by @jlaur are in. I'll separately confirm the testing status early next week.

~~Seems I can't vote (👎 ) for my own changes (or wasn't able to find an option), but please consider it a -1 from me for the interim (this applies to last commit's status only).~~

jlaur · 2024-06-29T09:36:13Z

bundles/org.openhab.binding.argoclima/README.md

+## Disclaimer
+
+This project is not affiliated with, funded, or in any way associated with Argoclima S.p.A.
+All third-party product, company names, logos and trademarks™ or registered® trademarks remain the property of their respective holders.


@kaikreuzer - sorry for tagging you directly (well, half-sorry, since I'm still doing it 😄) - do we have some project-wise disclaimer like this? It feels a bit inconsistent to have this at binding level, since I guess most bindings do not have this. On the other hand, it must be on binding-level to mention specific companies we are not affiliated with. From a legal perspective, is this needed at all?

@lsiepel, @mbronk - FTR, my comment here is generic and doesn't have to be considered for the PR at hand. Depending on response from @kaikreuzer we can adjust (if needed) even after this PR is merged.

Signed-off-by: Mateusz Bronk <[email protected]>

mbronk · 2024-07-01T13:24:57Z

As mentioned - changes suggested by @jlaur are in. I'll separately confirm the testing status early next week.

Update

All tests have passed on my end.

lsiepel

Thanks LGTM. This will (as exception due to feuture freeze) be included in 4.2.

* Initial contribution of the ArgoClima binding Signed-off-by: Mateusz Bronk <[email protected]>

* Initial contribution of the ArgoClima binding Signed-off-by: Mateusz Bronk <[email protected]> Signed-off-by: Patrik Gfeller <[email protected]>

* Initial contribution of the ArgoClima binding Signed-off-by: Mateusz Bronk <[email protected]>

mbronk requested a review from a team as a code owner August 22, 2023 23:53

mbronk force-pushed the mbronk/argoclima_binding_wip_OH4.1-SNAPSHOT-clean branch from a7a9dc8 to ed0a70f Compare August 22, 2023 23:58

mbronk mentioned this pull request Aug 23, 2023

[argoclima] ArgoClima Binding Logo openhab/openhab-docs#2125

Merged

jlaur added the new binding If someone has started to work on a binding. For a new binding PR. label Aug 23, 2023

mbronk force-pushed the mbronk/argoclima_binding_wip_OH4.1-SNAPSHOT-clean branch 3 times, most recently from b6f8a15 to e22b162 Compare August 24, 2023 18:54

lsiepel reviewed Aug 25, 2023

View reviewed changes

mbronk force-pushed the mbronk/argoclima_binding_wip_OH4.1-SNAPSHOT-clean branch from e22b162 to 7cc19e8 Compare August 25, 2023 20:05

This comment was marked as resolved.

Sign in to view

lsiepel requested changes Aug 27, 2023

View reviewed changes

This comment was marked as resolved.

Sign in to view

lsiepel requested changes Aug 28, 2023

View reviewed changes

This comment was marked as outdated.

Sign in to view

mbronk requested a review from lsiepel August 31, 2023 16:13

This comment was marked as outdated.

Sign in to view

lsiepel approved these changes Sep 10, 2023

View reviewed changes

mbronk requested a review from jlaur November 10, 2023 08:28

holgerfriedrich requested changes Dec 21, 2023

View reviewed changes

mbronk force-pushed the mbronk/argoclima_binding_wip_OH4.1-SNAPSHOT-clean branch from 8541027 to d56a032 Compare December 22, 2023 13:48

wborn reviewed Dec 23, 2023

View reviewed changes

bundles/org.openhab.binding.argoclima/pom.xml Outdated Show resolved Hide resolved

mbronk force-pushed the mbronk/argoclima_binding_wip_OH4.1-SNAPSHOT-clean branch from 23700ae to 5f02573 Compare December 23, 2023 10:27

lsiepel approved these changes Jun 2, 2024

View reviewed changes