pyairtouch3 0.1.0__tar.gz

pyairtouch3-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: pyairtouch3
+Version: 0.1.0
+Summary: Async Python client for AirTouch 3 controllers
+Author: pyairtouch3 contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/L0rdCha0s/pyairtouch3
+Project-URL: Repository, https://github.com/L0rdCha0s/pyairtouch3
+Project-URL: Issues, https://github.com/L0rdCha0s/pyairtouch3/issues
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+pyairtouch3
+===========
+
+Async Python client for AirTouch 3 controllers.
+
+The package contains the AirTouch 3 protocol models, message builders, response
+parser, TCP status/command client, and UDP discovery parser/scanner used by the
+Home Assistant `airtouch3` integration.

pyairtouch3-0.1.0/README.md

@@ -0,0 +1,8 @@
+pyairtouch3
+===========
+
+Async Python client for AirTouch 3 controllers.
+
+The package contains the AirTouch 3 protocol models, message builders, response
+parser, TCP status/command client, and UDP discovery parser/scanner used by the
+Home Assistant `airtouch3` integration.

pyairtouch3-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyairtouch3"
+version = "0.1.0"
+description = "Async Python client for AirTouch 3 controllers"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [
+  { name = "pyairtouch3 contributors" },
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "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",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Home Automation",
+]
+
+[project.urls]
+Homepage = "https://github.com/L0rdCha0s/pyairtouch3"
+Repository = "https://github.com/L0rdCha0s/pyairtouch3"
+Issues = "https://github.com/L0rdCha0s/pyairtouch3/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

pyairtouch3-0.1.0/setup.cfg

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

pyairtouch3-0.1.0/src/pyairtouch3/__init__.py

@@ -0,0 +1,41 @@
+"""Python client for AirTouch 3 controllers."""
+
+from .airtouch_aircon import Aircon
+from .airtouch_message import AirTouchMessage
+from .airtouch_sensor import Sensor
+from .airtouch_zone import AirtouchZone
+from .client import DEFAULT_PORT, RESPONSE_TIMEOUT, AirTouchClient, AirTouchError
+from .discovery import (
+    DISCOVERY_ATTEMPTS,
+    DISCOVERY_MESSAGE,
+    DISCOVERY_PORT,
+    DISCOVERY_SEND_INTERVAL,
+    AirTouch3Discovery,
+    async_discover_targets,
+    parse_discovery_payload,
+)
+from .enums import AcMode, ZoneStatus
+from .message_constants import MessageConstants
+from .message_response_parser import MessageResponseParser
+
+__all__ = [
+    "DEFAULT_PORT",
+    "DISCOVERY_ATTEMPTS",
+    "DISCOVERY_MESSAGE",
+    "DISCOVERY_PORT",
+    "DISCOVERY_SEND_INTERVAL",
+    "RESPONSE_TIMEOUT",
+    "AcMode",
+    "AirTouch3Discovery",
+    "AirTouchClient",
+    "AirTouchError",
+    "AirTouchMessage",
+    "Aircon",
+    "AirtouchZone",
+    "MessageConstants",
+    "MessageResponseParser",
+    "Sensor",
+    "ZoneStatus",
+    "async_discover_targets",
+    "parse_discovery_payload",
+]

pyairtouch3-0.1.0/src/pyairtouch3/airtouch_aircon.py

@@ -0,0 +1,116 @@
+"""Provides the Aircon class for controlling an AirTouch air conditioner."""
+
+import logging
+
+from .airtouch_sensor import Sensor
+from .airtouch_zone import AirtouchZone
+from .enums import AcMode
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class Aircon:
+    """Represents an AirTouch air conditioner object."""
+
+    def __init__(self, ac_id: int) -> None:
+        """Initialize the Aircon with the given AC identifier."""
+        self.ac_id = ac_id
+        self._zones: list[AirtouchZone] = []
+        self._sensors: list[Sensor] = []
+        self._status: bool = False
+        self._fan_speed: int = 0
+        self._room_temperature: float = 0
+        self._desired_temperature: int = 0
+        self._mode: AcMode = AcMode.AUTO
+        self._brand_id: int = 0
+        self._system_id: str = ""
+
+    @property
+    def zones(self) -> list[AirtouchZone]:
+        """Return the list of zones controlled by this AC."""
+        return self._zones
+
+    @zones.setter
+    def zones(self, new_zones: list[AirtouchZone]) -> None:
+        """Set the list of zones for this AC."""
+        self._zones = new_zones
+
+    @property
+    def sensors(self) -> list[Sensor]:
+        """Return the list of sensors associated with this AC."""
+        return self._sensors
+
+    @sensors.setter
+    def sensors(self, new_sensors: list[Sensor]) -> None:
+        """Set the list of sensors for this AC."""
+        self._sensors = new_sensors
+
+    @property
+    def status(self) -> bool:
+        """Return whether the AC unit is currently on (True) or off (False)."""
+        return self._status
+
+    @status.setter
+    def status(self, is_on: bool) -> None:
+        """Set the AC unit status."""
+        self._status = is_on
+
+    @property
+    def fan_speed(self) -> int:
+        """Return the current fan speed setting."""
+        return self._fan_speed
+
+    @fan_speed.setter
+    def fan_speed(self, speed: int) -> None:
+        """Set the fan speed of the AC."""
+        self._fan_speed = speed
+
+    @property
+    def room_temperature(self) -> float:
+        """Return the current room temperature as reported by the AC."""
+        return self._room_temperature
+
+    @room_temperature.setter
+    def room_temperature(self, temperature: float) -> None:
+        """Set the current room temperature for this AC."""
+        self._room_temperature = temperature
+
+    @property
+    def desired_temperature(self) -> int:
+        """Return the desired (target) temperature set on the AC."""
+        return self._desired_temperature
+
+    @desired_temperature.setter
+    def desired_temperature(self, temperature: int) -> None:
+        """Set the desired (target) temperature for this AC."""
+        self._desired_temperature = temperature
+
+    @property
+    def mode(self) -> AcMode:
+        """Return the current AC operating mode."""
+        return self._mode
+
+    @mode.setter
+    def mode(self, new_mode: AcMode) -> None:
+        """Set the AC operating mode."""
+        self._mode = new_mode
+
+    @property
+    def brand_id(self) -> int:
+        """Return the brand identifier for this AC."""
+        return self._brand_id
+
+    @brand_id.setter
+    def brand_id(self, new_brand_id: int) -> None:
+        """Set the brand identifier for this AC."""
+        self._brand_id = new_brand_id
+
+    @property
+    def system_id(self) -> str:
+        """Return the AirTouch controller system identifier."""
+        return self._system_id
+
+    @system_id.setter
+    def system_id(self, new_system_id: str) -> None:
+        """Set the AirTouch controller system identifier."""
+        self._system_id = new_system_id

pyairtouch3-0.1.0/src/pyairtouch3/airtouch_message.py

@@ -0,0 +1,154 @@
+"""Defines the AirTouchMessage class for building and modifying messages sent to the AirTouch system."""
+
+import logging
+from typing import Any
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AirTouchMessage:
+    """Builds various message types for the AirTouch system."""
+
+    def __init__(self) -> None:
+        """Initialize a new AirTouchMessage instance.
+
+        The default buffer is 13 bytes long, and `sum_byte` is used for checksum calculations.
+        """
+        self.buffer = bytearray(13)
+        self.sum_byte = bytearray(13)
+        self._is_temp = False
+
+    @property
+    def is_temp(self) -> bool:
+        """Indicates whether this message pertains to a temperature-related command."""
+        return self._is_temp
+
+    @is_temp.setter
+    def is_temp(self, value: bool) -> None:
+        """Set whether this message is temperature-related.
+
+        :param value: True if temperature-related, otherwise False.
+        """
+        self._is_temp = value
+
+    def reset_message(self) -> None:
+        """Reset the internal message buffer to default values.
+
+        Sets the first byte to 85 (0x55) and the third byte to 12 (0x0C).
+        """
+        for i in range(13):
+            self.buffer[i] = 0
+        self.buffer[0] = 85
+        self.buffer[2] = 12
+
+    def print_hex_code(self) -> None:
+        """Log the internal message buffer in hex format for debugging."""
+        _LOGGER.debug(",".join(format(x, "02x") for x in self.buffer))
+
+    def calc_checksum(self) -> int:
+        """Calculate an 8-bit checksum of the first 12 bytes of the buffer."""
+        self.sum_byte[:] = self.buffer
+        return sum(b & 0xFF for b in self.sum_byte[:-1]) % 256
+
+    def get_init_msg(self) -> bytearray:
+        """Create an initialization message buffer (13 bytes)."""
+        self.reset_message()
+        self.buffer[1] = 1
+        self.buffer[12] = self.calc_checksum()
+        return self.buffer
+
+    def toggle_zone(self, zone: int) -> bytearray:
+        """Create a command to toggle power on/off for a specific zone.
+
+        :param zone: The zone index to toggle.
+        :return: A 13-byte buffer for the toggle_zone command.
+        """
+        self.reset_message()
+        self.buffer[1] = 129  # -127 as unsigned
+        self.buffer[3] = zone
+        self.buffer[4] = 128  # -128 as unsigned
+        self.buffer[12] = self.calc_checksum()
+        return self.buffer
+
+    def set_fan(self, room: int, inc_dec: int) -> bytearray:
+        """Create a command to increment or decrement the fan/temperature setting for a given room.
+
+        :param room: The room or zone index.
+        :param inc_dec: Positive to increment temperature; negative to decrement.
+        :return: A 13-byte buffer with the fan adjustment command.
+        """
+        self.reset_message()
+        self.buffer[1] = 129  # -127 as unsigned
+        self.buffer[3] = room
+        self.buffer[4] = 2 if inc_dec >= 0 else 1
+        self.buffer[5] = 1
+        self.buffer[12] = self.calc_checksum()
+        return self.buffer
+
+    def toggle_ac_on_off(self, ac_id: int) -> bytearray:
+        """Create a command to toggle the AC on/off.
+
+        :param ac_id: The AirTouch AC identifier.
+        :return: A 13-byte buffer with the toggle command.
+        """
+        _LOGGER.debug("Toggling AC for id %d", ac_id)
+        self.reset_message()
+        self.buffer[1] = 134  # -122 as unsigned
+        self.buffer[3] = ac_id
+        self.buffer[4] = 128  # -128 as unsigned
+        self.buffer[12] = self.calc_checksum()
+        return self.buffer
+
+    def set_mode(self, ac_id: int, brand_id: int, in_mode: Any) -> bytearray:
+        """Create a command to set the AC mode (e.g., cool, heat, auto).
+
+        :param ac_id: AirTouch AC identifier.
+        :param brand_id: AC brand identifier, for special offsets.
+        :param in_mode: Mode, castable to int.
+        :return: A 13-byte buffer with the mode-setting command.
+        """
+        self.reset_message()
+        mode = int(in_mode)  # Ensure it's an integer
+
+        # Brand-specific remapping
+        if ac_id == 0 and brand_id == 11:
+            mode = {0: 0, 1: 2, 2: 3, 3: 4, 4: 1}.get(mode, mode)
+
+        if ac_id == 0 and brand_id == 15:
+            mode = {0: 5, 1: 2, 2: 3, 3: 4, 4: 1}.get(mode, mode)
+
+        _LOGGER.debug(
+            "Air Conditioner brand id at mode select: %d and mode %d", brand_id, mode
+        )
+        self.buffer[1] = 134  # -122 as unsigned
+        self.buffer[3] = ac_id
+        self.buffer[4] = 129  # -127 as unsigned
+        self.buffer[5] = mode
+
+        _LOGGER.debug("Checksum is %d", self.calc_checksum())
+        self.buffer[12] = self.calc_checksum()
+        return self.buffer
+
+    def set_fan_speed(self, ac_id: int, brand_id: int, in_mode: Any) -> bytearray:
+        """Create a command to set the fan speed for the AC unit.
+
+        :param ac_id: AirTouch AC identifier.
+        :param brand_id: AC brand identifier, used for certain speed mappings.
+        :param in_mode: Fan speed, castable to int.
+        :return: A 13-byte buffer with the fan speed-setting command.
+        """
+        self.reset_message()
+        mode = int(in_mode)  # Ensure it's an integer
+
+        if ac_id == 0 and brand_id == 15 and mode == 0:
+            mode = 4
+        if ac_id == 0 and brand_id == 2:
+            mode = {0: 0, 4: 1}.get(mode, mode + 1)
+
+        _LOGGER.debug("Final mode sending for fan speed: %d", mode)
+        self.buffer[1] = 134  # -122 as unsigned
+        self.buffer[3] = ac_id
+        self.buffer[4] = 130  # -126 as unsigned
+        self.buffer[5] = mode
+        self.buffer[12] = self.calc_checksum()
+        return self.buffer

pyairtouch3-0.1.0/src/pyairtouch3/airtouch_sensor.py

@@ -0,0 +1,30 @@
+"""Defines the Sensor class for representing a single sensor in an AirTouch system."""
+
+
+class Sensor:
+    """Represents an AirTouch sensor with temperature and availability state."""
+
+    def __init__(self) -> None:
+        """Initialize a new Sensor with default values for temperature and availability."""
+        self._current_temperature = 0
+        self._is_available = False
+
+    @property
+    def current_temperature(self) -> int:
+        """Return the current measured temperature."""
+        return self._current_temperature
+
+    @current_temperature.setter
+    def current_temperature(self, value: int) -> None:
+        """Set the current measured temperature."""
+        self._current_temperature = value
+
+    @property
+    def is_available(self) -> bool:
+        """Return True if the sensor is operational, otherwise False."""
+        return self._is_available
+
+    @is_available.setter
+    def is_available(self, value: bool) -> None:
+        """Set whether the sensor is operational."""
+        self._is_available = value

pyairtouch3-0.1.0/src/pyairtouch3/airtouch_zone.py

@@ -0,0 +1,98 @@
+"""Provides the AirtouchZone class for handling a single zone in an AirTouch system."""
+
+from .airtouch_sensor import Sensor
+from .enums import ZoneStatus
+
+
+class AirtouchZone:
+    """Represents a single AirTouch zone with temperature and status attributes."""
+
+    def __init__(self, touch_pad_temperature: int) -> None:
+        """Initialize the AirtouchZone.
+
+        :param touch_pad_temperature: Initial temperature displayed on the touch pad.
+        """
+        self._touch_pad_temperature = touch_pad_temperature
+        self._sensor = None  # type: Sensor | None
+        self._desired_temperature = 0
+        self._name = ""
+        self._status = ZoneStatus.ZONE_OFF
+        self._id = 0
+
+    @property
+    def touch_pad_temperature(self) -> int:
+        """Return the current touch pad temperature for this zone."""
+        return self._touch_pad_temperature
+
+    @touch_pad_temperature.setter
+    def touch_pad_temperature(self, value: int) -> None:
+        """Set the touch pad temperature.
+
+        :param value: The new touch pad temperature to store.
+        """
+        self._touch_pad_temperature = value
+
+    @property
+    def name(self) -> str:
+        """Return the name of this zone."""
+        return self._name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        """Set the name of this zone.
+
+        :param value: The new zone name.
+        """
+        self._name = value
+
+    @property
+    def id(self) -> int:
+        """Return the ID of this zone."""
+        return self._id
+
+    @id.setter
+    def id(self, value: int) -> None:
+        """Set the ID for this zone.
+
+        :param value: The new zone ID.
+        """
+        self._id = value
+
+    @property
+    def status(self) -> ZoneStatus:
+        """Return the current power/status of this zone."""
+        return self._status
+
+    @status.setter
+    def status(self, value: ZoneStatus) -> None:
+        """Update the power/status of this zone.
+
+        :param value: The new zone status.
+        """
+        self._status = value
+
+    @property
+    def desired_temperature(self) -> int:
+        """Return the desired (target) temperature for this zone."""
+        return self._desired_temperature
+
+    @desired_temperature.setter
+    def desired_temperature(self, value: int) -> None:
+        """Set the desired (target) temperature for this zone.
+
+        :param value: The new target temperature.
+        """
+        self._desired_temperature = value
+
+    @property
+    def sensor(self) -> Sensor | None:
+        """Return the Sensor object associated with this zone, if any."""
+        return self._sensor
+
+    @sensor.setter
+    def sensor(self, sensor: Sensor) -> None:
+        """Assign a Sensor object to this zone.
+
+        :param sensor: The Sensor instance that measures this zone's temperature.
+        """
+        self._sensor = sensor

pyairtouch3-0.1.0/src/pyairtouch3/client.py

@@ -0,0 +1,115 @@
+"""Async TCP client for AirTouch 3 controllers."""
+
+import asyncio
+import contextlib
+import logging
+
+from .airtouch_aircon import Aircon
+from .airtouch_message import AirTouchMessage
+from .message_constants import MessageConstants
+from .message_response_parser import MessageResponseParser
+
+_LOGGER = logging.getLogger(__name__)
+
+DEFAULT_PORT = 8899
+RESPONSE_TIMEOUT = 10
+MIN_RESPONSE_LENGTH = (
+    MessageConstants.AIRTOUCH_ID_START + MessageConstants.AIRTOUCH_ID_LENGTH
+)
+
+
+class AirTouchError(Exception):
+    """Error raised when AirTouch communication or parsing fails."""
+
+
+class AirTouchClient:
+    """Async client for an AirTouch 3 controller."""
+
+    def __init__(
+        self,
+        host: str,
+        port: int = DEFAULT_PORT,
+        *,
+        timeout: float = RESPONSE_TIMEOUT,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        """Initialize the client."""
+        self.host = host
+        self.port = port
+        self.timeout = timeout
+        self._logger = logger or _LOGGER
+
+    async def request_status(self) -> bytes:
+        """Send the status request and return the raw response bytes."""
+        writer: asyncio.StreamWriter | None = None
+        try:
+            self._logger.debug(
+                "Fetching AirTouch 3 data from %s:%s", self.host, self.port
+            )
+            async with asyncio.timeout(self.timeout):
+                reader, writer = await asyncio.open_connection(self.host, self.port)
+                writer.write(AirTouchMessage().get_init_msg())
+                await writer.drain()
+                return await reader.read(1024)
+        except (TimeoutError, OSError) as err:
+            raise AirTouchError(f"Communication error with AirTouch: {err}") from err
+        finally:
+            if writer:
+                writer.close()
+                with contextlib.suppress(OSError):
+                    await writer.wait_closed()
+
+    async def fetch_aircon(self) -> Aircon:
+        """Fetch and parse the controller status."""
+        response_data = await self.request_status()
+        self._logger.debug(
+            "Received %s bytes from AirTouch 3 controller at %s:%s",
+            len(response_data),
+            self.host,
+            self.port,
+        )
+        if len(response_data) < MIN_RESPONSE_LENGTH:
+            raise AirTouchError(
+                f"AirTouch response was too short: {len(response_data)} bytes"
+            )
+
+        try:
+            return MessageResponseParser(bytearray(response_data), self._logger).parse()
+        except (ValueError, IndexError) as err:
+            raise AirTouchError(f"Communication error with AirTouch: {err}") from err
+
+    async def send_message(self, message: bytes | bytearray) -> None:
+        """Send a raw AirTouch protocol message."""
+        writer: asyncio.StreamWriter | None = None
+        try:
+            async with asyncio.timeout(self.timeout):
+                _, writer = await asyncio.open_connection(self.host, self.port)
+                writer.write(message)
+                await writer.drain()
+        except (TimeoutError, OSError) as err:
+            raise AirTouchError(f"Communication error with AirTouch: {err}") from err
+        finally:
+            if writer:
+                writer.close()
+                with contextlib.suppress(OSError):
+                    await writer.wait_closed()
+
+    async def toggle_zone(self, zone_id: int) -> None:
+        """Toggle power on or off for a zone."""
+        await self.send_message(AirTouchMessage().toggle_zone(zone_id))
+
+    async def adjust_zone_temperature(self, zone_id: int, inc_dec: int) -> None:
+        """Increment or decrement a zone target temperature by one step."""
+        await self.send_message(AirTouchMessage().set_fan(zone_id, inc_dec))
+
+    async def toggle_ac_power(self, ac_id: int) -> None:
+        """Toggle power on or off for an AC."""
+        await self.send_message(AirTouchMessage().toggle_ac_on_off(ac_id))
+
+    async def set_mode(self, ac_id: int, brand_id: int, mode: int) -> None:
+        """Set the AC mode."""
+        await self.send_message(AirTouchMessage().set_mode(ac_id, brand_id, mode))
+
+    async def set_fan_speed(self, ac_id: int, brand_id: int, speed: int) -> None:
+        """Set the AC fan speed."""
+        await self.send_message(AirTouchMessage().set_fan_speed(ac_id, brand_id, speed))