xiaomi-ble

What it is and what it does

xiaomi-ble is a Python library for communicating with Xiaomi smart devices over Bluetooth Low Energy. It wraps the complexity of BLE protocol handling—using bleak for cross-platform Bluetooth access and related libraries for device data parsing and cryptography—into a simpler interface for discovering and reading sensor data from Xiaomi devices.

The library is in Pre-Alpha development, meaning its API and feature set are still evolving. It depends on a substantial stack of Bluetooth and cryptographic libraries (aiohttp, bleak, bleak-retry-connector, bluetooth-data-tools, bluetooth-sensor-state-data, cryptography, home-assistant-bluetooth, orjson, pycryptodomex, sensor-state-data) to handle the low-level work. It targets Python 3.11 and later and is actively maintained, with recent releases and ongoing commits.

Use it for:

• Read sensor data (temperature, humidity, battery) from Xiaomi smart home devices in a home automation setup
• Discover and enumerate Xiaomi BLE devices on a local network for device inventory or pairing workflows
• Integrate Xiaomi device telemetry into a Home Assistant or custom IoT dashboard
• Decrypt and parse Xiaomi device payloads for research or reverse-engineering Xiaomi BLE protocols
• Monitor Xiaomi device state changes asynchronously in a long-running service or daemon

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Manages Xiaomi BLE (Bluetooth Low Energy) devices by providing a Python interface to discover, connect to, and interact with Xiaomi devices over Bluetooth.

Yes, if you need to integrate Xiaomi BLE devices into a Python application and accept Pre-Alpha stability. The library is actively maintained, has low install friction, carries no known vulnerabilities, and uses a permissive license. However, verify that your target Xiaomi devices are supported and be prepared for API changes as the library matures.

Install

xiaomi-ble on PyPI

pip install xiaomi-ble

uv add xiaomi-ble

poetry add xiaomi-ble

Installing xiaomi-ble

Before you install

Low friction installation with a pure-Python wheel. Active maintenance (last commit 2026-08-10) and recent release (25 days old). Pre-Alpha status signals the library is still stabilizing; expect API changes or incomplete feature coverage.

License in practice

Apache-2.0 permissive license allows commercial and private use with minimal restrictions; you must include a copy of the license and note any modifications.

Quickstart

pip install xiaomi-ble

import asyncio
from xiaomi_ble import XiaomiBluetoothDeviceData

# Requires bleak for BLE scanning and connection
await XiaomiBluetoothDeviceData.discover()

Requires a system with Bluetooth hardware and appropriate OS-level Bluetooth drivers (Linux, macOS, or Windows with BLE support).

Verify before relying

• Which specific Xiaomi device models are supported by this version
• Whether the library handles device pairing or assumes pre-paired devices
• Real-world reliability and latency characteristics for typical Xiaomi devices
• Whether decryption of Xiaomi cloud keys is automatic or requires manual setup

Package facts

Evidence: xiaomi_ble-1.16.0-py3-none-any.whl

Tags

More Libraries packages