Improve API Documentation

[K1ngjulien]

Hi!
Loving the simplicity of this and would like to contribute!
Unfortunately, it is not quite obious to me from reading the code how the api communication is set up and what the different endpoints provide. I see two different api tokens and have no clue how and what they are used for and how they are aquired.

It would be nice to have a bit of documentation about this to make it easier to get started!

Something like this would toatally suffice:

/api/zaehler

Example Request:

{
    "apikey": "asdf"
}

Example Response:

{
    "values": [1, 2, 69]
}

I can try writing some of this if you show me where to look :). Chrome Devtools on the smartmeter dashboard?

[DarwinsBuddy]

Hi @K1ngjulien!

I appreciate your support :)
I think documenting it could be one thing, but since documentation tends to deteriorate over time, I'd rather stick to proper tests. So if you're familiar with pytest you could contribute some api test cases. Even when they are mocked, imho they provide enough insight into the API than we could achieve by simultaneously have to maintain both the documentation and the tests.

For "reverse engineering" the API use, as you already pointed out, Chrome's DevTools on the smartmeter portal.

I create already a ticket for specific test cases we didn't cover yet: #113

Since the API is not open, I fear it could change faster than we could adapt code and documentation. So better just change test cases for that matter.

If you coincidentally have access to a PV sensor, we are still missing test code for that as well. :)

Thanks in advance for any contribution what so ever.

[K1ngjulien]

Wiener Netze changing the API on us is not really something i would fear (unless it has happened before). It looks to me like they're propperly versioning their endpoint urls.

I'll have a look what I can do and probably write some api docs at least for myself :)

If you coincidentally have access to a PV sensor, we are still missing test code for that as well. :)

Funny you mention that... we have PV on our roof, but wien energie has been stealing all our unused electricity since they installed the smart meters and won't give us an "einspeisezählpunkt" for our 10 year old installation...

My neighbor seems to have finally gotten one, so I'll have to talk to him how he did that and maybe then i could help with the PV api :)
Are there any major differences between a normal zählpunkt and an einspeisezählpunkt for pv? or do you get more than just the energy meter measurements once you're selling to the grid?

[K1ngjulien]

Also: Do I just copy my code to homeassistant/custom_components/wnsm for development?

[DarwinsBuddy]

Wiener Netze changing the API on us is not really something i would fear (unless it has happened before). It looks to me like they're propperly versioning their endpoint urls.

It happened before, and afaik they are not versioning it (at least I am not aware of proper versioning)

I'll have a look what I can do and probably write some api docs at least for myself :)

If you write it any way, then please contribute it to the Wiki :)

If you coincidentally have access to a PV sensor, we are still missing test code for that as well. :)

Funny you mention that... we have PV on our roof, but wien energie has been stealing all our unused electricity since they installed the smart meters and won't give us an "einspeisezählpunkt" for our 10 year old installation...

I'd suggest switching to another service provider. Wien Energie is not giving you that, as they probably don't want to buy electricity from you. But there are other good options available for selling. Wiener Netze has to provide the infrastructure in this case, i.e. the smart meter.

My neighbor seems to have finally gotten one, so I'll have to talk to him how he did that and maybe then i could help with the PV api :) Are there any major differences between a normal zählpunkt and an einspeisezählpunkt for pv? or do you get more than just the energy meter measurements once you're selling to the grid?

No major differences, but potentially some difference in the way it is reported in smart meter webportal. See #51 for more information

[DarwinsBuddy]

Also: Do I just copy my code to homeassistant/custom_components/wnsm for development?

tests go here please: https://github.com/DarwinsBuddy/WienerNetzeSmartmeter/tree/main/tests/it

there is already a test_api.py. For coverage you can look into the corresponding test.yaml workflow in .github/actions

[DarwinsBuddy]

Also: Do I just copy my code to homeassistant/custom_components/wnsm for development?

if you want to develop on it and fiddle around, I can recommend my set up:

I checked out homeassistant-core, set up a dev container in vscode there and symlinked this repository into homeassistant/custom_components/wnsm as you suggested ;)

[K1ngjulien]

there seems to be some issue with pytest-homeassistant-custom-component

python3 -m venv .venv
source .venv/bin/activate
pip install -r tests/requirements.txt

setup and pip install work just fine but when i run the tests (even just pytest alone without any parameters) i get the following output:

[~/code/WienerNetzeSmartmeter (venv:.venv) (main:1) (1)]:  pytest --cov=wnsm tests --cov-report html --cov-report xml --cov-report term
Traceback (most recent call last):
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/bin/pytest", line 8, in <module>
    sys.exit(console_main())
             ^^^^^^^^^^^^^^
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/_pytest/config/__init__.py", line 190, in console_main
    code = main()
           ^^^^^^
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/_pytest/config/__init__.py", line 148, in main
    config = _prepareconfig(args, plugins)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/_pytest/config/__init__.py", line 329, in _prepareconfig
    config = pluginmanager.hook.pytest_cmdline_parse(
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/pluggy/_hooks.py", line 265, in __call__
    return self._hookexec(self.name, self.get_hookimpls(), kwargs, firstresult)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/pluggy/_manager.py", line 80, in _hookexec
    return self._inner_hookexec(hook_name, methods, kwargs, firstresult)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/pluggy/_callers.py", line 55, in _multicall
    gen.send(outcome)
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/_pytest/helpconfig.py", line 103, in pytest_cmdline_parse
    config: Config = outcome.get_result()
                     ^^^^^^^^^^^^^^^^^^^^
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/pluggy/_result.py", line 60, in get_result
    raise ex[1].with_traceback(ex[2])
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/pluggy/_callers.py", line 39, in _multicall
    res = hook_impl.function(*args)
          ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/_pytest/config/__init__.py", line 1058, in pytest_cmdline_parse
    self.parse(args)
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/_pytest/config/__init__.py", line 1346, in parse
    self._preparse(args, addopts=addopts)
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/_pytest/config/__init__.py", line 1229, in _preparse
    self.pluginmanager.load_setuptools_entrypoints("pytest11")
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/pluggy/_manager.py", line 287, in load_setuptools_entrypoints
    plugin = ep.load()
             ^^^^^^^^^
  File "/usr/lib/python3.11/importlib/metadata/__init__.py", line 202, in load
    module = import_module(match.group('module'))
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1206, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1178, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1149, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 690, in _load_unlocked
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/_pytest/assertion/rewrite.py", line 168, in exec_module
    exec(co, module.__dict__)
  File "/home/julian/code/WienerNetzeSmartmeter/.venv/lib/python3.11/site-packages/pytest_homeassistant_custom_component/plugins.py", line 116, in <module>
    from .asyncio_legacy import legacy_coroutine
ModuleNotFoundError: No module named 'pytest_homeassistant_custom_component.asyncio_legacy'

looking in venv/lib/python3.11/site-packages/pytest-homeassistant-custom-component/ the file asyncio_legacy.py is indeed missing 🤔

I manually upgraded with pip install pytest-homeassistant-custom-component==0.13.28 and that seems to run pytest perfectly fine and the asyncio_legacy module can also be found in the site-package folder

Is this something you've encountered before? Might be worth a version bump in case the tests are just working because the have an old version cached 😅

[K1ngjulien]

I'd suggest switching to another service provider. Wien Energie is not giving you that, as they probably don't want to buy electricity from you. But there are other good options available for selling. Wiener Netze has to provide the infrastructure in this case, i.e. the smart meter.

yeah but the problem is, before we can switch to something like OeMAG, we need Wiener Netze to give us the damn zählpunktnummer :D