pysaeco 0.1.0__py3-none-any.whl

pysaeco/__init__.py

@@ -0,0 +1,6 @@
+"""Python library for Saeco-family coffee machines."""
+
+from pysaeco.avanti import MachineStatus
+from pysaeco.client import SaecoClient, scan
+
+__all__ = ["MachineStatus", "SaecoClient", "scan"]

pysaeco/avanti.py

@@ -0,0 +1,616 @@
+from __future__ import annotations
+
+import ast
+import binascii
+import json
+from dataclasses import dataclass
+from enum import IntEnum, StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+SERVICE_UUID = "b8e06067-62ad-41ba-9231-206ae80ab550"
+RESPONSE_CHAR_UUID = "f897177b-aee8-4767-8ecc-cc694fd5fcee"
+WAKEUP_CHAR_UUID = "2fbc0f31-726a-4014-b9fe-c8be0652e982"
+COMMAND_CHAR_UUID = "bf45e40a-de2a-4bc8-bba0-e5d6065f1b4b"
+WAKEUP_VALUE = b"\xaa"
+DEFAULT_COMMAND_HANDLE = 0x1234
+
+
+class AvantiCommand(IntEnum):
+    ENTER_STANDBY = 0x10
+    SHOW_PIN = 0x18
+    READ_STATUS = 0x52
+    BREW_PRODUCT = 0xC0
+    STOP_BREWING = 0x50
+
+
+class AvantiResponse(IntEnum):
+    ENTER_STANDBY = 0x11
+    SHOW_PIN = 0x19
+    READ_STATUS = 0x53
+    STOP_BREWING = 0x51
+    BREW_PRODUCT = 0xC1
+    CRC_ERROR = 0xE0
+    LEN_ERROR = 0xE1
+    CMD_ERROR = 0xE2
+    PIN_ERROR = 0xE3
+
+
+ERROR_RESPONSES = frozenset(
+    {
+        AvantiResponse.CRC_ERROR,
+        AvantiResponse.LEN_ERROR,
+        AvantiResponse.CMD_ERROR,
+        AvantiResponse.PIN_ERROR,
+    }
+)
+
+
+class AvantiError(Exception):
+    """Base exception for Avanti protocol failures."""
+
+
+class AvantiResponseCrcError(AvantiError):
+    def __init__(self, frame: AvantiFrame) -> None:
+        self.frame = frame
+        super().__init__(
+            f"machine response {frame.response_name} failed CRC validation "
+            f"(payload={frame.payload.hex()})"
+        )
+
+
+class AvantiProtocolError(AvantiError):
+    def __init__(self, frame: AvantiFrame | None = None, message: str | None = None) -> None:
+        self.frame = frame
+        if message is None and frame is not None:
+            message = f"machine returned {frame.response_name} (payload={frame.payload.hex()})"
+        super().__init__(message or "Avanti protocol error")
+
+
+class AvantiCommandCrcError(AvantiProtocolError):
+    """The machine rejected a command because its CRC was invalid."""
+
+
+class AvantiCommandLengthError(AvantiProtocolError):
+    """The machine rejected a command because its length was invalid."""
+
+
+class AvantiCommandError(AvantiProtocolError):
+    """The machine rejected an unsupported or invalid command."""
+
+
+class AvantiPinError(AvantiProtocolError):
+    """The machine rejected the command PIN/handle."""
+
+
+class AvantiNoResponseError(AvantiProtocolError):
+    """The machine did not return a response frame."""
+
+
+class AvantiUnexpectedResponseError(AvantiProtocolError):
+    """The machine returned valid frames, but not the response we expected."""
+
+    def __init__(self, expected: AvantiResponse, frames: list[AvantiFrame]) -> None:
+        self.expected = expected
+        self.frames = frames
+        names = ", ".join(frame.response_name for frame in frames) or "none"
+        super().__init__(message=f"expected {expected.name.lower()} response, got {names}")
+
+
+PROTOCOL_ERROR_TYPES: dict[AvantiResponse, type[AvantiProtocolError]] = {
+    AvantiResponse.CRC_ERROR: AvantiCommandCrcError,
+    AvantiResponse.LEN_ERROR: AvantiCommandLengthError,
+    AvantiResponse.CMD_ERROR: AvantiCommandError,
+    AvantiResponse.PIN_ERROR: AvantiPinError,
+}
+
+
+class PowerState(StrEnum):
+    UNKNOWN = "unknown"
+    OFF = "off"
+    ON = "on"
+
+
+class BrewState(StrEnum):
+    IDLE = "idle"
+    BREWING = "brewing"
+    RINSING = "rinsing"
+    CLEANING = "cleaning"
+    DESCALING = "descaling"
+    BUSY = "busy"
+    ERROR = "error"
+
+
+class MachinePhase(IntEnum):
+    READY = 0
+    STOPPING_AFTER_ABORT = 16
+    DESCALING_PHASE_1 = 41
+    DESCALING_PHASE_2 = 42
+    CARAFE_WASHING_PHASE_1 = 50
+    CARAFE_WASHING_PHASE_2 = 51
+    BREWGROUP_CLEANING = 60
+    WATER_FILTER_ACTIVATION = 71
+    BREWING = 80
+    WATER_CIRCUIT_PRIMING = 81
+    PRESSURE_RECOVERY = 82
+    CARAFE_AUTOCLEAN = 85
+    BUSY = 90
+    SHUTTING_DOWN = 170
+    SHUTTING_DOWN_RINSING = 171
+    STARTING_UP = 186
+    STARTING_UP_HEATING_UP = 187
+
+
+class MaintenanceStatus(IntEnum):
+    NONE = 0
+    REPLACE_WATER_FILTER = 1
+    DESCALING_NEEDED = 2
+
+
+WARNING_NAMES: dict[int, str] = {
+    1: "refill_water_tank",
+    2: "refill_coffee_beans",
+    4: "empty_drip_tray",
+    8: "close_front_door",
+    16: "insert_brew_group",
+    32: "insert_dreg_drawer",
+    64: "close_bean_hopper",
+    128: "empty_dreg_drawer",
+}
+
+
+FEATURE_NAMES: dict[int, str] = {
+    1: "bean_hopper_door_present",
+    2: "water_filter_present",
+}
+
+
+@dataclass(frozen=True)
+class AvantiRecipe:
+    product_number: int
+    coffee_ml: int = 0
+    milk_ml: int = 0
+    aroma: int = 3
+    prebrew: int = 1
+    temperature: int = 1
+    coffee_min_ml: int = 0
+    coffee_max_ml: int = 0
+    milk_min_ml: int = 0
+    milk_max_ml: int = 0
+
+    @property
+    def id(self) -> int:
+        return self.product_number
+
+    @property
+    def name(self) -> str:
+        words = []
+        for char in type(self).__name__:
+            if char.isupper() and words:
+                words.append(" ")
+            words.append(char)
+        return "".join(words)
+
+    @property
+    def slug(self) -> str:
+        return slugify(f"{self.id}_{self.name}")
+
+    @property
+    def expression(self) -> str:
+        args: dict[str, int] = {
+            "coffee_ml": self.coffee_ml,
+            "aroma": self.aroma,
+            "prebrew": self.prebrew,
+            "temperature": self.temperature,
+        }
+        if self.milk_ml:
+            args["milk_ml"] = self.milk_ml
+        rendered = ", ".join(f"{name}={value}" for name, value in args.items())
+        return f"{type(self).__name__}({rendered})"
+
+    def payload(self) -> bytes:
+        coffee_quantity = 0
+        if self.coffee_ml != 0:
+            coffee_quantity = amount_ml_to_scalar(
+                self.coffee_ml,
+                self.coffee_min_ml,
+                self.coffee_max_ml,
+                "coffee",
+            )
+
+        milk_quantity = 0
+        if self.milk_ml != 0:
+            milk_quantity = amount_ml_to_scalar(
+                self.milk_ml,
+                self.milk_min_ml,
+                self.milk_max_ml,
+                "milk",
+            )
+
+        return bytes(
+            [
+                self.product_number & 0xFF,
+                self.aroma & 0xFF,
+                self.prebrew & 0xFF,
+                coffee_quantity & 0xFF,
+                self.temperature & 0xFF,
+                milk_quantity & 0xFF,
+                0x7B,
+                0x00,
+            ]
+        )
+
+
+@dataclass(frozen=True)
+class Espresso(AvantiRecipe):
+    def __init__(
+        self,
+        *,
+        coffee_ml: int = 50,
+        aroma: int = 5,
+        prebrew: int = 1,
+        temperature: int = 1,
+    ) -> None:
+        super().__init__(
+            product_number=1,
+            coffee_ml=coffee_ml,
+            aroma=aroma,
+            prebrew=prebrew,
+            temperature=temperature,
+            coffee_min_ml=30,
+            coffee_max_ml=70,
+        )
+
+
+@dataclass(frozen=True)
+class Coffee(AvantiRecipe):
+    def __init__(
+        self,
+        *,
+        coffee_ml: int = 110,
+        aroma: int = 3,
+        prebrew: int = 1,
+        temperature: int = 1,
+    ) -> None:
+        super().__init__(
+            product_number=3,
+            coffee_ml=coffee_ml,
+            aroma=aroma,
+            prebrew=prebrew,
+            temperature=temperature,
+            coffee_min_ml=70,
+            coffee_max_ml=140,
+        )
+
+
+@dataclass(frozen=True)
+class AmericanCoffee(AvantiRecipe):
+    def __init__(
+        self,
+        *,
+        coffee_ml: int = 170,
+        aroma: int = 3,
+        prebrew: int = 1,
+        temperature: int = 1,
+    ) -> None:
+        super().__init__(
+            product_number=4,
+            coffee_ml=coffee_ml,
+            aroma=aroma,
+            prebrew=prebrew,
+            temperature=temperature,
+            coffee_min_ml=110,
+            coffee_max_ml=320,
+        )
+
+
+@dataclass(frozen=True)
+class Cappuccino(AvantiRecipe):
+    def __init__(
+        self,
+        *,
+        coffee_ml: int = 70,
+        milk_ml: int = 70,
+        aroma: int = 5,
+        prebrew: int = 1,
+        temperature: int = 1,
+    ) -> None:
+        super().__init__(
+            product_number=10,
+            coffee_ml=coffee_ml,
+            milk_ml=milk_ml,
+            aroma=aroma,
+            prebrew=prebrew,
+            temperature=temperature,
+            coffee_min_ml=30,
+            coffee_max_ml=170,
+            milk_min_ml=40,
+            milk_max_ml=200,
+        )
+
+
+@dataclass(frozen=True)
+class AvantiFrame:
+    response: int
+    payload: bytes
+    crc_ok: bool
+
+    @property
+    def response_name(self) -> str:
+        try:
+            return AvantiResponse(self.response).name.lower()
+        except ValueError:
+            return "unknown"
+
+
+def raise_for_response_errors(frames: list[AvantiFrame]) -> None:
+    for frame in frames:
+        if not frame.crc_ok:
+            raise AvantiResponseCrcError(frame)
+        try:
+            response = AvantiResponse(frame.response)
+        except ValueError:
+            continue
+        if response in ERROR_RESPONSES:
+            raise PROTOCOL_ERROR_TYPES[response](frame)
+
+
+def require_response(frames: list[AvantiFrame], expected: AvantiResponse) -> None:
+    if not frames:
+        raise AvantiNoResponseError(message=f"expected {expected.name.lower()} response")
+    if not any(frame.response == expected for frame in frames):
+        raise AvantiUnexpectedResponseError(expected, frames)
+
+
+class MachineStatus(BaseModel):
+    """State document published to MQTT."""
+
+    model_config = ConfigDict(frozen=True)
+
+    power: PowerState = PowerState.UNKNOWN
+    running: bool = False
+    brew: BrewState = BrewState.IDLE
+    error: int = 0
+    warning: tuple[str, ...] = ()
+    maintenance: str | None = None
+    phase: int | None = None
+    features: tuple[str, ...] = ()
+    phase_name: str | None = None
+    descaling_needed: bool = False
+    raw: dict[str, object] = Field(default_factory=dict)
+
+    @classmethod
+    def from_avanti_frames(
+        cls,
+        frames: list[AvantiFrame],
+    ) -> MachineStatus:
+        frame_list = list(frames)
+        raw_frames = [_frame_to_raw(frame) for frame in frame_list]
+        status_frame = next(
+            (
+                frame
+                for frame in reversed(frame_list)
+                if frame.crc_ok
+                and frame.response == AvantiResponse.READ_STATUS
+                and len(frame.payload) >= 5
+            ),
+            None,
+        )
+        if status_frame is None:
+            return cls(raw={"transport": "ble", "frames": raw_frames})
+
+        error, warning, maintenance, phase, features = status_frame.payload[:5]
+        brew = _brew_for_status(error, phase)
+        return cls(
+            power=_power_for_phase(phase),
+            running=brew != BrewState.IDLE,
+            brew=brew,
+            error=error,
+            warning=_active_names(warning, WARNING_NAMES),
+            maintenance=_maintenance_name(maintenance),
+            phase=phase,
+            features=_active_names(features, FEATURE_NAMES),
+            phase_name=_enum_name(MachinePhase, phase),
+            descaling_needed=maintenance == MaintenanceStatus.DESCALING_NEEDED,
+            raw={"transport": "ble", "frames": raw_frames},
+        )
+
+
+def crc16_ccitt(data: bytes) -> int:
+    return binascii.crc_hqx(data, 0xFFFF)
+
+
+def build_command_packet(
+    command: AvantiCommand | int,
+    payload: bytes = b"",
+    handle: int = DEFAULT_COMMAND_HANDLE,
+) -> bytes:
+    if not 0 <= handle <= 0xFFFF:
+        raise ValueError("command handle must fit in 16 bits")
+    body = bytes([(handle >> 8) & 0xFF, handle & 0xFF, int(command) & 0xFF]) + payload
+    crc = crc16_ccitt(body)
+    return (
+        bytes([0xFE, 0xFF, 0x0F, (len(body) >> 8) & 0xFF, len(body) & 0xFF])
+        + body
+        + bytes([(crc >> 8) & 0xFF, crc & 0xFF])
+    )
+
+
+def parse_response_frame(data: bytes) -> AvantiFrame | None:
+    if len(data) < 8 or data[:3] != b"\xfe\xff\x0f":
+        return None
+    length = (data[3] << 8) | data[4]
+    body = data[5 : 5 + length]
+    if not body or len(data) < 7 + length:
+        return None
+    expected_crc = int.from_bytes(data[5 + length : 7 + length], "big")
+    return AvantiFrame(body[0], body[1:], expected_crc == crc16_ccitt(body))
+
+
+def _frame_to_raw(frame: object) -> dict[str, object]:
+    return {
+        "response": frame.response,
+        "response_name": frame.response_name,
+        "payload": frame.payload.hex(),
+        "crc_ok": frame.crc_ok,
+    }
+
+
+def _enum_name(enum: type[IntEnum], value: int) -> str | None:
+    try:
+        return enum(value).name.lower()
+    except ValueError:
+        return None
+
+
+def _maintenance_name(value: int) -> str | None:
+    if value == MaintenanceStatus.NONE:
+        return None
+    return _enum_name(MaintenanceStatus, value) or "unknown"
+
+
+def _active_names(value: int, names: dict[int, str]) -> tuple[str, ...]:
+    return tuple(name for bit, name in names.items() if value & bit)
+
+
+def _power_for_phase(phase: int) -> PowerState:
+    del phase
+    return PowerState.ON
+
+
+def _brew_for_status(error: int, phase: int) -> BrewState:
+    if error:
+        return BrewState.ERROR
+    if phase in {MachinePhase.BREWING, MachinePhase.CARAFE_AUTOCLEAN}:
+        return BrewState.BREWING
+    if phase in {
+        MachinePhase.CARAFE_WASHING_PHASE_1,
+        MachinePhase.CARAFE_WASHING_PHASE_2,
+        MachinePhase.SHUTTING_DOWN_RINSING,
+    }:
+        return BrewState.RINSING
+    if phase == MachinePhase.BREWGROUP_CLEANING:
+        return BrewState.CLEANING
+    if phase in {MachinePhase.DESCALING_PHASE_1, MachinePhase.DESCALING_PHASE_2}:
+        return BrewState.DESCALING
+    if phase in {
+        MachinePhase.BUSY,
+        MachinePhase.STARTING_UP,
+        MachinePhase.STARTING_UP_HEATING_UP,
+        MachinePhase.WATER_CIRCUIT_PRIMING,
+        MachinePhase.WATER_FILTER_ACTIVATION,
+        MachinePhase.PRESSURE_RECOVERY,
+    }:
+        return BrewState.BUSY
+    return BrewState.IDLE
+
+
+class ResponseAssembler:
+    def __init__(self) -> None:
+        self.buffer = bytearray()
+
+    def feed(self, data: bytes) -> list[bytes]:
+        if not data:
+            return []
+        if self.buffer or data.startswith(b"\xfe"):
+            self.buffer.extend(data)
+            return self._drain()
+        return [data]
+
+    def _drain(self) -> list[bytes]:
+        responses: list[bytes] = []
+        while len(self.buffer) >= 5:
+            if not self.buffer.startswith(b"\xfe\xff\x0f"):
+                responses.append(bytes(self.buffer))
+                self.buffer.clear()
+                break
+            length = (self.buffer[3] << 8) | self.buffer[4]
+            total = 7 + length
+            if len(self.buffer) < total:
+                break
+            frame = bytes(self.buffer[:total])
+            del self.buffer[:total]
+            responses.append(frame)
+        return responses
+
+
+def standby_packet(handle: int = DEFAULT_COMMAND_HANDLE) -> bytes:
+    return build_command_packet(AvantiCommand.ENTER_STANDBY, handle=handle)
+
+
+def show_pin_packet() -> bytes:
+    return build_command_packet(AvantiCommand.SHOW_PIN)
+
+
+def read_status_packet(handle: int = DEFAULT_COMMAND_HANDLE) -> bytes:
+    return build_command_packet(AvantiCommand.READ_STATUS, handle=handle)
+
+
+def stop_brewing_packet(handle: int = DEFAULT_COMMAND_HANDLE) -> bytes:
+    return build_command_packet(AvantiCommand.STOP_BREWING, handle=handle)
+
+
+def brew_packet(recipe: AvantiRecipe, handle: int = DEFAULT_COMMAND_HANDLE) -> bytes:
+    return build_command_packet(AvantiCommand.BREW_PRODUCT, recipe.payload(), handle=handle)
+
+
+AVANTI_RECIPES: tuple[AvantiRecipe, ...] = (
+    Espresso(),
+    Coffee(),
+    AmericanCoffee(),
+    Cappuccino(),
+)
+
+_RECIPE_TYPES: dict[str, type[AvantiRecipe]] = {
+    recipe_type.__name__: recipe_type
+    for recipe_type in (Espresso, Coffee, AmericanCoffee, Cappuccino)
+}
+
+
+def parse_recipe_expression(expression: str) -> AvantiRecipe:
+    node = ast.parse(expression, mode="eval").body
+    if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Name):
+        raise ValueError("recipe must be a call like Espresso(coffee_ml=50)")
+    recipe_type = _RECIPE_TYPES.get(node.func.id)
+    if recipe_type is None:
+        choices = ", ".join(sorted(_RECIPE_TYPES))
+        raise ValueError(f"unknown recipe {node.func.id!r}; expected one of: {choices}")
+    if node.args:
+        raise ValueError(f"recipe expressions only support keyword arguments: {expression}")
+
+    kwargs: dict[str, Any] = {}
+    for keyword in node.keywords:
+        if keyword.arg is None:
+            raise ValueError(f"recipe expressions do not support **kwargs: {expression}")
+        value = ast.literal_eval(keyword.value)
+        if not isinstance(value, int):
+            raise ValueError(f"{keyword.arg} must be an integer")
+        kwargs[keyword.arg] = value
+
+    return recipe_type(**kwargs)
+
+
+def amount_ml_to_scalar(value: int, minimum: int, maximum: int, label: str = "amount") -> int:
+    if minimum == 0 and maximum == 0:
+        raise ValueError(f"{label} amount is not supported for this recipe")
+    if value < minimum or value > maximum:
+        raise ValueError(f"{label} amount must be between {minimum}ml and {maximum}ml")
+
+    span = maximum - minimum
+    if span <= 0:
+        return 0
+    value = round_to_step(value, 5)
+    return round(((value - minimum) / span) * 100)
+
+
+def round_to_step(value: int, step: int) -> int:
+    return ((value + step // 2) // step) * step
+
+
+def slugify(value: str) -> str:
+    return "".join(char.lower() if char.isalnum() else "_" for char in value).strip("_")
+
+
+def command_message(action: str, **data: object) -> str:
+    return json.dumps({"action": action, **data}, separators=(",", ":"))