cremalink 0.1.0b5__py3-none-any.whl

cremalink/parsing/monitor/extractors.py

@@ -0,0 +1,69 @@
+"""
+This module provides extractor functions that pull data from a raw monitor frame.
+"""
+from __future__ import annotations
+
+import base64
+from typing import Any, Tuple
+
+from cremalink.parsing.monitor.frame import MonitorFrame
+
+
+def extract_fields_from_b64(
+    raw_b64: str,
+) -> Tuple[dict[str, Any], list[str], list[str], MonitorFrame | None]:
+    """
+    Parses a base64-encoded monitor string into a low-level MonitorFrame
+    and extracts its fields into a dictionary.
+
+    This function serves as the first step in the decoding pipeline. It handles
+    the initial, structural parsing of the byte frame and populates a dictionary
+    with the raw integer and byte values.
+
+    Args:
+        raw_b64: The base64-encoded monitor data string.
+
+    Returns:
+        A tuple containing:
+        - A dictionary of the extracted raw fields.
+        - A list of any warnings generated during parsing.
+        - A list of any errors encountered during parsing.
+        - The parsed `MonitorFrame` object, or None if parsing failed.
+    """
+    parsed: dict[str, Any] = {}
+    warnings: list[str] = []
+    errors: list[str] = []
+    frame: MonitorFrame | None = None
+    
+    # --- Step 1: Decode the raw bytes into a MonitorFrame ---
+    try:
+        frame = MonitorFrame.from_b64(raw_b64)
+    except Exception as exc:
+        # If frame parsing fails, record the error and exit.
+        errors.append(f"parse_failed: {exc}")
+        try:
+            # As a fallback, try to at least record the length of the raw data.
+            raw = base64.b64decode(raw_b64)
+            parsed["raw_length"] = len(raw)
+        except Exception:
+            pass
+        return parsed, warnings, errors, frame
+
+    # --- Step 2: Populate the 'parsed' dictionary with the frame's fields ---
+    parsed.update(
+        {
+            "accessory": frame.accessory,
+            "switches": list(frame.switches),
+            "alarms": list(frame.alarms),
+            "status": frame.status,
+            "action": frame.action,
+            "progress": frame.progress,
+            "direction": frame.direction,
+            "request_id": frame.request_id,
+            "answer_required": frame.answer_required,
+            "timestamp": frame.timestamp.hex() if frame.timestamp else "",
+            "extra": frame.extra.hex() if frame.extra else "",
+        }
+    )
+
+    return parsed, warnings, errors, frame

cremalink/parsing/monitor/frame.py

@@ -0,0 +1,132 @@
+"""
+This module defines the low-level structure of a "monitor" data frame.
+It handles the byte-level decoding of the raw payload from the device.
+"""
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+
+from cremalink.core.binary import crc16_ccitt
+
+
+@dataclass
+class MonitorFrame:
+    """
+    Represents the decoded, low-level structure of a monitor data frame.
+
+    This class takes the raw bytes from a monitor update and parses them into
+    their fundamental components according to the device's binary protocol.
+    This includes separating headers, payload, checksums, and timestamps.
+    """
+    # --- Frame Header/Metadata ---
+    direction: int
+    request_id: int
+    answer_required: int
+    # --- Core Payload Fields ---
+    accessory: int
+    switches: bytes
+    alarms: bytes
+    status: int
+    action: int
+    progress: int
+    # --- Frame Footer/Extra Data ---
+    timestamp: bytes
+    extra: bytes
+    # --- Raw Data ---
+    raw: bytes
+    raw_b64: str
+
+    @classmethod
+    def from_b64(cls, raw_b64: str) -> "MonitorFrame":
+        """
+        Decodes a base64 string into a structured MonitorFrame.
+
+        This factory method performs the primary byte-level parsing, including:
+        - Base64 decoding.
+        - Length validation.
+        - CRC-16 checksum verification.
+        - Splitting the raw bytes into their respective fields (header, payload, etc.).
+
+        Args:
+            raw_b64: The base64-encoded monitor data string.
+
+        Returns:
+            A populated MonitorFrame instance.
+
+        Raises:
+            ValueError: If the data is malformed, too short, or fails the CRC check.
+        """
+        raw = base64.b64decode(raw_b64)
+        if len(raw) < 4:
+            raise ValueError("Raw data is too short to contain a monitor frame")
+        
+        # --- Unpack the outer frame ---
+        direction = raw[0]
+        length = raw[1]
+        if length < 4 or len(raw) < length + 1:
+            raise ValueError("Length byte inconsistent with payload")
+        
+        data = raw[2: length - 1]
+        crc = raw[length - 1: length + 1]
+        
+        # --- Verify CRC ---
+        if crc != crc16_ccitt(raw[: length - 1]):
+            raise ValueError("CRC check failed")
+        
+        timestamp = raw[length + 1: length + 5]
+        extra = raw[length + 5:]
+
+        # --- Unpack the inner monitor data payload ---
+        if len(data) < 2:
+            raise ValueError("Monitor payload too short")
+        request_id = data[0]
+        answer_required = data[1]
+        contents = data[2:]
+        
+        # This implementation assumes a "V2" frame structure with 13 bytes of contents.
+        if len(contents) != 13:
+            raise ValueError("Monitor contents expected to be 13 bytes for V2 frames")
+        
+        accessory = contents[0]
+        switches = contents[1:3]
+        # Alarms are non-contiguous in the payload, so they are concatenated here.
+        alarms = contents[3:5] + contents[8:10]
+        status = contents[5]
+        action = contents[6]
+        progress = contents[7]
+
+        return cls(
+            direction=direction,
+            request_id=request_id,
+            answer_required=answer_required,
+            accessory=accessory,
+            switches=switches,
+            alarms=alarms,
+            status=status,
+            action=action,
+            progress=progress,
+            timestamp=timestamp,
+            extra=extra,
+            raw=raw,
+            raw_b64=raw_b64,
+        )
+
+    def as_dict(self) -> dict:
+        """
+        Returns a dictionary representation of the frame's contents.
+        This is useful for serialization or debugging.
+        """
+        return {
+            "direction": self.direction,
+            "request_id": self.request_id,
+            "answer_required": self.answer_required,
+            "accessory": self.accessory,
+            "switches": list(self.switches),
+            "alarms": list(self.alarms),
+            "status": self.status,
+            "action": self.action,
+            "progress": self.progress,
+            "timestamp": self.timestamp.hex() if self.timestamp else "",
+            "extra": self.extra.hex() if self.extra else "",
+        }

cremalink/parsing/monitor/model.py

@@ -0,0 +1,42 @@
+"""
+This module defines the high-level data model for a "monitor" data snapshot.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Optional
+
+from cremalink.parsing.monitor.frame import MonitorFrame
+
+
+@dataclass
+class MonitorSnapshot:
+    """
+    Represents a single snapshot of the device's monitoring status.
+
+    This dataclass acts as a container for all information related to a single
+    monitor update from the device. It holds the raw data, timestamps, any
+    parsed values, and metadata about the decoding process.
+
+    Attributes:
+        raw: The raw bytes of the monitor data payload.
+        raw_b64: The base64-encoded string representation of the raw data.
+        received_at: The timestamp when this snapshot was received.
+        parsed: A dictionary to hold the successfully parsed key-value data.
+        warnings: A list of any warnings generated during parsing.
+        errors: A list of any errors encountered during parsing.
+        source: The origin of the data (e.g., 'local' or 'cloud').
+        device_id: The identifier of the device that sent the data.
+        frame: A `MonitorFrame` instance if the raw bytes were successfully
+               decoded into a low-level frame structure.
+    """
+    raw: bytes
+    raw_b64: str
+    received_at: datetime
+    parsed: dict[str, Any] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    source: str = "local"
+    device_id: Optional[str] = None
+    frame: Optional[MonitorFrame] = None

cremalink/parsing/monitor/profile.py

@@ -0,0 +1,144 @@
+"""
+This module defines the data structures for a "Monitor Profile". A profile is a
+declarative configuration that describes how to interpret the raw bytes of a
+monitor frame for a specific device model.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, Optional
+
+# A set of valid source fields within the MonitorFrame.
+VALID_SOURCES = {"alarms", "switches", "status", "action", "progress", "accessory"}
+
+
+@dataclass
+class FlagDefinition:
+    """
+    Defines how to extract a boolean flag from a specific bit in a byte array.
+    This is used for parsing the 'alarms' and 'switches' byte fields.
+    """
+    source: str
+    byte: int
+    bit: int
+    invert: bool = False
+    description: Optional[str] = None
+
+    def validate(self) -> None:
+        """Checks if the definition is valid."""
+        if self.source not in {"alarms", "switches"}:
+            raise ValueError("flag source must be 'alarms' or 'switches'")
+        if self.byte < 0:
+            raise ValueError("byte must be non-negative")
+        if self.bit < 0 or self.bit > 7:
+            raise ValueError("bit must be between 0 and 7")
+
+
+@dataclass
+class PredicateDefinition:
+    """
+    Defines a logical condition to be evaluated against the monitor frame data.
+    Predicates are used to create higher-level boolean states, like "is_on"
+    or "is_making_coffee".
+    """
+    kind: str
+    source: Optional[str] = None
+    value: Any = None
+    values: Iterable[Any] | None = None
+    flag: str | None = None
+    byte: int | None = None
+    bit: int | None = None
+
+    def validate(self) -> None:
+        """Checks if the predicate definition is valid."""
+        if self.kind not in {
+            "equals", "not_equals", "in_set", "not_in_set",
+            "flag_true", "flag_false", "bit_set", "bit_clear",
+        }:
+            raise ValueError(f"Unsupported predicate kind: {self.kind}")
+        if self.source and self.source not in VALID_SOURCES:
+            raise ValueError(f"source must be one of {sorted(VALID_SOURCES)}")
+        if self.bit is not None and (self.bit < 0 or self.bit > 7):
+            raise ValueError("bit must be between 0 and 7")
+
+    def uses_flag(self) -> bool:
+        """Returns True if the predicate depends on a named flag."""
+        return self.kind in {"flag_true", "flag_false"}
+
+    def uses_bit_address(self) -> bool:
+        """Returns True if the predicate directly addresses a bit."""
+        return self.kind in {"bit_set", "bit_clear"}
+
+
+@dataclass
+class MonitorProfile:
+    """
+    A complete profile for parsing a device's monitor frame.
+
+    This class holds all the definitions needed to translate the raw bytes of a
+    monitor frame into meaningful, human-readable data. It is typically loaded
+    from a device-specific JSON file.
+    """
+    flags: Dict[str, FlagDefinition] = field(default_factory=dict)
+    enums: Dict[str, Dict[int, str]] = field(default_factory=dict)
+    predicates: Dict[str, PredicateDefinition] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict | None) -> "MonitorProfile":
+        """
+        Constructs a MonitorProfile from a dictionary (e.g., from a JSON file).
+        """
+        if not data:
+            return cls()
+        
+        # --- Load Flag Definitions ---
+        flags = {}
+        for name, flag_data in (data.get("flags") or {}).items():
+            flag = FlagDefinition(
+                source=flag_data.get("source"),
+                byte=int(flag_data.get("byte", 0)),
+                bit=int(flag_data.get("bit", 0)),
+                invert=bool(flag_data.get("invert", False)),
+                description=flag_data.get("description"),
+            )
+            flag.validate()
+            flags[name] = flag
+
+        # --- Load Predicate Definitions ---
+        predicates = {}
+        for name, pred_data in (data.get("predicates") or {}).items():
+            pred = PredicateDefinition(
+                kind=pred_data.get("kind"),
+                source=pred_data.get("source"),
+                value=pred_data.get("value"),
+                values=pred_data.get("values") or pred_data.get("set") or pred_data.get("in"),
+                flag=pred_data.get("flag"),
+                byte=pred_data.get("byte"),
+                bit=pred_data.get("bit"),
+            )
+            pred.validate()
+            predicates[name] = pred
+
+        # --- Load Enum Mappings ---
+        enums = {
+            name: {int(k): v for k, v in (mapping or {}).items()}
+            for name, mapping in (data.get("enums", {}) or {}).items()
+        }
+
+        return cls(flags=flags, enums=enums, predicates=predicates)
+
+    def available_fields(self) -> list[str]:
+        """Returns a sorted list of all defined flag and predicate names."""
+        dynamic = list(self.flags.keys()) + list(self.predicates.keys())
+        return sorted(set(dynamic))
+
+    def summary(self) -> dict[str, Any]:
+        """Provides a brief summary of the profile's contents."""
+        return {
+            "flags": list(self.flags.keys()),
+            "enums": {name: list(mapping.keys()) for name, mapping in self.enums.items()},
+            "predicates": list(self.predicates.keys()),
+        }
+
+
+__all__ = ["FlagDefinition", "PredicateDefinition", "MonitorProfile"]

cremalink/parsing/monitor/view.py

@@ -0,0 +1,196 @@
+"""
+This module provides the `MonitorView` class, which offers a high-level,
+user-friendly interface for accessing data from a `MonitorSnapshot`.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from cremalink.core.binary import get_bit
+from cremalink.parsing.monitor.frame import MonitorFrame
+from cremalink.parsing.monitor.model import MonitorSnapshot
+from cremalink.parsing.monitor.profile import MonitorProfile, PredicateDefinition
+
+
+class MonitorView:
+    """
+    A user-friendly view of a `MonitorSnapshot`, powered by a `MonitorProfile`.
+
+    This class acts as a wrapper around a `MonitorSnapshot`. It uses a given
+    `MonitorProfile` to translate raw, low-level data (like integer codes and
+    bit flags) into human-readable values (like enum names and boolean predicates).
+
+    It provides dynamic attribute access (`__getattr__`) to resolve flags and
+    predicates from the profile on the fly. For example, `view.is_on` or
+    `view.has_descaling_alarm`.
+    """
+
+    def __init__(self, snapshot: MonitorSnapshot, profile: MonitorProfile | dict[str, Any] | None = None) -> None:
+        """
+        Initializes the MonitorView.
+
+        Args:
+            snapshot: The `MonitorSnapshot` containing the data to be viewed.
+            profile: A `MonitorProfile` or a dictionary to build one from. This
+                     profile dictates how the raw data is interpreted.
+        """
+        self.snapshot = snapshot
+        # Ensure profile is always a MonitorProfile instance.
+        self.profile = profile if isinstance(profile, MonitorProfile) else MonitorProfile.from_dict(profile or {})
+        
+        # Attempt to get or parse the low-level MonitorFrame.
+        self._frame: Optional[MonitorFrame] = snapshot.frame
+        if self._frame is None and snapshot.raw_b64:
+            try:
+                self._frame = MonitorFrame.from_b64(snapshot.raw_b64)
+            except Exception:
+                self._frame = None
+
+    # --- raw accessors ---
+    @property
+    def raw(self) -> bytes:
+        """The raw bytes of the monitor payload."""
+        return self.snapshot.raw
+
+    @property
+    def raw_b64(self) -> str:
+        """The base64-encoded string of the monitor payload."""
+        return self.snapshot.raw_b64
+
+    @property
+    def parsed(self) -> dict[str, Any]:
+        """The dictionary of initially parsed, low-level fields."""
+        return self.snapshot.parsed
+
+    @property
+    def received_at(self):
+        """The timestamp when the snapshot was received."""
+        return self.snapshot.received_at
+
+    # --- standard fields ---
+    @property
+    def status_code(self) -> Optional[int]:
+        """The raw integer code for the device's main status."""
+        return self._frame.status if self._frame else None
+
+    @property
+    def action_code(self) -> Optional[int]:
+        """The raw integer code for the device's current action."""
+        return self._frame.action if self._frame else None
+
+    @property
+    def progress_percent(self) -> Optional[int]:
+        """The progress percentage (0-100) of the current action."""
+        return self._frame.progress if self._frame else None
+
+    @property
+    def accessory_code(self) -> Optional[int]:
+        """The raw integer code for the currently detected accessory."""
+        return self._frame.accessory if self._frame else None
+
+    # --- enum mapping ---
+    def _enum_lookup(self, enum_name: str, code: Optional[int]) -> Optional[str]:
+        """Looks up an enum name from a code using the profile."""
+        if code is None:
+            return None
+        mapping = self.profile.enums.get(enum_name, {})
+        # Return the string name, or the original code as a string if not found.
+        return mapping.get(int(code), str(code))
+
+    @property
+    def status_name(self) -> Optional[str]:
+        """The human-readable name of the device's status (e.g., 'Standby')."""
+        return self._enum_lookup("status", self.status_code)
+
+    @property
+    def action_name(self) -> Optional[str]:
+        """The human-readable name of the device's action (e.g., 'Brewing')."""
+        return self._enum_lookup("action", self.action_code)
+
+    @property
+    def accessory_name(self) -> Optional[str]:
+        """The human-readable name of the accessory (e.g., 'Milk Carafe')."""
+        return self._enum_lookup("accessory", self.accessory_code)
+
+    # --- flag/predicate helpers ---
+    def _resolve_flag(self, flag_name: str) -> Optional[bool]:
+        """Resolves a named boolean flag using its definition in the profile."""
+        if not self._frame:
+            return None
+        flag_def = self.profile.flags.get(flag_name)
+        if not flag_def:
+            return None
+        
+        data_bytes = self._frame.alarms if flag_def.source == "alarms" else self._frame.switches
+        if flag_def.byte >= len(data_bytes):
+            return None
+        
+        byte_val = data_bytes[flag_def.byte]
+        value = get_bit(byte_val, flag_def.bit)
+        return not value if flag_def.invert else value
+
+    def _source_value(self, source: str) -> Any:
+        """Gets a raw value from the frame by its source name."""
+        if not self._frame:
+            return None
+        return {
+            "alarms": self._frame.alarms,
+            "switches": self._frame.switches,
+            "status": self._frame.status,
+            "action": self._frame.action,
+            "progress": self._frame.progress,
+            "accessory": self._frame.accessory,
+        }.get(source)
+
+    def _evaluate_predicate(self, definition: PredicateDefinition) -> Optional[bool]:
+        """Evaluates a named predicate using its definition in the profile."""
+        try:
+            if definition.uses_flag():
+                flag_value = self._resolve_flag(definition.flag or "")
+                if flag_value is None:
+                    return None
+                return flag_value if definition.kind == "flag_true" else not flag_value
+
+            if definition.uses_bit_address():
+                if not self._frame or not definition.source:
+                    return None
+                source_bytes = self._frame.alarms if definition.source == "alarms" else self._frame.switches
+                if definition.byte is None or definition.byte >= len(source_bytes) or definition.bit is None:
+                    return None
+                bit_value = get_bit(source_bytes[definition.byte], definition.bit)
+                return bit_value if definition.kind == "bit_set" else not bit_value
+
+            source_val = self._source_value(definition.source) if definition.source else None
+            if definition.kind == "equals":
+                return source_val == definition.value
+            if definition.kind == "not_equals":
+                return source_val != definition.value
+            if definition.kind == "in_set":
+                return source_val in set(definition.values or [])
+            if definition.kind == "not_in_set":
+                return source_val not in set(definition.values or [])
+        except Exception:
+            return None
+        return None
+
+    # --- dynamic access ---
+    @property
+    def available_fields(self) -> list[str]:
+        """A list of all available dynamic fields (flags and predicates)."""
+        return self.profile.available_fields()
+
+    @property
+    def profile_summary(self) -> dict[str, Any]:
+        """A summary of the loaded profile."""
+        return self.profile.summary()
+
+    def __getattr__(self, item: str) -> Any:
+        """
+        Dynamically resolves flags and predicates from the profile.
+        This allows for accessing profile-defined fields like `view.is_on`.
+        """
+        if item in self.profile.flags:
+            return self._resolve_flag(item)
+        if item in self.profile.predicates:
+            return self._evaluate_predicate(self.profile.predicates[item])
+        raise AttributeError(f"{self.__class__.__name__} has no attribute '{item}'")

cremalink/parsing/properties/__init__.py

@@ -0,0 +1,9 @@
+"""
+This package handles the parsing and decoding of device 'properties'.
+
+Properties are key-value pairs that represent the static or semi-static
+attributes of the coffee machine, such as configuration settings or counters.
+"""
+from cremalink.parsing.properties.decode import PropertiesSnapshot
+
+__all__ = ["PropertiesSnapshot"]

cremalink/parsing/properties/decode.py

@@ -0,0 +1,53 @@
+"""
+This module provides classes for handling and decoding device properties.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Optional
+
+
+@dataclass
+class PropertiesSnapshot:
+    """
+    A container for a snapshot of device properties at a specific time.
+
+    This class holds the raw property data as received from the device,
+    the timestamp of when it was received, and a dictionary for any parsed
+    or processed values. It provides a helper method to easily access
+    property values from the potentially nested raw data structure.
+
+    Attributes:
+        raw: The raw dictionary of properties from the device.
+        received_at: The timestamp when the snapshot was taken.
+        parsed: A dictionary to hold processed or parsed property values.
+    """
+    raw: dict[str, Any]
+    received_at: Optional[datetime]
+    parsed: dict[str, Any] = field(default_factory=dict)
+
+    def get(self, name: str) -> Any:
+        """
+        Safely retrieves a property by its name from the raw data.
+
+        The properties data can come in different formats. This method checks
+        for the property name as a direct key and also searches within the
+        nested 'property' objects that are common in the API response.
+
+        Args:
+            name: The name of the property to retrieve.
+
+        Returns:
+            The property dictionary if found, otherwise None.
+        """
+        # First, check if the name is a top-level key in the raw dictionary.
+        if name in self.raw:
+            return self.raw[name]
+
+        # If not, iterate through the values to find a nested property object.
+        # This handles the common format: `{'some_id': {'property': {'name': name, ...}}}`
+        for entry in self.raw.values():
+            if isinstance(entry, dict) and entry.get("property", {}).get("name") == name:
+                return entry
+        return None

cremalink/resources/__init__.py

@@ -0,0 +1,10 @@
+"""
+This package contains static resources and configuration files for the cremalink
+library, such as API keys and language mappings.
+
+It provides helper functions to access these resources in a way that is
+compatible with standard Python packaging.
+"""
+from cremalink.resources.api_config import load_api_config
+
+__all__ = ["load_api_config"]

cremalink/resources/api_config.json

@@ -0,0 +1,14 @@
+{
+  "GIGYA": {
+    "API_KEY": "3_e5qn7USZK-QtsIso1wCelqUKAK_IVEsYshRIssQ-X-k55haiZXmKWDHDRul2e5Y2",
+    "CLIENT_ID": "1S8q1WJEs-emOB43Z0-66WnL",
+    "CLIENT_SECRET": "lmnceiD0B-4KPNN5ZS6WuWU70j9V5BCuSlz2OPsvHkyLryhMkJkPvKsivfTq3RfNYj8GpCELtOBvhaDIzKcBtg",
+    "SDK_BUILD": "16650"
+  },
+  "AYLA": {
+    "APP_ID": "DeLonghiComfort2-mw-id",
+    "APP_SECRET": "DeLonghiComfort2-Yg4miiqiNcf0Or-EhJwRh7ACfBY",
+    "API_URL": "https://ads-eu.aylanetworks.com/apiv1",
+    "OAUTH_URL": "https://user-field-eu.aylanetworks.com"
+  }
+}