aiorefoss 1.0.3__tar.gz

aiorefoss-1.0.3/LICENSE

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

aiorefoss-1.0.3/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: aiorefoss
+Version: 1.0.3
+Summary: Asynchronous Python library for Refoss smart devices
+Author: ashionky
+Author-email: ashionky <495519020@qq.com>
+Project-URL: Homepage, https://github.com/ashionky/aiorefoss
+Project-URL: Bug Tracker, https://github.com/ashionky/aiorefoss/issues
+Project-URL: Repository, https://github.com/ashionky/aiorefoss
+Keywords: refoss,homeassistant,iot,smart-home,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: yarl>=1.9.0
+Provides-Extra: fastjson
+Requires-Dist: orjson>=3.9.0; extra == "fastjson"
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# aiorefoss
+
+Asynchronous Python library for Refoss smart devices, designed for Home Assistant integration.
+
+## Features
+
+- Async WebSocket connection
+- Device authentication support for new firmware (EM16P v3.1.11+)
+- Automatic auth challenge handling
+- Real-time status updates
+- Device configuration management
+- Cross-platform JSON support (orjson with stdlib fallback)
+
+## Installation
+
+```bash
+pip install aiorefoss
+```
+
+With faster JSON support:
+```bash
+pip install aiorefoss[fastjson]
+```
+
+## Quick Start
+
+```python
+import asyncio
+from aiorefoss.rpc_device.device import RpcDevice
+from aiorefoss.common import process_ip_or_options
+
+async def main():
+    options = await process_ip_or_options("192.168.1.100")
+    device = await RpcDevice.create(None, options)
+    await device.initialize()
+    print(f"Device model: {device.model}")
+    print(f"Firmware version: {device.firmware_version}")
+    await device.shutdown()
+
+asyncio.run(main())
+```
+
+## Requirements
+
+- Python 3.12+
+- aiohttp
+- yarl
+- orjson (optional, for better performance)
+
+## License
+
+MIT
+
+## Support
+
+- Email: support@refoss.net
+- Issues: https://github.com/ashionky/aiorefoss/issues

aiorefoss-1.0.3/README.md

@@ -0,0 +1,57 @@
+# aiorefoss
+
+Asynchronous Python library for Refoss smart devices, designed for Home Assistant integration.
+
+## Features
+
+- Async WebSocket connection
+- Device authentication support for new firmware (EM16P v3.1.11+)
+- Automatic auth challenge handling
+- Real-time status updates
+- Device configuration management
+- Cross-platform JSON support (orjson with stdlib fallback)
+
+## Installation
+
+```bash
+pip install aiorefoss
+```
+
+With faster JSON support:
+```bash
+pip install aiorefoss[fastjson]
+```
+
+## Quick Start
+
+```python
+import asyncio
+from aiorefoss.rpc_device.device import RpcDevice
+from aiorefoss.common import process_ip_or_options
+
+async def main():
+    options = await process_ip_or_options("192.168.1.100")
+    device = await RpcDevice.create(None, options)
+    await device.initialize()
+    print(f"Device model: {device.model}")
+    print(f"Firmware version: {device.firmware_version}")
+    await device.shutdown()
+
+asyncio.run(main())
+```
+
+## Requirements
+
+- Python 3.12+
+- aiohttp
+- yarl
+- orjson (optional, for better performance)
+
+## License
+
+MIT
+
+## Support
+
+- Email: support@refoss.net
+- Issues: https://github.com/ashionky/aiorefoss/issues

aiorefoss-1.0.3/aiorefoss/__init__.py

@@ -0,0 +1,36 @@
+"""Refoss asynchronous Python library for Home Assistant.
+
+This library provides async support for Refoss smart devices using WebSocket.
+"""
+
+__version__ = "1.0.3"
+
+from .common import ConnectionOptions, IpOrOptionsType, get_info, process_ip_or_options
+from .exceptions import (
+    DeviceConnectionError,
+    DeviceConnectionTimeoutError,
+    InvalidAuthError,
+    MacAddressMismatchError,
+    NotInitialized,
+    RefossError,
+    RpcCallError,
+    WrongRefoss,
+)
+from .rpc_device.device import RpcDevice, RpcUpdateType
+
+__all__ = [
+    "ConnectionOptions",
+    "DeviceConnectionError",
+    "DeviceConnectionTimeoutError",
+    "InvalidAuthError",
+    "IpOrOptionsType",
+    "MacAddressMismatchError",
+    "NotInitialized",
+    "RefossError",
+    "RpcCallError",
+    "RpcDevice",
+    "RpcUpdateType",
+    "WrongRefoss",
+    "get_info",
+    "process_ip_or_options",
+]

aiorefoss-1.0.3/aiorefoss/common.py

@@ -0,0 +1,150 @@
+"""Common code for Refoss library."""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import logging
+from dataclasses import dataclass
+from socket import gethostbyname
+from typing import Any, cast
+
+from aiohttp import BasicAuth, ClientSession, ClientTimeout
+from yarl import URL
+
+from .const import (
+    CONNECT_ERRORS,
+    DEFAULT_HTTP_PORT,
+    DEVICE_IO_TIMEOUT,
+)
+from .exceptions import (
+    DeviceConnectionError,
+    DeviceConnectionTimeoutError,
+    MacAddressMismatchError,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+DEVICE_IO_TIMEOUT_CLIENT_TIMEOUT = ClientTimeout(total=DEVICE_IO_TIMEOUT)
+
+
+@dataclass(slots=True)
+class ConnectionOptions:
+    """Refoss options for connection."""
+
+    ip_address: str
+    username: str | None = None
+    password: str | None = None
+    device_mac: str | None = None
+    port: int = DEFAULT_HTTP_PORT
+    auth: BasicAuth | None = None
+
+    def __post_init__(self) -> None:
+        """Call after initialization."""
+        if self.username is not None:
+            if self.password is None:
+                raise ValueError("Supply both username and password")
+            object.__setattr__(self, "auth", BasicAuth(self.username, self.password))
+
+
+IpOrOptionsType = str | ConnectionOptions
+
+
+async def process_ip_or_options(ip_or_options: IpOrOptionsType) -> ConnectionOptions:
+    """Return ConnectionOptions class from ip str or ConnectionOptions."""
+    if isinstance(ip_or_options, str):
+        options = ConnectionOptions(ip_or_options)
+    else:
+        options = ip_or_options
+
+    try:
+        ipaddress.ip_address(options.ip_address)
+    except ValueError:
+        loop = asyncio.get_running_loop()
+        options.ip_address = await loop.run_in_executor(
+            None, gethostbyname, options.ip_address
+        )
+
+    return options
+
+
+async def get_info(
+    aiohttp_session: ClientSession,
+    ip_address: str,
+    device_mac: str | None = None,
+    port: int = DEFAULT_HTTP_PORT,
+) -> dict[str, Any]:
+    """Get info from device through REST call."""
+    url = URL.build(
+        scheme="http",
+        host=ip_address,
+        port=port,
+        path="/rpc/Refoss.DeviceInfo.Get",
+    )
+
+    try:
+        async with aiohttp_session.get(
+            url,
+            raise_for_status=True,
+            timeout=DEVICE_IO_TIMEOUT_CLIENT_TIMEOUT,
+        ) as resp:
+            result: dict[str, Any] = await resp.json()
+    except TimeoutError as err:
+        error = DeviceConnectionTimeoutError(err)
+        _LOGGER.warning(
+            "host %s:%s: Connection timeout while fetching device info: %r",
+            ip_address,
+            port,
+            error,
+        )
+        raise error from err
+    except CONNECT_ERRORS as err:
+        error = DeviceConnectionError(err)
+        _LOGGER.warning(
+            "host %s:%s: Connection error while fetching device info: %r",
+            ip_address,
+            port,
+            error,
+        )
+        raise error from err
+
+    try:
+        mac = result["mac"]
+    except KeyError as err:
+        error = DeviceConnectionError(f"Device response missing 'mac' field: {result}")
+        _LOGGER.error(
+            "host %s:%s: Invalid device info response, missing mac field: %s",
+            ip_address,
+            port,
+            result,
+        )
+        raise error from err
+
+    if device_mac and device_mac != mac:
+        error = MacAddressMismatchError(f"Input MAC: {device_mac}, Refoss MAC: {mac}")
+        _LOGGER.warning(
+            "host %s:%s: MAC address mismatch: expected=%s, got=%s",
+            ip_address,
+            port,
+            device_mac,
+            mac,
+        )
+        raise error
+
+    return result
+
+
+def fmt_macaddress(macaddress: str):
+    """internal component macaddress representation (lowercase without dots/colons)"""
+    return macaddress.replace(":", "").lower()
+
+
+def mac_address_from_name(name: str) -> str | None:
+    """Convert a name to a mac address."""
+    mac = name.partition(".")[0].partition("-")[-1]
+    return mac.lower() if len(mac) == 12 else None
+
+
+def get_info_auth(info: dict[str, Any]) -> bool:
+    """Return true if device has authorization enabled."""
+    return cast(bool, info.get("auth_en"))

aiorefoss-1.0.3/aiorefoss/const.py

@@ -0,0 +1,37 @@
+"""Constants for refoss."""
+
+from enum import Enum
+
+import aiohttp
+
+from .exceptions import DeviceConnectionError
+
+CONNECT_ERRORS = (aiohttp.ClientError, DeviceConnectionError, OSError)
+
+
+class UndefinedType(Enum):
+    """Singleton type for use with not set sentinel values."""
+
+    _singleton = 0
+
+
+UNDEFINED = UndefinedType._singleton
+
+
+# Timeout used for Device IO
+DEVICE_IO_TIMEOUT = 10.0
+
+# Timeout used for polling
+DEVICE_POLL_TIMEOUT = 20.0
+
+# Timeout used for initial connection calls
+# after the connection has been established
+DEVICE_INIT_TIMEOUT = 30.0
+
+
+WS_HEARTBEAT = 30
+
+# Notification sent by  device in case of WebSocket close
+NOTIFY_WS_CLOSED = "NotifyWebSocketClosed"
+
+DEFAULT_HTTP_PORT = 80

aiorefoss-1.0.3/aiorefoss/exceptions.py

@@ -0,0 +1,53 @@
+"""Refoss exceptions."""
+
+from __future__ import annotations
+
+
+class RefossError(Exception):
+    """Base class for aioRefoss errors."""
+
+
+class ConnectionClosed(RefossError):
+    """Exception raised when the connection is closed."""
+
+
+class InvalidMessage(RefossError):
+    """Exception raised when an invalid message is received."""
+
+
+class NotInitialized(RefossError):
+    """Raised if device is not initialized."""
+
+
+class WrongRefoss(RefossError):
+    """Exception raised to indicate wrong Refoss generation."""
+
+
+# Errors to be handled by the caller:
+#    Errors that are expected to happen and should be handled by the caller.
+
+
+class DeviceConnectionError(RefossError):
+    """Exception indicates device connection errors."""
+
+
+class DeviceConnectionTimeoutError(DeviceConnectionError):
+    """Exception indicates device connection timeout errors."""
+
+
+class InvalidAuthError(RefossError):
+    """Raised to indicate invalid or missing authentication error."""
+
+
+class MacAddressMismatchError(RefossError):
+    """Raised if input MAC address does not match the device MAC address."""
+
+
+class RpcCallError(RefossError):
+    """Raised to indicate errors in RPC call."""
+
+    def __init__(self, code: int, message: str = "") -> None:
+        """Initialize JSON RPC errors."""
+        self.code = code
+        self.message = message
+        super().__init__(code, message)

aiorefoss-1.0.3/aiorefoss/json.py

@@ -0,0 +1,56 @@
+"""JSON helper.
+
+Uses orjson for better performance if available, falls back to standard library json.
+"""
+
+import json
+from typing import Any
+
+try:
+    import orjson
+
+    JSONDecodeError = orjson.JSONDecodeError
+    json_loads = orjson.loads
+    _has_orjson = True
+
+    def json_encoder_default(obj: Any) -> Any:
+        """Convert objects for orjson."""
+        if isinstance(obj, set | tuple):
+            return list(obj)
+        raise TypeError
+
+    def json_dumps(data: Any) -> str:
+        """Dump json string using orjson."""
+        return orjson.dumps(
+            data,
+            option=orjson.OPT_NON_STR_KEYS,
+            default=json_encoder_default,
+        ).decode("utf-8")
+
+    def json_bytes(data: Any) -> bytes:
+        """Dump json bytes using orjson."""
+        return orjson.dumps(
+            data,
+            option=orjson.OPT_NON_STR_KEYS,
+            default=json_encoder_default,
+        )
+
+except ImportError:
+    # Fallback to standard library json
+    JSONDecodeError = json.JSONDecodeError
+    json_loads = json.loads
+    _has_orjson = False
+
+    def _json_encoder_default(obj: Any) -> Any:
+        """Convert objects for standard json."""
+        if isinstance(obj, set | tuple):
+            return list(obj)
+        raise TypeError
+
+    def json_dumps(data: Any) -> str:
+        """Dump json string using standard library json."""
+        return json.dumps(data, default=_json_encoder_default)
+
+    def json_bytes(data: Any) -> bytes:
+        """Dump json bytes using standard library json."""
+        return json.dumps(data, default=_json_encoder_default).encode("utf-8")

aiorefoss-1.0.3/aiorefoss/rpc_device/__init__.py

@@ -0,0 +1,5 @@
+"""Refoss device."""
+
+from .device import RpcDevice, RpcUpdateType
+
+__all__ = ["RpcDevice", "RpcUpdateType"]