sungrow-isolarcloud 0.5.0__tar.gz

sungrow_isolarcloud-0.5.0/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.

sungrow_isolarcloud-0.5.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+exclude tests/*

sungrow_isolarcloud-0.5.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: sungrow-isolarcloud
+Version: 0.5.0
+Summary: A library to interact with Sungrow's iSolarCloud API (KRoperUK fork with battery, EV charger and dispatch extensions)
+Author: KRoperUK
+Author-email: Tore Green <bugjam@e-dreams.dk>
+License: MIT
+Project-URL: Homepage, https://github.com/KRoperUK/pysolarcloud
+Project-URL: Issues, https://github.com/KRoperUK/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: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+
+# sungrow-isolarcloud
+
+A maintained fork of the [pysolarcloud](https://github.com/bugjam/pysolarcloud) library for interacting with Sungrow's [iSolarCloud API](https://developer-api.isolarcloud.com/).
+
+Install from PyPI:
+
+```
+pip install sungrow-isolarcloud
+```
+
+This fork adds:
+* Support for requesting **additional / custom measure points** without modifying the upstream point map (useful for battery charge/discharge power fields that vary by inverter model).
+* A best-effort **per-device realtime** helper for devices such as EV chargers (`Plants.async_get_device_realtime`).
+* A **heartbeat** helper for External EMS dispatch mode (`Control.async_heartbeat` / `Control.heartbeat_loop`).
+* Convenience constants for dispatch command value sets (`Control.CHARGE_DISCHARGE_COMMANDS`, `Control.FORCED_CHARGING`).
+
+The package supports the following functionality:
+* OAuth2 authentication
+* Getting a list plants
+* Getting details of a plant
+* Getting devices of a plant
+* Getting "real-time" data of a plant (Data is updated every 5 minutes according to Sungrow's documentation)
+* Getting historical data
+* Getting and updating grid control settings
+
+## 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
+
+## 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()
+if plant_list:
+   print(f"{len(plant_list)} plants found:")
+   for plant in plant_list:
+         print(f"Plant ID: {plant["ps_id"]}, Name: {plant["ps_name"]}")
+else:
+   print("No plants found.")
+   return
+
+print("\nFetching detailed information for each plant...\n")
+plant_ids = [str(plant["ps_id"]) for plant in plant_list]
+plant_details = await plants_api.async_get_plant_details(plant_ids)
+for plant in plant_details:
+   print(f"Details for Plant ID {plant["ps_id"]}: {plant}")
+
+print("\nFetching real-time data for each plant...\n")
+real_time_data = await plants_api.async_get_realtime_data(plant_ids)
+for plant_id, data in real_time_data.items():
+   # Print only the data points where value is not None
+   data_values = {k: v for k, v in data.items() if v and v.get("value") is not None}
+   print(f"Real-time data for Plant ID {plant_id}: {data_values}")
+```
+
+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`.
+
+## Grid Control
+
+The `Control` class enables retrieving and updating grid control settings. Parameters and value sets are documented in the iSolarCloud Developer portal.
+
+### Example
+
+```python
+from pysolarcloud.control import Control
+from pysolarcloud.plants import DeviceType
+
+devices = await plants_api.async_get_plant_devices(plant_id, device_types=[DeviceType.ENERGY_STORAGE_SYSTEM])
+device_uuid = devices[0]["uuid"]
+control_api = Control(auth)
+# Fetch current config
+current_settings = await control_api.async_read_parameters(device_uuid)
+print(current_settings)
+# Make an update using the canonical command values
+await control_api.async_update_parameters(
+    device_uuid,
+    {
+        "charge_discharge_command": Control.CHARGE_DISCHARGE_COMMANDS["charge"],
+        "charge_discharge_power": "2500",
+    },
+)
+
+# When using External EMS mode, send a heartbeat periodically to keep the inverter in dispatch mode.
+# 10017 = external_ems_heartbeat, value is the heartbeat interval in seconds (1-1000).
+await control_api.async_heartbeat(device_uuid, interval_seconds=60)
+```
+
+# 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.
+
+Enjoy!

sungrow_isolarcloud-0.5.0/README.md

@@ -0,0 +1,126 @@
+# sungrow-isolarcloud
+
+A maintained fork of the [pysolarcloud](https://github.com/bugjam/pysolarcloud) library for interacting with Sungrow's [iSolarCloud API](https://developer-api.isolarcloud.com/).
+
+Install from PyPI:
+
+```
+pip install sungrow-isolarcloud
+```
+
+This fork adds:
+* Support for requesting **additional / custom measure points** without modifying the upstream point map (useful for battery charge/discharge power fields that vary by inverter model).
+* A best-effort **per-device realtime** helper for devices such as EV chargers (`Plants.async_get_device_realtime`).
+* A **heartbeat** helper for External EMS dispatch mode (`Control.async_heartbeat` / `Control.heartbeat_loop`).
+* Convenience constants for dispatch command value sets (`Control.CHARGE_DISCHARGE_COMMANDS`, `Control.FORCED_CHARGING`).
+
+The package supports the following functionality:
+* OAuth2 authentication
+* Getting a list plants
+* Getting details of a plant
+* Getting devices of a plant
+* Getting "real-time" data of a plant (Data is updated every 5 minutes according to Sungrow's documentation)
+* Getting historical data
+* Getting and updating grid control settings
+
+## 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
+
+## 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()
+if plant_list:
+   print(f"{len(plant_list)} plants found:")
+   for plant in plant_list:
+         print(f"Plant ID: {plant["ps_id"]}, Name: {plant["ps_name"]}")
+else:
+   print("No plants found.")
+   return
+
+print("\nFetching detailed information for each plant...\n")
+plant_ids = [str(plant["ps_id"]) for plant in plant_list]
+plant_details = await plants_api.async_get_plant_details(plant_ids)
+for plant in plant_details:
+   print(f"Details for Plant ID {plant["ps_id"]}: {plant}")
+
+print("\nFetching real-time data for each plant...\n")
+real_time_data = await plants_api.async_get_realtime_data(plant_ids)
+for plant_id, data in real_time_data.items():
+   # Print only the data points where value is not None
+   data_values = {k: v for k, v in data.items() if v and v.get("value") is not None}
+   print(f"Real-time data for Plant ID {plant_id}: {data_values}")
+```
+
+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`.
+
+## Grid Control
+
+The `Control` class enables retrieving and updating grid control settings. Parameters and value sets are documented in the iSolarCloud Developer portal.
+
+### Example
+
+```python
+from pysolarcloud.control import Control
+from pysolarcloud.plants import DeviceType
+
+devices = await plants_api.async_get_plant_devices(plant_id, device_types=[DeviceType.ENERGY_STORAGE_SYSTEM])
+device_uuid = devices[0]["uuid"]
+control_api = Control(auth)
+# Fetch current config
+current_settings = await control_api.async_read_parameters(device_uuid)
+print(current_settings)
+# Make an update using the canonical command values
+await control_api.async_update_parameters(
+    device_uuid,
+    {
+        "charge_discharge_command": Control.CHARGE_DISCHARGE_COMMANDS["charge"],
+        "charge_discharge_power": "2500",
+    },
+)
+
+# When using External EMS mode, send a heartbeat periodically to keep the inverter in dispatch mode.
+# 10017 = external_ems_heartbeat, value is the heartbeat interval in seconds (1-1000).
+await control_api.async_heartbeat(device_uuid, interval_seconds=60)
+```
+
+# 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.
+
+Enjoy!

sungrow_isolarcloud-0.5.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "sungrow-isolarcloud"
+version = "0.5.0"
+authors = [
+  { name="Tore Green", email="bugjam@e-dreams.dk" },
+  { name="KRoperUK" },
+]
+description = "A library to interact with Sungrow's iSolarCloud API (KRoperUK fork with battery, EV charger and dispatch extensions)"
+readme = "README.md"
+requires-python = ">=3.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Framework :: AsyncIO",
+    "Topic :: Home Automation",
+]
+license = { text = "MIT" }
+dynamic = [ 
+    "dependencies",
+    "optional-dependencies"
+]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project.urls]
+Homepage = "https://github.com/KRoperUK/pysolarcloud"
+Issues = "https://github.com/KRoperUK/pysolarcloud/issues"

sungrow_isolarcloud-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sungrow_isolarcloud-0.5.0/setup.py

@@ -0,0 +1,28 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="pysolarcloud",
+    version="0.1.0",
+    packages=find_packages(where="src"),
+    package_dir={"": "src"},
+    install_requires=[
+        "aiohttp",
+    ],
+    extras_require={
+        "dev": [
+            "pytest",
+            "pytest-asyncio",
+        ],
+    },
+    entry_points={
+        "console_scripts": [
+            # Add any command-line scripts here
+        ],
+    },
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.7",
+)

sungrow_isolarcloud-0.5.0/src/pysolarcloud/__init__.py

@@ -0,0 +1,151 @@
+"""A Python library to interact with Sungrow's iSolarCloud API."""
+
+from abc import ABC, abstractmethod
+from enum import StrEnum
+import logging
+import time
+from urllib.parse import quote_plus
+
+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_tokens.
+    """
+
+    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:
+                auth_server = "web3.isolarcloud.com"
+                cloud_id = 1
+            case Server.International.value:
+                auth_server = "web3.isolarcloud.com.hk"
+                cloud_id = 2
+            case Server.Europe.value:
+                auth_server = "web3.isolarcloud.eu"
+                cloud_id = 3
+            case Server.Australia.value:
+                auth_server = "auweb3.isolarcloud.com"
+                cloud_id = 7
+        return f"https://{auth_server}/#/authorized-app?cloudId={cloud_id}&applicationId={self.app_id}&redirectUrl={quote_plus(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|str):
+        if isinstance(err, dict):
+            super().__init__(err["error"])
+            self.error = err["error"]
+            self.error_description = err.get("error_description")
+            self.req_serial_num = err.get("req_serial_num", None)
+        else:
+            super().__init__(err)
+            self.error = err
+            self.error_description = None
+            self.req_serial_num = None

sungrow_isolarcloud-0.5.0/src/pysolarcloud/control.py

@@ -0,0 +1,236 @@
+import asyncio
+from datetime import datetime
+from . import AbstractAuth, PySolarCloudException, _LOGGER
+
+class Control:
+    """Class to interact with the Grid Control API."""
+    def __init__(self, auth: AbstractAuth, *, lang: str = "_en_US"):
+        """Initialize the control API."""
+        self.auth = auth
+
+    async def async_param_config_verification(self, device_uuid: str, set_type: int) -> bool:
+        """Verifies whether the device supports parameter configuration."""
+        uri = "/openapi/platform/paramSettingCheck"
+        res = await self.auth.request(uri, {"set_type": set_type, "uuid": str(device_uuid)})
+        res.raise_for_status()
+        data = await res.json()
+        _LOGGER.debug("async_param_config_verification: %s", data)
+        if data.get("result_code") == "1" and data["result_data"]["check_result"] == "1":
+            supported = data["result_data"]["dev_result_list"][0]["check_result"]
+            if supported == "1":
+                return True
+            else:
+                return False
+        raise PySolarCloudException(f"Could not check support for device {device_uuid} set_type {set_type}: {data}")
+
+    async def async_check_read_support(self, device_uuid: str) -> bool:
+        """Check if the device supports read operations."""
+        return await self.async_param_config_verification(device_uuid, 2)
+
+    async def async_check_update_support(self, device_uuid: str) -> bool:
+        """Check if the device supports read operations."""
+        return await self.async_param_config_verification(device_uuid, 0)
+
+    async def wait_for_task(self, device_uuid: str, task_id: str) -> dict:
+        """Poll for the task to be completed."""
+        uri = "/openapi/platform/getParamSettingTask"
+        params = {
+            "task_id": str(task_id),
+            "uuid": str(device_uuid),
+        }
+        await asyncio.sleep(2)
+        while True:
+            res = await self.auth.request(uri, params)
+            res.raise_for_status()
+            data = await res.json()
+            _LOGGER.debug("wait_for_task: %s", data)
+            if data.get("result_code") == "1" and data["result_data"]["command_status"] == 2:
+                # Task is still running
+                await asyncio.sleep(5)
+                continue
+            elif data.get("result_code") == "1" and data["result_data"]["command_status"] == 8:
+                return data["result_data"]["param_list"]
+            else:
+                _LOGGER.error("Task not successful %s: %s", task_id, data)
+                raise PySolarCloudException(f"Task not succesful {task_id}: {data}")
+
+    async def async_read_parameters(self, device_uuid: str, param_list : list[str]|None = None) -> dict:
+        """Read the parameters from the device."""
+        uri = "/openapi/platform/paramSetting"
+        if param_list is None:
+            ps = self.config_parameters.keys()
+        else:
+            param_map = {v: k for k, v in self.config_parameters.items()}
+            ps = [param_map.get(p,p) for p in param_list]
+        _LOGGER.debug("async_read_parameters: param_list=%s", ps)
+        plist = [ { "param_code": p, "set_value": "" } for p in ps ]
+        params = {
+            "set_type": 2,
+            "uuid": str(device_uuid),
+            "task_name": f"Readback {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+            "expire_second": 120,
+            "param_list": plist,
+        }
+        res = await self.auth.request(uri, params)
+        res.raise_for_status()
+        data = await res.json()
+        _LOGGER.debug("async_read_parameters: %s", data)
+        if data.get("result_code") == "1" and data["result_data"]["check_result"] == "1" \
+                and data["result_data"]["dev_result_list"][0]["code"] == "1":
+            task_id = data["result_data"]["dev_result_list"][0]["task_id"]
+            results = await self.wait_for_task(device_uuid, task_id)
+            return [self._format_param_readout(param, param["return_value"]) for param in results]
+        raise PySolarCloudException(f"Could not read parameters from device {device_uuid}: {data}")
+
+    async def async_update_parameters(self, device_uuid: str, param_values : dict) -> dict:
+        """Update parameters to the device."""
+        uri = "/openapi/platform/paramSetting"
+        param_codes = {v: k for k, v in self.config_parameters.items()}
+        plist = [ { "param_code": param_codes.get(str(p),str(p)), "set_value": str(v) } for p,v in param_values.items() ]
+        _LOGGER.debug("async_update_parameters: param_valuest=%s", plist)
+        params = {
+            "set_type": 0,
+            "uuid": str(device_uuid),
+            "task_name": f"Update {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+            "expire_second": 120,
+            "param_list": plist,
+        }
+        res = await self.auth.request(uri, params)
+        res.raise_for_status()
+        data = await res.json()
+        _LOGGER.debug("async_update_parameters: %s", data)
+        if data.get("result_code") == "1" and data["result_data"]["check_result"] == "1" \
+                and data["result_data"]["dev_result_list"][0]["code"] == "1":
+            task_id = data["result_data"]["dev_result_list"][0]["task_id"]
+            results = await self.wait_for_task(device_uuid, task_id)
+            return [self._format_param_readout(param, param["set_value"]) for param in results]
+        raise PySolarCloudException(f"Could not update parameters of device {device_uuid}: {data}")
+
+    async def async_heartbeat(self, device_uuid: str, interval_seconds: int) -> None:
+        """Send a single External EMS heartbeat (param 10017) and return.
+
+        The iSolarCloud API expects the heartbeat value to be the polling interval itself
+        (1-1000 seconds, see Appendix 10 of the developer portal). When the EMS stops sending
+        heartbeats the inverter reverts to its default mode.
+
+        For a long-running heartbeat use :meth:`heartbeat_loop` instead.
+        """
+        if not 1 <= interval_seconds <= 1000:
+            raise ValueError("heartbeat interval must be between 1 and 1000 seconds")
+        await self.async_update_parameters(device_uuid, {"external_ems_heartbeat": str(interval_seconds)})
+
+    async def heartbeat_loop(self, device_uuid: str, interval_seconds: int, stop_event: asyncio.Event) -> None:
+        """Continuously send External EMS heartbeats until *stop_event* is set.
+
+        Each heartbeat refreshes param 10017 to *interval_seconds*. Sleeps
+        ``interval_seconds`` between heartbeats so the inverter never times out.
+        """
+        if not 1 <= interval_seconds <= 1000:
+            raise ValueError("heartbeat interval must be between 1 and 1000 seconds")
+        while not stop_event.is_set():
+            try:
+                await self.async_heartbeat(device_uuid, interval_seconds)
+            except PySolarCloudException as err:
+                _LOGGER.warning("EMS heartbeat failed for %s: %s", device_uuid, err)
+            try:
+                await asyncio.wait_for(stop_event.wait(), timeout=interval_seconds)
+            except asyncio.TimeoutError:
+                continue
+            return
+
+    def _format_param_readout(self, param: str, value: str) -> dict:
+        """Format the parameter response."""
+        readout = {
+            "id": param["param_code"],
+            "code": self.config_parameters.get(param["param_code"], param["param_code"]),
+            "name": param["point_name"],
+            "value": value,
+            "unit": param.get("unit", ""),
+            "precision": param.get("set_precision", None),
+        }
+        if param.get("set_val_name"):
+            value_set_names = param["set_val_name"].split("|")
+            value_set_values = param["set_val_name_val"].split("|")
+            if value in value_set_values:
+                readout["value"] = value_set_names[value_set_values.index(value)]
+                readout["value_set"] = dict(zip(value_set_names, value_set_values))
+        else:
+            try:
+                readout["value"] = float(value)
+            except ValueError:
+                pass
+        return readout
+
+    # Canonical name -> on-the-wire value for the `charge_discharge_command` parameter
+    # (10004). The API returns either the numeric value or one of these names depending
+    # on firmware.
+    CHARGE_DISCHARGE_COMMANDS = {
+        "stop": "204",
+        "charge": "170",
+        "discharge": "187",
+    }
+
+    # Canonical name -> on-the-wire value for `forced_charging` (10065).
+    FORCED_CHARGING = {
+        "disable": "85",
+        "enable": "170",
+    }
+
+    config_parameters = {
+        "10001": "soc_upper_limit",
+        "10002": "soc_lower_limit",
+        "10004": "charge_discharge_command",
+        "10005": "charge_discharge_power",
+        "10007": "limited_power_switch",
+        "10008": "active_power_limit_ratio",
+        "10009": "reactive_power_regulation_mode",
+        "10010": "q_t",
+        "10011": "power_on",
+        "10012": "feed_in_limitation",
+        "10013": "feed_in_limitation_value",
+        "10014": "feed_in_limitation_ratio",
+        "10017": "external_ems_heartbeat",
+        "10024": "battery_first",
+        "10025": "active_power_soft_start_after_fault",
+        "10026": "active_power_soft_start_time_after_fault",
+        "10027": "active_power_soft_start",
+        "10028": "active_power_soft_start_gradient",
+        "10029": "active_power_gradient_control",
+        "10030": "active_power_decline_gradient",
+        "10031": "active_power_rising_gradient",
+        "10032": "active_power_setting_persistence",
+        "10033": "shutdown_when_active_power_limit_to_0",
+        "10034": "reactive_response",
+        "10035": "reactive_power_regulation_time",
+        "10036": "pf",
+        "10065": "forced_charging",
+        "10066": "forced_charging_valid_time",
+        "10067": "forced_charging_start_time_1_hour",
+        "10068": "forced_charging_start_time_1_minute",
+        "10069": "forced_charging_end_time_1_hour",
+        "10070": "forced_charging_end_time_1_minute",
+        "10071": "forced_charging_target_soc_1",
+        "10072": "forced_charging_start_time_2_hour",
+        "10073": "forced_charging_start_time_2_minute",
+        "10074": "forced_charging_end_time_2_hour",
+        "10075": "forced_charging_end_time_2_minute",
+        "10076": "forced_charging_target_soc_2",
+        "10091": "max_charging_power",
+        "10092": "max_discharging_power",
+
+        # These are defined in API documentation but are rejected by the API as duplicates of 10071 and 10076
+        # "10015": "forced_charging_target_soc1",
+        # "10016": "forced_charging_target_soc2",
+
+        # These are defined in API documentation but cause validation error from the API
+        # "10003": "energy_management_mode",
+        # "10006": "existing_inverter",
+        # "10082": "charge_discharge_command_in_external_dispatch_mode",
+        # "10083": "charging_discharging_power_in_external_dispatch_mode",
+        # "10084": "power_limiting_command_in_external_dispatch_mode",
+        # "10085": "ems_heartbeat_settings_in_external_dispatch_mode",
+        # "10086": "energy_management_mode",
+        # "10087": "feed_in_limitation_ratio_in_external_dispatch_mode",
+        # "10088": "feed_in_limitation_on_off_in_external_dispatch_mode",
+        # "10089": "feed_in_limitation_value_in_external_dispatch_mode",
+    }

sungrow_isolarcloud-0.5.0/src/pysolarcloud/plants.py

@@ -0,0 +1,396 @@
+from datetime import datetime, timedelta
+from enum import Enum
+from . import AbstractAuth, PySolarCloudException, _LOGGER
+
+class DeviceType(Enum):
+    """Enum for the device types used by async_get_plant_devices."""
+    INVERTER = 1
+    CONTAINER = 2
+    GRID_CONNECTION_POINT = 3
+    COMBINER_BOX = 4
+    METEO_STATION = 5
+    TRANSFORMER = 6
+    METER = 7
+    UPS = 8
+    DATA_LOGGER = 9
+    STRING = 10
+    PLANT = 11
+    CIRCUIT_PROTECTION = 12
+    SPLITTING_DEVICE = 13
+    ENERGY_STORAGE_SYSTEM = 14
+    SAMPLING_DEVICE = 15
+    EMU = 16
+    UNIT = 17
+    TEMPERATURE_AND_HUMIDITY_SENSOR = 18
+    INTELLIGENT_POWER_DISTRIBUTION_CABINET = 19
+    DISPLAY_DEVICE = 20
+    AC_POWER_DISTRIBUTED_CABINET = 21
+    COMMUNICATION_MODULE = 22
+    SYSTEM_BMS = 23
+    ARRAY_BMS = 24
+    DC_DC = 25
+    ENERGY_MANAGEMENT_SYSTEM = 26
+    TRACKING_SYSTEM = 27
+    WIND_ENERGY_CONVERTER = 28
+    SVG = 29
+    PT_CABINET = 30
+    BUS_PROTECTION = 31
+    CLEANING_DEVICE = 32
+    DIRECT_CURRENT_CABINET = 33
+    PUBLIC_MEASUREMENT_AND_CONTROL = 34
+    ENERGY_STORAGE_SYSTEM_2 = 37
+    BATTERY = 43
+    BATTERY_CLUSTER_MANAGEMENT_UNIT = 44
+    LOCAL_CONTROLLER = 45
+    BATTERY_SYSTEM_CONTROLLER = 52
+
+
+class DeviceFaultStaus(Enum):
+    """Enum for the device fault status used by async_get_plant_devices."""
+    FAULT = 1
+    ALARM = 2
+    NORMAL = 4
+
+
+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})
+        res.raise_for_status()
+        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_plant_devices(self, plant_id: str, *, device_types: list[DeviceType | int] = []) -> list[dict]:
+        """Return details about the devices for a plant."""
+        uri = "/openapi/platform/getDeviceListByPsId"
+        params = {"ps_id": plant_id, "page": 1, "size": 100}
+        if device_types:
+            params["device_type_list"] = [str(d.value) if isinstance(d, DeviceType) else str(d) for d in device_types]
+        res = await self.auth.request(uri, params)
+        res.raise_for_status()
+        data = await res.json()
+        if "error" in data:
+            _LOGGER.error("Error response from %s: %s", uri, data)
+            raise PySolarCloudException(res)
+        devices = data["result_data"]["pageList"]
+        for device in devices:
+            # Convert the device type and fault status to enums
+            if device["device_type"] in DeviceType:
+                device["device_type"] = DeviceType(device["device_type"])
+            if device["dev_fault_status"] in DeviceFaultStaus:
+                device["dev_fault_status"] = DeviceFaultStaus(device["dev_fault_status"])
+        _LOGGER.debug("async_get_plant_devices: %s", devices)
+        return devices
+
+    async def async_get_realtime_data(
+        self,
+        plant_id: str | list[str],
+        *,
+        measure_points=None,
+        extra_measure_points: dict[str, str] | None = 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.
+        extra_measure_points: dict[str, str] - Mapping of additional point_id -> code pairs to
+            request alongside the defaults. Useful for surfacing fields the upstream library
+            hasn't catalogued (e.g. newer battery or EV-charger point IDs). Returned data points
+            use the codes supplied here verbatim.
+
+        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]
+        # Merge the canonical measure_points map with any caller-supplied extras for this call
+        # only — we deliberately do not mutate the class-level dict so concurrent callers and
+        # other Plants instances see the upstream defaults.
+        effective_points = dict(self.measure_points)
+        if extra_measure_points:
+            effective_points.update(extra_measure_points)
+        if measure_points is None:
+            ms = list(effective_points.keys())
+        else:
+            measure_points_map = {v: k for k, v in effective_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, effective_points) 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
+
+    async def async_get_device_realtime(
+        self,
+        plant_id: str,
+        device_type: DeviceType | int | str,
+        *,
+        extra_measure_points: dict[str, str] | None = None,
+    ) -> dict:
+        """Best-effort device-level realtime fetch for non-inverter devices.
+
+        The iSolarCloud plant realtime endpoint aggregates all points at the plant level and does
+        not separate per-device data for chargers, batteries, etc. Some accounts / regions expose
+        a per-device endpoint; when it is not available, this method returns an empty dict rather
+        than raising, so callers can feature-detect gracefully.
+
+        Returns a dict keyed by device uuid, each value being the same measure-point structure as
+        :meth:`async_get_realtime_data`.
+        """
+        if isinstance(device_type, DeviceType):
+            type_id = device_type.value
+        else:
+            type_id = int(device_type)
+        effective_points = dict(self.measure_points)
+        if extra_measure_points:
+            effective_points.update(extra_measure_points)
+        uri = "/openapi/platform/getDeviceRealTimeData"
+        res = await self.auth.request(
+            uri,
+            {
+                "ps_id": str(plant_id),
+                "device_type": str(type_id),
+                "point_id_list": list(effective_points.keys()),
+                "is_get_point_dict": "1",
+            },
+            lang=self.lang,
+        )
+        # Many accounts do not have this endpoint; treat transport / API errors as "unsupported"
+        # and let the caller decide how to surface that. We deliberately swallow only the
+        # "endpoint missing" class of failure, not generic 4xx/5xx.
+        if res.status in (404, 405):
+            _LOGGER.debug("Device realtime endpoint unavailable for plant %s type %s", plant_id, type_id)
+            return {}
+        res = await res.json()
+        if "error" in res:
+            error_code = res["error"].get("error") if isinstance(res["error"], dict) else None
+            if error_code in {"endpoint_not_found", "invalid_request"}:
+                _LOGGER.debug("Device realtime endpoint rejected request: %s", res)
+                return {}
+            _LOGGER.error("Error response from %s: %s", uri, res)
+            raise PySolarCloudException(res)
+        point_dict_items = res.get("result_data", {}).get("point_dict", []) or []
+        point_dict = {str(p["point_id"]): p for p in point_dict_items}
+        device_lists = res.get("result_data", {}).get("device_point_list", []) or []
+        out: dict[str, dict] = {}
+        for device in device_lists:
+            uuid = str(device.get("uuid") or device.get("device_id") or "")
+            if not uuid:
+                continue
+            data = [
+                self._format_measure_point(k[1:], v, point_dict, effective_points)
+                for k, v in device.items()
+                if k[0] == 'p' and k[1:].isdigit()
+            ]
+            out[uuid] = {d["code"]: d for d in data}
+        return out
+
+    async def async_get_historical_data(self, plant_id: str | list[str], start_time: datetime, end_time: datetime = None, *, measure_points=None, interval=timedelta(minutes=60)) -> dict:
+        """Return historical data from one or more plants.
+
+        plant_id: str | list[str] - The ID of the plant or a list of plant IDs.
+        start_time: datetime - The start time of the data to retrieve.
+        end_time: datetime - The end time of the data to retrieve. If end_time is not specified, 3 hours of data is returned.
+        measure_points: list[str] - A list of measure points to return. If None, all measure points are returned.
+        interval: timedelta - The interval in minutes between data points. The minimum interval is 1 minute. Default is 60 minutes.
+        Data is returned as a dictionary of lists:
+        {
+            plant_id: [
+                {
+                    "timestamp": datetime,
+                    "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)
+                }
+            ]
+        }
+        """
+        if isinstance(plant_id, list):
+            ps = str(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]
+        if end_time is None:
+            end_time = start_time + timedelta(hours=3)
+        TS_FORMAT = "%Y%m%d%H%M%S"
+        uri = "/openapi/platform/getPowerStationPointMinuteDataList"
+        params = {
+            "ps_id_list": ps,
+            "points": ",".join(["p"+m for m in ms]),
+            "is_get_point_dict": "1",
+            "start_time_stamp": start_time.strftime(TS_FORMAT),
+            "end_time_stamp": end_time.strftime(TS_FORMAT),
+            "minute_interval": str(interval.seconds // 60),
+        }
+        res = await self.auth.request(uri, params, lang=self.lang)
+        res = await res.json()
+        if res.get("result_code") != "1":
+            _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_id, plant in res["result_data"].items():
+            if plant_id == "point_dict":
+                continue
+            series = []
+            for frame in plant:
+                data = {}
+                ts = datetime.strptime(frame["time_stamp"], TS_FORMAT)
+                for k,v in frame.items():
+                    if k == "time_stamp":
+                        continue
+                    else:
+                        data = self._format_measure_point(k[1:], v, point_dict, self.measure_points)
+                        data["timestamp"] = ts
+                    series.append(data)
+            plants[str(plant_id)] = series
+        _LOGGER.debug("async_get_historical_data: %s", plants)
+        return plants
+
+    def _format_measure_point(self, point_id: str, point_value: str, point_dict: dict, measure_points: dict | None = None) -> dict:
+        try:
+            v = float(point_value) if point_value is not None else None
+        except ValueError:
+            v = point_value
+        code_map = measure_points if measure_points is not None else self.measure_points
+        return {
+            "id": point_id,
+            "code": code_map.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
+    }

sungrow_isolarcloud-0.5.0/src/sungrow_isolarcloud.egg-info/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: sungrow-isolarcloud
+Version: 0.5.0
+Summary: A library to interact with Sungrow's iSolarCloud API (KRoperUK fork with battery, EV charger and dispatch extensions)
+Author: KRoperUK
+Author-email: Tore Green <bugjam@e-dreams.dk>
+License: MIT
+Project-URL: Homepage, https://github.com/KRoperUK/pysolarcloud
+Project-URL: Issues, https://github.com/KRoperUK/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: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+
+# sungrow-isolarcloud
+
+A maintained fork of the [pysolarcloud](https://github.com/bugjam/pysolarcloud) library for interacting with Sungrow's [iSolarCloud API](https://developer-api.isolarcloud.com/).
+
+Install from PyPI:
+
+```
+pip install sungrow-isolarcloud
+```
+
+This fork adds:
+* Support for requesting **additional / custom measure points** without modifying the upstream point map (useful for battery charge/discharge power fields that vary by inverter model).
+* A best-effort **per-device realtime** helper for devices such as EV chargers (`Plants.async_get_device_realtime`).
+* A **heartbeat** helper for External EMS dispatch mode (`Control.async_heartbeat` / `Control.heartbeat_loop`).
+* Convenience constants for dispatch command value sets (`Control.CHARGE_DISCHARGE_COMMANDS`, `Control.FORCED_CHARGING`).
+
+The package supports the following functionality:
+* OAuth2 authentication
+* Getting a list plants
+* Getting details of a plant
+* Getting devices of a plant
+* Getting "real-time" data of a plant (Data is updated every 5 minutes according to Sungrow's documentation)
+* Getting historical data
+* Getting and updating grid control settings
+
+## 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
+
+## 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()
+if plant_list:
+   print(f"{len(plant_list)} plants found:")
+   for plant in plant_list:
+         print(f"Plant ID: {plant["ps_id"]}, Name: {plant["ps_name"]}")
+else:
+   print("No plants found.")
+   return
+
+print("\nFetching detailed information for each plant...\n")
+plant_ids = [str(plant["ps_id"]) for plant in plant_list]
+plant_details = await plants_api.async_get_plant_details(plant_ids)
+for plant in plant_details:
+   print(f"Details for Plant ID {plant["ps_id"]}: {plant}")
+
+print("\nFetching real-time data for each plant...\n")
+real_time_data = await plants_api.async_get_realtime_data(plant_ids)
+for plant_id, data in real_time_data.items():
+   # Print only the data points where value is not None
+   data_values = {k: v for k, v in data.items() if v and v.get("value") is not None}
+   print(f"Real-time data for Plant ID {plant_id}: {data_values}")
+```
+
+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`.
+
+## Grid Control
+
+The `Control` class enables retrieving and updating grid control settings. Parameters and value sets are documented in the iSolarCloud Developer portal.
+
+### Example
+
+```python
+from pysolarcloud.control import Control
+from pysolarcloud.plants import DeviceType
+
+devices = await plants_api.async_get_plant_devices(plant_id, device_types=[DeviceType.ENERGY_STORAGE_SYSTEM])
+device_uuid = devices[0]["uuid"]
+control_api = Control(auth)
+# Fetch current config
+current_settings = await control_api.async_read_parameters(device_uuid)
+print(current_settings)
+# Make an update using the canonical command values
+await control_api.async_update_parameters(
+    device_uuid,
+    {
+        "charge_discharge_command": Control.CHARGE_DISCHARGE_COMMANDS["charge"],
+        "charge_discharge_power": "2500",
+    },
+)
+
+# When using External EMS mode, send a heartbeat periodically to keep the inverter in dispatch mode.
+# 10017 = external_ems_heartbeat, value is the heartbeat interval in seconds (1-1000).
+await control_api.async_heartbeat(device_uuid, interval_seconds=60)
+```
+
+# 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.
+
+Enjoy!

sungrow_isolarcloud-0.5.0/src/sungrow_isolarcloud.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE.txt
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+src/pysolarcloud/__init__.py
+src/pysolarcloud/control.py
+src/pysolarcloud/plants.py
+src/sungrow_isolarcloud.egg-info/PKG-INFO
+src/sungrow_isolarcloud.egg-info/SOURCES.txt
+src/sungrow_isolarcloud.egg-info/dependency_links.txt
+src/sungrow_isolarcloud.egg-info/requires.txt
+src/sungrow_isolarcloud.egg-info/top_level.txt

sungrow_isolarcloud-0.5.0/src/sungrow_isolarcloud.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sungrow_isolarcloud-0.5.0/src/sungrow_isolarcloud.egg-info/requires.txt

@@ -0,0 +1,5 @@
+aiohttp
+
+[dev]
+pytest
+pytest-asyncio

sungrow_isolarcloud-0.5.0/src/sungrow_isolarcloud.egg-info/top_level.txt

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