/python-miio

Python library & console tool for controlling Xiaomi smart appliances

Primary LanguagePythonOtherNOASSERTION

python-miio

Chat PyPI version PyPI downloads Build Status Coverage Status Documentation status Black

This library (and its accompanying cli tool) can be used to interface with devices using Xiaomi's miIO and MIoT protocols.

Getting started

The miiocli command allows controlling supported devices from the command line, given that you know their IP addresses and tokens. You can use miiocli cloud command to obtain this information from the cloud. Refer to Getting started section of the manual for more detailed instructions.

You can always use --help to get more information about available commands, subcommands, and their options. For example, to print out options and available commands:

$ miiocli --help
Usage: miiocli [OPTIONS] COMMAND [ARGS]...

Options:
  -d, --debug
  -o, --output [default|json|json_pretty]
  --help                          Show this message and exit.

Commands:
  airconditioningcompanion
  ..

You can get some information from any miIO/MIoT device, including its device model, using the info command:

miiocli device --ip <ip> --token <token> info

Model: some.device.model1
Hardware version: esp8285
Firmware version: 1.0.1_0012
Network: {'localIp': '<ip>', 'mask': '255.255.255.0', 'gw': '<ip>'}
AP: {'rssi': -73, 'ssid': '<nnetwork>', 'primary': 11, 'bssid': '<bssid>'}

Controlling MIoT devices

MiOT devices are supported by the genericmiot integration which provides basic support for all MiOT devices. Internally, it downloads miot-spec files to find out about supported features. All features of supported devices are available using these common commands:

-  ``miiocli genericmiot status`` to print the device status information, including settings (prefixed with ``[S]``).
-  ``miiocli genericmiot set`` to change settings.
-  ``miiocli genericmiot actions`` to list available actions.
-  ``miiocli genericmiot call`` to execute actions.

Use miiocli genericmiot --help for more available commands.

Controlling other devices

Older devices are mainly supported by their corresponding modules (e.g., roborockvacuum or fan).

You can get the list of available commands for any given module by passing --help argument to it:

$ miiocli roborockvacuum --help

Usage: miiocli roborockvacuum [OPTIONS] COMMAND [ARGS]...

Options:
  --ip TEXT       [required]
  --token TEXT    [required]
  --id-file FILE
  --help          Show this message and exit.

Commands:
  add_timer                Add a timer.
  ..

Each command invocation will automatically detect the device model necessary for some actions by querying the device. You can avoid this by specifying the model manually:

miiocli roborockvacuum --model roborock.vacuum.s5 --ip <ip> --token <token> start

API usage

All functionalities of this library are accessible through the miio module. While you can initialize individual integration classes manually, the simplest way to obtain a device instance is to use DeviceFactory:

from miio import DeviceFactory

dev = DeviceFactory.create("<ip address>", "<token>")
dev.info()

This will perform an info query to the device to detect its model information, which is crucial especially for MiOT devices.

Introspecting supported features

You can introspect device classes using the following methods:

-  ``actions()`` to return information about available device actions.
-  ``settings()`` to obtain information about available settings that can be changed.
-  ``sensors()`` to obtain information about sensors.

Each of these return device descriptor objects, which contain the necessary metadata about the available features to allow constructing generic interfaces.

Troubleshooting

You can find some solutions for the most common problems can be found in Troubleshooting section.

If you have any questions, or simply want to join up for a chat, check our Matrix room.

Contributing

We welcome all sorts of contributions from patches to add improvements or fixing bugs to improving the documentation. To ease the process of setting up a development environment we have prepared a short guide for getting you started.

Supported devices

While all MIoT devices are supported through the genericmiot integration, this library supports also the following devices:

-  Xiaomi Mi Robot Vacuum V1, S4, S4 MAX, S5, S5 MAX, S6 Pure, M1S, S7
-  Xiaomi Mi Home Air Conditioner Companion
-  Xiaomi Mi Smart Air Conditioner A (xiaomi.aircondition.mc1, mc2, mc4, mc5)
-  Xiaomi Mi Air Purifier 2, 3H, 3C, 4, Pro, Pro H, 4 Pro (zhimi.airpurifier.m2, mb3, mb4, mb5, v7, vb2, va2), 4 Lite
-  Xiaomi Mi Air (Purifier) Dog X3, X5, X7SM (airdog.airpurifier.x3, x5, x7sm)
-  Xiaomi Mi Air Humidifier
-  Smartmi Air Purifier
-  Xiaomi Aqara Camera
-  Xiaomi Aqara Gateway (basic implementation, alarm, lights)
-  Xiaomi Mijia 360 1080p
-  Xiaomi Mijia STYJ02YM (Viomi)
-  Xiaomi Mijia 1C STYTJ01ZHM (Dreame)
-  Dreame F9, D9, L10 Pro, Z10 Pro
-  Dreame Trouver Finder
-  Xiaomi Mi Home (Mijia) G1 Robot Vacuum Mop MJSTG1
-  Xiaomi Roidmi Eve
-  Xiaomi Mi Smart WiFi Socket
-  Xiaomi Chuangmi camera (chuangmi.camera.ipc009, ipc013, ipc019, 038a2)
-  Xiaomi Chuangmi Plug V1 (1 Socket, 1 USB Port)
-  Xiaomi Chuangmi Plug V3 (1 Socket, 2 USB Ports)
-  Xiaomi Smart Power Strip V1 and V2 (WiFi, 6 Ports)
-  Xiaomi Philips Eyecare Smart Lamp 2
-  Xiaomi Philips RW Read (philips.light.rwread)
-  Xiaomi Philips LED Ceiling Lamp
-  Xiaomi Philips LED Ball Lamp (philips.light.bulb)
-  Xiaomi Philips LED Ball Lamp White (philips.light.hbulb)
-  Xiaomi Philips Zhirui Smart LED Bulb E14 Candle Lamp
-  Xiaomi Philips Zhirui Bedroom Smart Lamp
-  Huayi Huizuo Lamps
-  Xiaomi Universal IR Remote Controller (Chuangmi IR)
-  Xiaomi Mi Smart Pedestal Fan V2, V3, SA1, ZA1, ZA3, ZA4, ZA5 1C, P5, P9, P10, P11, P15, P18, P33
-  Xiaomi Rosou SS4 Ventilator (leshow.fan.ss4)
-  Xiaomi Mi Air Humidifier V1, CA1, CA4, CB1, MJJSQ, JSQ, JSQ1, JSQ001
-  Xiaomi Mi Water Purifier (Basic support: Turn on & off)
-  Xiaomi Mi Water Purifier D1, C1 (Triple Setting)
-  Xiaomi PM2.5 Air Quality Monitor V1, B1, S1
-  Xiaomi Smart WiFi Speaker
-  Xiaomi Mi WiFi Repeater 2
-  Xiaomi Mi Smart Rice Cooker
-  Xiaomi Smartmi Fresh Air System VA2 (zhimi.airfresh.va2), VA4 (va4), T2017 (t2017), A1 (dmaker.airfresh.a1)
-  Yeelight lights (see also `python-yeelight <https://gitlab.com/stavros/python-yeelight/>`__)
-  Xiaomi Mi Air Dehumidifier
-  Xiaomi Tinymu Smart Toilet Cover
-  Xiaomi 16 Relays Module
-  Xiaomi Xiao AI Smart Alarm Clock
-  Smartmi Radiant Heater Smart Version (ZA1 version)
-  Xiaomi Mi Smart Space Heater
-  Xiaomiyoupin Curtain Controller (Wi-Fi) (lumi.curtain.hagl05)
-  Xiaomi Dishwasher (viomi.dishwasher.m02)
-  Xiaomi Xiaomi Mi Smart Space Heater S (zhimi.heater.mc2)
-  Xiaomi Xiaomi Mi Smart Space Heater 1S (zhimi.heater.za2)
-  Yeelight Dual Control Module (yeelink.switch.sw1)
-  Scishare coffee maker (scishare.coffee.s1102)
-  Qingping Air Monitor Lite (cgllc.airm.cgdn1)
-  Xiaomi Walkingpad A1 (ksmb.walkingpad.v3)
-  Xiaomi Smart Pet Water Dispenser (mmgg.pet_waterer.s1, s4, wi11)
-  Xiaomi Mi Smart Humidifer S (jsqs, jsq5)
-  Xiaomi Mi Robot Vacuum Mop 2 (Pro+, Ultra)

Feel free to create a pull request to add support for new devices as well as additional features for supported devices.

Projects using this library

This library is used by various projects to support MiIO/MiOT devices. If you are using this library for your project, feel free to open a PR to get it listed here!

Home Assistant (official)

Home Assistant uses this library to support several platforms out-of-the-box. This list is incomplete as the platforms (in parentheses) may also support other devices listed above.

Home Assistant (custom)

Other related projects

This is a list of other projects around the Xiaomi ecosystem that you can find interesting. Feel free to submit more related projects.