pylamarzocco 1.2.3__tar.gz

pylamarzocco-1.2.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Josef
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pylamarzocco-1.2.3/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.1
+Name: pylamarzocco
+Version: 1.2.3
+Summary: A Python implementation of the new La Marzocco API
+Home-page: https://github.com/zweckj/pylamarzocco
+Author: Josef Zweck
+Author-email: 24647999+zweckj@users.noreply.github.com
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.16.1
+Requires-Dist: websockets>=11.0.2
+Requires-Dist: bleak>=0.20.2
+
+# La Marzocco Python Client
+
+This is a library to interface with La Marzocco's Home machines.
+It also has support to get information for the Pico grinder.
+
+![workflow](https://github.com/zweckj/pylamarzocco/actions/workflows/pypi.yaml/badge.svg)
+[![codecov](https://codecov.io/gh/zweckj/pylamarzocco/graph/badge.svg?token=350GPTLZXS)](https://codecov.io/gh/zweckj/pylamarzocco)
+
+# Libraries in this project
+
+- `LaMarzoccoLocalClient` calls the new local API the Micra exposes, using the Bearer token from the customer cloud endpoint. However, this API currently only supports getting the config, and some status objects (like shottimer) over websockets, but does not support setting anything (to my knowledge). Local settings appear to only happen through [Bluetooth connections](#lmbluetooth).
+- `LaMarzoccoCloudClient` interacts with `gw-lmz.lamarzocco.com` to send commands. pylamarzocco can be initialized to only issue remote commands, or to initialize an instance of `lmlocalapi` for getting the current machine settings. This helps to avoid flooding the cloud API and is faster overall.
+- `LaMarzoccoBluetoothClient` provides a bluetooth client to send settings to the machine via bluetooth
+
+# Setup
+
+## LaMarzoccoCloudClient
+
+You need `username` and `password`, which are the credentials you're using to sign into the La Marzocco Home app.
+
+It is initialized like this
+
+```python
+cloud_client = await LaMarzoccoCloudClient(username, password)
+```
+
+## LaMarzoccoLocalClient
+
+If you just want to run the local API you need the IP of your machine, the Port it is listening on (8081 by default), the Bearer token (`communicationKey`) used for local communication.
+You can obtain that key by inspecting a call to `https://cms.lamarzocco.io/api/customer`, while connected to `mitmproxy` (process above), or making a new (authenticated) call to that endpoint.
+
+Then you can init the class with
+
+```python
+local_client = LaMarzoccoLocalClient(ip, local_token)
+```
+
+## LaMarzoccoBluetoothClient
+
+Some commands, like turning the machine on and off are always sent through bluetooth whenever possible. The available bluetooth characteristics are described in [bluetooth_characteristics](docs/bluetooth_characteristics.md).
+The class `LaMarzoccoBluetoothClient` discovers any bluetooth devices connects to it. Then we can send local bluetooth commands.
+
+To use Bluetooth you can either init pylamarzocco with
+
+```python
+    if bluetooth_devices := LaMarzoccoBluetoothClient.discover_devices():
+        print("Found bluetooth device:", bluetooth_devices[0])
+
+    bluetooth_client = LaMarzoccoBluetoothClient(
+        username,
+        serial_number,
+        local_token
+        bluetooth_devices[0],
+    )
+```
+
+The local_token is the same token you need to initialize the local API, which you need to get from LM's cloud once. The serial number is your machine's serial number and the username is the email of your LaMarzocco account.
+
+## Machine
+
+Once you have any or all of the clients, you can initialize a machine object with
+
+```python
+machine = Machine.create(model, serial_number, name, cloud_client, local_client, bluetooth_client)
+```
+
+You can then use the machine object to send commands to the machine, or to get the current status of the machine. If you're running in cloud only mode, please be mindful with the requests to not flood the cloud API.
+
+## Grinder
+
+The Pico grinder can be initialized with
+
+```python
+grinder = LaMarzoccoGrinder.create(model, serial_number, name, cloud_client, local_client, bluetooth_client)
+```
+
+where you can use the same cloud client as for the machine, but you need to initialize new local and bluetooth clients (the same way as for the machine) to use the grinder.
+
+### Websockets
+
+The local API initiates a websocket connection to
+
+```
+http://{IP}:8081/api/v1/streaming
+```
+
+The packets which are received on that WebSocket are documented in [websockets](docs/websockets.md)
+
+If WebSockets are enabled the shot timer becomes available to use, however as long as the library is running in WebSocket mode, the App will no longer be able to connect.
+
+To use WebSockets start the integration with
+
+```python
+await machine.websocket_connect(callback)
+```
+
+with an optional callback function that will be called whenever there have been updates for the machine from the websocket.

pylamarzocco-1.2.3/README.md

@@ -0,0 +1,97 @@
+# La Marzocco Python Client
+
+This is a library to interface with La Marzocco's Home machines.
+It also has support to get information for the Pico grinder.
+
+![workflow](https://github.com/zweckj/pylamarzocco/actions/workflows/pypi.yaml/badge.svg)
+[![codecov](https://codecov.io/gh/zweckj/pylamarzocco/graph/badge.svg?token=350GPTLZXS)](https://codecov.io/gh/zweckj/pylamarzocco)
+
+# Libraries in this project
+
+- `LaMarzoccoLocalClient` calls the new local API the Micra exposes, using the Bearer token from the customer cloud endpoint. However, this API currently only supports getting the config, and some status objects (like shottimer) over websockets, but does not support setting anything (to my knowledge). Local settings appear to only happen through [Bluetooth connections](#lmbluetooth).
+- `LaMarzoccoCloudClient` interacts with `gw-lmz.lamarzocco.com` to send commands. pylamarzocco can be initialized to only issue remote commands, or to initialize an instance of `lmlocalapi` for getting the current machine settings. This helps to avoid flooding the cloud API and is faster overall.
+- `LaMarzoccoBluetoothClient` provides a bluetooth client to send settings to the machine via bluetooth
+
+# Setup
+
+## LaMarzoccoCloudClient
+
+You need `username` and `password`, which are the credentials you're using to sign into the La Marzocco Home app.
+
+It is initialized like this
+
+```python
+cloud_client = await LaMarzoccoCloudClient(username, password)
+```
+
+## LaMarzoccoLocalClient
+
+If you just want to run the local API you need the IP of your machine, the Port it is listening on (8081 by default), the Bearer token (`communicationKey`) used for local communication.
+You can obtain that key by inspecting a call to `https://cms.lamarzocco.io/api/customer`, while connected to `mitmproxy` (process above), or making a new (authenticated) call to that endpoint.
+
+Then you can init the class with
+
+```python
+local_client = LaMarzoccoLocalClient(ip, local_token)
+```
+
+## LaMarzoccoBluetoothClient
+
+Some commands, like turning the machine on and off are always sent through bluetooth whenever possible. The available bluetooth characteristics are described in [bluetooth_characteristics](docs/bluetooth_characteristics.md).
+The class `LaMarzoccoBluetoothClient` discovers any bluetooth devices connects to it. Then we can send local bluetooth commands.
+
+To use Bluetooth you can either init pylamarzocco with
+
+```python
+    if bluetooth_devices := LaMarzoccoBluetoothClient.discover_devices():
+        print("Found bluetooth device:", bluetooth_devices[0])
+
+    bluetooth_client = LaMarzoccoBluetoothClient(
+        username,
+        serial_number,
+        local_token
+        bluetooth_devices[0],
+    )
+```
+
+The local_token is the same token you need to initialize the local API, which you need to get from LM's cloud once. The serial number is your machine's serial number and the username is the email of your LaMarzocco account.
+
+## Machine
+
+Once you have any or all of the clients, you can initialize a machine object with
+
+```python
+machine = Machine.create(model, serial_number, name, cloud_client, local_client, bluetooth_client)
+```
+
+You can then use the machine object to send commands to the machine, or to get the current status of the machine. If you're running in cloud only mode, please be mindful with the requests to not flood the cloud API.
+
+## Grinder
+
+The Pico grinder can be initialized with
+
+```python
+grinder = LaMarzoccoGrinder.create(model, serial_number, name, cloud_client, local_client, bluetooth_client)
+```
+
+where you can use the same cloud client as for the machine, but you need to initialize new local and bluetooth clients (the same way as for the machine) to use the grinder.
+
+### Websockets
+
+The local API initiates a websocket connection to
+
+```
+http://{IP}:8081/api/v1/streaming
+```
+
+The packets which are received on that WebSocket are documented in [websockets](docs/websockets.md)
+
+If WebSockets are enabled the shot timer becomes available to use, however as long as the library is running in WebSocket mode, the App will no longer be able to connect.
+
+To use WebSockets start the integration with
+
+```python
+await machine.websocket_connect(callback)
+```
+
+with an optional callback function that will be called whenever there have been updates for the machine from the websocket.

pylamarzocco-1.2.3/pylamarzocco/__init__.py

@@ -0,0 +1,7 @@
+"""Import for ease of use."""
+
+from .client_local import LaMarzoccoLocalClient
+from .client_cloud import LaMarzoccoCloudClient
+from .client_bluetooth import LaMarzoccoBluetoothClient
+from .lm_machine import LaMarzoccoMachine
+from .lm_grinder import LaMarzoccoGrinder

pylamarzocco-1.2.3/pylamarzocco/client_bluetooth.py

@@ -0,0 +1,167 @@
+"""Bluetooth class for La Marzocco machines."""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from typing import Any
+
+from bleak import (
+    BaseBleakScanner,
+    BleakClient,
+    BleakError,
+    BleakScanner,
+    BLEDevice,
+)
+
+from .const import (
+    AUTH_CHARACTERISTIC,
+    BT_MODEL_PREFIXES,
+    SETTINGS_CHARACTERISTIC,
+    BoilerType,
+)
+from .exceptions import (
+    BluetoothConnectionFailed,
+)
+
+_logger = logging.getLogger(__name__)
+
+
+class LaMarzoccoBluetoothClient:
+    """Class to interact with machine via Bluetooth."""
+
+    def __init__(
+        self,
+        username: str,
+        serial_number: str,
+        token: str,
+        address_or_ble_device: BLEDevice | str,
+    ) -> None:
+        """Initializes a new LaMarzoccoBluetoothClient instance."""
+        self._username = username
+        self._serial_number = serial_number
+        self._token = token
+        self._address = (
+            address_or_ble_device.address
+            if isinstance(address_or_ble_device, BLEDevice)
+            else address_or_ble_device
+        )
+        self._address_or_ble_device = address_or_ble_device
+        self._client = BleakClient(address_or_ble_device)
+
+    @staticmethod
+    async def discover_devices(
+        scanner: BaseBleakScanner | BleakScanner | None = None,
+    ) -> list[BLEDevice]:
+        """Find machines based on model name."""
+        ble_devices: list[BLEDevice] = []
+
+        if scanner is None:
+            scanner = BleakScanner()
+        assert hasattr(scanner, "discover")
+        devices: list[BLEDevice] = await scanner.discover()
+        for device in devices:
+            if device.name and device.name.startswith(BT_MODEL_PREFIXES):
+                ble_devices.append(device)
+
+        return ble_devices
+
+    @property
+    def address(self) -> str:
+        """Return the BT MAC address of the machine."""
+
+        return self._address
+
+    @property
+    def connected(self) -> bool:
+        """Return the connection status."""
+
+        return self._client.is_connected
+
+    async def set_power(self, enabled: bool) -> None:
+        """Power on the machine."""
+
+        mode = "BrewingMode" if enabled else "StandBy"
+        data = {
+            "name": "MachineChangeMode",
+            "parameter": {
+                "mode": mode,
+            },
+        }
+        await self._write_bluetooth_json_message(data)
+
+    async def set_steam(self, enabled: bool) -> None:
+        """Power cycle steam."""
+
+        data = {
+            "name": "SettingBoilerEnable",
+            "parameter": {
+                "identifier": "SteamBoiler",
+                "state": enabled,
+            },
+        }
+        await self._write_bluetooth_json_message(data)
+
+    async def set_temp(self, boiler: BoilerType, temperature: float) -> None:
+        """Set boiler temperature (in Celsius)"""
+
+        data = {
+            "name": "SettingBoilerTarget",
+            "parameter": {
+                "identifier": boiler.value,
+                "value": temperature,
+            },
+        }
+        await self._write_bluetooth_json_message(data)
+
+    async def _write_bluetooth_message(
+        self, characteristic: str, message: bytes | str
+    ) -> None:
+        """Connect to machine and write a message."""
+
+        if not self._client.is_connected:
+            try:
+                self._client = BleakClient(self._address_or_ble_device)
+                await self._client.connect()
+                await self._authenticate()
+            except (BleakError, TimeoutError) as e:
+                raise BluetoothConnectionFailed(
+                    f"Failed to connect to machine with Bluetooth: {e}"
+                ) from e
+
+        # check if message is already bytes string
+        if not isinstance(message, bytes):
+            message = bytes(message, "utf-8")
+
+        # append trailing zeros to settings message
+        if characteristic == SETTINGS_CHARACTERISTIC:
+            message += b"\x00"
+
+        _logger.debug("Sending bluetooth message: %s to %s", message, characteristic)
+
+        await self._client.write_gatt_char(characteristic, message)
+
+    async def _write_bluetooth_json_message(
+        self,
+        data: dict[str, Any],
+        characteristic: str = SETTINGS_CHARACTERISTIC,
+    ) -> None:
+        """Write a json message to the machine."""
+
+        await self._write_bluetooth_message(
+            characteristic=characteristic,
+            message=json.dumps(data, separators=(",", ":")),
+        )
+
+    async def _authenticate(self) -> None:
+        """Build authentication string and send it to the machine."""
+
+        user = self._username + ":" + self._serial_number
+        user_bytes = user.encode("utf-8")
+        token = self._token.encode("utf-8")
+        auth_string = base64.b64encode(user_bytes) + b"@" + base64.b64encode(token)
+        await self._write_bluetooth_message(
+            characteristic=AUTH_CHARACTERISTIC,
+            message=auth_string,
+        )