philips-airctrl 1.0.0__py3-none-any.whl

philips_airctrl/__init__.py

@@ -0,0 +1,4 @@
+from philips_airctrl._version import __version__
+from philips_airctrl.coap.client import Client as CoAPClient
+
+__all__ = ["CoAPClient", "__version__"]

philips_airctrl/__main__.py

@@ -0,0 +1,4 @@
+from philips_airctrl.cli import main
+
+if __name__ == "__main__":
+    main()

philips_airctrl/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for package version."""
+
+__version__ = "1.0.0"

philips_airctrl/cli.py

@@ -0,0 +1,337 @@
+"""Command-line interface for philips-airctrl."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import json
+import logging
+import sys
+
+from tabulate import tabulate
+
+from philips_airctrl import CoAPClient
+from philips_airctrl.device_info import DeviceInfoExtractor
+from philips_airctrl.discovery import DeviceDiscovery
+from philips_airctrl.setup_wizard import SetupWizard
+
+logging.basicConfig(level=logging.WARN)
+logger = logging.getLogger(__package__)
+
+
+def parse_args(args: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    subparsers = parser.add_subparsers(
+        dest="command",
+        required=True,
+        help="sub-command help",
+    )
+
+    parser.add_argument(
+        "-D",
+        "--debug",
+        dest="debug",
+        action="store_true",
+        help="Enable debug output",
+    )
+    parser_status = subparsers.add_parser(
+        "status",
+        help="get status of device",
+    )
+    parser_status.add_argument(
+        "-H",
+        "--host",
+        dest="host",
+        type=str,
+        required=True,
+        help="Address of CoAP device",
+    )
+    parser_status.add_argument(
+        "-P",
+        "--port",
+        dest="port",
+        type=int,
+        default=5683,
+        help="Port of CoAP device (default: %(default)s)",
+    )
+    parser_status.add_argument(
+        "-J",
+        "--json",
+        dest="json",
+        action="store_true",
+        help="Output status as JSON",
+    )
+    parser_status_observe = subparsers.add_parser(
+        "status-observe",
+        help="Observe status of device",
+    )
+    parser_status_observe.add_argument(
+        "-H",
+        "--host",
+        dest="host",
+        type=str,
+        required=True,
+        help="Address of CoAP device",
+    )
+    parser_status_observe.add_argument(
+        "-P",
+        "--port",
+        dest="port",
+        type=int,
+        default=5683,
+        help="Port of CoAP device (default: %(default)s)",
+    )
+    parser_status_observe.add_argument(
+        "-J",
+        "--json",
+        dest="json",
+        action="store_true",
+        help="Output status as JSON",
+    )
+    parser_set = subparsers.add_parser(
+        "set",
+        help="Set value of device",
+    )
+    parser_set.add_argument(
+        "-H",
+        "--host",
+        dest="host",
+        type=str,
+        required=True,
+        help="Address of CoAP device",
+    )
+    parser_set.add_argument(
+        "-P",
+        "--port",
+        dest="port",
+        type=int,
+        default=5683,
+        help="Port of CoAP device (default: %(default)s)",
+    )
+    parser_set.add_argument(
+        "values",
+        metavar="K=V",
+        type=str,
+        nargs="+",
+        help="Key-Value pairs to set",
+    )
+    parser_set.add_argument(
+        "-I",
+        "--int",
+        dest="value_as_int",
+        action="store_true",
+        help="Encode value as integer",
+    )
+
+    # Discovery command
+    parser_discover = subparsers.add_parser(
+        "discover",
+        help="Discover Philips air purifiers on the network",
+    )
+    parser_discover.add_argument(
+        "-n",
+        "--network",
+        dest="network",
+        type=str,
+        help="Specific network to scan (e.g., 192.168.1.0/24)",
+    )
+    parser_discover.add_argument(
+        "-t",
+        "--timeout",
+        dest="timeout",
+        type=float,
+        default=5.0,
+        help="Timeout for device discovery (default: %(default)s)",
+    )
+
+    # Device info command
+    parser_device_info = subparsers.add_parser(
+        "device-info",
+        help="Get comprehensive device information",
+    )
+    parser_device_info.add_argument(
+        "-H",
+        "--host",
+        dest="host",
+        type=str,
+        required=True,
+        help="Address of CoAP device",
+    )
+    parser_device_info.add_argument(
+        "-P",
+        "--port",
+        dest="port",
+        type=int,
+        default=5683,
+        help="Port of CoAP device (default: %(default)s)",
+    )
+    parser_device_info.add_argument(
+        "-f",
+        "--format",
+        dest="format",
+        choices=["json", "yaml"],
+        default="json",
+        help="Output format (default: %(default)s)",
+    )
+    parser_device_info.add_argument(
+        "-o",
+        "--output",
+        dest="output",
+        type=str,
+        help="Output file (default: stdout)",
+    )
+
+    # Setup wizard command
+    subparsers.add_parser(
+        "setup",
+        help="Interactive setup wizard for Home Assistant integration",
+    )
+
+    return parser.parse_args(args)
+
+
+async def handle_discover_command(args: argparse.Namespace) -> None:
+    """Handle the discover command."""
+    print("Discovering Philips air purifiers on the network...")
+    print()
+
+    discovery = DeviceDiscovery(timeout=args.timeout)
+
+    if args.network:
+        devices = await discovery.discover_single_network(args.network)
+        print(f"Scanning network: {args.network}")
+    else:
+        devices = await discovery.discover_devices()
+        networks = discovery.get_network_ranges()
+        print(f"Scanning networks: {', '.join(networks)}")
+
+    print()
+
+    if not devices:
+        print("No devices found.")
+        print()
+        print("Troubleshooting tips:")
+        print("  Ensure your air purifier is connected to the same network")
+        print("  Check that the device is powered on")
+        print("  Verify your firewall allows UDP traffic on port 5683")
+        print("  Try specifying a specific network with -n option")
+        return
+
+    print(f"Found {len(devices)} device(s):")
+    print()
+
+    headers = ["IP Address", "Model", "Name", "Firmware", "WiFi Signal"]
+    rows = []
+
+    for device in devices:
+        signal = f"{device.status.get('rssi', 'N/A')} dBm" if device.status else "N/A"
+        rows.append(
+            [
+                device.ip,
+                device.model or "Unknown",
+                device.name or "Unknown",
+                device.firmware_version or "Unknown",
+                signal,
+            ]
+        )
+
+    print(tabulate(rows, headers=headers, tablefmt="grid"))
+    print()
+    print("Use 'philips-airctrl device-info -H <IP>' to extract technical device data")
+    print("Use 'philips-airctrl setup' to collect device info for developers")
+
+
+async def handle_device_info_command(args: argparse.Namespace) -> None:
+    """Handle the device-info command."""
+    print(f"Gathering device information from {args.host}...")
+
+    extractor = DeviceInfoExtractor(args.host, args.port)
+    device_info = await extractor.get_device_info()
+
+    if args.format == "json":
+        output = extractor.export_json(device_info, pretty=True)
+    else:
+        output = extractor.export_yaml(device_info)
+
+    if args.output:
+        with open(args.output, "w") as f:
+            f.write(output)
+        print(f"Device information saved to: {args.output}")
+    else:
+        print(output)
+
+
+async def handle_setup_command() -> None:
+    """Handle the setup command."""
+    wizard = SetupWizard()
+    await wizard.run()
+
+
+async def async_main() -> None:
+    args = parse_args()
+    if args.debug:
+        logger.setLevel(logging.DEBUG)
+        logging.getLogger("coap").setLevel(logging.DEBUG)
+        logging.getLogger("philips_airpurifier").setLevel(logging.DEBUG)
+
+    if args.command == "discover":
+        await handle_discover_command(args)
+        return
+    if args.command == "setup":
+        await handle_setup_command()
+        return
+
+    if not hasattr(args, "host") or not args.host:
+        print("Error: Host is required for this command")
+        return
+
+    client = None
+    try:
+        client = await CoAPClient.create(host=args.host, port=args.port)
+        if args.command == "status":
+            status, max_age = await client.get_status()
+            if args.json:
+                print(json.dumps(status, indent=2))
+            else:
+                print(status)
+                print(f"max_age = {max_age}")
+        elif args.command == "status-observe":
+            async for status in client.observe_status():
+                if args.json:
+                    print(json.dumps(status, indent=2))
+                else:
+                    print(status)
+                sys.stdout.flush()
+        elif args.command == "set":
+            data: dict[str, str | int | bool] = {}
+            failed = False
+            for e in args.values:
+                k, v = e.split("=")
+                if v == "true":
+                    data[k] = True
+                elif v == "false":
+                    data[k] = False
+                elif args.value_as_int:
+                    try:
+                        data[k] = int(v)
+                    except ValueError:
+                        print(f"Cannot encode value '{v}' as int")
+                        failed = True
+                        break
+                else:
+                    data[k] = v
+            if not failed and data:
+                await client.set_control_values(data=data)
+        elif args.command == "device-info":
+            await handle_device_info_command(args)
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        pass
+    finally:
+        if client:
+            await client.shutdown()
+
+
+def main() -> None:
+    with contextlib.suppress(KeyboardInterrupt):
+        asyncio.run(async_main())

philips_airctrl/coap/__init__.py

@@ -0,0 +1 @@
+from philips_airctrl.coap.client import Client as Client

philips_airctrl/coap/client.py

@@ -0,0 +1,167 @@
+"""Client to interact with the aiocoap library."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+from aiocoap import Context, Message, Unreliable
+from aiocoap.error import NetworkError
+from aiocoap.numbers.codes import GET, POST
+
+from philips_airctrl.coap.encryption import EncryptionContext
+
+logger = logging.getLogger(__name__)
+
+RETRY_DELAY = 0.5
+
+
+class Client:
+    STATUS_PATH = "/sys/dev/status"
+    CONTROL_PATH = "/sys/dev/control"
+    SYNC_PATH = "/sys/dev/sync"
+
+    def __init__(self, host: str, port: int = 5683) -> None:
+        self.host = host
+        self.port = port
+        self._client_context: Context | None = None
+        self._encryption_context: EncryptionContext | None = None
+
+    async def _init(self) -> None:
+        self._client_context = await Context.create_client_context()
+        self._encryption_context = EncryptionContext()
+        await self._sync()
+
+    @classmethod
+    async def create(cls, *args: Any, **kwargs: Any) -> Client:
+        obj = cls(*args, **kwargs)
+        await obj._init()
+        return obj
+
+    async def __aenter__(self) -> Client:
+        await self._init()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        await self.shutdown()
+
+    async def shutdown(self) -> None:
+        if self._client_context:
+            await self._client_context.shutdown()
+
+    async def _sync(self) -> None:
+        logger.debug("syncing")
+        sync_request = os.urandom(4).hex().upper()
+        request = Message(
+            code=POST,
+            transport_tuning=Unreliable,
+            uri=f"coap://{self.host}:{self.port}{self.SYNC_PATH}",
+            payload=sync_request.encode(),
+        )
+        response = await self._client_context.request(request).response
+        client_key = response.payload.decode()
+        logger.debug("synced: %s", client_key)
+        self._encryption_context.set_client_key(client_key)
+
+    async def get_status(self) -> tuple[dict[str, Any], int]:
+        logger.debug("retrieving status")
+        request = Message(
+            code=GET,
+            transport_tuning=Unreliable,
+            uri=f"coap://{self.host}:{self.port}{self.STATUS_PATH}",
+        )
+        request.opt.observe = 0
+        try:
+            response = await self._client_context.request(request).response
+        except NetworkError:
+            logger.error("network error while retrieving status")
+            raise
+        payload_encrypted = response.payload.decode()
+        payload = self._encryption_context.decrypt(payload_encrypted)
+        logger.debug("status: %s", payload)
+        state_reported = json.loads(payload)
+        max_age = 60
+        try:
+            max_age = response.opt.max_age
+            logger.debug("max age = %s", max_age)
+        except AttributeError:
+            logger.debug("no max age found in CoAP options")
+        return state_reported["state"]["reported"], max_age
+
+    async def observe_status(self) -> AsyncIterator[dict[str, Any]]:
+        def decrypt_status(response: Any) -> dict[str, Any]:
+            payload_encrypted = response.payload.decode()
+            payload = self._encryption_context.decrypt(payload_encrypted)
+            logger.debug("observation status: %s", payload)
+            status = json.loads(payload)
+            return status["state"]["reported"]
+
+        logger.debug("observing status")
+        request = Message(
+            code=GET,
+            transport_tuning=Unreliable,
+            uri=f"coap://{self.host}:{self.port}{self.STATUS_PATH}",
+        )
+        request.opt.observe = 0
+        requester = self._client_context.request(request)
+        response = await requester.response
+        yield decrypt_status(response)
+        async for response in requester.observation:
+            yield decrypt_status(response)
+
+    async def set_control_value(
+        self, key: str, value: Any, retry_count: int = 5, resync: bool = True
+    ) -> bool | None:
+        return await self.set_control_values(
+            data={key: value}, retry_count=retry_count, resync=resync
+        )
+
+    async def set_control_values(
+        self, data: dict[str, Any], retry_count: int = 5, resync: bool = True
+    ) -> bool | None:
+        state_desired = {
+            "state": {
+                "desired": {
+                    "CommandType": "app",
+                    "DeviceId": "",
+                    "EnduserId": "",
+                    **data,
+                }
+            }
+        }
+        payload = json.dumps(state_desired)
+        logger.debug("REQUEST: %s", payload)
+        payload_encrypted = self._encryption_context.encrypt(payload)
+
+        for attempt in range(retry_count + 1):
+            request = Message(
+                code=POST,
+                transport_tuning=Unreliable,
+                uri=f"coap://{self.host}:{self.port}{self.CONTROL_PATH}",
+                payload=payload_encrypted.encode(),
+            )
+            response = await self._client_context.request(request).response
+            logger.debug("RESPONSE: %s", response.payload)
+            result = json.loads(response.payload)
+            if result.get("status") == "success":
+                return True
+            if resync:
+                logger.debug("set_control_value failed. resyncing...")
+                await self._sync()
+            if attempt < retry_count:
+                logger.debug("set_control_value failed. retrying...")
+                await asyncio.sleep(RETRY_DELAY)
+
+        logger.error("set_control_value failed: %s", data)
+        return False

philips_airctrl/coap/encryption.py

@@ -0,0 +1,69 @@
+"""AES-CBC encryption/decryption for Philips air purifier CoAP protocol."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from Cryptodome.Cipher import AES
+from Cryptodome.Util.Padding import pad, unpad
+
+
+class DigestMismatchError(Exception):
+    pass
+
+
+class ClientKeyNotInitialisedError(RuntimeError):
+    """Raised when an operation requires a client key that has not been set."""
+
+    def __init__(self) -> None:
+        super().__init__("Client key not initialised; call set_client_key() first")
+
+
+class EncryptionContext:
+    SECRET_KEY = "JiangPan"  # noqa: S105  # nosec B105 - required by device protocol
+
+    def __init__(self) -> None:
+        self._client_key: str | None = None
+
+    def set_client_key(self, client_key: str) -> None:
+        self._client_key = client_key
+
+    def _increment_client_key(self) -> None:
+        if self._client_key is None:
+            raise ClientKeyNotInitialisedError
+        client_key_int = (int(self._client_key, 16) + 1) & 0xFFFFFFFF
+        client_key_next = client_key_int.to_bytes(4, byteorder="big").hex().upper()
+        self._client_key = client_key_next
+
+    def _create_cipher(self, key: str) -> Any:
+        key_and_iv = hashlib.md5((self.SECRET_KEY + key).encode()).hexdigest().upper()  # noqa: S324  # nosec B324 - required by device protocol
+        half_keylen = len(key_and_iv) // 2
+        secret_key = key_and_iv[:half_keylen]
+        iv = key_and_iv[half_keylen:]
+        return AES.new(
+            key=secret_key.encode(),
+            mode=AES.MODE_CBC,
+            iv=iv.encode(),
+        )
+
+    def encrypt(self, payload: str) -> str:
+        self._increment_client_key()
+        key = self._client_key
+        plaintext_padded = pad(payload.encode(), 16, style="pkcs7")
+        cipher = self._create_cipher(key)
+        ciphertext = cipher.encrypt(plaintext_padded).hex().upper()
+        digest = hashlib.sha256((key + ciphertext).encode()).hexdigest().upper()
+        return key + ciphertext + digest
+
+    def decrypt(self, payload_encrypted: str) -> str:
+        key = payload_encrypted[:8]
+        ciphertext = payload_encrypted[8:-64]
+        digest = payload_encrypted[-64:]
+        digest_calculated = hashlib.sha256((key + ciphertext).encode()).hexdigest().upper()
+        if digest != digest_calculated:
+            raise DigestMismatchError
+        cipher = self._create_cipher(key)
+        plaintext_padded = cipher.decrypt(bytes.fromhex(ciphertext))
+        plaintext_unpadded = unpad(plaintext_padded, 16, style="pkcs7")
+        return plaintext_unpadded.decode()