Understanding what the parameters/calculations mean

[pmatos]

Hi,

I have a few questions:

1. What's the difference between parameters and calculations?
2. Do you hold a file somewhere about the meaning of the parameters you know about?

For example, If I open my Alpha Innotec Control application I can see values and explanations, I was wondering if I could print all values available and try to associate them to an explanation of what they are. I could then add to the documentation you already publicly have. What do you think?

Also, is there a way to cycle through all parameters, calculations and print their values?

[kbabioch]

@pmatos You'll find the "documentation" of parameters and calculation and how they interact with each other in the source code of python-luxtronik, i.e.:

• https://github.com/Bouni/python-luxtronik/blob/main/luxtronik/parameters.py
• https://github.com/Bouni/python-luxtronik/blob/main/luxtronik/calculations.py

Essentially this is a way to structure / abstract the code to have a Python representation of the data sent to and received from the controller.

You'll need to understand a little bit of Python to understand why the code is structured in this way. The actual meaning is not known for some/many of those parameters, since there is no public documentation and this is "only" a project based on reverse engineering.

[pmatos]

Turns out print all values was actually quite easy:

from luxtronik import Luxtronik, datatypes

l = Luxtronik('192.168.178.74', 8889)

print('Parameters')

for idx in range(1126):
    if not isinstance(l.parameters.get(idx), datatypes.Unknown):
        print('{} : {} {}'.format(idx, l.parameters.get(idx), l.parameters.get(idx).measurement_type))


print('Calculations')

for idx in range(260):
    calc = l.calculations.get(idx)
    if not l.calculations.get(idx):
        print('WARN: calculation {} is None'.format(idx))
    elif not isinstance(l.calculations.get(idx), datatypes.Unknown):
        print('{} : {} {}'.format(idx, l.calculations.get(idx), l.calculations.get(idx).measurement_type))

I understand that there's not much documentation. Still, I thought that we could work on a file that could contain things like

<id> : <explanation>

and sort of create a community-led file that could explain what things are. the IDs by themselves are sometimes but not often self-explanable.

[kbabioch]

Well, a "human-understandable" explanation might indeed be helpful. I'm just wondering whether it is a good idea to have it in a separate list (which will get outdated), or whether we should add some meta information into the code for every datatype?

@Bouni any preferences? I'm willing to document what I know, just wondering how best to start here.

[Bouni]

Thanks @kbabioch for helping out with this!

First of all, this must happen within the luxtronik python module rather than her in the home-assistant integration, so I'll transfer this issue.

[Bouni]

It's totally legit to have something like this:

# https://github.com/Bouni/python-luxtronik/blob/main/luxtronik/calculations.py#L53
10: Celsius("ID_WEB_Temperatur_TVL", "Temperatur Vorlauf"),

The big downside is that we do not have language support like this and German is far from ideal.
English is feasible but still a lot of users are not native speakers as well.

Ideally we would utilize gettext but I've never used it before and need to look into it. @kbabioch are you familiar with gettext?

[kbabioch]

I'm familiar with gettext and have used it across some projects (although not necessarily with Python).

However I'm not yet convinced that "abusing" strings as part of the class is the right way to document the parameters. While something like Temperatur Vorlauf is already more descriptive than ID_WEB_Temperatur_TVL.

In a perfect world the documentation should also contain more details, i.e. what this parameter means (physically), what the allowed values are (data type, min, max, etc.).

Typically I would suggest to use docstrings for this, so that the documentation lives next to the code to ensure it stays consistent as good as possible.

There are some problems though:

• The essential aspects that need documentation are entries in a dictionary. Not sure how well docstrings will work for that, some initial tests were not too promising.
• No i18n: The code will be documented in English most likely. I'm not familiar with docstrings in multiple languages. For me English is perfectly fine, but some users of the library might be unhappy with that. I'm pretty sure that the user base of this library are owners of AIT products, which is probably widespread in Germany, but nowhere else?

[Bouni]

Maybe the docs could live in a seperate file and matched by the id, that way we could have a proper name, description, min, max etc. as well as i18n support (at least thats waht I assume, nver really used it)

Something like

docs.py

paramter_docs = {
...
  10: {
    "name": _("Vorlauftemperatur"),
    "description": _("bla bla"),
    "min": 10.0,
    "max": 50.0
  },
...
}

_() the is used to get the correct translation via gettext.

I guess we need to pass the id then into the class to have it available for getting the docs, something like 10: Celsius("ID_WEB_Temperatur_TVL", 10),

[BenPru]

docs.py

paramter_docs = {
...
  10: {
    "name": _("Vorlauftemperatur"),
    "description": _("bla bla"),
    "min": 10.0,
    "max": 50.0
  },
...
}

Can we add a unique textual entity_key (e.g. flow_in_temperature) and a not mandatory visibility_id?
A part of the params and calulations have a visibility_id which says available or not.

[Bouni]

@BenPru You mean like the example you posted here: #41 (comment) ?

[BenPru]

@BenPru You mean like the example you posted here: #41 (comment) ?

Yes

[Bouni]

Was this just a made up example or did you actually start to implement and test this somewhere?

[BenPru]

Was this just a made up example or did you actually start to implement and test this somewhere?

Just example and perhaps to direct use for @kbabioch 😃.

[BenPru]

@kbabioch @Bouni
Home assistant have no translation for the entity names and attribute names currently can only translate values and names in the climate domain.
I have implemented my own translation and I think in a core integration I can't use them.
If we have an api call in this (or another) module to get a localized name and description would be gorgeous.
What do you think about that?

[Bouni]

@BenPru You mean having the translations in this core module and for example pass a language code to the Luxtronik calls and then it returns the already translated names?

That sounds good to me!

[BenPru]

the translations in this core module and for example pass a language code to the Luxtronik calls and then it returns the already translated names?

Yes, exact. Perhaps we can add the original ait Luxtronik name. E.g. "AV-Abtauventil":

[gerw]

Another possibility would be to put the descriptions of the parameters into a json file.

[kbabioch]

Another possibility would be to put the descriptions of the parameters into a json file.

I like this idea very much. Don't care too much about the exact format of this file (JSON, YAML, Python, etc.). During initialization that file can then be read and used by the library. This file could then be easily edited / translated by other means and it is rather easy to update it without touching the code.

What kind of data do we need to store / manage for each parameter / visibility / calculations?