search

rytilahti / python-miio

Python library & console tool for controlling Xiaomi smart appliances
https://python-miio.readthedocs.io
GNU General Public License v3.0
3.77k stars 563 forks source link
home-assistant home-automation miio miot miot-spec python smart-home xiaomi

readme

python-miio

Chat PyPI version PyPI downloads Build Status Coverage Status Documentation status

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

The most recent release can be installed using pip:

pip install python-miio

Alternatively, you can install the latest development version from GitHub:

pip install git+https://github.com/rytilahti/python-miio.git

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: example@example.com
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:

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

Model: rockrobo.vacuum.v1
Hardware version: MW300
Firmware version: 1.2.4_16
Supported using: RoborockVacuum
Command: miiocli roborockvacuum --ip 127.0.0.1 --token 00000000000000000000000000000000
Supported by genericmiot: True

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):

 miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 set light:brightness 0

 [{'did': 'light:brightness', 'siid': 2, 'piid': 3, 'code': 0}]

Using actions

Most devices will also offer actions:

miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 actions

Light (light)
        light:toggle            Toggle
        light:brightness-down   Brightness Down
        light:brightness-up     Brightness Up

These can be executed using the call command:

miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 call light:toggle

{'code': 0, 'out': []}

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:

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

Troubleshooting

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:

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:

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.

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.