Registry / communication / python-miio

python-miio

JSON →
library0.5.12pypypi✓ verified 85d ago

python-miio is a Python library and accompanying command-line tool (`miiocli`) designed to control Xiaomi smart home devices using their miIO and MIoT protocols. It provides an API to interact with a wide range of devices, including robot vacuums, air purifiers, humidifiers, lights, and smart plugs. The library is actively maintained with ongoing development towards a significant 0.6.0 release that introduces major architectural changes.

pip install python-miio
INSTALL
IMPORT
SIG · PYTHON-MIIO
P
python-miio
communicationpythonv0.5.12
Install
8.9s avg
Import
1448ms
Disk
78MB
Pass rate
1/ 10
Env Coverage1 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.6.0.dev0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
4/12 runs
4/12 runs
py 3.11
4/12 runs
4/12 runs
py 3.12
4/12 runs
4/12 runs
py 3.13
4/12 runs
4/12 runs
py 3.9
4/12 runs
✓ 8.88s
78MB installed
● package 78MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AirConditionerMiot
from miio import AirConditionerMiot
from miio import DeviceFactory

This quickstart demonstrates how to connect to a Xiaomi smart appliance using `DeviceFactory`, which is the recommended approach for modern MIoT devices and future versions of the library (0.6.0+). It attempts to retrieve basic device information and status. Device IP and token are expected from environment variables for security and flexibility.

import os from miio import DeviceFactory from miio.exceptions import DeviceException DEVICE_IP = os.environ.get('MIIO_DEVICE_IP', '192.168.1.100') DEVICE_TOKEN = os.environ.get('MIIO_DEVICE_TOKEN', 'YOUR_DEVICE_TOKEN') # 32-character hex token if DEVICE_TOKEN == 'YOUR_DEVICE_TOKEN': print("WARNING: Replace 'YOUR_DEVICE_TOKEN' with your actual device token or set MIIO_DEVICE_TOKEN environment variable.") print(" You can obtain tokens using 'miiocli cloud' (requires micloud) or legacy methods outlined in the documentation.") exit(1) if __name__ == '__main__': try: # For modern MIoT devices or future-proof instantiation (requires python-miio 0.6.0.dev0+ for best results) # For 0.5.x, direct class import like `from miio import RoborockVacuum` is more typical. dev = DeviceFactory.create(DEVICE_IP, DEVICE_TOKEN) print(f"Connected to device: {dev.info.model} ({dev.info.firmware_version})") status = dev.status() if hasattr(status, 'power'): print(f"Device power: {status.power}") elif hasattr(status, 'temperature'): print(f"Device temperature: {status.temperature}°C") else: print(f"Device status: {status.data}") except DeviceException as e: print(f"Error connecting to device: {e}") print("Ensure the IP address and token are correct and the device is on the same network or subnet.") except Exception as e: print(f"An unexpected error occurred: {e}")
miiocli --version
Debug
Known issues
breakingStarting with 0.6.0, major breaking changes include moving device integrations into `miio.integrations` (e.g., `miio.vacuum` becomes `miio.integrations.vacuum.roborock`). Direct imports of device classes are discouraged in favor of `DeviceFactory.create()` for automatic discovery. Python 3.7 support will be dropped.
fix
Migrate to `DeviceFactory.create(ip, token)` for device instantiation. If using a specific device class, verify its new import path under `miio.integrations`. Ensure your Python version is 3.8 or higher.
affects: 0.6.0.dev0+
deprecatedSpecific device classes (e.g., `AirFreshVA4`, `AirHumidifierCA1/CB1/CB2`, `Vacuum`) have been deprecated in favor of more generic classes (e.g., `AirFresh`, `AirHumidifier`) and model-based discovery. The `Vacuum` class itself is deprecated and will be reused as a common interface.
fix
Use the more generic device class or leverage `DeviceFactory.create()` which handles model-based discovery. For example, instead of `AirHumidifierCA1`, use `AirHumidifier`.
affects: 0.5.9, 0.5.11
gotchaObtaining device tokens can be challenging. While `miiocli cloud` (requires `micloud` package) can fetch tokens from your Xiaomi cloud account, many users still resort to legacy methods like inspecting Mi Home app logs or backups for older versions.
fix
Refer to the official documentation's 'Obtaining tokens' section. The `miiocli cloud` command is often the easiest, but if it fails, 'Legacy methods for obtaining tokens' documentation provides alternatives.
affects: All versions
gotchaDevices may not respond or exhibit intermittent connection issues if the client and the Xiaomi device are on different subnets. The device might reject requests if the source IP is not in its local subnet.
fix
Place the `python-miio` client and the Xiaomi device on the same subnet. Alternatively, if dual-homing is an option, configure your client to be in both subnets. For firewall rules, use `REJECT` instead of `DROP` for outbound connections if you wish to keep the device isolated.
affects: All versions
Upgrade
Version history
0.5.12latest on PyPI · released Jul 18, 2022
Audit
Dependencies
clickrequiredCommand-Line Interface Creation Kit
constructrequiredDeclarative parser for binary data
cryptographyrequiredCryptographic primitives
netifacesrequiredNetwork interface information
zeroconfrequiredmDNS/DNS-SD (Bonjour) implementation
micloudoptionalRequired for fetching device tokens from Xiaomi cloud via miiocli.
Agent activity
23 hits · last 30 days
node
22
OpenAI (training)
1
Resources
python-miio — pip install python-miio · libregistry