A look at rytilahti/python-miio: 4.3k stars on GitHub, written primarily in Python, tracked under the Backend category. Python library & console tool for controlling Xiaomi smart appliances
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
This library (and its accompanying cli tool, miiocli) can be used to control devices using Xiaomi's
miIO
and MIoT protocols.
This is a voluntary, community-driven effort and is not affiliated with any of the companies whose devices are supported by this library.
Issue reports and pull requests are welcome, see contributing!
The full documentation is available at python-miio.readthedocs.io.
Installation
Getting started
Controlling modern (MIoT) devices
Controlling older (miIO) devices
Troubleshooting
API usage
Contributing
Simulators
Supported devices
Projects using this library
Other related projects
Installation
The most recent release can be installed using pip:
pip install python-miio
Alternatively, you can install the latest development version from GitHub:
This project is currently ongoing a major refactoring effort.
If you are interested in controlling modern (MIoT) devices, you want to use the git version (or pre-releases, pip install --pre python-miio) until version 0.6.0 is released.
Getting started
The miiocli command allows controlling supported devices from the
command line, given that you know their IP addresses and tokens.
The simplest way to acquire the tokens is by using the miiocli cloud command,
which fetches them for you from your cloud account using micloud:
miiocli cloud
Username: [email protected]
Password:
== name of the device (Device offline ) ==
Model: example.device.v1
Token: b1946ac92492d2347c6235b4d2611184
IP: 192.168.xx.xx (mac: ab:cd:ef:12:34:56)
DID: 123456789
Locale: cn
Alternatively, see the docs
for other ways to obtain them.
After you have your token, you can start controlling the device.
First, you can use info to get some generic information from any (even yet unsupported) device:
Note that the command field which gives you the direct command to use for controlling the device.
If the device is supported by the genericmiot integration as stated in the output,
you can also use miiocli genericmiot for controlling it.
You can always use --help to get more information about available
commands, subcommands, and their options.
Controlling modern (MIoT) devices
Most modern (MIoT) devices are automatically supported by the genericmiot integration.
Internally, it uses ("miot spec") files to find out about supported features,
such as sensors, settings and actions.
This device model specific file will be downloaded (and cached locally) when you use the genericmiot integration for the first time.
All features of supported devices are available using the common commands status (to show the device state), set (to change the settings), actions to list available actions and call to execute actions.
Device status
Executing status will show the current device state, and also the accepted values for settings (marked with access RW):
miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 status
Service Light (light)
Switch Status (light:on, access: RW): False (<class 'bool'>, )
Brightness (light:brightness, access: RW): 60 % (<class 'int'>, min: 1, max: 100, step: 1)
Power Off Delay Time (light:off-delay-time, access: RW): 1:47:00 (<class 'int'>, min: 0, max: 120, step: 1)
Changing settings
To change a setting, you need to provide the name of the setting (e.g., light:brightness in the example above):
Use miiocli genericmiot --help for more available commands.
Note, using this integration requires you to use the git version until version 0.6.0 is released.
Controlling older (miIO) devices
Older devices are mainly supported by their corresponding modules (e.g.,
roborockvacuum or fan).
The info command will output the command to use, if the device is supported.
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 try to detect the device model.
In some situations (e.g., if the device has no cloud connectivity) this information
may not be available, causing an error.
Defining the model manually allows to skip the model detection:
The miiocli tool has a --debug (-d) flag that can be used to enable debug logging.
You can repeat this multiple times (e.g., -dd) to increase the verbosity of the output.
You can find some solutions for the most common problems can be found in
Troubleshooting
section.
If you have any questions, feel free to create an issue or start a discussion on GitHub.
Alternatively, you can check our Matrix room.
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.status()
This will perform an info query to the device to detect the model,
and construct the corresponding device class for you.
Introspecting supported features
You can introspect device classes using the following methods:
sensors() to obtain information about sensors.
settings() to obtain information about available settings that can be changed.
actions() to return information about available device actions.
Each of these return device descriptor
objects,
which contain the necessary metadata about the available features to
allow constructing generic interfaces.
Note: some integrations may not have descriptors defined. Adding them is straightforward, so feel free to contribute!
Contributing
We welcome all sorts of contributions: from improvements
or fixing bugs to improving the documentation. We have prepared a short
guide
for getting you started.
Simulators
If you are a developer working on a project that communicates using the miIO/MIoT protocol,
or want to contribute to this project but do not have a specific device,
you can use the simulators provided by this project.
The miiocli tool ships with simple simulators for both miIO and MIoT that can be used to test your code.
Supported devices
While all MIoT devices are supported through the genericmiot
integration, this library supports also the following devices:
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 already supported ones.
Projects using this library
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.
Xiaomi Mi Robot Vacuum (vacuum)
Xiaomi Philips Light (light)
Xiaomi Mi Air Purifier and Air Humidifier (fan)
Xiaomi Smart WiFi Socket and Smart Power Strip (switch)
Xiaomi Universal IR Remote Controller (remote)
Xiaomi Mi Air Quality Monitor (PM2.5) (sensor)
Xiaomi Aqara Gateway Alarm (alarm_control_panel)
Xiaomi Mi WiFi Repeater 2 (device_tracker)
Home Assistant (custom)
Xiaomi Mi Home Air Conditioner Companion
Xiaomi Mi Smart Pedestal Fan
Xiaomi Mi Smart Rice Cooker
Xiaomi Raw Sensor
Xiaomi MIoT Devices
Xiaomi Miot Auto
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.
dustcloud (reverse engineering and rooting xiaomi devices)
Valetudo (cloud free vacuum firmware)
micloud (library to access xiaomi cloud services, can be used to obtain device tokens)
micloudfaker (dummy cloud server, can be used to fix powerstrip status requests when without internet access)
Xiaomi Cloud Tokens Extractor (an alternative way to fetch tokens from the cloud)
Yes — rytilahti/python-miio ships under the GPL-3.0 license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/rytilahti/python-miio.
What else is in the Backend space?
rytilahti/python-miio is tracked by TopGit under the Backend category, alongside 8 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What is rytilahti/python-miio?
rytilahti/python-miio (rytilahti/python-miio) is a Python project on GitHub. From the project's own README: Python library & console tool for controlling Xiaomi smart appliances
What license does rytilahti/python-miio use?
rytilahti/python-miio is released under the GPL-3.0 license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
Where can I see rytilahti/python-miio in action?
The project maintains a homepage at https://python-miio.readthedocs.io. The README tab on this page also usually contains screenshots and a quickstart.
Where do I read more about rytilahti/python-miio?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/rytilahti/python-miio is the definitive source.
Why is rytilahti/python-miio categorized under Backend?
TopGit places rytilahti/python-miio in the Backend category based on its GitHub topics and description (tagged: "home-assistant", "home-automation", "miio"). Categories are assigned from real repository metadata, not editorial guesswork.
Read full README in the tab above.
Still deciding about python-miio?
One click hands the question to an AI along with this page — see what it says about python-miio.
/python-miio
