Python library for interfacing with Xiaomi smart appliances

Warnings

• breaking Starting 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.
• deprecated Specific 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`.
• gotcha Obtaining 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.
• gotcha Devices 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.

Install

• pip install python-miio Stable release
• pip install --pre python-miio Pre-release (0.6.0.dev0+)
• pip install 'python-miio[micloud]' With cloud token fetching support

Imports

• DeviceFactory

  from miio import DeviceFactory

  Recommended for 0.6.0+ and modern MIoT devices for dynamic device instance creation. Handles model discovery automatically.
• RoborockVacuum
  wrong:

  from miio.vacuum import RoborockVacuum

  correct:

  from miio import RoborockVacuum

  For 0.5.x, direct import of specific device classes is common. In 0.6.0, integrations moved to `miio.integrations.*` and direct class import for older devices may change.

Quickstart

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}")