desky-ble 0.1.2__tar.gz

desky_ble-0.1.2/.gitignore

@@ -0,0 +1,10 @@
+decompiled
+extracted
+*.xapk
+.venv
+.ruff_cache
+.pytest_cache
+*pycache*
+examples
+tests
+.github

desky_ble-0.1.2/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: desky-ble
+Version: 0.1.2
+Summary: Unofficial Python library for local Bluetooth LE control of Desky® Standing Desks.
+Project-URL: Homepage, https://github.com/vakintosh/ha-desky-ble
+Project-URL: Bug-Tracker, https://github.com/vakintosh/ha-desky-ble/issues
+Author: vakintosh
+License: MIT
+Keywords: ble,bluetooth,desky,home-assistant,iot,standing-desk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.13
+Requires-Dist: bleak-retry-connector>=4.5.0
+Requires-Dist: bleak>=2.1.1
+Description-Content-Type: text/markdown
+
+# desky-ble
+
+Unofficial Python library for local Bluetooth LE control of Desky® Standing Desks.
+
+This standalone client library provides a robust, asynchronous interface for interacting with Desky desk controllers. It handles all low-level BLE communication, including real-time height monitoring, preset management, and automatic detection of common controller variants (specifically those utilizing Lierda and Peilin chipsets).
+
+Designed for interoperability, this library is built to integrate seamlessly with platforms like Home Assistant, enabling local, cloud-free automation of your workspace.
+
+## Supported controllers
+
+| Variant  | BLE Service UUID                         |
+|----------|------------------------------------------|
+| Lierda 1 | `0000ff12-0000-1000-8000-00805f9b34fb`   |
+| Lierda 2 | `0000fe60-0000-1000-8000-00805f9b34fb`   |
+| Peilin   | `88121427-11e2-52a2-4615-ff00dec16800`   |
+
+## Installation
+
+```bash
+pip install desky-ble
+```
+
+Requires Python 3.13+.
+
+## Quick start
+
+```python
+import asyncio
+from bleak import BleakScanner
+from desky_ble import DeskyBleClient, DeskState
+
+async def main():
+    device = await BleakScanner.find_device_by_name("Desky")
+
+    def on_state(state: DeskState):
+        print(f"Height: {state.height_cm} cm, Moving: {state.is_moving}")
+
+    client = DeskyBleClient(device, state_callback=on_state)
+    await client.connect()
+    await client.request_status()
+    await client.move_up()
+    await asyncio.sleep(2)
+    await client.stop()
+    await client.disconnect()
+
+asyncio.run(main())
+```
+
+## Features
+
+### Motion control
+
+- `move_up()` / `move_down()` — continuous movement
+- `stop()` — stop any movement
+- `move_to_height(raw)` — move to a specific height (raw value = cm × 10)
+
+### Memory presets
+
+- `recall_memory(slot)` — recall a saved preset (slots 1–4)
+- `save_memory(slot)` — save current height to a preset
+
+### Desk settings
+
+- `set_brightness(value)` — LED display brightness (0–100)
+- `set_led_color(value)` — LED colour (1–7)
+- `set_lighting(value)` — under-desk lighting (0=off, 1=on)
+- `set_vibration(value)` — vibration feedback (0=off, 1=on)
+- `set_lock(value)` — child lock (0=off, 1=on)
+- `set_anti_collision(value)` — anti-collision sensitivity (1–3)
+- `set_touch_mode(value)` — touch mode (0=one-press, 1=hold)
+- `set_unit(value)` — display unit
+- `set_reminder(minutes)` — sit/stand reminder interval
+- `clear_limits()` — clear upper/lower height limits
+
+### State tracking
+
+The `DeskState` object is updated in real-time via BLE notifications:
+
+```python
+state = client.state
+state.height_cm       # Current height in cm
+state.height_raw      # Raw height value
+state.is_moving       # Whether the desk is moving
+state.lock_status     # Child lock (0=off, 1=on)
+state.brightness      # Display brightness (0-100)
+state.led_color       # LED colour (1-7)
+state.vibration       # Vibration feedback (0=off, 1=on)
+state.lighting        # Under-desk lighting (0=off, 1=on)
+state.anti_collision  # Anti-collision sensitivity (1-3)
+state.has_limits      # Whether height limits are set
+```
+
+### Settings persistence
+
+After reconnect, call `restore_settings()` to re-apply any settings that the desk may have reset.
+
+## License
+
+MIT

desky_ble-0.1.2/README.md

@@ -0,0 +1,99 @@
+# desky-ble
+
+Unofficial Python library for local Bluetooth LE control of Desky® Standing Desks.
+
+This standalone client library provides a robust, asynchronous interface for interacting with Desky desk controllers. It handles all low-level BLE communication, including real-time height monitoring, preset management, and automatic detection of common controller variants (specifically those utilizing Lierda and Peilin chipsets).
+
+Designed for interoperability, this library is built to integrate seamlessly with platforms like Home Assistant, enabling local, cloud-free automation of your workspace.
+
+## Supported controllers
+
+| Variant  | BLE Service UUID                         |
+|----------|------------------------------------------|
+| Lierda 1 | `0000ff12-0000-1000-8000-00805f9b34fb`   |
+| Lierda 2 | `0000fe60-0000-1000-8000-00805f9b34fb`   |
+| Peilin   | `88121427-11e2-52a2-4615-ff00dec16800`   |
+
+## Installation
+
+```bash
+pip install desky-ble
+```
+
+Requires Python 3.13+.
+
+## Quick start
+
+```python
+import asyncio
+from bleak import BleakScanner
+from desky_ble import DeskyBleClient, DeskState
+
+async def main():
+    device = await BleakScanner.find_device_by_name("Desky")
+
+    def on_state(state: DeskState):
+        print(f"Height: {state.height_cm} cm, Moving: {state.is_moving}")
+
+    client = DeskyBleClient(device, state_callback=on_state)
+    await client.connect()
+    await client.request_status()
+    await client.move_up()
+    await asyncio.sleep(2)
+    await client.stop()
+    await client.disconnect()
+
+asyncio.run(main())
+```
+
+## Features
+
+### Motion control
+
+- `move_up()` / `move_down()` — continuous movement
+- `stop()` — stop any movement
+- `move_to_height(raw)` — move to a specific height (raw value = cm × 10)
+
+### Memory presets
+
+- `recall_memory(slot)` — recall a saved preset (slots 1–4)
+- `save_memory(slot)` — save current height to a preset
+
+### Desk settings
+
+- `set_brightness(value)` — LED display brightness (0–100)
+- `set_led_color(value)` — LED colour (1–7)
+- `set_lighting(value)` — under-desk lighting (0=off, 1=on)
+- `set_vibration(value)` — vibration feedback (0=off, 1=on)
+- `set_lock(value)` — child lock (0=off, 1=on)
+- `set_anti_collision(value)` — anti-collision sensitivity (1–3)
+- `set_touch_mode(value)` — touch mode (0=one-press, 1=hold)
+- `set_unit(value)` — display unit
+- `set_reminder(minutes)` — sit/stand reminder interval
+- `clear_limits()` — clear upper/lower height limits
+
+### State tracking
+
+The `DeskState` object is updated in real-time via BLE notifications:
+
+```python
+state = client.state
+state.height_cm       # Current height in cm
+state.height_raw      # Raw height value
+state.is_moving       # Whether the desk is moving
+state.lock_status     # Child lock (0=off, 1=on)
+state.brightness      # Display brightness (0-100)
+state.led_color       # LED colour (1-7)
+state.vibration       # Vibration feedback (0=off, 1=on)
+state.lighting        # Under-desk lighting (0=off, 1=on)
+state.anti_collision  # Anti-collision sensitivity (1-3)
+state.has_limits      # Whether height limits are set
+```
+
+### Settings persistence
+
+After reconnect, call `restore_settings()` to re-apply any settings that the desk may have reset.
+
+## License
+
+MIT

desky_ble-0.1.2/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "desky-ble"
+version = "0.1.2"
+description = "Unofficial Python library for local Bluetooth LE control of Desky® Standing Desks."
+readme = "README.md"
+requires-python = ">=3.13"
+license = {text = "MIT"}
+authors = [
+    {name = "vakintosh"}
+]
+keywords = ["home-assistant", "bluetooth", "ble", "desky", "standing-desk", "iot"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+]
+dependencies = [
+    "bleak>=2.1.1",
+    "bleak-retry-connector>=4.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/vakintosh/ha-desky-ble"
+Bug-Tracker = "https://github.com/vakintosh/ha-desky-ble/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/desky_ble"]

desky_ble-0.1.2/src/desky_ble/__init__.py

@@ -0,0 +1,90 @@
+"""desky-ble – standalone BLE protocol and client library for Desky standing desks."""
+
+from __future__ import annotations
+
+from .ble_client import ControllerVariant, DeskyBleClient
+from .protocol import (
+    CMD_CLEAR_LIMIT,
+    CMD_GET_ANTI_COLLISION,
+    CMD_GET_BRIGHTNESS,
+    CMD_GET_CURRENT_LIMITATION,
+    CMD_GET_LED_COLOR,
+    CMD_GET_LIGHTING,
+    CMD_GET_LOCK,
+    CMD_GET_STATUS,
+    CMD_GET_VIBRATION,
+    CMD_HANDSHAKE,
+    CMD_MOVE_DOWN,
+    CMD_MOVE_UP,
+    CMD_RECALL_MEMORY_1,
+    CMD_RECALL_MEMORY_2,
+    CMD_RECALL_MEMORY_3,
+    CMD_RECALL_MEMORY_4,
+    CMD_SAVE_MEMORY_1,
+    CMD_SAVE_MEMORY_2,
+    CMD_SAVE_MEMORY_3,
+    CMD_SAVE_MEMORY_4,
+    CMD_STOP,
+    DeskState,
+    Opcode,
+    build_frame,
+    cmd_move_to_height,
+    cmd_set_anti_collision,
+    cmd_set_brightness,
+    cmd_set_led_color,
+    cmd_set_lighting,
+    cmd_set_lock,
+    cmd_set_reminder,
+    cmd_set_touch_mode,
+    cmd_set_unit,
+    cmd_set_value,
+    cmd_set_vibration,
+    height_cm_to_raw,
+    height_is_cm,
+    height_raw_to_cm,
+    parse_notification,
+)
+
+__all__ = [
+    "CMD_CLEAR_LIMIT",
+    "CMD_GET_ANTI_COLLISION",
+    "CMD_GET_BRIGHTNESS",
+    "CMD_GET_CURRENT_LIMITATION",
+    "CMD_GET_LED_COLOR",
+    "CMD_GET_LIGHTING",
+    "CMD_GET_LOCK",
+    "CMD_GET_STATUS",
+    "CMD_GET_VIBRATION",
+    "CMD_HANDSHAKE",
+    "CMD_MOVE_DOWN",
+    "CMD_MOVE_UP",
+    "CMD_RECALL_MEMORY_1",
+    "CMD_RECALL_MEMORY_2",
+    "CMD_RECALL_MEMORY_3",
+    "CMD_RECALL_MEMORY_4",
+    "CMD_SAVE_MEMORY_1",
+    "CMD_SAVE_MEMORY_2",
+    "CMD_SAVE_MEMORY_3",
+    "CMD_SAVE_MEMORY_4",
+    "CMD_STOP",
+    "ControllerVariant",
+    "DeskState",
+    "DeskyBleClient",
+    "Opcode",
+    "build_frame",
+    "cmd_move_to_height",
+    "cmd_set_anti_collision",
+    "cmd_set_brightness",
+    "cmd_set_led_color",
+    "cmd_set_lighting",
+    "cmd_set_lock",
+    "cmd_set_reminder",
+    "cmd_set_touch_mode",
+    "cmd_set_unit",
+    "cmd_set_value",
+    "cmd_set_vibration",
+    "height_cm_to_raw",
+    "height_is_cm",
+    "height_raw_to_cm",
+    "parse_notification",
+]

desky_ble-0.1.2/src/desky_ble/ble_client.py

@@ -0,0 +1,363 @@
+"""BLE client for Desky standing desks.
+
+Standalone version without Home Assistant dependencies.
+BLE UUIDs and constants are defined locally.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable
+from enum import Enum, auto
+
+from bleak import BleakClient
+from bleak.backends.characteristic import BleakGATTCharacteristic
+from bleak.backends.device import BLEDevice
+from bleak_retry_connector import establish_connection
+
+from .protocol import (
+    CMD_CLEAR_LIMIT,
+    CMD_GET_ANTI_COLLISION,
+    CMD_GET_BRIGHTNESS,
+    CMD_GET_LED_COLOR,
+    CMD_GET_LIGHTING,
+    CMD_GET_LOCK,
+    CMD_GET_STATUS,
+    CMD_GET_VIBRATION,
+    CMD_HANDSHAKE,
+    CMD_MOVE_DOWN,
+    CMD_MOVE_UP,
+    CMD_RECALL_MEMORY_1,
+    CMD_RECALL_MEMORY_2,
+    CMD_RECALL_MEMORY_3,
+    CMD_RECALL_MEMORY_4,
+    CMD_SAVE_MEMORY_1,
+    CMD_SAVE_MEMORY_2,
+    CMD_SAVE_MEMORY_3,
+    CMD_SAVE_MEMORY_4,
+    CMD_STOP,
+    DeskState,
+    cmd_move_to_height,
+    cmd_set_anti_collision,
+    cmd_set_brightness,
+    cmd_set_led_color,
+    cmd_set_lighting,
+    cmd_set_lock,
+    cmd_set_reminder,
+    cmd_set_touch_mode,
+    cmd_set_unit,
+    cmd_set_vibration,
+    parse_notification,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+UUID_SERVICE_LIERDA1 = "0000ff12-0000-1000-8000-00805f9b34fb"
+UUID_CHAR_WRITE_LIERDA1 = "0000ff01-0000-1000-8000-00805f9b34fb"
+UUID_CHAR_READ_LIERDA1 = "0000ff02-0000-1000-8000-00805f9b34fb"
+
+UUID_SERVICE_LIERDA2 = "0000fe60-0000-1000-8000-00805f9b34fb"
+UUID_CHAR_WRITE_LIERDA2 = "0000fe61-0000-1000-8000-00805f9b34fb"
+UUID_CHAR_READ_LIERDA2 = "0000fe62-0000-1000-8000-00805f9b34fb"
+
+UUID_SERVICE_PEILIN = "88121427-11e2-52a2-4615-ff00dec16800"
+UUID_CHAR_RW_PEILIN = "88121427-11e2-52a2-4615-ff00dec16801"
+
+UUID_SERVICE_LOGIN = "9e5d1e47-5c13-43a0-8635-82adffc0386f"
+UUID_CHAR_LOGIN_WRITE = "9e5d1e47-5c13-43a0-8635-82adffc1386f"
+
+LOGIN_PAYLOAD = bytes([0x01, 0x16, 0x02, 0x38, 0x38, 0x38, 0x38])
+
+ALL_SERVICE_UUIDS: list[str] = [
+    UUID_SERVICE_LIERDA1,
+    UUID_SERVICE_LIERDA2,
+    UUID_SERVICE_PEILIN,
+]
+
+_RECALL_MEMORY_CMDS: dict[int, bytes] = {
+    1: CMD_RECALL_MEMORY_1,
+    2: CMD_RECALL_MEMORY_2,
+    3: CMD_RECALL_MEMORY_3,
+    4: CMD_RECALL_MEMORY_4,
+}
+
+_SAVE_MEMORY_CMDS: dict[int, bytes] = {
+    1: CMD_SAVE_MEMORY_1,
+    2: CMD_SAVE_MEMORY_2,
+    3: CMD_SAVE_MEMORY_3,
+    4: CMD_SAVE_MEMORY_4,
+}
+
+
+class ControllerVariant(Enum):
+    """BLE controller type detected from GATT services."""
+
+    LIERDA1 = auto()
+    LIERDA2 = auto()
+    PEILIN = auto()
+
+
+class DeskyBleClient:
+    """Async BLE client for Desky standing desks."""
+
+    __slots__ = (
+        "_ble_device",
+        "_client",
+        "_variant",
+        "_write_char",
+        "_read_char",
+        "_state",
+        "_state_callback",
+        "_lock",
+        "_desired_settings",
+    )
+
+    def __init__(
+        self,
+        ble_device: BLEDevice,
+        state_callback: Callable[[DeskState], None] | None = None,
+    ) -> None:
+        self._ble_device = ble_device
+        self._client: BleakClient | None = None
+        self._variant: ControllerVariant | None = None
+        self._write_char: str | None = None
+        self._read_char: str | None = None
+        self._state = DeskState()
+        self._state_callback = state_callback
+        self._lock = asyncio.Lock()
+        self._desired_settings: dict[str, tuple[int, bytes]] = {}
+
+    @property
+    def state(self) -> DeskState:
+        return self._state
+
+    @property
+    def variant(self) -> ControllerVariant | None:
+        return self._variant
+
+    @property
+    def is_connected(self) -> bool:
+        return self._client is not None and self._client.is_connected
+
+    async def connect(self) -> None:
+        """Establish BLE connection with retry logic."""
+        self._client = await establish_connection(
+            BleakClient,
+            self._ble_device,
+            self._ble_device.address,
+        )
+        await self._detect_variant()
+        await self._setup_notifications()
+        await self._send(CMD_HANDSHAKE)
+        _LOGGER.debug(
+            "Connected to Desky %s (variant=%s)",
+            self._ble_device.address,
+            self._variant,
+        )
+
+    async def disconnect(self) -> None:
+        if self._client and self._client.is_connected:
+            await self._client.disconnect()
+        self._client = None
+
+    async def _detect_variant(self) -> None:
+        """Identify the controller variant from advertised GATT services."""
+        if self._client is None:
+            msg = "Not connected"
+            raise RuntimeError(msg)
+
+        service_uuids = {str(s.uuid).lower() for s in self._client.services}
+
+        if UUID_SERVICE_LIERDA2.lower() in service_uuids:
+            self._variant = ControllerVariant.LIERDA2
+            self._write_char = UUID_CHAR_WRITE_LIERDA2
+            self._read_char = UUID_CHAR_READ_LIERDA2
+        elif UUID_SERVICE_LIERDA1.lower() in service_uuids:
+            self._variant = ControllerVariant.LIERDA1
+            self._write_char = UUID_CHAR_WRITE_LIERDA1
+            self._read_char = UUID_CHAR_READ_LIERDA1
+        elif UUID_SERVICE_PEILIN.lower() in service_uuids:
+            self._variant = ControllerVariant.PEILIN
+            self._write_char = UUID_CHAR_RW_PEILIN
+            self._read_char = UUID_CHAR_RW_PEILIN
+        else:
+            msg = (
+                f"No known Desky service found on {self._ble_device.address}. "
+                f"Services: {service_uuids}"
+            )
+            raise RuntimeError(msg)
+
+        if self._variant == ControllerVariant.PEILIN:
+            await self._peilin_login(service_uuids)
+
+    async def _peilin_login(self, service_uuids: set[str]) -> None:
+        """Send the login payload required by Peilin controllers."""
+        if UUID_SERVICE_LOGIN.lower() not in service_uuids:
+            _LOGGER.debug("No login service found; skipping Peilin login")
+            return
+        if self._client is None:
+            return
+        try:
+            await self._client.write_gatt_char(
+                UUID_CHAR_LOGIN_WRITE, LOGIN_PAYLOAD, response=True
+            )
+            _LOGGER.debug("Peilin login handshake sent")
+        except Exception:
+            _LOGGER.warning("Failed to send Peilin login handshake", exc_info=True)
+
+    async def _setup_notifications(self) -> None:
+        if self._client is None or self._read_char is None:
+            return
+        await self._client.start_notify(self._read_char, self._on_notification)
+
+    def _on_notification(
+        self,
+        _characteristic: BleakGATTCharacteristic,
+        data: bytearray,
+    ) -> None:
+        if parse_notification(data, self._state) and self._state_callback:
+            self._state_callback(self._state)
+
+    async def _send(self, frame: bytes) -> None:
+        async with self._lock:
+            if self._client is None or self._write_char is None:
+                msg = "Not connected"
+                raise RuntimeError(msg)
+            await self._client.write_gatt_char(self._write_char, frame, response=False)
+            _LOGGER.debug("TX → %s", frame.hex())
+
+    async def _send_setting(self, frame: bytes) -> None:
+        """Send a settings command using the APK's reliability pattern."""
+        async with self._lock:
+            if self._client is None or self._write_char is None:
+                msg = "Not connected"
+                raise RuntimeError(msg)
+            await self._client.write_gatt_char(
+                self._write_char, CMD_HANDSHAKE, response=False
+            )
+            _LOGGER.debug("TX (handshake) → %s", CMD_HANDSHAKE.hex())
+            await asyncio.sleep(0.15)
+            await self._client.write_gatt_char(self._write_char, frame, response=True)
+            _LOGGER.debug("TX (setting #1) → %s", frame.hex())
+            await asyncio.sleep(0.20)
+            await self._client.write_gatt_char(self._write_char, frame, response=True)
+            _LOGGER.debug("TX (setting #2) → %s", frame.hex())
+
+    async def _send_preset(self, frame: bytes) -> None:
+        """Send a memory-preset command using the APK's reliability pattern."""
+        await self._send_setting(frame)
+
+    async def move_up(self) -> None:
+        await self._send(CMD_MOVE_UP)
+
+    async def move_down(self) -> None:
+        await self._send(CMD_MOVE_DOWN)
+
+    async def stop(self) -> None:
+        await self._send(CMD_STOP)
+
+    async def move_to_height(self, raw_height: int) -> None:
+        """Move to a specific height (*raw_height* = cm × 10)."""
+        await self._send(CMD_STOP)
+        await asyncio.sleep(0.2)
+        frame = cmd_move_to_height(raw_height)
+        await self._send(frame)
+
+    async def recall_memory(self, slot: int) -> None:
+        """Recall a memory preset (slot 1–4)."""
+        frame = _RECALL_MEMORY_CMDS.get(slot)
+        if frame is None:
+            msg = f"Invalid memory slot {slot}"
+            raise ValueError(msg)
+        await self._send_preset(frame)
+
+    async def save_memory(self, slot: int) -> None:
+        """Save current height to a memory slot (1–4)."""
+        frame = _SAVE_MEMORY_CMDS.get(slot)
+        if frame is None:
+            msg = f"Invalid memory slot {slot}"
+            raise ValueError(msg)
+        await self._send_preset(frame)
+
+    async def request_status(self) -> None:
+        await self._send(CMD_GET_STATUS)
+
+    async def request_all_settings(self) -> None:
+        """Query every known setting from the desk."""
+        for frame in (
+            CMD_GET_ANTI_COLLISION,
+            CMD_GET_LOCK,
+            CMD_GET_VIBRATION,
+            CMD_GET_LED_COLOR,
+            CMD_GET_LIGHTING,
+            CMD_GET_BRIGHTNESS,
+        ):
+            await self._send(frame)
+            await asyncio.sleep(0.1)
+
+    def _remember(self, key: str, value: int, frame: bytes) -> None:
+        """Record the user's intended value for a setting."""
+        self._desired_settings[key] = (value, frame)
+
+    async def set_brightness(self, value: int) -> None:
+        frame = cmd_set_brightness(value)
+        self._remember("brightness", value, frame)
+        await self._send_setting(frame)
+
+    async def set_led_color(self, value: int) -> None:
+        frame = cmd_set_led_color(value)
+        self._remember("led_color", value, frame)
+        await self._send_setting(frame)
+
+    async def set_vibration(self, value: int) -> None:
+        frame = cmd_set_vibration(value)
+        self._remember("vibration", value, frame)
+        await self._send_setting(frame)
+
+    async def set_lock(self, value: int) -> None:
+        frame = cmd_set_lock(value)
+        self._remember("lock_status", value, frame)
+        await self._send_setting(frame)
+
+    async def set_lighting(self, value: int) -> None:
+        frame = cmd_set_lighting(value)
+        self._remember("lighting", value, frame)
+        await self._send_setting(frame)
+
+    async def set_anti_collision(self, value: int) -> None:
+        frame = cmd_set_anti_collision(value)
+        self._remember("anti_collision", value, frame)
+        await self._send_setting(frame)
+
+    async def set_touch_mode(self, value: int) -> None:
+        frame = cmd_set_touch_mode(value)
+        self._remember("touch_mode", value, frame)
+        await self._send_setting(frame)
+
+    async def set_unit(self, value: int) -> None:
+        await self._send_setting(cmd_set_unit(value))
+
+    async def set_reminder(self, minutes: int) -> None:
+        await self._send_setting(cmd_set_reminder(minutes))
+
+    async def restore_settings(self) -> None:
+        """Re-apply any user-set settings that the desk reported differently
+        after a reconnect."""
+        if not self._desired_settings:
+            return
+
+        for key, (desired, frame) in self._desired_settings.items():
+            current = getattr(self._state, key, None)
+            if current != desired:
+                _LOGGER.debug(
+                    "Restoring setting '%s': desk=%s → desired=%s",
+                    key,
+                    current,
+                    desired,
+                )
+                await self._send_setting(frame)
+                await asyncio.sleep(0.1)
+
+    async def clear_limits(self) -> None:
+        await self._send(CMD_CLEAR_LIMIT)

desky_ble-0.1.2/src/desky_ble/protocol.py

@@ -0,0 +1,269 @@
+"""BLE protocol encoder/decoder for Desky standing desks.
+
+This module is a standalone copy of the protocol layer, usable without
+Home Assistant.  It is re-exported by the ``desky_ble`` PyPI package.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+import logging
+
+_LOGGER = logging.getLogger(__name__)
+
+HEADER_TX = bytes([0xF1, 0xF1])
+HEADER_RX = bytes([0xF2, 0xF2])
+FOOTER_TX = 0x7E
+
+
+class Opcode(enum.IntEnum):
+    """Command opcodes extracted from the Desky APK."""
+
+    MOVE_UP = 0x01
+    MOVE_DOWN = 0x02
+    SAVE_MEMORY_1 = 0x03
+    SAVE_MEMORY_2 = 0x04
+    RECALL_MEMORY_1 = 0x05
+    RECALL_MEMORY_2 = 0x06
+    GET_STATUS = 0x07
+    GET_LIMIT = 0x0C
+    SET_UNIT = 0x0E
+    SET_TOUCH_MODE = 0x19
+    MOVE_TO_HEIGHT = 0x1B
+    SET_ANTI_COLLISION = 0x1D
+    SET_HIGHEST_LIMIT = 0x21
+    SET_LOWEST_LIMIT = 0x22
+    CLEAR_LIMIT = 0x23
+    SAVE_MEMORY_3 = 0x25
+    SAVE_MEMORY_4 = 0x26
+    RECALL_MEMORY_3 = 0x27
+    RECALL_MEMORY_4 = 0x28
+    STOP = 0x2B
+    SET_REMINDER = 0xB1
+    SET_LOCK = 0xB2
+    SET_VIBRATION = 0xB3
+    SET_LED_COLOR = 0xB4
+    SET_LIGHTING = 0xB5
+    SET_BRIGHTNESS = 0xB6
+    HANDSHAKE = 0xFE
+
+
+_DUAL_OPCODES = {
+    Opcode.SET_ANTI_COLLISION,
+    Opcode.SET_LOCK,
+    Opcode.SET_VIBRATION,
+    Opcode.SET_LED_COLOR,
+    Opcode.SET_LIGHTING,
+    Opcode.SET_BRIGHTNESS,
+}
+
+
+def _checksum(cmd: int, length: int, data: bytes) -> int:
+    """Compute the additive checksum over cmd + length + data."""
+    return (cmd + length + sum(data)) & 0xFF
+
+
+def height_cm_to_raw(height_cm: float) -> int:
+    """Convert a height in *cm* to the raw protocol value (× 10)."""
+    return int(round(height_cm * 10))
+
+
+def height_raw_to_cm(raw: int) -> float:
+    """Convert raw protocol value back to cm."""
+    return raw / 10.0
+
+
+def height_is_cm(raw: int) -> bool:
+    """Return True if the raw value represents centimetres (≥ 550)."""
+    return raw >= 550
+
+
+def build_frame(opcode: int, data: bytes = b"") -> bytes:
+    """Build a complete TX frame ready to write to the BLE characteristic.
+
+    Returns
+    -------
+    bytes
+        ``[0xF1, 0xF1, CMD, LEN, *DATA, CHECKSUM, 0x7E]``
+    """
+    length = len(data)
+    cs = _checksum(opcode, length, data)
+    return HEADER_TX + bytes([opcode, length]) + data + bytes([cs, FOOTER_TX])
+
+
+CMD_MOVE_UP = build_frame(Opcode.MOVE_UP)
+CMD_MOVE_DOWN = build_frame(Opcode.MOVE_DOWN)
+CMD_STOP = build_frame(Opcode.STOP)
+CMD_RECALL_MEMORY_1 = build_frame(Opcode.RECALL_MEMORY_1)
+CMD_RECALL_MEMORY_2 = build_frame(Opcode.RECALL_MEMORY_2)
+CMD_RECALL_MEMORY_3 = build_frame(Opcode.RECALL_MEMORY_3)
+CMD_RECALL_MEMORY_4 = build_frame(Opcode.RECALL_MEMORY_4)
+CMD_SAVE_MEMORY_1 = build_frame(Opcode.SAVE_MEMORY_1)
+CMD_SAVE_MEMORY_2 = build_frame(Opcode.SAVE_MEMORY_2)
+CMD_SAVE_MEMORY_3 = build_frame(Opcode.SAVE_MEMORY_3)
+CMD_SAVE_MEMORY_4 = build_frame(Opcode.SAVE_MEMORY_4)
+CMD_GET_STATUS = build_frame(Opcode.GET_STATUS)
+CMD_GET_LIMIT = build_frame(Opcode.GET_LIMIT)
+CMD_CLEAR_LIMIT = build_frame(Opcode.CLEAR_LIMIT)
+CMD_HANDSHAKE = build_frame(Opcode.HANDSHAKE)
+
+CMD_GET_ANTI_COLLISION = build_frame(Opcode.SET_ANTI_COLLISION)
+CMD_GET_LOCK = build_frame(Opcode.SET_LOCK)
+CMD_GET_VIBRATION = build_frame(Opcode.SET_VIBRATION)
+CMD_GET_LED_COLOR = build_frame(Opcode.SET_LED_COLOR)
+CMD_GET_LIGHTING = build_frame(Opcode.SET_LIGHTING)
+CMD_GET_BRIGHTNESS = build_frame(Opcode.SET_BRIGHTNESS)
+CMD_GET_CURRENT_LIMITATION = build_frame(0x20)
+
+
+def cmd_move_to_height(raw_height: int) -> bytes:
+    """Build a move-to-height command (raw = cm × 10)."""
+    data = bytes([(raw_height >> 8) & 0xFF, raw_height & 0xFF])
+    return build_frame(Opcode.MOVE_TO_HEIGHT, data)
+
+
+def cmd_set_highest_limit(raw_height: int) -> bytes:
+    data = bytes([(raw_height >> 8) & 0xFF, raw_height & 0xFF])
+    return build_frame(Opcode.SET_HIGHEST_LIMIT, data)
+
+
+def cmd_set_lowest_limit(raw_height: int) -> bytes:
+    data = bytes([(raw_height >> 8) & 0xFF, raw_height & 0xFF])
+    return build_frame(Opcode.SET_LOWEST_LIMIT, data)
+
+
+def cmd_set_value(opcode: int, value: int) -> bytes:
+    """Build a single-byte-value set command."""
+    return build_frame(opcode, bytes([value & 0xFF]))
+
+
+def cmd_set_touch_mode(value: int) -> bytes:
+    return cmd_set_value(Opcode.SET_TOUCH_MODE, value)
+
+
+def cmd_set_unit(value: int) -> bytes:
+    return cmd_set_value(Opcode.SET_UNIT, value)
+
+
+def cmd_set_brightness(value: int) -> bytes:
+    return cmd_set_value(Opcode.SET_BRIGHTNESS, value)
+
+
+def cmd_set_led_color(value: int) -> bytes:
+    return cmd_set_value(Opcode.SET_LED_COLOR, value)
+
+
+def cmd_set_vibration(value: int) -> bytes:
+    return cmd_set_value(Opcode.SET_VIBRATION, value)
+
+
+def cmd_set_lock(value: int) -> bytes:
+    return cmd_set_value(Opcode.SET_LOCK, value)
+
+
+def cmd_set_lighting(value: int) -> bytes:
+    return cmd_set_value(Opcode.SET_LIGHTING, value)
+
+
+def cmd_set_anti_collision(value: int) -> bytes:
+    return cmd_set_value(Opcode.SET_ANTI_COLLISION, value)
+
+
+def cmd_set_reminder(minutes: int) -> bytes:
+    return cmd_set_value(Opcode.SET_REMINDER, minutes)
+
+
+@dataclasses.dataclass(slots=True)
+class DeskState:
+    """Mutable snapshot of all known desk state."""
+
+    height_raw: int | None = None
+    is_moving: bool = False
+    lock_status: int | None = None
+    brightness: int | None = None
+    led_color: int | None = None
+    vibration: int | None = None
+    lighting: int | None = None
+    anti_collision: int | None = None
+    touch_mode: int | None = None
+    upper_limit_raw: int | None = None
+    lower_limit_raw: int | None = None
+    has_limits: bool = False
+
+    @property
+    def height_cm(self) -> float | None:
+        if self.height_raw is None:
+            return None
+        return height_raw_to_cm(self.height_raw)
+
+
+def parse_notification(data: bytes | bytearray, state: DeskState) -> bool:
+    """Parse a BLE notification payload and update *state* in-place.
+
+    Returns ``True`` if the notification was recognised and handled.
+
+    Uses a zero-copy ``memoryview`` to avoid intermediate allocations
+    when slicing the incoming BLE payload.
+    """
+    mv = memoryview(data)
+
+    if len(mv) < 6:
+        return False
+
+    if mv[0] != 0xF2 or mv[1] != 0xF2:
+        return False
+
+    cmd = mv[2]
+    data_len = mv[3]
+
+    if cmd == 0x01 and data_len == 0x03 and len(mv) >= 6:
+        raw = (mv[4] << 8) | mv[5]
+        state.height_raw = raw
+        state.is_moving = True
+        return True
+
+    if cmd == 0x21 and data_len == 0x02 and len(mv) >= 6:
+        state.upper_limit_raw = (mv[4] << 8) | mv[5]
+        state.has_limits = True
+        return True
+
+    if cmd == 0x22 and data_len == 0x02 and len(mv) >= 6:
+        state.lower_limit_raw = (mv[4] << 8) | mv[5]
+        state.has_limits = True
+        return True
+
+    if cmd == 0x20 and data_len == 0x01 and len(mv) >= 5:
+        state.has_limits = mv[4] != 0x00
+        return True
+
+    if cmd == 0x1D and data_len == 0x01 and len(mv) >= 5:
+        state.anti_collision = mv[4]
+        return True
+
+    if cmd == 0xB2 and data_len == 0x01 and len(mv) >= 5:
+        state.lock_status = mv[4]
+        return True
+
+    if cmd == 0xB6 and data_len == 0x01 and len(mv) >= 5:
+        state.brightness = mv[4]
+        return True
+
+    if cmd == 0xB4 and data_len == 0x01 and len(mv) >= 5:
+        state.led_color = mv[4]
+        return True
+
+    if cmd == 0xB3 and data_len == 0x01 and len(mv) >= 5:
+        state.vibration = mv[4]
+        return True
+
+    if cmd == 0xB5 and data_len == 0x01 and len(mv) >= 5:
+        state.lighting = mv[4]
+        return True
+
+    if cmd == 0x19 and data_len == 0x01 and len(mv) >= 5:
+        state.touch_mode = mv[4]
+        return True
+
+    _LOGGER.debug("Unhandled notification: %s", bytes(mv).hex())
+    return False