cremalink 0.1.0b5__py3-none-any.whl

cremalink/__init__.py

@@ -0,0 +1,33 @@
+"""
+Cremalink: A Python library for interacting with De'Longhi coffee machines.
+
+This top-level package exposes the primary user-facing classes and functions
+for easy access, including the main `Client`, the `Device` model, and factory
+functions for creating device instances.
+"""
+from cremalink.clients.cloud import Client
+from cremalink.domain import Device, create_cloud_device, create_local_device
+from cremalink.local_server_app import create_app, ServerSettings
+from cremalink.local_server import LocalServer
+from cremalink.devices import device_map
+from importlib.metadata import PackageNotFoundError, version
+
+__all__ = [
+    "Client",
+    "Device",
+    "create_local_device",
+    "create_cloud_device",
+    "LocalServer",
+    "create_app",
+    "ServerSettings",
+    "device_map",
+]
+
+try:
+    __name__ = "cremalink"
+    # Retrieve the package version from installed metadata.
+    __version__ = version(__name__)
+except PackageNotFoundError:
+    # If the package is not installed (e.g., running from source),
+    # fall back to a default version.
+    __version__ = "0.0.0"

cremalink/clients/__init__.py

@@ -0,0 +1,10 @@
+"""
+This package provides high-level client interfaces for interacting with
+the cremalink system.
+
+The `Client` class from the `cloud` module is exposed as the primary
+entry point for this package.
+"""
+from cremalink.clients.cloud import Client
+
+__all__ = ["Client"]

cremalink/clients/cloud.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import json
+import os
+
+import requests
+
+from cremalink.domain import create_cloud_device
+from cremalink.resources import load_api_config
+
+API_USER_AGENT = "datatransport/3.1.2 android/"
+TOKEN_USER_AGENT = "DeLonghiComfort/3 CFNetwork/1568.300.101 Darwin/24.2.0"
+
+
+class Client:
+    """
+    Client for interacting with the Ayla IoT cloud platform.
+    Manages authentication (access and refresh tokens) and device discovery.
+    """
+
+    def __init__(self, token_path: str):
+        # Ensure the token_path points to a JSON file.
+        if not token_path.endswith(".json"):
+            raise ValueError("token_path must point to a .json file")
+
+        # Load API configuration from resources.
+        self.api_conf = load_api_config()
+        self.gigya_api = self.api_conf.get("GIGYA")
+        self.ayla_api = self.api_conf.get("AYLA")
+
+        self.token_path = token_path
+        # Retrieve or refresh the access token upon initialization.
+        self.access_token = self.__get_access_token()
+        # Fetch the list of devices associated with the account.
+        self.devices = requests.get(
+            url=f"{self.ayla_api.get('API_URL')}/devices.json",
+            headers={
+                "User-Agent": API_USER_AGENT,
+                "Authorization": f"auth_token {self.access_token}",
+                "Accept": "application/json",
+            },
+        ).json()
+
+    def get_devices(self):
+        """
+        Retrieves a list of Device Serial Numbers (DSNs) for all registered devices.
+
+        Returns:
+            list[str]: A list of DSNs.
+        """
+        devices: list[str] = []
+        for device in self.devices:
+            devices.append(device["device"]["dsn"])
+        return devices
+
+    def get_device(self, dsn: str, device_map_path: dict | None = None):
+        """
+        Retrieves a specific cloud device by its DSN.
+
+        Args:
+            dsn (str): The Device Serial Number of the desired device.
+            device_map_path (dict | None): Optional mapping for device properties.
+
+        Returns:
+            CloudDevice | None: An instance of CloudDevice if found, otherwise None.
+        """
+        for device_dsn in self.get_devices():
+            if device_dsn == dsn:
+                return create_cloud_device(device_dsn, self.access_token, device_map_path)
+        return None
+
+    def __get_access_token(self):
+        """
+        Retrieves a valid access token, refreshing it if necessary using the refresh token.
+        """
+        refresh_token = self.__get_refresh_token()
+        # If no refresh token is found, prompt the user to provide one.
+        if not refresh_token or refresh_token == "":
+            self.__set_refresh_token("")
+            raise ValueError(f"No refresh token found. Open {self.token_path} and add a valid refresh token.")
+        response = requests.post(
+            url=f"{self.ayla_api.get('OAUTH_URL')}/users/refresh_token.json",
+            headers={
+                "User-Agent": TOKEN_USER_AGENT,
+                "Content-Type": "application/json",
+            },
+            json={"user": {"refresh_token": refresh_token}},
+        )
+        if response.status_code == 200:
+            # If successful, extract new access and refresh tokens.
+            data = response.json()
+            new_access_token = data["access_token"]
+            new_refresh_token = data["refresh_token"]
+            # Update the stored refresh token.
+            self.__set_refresh_token(new_refresh_token)
+            return new_access_token
+        else:
+            # Raise an error if access token retrieval fails.
+            raise ValueError(f"Failed to get access token: {response.status_code} {response.text}")
+
+    def __get_refresh_token(self):
+        """
+        Reads the refresh token from the token file.
+
+        Returns:
+            str | None: The refresh token if found, otherwise None.
+        """
+        if os.path.exists(self.token_path):
+            with open(self.token_path, "r") as f:
+                data = f.read()
+                f.close()
+                if data:
+                    token_data = json.loads(data)
+                    return token_data.get("refresh_token", None)
+        return None
+
+    def __set_refresh_token(self, refresh_token: str):
+        """
+        Writes the provided refresh token to the token file.
+
+        Args:
+            refresh_token (str): The new refresh token to store.
+        """
+        with open(self.token_path, "w+") as f:
+            # Read existing data to preserve other potential keys.
+            data = f.read()
+            token_data = json.loads(data) if data else {}
+            token_data["refresh_token"] = refresh_token
+            f.write(json.dumps(token_data, indent=2))
+            f.close()

cremalink/core/__init__.py

@@ -0,0 +1,6 @@
+"""
+This package contains core utilities and base functionalities that are used
+across the cremalink library.
+"""
+
+__all__ = []

cremalink/core/binary.py

@@ -0,0 +1,102 @@
+"""
+This module provides binary utility functions for handling data conversions,
+checksum calculations, and bitwise operations, often required for communication
+with hardware devices.
+"""
+from __future__ import annotations
+
+import base64
+from typing import Iterable
+
+# Polynomial for CRC-16 CCITT calculation.
+CRC16_POLY = 0x1021
+
+
+def crc16_ccitt(data: bytes) -> bytes:
+    """
+    Calculates the CRC-16 CCITT checksum for the given data.
+
+    This implementation uses a specific initial value (0x1D0F) and polynomial (0x1021).
+
+    Args:
+        data: The input bytes to checksum.
+
+    Returns:
+        A 2-byte sequence representing the calculated CRC in big-endian format.
+    """
+    crc = 0x1D0F  # Initial CRC value.
+    for byte in data:
+        crc ^= byte << 8
+        for _ in range(8):
+            if crc & 0x8000:
+                crc = (crc << 1) ^ CRC16_POLY
+            else:
+                crc <<= 1
+    return (crc & 0xFFFF).to_bytes(2, byteorder="big")
+
+
+def b64_to_cmd_hex(b64_data: str) -> str:
+    """
+    Decodes a base64 string, extracts a command frame, and returns it as a hex string.
+
+    The function cleans the input base64 string, decodes it, and then uses the
+    second byte of the decoded data as a length specifier to extract the
+    relevant command frame.
+
+    Args:
+        b64_data: The base64 encoded data string.
+
+    Returns:
+        The extracted command frame as a hexadecimal string.
+    """
+    # Remove whitespace and add padding if necessary.
+    cleaned = "".join(b64_data.split())
+    cleaned += "=" * (-len(cleaned) % 4)
+
+    # Decode the base64 string.
+    raw = base64.b64decode(cleaned)
+
+    # The second byte (index 1) is the length of the command frame.
+    length = raw[1]
+    cmd_frame = raw[: length + 1]
+
+    # Return the command frame as a hex string.
+    return cmd_frame.hex()
+
+
+def get_bit(byte_value: int, bit_index: int) -> bool:
+    """
+    Gets the value of a specific bit in a byte.
+
+    Args:
+        byte_value: The integer representation of the byte.
+        bit_index: The index of the bit to retrieve (0-7).
+
+    Returns:
+        True if the bit is 1, False if it is 0.
+
+    Raises:
+        ValueError: If bit_index is not between 0 and 7.
+    """
+    if not 0 <= bit_index <= 7:
+        raise ValueError("bit_index must be between 0 and 7")
+    return bool(byte_value & (1 << bit_index))
+
+
+def safe_byte_at(data: Iterable[int] | bytes, index: int) -> int | None:
+    """
+    Safely retrieves a byte from a sequence or iterable at a given index.
+
+    Args:
+        data: The data to access, can be bytes or an iterable of integers.
+        index: The index of the byte to retrieve.
+
+    Returns:
+        The byte as an integer if the index is valid, otherwise None.
+    """
+    try:
+        # Convert to list to handle various iterable types and access by index.
+        return list(data)[index]
+    except (IndexError, TypeError):
+        # Return None if index is out of bounds or type is not subscriptable.
+        return None

cremalink/crypto/__init__.py

@@ -0,0 +1,142 @@
+"""
+This module provides a set of cryptographic helper functions for handling
+encryption, decryption, and hashing, primarily using AES and HMAC.
+"""
+
+import base64
+import hashlib
+import hmac
+
+from Crypto.Cipher import AES
+
+
+def hmac_for_key_and_data(key: bytes, data: bytes) -> bytes:
+    """
+    Generates an HMAC-SHA256 digest for the given key and data.
+
+    Args:
+        key: The secret key for the HMAC operation.
+        data: The message data to hash.
+
+    Returns:
+        The raw HMAC-SHA256 digest as bytes.
+    """
+    mac_hash = hmac.new(key, data, hashlib.sha256)
+    return mac_hash.digest()
+
+
+def pad_zero(data: bytes, block_size: int = 16) -> bytes:
+    """
+    Pads data with zero bytes to a multiple of the specified block size.
+
+    Note: This padding scheme is not reversible if the original data can
+    end with zero bytes.
+
+    Args:
+        data: The bytes to pad.
+        block_size: The block size to align to. Defaults to 16.
+
+    Returns:
+        The zero-padded data.
+    """
+    padding_length = block_size - len(data) % block_size
+    return data + (padding_length * b"\x00")
+
+
+def unpad_zero(data: bytes) -> bytes:
+    """
+    Removes trailing zero-byte padding from data.
+
+    This works by finding the first null byte and truncating the rest.
+
+    Args:
+        data: The padded bytes.
+
+    Returns:
+        The unpadded data.
+    """
+    # Finds the first occurrence of a null byte and slices the data up to that point.
+    return data.rstrip(b"\x00")
+
+
+def extract_bits(raw: bytes, start: int, end: int) -> bytearray:
+    """
+    Extracts a slice from the hexadecimal representation of raw bytes.
+
+    Note: The name is a misnomer; it operates on the hex string, not raw bits.
+
+    Args:
+        raw: The input bytes.
+        start: The starting index in the hex string representation.
+        end: The ending index in the hex string representation.
+
+    Returns:
+        A bytearray corresponding to the specified hex slice.
+    """
+    strhex = raw.hex()
+    return bytearray.fromhex(strhex[start:end])
+
+
+def aes_encrypt(message: str, key: bytes, iv: bytes) -> str:
+    """
+    Encrypts a string using AES-128 in CBC mode with zero-padding.
+
+    Args:
+        message: The string message to encrypt.
+        key: The 16-byte encryption key.
+        iv: The 16-byte initialization vector (IV).
+
+    Returns:
+        A base64-encoded string of the encrypted data.
+    """
+    raw = pad_zero(message.encode())
+    cipher = AES.new(key, AES.MODE_CBC, iv)
+    enc = cipher.encrypt(raw)
+    return base64.b64encode(enc).decode("utf-8")
+
+
+def aes_decrypt(enc: str, key: bytes, iv: bytes) -> bytes:
+    """
+    Decrypts a base64-encoded string using AES-128 in CBC mode.
+
+    Args:
+        enc: The base64-encoded encrypted string.
+        key: The 16-byte decryption key.
+        iv: The 16-byte initialization vector (IV).
+
+    Returns:
+        The decrypted data as bytes, after removing zero-padding.
+    """
+    decoded = base64.b64decode(enc)
+    cipher = AES.new(key, AES.MODE_CBC, iv)
+    dec = cipher.decrypt(decoded)
+    return unpad_zero(dec)
+
+
+def rotate_iv_from_ciphertext(enc: str) -> bytes:
+    """
+    Extracts the last 16 bytes from a ciphertext to be used as the next IV.
+
+    This is a common technique in some protocols to chain IVs.
+
+    Args:
+        enc: The base64-encoded ciphertext.
+
+    Returns:
+        The last 16 bytes of the raw ciphertext.
+    """
+    decoded_hex = base64.b64decode(enc).hex()
+    # The last 16 bytes are the last 32 characters of the hex string.
+    return bytearray.fromhex(decoded_hex[-32:])
+
+
+# Specifies the public API of this module.
+__all__ = [
+    "aes_decrypt",
+    "aes_encrypt",
+    "extract_bits",
+    "hmac_for_key_and_data",
+    "pad_zero",
+    "rotate_iv_from_ciphertext",
+    "unpad_zero",
+]

cremalink/devices/AY008ESP1.json

@@ -0,0 +1,114 @@
+{
+  "device_type": "AY008ESP1",
+  "command_map": {
+    "americano": {
+      "command": "0d1483f006010100280f006e1b010203040006ecfe",
+      "name": "Americano"
+    },
+    "coffee": {
+      "command": "0d1183f002011b040100f002030400060ab7",
+      "name": "Coffee"
+    },
+    "doppio_plus": {
+      "command": "0d0f83f005020100601b00040006138e",
+      "name": "Doppio Plus"
+    },
+    "double_espresso": {
+      "command": "0d0883f00401062342",
+      "name": "Double Espresso"
+    },
+    "espresso": {
+      "command": "0d1183f0010101007e1b030202040006afe2",
+      "name": "Espresso"
+    },
+    "espresso_soul": {
+      "command": "0d0d83f0c80101003c1b04064270",
+      "name": "Espresso Soul"
+    },
+    "hot_water": {
+      "command": "0d0d83f010010f00fa1b01068124",
+      "name": "Hot Water"
+    },
+    "long_coffee": {
+      "command": "0d1183f003010100a01b010203040006fc08",
+      "name": "Long Coffee"
+    },
+    "refresh": {
+      "command": "0d07840f03025640",
+      "name": "Refresh Status"
+    },
+    "standby": {
+      "command": "0d07840f01010041",
+      "name": "Turn Off"
+    },
+    "stop": {
+      "command": "0d0d83f010020f00fa1b010659a6",
+      "name": "Stop"
+    },
+    "wakeup": {
+      "command": "0d07840f02015512",
+      "name": "Turn On"
+    }
+  },
+  "property_map": {
+    "monitor": "d302_monitor"
+  },
+  "monitor_profile": {
+    "enums": {
+      "accessory": {
+        "0": "none",
+        "1": "hot_water_spout",
+        "2": "latte_crema_hot",
+        "3": "chocolate",
+        "4": "latte_crema_hot_clean",
+        "6": "latte_crema_cool",
+        "7": "latte_crema_cool_clean"
+      },
+      "status": {
+        "0": "in_standby",
+        "1": "waking_up",
+        "2": "going_to_sleep",
+        "4": "descaling",
+        "5": "preparing_steam",
+        "7": "ready",
+        "8": "rinsing",
+        "10": "preparing_milk",
+        "11": "dispensing_hot_water",
+        "12": "cleaning_milk",
+        "16": "preparing_chocolate",
+        "17": "preparing_milk_alt",
+        "29": "unknown_29"
+      },
+      "action": {}
+    },
+    "flags": {
+      "is_watertank_open": {
+        "source": "alarms",
+        "byte": 1,
+        "bit": 5
+      },
+      "is_watertank_empty": {
+        "source": "alarms",
+        "byte": 0,
+        "bit": 0
+      },
+      "is_waste_container_missing": {
+        "source": "switches",
+        "byte": 0,
+        "bit": 3
+      }
+    },
+    "predicates": {
+      "is_busy": {
+        "kind": "not_equals",
+        "source": "action",
+        "value": 0
+      },
+      "is_idle": {
+        "kind": "equals",
+        "source": "action",
+        "value": 0
+      }
+    }
+  }
+}

cremalink/devices/__init__.py

@@ -0,0 +1,116 @@
+"""
+This module handles the discovery and loading of device definition files,
+referred to as "device maps."
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+import tempfile
+from pathlib import Path
+from typing import Any, List
+from importlib import resources
+
+
+class DeviceMapNotFoundError(FileNotFoundError):
+    """Custom exception raised when a specific device map cannot be found."""
+    pass
+
+
+def _normalize_model_id(model_id: str) -> str:
+    """
+    Cleans and validates the model ID string.
+
+    Args:
+        model_id: The raw model ID.
+
+    Returns:
+        A normalized model ID string.
+
+    Raises:
+        ValueError: If the model_id is empty or just whitespace.
+    """
+    if not model_id or not model_id.strip():
+        raise ValueError("device_map(model_id) requires a non-empty model_id.")
+    model_id = model_id.strip()
+    # Remove .json extension if present, case-insensitively.
+    if model_id.lower().endswith(".json"):
+        model_id = model_id[:-5]
+    return model_id
+
+
+def get_device_maps() -> List[str]:
+    """
+    Lists all available device maps by scanning the package data.
+
+    Returns:
+        A sorted list of unique model IDs (without the .json extension).
+    """
+    # Access the 'cremalink.devices' package as a resource container.
+    base = resources.files("cremalink.devices")
+    models: List[str] = []
+    for entry in base.iterdir():
+        # Find all .json files in the package.
+        if entry.is_file() and entry.name.lower().endswith(".json"):
+            models.append(Path(entry.name).stem)
+    # Return a sorted list of unique model names.
+    return sorted(set(models))
+
+
+def device_map(model_id: str) -> str:
+    """
+    Finds the absolute path to a device map file for a given model ID.
+
+    This function handles packaged resources, extracting them to a temporary
+    directory if they are not directly accessible on the filesystem.
+
+    Args:
+        model_id: The model ID of the device.
+
+    Returns:
+        The absolute path to the device map JSON file as a string.
+
+    Raises:
+        DeviceMapNotFoundError: If the map for the given model ID doesn't exist.
+    """
+    model_id = _normalize_model_id(model_id)
+    filename = f"{model_id}.json"
+
+    base = resources.files("cremalink.devices")
+    res: pathlib.Path = base.joinpath(filename)
+
+    if not res.exists():
+        available = get_device_maps()
+        raise DeviceMapNotFoundError(
+            f"Device map '{model_id}' not found. Available: {available}"
+        )
+
+    try:
+        # Efficiently get the file path if the resource is on the filesystem.
+        with resources.as_file(res) as p:
+            return str(Path(p))
+    except Exception:
+        # Fallback for zipped packages: copy the file to a temp location.
+        cache_dir = Path(tempfile.gettempdir()) / "cremalink_device_maps"
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        target = cache_dir / filename
+
+        # Write the file to the temp cache and return its path.
+        target.write_bytes(res.read_bytes())
+        return str(target)
+
+
+def load_device_map(model_id: str) -> dict[str, Any]:
+    """
+    Loads a device map from its JSON file into a dictionary.
+
+    Args:
+        model_id: The model ID of the device to load.
+
+    Returns:
+        A dictionary containing the device map data, or an empty dict on failure.
+    """
+    path = device_map(model_id)
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    return data if isinstance(data, dict) else {}

cremalink/domain/__init__.py

@@ -0,0 +1,11 @@
+"""
+This package defines the core domain models for the cremalink library,
+representing the main entities like the coffee machine itself.
+
+It exposes the primary `Device` class and factory functions for creating
+device instances, abstracting away the underlying implementation details.
+"""
+from cremalink.domain.device import Device
+from cremalink.domain.factory import create_cloud_device, create_local_device
+
+__all__ = ["Device", "create_cloud_device", "create_local_device"]