pysunsynkweb 0.0.2__py3-none-any.whl

pysunsynkweb/__about__.py

@@ -0,0 +1,6 @@
+"""The about file for version control"""
+
+# SPDX-FileCopyrightText: 2024-present Francois <f@flve.uk>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.0.2"

pysunsynkweb/__init__.py

@@ -0,0 +1,4 @@
+"""A package that wraps the Sunsynk web api (https://sunsynk.net)"""
+# SPDX-FileCopyrightText: 2024-present Francois <f@flve.uk>
+#
+# SPDX-License-Identifier: MIT

pysunsynkweb/battery.py

@@ -0,0 +1,6 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Battery:
+    id: int

pysunsynkweb/const.py

@@ -0,0 +1,10 @@
+"""Constants for pysunsynkweb."""
+
+BASE_URL = "https://api.sunsynk.net"
+BASE_API = BASE_URL + "/api/v1"
+BASE_HEADERS = {
+    "accept": "application/json",
+    "content-type": "application/json",
+    "accept-language": "en-US,en;q=0.5",
+    "accept-encoding": "gzip, deflate, br",
+}

pysunsynkweb/exceptions.py

@@ -0,0 +1,5 @@
+"""Exceptions module"""
+
+
+class AuthenticationFailed(Exception):
+    """Raised when authentication failed"""

pysunsynkweb/inverter.py

@@ -0,0 +1,72 @@
+from dataclasses import dataclass, field
+import decimal
+from typing import Union
+
+from pysunsynkweb.const import BASE_API
+from pysunsynkweb.pvstring import PVString
+from pysunsynkweb.session import SunsynkwebSession
+
+
+@dataclass
+class Inverter:
+    sn: int
+    session: Union[SunsynkwebSession, None] = None
+    acc_pv: decimal.Decimal = decimal.Decimal(0)
+    acc_grid_export: decimal.Decimal = decimal.Decimal(0)
+    acc_grid_import: decimal.Decimal = decimal.Decimal(0)
+    acc_battery_discharge: decimal.Decimal = decimal.Decimal(0)
+    acc_battery_charge: decimal.Decimal = decimal.Decimal(0)
+    acc_load: decimal.Decimal = decimal.Decimal(0)
+    pv_strings: dict = field(default_factory=dict)
+
+    async def _get_total_grid(self):
+        returned = await self.session.get(
+            BASE_API + f"/inverter/grid/{self.sn}/realtime",
+            params={"lan": "en"},
+        )
+        self.acc_grid_export = decimal.Decimal(returned["data"]["etotalTo"])
+        self.acc_grid_import = decimal.Decimal(returned["data"]["etotalFrom"])
+
+    async def _get_total_battery(self):
+        returned = await self.session.get(
+            BASE_API + f"/inverter/battery/{self.sn}/realtime",
+            params={"lan": "en"},
+        )
+        self.acc_battery_charge = decimal.Decimal(returned["data"]["etotalChg"])
+        self.acc_battery_discharge = decimal.Decimal(returned["data"]["etotalDischg"])
+
+    async def _get_total_pv(self):
+        returned = await self.session.get(
+            BASE_API + f"/inverter/{self.sn}/total",
+            params={"lan": "en"},
+        )
+        self.acc_pv = sum(
+            [
+                decimal.Decimal(i["value"])
+                for i in returned["data"]["infos"][0]["records"]
+            ]
+        )
+
+    async def _get_total_load(self):
+        returned = await self.session.get(
+            BASE_API + f"/inverter/load/{self.sn}/realtime",
+            params={"lan": "en"},
+        )
+        self.acc_load = decimal.Decimal(returned["data"]["totalUsed"])
+
+    async def _update_strings(self):
+        returned = await self.session.get(
+            BASE_API + f"/inverter/{self.sn}/realtime/input"
+        )
+        strings_raw = returned["data"]["pvIV"]
+        for string in strings_raw:
+            self.pv_strings.setdefault(
+                string["pvNo"], PVString(id=string["pvNo"])
+            ).update_from_inv(string)
+
+    async def update(self):
+        await self._get_total_pv()
+        await self._get_total_grid()
+        await self._get_total_battery()
+        await self._get_total_load()
+        await self._update_strings()

pysunsynkweb/model.py

@@ -0,0 +1,172 @@
+"""Top level data model for the sunsynk web api."""
+
+from dataclasses import dataclass, field
+import decimal
+import logging
+import pprint
+from typing import List, Union
+
+from pysunsynkweb.inverter import Inverter
+
+from .const import BASE_API
+from .session import SunsynkwebSession
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class Plant:
+    """Proxy for the 'Plant' object in sunsynk web api.
+
+    A plant can host multiple inverters and other devices. Our plant object
+    carries a summary of the data from all inverters in the plant.
+
+    In the limited sample i've got, there is one plant per inverter.
+
+    """
+
+    id: int
+    master_id: int
+    name: str
+    status: int
+    battery_power: int = 0
+    state_of_charge: float = 0
+    load_power: int = 0
+    grid_power: int = 0
+    pv_power: int = 0
+    session: Union[SunsynkwebSession, None] = None
+    inverters: List[Inverter] = field(default_factory=list)
+
+    def __repr__(self):
+        """Summary of the plant"""
+        return f"""Plant {id}
+
+        {self.name}
+        Battery power {self.battery_power} W ({self.state_of_charge})%
+        Grid Power: {self.grid_power} W
+        PV Power: {self.pv_power} W
+        Accumulated PV Energy {self.acc_pv} KWh
+        Accumulated Grid export {self.acc_grid_export} KWh
+        Accumulated Grid import {self.acc_grid_import} KWh
+        Accumulated Load {self.acc_load} KWh
+        Accumulated Battery discharge {self.acc_battery_discharge} KWh
+        Accumulated Battery charge {self.acc_battery_charge} KWh
+
+        """
+
+    def ismaster(self):
+        """Is the plant a master plant.
+
+         Unused at the moment, but required when introducing read-write calls
+        (for instance to command to charge batteries from the grid).
+        """
+        return self.master_id == self.id
+
+    @classmethod
+    def from_api(cls, api_return, session):
+        """Create the plant from the return of the web api."""
+        return cls(
+            name=api_return["name"],
+            id=api_return["id"],
+            master_id=api_return["masterId"],
+            status=api_return["status"],
+            session=session,
+        )
+
+    async def enrich_inverters(self):
+        """Populate inverters' serial numbers.
+
+        The plant summary doesn't contain the inverters, so we have a
+        separate call to populate inverter's serial numbers.
+        """
+        returned = await self.session.get(
+            BASE_API + f"/plant/{self.id}/inverters",
+            params={"page": 1, "limit": 20, "type": -1, "status": -1},
+        )
+        self.inverters = [
+            Inverter(k["sn"], session=self.session) for k in returned["data"]["infos"]
+        ]
+
+    async def _get_instantaneous_data(self):
+        """Populate instantaneous data.
+
+        Instantaneous data is conveniently summarized in the 'flow' api end point.
+        """
+        returned = await self.session.get(
+            BASE_API + f"/plant/energy/{self.id}/flow",
+            params={"page": 1, "limit": 20},
+        )
+        _LOGGER.debug("Flow Api returned %s", pprint.pformat(returned))
+
+        self.battery_power = returned["data"]["battPower"]
+        if returned["data"]["toBat"]:
+            self.battery_power *= -1
+        self.state_of_charge = returned["data"]["soc"]
+        self.load_power = returned["data"]["loadOrEpsPower"]
+        self.grid_power = returned["data"]["gridOrMeterPower"]
+        if returned["data"]["toGrid"]:
+            self.grid_power *= -1
+        self.pv_power = returned["data"]["pvPower"]
+
+    async def update(self):
+        """Update all sensors."""
+        await self._get_instantaneous_data()
+        for inverter in self.inverters:
+            await inverter.update()
+
+    @property
+    def acc_pv(self):
+        return sum(i.acc_pv for i in self.inverters)
+
+    @property
+    def acc_grid_export(self):
+        return max(i.acc_grid_export for i in self.inverters)
+
+    @property
+    def acc_grid_import(self):
+        return max(i.acc_grid_import for i in self.inverters)
+
+    @property
+    def acc_battery_discharge(self):
+        return sum(i.acc_battery_discharge for i in self.inverters)
+
+    @property
+    def acc_battery_charge(self):
+        return sum(i.acc_battery_charge for i in self.inverters)
+
+    @property
+    def acc_load(self):
+        return sum(i.acc_load for i in self.inverters)
+
+
+@dataclass
+class Installation:
+    """An installation is a series of plants.
+
+    This integration presents the plants as a single entity.
+    """
+
+    plants: List[Plant]
+
+    @classmethod
+    def from_api(cls, api_return, session):
+        """Create the installation from the sunsynk web api."""
+        assert "data" in api_return
+        assert api_return["msg"] == "Success"
+        return cls(
+            plants=[Plant.from_api(ret, session) for ret in api_return["data"]["infos"]]
+        )
+
+    async def update(self):
+        """Update all the plants. They will in turn update their sensors."""
+        for plant in self.plants:
+            await plant.update()
+
+
+async def get_plants(session: SunsynkwebSession):
+    """Start walking the plant composition."""
+    returned = await session.get(BASE_API + "/plants", params={"page": 1, "limit": 20})
+    installation = Installation.from_api(returned, session)
+    for plant in installation.plants:
+        await plant.enrich_inverters()
+    return installation

pysunsynkweb/pvstring.py

@@ -0,0 +1,41 @@
+from dataclasses import dataclass
+import datetime
+import decimal
+
+
+@dataclass
+class PVString:
+    """A PV 'string'.
+
+    PV 'strings' are cables from a set of solar panels. Typically, your
+    installer will group the panels on string based on common orientation
+    or exposure to the sun.
+
+    """
+
+    id: int
+    voltage: decimal.Decimal = decimal.Decimal(0)
+    power: decimal.Decimal = decimal.Decimal(0)
+    amperage: decimal.Decimal = decimal.Decimal(0)
+    last_update: datetime.datetime = None
+
+    def update_from_inv(self, data):
+        """Update from invertor 'input' request.
+
+                ```
+                {
+                        "id": null,
+                        "pvNo": 1,
+                        "vpv": "212.9",
+                        "ipv": "1.0",
+                        "ppv": "222.0",
+                        "todayPv": "0.0",
+                        "sn": "2211166856",
+                        "time": "2024-06-13 07:54:05"
+                    },
+        ```
+        """
+        self.last_update = datetime.datetime.strptime(data["time"], "%Y-%m-%d %H:%M:%S")
+        self.power = decimal.Decimal(data["ppv"])
+        self.voltage = decimal.Decimal(data["vpv"])
+        self.amperage = decimal.Decimal(data["ipv"])

pysunsynkweb/session.py

@@ -0,0 +1,77 @@
+"""A session object
+
+Maintaining the authentication with the sunsynk api and
+wrapping repetitive things
+"""
+
+import logging
+import pprint
+
+import aiohttp
+
+from .const import BASE_HEADERS, BASE_URL
+from .exceptions import AuthenticationFailed
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class SunsynkwebSession:
+    """the main entry point to sunsynk api.
+
+    Maintains http headers,
+    authentication token, etc.
+    """
+
+    def __init__(self, session: aiohttp.ClientSession, username: str, password: str) -> None:
+        """Pass an aiohttp client session and authentication items"""
+        self.session = session
+        self.bearer = None
+        self.username = username
+        self.password = password
+
+    async def get(self, *args, **kwargs):
+        """Run a GET query against the sunsynk api"""
+        if self.bearer is None:
+            await self._get_bearer_token()
+        headers = BASE_HEADERS.copy()
+        headers.update({"Authorization": f"Bearer{self.bearer}"})
+        kwargs["headers"] = headers
+        result = await self.session.get(*args, **kwargs)
+        result = await result.json()
+        if result.get("msg") != "Success" and result.get("code") == 401:
+            # expired token
+            await self._get_bearer_token()
+            result = await self.get(*args, **kwargs)
+        return result
+
+    async def _get_bearer_token(self):
+        """Get the bearer token for the sunsynk api."""
+        params = {
+            "username": self.username,
+            "password": self.password,
+            "grant_type": "password",
+            "client_id": "csp-web",
+            "source": "sunsynk",
+            "areaCode": "sunsynk",
+        }
+        returned = await self.session.post(BASE_URL + "/oauth/token", json=params, headers=BASE_HEADERS)
+
+        returned = await returned.json()
+        _LOGGER.debug("authentication attempt returned %s", pprint.pformat(returned))
+        # returned data looks like the below
+        # {
+        #     "code": 0,
+        #     "msg": "Success",
+        #     "data": {
+        #         "access_token": "VALUE",
+        #         "token_type": "bearer",
+        #         "refresh_token": "VALUE",
+        #         "expires_in": 604799,
+        #         "scope": "all",
+        #     },
+        #     "success": True,
+        # }
+        try:
+            self.bearer = returned["data"]["access_token"]
+        except KeyError as exc:
+            raise AuthenticationFailed from exc

pysunsynkweb-0.0.2.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.3
+Name: pysunsynkweb
+Version: 0.0.2
+Project-URL: Documentation, https://github.com/francoisverbeek/pysunsynkweb
+Project-URL: Issues, https://github.com/francoisverbeek/pysunsynkweb/issues
+Project-URL: Source, https://github.com/francoisverbeek/pysunsynkweb
+Author-email: Francois <f@flve.uk>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.8
+Requires-Dist: aiohttp
+Description-Content-Type: text/markdown
+
+# Sunsynk Web
+
+[![PyPI - Version](https://img.shields.io/pypi/v/pysunsynkweb.svg)](https://pypi.org/project/pysunsynkweb)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pysunsynkweb.svg)](https://pypi.org/project/pysunsynkweb)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [License](#license)
+
+## Installation
+
+```console
+pip install pysunsynkweb
+```
+
+## License
+
+`pysunsynkweb` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

pysunsynkweb-0.0.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+pysunsynkweb/__about__.py,sha256=Iug5BLKo1Q_htAJ3DfAWjoemeuWjZ-BTsD9zs-if9J4,157
+pysunsynkweb/__init__.py,sha256=W-7fTovQ_YrLkagXsWhaSSMdEbmaNHMU72Hmi2ul8jI,162
+pysunsynkweb/battery.py,sha256=MRF4vtUxOuaJrsiEi4761FqtNE8a1Y038dAkV9VpZPo,74
+pysunsynkweb/const.py,sha256=N2PnrEETMhNF6k2vqxzqDlmA9BKyfOSPA2VFsXMAu08,282
+pysunsynkweb/exceptions.py,sha256=3XiZihDBmFM6aCV3MAl3sC3D8XsajL382ah7EAiwe3M,109
+pysunsynkweb/inverter.py,sha256=JeTTylP2R41XU07E2u6OkoKeyAHDlFxb6BiHlqY4FW0,2596
+pysunsynkweb/model.py,sha256=qIwcJ_VSjx7CY3XSAO3tqFIStO5vsEfFcIGPeEnORU0,5370
+pysunsynkweb/pvstring.py,sha256=hJEofwkxqc3EOxvsQMpGdCT5QUgtjISKDCN-fLyEVP4,1250
+pysunsynkweb/session.py,sha256=OP81Kyl1AnnP-8h3x4-mhGORRa4D4BrAu8HfVwv-QjY,2465
+pysunsynkweb-0.0.2.dist-info/METADATA,sha256=SEUl3CuWhCsfCW2PCYk4HGbFSwusLZDw0mNb3bCsHow,1433
+pysunsynkweb-0.0.2.dist-info/WHEEL,sha256=zEMcRr9Kr03x1ozGwg5v9NQBKn3kndp6LSoSlVg-jhU,87
+pysunsynkweb-0.0.2.dist-info/licenses/LICENSE.txt,sha256=FlpRiuOvoN51zmppyHedCkDPsMo1ZB3PYxd-mV8X7t0,1085
+pysunsynkweb-0.0.2.dist-info/RECORD,,

pysunsynkweb-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.24.2
+Root-Is-Purelib: true
+Tag: py3-none-any

pysunsynkweb-0.0.2.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024-present Francois <f@flve.uk>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.