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

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

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). Shell equivalent: python examples/lock_cli.py --transport bleak lock.

Start here

docs/ — the documentation entry point (understand · port · diagnose).
docs/devices/u200/validation.md — run it against a real U200 (facade, transports, troubleshooting).
docs/architecture.md — how it works end to end and the transversal-vs-device Layer Map.
docs/porting-guide.md — the numbered process to bring a new device online, with the CRC and login obstacles solved up front.
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); raw captures live under a git-ignored captures/ tree. See Constitution Principle I in .specify/memory/constitution.md.

License

See LICENSE.

Metadata

Release files for aqara-ble 1.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aqara-ble 1.11.0
File	Size	Uploaded
aqara_ble-1.11.0.tar.gz	155.6 kB	Sep 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for aqara-ble 1.11.0
File	Interpreter	ABI	Platform	Reset
aqara_ble-1.11.0-py3-none-any.whl 118.4 kB Sep 6, 2026	Python 3	none	any	Details

Total release size: 274.0 kB

Release files / aqara_ble-1.11.0.tar.gz

Download URL	aqara_ble-1.11.0.tar.gz
Size	155.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`8b31fdd68d54fa082f54c03e7fc12d25fd577f0cb3736c51eb106d3b3c8eadb5`
BLAKE2b-256 checksum How to use checksums	`34039617f2f759852a0820ad1ce78d03b1b481e0281ccf9adf200341eb2426d4`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dani811/Aqara
Publishing commit: github.com/dani811/Aqara/tree/6fbecfa128cb3acf904280c9088dea554c2b80e5

Workflow

Publishing configuration: github.com/dani811/Aqara/blob/6fbecfa128cb3acf904280c9088dea554c2b80e5/.github/workflows/publish.yml
Publishing logs: github.com/dani811/Aqara/actions/runs/34030787826/attempts/1

Artifact

Subject: aqara_ble-1.11.0.tar.gz
SHA-256 checksum: 8b31fdd68d54fa082f54c03e7fc12d25fd577f0cb3736c51eb106d3b3c8eadb5 Verifying attestations

Release files / aqara_ble-1.11.0-py3-none-any.whl

Download URL	aqara_ble-1.11.0-py3-none-any.whl
Size	118.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`0166fa481b131ec9417c16710c3bf754ca99137d8a488ccfc8fb642d4424c4e0`
BLAKE2b-256 checksum How to use checksums	`9dedd1872bdf28ce46ffd81ee923684c8e33cd7db61f974a6d2ce5501d77532d`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dani811/Aqara
Publishing commit: github.com/dani811/Aqara/tree/6fbecfa128cb3acf904280c9088dea554c2b80e5

Workflow

Publishing configuration: github.com/dani811/Aqara/blob/6fbecfa128cb3acf904280c9088dea554c2b80e5/.github/workflows/publish.yml
Publishing logs: github.com/dani811/Aqara/actions/runs/34030787826/attempts/1

Artifact

Subject: aqara_ble-1.11.0-py3-none-any.whl
SHA-256 checksum: 0166fa481b131ec9417c16710c3bf754ca99137d8a488ccfc8fb642d4424c4e0 Verifying attestations