aiomarstek 0.1.0__tar.gz

aiomarstek-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marstek
+
+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.

aiomarstek-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: aiomarstek
+Version: 0.1.0
+Summary: Async client library for local Marstek devices
+Author: Marstek
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Clarksonurge/aiomarstek
+Project-URL: Issues, https://github.com/Clarksonurge/aiomarstek/issues
+Keywords: asyncio,home-assistant,marstek,udp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: ruff>=0.8; extra == "test"
+Dynamic: license-file
+
+# aiomarstek
+
+Async client library for local Marstek device communication.
+
+`aiomarstek` contains the UDP protocol, command builder, discovery cache,
+polling pause handling, and high-level status helpers used by the Home Assistant
+Marstek integration.
+
+## Installation
+
+```bash
+python -m pip install aiomarstek
+```
+
+## Example
+
+```python
+import asyncio
+
+from aiomarstek import MarstekUDPClient
+
+
+async def main() -> None:
+    client = MarstekUDPClient()
+    await client.async_setup()
+    try:
+        devices = await client.discover_devices()
+        print(devices)
+    finally:
+        await client.async_cleanup()
+
+
+asyncio.run(main())
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+python -m pytest
+python -m ruff check .
+python -m build
+```

aiomarstek-0.1.0/README.md

@@ -0,0 +1,43 @@
+# aiomarstek
+
+Async client library for local Marstek device communication.
+
+`aiomarstek` contains the UDP protocol, command builder, discovery cache,
+polling pause handling, and high-level status helpers used by the Home Assistant
+Marstek integration.
+
+## Installation
+
+```bash
+python -m pip install aiomarstek
+```
+
+## Example
+
+```python
+import asyncio
+
+from aiomarstek import MarstekUDPClient
+
+
+async def main() -> None:
+    client = MarstekUDPClient()
+    await client.async_setup()
+    try:
+        devices = await client.discover_devices()
+        print(devices)
+    finally:
+        await client.async_cleanup()
+
+
+asyncio.run(main())
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+python -m pytest
+python -m ruff check .
+python -m build
+```

aiomarstek-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aiomarstek"
+version = "0.1.0"
+description = "Async client library for local Marstek devices"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Marstek" }]
+keywords = ["asyncio", "home-assistant", "marstek", "udp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/Clarksonurge/aiomarstek"
+Issues = "https://github.com/Clarksonurge/aiomarstek/issues"
+
+[tool.setuptools.package-data]
+aiomarstek = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "RUF"]
+ignore = ["ASYNC109"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

aiomarstek-0.1.0/setup.cfg

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

aiomarstek-0.1.0/src/aiomarstek/__init__.py

@@ -0,0 +1,43 @@
+"""Marstek client library."""
+
+from __future__ import annotations
+
+from .command_builder import (
+    build_command,
+    discover,
+    get_battery_status,
+    get_es_mode,
+    get_es_status,
+    get_next_request_id,
+    get_pv_status,
+    reset_request_id,
+)
+from .const import (
+    CMD_BATTERY_STATUS,
+    CMD_DISCOVER,
+    CMD_ES_MODE,
+    CMD_ES_STATUS,
+    CMD_PV_GET_STATUS,
+    DEFAULT_UDP_PORT,
+    DISCOVERY_TIMEOUT,
+)
+from .udp_client import MarstekUDPClient
+
+__all__ = [
+    "CMD_BATTERY_STATUS",
+    "CMD_DISCOVER",
+    "CMD_ES_MODE",
+    "CMD_ES_STATUS",
+    "CMD_PV_GET_STATUS",
+    "DEFAULT_UDP_PORT",
+    "DISCOVERY_TIMEOUT",
+    "MarstekUDPClient",
+    "build_command",
+    "discover",
+    "get_battery_status",
+    "get_es_mode",
+    "get_es_status",
+    "get_next_request_id",
+    "get_pv_status",
+    "reset_request_id",
+]

aiomarstek-0.1.0/src/aiomarstek/command_builder.py

@@ -0,0 +1,64 @@
+"""Command builder for Marstek devices."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .const import (
+    CMD_BATTERY_STATUS,
+    CMD_DISCOVER,
+    CMD_ES_MODE,
+    CMD_ES_STATUS,
+    CMD_PV_GET_STATUS,
+)
+
+_request_id = 0
+
+
+def get_next_request_id() -> int:
+    """Get next request ID."""
+    global _request_id
+    _request_id += 1
+    return _request_id
+
+
+def reset_request_id() -> None:
+    """Reset request ID counter."""
+    global _request_id
+    _request_id = 0
+
+
+def build_command(method: str, params: dict[str, Any] | None = None) -> str:
+    """Build command JSON string."""
+    command = {
+        "id": get_next_request_id(),
+        "method": method,
+        "params": params or {},
+    }
+    return json.dumps(command)
+
+
+def discover() -> str:
+    """Device discovery command."""
+    return build_command(CMD_DISCOVER, {"ble_mac": "0"})
+
+
+def get_battery_status(device_id: int = 0) -> str:
+    """Battery status query command."""
+    return build_command(CMD_BATTERY_STATUS, {"id": device_id})
+
+
+def get_es_status(device_id: int = 0) -> str:
+    """Get device power status and statistics command."""
+    return build_command(CMD_ES_STATUS, {"id": device_id})
+
+
+def get_es_mode(device_id: int = 0) -> str:
+    """Get device operating mode and battery info command."""
+    return build_command(CMD_ES_MODE, {"id": device_id})
+
+
+def get_pv_status(device_id: int = 0) -> str:
+    """Get device PV status command."""
+    return build_command(CMD_PV_GET_STATUS, {"id": device_id})

aiomarstek-0.1.0/src/aiomarstek/const.py

@@ -0,0 +1,14 @@
+"""Constants for the Marstek client library."""
+
+from __future__ import annotations
+
+from typing import Final
+
+DEFAULT_UDP_PORT: Final = 30000
+DISCOVERY_TIMEOUT: Final = 10.0
+
+CMD_DISCOVER: Final = "Marstek.GetDevice"
+CMD_BATTERY_STATUS: Final = "Bat.GetStatus"
+CMD_ES_STATUS: Final = "ES.GetStatus"
+CMD_ES_MODE: Final = "ES.GetMode"
+CMD_PV_GET_STATUS: Final = "PV.GetStatus"

aiomarstek-0.1.0/src/aiomarstek/py.typed

@@ -0,0 +1 @@
+

aiomarstek-0.1.0/src/aiomarstek/udp_client.py

@@ -0,0 +1,508 @@
+"""UDP client for Marstek device communication."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import socket
+from collections.abc import Iterable
+from contextlib import suppress
+from typing import Any
+
+from .command_builder import discover, get_es_mode, get_pv_status
+from .const import DEFAULT_UDP_PORT, DISCOVERY_TIMEOUT
+
+_LOGGER = logging.getLogger(__name__)
+_SOCKET_FACTORY = socket.socket
+
+
+class MarstekUDPClient:
+    """UDP client for Marstek device communication."""
+
+    def __init__(
+        self,
+        port: int = DEFAULT_UDP_PORT,
+        broadcast_addresses: Iterable[str] | None = None,
+    ) -> None:
+        """Initialize UDP client."""
+        self._port = port
+        self._socket: socket.socket | None = None
+        self._pending_requests: dict[int, asyncio.Future] = {}
+        self._response_cache: dict[int, dict[str, Any]] = {}
+        self._listen_task: asyncio.Task | None = None
+        self._discovery_cache: list[dict[str, Any]] | None = None
+        self._cache_timestamp: float = 0
+        self._cache_duration: float = 30.0
+        self._local_send_ip: str = "0.0.0.0"
+        self._polling_paused: dict[str, bool] = {}
+        self._polling_lock: asyncio.Lock = asyncio.Lock()
+        self._broadcast_addresses = list(broadcast_addresses or ["255.255.255.255"])
+
+    def set_broadcast_addresses(self, addresses: Iterable[str]) -> None:
+        """Set broadcast addresses used for discovery."""
+        self._broadcast_addresses = list(addresses)
+
+    def get_discovery_cache(self) -> list[dict[str, Any]] | None:
+        """Return a copy of the discovery cache."""
+        if self._discovery_cache is None:
+            return None
+        return self._discovery_cache.copy()
+
+    async def async_setup(self) -> None:
+        """Setup UDP socket."""
+        if self._socket is not None:
+            return
+
+        self._socket = _SOCKET_FACTORY(socket.AF_INET, socket.SOCK_DGRAM)
+        self._socket.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+        self._socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        self._socket.setblocking(False)
+        self._socket.bind(("0.0.0.0", 30000))
+        _LOGGER.debug(
+            "UDP client bound to %s:%s",
+            self._socket.getsockname()[0],
+            self._socket.getsockname()[1],
+        )
+
+    async def async_cleanup(self) -> None:
+        """Cleanup UDP socket."""
+        if self._listen_task and not self._listen_task.done():
+            self._listen_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._listen_task
+
+        if self._socket:
+            self._socket.close()
+            self._socket = None
+
+    def _is_cache_valid(self) -> bool:
+        """Check if cache is valid."""
+        if self._discovery_cache is None:
+            return False
+        current_time = asyncio.get_running_loop().time()
+        return (current_time - self._cache_timestamp) < self._cache_duration
+
+    def clear_discovery_cache(self) -> None:
+        """Clear discovery cache."""
+        self._discovery_cache = None
+        self._cache_timestamp = 0
+        _LOGGER.debug("Device discovery cache cleared")
+
+    async def _send_udp_message(
+        self, message: str, target_ip: str, target_port: int | None = None
+    ) -> None:
+        """Send UDP message to the specified target."""
+        if not self._socket:
+            await self.async_setup()
+
+        try:
+            data = message.encode("utf-8")
+            self._socket.sendto(data, (target_ip, target_port or self._port))
+            _LOGGER.debug(
+                "Send: %s:%d <- %s:%d | %s",
+                target_ip,
+                target_port or self._port,
+                self._local_send_ip,
+                self._port,
+                message,
+            )
+        except Exception as err:
+            _LOGGER.error("Failed to send UDP message: %s", err)
+            raise
+
+    async def send_request(
+        self,
+        message: str,
+        target_ip: str,
+        target_port: int | None = None,
+        timeout: float = 5.0,
+        *,
+        quiet_on_timeout: bool = False,
+    ) -> dict[str, Any]:
+        """Send unicast request and wait for response."""
+        if not self._socket:
+            await self.async_setup()
+
+        try:
+            message_obj = json.loads(message)
+            request_id = message_obj["id"]
+        except (json.JSONDecodeError, KeyError) as err:
+            _LOGGER.error("Invalid message format: %s", err)
+            raise ValueError(f"Invalid message format: {err}") from err
+
+        loop = asyncio.get_running_loop()
+        future = loop.create_future()
+        self._pending_requests[request_id] = future
+
+        try:
+            if not self._listen_task or self._listen_task.done():
+                self._listen_task = asyncio.create_task(self._listen_for_responses())
+
+            await self._send_udp_message(message, target_ip, target_port)
+
+            try:
+                return await asyncio.wait_for(future, timeout=timeout)
+            except TimeoutError as err:
+                if quiet_on_timeout or self.is_polling_paused(target_ip):
+                    _LOGGER.debug(
+                        "Request timeout: %s:%d (quiet)",
+                        target_ip,
+                        target_port or self._port,
+                    )
+                else:
+                    _LOGGER.warning(
+                        "Request timeout: %s:%d",
+                        target_ip,
+                        target_port or self._port,
+                    )
+                raise TimeoutError(
+                    f"Request timeout to {target_ip}:{target_port or self._port}"
+                ) from err
+        finally:
+            self._pending_requests.pop(request_id, None)
+
+    async def _listen_for_responses(self) -> None:
+        """Listen for UDP responses."""
+        if not self._socket:
+            return
+
+        loop = asyncio.get_running_loop()
+        while True:
+            try:
+                data, addr = await loop.sock_recvfrom(self._socket, 4096)
+                response_text = data.decode("utf-8")
+                try:
+                    response = json.loads(response_text)
+                except json.JSONDecodeError:
+                    response = {"raw": response_text}
+                request_id = response.get("id") if isinstance(response, dict) else None
+
+                _LOGGER.debug(
+                    "Recv: %s:%d -> %s:%d | %s",
+                    addr[0],
+                    addr[1],
+                    self._local_send_ip,
+                    self._port,
+                    json.dumps(response, ensure_ascii=False),
+                )
+
+                if request_id:
+                    self._response_cache[request_id] = {
+                        "response": response,
+                        "addr": addr,
+                        "timestamp": loop.time(),
+                    }
+
+                if request_id and request_id in self._pending_requests:
+                    future = self._pending_requests.pop(request_id)
+                    if not future.done():
+                        future.set_result(response)
+            except asyncio.CancelledError:
+                break
+            except OSError as err:
+                _LOGGER.error("Error receiving UDP response: %s", err)
+                await asyncio.sleep(1)
+
+    async def send_broadcast_request(
+        self,
+        message: str,
+        timeout: float = DISCOVERY_TIMEOUT,
+        broadcast_addresses: Iterable[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Send broadcast request and collect all responses."""
+        if not self._socket:
+            await self.async_setup()
+
+        try:
+            message_obj = json.loads(message)
+            request_id = message_obj["id"]
+        except (json.JSONDecodeError, KeyError) as err:
+            _LOGGER.error("Invalid message format: %s", err)
+            return []
+
+        responses: list[dict[str, Any]] = []
+        start_time = asyncio.get_running_loop().time()
+        loop = asyncio.get_running_loop()
+        future = loop.create_future()
+        self._pending_requests[request_id] = future
+
+        try:
+            if not self._listen_task or self._listen_task.done():
+                self._listen_task = asyncio.create_task(self._listen_for_responses())
+
+            targets = list(broadcast_addresses or self._broadcast_addresses)
+            _LOGGER.debug("Broadcast targets: %s", targets)
+
+            for address in targets:
+                await self._send_udp_message(message, address, self._port)
+                _LOGGER.debug("Sent to %s:%s", address, self._port)
+
+            _LOGGER.debug("Broadcast to %d interfaces", len(targets))
+            _LOGGER.debug("Broadcast payload: %s", message)
+            _LOGGER.debug("Target port: %s", self._port)
+
+            _LOGGER.debug("Start waiting for responses, timeout: %d s", timeout)
+            try:
+                while (loop.time() - start_time) < timeout:
+                    if request_id in self._response_cache:
+                        cached_response = self._response_cache[request_id]
+                        responses.append(cached_response["response"])
+                        _LOGGER.debug(
+                            "Broadcast ID:%s received %d response(s)",
+                            request_id,
+                            len(responses),
+                        )
+                        del self._response_cache[request_id]
+
+                    await asyncio.sleep(0.1)
+
+                    if (loop.time() - start_time) >= timeout:
+                        _LOGGER.debug("Broadcast ID:%s wait timeout", request_id)
+                        break
+            except OSError as err:
+                _LOGGER.error("Error waiting for response: %s", err)
+        finally:
+            self._pending_requests.pop(request_id, None)
+
+        _LOGGER.info("Broadcast discovery finished, %d responses", len(responses))
+        return responses
+
+    async def discover_devices(
+        self,
+        use_cache: bool = True,
+        broadcast_addresses: Iterable[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Discover Marstek devices on network and deduplicate results."""
+        if use_cache and self._is_cache_valid():
+            _LOGGER.debug("Using cached discovery results")
+            return self._discovery_cache.copy()
+
+        devices: list[dict[str, Any]] = []
+        seen_devices: set[str] = set()
+
+        try:
+            responses = await self.send_broadcast_request(
+                discover(),
+                broadcast_addresses=broadcast_addresses,
+            )
+
+            for response in responses:
+                if response.get("result"):
+                    device_info = response["result"]
+                    device_id = (
+                        device_info.get("ip", "")
+                        or device_info.get("ble_mac")
+                        or device_info.get("wifi_mac")
+                        or f"device_{int(asyncio.get_running_loop().time())}_{hash(str(device_info)) % 10000}"
+                    )
+
+                    if device_id in seen_devices:
+                        _LOGGER.debug(
+                            "Skip duplicate device: %s (IP: %s, BLE_MAC: %s, WiFi_MAC: %s)",
+                            device_id,
+                            device_info.get("ip"),
+                            device_info.get("ble_mac"),
+                            device_info.get("wifi_mac"),
+                        )
+                        continue
+
+                    seen_devices.add(device_id)
+                    _LOGGER.debug(
+                        "Add device: %s (IP: %s, BLE_MAC: %s, WiFi_MAC: %s)",
+                        device_id,
+                        device_info.get("ip"),
+                        device_info.get("ble_mac"),
+                        device_info.get("wifi_mac"),
+                    )
+
+                    device = {
+                        "id": device_info.get("id", 0),
+                        "device_type": device_info.get("device", "Unknown"),
+                        "version": device_info.get("ver", 0),
+                        "wifi_name": device_info.get("wifi_name", ""),
+                        "ip": device_info.get("ip", ""),
+                        "wifi_mac": device_info.get("wifi_mac", ""),
+                        "ble_mac": device_info.get("ble_mac", ""),
+                        "mac": device_info.get("wifi_mac")
+                        or device_info.get("ble_mac", ""),
+                        "model": device_info.get("device", "Unknown"),
+                        "firmware": str(device_info.get("ver", 0)),
+                    }
+
+                    devices.append(device)
+                    _LOGGER.info(
+                        "Discovered device: Type=%s, Version=%s, WiFi=%s, IP=%s, MAC=%s",
+                        device["device_type"],
+                        device["version"],
+                        device["wifi_name"],
+                        device["ip"],
+                        device["mac"],
+                    )
+        except OSError as err:
+            _LOGGER.error("Device discovery failed: %s", err)
+
+        self._discovery_cache = devices.copy()
+        self._cache_timestamp = asyncio.get_running_loop().time()
+
+        _LOGGER.info("Device discovery finished, %d unique devices", len(devices))
+        return devices
+
+    async def pause_polling(self, device_ip: str) -> None:
+        """Pause polling for a specific device."""
+        async with self._polling_lock:
+            self._polling_paused[device_ip] = True
+            _LOGGER.info("Polling paused for device: %s", device_ip)
+
+    async def resume_polling(self, device_ip: str) -> None:
+        """Resume polling for a specific device."""
+        async with self._polling_lock:
+            self._polling_paused[device_ip] = False
+            _LOGGER.info("Polling resumed for device: %s", device_ip)
+
+    def is_polling_paused(self, device_ip: str) -> bool:
+        """Check if polling is paused for a specific device."""
+        return self._polling_paused.get(device_ip, False)
+
+    async def send_request_with_polling_control(
+        self,
+        message: str,
+        target_ip: str,
+        target_port: int | None = None,
+        timeout: float = 5.0,
+    ) -> dict[str, Any]:
+        """Send request with polling control."""
+        await self.pause_polling(target_ip)
+
+        try:
+            return await self.send_request(
+                message,
+                target_ip,
+                target_port,
+                timeout,
+                quiet_on_timeout=True,
+            )
+        finally:
+            await self.resume_polling(target_ip)
+
+    async def get_device_status(
+        self,
+        device_ip: str,
+        *,
+        previous_data: dict[str, Any] | None = None,
+        timeout: float = 2.5,
+        delay_ms: int = 2000,
+    ) -> dict[str, Any]:
+        """Fetch device status and PV data."""
+        current_data = previous_data or {}
+        result_data = {
+            "battery_soc": current_data.get("battery_soc", 0),
+            "battery_power": current_data.get("battery_power", 0),
+            "device_mode": current_data.get("device_mode", "Unknown"),
+            "battery_status": current_data.get("battery_status", "Unknown"),
+            "device_ip": device_ip,
+            "last_update": asyncio.get_running_loop().time(),
+            "pv1_power": current_data.get("pv1_power", 0),
+            "pv1_voltage": current_data.get("pv1_voltage", 0),
+            "pv1_current": current_data.get("pv1_current", 0),
+            "pv1_state": current_data.get("pv1_state", 0),
+            "pv2_power": current_data.get("pv2_power", 0),
+            "pv2_voltage": current_data.get("pv2_voltage", 0),
+            "pv2_current": current_data.get("pv2_current", 0),
+            "pv2_state": current_data.get("pv2_state", 0),
+            "pv3_power": current_data.get("pv3_power", 0),
+            "pv3_voltage": current_data.get("pv3_voltage", 0),
+            "pv3_current": current_data.get("pv3_current", 0),
+            "pv3_state": current_data.get("pv3_state", 0),
+            "pv4_power": current_data.get("pv4_power", 0),
+            "pv4_voltage": current_data.get("pv4_voltage", 0),
+            "pv4_current": current_data.get("pv4_current", 0),
+            "pv4_state": current_data.get("pv4_state", 0),
+        }
+
+        async def delay(ms: int) -> None:
+            await asyncio.sleep(ms / 1000.0)
+
+        async def es_status_request() -> bool:
+            try:
+                mode_as_status_result = await self.send_request(
+                    get_es_mode(0),
+                    device_ip,
+                    timeout=timeout,
+                )
+                status_data = mode_as_status_result.get("result", {})
+
+                battery_soc = status_data.get(
+                    "bat_soc", result_data.get("battery_soc", 0)
+                )
+                result_data["battery_soc"] = battery_soc
+                ongrid_power = status_data.get(
+                    "ongrid_power", result_data.get("battery_power", 0)
+                )
+                result_data["battery_power"] = abs(ongrid_power)
+                result_data["device_mode"] = status_data.get("mode", "Unknown")
+                if ongrid_power > 0:
+                    result_data["battery_status"] = "Selling"
+                elif ongrid_power < 0:
+                    result_data["battery_status"] = "Charging"
+                else:
+                    result_data["battery_status"] = "Idle"
+            except (TimeoutError, OSError, ValueError):
+                return False
+            return True
+
+        async def pv_status_request() -> bool:
+            try:
+                pv_status_result = await self.send_request(
+                    get_pv_status(0),
+                    device_ip,
+                    timeout=timeout,
+                )
+                pv_data = pv_status_result.get("result", {})
+
+                for key in (
+                    "pv1_power",
+                    "pv1_voltage",
+                    "pv1_current",
+                    "pv1_state",
+                    "pv2_power",
+                    "pv2_voltage",
+                    "pv2_current",
+                    "pv2_state",
+                    "pv3_power",
+                    "pv3_voltage",
+                    "pv3_current",
+                    "pv3_state",
+                    "pv4_power",
+                    "pv4_voltage",
+                    "pv4_current",
+                    "pv4_state",
+                ):
+                    result_data[key] = pv_data.get(key, result_data.get(key, 0))
+            except (TimeoutError, OSError, ValueError):
+                return False
+            return True
+
+        try:
+            await es_status_request()
+        except (TimeoutError, OSError, ValueError) as err:
+            _LOGGER.error("Device %s ES.GetMode request failed: %s", device_ip, err)
+
+        await delay(delay_ms)
+
+        try:
+            await pv_status_request()
+        except (TimeoutError, OSError, ValueError) as err:
+            _LOGGER.error("Device %s PV.GetStatus request failed: %s", device_ip, err)
+
+        return result_data
+
+    async def get_device_info(
+        self, device_ip: str, *, timeout: float = 5.0
+    ) -> dict[str, Any]:
+        """Fetch device information from a specific host."""
+        response = await self.send_request(discover(), device_ip, timeout=timeout)
+        result = response.get("result") if isinstance(response, dict) else None
+        if not isinstance(result, dict):
+            raise TypeError("No device information returned")
+        return result

aiomarstek-0.1.0/src/aiomarstek.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: aiomarstek
+Version: 0.1.0
+Summary: Async client library for local Marstek devices
+Author: Marstek
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Clarksonurge/aiomarstek
+Project-URL: Issues, https://github.com/Clarksonurge/aiomarstek/issues
+Keywords: asyncio,home-assistant,marstek,udp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: ruff>=0.8; extra == "test"
+Dynamic: license-file
+
+# aiomarstek
+
+Async client library for local Marstek device communication.
+
+`aiomarstek` contains the UDP protocol, command builder, discovery cache,
+polling pause handling, and high-level status helpers used by the Home Assistant
+Marstek integration.
+
+## Installation
+
+```bash
+python -m pip install aiomarstek
+```
+
+## Example
+
+```python
+import asyncio
+
+from aiomarstek import MarstekUDPClient
+
+
+async def main() -> None:
+    client = MarstekUDPClient()
+    await client.async_setup()
+    try:
+        devices = await client.discover_devices()
+        print(devices)
+    finally:
+        await client.async_cleanup()
+
+
+asyncio.run(main())
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+python -m pytest
+python -m ruff check .
+python -m build
+```

aiomarstek-0.1.0/src/aiomarstek.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/aiomarstek/__init__.py
+src/aiomarstek/command_builder.py
+src/aiomarstek/const.py
+src/aiomarstek/py.typed
+src/aiomarstek/udp_client.py
+src/aiomarstek.egg-info/PKG-INFO
+src/aiomarstek.egg-info/SOURCES.txt
+src/aiomarstek.egg-info/dependency_links.txt
+src/aiomarstek.egg-info/requires.txt
+src/aiomarstek.egg-info/top_level.txt
+tests/test_command_builder.py
+tests/test_udp_client.py

aiomarstek-0.1.0/src/aiomarstek.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aiomarstek-0.1.0/src/aiomarstek.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[test]
+pytest>=8.0
+pytest-asyncio>=0.24
+ruff>=0.8

aiomarstek-0.1.0/src/aiomarstek.egg-info/top_level.txt

@@ -0,0 +1 @@
+aiomarstek

aiomarstek-0.1.0/tests/test_command_builder.py

@@ -0,0 +1,114 @@
+"""Tests for the Marstek command builder."""
+
+from __future__ import annotations
+
+import json
+
+from aiomarstek import (
+    CMD_BATTERY_STATUS,
+    CMD_DISCOVER,
+    CMD_ES_MODE,
+    CMD_ES_STATUS,
+    CMD_PV_GET_STATUS,
+    build_command,
+    discover,
+    get_battery_status,
+    get_es_mode,
+    get_es_status,
+    get_next_request_id,
+    get_pv_status,
+    reset_request_id,
+)
+
+
+def test_get_next_request_id() -> None:
+    """Test request ID generation."""
+    reset_request_id()
+    assert get_next_request_id() == 1
+    assert get_next_request_id() == 2
+    assert get_next_request_id() == 3
+
+
+def test_reset_request_id() -> None:
+    """Test request ID reset."""
+    get_next_request_id()
+    get_next_request_id()
+    reset_request_id()
+    assert get_next_request_id() == 1
+
+
+def test_build_command() -> None:
+    """Test building a command."""
+    reset_request_id()
+    command = build_command("test.method", {"param": "value"})
+    parsed = json.loads(command)
+
+    assert parsed["id"] == 1
+    assert parsed["method"] == "test.method"
+    assert parsed["params"] == {"param": "value"}
+
+
+def test_build_command_without_params() -> None:
+    """Test building a command without parameters."""
+    reset_request_id()
+    command = build_command("test.method")
+    parsed = json.loads(command)
+
+    assert parsed["id"] == 1
+    assert parsed["method"] == "test.method"
+    assert parsed["params"] == {}
+
+
+def test_discover() -> None:
+    """Test discover command."""
+    reset_request_id()
+    command = discover()
+    parsed = json.loads(command)
+
+    assert parsed["id"] == 1
+    assert parsed["method"] == CMD_DISCOVER
+    assert parsed["params"] == {"ble_mac": "0"}
+
+
+def test_get_battery_status() -> None:
+    """Test battery status command."""
+    reset_request_id()
+    command = get_battery_status(5)
+    parsed = json.loads(command)
+
+    assert parsed["id"] == 1
+    assert parsed["method"] == CMD_BATTERY_STATUS
+    assert parsed["params"] == {"id": 5}
+
+
+def test_get_es_status() -> None:
+    """Test ES status command."""
+    reset_request_id()
+    command = get_es_status(0)
+    parsed = json.loads(command)
+
+    assert parsed["id"] == 1
+    assert parsed["method"] == CMD_ES_STATUS
+    assert parsed["params"] == {"id": 0}
+
+
+def test_get_es_mode() -> None:
+    """Test ES mode command."""
+    reset_request_id()
+    command = get_es_mode(0)
+    parsed = json.loads(command)
+
+    assert parsed["id"] == 1
+    assert parsed["method"] == CMD_ES_MODE
+    assert parsed["params"] == {"id": 0}
+
+
+def test_get_pv_status() -> None:
+    """Test PV status command."""
+    reset_request_id()
+    command = get_pv_status(0)
+    parsed = json.loads(command)
+
+    assert parsed["id"] == 1
+    assert parsed["method"] == CMD_PV_GET_STATUS
+    assert parsed["params"] == {"id": 0}

aiomarstek-0.1.0/tests/test_udp_client.py

@@ -0,0 +1,112 @@
+"""Tests for the Marstek UDP client."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from aiomarstek import MarstekUDPClient
+
+
+@pytest.fixture
+def socket_mock() -> MagicMock:
+    """Mock Marstek UDP sockets."""
+    socket_instance = MagicMock()
+    socket_instance.getsockname.return_value = ("0.0.0.0", 30000)
+    with patch("aiomarstek.udp_client._SOCKET_FACTORY", return_value=socket_instance):
+        yield socket_instance
+
+
+async def test_async_setup(socket_mock: MagicMock) -> None:
+    """Test UDP client setup."""
+    client = MarstekUDPClient()
+
+    await client.async_setup()
+
+    socket_mock.setsockopt.assert_called()
+    socket_mock.setblocking.assert_called_once_with(False)
+    socket_mock.bind.assert_called_once_with(("0.0.0.0", 30000))
+
+
+async def test_async_cleanup(socket_mock: MagicMock) -> None:
+    """Test UDP client cleanup."""
+    client = MarstekUDPClient()
+
+    await client.async_setup()
+    await client.async_cleanup()
+
+    socket_mock.close.assert_called_once()
+
+
+async def test_send_udp_message(socket_mock: MagicMock) -> None:
+    """Test sending UDP messages."""
+    client = MarstekUDPClient()
+
+    await client._send_udp_message('{"id": 1, "method": "test"}', "192.0.2.1", 30000)
+
+    socket_mock.sendto.assert_called_once_with(
+        b'{"id": 1, "method": "test"}',
+        ("192.0.2.1", 30000),
+    )
+
+
+async def test_discover_devices_cache(socket_mock: MagicMock) -> None:
+    """Test device discovery cache."""
+    client = MarstekUDPClient()
+    response = {
+        "id": 1,
+        "result": {
+            "id": 0,
+            "device": "ES5",
+            "ver": 1,
+            "wifi_name": "TestWiFi",
+            "ip": "192.0.2.1",
+            "wifi_mac": "AA:BB:CC:DD:EE:FF",
+            "ble_mac": "11:22:33:44:55:66",
+        },
+    }
+
+    with patch.object(client, "send_broadcast_request", return_value=[response]):
+        devices = await client.discover_devices(use_cache=False)
+        cached_devices = await client.discover_devices(use_cache=True)
+
+    assert devices == cached_devices
+    assert cached_devices[0]["device_type"] == "ES5"
+    assert cached_devices[0]["ip"] == "192.0.2.1"
+
+
+async def test_polling_control() -> None:
+    """Test polling pause and resume."""
+    client = MarstekUDPClient()
+
+    assert not client.is_polling_paused("192.0.2.1")
+    await client.pause_polling("192.0.2.1")
+    assert client.is_polling_paused("192.0.2.1")
+    await client.resume_polling("192.0.2.1")
+    assert not client.is_polling_paused("192.0.2.1")
+
+
+async def test_send_request_invalid_message(socket_mock: MagicMock) -> None:
+    """Test invalid request payload handling."""
+    client = MarstekUDPClient()
+
+    with pytest.raises(ValueError):
+        await client.send_request("not json", "192.0.2.1", timeout=0.1)
+
+
+async def test_get_device_status_preserves_previous_data() -> None:
+    """Test status helper preserves previous data when requests fail."""
+    client = MarstekUDPClient()
+    previous_data = {"battery_soc": 42, "pv1_power": 100}
+
+    with patch.object(client, "send_request", side_effect=TimeoutError):
+        result = await client.get_device_status(
+            "192.0.2.1",
+            previous_data=previous_data,
+            delay_ms=0,
+        )
+
+    assert result["battery_soc"] == 42
+    assert result["pv1_power"] == 100
+    assert result["device_ip"] == "192.0.2.1"