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.
1 maintainer
Metadata
1 maintainer
Release files for aqara-ble 1.15.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| aqara_ble-1.15.1.tar.gz | 163.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| aqara_ble-1.15.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 288.4 kB
Release files / aqara_ble-1.15.1.tar.gz
| Download URL | aqara_ble-1.15.1.tar.gz |
|---|---|
| Size | 163.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
15f407d12adfa836809b26106414754333da1037252532907817e45f810238cb
|
|
BLAKE2b-256 checksum How to use checksums |
14445788fad9aec0746b74c69e2ca9e4aa5c668fbeb086574268a4b6aa6881d0
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / aqara_ble-1.15.1-py3-none-any.whl
| Download URL | aqara_ble-1.15.1-py3-none-any.whl |
|---|---|
| Size | 124.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bc8dd42a44616b7ff4775203afcf3948683808601e5edbbdbdfffc4f3bb851e2
|
|
BLAKE2b-256 checksum How to use checksums |
bc5d87f2d7815ca635f01f289f7b28685ff5ca322da37c637b78f25661e11a8c
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency log
