aqara-ble 1.0.0__tar.gz

aqara_ble-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dani811
+
+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.

aqara_ble-1.0.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: aqara-ble
+Version: 1.0.0
+Summary: Autonomous BLE control library for the Aqara U200 smart lock — cloud KDF, auth handshake and AES-CCM control channel, reimplemented in pure Python.
+Author: dani811
+Maintainer: dani811
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dani811/Aqara
+Project-URL: Repository, https://github.com/dani811/Aqara
+Project-URL: Issues, https://github.com/dani811/Aqara/issues
+Keywords: aqara,u200,smart-lock,bluetooth,ble,reverse-engineering,home-automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=43.0.0
+Provides-Extra: ble
+Requires-Dist: bleak>=0.22; extra == "ble"
+Provides-Extra: bumble
+Requires-Dist: bumble>=0.0.200; extra == "bumble"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# Aqara BLE
+
+Autonomous control of Aqara Bluetooth Low Energy locks from Python — no app, no
+phone — reconstructed by reverse-engineering the official application's observed
+behaviour. The **U200** is the fully solved reference device.
+
+## Goals
+
+- Document the Aqara BLE + cloud protocol precisely enough to reproduce it.
+- Provide a cross-platform Python library that exposes the lock's full operation
+  surface.
+- Enable a native Home Assistant integration (the primary target).
+- Make porting to other Aqara-family devices a methodical, repeatable process.
+
+## Quick start
+
+Two ways in — a terminal command and an importable API. **Integrations couple to
+the API**; the CLI is just a thin adapter over that same API.
+
+### Terminal — the `aqara` command
+
+```bash
+pip install -e .            # puts `aqara` on your PATH
+aqara login                 # account login only (no radio)
+aqara scan  --transport bleak
+aqara lock  --transport bumble --port serial:/dev/cu.usbmodemNNNN,115200
+aqara unlock ; aqara operate keepalive
+```
+
+Credentials come from `--account/--password` or the environment/`.env`
+(`AQARA_ACCOUNT`, `AQARA_PASSWORD`, `AQARA_APPID`, `AQARA_APPKEY`,
+`AQARA_CLIENT_ID`, `AQARA_PHONE_ID`, `AQARA_DEVICE_ID`).
+
+### Library — the coupling surface for integrations
+
+```python
+from aqara_ble import BleakTransport, CloudAuthManager, U200Client
+
+auth = CloudAuthManager(
+    account=..., password=..., appid=..., appkey=..., client_id=..., phone_id=...
+)
+async with await U200Client.connect(
+    auth=auth, transport=BleakTransport(), device_id="lumi1.xxxx"
+) as lock:
+    await lock.lock()
+```
+
+The facade logs in (and re-authenticates on token expiry), scans and identifies
+the lock by what it advertises, connects, discovers services and runs the
+authenticated operation. Swap `BleakTransport()` for
+`BumbleTransport("serial:/dev/…")` to drive an ESP32‑S3 controller
+([firmware](tools/esp32s3_hci_usb/README.md)). Shell equivalent:
+`python examples/lock_cli.py --transport bleak lock`.
+
+## Start here
+
+- **[docs/](docs/README.md)** — the documentation entry point (understand · port ·
+  diagnose).
+- **[docs/devices/u200/validation.md](docs/devices/u200/validation.md)** — run it
+  against a real U200 (facade, transports, troubleshooting).
+- **[docs/architecture.md](docs/architecture.md)** — how it works end to end and
+  the transversal-vs-device Layer Map.
+- **[docs/porting-guide.md](docs/porting-guide.md)** — the numbered process to
+  bring a new device online, with the CRC and login obstacles solved up front.
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — Spec-Driven Development workflow and the
+  secret-hygiene rules.
+
+## Secrets — non-negotiable
+
+No real secret, capture, or app source ever enters this repository. Credentials
+and device identifiers live only in a local, git-ignored `.env` (see
+[`.env.example`](.env.example)); raw captures live under a git-ignored `captures/`
+tree. See Constitution Principle I in
+[`.specify/memory/constitution.md`](.specify/memory/constitution.md).
+
+## License
+
+See [LICENSE](LICENSE).

aqara_ble-1.0.0/README.md

@@ -0,0 +1,78 @@
+# Aqara BLE
+
+Autonomous control of Aqara Bluetooth Low Energy locks from Python — no app, no
+phone — reconstructed by reverse-engineering the official application's observed
+behaviour. The **U200** is the fully solved reference device.
+
+## Goals
+
+- Document the Aqara BLE + cloud protocol precisely enough to reproduce it.
+- Provide a cross-platform Python library that exposes the lock's full operation
+  surface.
+- Enable a native Home Assistant integration (the primary target).
+- Make porting to other Aqara-family devices a methodical, repeatable process.
+
+## Quick start
+
+Two ways in — a terminal command and an importable API. **Integrations couple to
+the API**; the CLI is just a thin adapter over that same API.
+
+### Terminal — the `aqara` command
+
+```bash
+pip install -e .            # puts `aqara` on your PATH
+aqara login                 # account login only (no radio)
+aqara scan  --transport bleak
+aqara lock  --transport bumble --port serial:/dev/cu.usbmodemNNNN,115200
+aqara unlock ; aqara operate keepalive
+```
+
+Credentials come from `--account/--password` or the environment/`.env`
+(`AQARA_ACCOUNT`, `AQARA_PASSWORD`, `AQARA_APPID`, `AQARA_APPKEY`,
+`AQARA_CLIENT_ID`, `AQARA_PHONE_ID`, `AQARA_DEVICE_ID`).
+
+### Library — the coupling surface for integrations
+
+```python
+from aqara_ble import BleakTransport, CloudAuthManager, U200Client
+
+auth = CloudAuthManager(
+    account=..., password=..., appid=..., appkey=..., client_id=..., phone_id=...
+)
+async with await U200Client.connect(
+    auth=auth, transport=BleakTransport(), device_id="lumi1.xxxx"
+) as lock:
+    await lock.lock()
+```
+
+The facade logs in (and re-authenticates on token expiry), scans and identifies
+the lock by what it advertises, connects, discovers services and runs the
+authenticated operation. Swap `BleakTransport()` for
+`BumbleTransport("serial:/dev/…")` to drive an ESP32‑S3 controller
+([firmware](tools/esp32s3_hci_usb/README.md)). Shell equivalent:
+`python examples/lock_cli.py --transport bleak lock`.
+
+## Start here
+
+- **[docs/](docs/README.md)** — the documentation entry point (understand · port ·
+  diagnose).
+- **[docs/devices/u200/validation.md](docs/devices/u200/validation.md)** — run it
+  against a real U200 (facade, transports, troubleshooting).
+- **[docs/architecture.md](docs/architecture.md)** — how it works end to end and
+  the transversal-vs-device Layer Map.
+- **[docs/porting-guide.md](docs/porting-guide.md)** — the numbered process to
+  bring a new device online, with the CRC and login obstacles solved up front.
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — Spec-Driven Development workflow and the
+  secret-hygiene rules.
+
+## Secrets — non-negotiable
+
+No real secret, capture, or app source ever enters this repository. Credentials
+and device identifiers live only in a local, git-ignored `.env` (see
+[`.env.example`](.env.example)); raw captures live under a git-ignored `captures/`
+tree. See Constitution Principle I in
+[`.specify/memory/constitution.md`](.specify/memory/constitution.md).
+
+## License
+
+See [LICENSE](LICENSE).

aqara_ble-1.0.0/aqara_ble/__init__.py

@@ -0,0 +1,206 @@
+"""Autonomous BLE control for the Aqara U200 smart lock.
+
+Pure-Python reimplementation of the cloud KDF, the BLE authentication
+handshake (frames ``0610``/``0710``) and the AES-CCM control channel. See
+``docs/`` for the reverse-engineered protocol.
+
+This package is assembled incrementally, one Spec Kit feature at a time. The
+recommended entry point is the **feature 015 facade**: ``U200Client`` +
+a ``Transport`` (``BleakTransport`` for the host radio, ``BumbleTransport`` for
+an external ESP32-S3 HCI controller) + ``CloudAuthManager`` (account login with
+automatic token refresh). The lower-level pieces (KDF, framing, session flow,
+operations catalogue) remain public for advanced consumers.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .auth import CloudAuthManager
+from .bumble_transport import BumbleGattAdapter
+from .client import OperationResult, U200Client
+from .cloud_crypto import (
+    aes128gcm_decrypt_body,
+    aes128gcm_encrypt_body,
+    compute_nonce,
+    compute_sign,
+    encrypt_login_password,
+    hkdf_expand,
+    hkdf_extract,
+    hkdf_sha256,
+    make_local_signer,
+)
+from .control_codec import decrypt_control_payload, encrypt_control_payload
+from .errors import AmbiguousDeviceError, FlowPhase, NoDeviceFoundError, U200ClientError
+from .framing import (
+    assemble_auth_fragments,
+    build_auth_message,
+    crc16_aqara,
+    fragment_auth_message,
+    parse_auth_message,
+)
+from .gatt import GattClient
+from .gatt_uuids import (
+    AUTH_NOTIFY_UUID,
+    AUTH_SERVICE_UUID,
+    AUTH_WRITE_UUID,
+    AUX_NOTIFY_UUID,
+    AUX_SERVICE_UUID,
+    CONTROL_NOTIFY2_UUID,
+    CONTROL_NOTIFY_UUID,
+    CONTROL_SERVICE_UUID,
+    CONTROL_WRITE_UUID,
+    GATT_CACHING_PREAMBLE_UUID16,
+    PRE_AUTH_NOTIFY_ORDER,
+    U200_SERVICE_UUIDS,
+)
+from .kdf import (
+    CloudServiceError,
+    build_cloud_auth_headers,
+    cloud_get_public_key,
+    cloud_verify,
+    get_session_material,
+    login,
+    prepare_runtime_cloud_auth_headers,
+)
+from .lock_ops import (
+    LockOperation,
+    LockOperationWrite,
+    build_control_frame,
+    build_control_query_write,
+    build_lock_operation_write,
+    build_operate_frame,
+    normalize_lock_operation,
+    send_lock_operation,
+)
+from .lock_state import LockState, decode_lock_state
+from .models import MODEL_BY_PRODUCT_ID, decode_manufacturer_payload
+from .operations_catalog import (
+    OPERATIONS_CATALOG,
+    CommandFamily,
+    OperationEntry,
+    OperationStatus,
+    find_operation,
+    operations_in_family,
+)
+from .protocol import (
+    ControlRequest,
+    control_command_name,
+    parse_control_request,
+    valid_crc,
+)
+from .scanner import identify_candidate, scan, select_preferred
+from .session import (
+    OperationInProgressError,
+    SessionMaterial,
+    run_authenticated_lock_operation,
+)
+from .transport import (
+    AQARA_COMPANY_ID,
+    EXPECTED_NAME,
+    BleakTransport,
+    BumbleTransport,
+    ScanCandidate,
+    Transport,
+)
+from .volume import (
+    VoiceVolumePreset,
+    VoiceVolumeWrite,
+    build_voice_volume_write,
+    normalize_voice_volume_preset,
+    set_voice_volume,
+    write_voice_volume,
+)
+
+try:
+    __version__ = version("aqara-ble")
+except PackageNotFoundError:  # pragma: no cover - running from a source checkout
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "AQARA_COMPANY_ID",
+    "AUTH_NOTIFY_UUID",
+    "AUTH_SERVICE_UUID",
+    "AUTH_WRITE_UUID",
+    "AUX_NOTIFY_UUID",
+    "AUX_SERVICE_UUID",
+    "CONTROL_NOTIFY2_UUID",
+    "CONTROL_NOTIFY_UUID",
+    "CONTROL_SERVICE_UUID",
+    "CONTROL_WRITE_UUID",
+    "EXPECTED_NAME",
+    "GATT_CACHING_PREAMBLE_UUID16",
+    "MODEL_BY_PRODUCT_ID",
+    "OPERATIONS_CATALOG",
+    "PRE_AUTH_NOTIFY_ORDER",
+    "U200_SERVICE_UUIDS",
+    "AmbiguousDeviceError",
+    "BleakTransport",
+    "BumbleGattAdapter",
+    "BumbleTransport",
+    "CloudAuthManager",
+    "CloudServiceError",
+    "CommandFamily",
+    "ControlRequest",
+    "FlowPhase",
+    "GattClient",
+    "LockOperation",
+    "LockOperationWrite",
+    "LockState",
+    "NoDeviceFoundError",
+    "OperationEntry",
+    "OperationInProgressError",
+    "OperationResult",
+    "OperationStatus",
+    "ScanCandidate",
+    "SessionMaterial",
+    "Transport",
+    "U200Client",
+    "U200ClientError",
+    "VoiceVolumePreset",
+    "VoiceVolumeWrite",
+    "__version__",
+    "aes128gcm_decrypt_body",
+    "aes128gcm_encrypt_body",
+    "assemble_auth_fragments",
+    "build_auth_message",
+    "build_cloud_auth_headers",
+    "build_control_frame",
+    "build_control_query_write",
+    "build_lock_operation_write",
+    "build_operate_frame",
+    "build_voice_volume_write",
+    "cloud_get_public_key",
+    "cloud_verify",
+    "compute_nonce",
+    "compute_sign",
+    "control_command_name",
+    "crc16_aqara",
+    "decode_lock_state",
+    "decode_manufacturer_payload",
+    "decrypt_control_payload",
+    "encrypt_control_payload",
+    "encrypt_login_password",
+    "find_operation",
+    "fragment_auth_message",
+    "get_session_material",
+    "hkdf_expand",
+    "hkdf_extract",
+    "hkdf_sha256",
+    "identify_candidate",
+    "login",
+    "make_local_signer",
+    "normalize_lock_operation",
+    "normalize_voice_volume_preset",
+    "operations_in_family",
+    "parse_auth_message",
+    "parse_control_request",
+    "prepare_runtime_cloud_auth_headers",
+    "run_authenticated_lock_operation",
+    "scan",
+    "select_preferred",
+    "send_lock_operation",
+    "set_voice_volume",
+    "valid_crc",
+    "write_voice_volume",
+]

aqara_ble-1.0.0/aqara_ble/auth.py

@@ -0,0 +1,140 @@
+"""
+Automatic token management for cloud authentication.
+
+Handles login, token refresh on 108 errors, and transparent credential loading.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from .cloud_crypto import Signer, make_local_signer
+from .kdf import CloudServiceError, login
+
+logger = logging.getLogger(__name__)
+
+
+class CloudAuthManager:
+    """Manages Aqara cloud authentication with automatic token refresh.
+
+    Features:
+    - Load credentials from environment or .env files
+    - Automatic login with account/password (no manual token required)
+    - Transparent token refresh on expiration (code 108)
+    - Thread-safe caching of valid tokens
+    """
+
+    def __init__(
+        self,
+        *,
+        account: str,
+        password: str,
+        appid: str,
+        appkey: str,
+        client_id: str,
+        phone_id: str,
+        region: str = "EU",
+        district: str = "ES",
+    ) -> None:
+        """Initialize auth manager with account credentials.
+
+        Args:
+            account: Aqara account (email or phone)
+            password: Aqara account password
+            appid: Aqara app ID
+            appkey: Aqara app key
+            client_id: Firebase Cloud Messaging client ID
+            phone_id: Device phone ID
+            region: Aqara region (EU, CN, etc.)
+            district: Aqara district (ES, CN, etc.)
+        """
+        self.account = account
+        self.password = password
+        self.appid = appid
+        self.appkey = appkey
+        self.client_id = client_id
+        self.phone_id = phone_id
+        self.region = region
+        self.district = district
+
+        self._token: str | None = None
+        self._user_id: str | None = None
+
+    def _login(self) -> tuple[str, str]:
+        """Perform login and return (token, user_id).
+
+        A ``code 810`` (wrong password / unregistered account) is translated into
+        a clear, **non-retryable** error so the caller never loops on it — it is
+        not a token expiry. No credential is logged.
+        """
+        logger.debug("cloud login: starting")
+        try:
+            result = login(
+                self.account,
+                self.password,
+                appid=self.appid,
+                appkey=self.appkey,
+                client_id=self.client_id,
+                phone_id=self.phone_id,
+                region=self.region,
+                district=self.district,
+            )
+        except CloudServiceError as exc:
+            if exc.is_code(810):
+                raise RuntimeError(
+                    "Aqara login rejected the credentials (code 810): wrong "
+                    "password, or the account is not registered in this region. "
+                    "This is not a token expiry and is not retried."
+                ) from exc
+            raise
+        token = result.get("token")
+        user_id = result.get("userId") or result.get("uid")
+        if not token:
+            raise RuntimeError(f"Login failed: no token in result {sorted(result)}")
+        logger.debug("cloud login: succeeded")
+        return token, user_id or ""
+
+    def build_signer(self, *, force_refresh: bool = False) -> Signer:
+        """Build a cloud request signer bound to a valid token (logging in if
+        needed). Used by the operation flow to sign cloud calls and to rebuild
+        the signer after a token refresh."""
+        token = self.get_token(force_refresh=force_refresh)
+        return make_local_signer(
+            appid=self.appid,
+            appkey=self.appkey,
+            token=token,
+            user_id=self._user_id or "",
+            client_id=self.client_id,
+            phone_id=self.phone_id,
+            area=self.region,
+        )
+
+    def get_token(self, *, force_refresh: bool = False) -> str:
+        """Get valid token, logging in if needed.
+
+        Args:
+            force_refresh: Force new login even if cached token exists
+
+        Returns:
+            Valid JWT token for cloud API calls
+        """
+        if self._token and not force_refresh:
+            return self._token
+
+        token, user_id = self._login()
+        self._token = token
+        self._user_id = user_id
+        return token
+
+    def handle_expired_token(self) -> str:
+        """Handle a ``code=108`` (token expired) by forcing a fresh login.
+
+        Returns:
+            New valid token
+        """
+        logger.debug("cloud token: refreshing (expired)")
+        return self.get_token(force_refresh=True)
+
+    # NOTE: environment-based construction lives OUTSIDE the library, in
+    # examples/auth_from_env.py (Feature 014). The library never reads the
+    # environment: the consumer (e.g. Home Assistant) injects credentials.