pysolarcloud 0.1.0__py3-none-any.whl

pysolarcloud/__init__.py

@@ -0,0 +1,140 @@
+"""A Python library to interact with Sungrow's iSolarCloud API."""
+
+from abc import ABC, abstractmethod
+from enum import StrEnum
+import logging
+import time
+
+from aiohttp import ClientResponse, ClientSession
+
+_LOGGER = logging.getLogger(__name__)
+
+class Server(StrEnum):
+    """Enum of iSolarCloud servers."""
+    China = "https://gateway.isolarcloud.com"
+    International = "https://gateway.isolarcloud.com.hk"
+    Europe = "https://gateway.isolarcloud.eu"
+    Australia = "https://augateway.isolarcloud.com"
+
+class AbstractAuth(ABC):
+    """Abstract class to make authenticated requests.
+    
+    Subclasses must implement the async_get_access_token method
+    and may call async_fetch_tokens and async_refresh_token.
+    """
+
+    def __init__(self, websession: ClientSession, server: Server | str, client_id: str, client_secret: str, app_id: str):
+        """Initialize the authorization session."""
+        self.websession = websession
+        self.host = server.value if isinstance(server, Server) else server
+        self.appkey = client_id
+        self.access_key = client_secret
+        self.app_id = app_id
+
+    def auth_url(self, redirect_uri: str) -> str:
+        """Return the URL to authorize the user."""
+        match self.host:
+            case Server.China.value:
+                cloud_id = 1
+            case Server.International.value:
+                cloud_id = 2
+            case Server.Europe.value:
+                cloud_id = 3
+            case Server.Australia.value:
+                cloud_id = 4
+        return f"https://web3.isolarcloud.eu/#/authorized-app?cloudId={cloud_id}&applicationId={self.app_id}&redirectUrl={redirect_uri}"
+
+    @abstractmethod
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token."""
+
+    async def request(self, path, data, *, lang="_en_US", **kwargs) -> ClientResponse:
+        """Make a request to iSolarCloud.
+        
+        Parameters:
+        path -- the path to request
+        data -- the data to send
+        lang -- the language to use (default "_en_US", supported languages are "_en_US", "_zh_CN", "_ja_JP", "_es_ES", "_de_DE", "_pt_BR", "_fr_FR", "_it_IT", "_ko_KR", "_nl_NL", "_pl_PL", "_vi_VN", "_zh_TW"
+        **kwargs -- additional arguments to pass to the request
+        """
+        if not path.startswith("/"):
+            path = f"/{path}"
+        if headers := kwargs.pop("headers", {}):
+            headers = dict(headers)
+        access_token = await self.async_get_access_token()
+        headers = {**headers, "x-access-key": self.access_key, "Authorization": f"Bearer {access_token}"}
+        body = {**data, "appkey": self.appkey, "lang": lang}
+        return await self.websession.request(
+            "post", f"{self.host}{path}", json=body, **kwargs, headers=headers,
+        )
+    
+    async def async_fetch_tokens(self, code, redirect_uri, **kwargs) -> ClientResponse:
+        """Fetch the access and refresh tokens."""
+        if headers := kwargs.pop("headers", {}):
+            headers = dict(headers)
+        headers = {**headers, "x-access-key": self.access_key, "Content-type": "application/json"}
+        body = {
+            "appkey": self.appkey, 
+            "code": code, 
+            "grant_type": "authorization_code",
+            "redirect_uri": redirect_uri
+        }
+        response = await self.websession.request("post", f"{self.host}/openapi/apiManage/token", json=body, headers=headers, **kwargs)
+        return await response.json()
+
+    async def async_refresh_tokens(self, refresh_token, **kwargs) -> ClientResponse:
+        """Refresh the access token."""
+        if headers := kwargs.pop("headers", {}):
+            headers = dict(headers)
+        headers = {**headers, "x-access-key": self.access_key}
+        body = {
+            "appkey": self.appkey, 
+            "refresh_token": refresh_token
+        }
+        response = await self.websession.request("post", f"{self.host}/openapi/apiManage/refreshToken", json=body, **kwargs, headers=headers)
+        return await response.json()
+    
+class Auth(AbstractAuth):
+    """Class to authenticate with the SolarCloud API."""
+
+    def __init__(self, host: str, appkey: str, access_key: str, app_id: str, *, websession: ClientSession = None):
+        """Initialize the auth."""
+        if websession is None:
+            websession = ClientSession(raise_for_status=True)
+        super().__init__(websession, host, appkey, access_key, app_id)
+        self.tokens = None
+
+    async def async_authorize(self, code, redirect_uri):
+        """Authorize the user."""
+        ts = await self.async_fetch_tokens(code, redirect_uri)
+        print(ts)
+        if "access_token" not in ts:
+            _LOGGER.error("Authorization failed: %s", str(ts))
+            return
+        self.tokens = {
+            "access_token": ts["access_token"],
+            "refresh_token": ts["refresh_token"],
+            "expires_at": int(time.time()) + ts["expires_in"] - 20,
+        }
+        _LOGGER.debug("Authorization succesful")
+
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token."""
+        if self.tokens is None:
+            raise PySolarCloudException({"error": "auth_not_initialised", "error_description": "You must authorize first."})
+        if self.tokens["expires_at"] < int(time.time()):
+            ts = await self.async_refresh_tokens(self.tokens["refresh_token"])
+            self.tokens = {
+                "access_token": ts["access_token"],
+                "refresh_token": ts["refresh_token"],
+                "expires_at": int(time.time()) + ts["expires_in"] - 20,
+            }
+        return self.tokens["access_token"]
+
+class PySolarCloudException(Exception):
+    """Exception class raised by PySolarCloud when communication with the iSolarCloud service fails."""
+    def __init__(self, err: dict):
+        super().__init__(err["error"])
+        self.error = err["error"]
+        self.error_description = err["error_description"]
+        self.req_serial_num = err.get("req_serial_num", None)

pysolarcloud/plants.py

@@ -0,0 +1,170 @@
+from . import AbstractAuth, PySolarCloudException, _LOGGER
+
+class Plants:
+    """Class to interact with the plants API."""
+
+    def __init__(self, auth: AbstractAuth, *, lang: str = "_en_US"):
+        """Initialize the plants."""
+        self.auth = auth
+        self.lang = lang
+
+    async def async_get_plants(self) -> list[dict]:
+        """Return the list of plants accessible to the user."""
+        uri = "/openapi/platform/queryPowerStationList"
+        res = await self.auth.request(uri, {"page": 1, "size": 100})
+        res.raise_for_status()
+        data = await res.json()
+        if "error" in data:
+            _LOGGER.error("Error response from %s: %s", uri, data)
+            raise PySolarCloudException(res)
+        plants = [plant for plant in data["result_data"]["pageList"]]
+        _LOGGER.debug("async_get_plants: %s", plants)
+        return plants
+
+    async def async_get_plant_details(self, plant_id: str | list[str]) -> list[dict]:
+        """Return details about one or more plants."""
+        if isinstance(plant_id, list):
+            ps = ",".join(plant_id)
+        else:
+            ps = plant_id
+        uri = "/openapi/platform/getPowerStationDetail"
+        res = await self.auth.request(uri, {"ps_ids": ps})
+        data = await res.json()
+        if "error" in data:
+            _LOGGER.error("Error response from %s: %s", uri, res)
+            raise PySolarCloudException(res)
+        plants = data["result_data"]["data_list"]
+        _LOGGER.debug("async_get_plant_details: %s", plants)
+        return plants
+
+    async def async_get_realtime_data(self, plant_id: str | list[str], *, measure_points=None) -> dict:
+        """Return the latest realtime data from one or more plants.
+        
+        plant_id: str | list[str] - The ID of the plant or a list of plant IDs.
+        measure_points: list[str] - A list of measure points to return. If None, all measure points are returned.
+        Data is returned as a dictionary of dictionaries:
+        {
+            plant_id: {
+                measure_point_code: {
+                    "id": str, # Numerical identifier of the measure point
+                    "code": str, # Readable code of the measure point (see measure_points dict)
+                    "value": float | str,
+                    "unit": str,
+                    "name": str, # Name of the measure point (in the specified language)
+                }
+            }
+        }
+        iSolarCloud data is updated every 5 minutes so polling more frequently than that is not useful.
+        """
+        if isinstance(plant_id, list):
+            ps = plant_id
+        else:
+            ps = [plant_id]
+        if measure_points is None:
+            ms = list(self.measure_points.keys())
+        else:
+            measure_points_map = {v: k for k, v in self.measure_points.items()}
+            ms = [m if m.isdigit() else measure_points_map[m] for m in measure_points]
+        uri = "/openapi/platform/getPowerStationRealTimeData"
+        res = await self.auth.request(uri, {"ps_id_list": ps, "point_id_list": ms, "is_get_point_dict": "1"}, lang=self.lang)
+        res = await res.json()
+        if "error" in res:
+            _LOGGER.error("Error response from %s: %s", uri, res)
+            raise PySolarCloudException(res)
+        point_dict = dict([(str(point["point_id"]), point) for point in res["result_data"]["point_dict"]])
+        plants = {}
+        for plant in res["result_data"]["device_point_list"]:
+            data = [self._format_measure_point(k[1:], v, point_dict) for k,v in plant.items() if k[0]=='p' and k[1:].isdigit()]
+            data_as_dict = {d["code"]: d for d in data}
+            plants[str(plant["ps_id"])] = data_as_dict
+        _LOGGER.debug("async_get_realtime_data: %s", plants)
+        return plants
+    
+    def _format_measure_point(self, point_id: str, point_value: str, point_dict: dict) -> dict:
+        try:
+            v = float(point_value) if point_value is not None else None
+        except ValueError:
+            v = point_value
+        return {
+            "id": point_id,
+            "code": self.measure_points.get(point_id, point_id),
+            "value": v,
+            "unit": point_dict.get(point_id, {}).get("point_unit", None),
+            "name": point_dict.get(point_id, {}).get("point_name", None),
+        }
+
+    measure_points = {
+        "83022": "daily_yield", # Wh
+        "83024": "total_yield", # Wh
+        "83033": "power", # W
+        "83019": "power_fraction", # Plant Power/Installed Power of Plant 
+        "83006": "meter_daily_yield", # Wh
+        "83020": "meter_total_yield", # Wh
+        "83011": "meter_e_daily_consumption", # Wh
+        "83021": "accumulative_power_consumption_by_meter", # Wh
+        "83032": "meter_ac_power", # W
+        "83007": "meter_pr", # 
+        "83002": "inverter_ac_power", # W
+        "83009": "inverter_daily_yield", # Wh
+        "83004": "inverter_total_yield", # Wh
+        "83012": "p_radiation_h", # W/㎡
+        "83013": "daily_irradiation", # Wh/㎡
+        "83023": "plant_pr", # 
+        "83005": "daily_equivalent_hours", # h
+        "83025": "plant_equivalent_hours", # h
+        "83018": "daily_yield_theoretical", # Wh
+        "83001": "inverter_ac_power_normalization", # W/Wp
+        "83008": "daily_equivalent_hours_of_inverter", # h
+        "83010": "inverter_pr", # 
+        "83016": "plant_ambient_temperature", # ℃
+        "83017": "plant_module_temperature", # ℃
+        "83046": "pcs_total_active_power", # W
+        "83052": "total_load_active_power", # W
+        "83067": "total_active_power_of_pv", # W
+        "83097": "daily_direct_energy_consumption", # Wh
+        "83100": "total_direct_energy_consumption", # Wh
+        "83102": "energy_purchased_today", # Wh
+        "83105": "total_purchased_energy", # Wh
+        "83106": "load_power", # W
+        "83118": "daily_load_consumption", # Wh
+        "83124": "total_load_consumption", # Wh
+        "83119": "daily_feed_in_energy_pv", # Wh
+        "83072": "feed_in_energy_today", # Wh
+        "83075": "feed_in_energy_total", # Wh
+        "83252": "battery_level_soc", # 
+        "83129": "battery_soc", # 
+        "83232": "total_field_soc", # 
+        "83233": "total_field_maximum_rechargeable_power", # W
+        "83234": "total_field_maximum_dischargeable_power", # W
+        "83235": "total_field_chargeable_energy", # Wh
+        "83236": "total_field_dischargeable_energy", # Wh
+        "83237": "total_field_energy_storage_maximum_reactive_power", # W
+        "83238": "total_field_energy_storage_active_power", # W
+        "83239": "total_field_reactive_power", # var
+        "83240": "total_field_power_factor", # 
+        "83243": "daily_field_charge_capacity", # Wh
+        "83241": "total_field_charge_capacity", # Wh
+        "83244": "daily_field_discharge_capacity", # Wh
+        "83242": "total_field_discharge_capacity", # Wh
+        "83548": "total_number_of_charge_discharge", # 
+        "83549": "grid_active_power", # W
+        "83419": "daily_highest_inverter_power_inverter_installed_capacity", # 
+        "83317": "power_forecast", # W
+        "83318": "planned_es_charging_discharging_power", # W
+        "83319": "planned_es_soc", # 
+        "83320": "planned_charging_power", # Wh
+        "83321": "planned_discharging_power", # Wh
+        "83322": "ess_daily_charge_ems", # Wh
+        "83324": "energy_storage_cumulative_charge", # Wh
+        "83323": "ess_daily_discharge_ems", # Wh
+        "83325": "cumulative_discharge", # Wh
+        "83327": "energy_storage_remaining_charge", # Wh
+        "83326": "energy_storage_active_power_ems", # W
+        "83328": "grid_active_power_ems", # W
+        "83329": "pv_active_power_ems", # W
+        "83330": "load_active_power_ems", # W
+        "83331": "daily_pv_yield_ems", # Wh
+        "83332": "total_pv_yield", # Wh
+        "83334": "energy_storage_soc_ems", # 
+        "83335": "energy_storage_remaining_charge_ems", # Wh
+    }

pysolarcloud-0.1.0.dist-info/LICENSE.txt

@@ -0,0 +1,18 @@
+Copyright 2025 Tore Green
+
+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.

pysolarcloud-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.2
+Name: pysolarcloud
+Version: 0.1.0
+Summary: A library to interact with Sungrow's iSolarCloud API
+Author-email: Tore Green <bugjam@e-dreams.dk>
+License: MIT
+Project-URL: Homepage, https://github.com/bugjam/pysolarcloud
+Project-URL: Issues, https://github.com/bugjam/pysolarcloud/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: aiohttp
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+
+# pysolarcloud
+
+A Python package to interact with the [iSolarCloud API](https://developer-api.isolarcloud.com/) by Sungrow.
+
+The current version has only very basic functionality:
+* OAuth2 authentication
+* Getting a list plants
+* Getting details of a plant
+* Getting "real-time" data of a plant (Data is updated every 5 minutes according to Sungrow's documentation)
+
+## Quirks
+The iSolarCloud API is quite new and not very mature. Some tips:
+* The authorisation flow is based on OAuth2 but doesn't work exactly as you would expect
+* The `state` parameter is not passed back after to the authorisation step. This makes it more tricky to resume the flow in a client application.
+* User is asked to approve the authorisation if the flow is invoked again, e.g. in case the tokens have expired - unlike many OAuth2 implementations who will perform a "silent" authorisation if the user has already approved the access.
+* The API documentation lists a lot of data points which do not seem to be returned from my inverter, it probably varies between models.
+* There are different iSolarCloud servers for different regions, see the `pysolarcloud.Server` enum
+* API endpoints accept a language code but respond with Chinese text when when English is requested
+
+# Usage
+
+## Installation
+
+```
+pip install pysolarcloud
+```
+
+## Register your app
+1. Create an account in the [iSolarCloud Developer Portal](https://developer-api.isolarcloud.com/)
+2. Create an app in the developer portal
+   * Answer "Yes" to authorize with OAuth2.0
+   * Enter a Redirect URL for your app (this can be changed later)
+3. Wait for approval by Sungrow
+4. Find the needed configuration details in the developer portal. You will need:
+   * Appkey
+   * Secret Key
+   * Application Id (This is shown as a query parameter within the Authorize URL in the developer portal)
+
+## Example
+
+```python
+from pysolarcloud import Auth, Server
+from pysolarcloud.plants import Plants
+
+app_key = "your app key"
+secret_key = "your secret key"
+app_id = "your app id"
+redirect_uri = "your redirect uri"
+
+auth = Auth(Server.Europe, app_key, secret_key, app_id)
+url = Auth.auth_url(redirect_uri)
+```
+1. Redirect user to `url`
+2. User selects plant(s) and grants authorisation
+3. iSolarCloud will redirect the user to `redirect_uri` with query parameter `code`
+```python
+await auth.async_authorize(code, redirect_uri)
+plants_api = Plants(auth)
+plant_list = await plants_api.async_get_plants()
+```
+
+The `Auth` class keeps the access between calls and refreshes it when needed. If you prefer to manage this state yourself, you can create your own subclass of `AbstractAuth`.
+
+# Contributions
+Ideas or contributions are welcome. I am not afiliated with Sungrow, I'm just another user of the API. My main use case will be a HomeAssistant integration based on this package.
+
+I don't currently have a need for the Grid Control APIs and I might not be able to test them on my own plant[^1] - but let me know if you are interested.
+
+[^1]: because it's controlled by [Heartbeat](https://1komma5.com/en/offer/energymanager-heartbeat/)
+
+Enjoy!

pysolarcloud-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pysolarcloud/__init__.py,sha256=OPACPbLOOayqH4ryv-88m28r64l9scHbat4t6dV8mZ4,6031
+pysolarcloud/plants.py,sha256=xK5_zere9SnqcAvSq_2mae5pUdmeNJEyh8A-CssH7cs,7948
+pysolarcloud-0.1.0.dist-info/LICENSE.txt,sha256=Vma6PIRPNDEelPJFEff5lxpxlQBdIv_9eeFlMK1Cc4Q,1068
+pysolarcloud-0.1.0.dist-info/METADATA,sha256=38VVx42vzAwACaPTZEVD8QgzvVAQy2AcKYu2GIE8RAM,3833
+pysolarcloud-0.1.0.dist-info/WHEEL,sha256=EaM1zKIUYa7rQnxGiOCGhzJABRwy4WO57rWMR3_tj4I,91
+pysolarcloud-0.1.0.dist-info/top_level.txt,sha256=JsfYsG6nh4vbllpPiUNEVFOALTD6WDEFQBMM2xdzLWU,13
+pysolarcloud-0.1.0.dist-info/RECORD,,

pysolarcloud-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.9.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pysolarcloud-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pysolarcloud