pysamsungnasa 0.4.0__tar.gz

pysamsungnasa-0.4.0/LICENSE

@@ -0,0 +1 @@
+    MIT License

pysamsungnasa-0.4.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: pysamsungnasa
+Version: 0.4.0
+Summary: Connect to Samsung ASHP / AC units over NASA via RS485
+Author-email: Jordan Harvey <jordan@hrvy.uk>
+Requires-Python: >=3.13.0
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+License-File: LICENSE
+Requires-Dist: aiotelnet~=1.1.0
+Requires-Dist: prompt_toolkit>=3.0.0 ; extra == "cli"
+Requires-Dist: python-dotenv>=0.9.9 ; extra == "cli"
+Requires-Dist: mkdocs>=1.4.0 ; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0 ; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.23.0 ; extra == "docs"
+Requires-Dist: griffe>=0.40 ; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.0 ; extra == "docs"
+Requires-Dist: bandit[toml]==1.9.2 ; extra == "test"
+Requires-Dist: black==25.12.0 ; extra == "test"
+Requires-Dist: check-manifest==0.51 ; extra == "test"
+Requires-Dist: flake8-bugbear==25.11.29 ; extra == "test"
+Requires-Dist: flake8-docstrings ; extra == "test"
+Requires-Dist: flake8-formatter_junit_xml ; extra == "test"
+Requires-Dist: flake8 ; extra == "test"
+Requires-Dist: flake8-pyproject ; extra == "test"
+Requires-Dist: pre-commit==4.5.1 ; extra == "test"
+Requires-Dist: pylint==4.0.4 ; extra == "test"
+Requires-Dist: pylint_junit ; extra == "test"
+Requires-Dist: pytest-cov==7.0.0 ; extra == "test"
+Requires-Dist: pytest-mock<3.15.2 ; extra == "test"
+Requires-Dist: pytest-runner ; extra == "test"
+Requires-Dist: pytest-asyncio==1.3.0 ; extra == "test"
+Requires-Dist: pytest==9.0.2 ; extra == "test"
+Requires-Dist: pytest-github-actions-annotate-failures ; extra == "test"
+Requires-Dist: shellcheck-py==0.11.0.1 ; extra == "test"
+Project-URL: Documentation, https://github.com/pantherale0/pysamsungnasa
+Project-URL: Source, https://github.com/pantherale0/pysamsungnasa
+Project-URL: Tracker, https://github.com/pantherale0/pysamsungnasa/issues
+Provides-Extra: cli
+Provides-Extra: docs
+Provides-Extra: test
+
+# pysamsungnasa
+
+[![Tests](https://github.com/pantherale0/pysamsungnasa/actions/workflows/test.yml/badge.svg)](https://github.com/pantherale0/pysamsungnasa/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/pantherale0/pysamsungnasa/branch/main/graph/badge.svg)](https://codecov.io/gh/pantherale0/pysamsungnasa)
+
+A Python library to communicate with Samsung heat pumps, in theory both cool only and cool+heat units are supported, although only tested on an EHS unit (cool+heat)
+
+## Features
+
+- Connect and disconnect from Samsung HVAC/EHS units via a TCP socket over the F1/F2 connectors (NasaClient).
+- Discover new devices on the NASA network and manage known devices (SamsungNasa).
+- Send commands to devices and handle responses (SamsungNasa, NasaClient).
+- Parse incoming data packets from devices (NasaPacketParser, various message classes).
+- Represent devices with attributes and control their functions (NasaDevice, DhwController, ClimateController).
+- Control DHW (Domestic Hot Water) settings like power, operation mode, and target temperature (DhwController).
+- Control climate settings like power, mode, target temperature, fan speed, and more (ClimateController).
+- Provide a mechanism for callbacks to be notified of device and packet updates (NasaDevice).
+- Support reading device configurations (NasaDevice).
+- Handle message construction and parsing based on message types (protocol.factory).
+- Define specific message formats for indoor and outdoor units (protocol.factory.messages).
+
+## Future plans
+
+These might not end up happening, but I would like to have a go at creating these one day.
+
+- Simulate a remote controller for a "dummy" zone 2
+- Send custom Z1/Z2 temperature readings to the master controller
+- Implement TPI/load awareness/preditive model algorithms for an advanced complete custom controller
+
+## Installation
+
+```bash
+pip install pysamsungnasa
+```
+
+## Usage
+
+TODO
+
+## Configuration
+
+TODO
+
+## Contributing
+
+TODO
+
+## Thanks
+
+This project utilizes or incorporates ideas, code and work from the following sources,
+and I would like to express my sincere gratitude to their creators and contributors:
+
+- [ESPHome Samsung HVAC Bus](https://github.com/omerfaruk-aran/esphome_samsung_hvac_bus/)
+- [Samsung NASA MQTT Bridge](https://github.com/70p4z/samsung-nasa-mqtt/)
+- [Samsung ASHP NASA link MQTT bridge / Home Assistant](https://community.openenergymonitor.org/t/contribution-samsung-ashp-nasa-link-mqtt-bridge-home-assistant)
+- [OpenEnergyMonitoring Forum](https://community.openenergymonitor.org/search?q=samsung) for all the shared wisdom on multiple threads.
+- @betaphi for the [EHS Wiki](https://wiki.myehs.eu/wiki/Main_Page), which provided valuable insights into different messages. The protocol is mostly documented [here](NOTES.md) as the NASA Protocol page is no longer on the wiki. More messages are defined within the parser classes from the latest version of S-Net.
+
+None of this would have been possible without the above.
+

pysamsungnasa-0.4.0/README.md

@@ -0,0 +1,59 @@
+# pysamsungnasa
+
+[![Tests](https://github.com/pantherale0/pysamsungnasa/actions/workflows/test.yml/badge.svg)](https://github.com/pantherale0/pysamsungnasa/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/pantherale0/pysamsungnasa/branch/main/graph/badge.svg)](https://codecov.io/gh/pantherale0/pysamsungnasa)
+
+A Python library to communicate with Samsung heat pumps, in theory both cool only and cool+heat units are supported, although only tested on an EHS unit (cool+heat)
+
+## Features
+
+- Connect and disconnect from Samsung HVAC/EHS units via a TCP socket over the F1/F2 connectors (NasaClient).
+- Discover new devices on the NASA network and manage known devices (SamsungNasa).
+- Send commands to devices and handle responses (SamsungNasa, NasaClient).
+- Parse incoming data packets from devices (NasaPacketParser, various message classes).
+- Represent devices with attributes and control their functions (NasaDevice, DhwController, ClimateController).
+- Control DHW (Domestic Hot Water) settings like power, operation mode, and target temperature (DhwController).
+- Control climate settings like power, mode, target temperature, fan speed, and more (ClimateController).
+- Provide a mechanism for callbacks to be notified of device and packet updates (NasaDevice).
+- Support reading device configurations (NasaDevice).
+- Handle message construction and parsing based on message types (protocol.factory).
+- Define specific message formats for indoor and outdoor units (protocol.factory.messages).
+
+## Future plans
+
+These might not end up happening, but I would like to have a go at creating these one day.
+
+- Simulate a remote controller for a "dummy" zone 2
+- Send custom Z1/Z2 temperature readings to the master controller
+- Implement TPI/load awareness/preditive model algorithms for an advanced complete custom controller
+
+## Installation
+
+```bash
+pip install pysamsungnasa
+```
+
+## Usage
+
+TODO
+
+## Configuration
+
+TODO
+
+## Contributing
+
+TODO
+
+## Thanks
+
+This project utilizes or incorporates ideas, code and work from the following sources,
+and I would like to express my sincere gratitude to their creators and contributors:
+
+- [ESPHome Samsung HVAC Bus](https://github.com/omerfaruk-aran/esphome_samsung_hvac_bus/)
+- [Samsung NASA MQTT Bridge](https://github.com/70p4z/samsung-nasa-mqtt/)
+- [Samsung ASHP NASA link MQTT bridge / Home Assistant](https://community.openenergymonitor.org/t/contribution-samsung-ashp-nasa-link-mqtt-bridge-home-assistant)
+- [OpenEnergyMonitoring Forum](https://community.openenergymonitor.org/search?q=samsung) for all the shared wisdom on multiple threads.
+- @betaphi for the [EHS Wiki](https://wiki.myehs.eu/wiki/Main_Page), which provided valuable insights into different messages. The protocol is mostly documented [here](NOTES.md) as the NASA Protocol page is no longer on the wiki. More messages are defined within the parser classes from the latest version of S-Net.
+
+None of this would have been possible without the above.

pysamsungnasa-0.4.0/pyproject.toml

@@ -0,0 +1,310 @@
+[build-system]
+requires = ["flit_core >=2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name =  "pysamsungnasa"
+authors = [
+    {name = "Jordan Harvey", email = "jordan@hrvy.uk"},
+]
+description = "Connect to Samsung ASHP / AC units over NASA via RS485"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13"
+]
+requires-python = ">=3.13.0"
+dynamic = ["version"]
+dependencies = [
+    "aiotelnet~=1.1.0"
+]
+
+[project.optional-dependencies]
+cli = [
+    "prompt_toolkit>=3.0.0",
+    "python-dotenv>=0.9.9"
+]
+docs = [
+    "mkdocs>=1.4.0",
+    "mkdocs-material>=9.0.0",
+    "mkdocstrings[python]>=0.23.0",
+    "griffe>=0.40",
+    "pymdown-extensions>=10.0"
+]
+test = [
+    "bandit[toml]==1.9.2",
+    "black==25.12.0",
+    "check-manifest==0.51",
+    "flake8-bugbear==25.11.29",
+    "flake8-docstrings",
+    "flake8-formatter_junit_xml",
+    "flake8",
+    "flake8-pyproject",
+    "pre-commit==4.5.1",
+    "pylint==4.0.4",
+    "pylint_junit",
+    "pytest-cov==7.0.0",
+    "pytest-mock<3.15.2",
+    "pytest-runner",
+    "pytest-asyncio==1.3.0",
+    "pytest==9.0.2",
+    "pytest-github-actions-annotate-failures",
+    "shellcheck-py==0.11.0.1"
+]
+
+[project.urls]
+Documentation = "https://github.com/pantherale0/pysamsungnasa"
+Source = "https://github.com/pantherale0/pysamsungnasa"
+Tracker = "https://github.com/pantherale0/pysamsungnasa/issues"
+
+[tool.flit.module]
+name = "pysamsungnasa"
+
+[tool.bandit]
+exclude_dirs = ["build","dist","tests","scripts"]
+number = 4
+recursive = true
+targets = "src/pysamsungnasa"
+
+[tool.black]
+line-length = 120
+fast = true
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+
+[tool.flake8]
+max-line-length = 120
+select = "F,E,W,B,B901,B902,B903"
+exclude = [
+    ".eggs",
+    ".git",
+    ".tox",
+    "nssm",
+    "obj",
+    "out",
+    "packages",
+    "pywin32",
+    "tests",
+    "swagger_client"
+]
+ignore = [
+    "E722",
+    "B001",
+    "W503",
+    "E203"
+]
+
+[tool.pyright]
+include = ["src/pysamsungnasa"]
+exclude = [
+    "**/node_modules",
+    "**/__pycache__",
+]
+venv = "env37"
+
+reportMissingImports = true
+reportMissingTypeStubs = false
+
+pythonVersion = "3.13"
+pythonPlatform = "Linux"
+
+executionEnvironments = [
+  { root = "src/pysamsungnasa" }
+]
+
+[tool.pytest.ini_options]
+addopts = "--cov-report xml:coverage.xml --cov pysamsungnasa --cov-fail-under 0 --cov-append -m 'not integration'"
+pythonpath = [
+  "."
+]
+testpaths = "tests"
+junit_family = "xunit2"
+markers = [
+    "integration: marks as integration test",
+    "slow: marks tests as slow",
+    "unit: fast offline tests",
+]
+
+[tool.tox]
+legacy_tox_ini = """
+[tox]
+envlist = py, integration, all
+
+[testenv]
+commands =
+    pytest -m "not integration" {posargs}
+
+[testenv:integration]
+commands =
+    pytest -m "integration" {posargs}
+
+[testenv:all]
+extras = all
+commands =
+    pytest {posargs}
+"""
+
+[tool.pylint]
+extension-pkg-whitelist= [
+    "numpy",
+    "torch",
+    "cv2",
+    "pyodbc",
+    "pydantic",
+    "ciso8601",
+    "netcdf4",
+    "scipy"
+]
+ignore="CVS"
+ignore-patterns="test.*?py,conftest.py"
+init-hook='import sys; sys.setrecursionlimit(8 * sys.getrecursionlimit())'
+jobs=0
+limit-inference-results=100
+persistent="yes"
+suggestion-mode="yes"
+unsafe-load-any-extension="no"
+
+[tool.pylint.'MESSAGES CONTROL']
+enable="c-extension-no-member"
+
+[tool.pylint.'REPORTS']
+evaluation="10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)"
+output-format="text"
+reports="no"
+score="yes"
+
+[tool.pylint.'REFACTORING']
+max-nested-blocks=5
+never-returning-functions="sys.exit"
+
+[tool.pylint.'BASIC']
+argument-naming-style="snake_case"
+attr-naming-style="snake_case"
+bad-names= [
+    "foo",
+    "bar"
+]
+class-attribute-naming-style="any"
+class-naming-style="PascalCase"
+const-naming-style="UPPER_CASE"
+docstring-min-length=-1
+function-naming-style="snake_case"
+good-names= [
+    "i",
+    "j",
+    "k",
+    "ex",
+    "Run",
+    "_"
+]
+include-naming-hint="yes"
+inlinevar-naming-style="any"
+method-naming-style="snake_case"
+module-naming-style="any"
+no-docstring-rgx="^_"
+property-classes="abc.abstractproperty"
+variable-naming-style="snake_case"
+
+[tool.pylint.'FORMAT']
+ignore-long-lines="^\\s*(# )?.*['\"]?<?https?://\\S+>?"
+indent-after-paren=4
+indent-string='    '
+max-line-length=120
+max-module-lines=1000
+single-line-class-stmt="no"
+single-line-if-stmt="no"
+
+[tool.pylint.'LOGGING']
+logging-format-style="old"
+logging-modules="logging"
+
+[tool.pylint.'MISCELLANEOUS']
+notes= [
+    "FIXME",
+    "XXX",
+    "TODO"
+]
+
+[tool.pylint.'SIMILARITIES']
+ignore-comments="yes"
+ignore-docstrings="yes"
+ignore-imports="yes"
+min-similarity-lines=7
+
+[tool.pylint.'SPELLING']
+max-spelling-suggestions=4
+spelling-store-unknown-words="no"
+
+[tool.pylint.'STRING']
+check-str-concat-over-line-jumps="no"
+
+[tool.pylint.'TYPECHECK']
+contextmanager-decorators="contextlib.contextmanager"
+generated-members="numpy.*,np.*,collect_list"
+ignore-mixin-members="yes"
+ignore-none="yes"
+ignore-on-opaque-inference="yes"
+ignored-classes="optparse.Values,thread._local,_thread._local,numpy,torch,swagger_client"
+ignored-modules="numpy,torch,swagger_client,netCDF4,scipy"
+missing-member-hint="yes"
+missing-member-hint-distance=1
+missing-member-max-choices=1
+
+[tool.pylint.'VARIABLES']
+additional-builtins="dbutils"
+allow-global-unused-variables="yes"
+callbacks= [
+    "cb_",
+    "_cb"
+]
+dummy-variables-rgx="_+$|(_[a-zA-Z0-9_]*[a-zA-Z0-9]+?$)|dummy|^ignored_|^unused_"
+ignored-argument-names="_.*|^ignored_|^unused_"
+init-import="no"
+redefining-builtins-modules="six.moves,past.builtins,future.builtins,builtins,io"
+
+[tool.pylint.'CLASSES']
+defining-attr-methods= [
+    "__init__",
+    "__new__",
+    "setUp",
+    "__post_init__"
+]
+exclude-protected= [
+    "_asdict",
+    "_fields",
+    "_replace",
+    "_source",
+    "_make"
+]
+valid-classmethod-first-arg="cls"
+valid-metaclass-classmethod-first-arg="cls"
+
+[tool.pylint.'DESIGN']
+max-args=5
+max-attributes=7
+max-bool-expr=5
+max-branches=12
+max-locals=15
+max-parents=7
+max-public-methods=20
+max-returns=6
+max-statements=50
+min-public-methods=2
+
+[tool.pylint.'IMPORTS']
+allow-wildcard-with-all="no"
+analyse-fallback-blocks="no"
+deprecated-modules="optparse,tkinter.tix"
+
+[tool.pylint.'EXCEPTIONS']
+overgeneral-exceptions= [
+    "BaseException",
+    "Exception"
+]

pysamsungnasa-0.4.0/pysamsungnasa/__init__.py

@@ -0,0 +1,9 @@
+"""Samsung NASA."""
+
+from __future__ import annotations
+
+from .nasa import SamsungNasa
+
+__version__ = "0.4.0"
+
+__all__ = ["SamsungNasa"]

pysamsungnasa-0.4.0/pysamsungnasa/__main__.py

@@ -0,0 +1,70 @@
+"""Functionality to execute when run as a script."""
+
+# Uses cli.py to provide an interactive CLI for testing.
+# Environment variables can be used to set the host and port of the Samsung NASA device:
+
+import asyncio
+import os
+import logging
+from dotenv import load_dotenv
+
+from .nasa import SamsungNasa
+from .cli import interactive_cli
+
+load_dotenv()
+
+
+async def main():
+    """Main function to start the interactive CLI."""
+    if os.getenv("SAMSUNG_HP_HOST") is None or os.getenv("SAMSUNG_HP_PORT") is None:
+        print("Please set the SAMSUNG_HP_HOST and SAMSUNG_HP_PORT environment variables.", file=sys.stderr)
+        sys.exit(1)
+
+    nasa = SamsungNasa(
+        host=os.getenv("SAMSUNG_HP_HOST"),
+        port=int(os.getenv("SAMSUNG_HP_PORT")),
+        config={
+            "device_pnp": os.getenv("SAMSUNG_HP_DEVICE_PNP", "True").lower() in ("true", "1", "yes"),
+            "device_dump_only": os.getenv("SAMSUNG_HP_DEVICE_DUMP_ONLY", "False").lower() in ("true", "1", "yes"),
+            "log_all_messages": os.getenv("SAMSUNG_HP_LOG_ALL_MESSAGES", "False").lower() in ("true", "1", "yes"),
+            "log_buffer_messages": os.getenv("SAMSUNG_HP_LOG_BUFFER_MESSAGES", "False").lower() in ("true", "1", "yes"),
+            "messages_to_log": (
+                [int(x, 0) for x in os.getenv("SAMSUNG_HP_MESSAGES_TO_LOG", "").split(",") if x.strip()]
+                if os.getenv("SAMSUNG_HP_MESSAGES_TO_LOG")
+                else []
+            ),
+            "devices_to_log": (
+                [x.strip() for x in os.getenv("SAMSUNG_HP_DEVICES_TO_LOG", "").split(",") if x.strip()]
+                if os.getenv("SAMSUNG_HP_DEVICES_TO_LOG")
+                else []
+            ),
+        },
+    )
+    await nasa.start()
+    try:
+        await interactive_cli(nasa)
+    finally:
+        await nasa.stop()
+
+
+if __name__ == "__main__":
+    # Log to nasa.log in CWD at level defined by LOG_LEVEL env var (default DEBUG)
+    log_level = os.getenv("LOG_LEVEL", "DEBUG").upper()
+    logging.basicConfig(
+        level=getattr(logging, log_level, logging.DEBUG),
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        filename="nasa.log",
+        filemode="a",
+    )
+    # Add a logger for error messages to console
+    console = logging.StreamHandler()
+    console.setLevel(logging.ERROR)
+    formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    console.setFormatter(formatter)
+    logging.getLogger().addHandler(console)
+
+    # Suppress noisy aiotelnet.client debug logs
+    logging.getLogger("aiotelnet.client").setLevel(logging.INFO)
+
+    # Execute main
+    asyncio.run(main())

pysamsungnasa-0.4.0/pysamsungnasa/autodiscovery.py

@@ -0,0 +1,30 @@
+"""NASA Device Autodiscovery."""
+
+from .nasa import SamsungNasa
+from .nasa_client import NasaClient
+from .protocol.enum import DataType
+from .protocol.factory import build_message, SendMessage
+
+
+async def request_network_address(client: NasaClient):
+    """Request a network address from the client."""
+    await client.send_command(
+        message=[
+            build_message(
+                source="500000",
+                destination="B0FFFF",
+                messages=[SendMessage(MESSAGE_ID=hex(0x10000 + 0x210)[-4:], PAYLOAD=bytes.fromhex(hex(0x10000)[-4:]))],
+            )
+        ]
+    )
+
+
+async def autodiscover_devices(client: NasaClient):
+    """Send auto disocvery packets to the client."""
+
+
+async def nasa_poke(client: SamsungNasa):
+    """Send poke packets to the client."""
+    await client.send_message(
+        0x4242, payload=bytes.fromhex("FFFF"), destination="200000", request_type=DataType.REQUEST
+    )