pyhems 0.1.0__tar.gz

pyhems-0.1.0/LICENSE

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

pyhems-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: pyhems
+Version: 0.1.0
+Summary: ECHONET Lite library for Home Energy Management System (HEMS)
+Author: Sayurin
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bidict>=0.23.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# pyhems
+
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+ECHONET Lite library for Home Energy Management System (HEMS).
+
+**[🇯🇵 日本語ドキュメント](README.ja.md)**
+
+## Features
+
+- ECHONET Lite frame encoding/decoding
+- UDP multicast device discovery
+- Async runtime client with event subscription
+- MRA (Machine Readable Appendix) data fetcher
+- Full type hints (`py.typed`)
+
+## Requirements
+
+- Python 3.13+
+- bidict>=0.23.0
+
+## License
+
+MIT License
+
+## Installation
+
+```bash
+pip install pyhems
+```
+
+## Quick Start
+
+```python
+import asyncio
+from pyhems.runtime import HemsClient, HemsInstanceListEvent
+
+async def main():
+    client = HemsClient(interface="0.0.0.0")
+    await client.start()
+
+    def on_event(event):
+        if isinstance(event, HemsInstanceListEvent):
+            print(f"Node: {event.node_id}, Instances: {event.instances}")
+
+    unsubscribe = client.subscribe(on_event)
+    await asyncio.sleep(60)
+    unsubscribe()
+    await client.stop()
+
+asyncio.run(main())
+```

pyhems-0.1.0/README.md

@@ -0,0 +1,53 @@
+# pyhems
+
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+ECHONET Lite library for Home Energy Management System (HEMS).
+
+**[🇯🇵 日本語ドキュメント](README.ja.md)**
+
+## Features
+
+- ECHONET Lite frame encoding/decoding
+- UDP multicast device discovery
+- Async runtime client with event subscription
+- MRA (Machine Readable Appendix) data fetcher
+- Full type hints (`py.typed`)
+
+## Requirements
+
+- Python 3.13+
+- bidict>=0.23.0
+
+## License
+
+MIT License
+
+## Installation
+
+```bash
+pip install pyhems
+```
+
+## Quick Start
+
+```python
+import asyncio
+from pyhems.runtime import HemsClient, HemsInstanceListEvent
+
+async def main():
+    client = HemsClient(interface="0.0.0.0")
+    await client.start()
+
+    def on_event(event):
+        if isinstance(event, HemsInstanceListEvent):
+            print(f"Node: {event.node_id}, Instances: {event.instances}")
+
+    unsubscribe = client.subscribe(on_event)
+    await asyncio.sleep(60)
+    unsubscribe()
+    await client.stop()
+
+asyncio.run(main())
+```

pyhems-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyhems"
+version = "0.1.0"
+license = "MIT"
+license-files = ["LICENSE"]
+description = "ECHONET Lite library for Home Energy Management System (HEMS)"
+readme = "README.md"
+authors = [
+    {name = "Sayurin"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "bidict>=0.23.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "pytest-cov>=4.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+required-version = ">=0.13.0"
+
+[tool.ruff.lint]
+select = [
+  "E",      # pycodestyle errors
+  "W",      # pycodestyle warnings
+  "F",      # pyflakes
+  "I",      # isort
+  "B",      # flake8-bugbear
+  "C4",     # flake8-comprehensions
+  "UP",     # pyupgrade
+  "D",      # pydocstyle (docstrings)
+  "RUF",    # ruff-specific
+  "ASYNC",  # flake8-async
+  "PT",     # flake8-pytest-style
+  "SIM",    # flake8-simplify
+  "T20",    # flake8-print
+]
+
+ignore = [
+  "E501",   # line too long (formatter handles this)
+  "D100",   # Missing docstring in public module
+  "D104",   # Missing docstring in public package
+  "D202",   # No blank lines allowed after function docstring
+  "D203",   # 1 blank line required before class docstring (conflicts with D211)
+  "D213",   # Multi-line docstring summary should start at the second line (conflicts with D212)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D103", "S101"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+strict = false
+
+[tool.codespell]
+skip = "./.*,*.csv,*.json"
+quiet-level = 2

pyhems-0.1.0/setup.cfg

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

pyhems-0.1.0/src/pyhems/__init__.py

@@ -0,0 +1,62 @@
+"""pyhems - ECHONET Lite library for HEMS."""
+
+from .const import (
+    CONTROLLER_CLASS,
+    CONTROLLER_INSTANCE,
+    DISCOVERY_DEFAULT_EPCS,
+    ECHONET_MULTICAST,
+    ECHONET_PORT,
+    EPC_IDENTIFICATION_NUMBER,
+    EPC_INSTANCE_LIST,
+    EPC_MANUFACTURER_CODE,
+    EPC_PRODUCT_CODE,
+    EPC_SELF_NODE_INSTANCE_LIST,
+    EPC_SERIAL_NUMBER,
+    ESV_GET,
+    ESV_GET_RES,
+    ESV_GET_SNA,
+    ESV_INF,
+    ESV_INF_REQ,
+    ESV_INF_SNA,
+    ESV_SET_RES,
+    ESV_SET_SNA,
+    ESV_SETC,
+    NODE_PROFILE_CLASS,
+    NODE_PROFILE_INSTANCE,
+)
+from .frame import Frame, Property
+from .transport import EchonetLiteProtocol, create_multicast_socket
+from .utils import decode_ascii_property, parse_property_map
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CONTROLLER_CLASS",
+    "CONTROLLER_INSTANCE",
+    "DISCOVERY_DEFAULT_EPCS",
+    "ECHONET_MULTICAST",
+    "ECHONET_PORT",
+    "EPC_IDENTIFICATION_NUMBER",
+    "EPC_INSTANCE_LIST",
+    "EPC_MANUFACTURER_CODE",
+    "EPC_PRODUCT_CODE",
+    "EPC_SELF_NODE_INSTANCE_LIST",
+    "EPC_SERIAL_NUMBER",
+    "ESV_GET",
+    "ESV_GET_RES",
+    "ESV_GET_SNA",
+    "ESV_INF",
+    "ESV_INF_REQ",
+    "ESV_INF_SNA",
+    "ESV_SETC",
+    "ESV_SET_RES",
+    "ESV_SET_SNA",
+    "NODE_PROFILE_CLASS",
+    "NODE_PROFILE_INSTANCE",
+    "EchonetLiteProtocol",
+    "Frame",
+    "Property",
+    "create_multicast_socket",
+    "decode_ascii_property",
+    "parse_property_map",
+]

pyhems-0.1.0/src/pyhems/const.py

@@ -0,0 +1,42 @@
+"""Constants for ECHONET Lite protocol and HEMS communication."""
+
+# ECHONET Lite Transport
+ECHONET_PORT = 3610
+ECHONET_MULTICAST = "224.0.23.0"
+
+# Node Profile
+NODE_PROFILE_CLASS = 0x0EF0
+NODE_PROFILE_INSTANCE = 0x0EF001
+
+# Controller
+CONTROLLER_CLASS = 0x05FF
+CONTROLLER_INSTANCE = 0x05FF01
+
+# ESV (Service Codes)
+ESV_SET_SNA = 0x51  # Set response with some properties unavailable
+ESV_GET_SNA = 0x52  # Get response with some properties unavailable
+ESV_INF_SNA = 0x53  # Notification request SNA
+ESV_SETC = 0x61  # Set with response
+ESV_GET = 0x62  # Get request
+ESV_INF_REQ = 0x63  # Notification request
+ESV_SET_RES = 0x71  # Set response
+ESV_GET_RES = 0x72  # Get response
+ESV_INF = 0x73  # Notification
+
+# EPC (Property Codes)
+EPC_IDENTIFICATION_NUMBER = 0x83
+EPC_MANUFACTURER_CODE = 0x8A
+EPC_PRODUCT_CODE = 0x8C
+EPC_SERIAL_NUMBER = 0x8D
+EPC_INSTANCE_LIST = 0xD5
+EPC_SELF_NODE_INSTANCE_LIST = 0xD6
+
+# Default EPCs for node discovery (required for identification)
+DISCOVERY_DEFAULT_EPCS: list[int] = [
+    EPC_IDENTIFICATION_NUMBER,
+    EPC_SELF_NODE_INSTANCE_LIST,
+]
+
+# Retry settings for Get requests
+GET_TIMEOUT = 5.0  # Seconds to wait for response
+GET_MAX_RETRIES = 3  # Maximum retry attempts for failed properties

pyhems-0.1.0/src/pyhems/discovery.py

@@ -0,0 +1,44 @@
+"""ECHONET Lite device discovery utilities."""
+
+from .const import (
+    EPC_IDENTIFICATION_NUMBER,
+    EPC_INSTANCE_LIST,
+    EPC_SELF_NODE_INSTANCE_LIST,
+)
+from .frame import Frame
+
+
+def extract_discovery_info(frame: Frame) -> tuple[str | None, list[int]]:
+    """Extract node_id and instance list from a frame.
+
+    Args:
+        frame: The received frame.
+
+    Returns:
+        Tuple of (node_id, instances).
+        node_id is None if not found.
+        instances is a list of instance EOJs.
+
+    """
+    node_id: str | None = None
+    instances: list[int] = []
+
+    for prop in frame.properties:
+        if not prop.edt:
+            continue
+        if prop.epc == EPC_IDENTIFICATION_NUMBER:
+            # Identification number (0x83)
+            # Format: 1 byte protocol type (0xFE) + 16 bytes unique ID
+            # We use the hex string representation of the whole value
+            node_id = prop.edt.hex()
+        elif prop.epc in (EPC_INSTANCE_LIST, EPC_SELF_NODE_INSTANCE_LIST):
+            # Decode instance list from EDT
+            # Format: 1 byte count + (count * 3 bytes for each EOJ)
+            count = prop.edt[0]
+            for i in range(count):
+                offset = 1 + (i * 3)
+                if offset + 3 <= len(prop.edt):
+                    eoj = int.from_bytes(prop.edt[offset : offset + 3], "big")
+                    instances.append(eoj)
+
+    return node_id, instances

pyhems-0.1.0/src/pyhems/frame.py

@@ -0,0 +1,102 @@
+"""ECHONET Lite protocol frame handling."""
+
+from dataclasses import dataclass, field
+from typing import Self
+
+
+@dataclass(slots=True)
+class Property:
+    """ECHONET Lite property in a frame."""
+
+    epc: int
+    edt: bytes = field(default=b"")
+
+    @property
+    def pdc(self) -> int:
+        """Return the property data counter (length of EDT)."""
+        return len(self.edt)
+
+    def __repr__(self) -> str:
+        """Return a string representation of the property."""
+        return f"Property(epc=0x{self.epc:02X}, edt={self.edt.hex()})"
+
+
+@dataclass(slots=True)
+class Frame:
+    """ECHONET Lite frame structure."""
+
+    seoj: bytes
+    deoj: bytes
+    esv: int
+    tid: int = 0
+    properties: list[Property] = field(default_factory=list)
+
+    # ECHONET Lite header constants
+    EHD1 = 0x10  # ECHONET Lite
+    EHD2 = 0x81  # Format 1
+
+    # Class-level TID generator
+    _tid_counter = 0
+
+    def is_response_frame(self) -> bool:
+        """Check if frame is a response (success or failure).
+
+        Success responses: 0x70-0x7F
+        Failure responses: 0x50-0x5F
+        """
+        return (0x70 <= self.esv <= 0x7F) or (0x50 <= self.esv <= 0x5F)
+
+    @classmethod
+    def next_tid(cls) -> int:
+        """Generate next transaction ID."""
+        cls._tid_counter = cls._tid_counter + 1
+        if cls._tid_counter > 0xFFFF:
+            cls._tid_counter = 1
+        return cls._tid_counter
+
+    @classmethod
+    def decode(cls, data: bytes) -> Self:
+        """Decode an ECHONET Lite frame from bytes."""
+        if len(data) < 12:
+            raise ValueError("Frame too short")
+
+        ehd1, ehd2 = data[0], data[1]
+        if ehd1 != cls.EHD1 or ehd2 != cls.EHD2:
+            raise ValueError(f"Invalid ECHONET Lite header: {ehd1:#x} {ehd2:#x}")
+
+        tid = int.from_bytes(data[2:4], "big")
+        seoj = data[4:7]
+        deoj = data[7:10]
+        esv = data[10]
+        opc = data[11]
+
+        properties: list[Property] = []
+        offset = 12
+        for _ in range(opc):
+            if offset >= len(data):
+                raise ValueError("Incomplete property data")
+            epc = data[offset]
+            pdc = data[offset + 1]
+            edt = data[offset + 2 : offset + 2 + pdc]
+            properties.append(Property(epc=epc, edt=edt))
+            offset += 2 + pdc
+
+        return cls(seoj=seoj, deoj=deoj, esv=esv, tid=tid, properties=properties)
+
+    def encode(self) -> bytes:
+        """Encode the frame to bytes."""
+        result = bytearray()
+        result.append(self.EHD1)
+        result.append(self.EHD2)
+        result.extend(self.tid.to_bytes(2, "big"))
+        result.extend(self.seoj)
+        result.extend(self.deoj)
+        result.append(self.esv)
+        result.append(len(self.properties))
+
+        for prop in self.properties:
+            result.append(prop.epc)
+            result.append(prop.pdc)
+            result.extend(prop.edt)
+
+        return bytes(result)