|Chat| |PyPI version| |PyPI downloads| |Build Status| |Coverage Status| |Docs| |Black|
This library (and its accompanying cli tool) can be used to interface with devices using Xiaomi's miIO <https://github.com/OpenMiHome/mihome-binary-protocol/blob/master/doc/PROTOCOL.md>__ and MIoT protocols.
If you already have a token for your device and the device type, you can directly start using miiocli tool.
If you don't have a token for your device, refer to Getting started <https://python-miio.readthedocs.io/en/latest/discovery.html>__ section of the manual <https://python-miio.readthedocs.io>__ for instructions how to obtain it.
The miiocli is the main way to execute commands from command line.
You can always use --help to get more information about the available commands.
For example, executing it without any extra arguments will 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>'}
Different devices are 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
All functionality is accessible through the miio module::
from miio import RoborockVacuum
vac = RoborockVacuum("<ip address>", "<token>")
vac.start()
Each separate device type inherits from miio.Device
(and in case of MIoT devices, miio.MiotDevice) which provides a common API.
Each command invocation will automatically detect (and cache) the device model necessary for some actions by querying the device. You can avoid this by specifying the model manually::
from miio import RoborockVacuum
vac = RoborockVacuum("<ip address>", "<token>", model="roborock.vacuum.s5")
Please refer to API documentation <https://python-miio.readthedocs.io/en/latest/api/miio.html>__ for more information.
You can find some solutions for the most common problems can be found in Troubleshooting <https://python-miio.readthedocs.io/en/latest/troubleshooting.html>__ section.
If you have any questions, or simply want to join up for a chat, check our Matrix room <https://matrix.to/#/#python-miio-chat:matrix.org>__.
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 <https://python-miio.readthedocs.io/en/latest/contributing.html>__ for getting you started.
python-yeelight <https://gitlab.com/stavros/python-yeelight/>__)Feel free to create a pull request to add support for new devices as well as additional features for supported devices.
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.
Xiaomi Mi Robot Vacuum <https://home-assistant.io/components/vacuum.xiaomi_miio/>__ (vacuum)Xiaomi Philips Light <https://home-assistant.io/components/light.xiaomi_miio/>__ (light)Xiaomi Mi Air Purifier and Air Humidifier <https://home-assistant.io/components/fan.xiaomi_miio/>__ (fan)Xiaomi Smart WiFi Socket and Smart Power Strip <https://home-assistant.io/components/switch.xiaomi_miio/>__ (switch)Xiaomi Universal IR Remote Controller <https://home-assistant.io/components/remote.xiaomi_miio/>__ (remote)Xiaomi Mi Air Quality Monitor (PM2.5) <https://home-assistant.io/components/sensor.xiaomi_miio/>__ (sensor)Xiaomi Aqara Gateway Alarm <https://home-assistant.io/components/alarm_control_panel.xiaomi_miio/>__ (alarm_control_panel)Xiaomi Mi WiFi Repeater 2 <https://www.home-assistant.io/components/device_tracker.xiaomi_miio/>__ (device_tracker)Home Assistant (custom) ^^^^^^^^^^^^^^^^^^^^^^^
Xiaomi Mi Home Air Conditioner Companion <https://github.com/syssi/xiaomi_airconditioningcompanion>__Xiaomi Mi Smart Pedestal Fan <https://github.com/syssi/xiaomi_fan>__Xiaomi Mi Smart Rice Cooker <https://github.com/syssi/xiaomi_cooker>__Xiaomi Raw Sensor <https://github.com/syssi/xiaomi_raw>__Xiaomi MIoT Devices <https://github.com/ha0y/xiaomi_miot_raw>__Xiaomi Miot Auto <https://github.com/al-one/hass-xiaomi-miot>__This is a list of other projects around the Xiaomi ecosystem that you can find interesting. Feel free to submit more related projects.
dustcloud <https://github.com/dgiese/dustcloud>__ (reverse engineering and rooting xiaomi devices)Valetudo <https://github.com/Hypfer/Valetudo>__ (cloud free vacuum firmware)micloud <https://github.com/Squachen/micloud>__ (library to access xiaomi cloud services, can be used to obtain device tokens)micloudfaker <https://github.com/unrelentingtech/micloudfaker>__ (dummy cloud server, can be used to fix powerstrip status requests when without internet access)Your project here? Feel free to open a PR! <https://github.com/rytilahti/python-miio/pulls>__.. |Chat| image:: https://img.shields.io/matrix/python-miio-chat:matrix.org :target: https://matrix.to/#/#python-miio-chat:matrix.org .. |PyPI version| image:: https://badge.fury.io/py/python-miio.svg :target: https://badge.fury.io/py/python-miio .. |PyPI downloads| image:: https://img.shields.io/pypi/dw/python-miio :target: https://pypi.org/project/python-miio/ .. |Build Status| image:: https://github.com/rytilahti/python-miio/actions/workflows/ci.yml/badge.svg :target: https://github.com/rytilahti/python-miio/actions/workflows/ci.yml .. |Coverage Status| image:: https://codecov.io/gh/rytilahti/python-miio/branch/master/graph/badge.svg?token=lYKWubxkLU :target: https://codecov.io/gh/rytilahti/python-miio .. |Docs| image:: https://readthedocs.org/projects/python-miio/badge/?version=latest :alt: Documentation status :target: https://python-miio.readthedocs.io/en/latest/?badge=latest .. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black
FAQs
Python library for interfacing with Xiaomi smart appliances
We found that python-miio demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.