Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve docs on token acquisition and cleanup legacy methods #1757

Merged
merged 2 commits into from
Mar 8, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,20 @@ 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](https://github.com/Squachen/micloud/).
Alternatively, see [the docs](https://python-miio.readthedocs.io/en/latest/legacy_token_extraction.html#legacy-token-extraction)
which fetches them for you from your cloud account using [micloud](https://github.com/Squachen/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](https://python-miio.readthedocs.io/en/latest/discovery.html#obtaining-tokens)
for other ways to obtain them.

After you have your token, you can start controlling the device.
Expand Down Expand Up @@ -325,4 +337,5 @@ can find interesting. Feel free to submit more related projects.
* [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)
* [Xiaomi Cloud Tokens Extractor](https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor) (an alternative way to fetch tokens from the cloud)
* [Your project here? Feel free to open a PR!](https://github.com/rytilahti/python-miio/pulls)
2 changes: 1 addition & 1 deletion docs/device_docs/vacuum.rst
Original file line number Diff line number Diff line change
Expand Up @@ -310,4 +310,4 @@ so it is also possible to pass dicts.
:prog: mirobo
:show-nested:

:py:class:`API <miio.integrations.roborocok.vacuum>`
:py:class:`API <miio.integrations.roborock.vacuum>`
7 changes: 6 additions & 1 deletion docs/discovery.rst
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,12 @@ as well as the server locale to use for fetching the tokens.

miiocli cloud list

:ref:`Alternatively, see our documentation for other ways to obtain the tokens<legacy_token_extraction>`.
Username: example@example.com
Password:
Locale (all, cn, de, i2, ru, sg, us): all


Alternatively, you can try one of the :ref:`legacy ways to obtain the tokens<legacy_token_extraction>`.

You can also access this functionality programatically using :class:`miio.cloud.CloudInterface`.

Expand Down
65 changes: 21 additions & 44 deletions docs/legacy_token_extraction.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
:orphan:


.. _legacy_token_extraction:

Legacy methods for obtaining tokens
Expand All @@ -8,15 +9,10 @@ Legacy methods for obtaining tokens
This page describes several ways to extract device tokens,
both with and without cloud access.

.. _cloud_tokens:

Tokens from Mi Home Cloud
=========================

The fastest way to obtain tokens is to use the
[cloud tokens extractor](https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor) by Piotr Machowski.
Check out his repository for detailed instructions on installation and execution.
.. note::

You generally want to use the :ref:`miiocli cloud command <obtaining_tokens>` to obtain tokens.
These methods are listed here just for historical reference and may not work anymore.

.. _logged_tokens:

Expand Down Expand Up @@ -50,8 +46,8 @@ or database from the Mi Home app.
The procedure is briefly described below,
but you may find the following links also useful:

- https://github.com/jghaanstra/com.xiaomi-miio/blob/master/docs/obtain_token.md
- https://github.com/homeassistantchina/custom_components/blob/master/doc/chuang_mi_ir_remote.md
* https://github.com/jghaanstra/com.xiaomi-miio/blob/master/docs/obtain_token.md
* https://github.com/homeassistantchina/custom_components/blob/master/doc/chuang_mi_ir_remote.md

Android
~~~~~~~
Expand Down Expand Up @@ -109,24 +105,24 @@ Apple
Create a new unencrypted iOS backup to your computer.
To do that you've to follow these steps:

- Connect your iOS device to the computer
- Open iTunes
- Click on your iOS device (sidebar left or icon on top navigation bar)
- In the Summary view check the following settings
- Automatically Back Up: ``This Computer``
- **Disable** ``Encrypt iPhone backup``
- Click ``Back Up Now``
#. Connect your iOS device to the computer
#. Open iTunes
#. Click on your iOS device (sidebar left or icon on top navigation bar)
#. In the Summary view check the following settings
* Automatically Back Up: ``This Computer``
* **Disable** ``Encrypt iPhone backup``
#. Click ``Back Up Now``

When the backup is finished, download `iBackup Viewer <https://www.imactools.com/iphonebackupviewer/>`_ and follow these steps:

- Open iBackup Viewer
- Click on your newly created backup
- Click on the ``Raw Files`` icon (looks like a file tree)
- On the left column, search for ``AppDomain-com.xiaomi.mihome`` and select it
- Click on the search icon in the header
- Enter ``_mihome`` in the search field
- Select the ``Documents/0123456789_mihome.sqlite`` file (the one with the number prefixed)
- Click ``Export -> Selected…`` in the header and store the file
#. Open iBackup Viewer
#. Click on your newly created backup
#. Click on the ``Raw Files`` icon (looks like a file tree)
#. On the left column, search for ``AppDomain-com.xiaomi.mihome`` and select it
#. Click on the search icon in the header
#. Enter ``_mihome`` in the search field
#. Select the ``Documents/0123456789_mihome.sqlite`` file (the one with the number prefixed)
#. Click ``Export -> Selected…`` in the header and store the file

Now you've exported the SQLite database to your Mac and you can extract the tokens.

Expand All @@ -149,34 +145,17 @@ Encrypted tokens as `recently introduced on iOS devices <https://github.com/ryti
For decrypting Android backups the password has to be provided
to the tool with ``--password <password>``.

*Please feel free to submit pull requests to simplify this procedure!*

.. code-block:: bash

$ miio-extract-tokens backup.ab
Opened backup/backup.ab
Extracting to /tmp/tmpvbregact
Reading tokens from Android DB
Gateway
Model: lumi.gateway.v3
IP address: 192.168.XXX.XXX
Token: 91c52a27eff00b954XXX
MAC: 28:6C:07:XX:XX:XX
room1
Model: yeelink.light.color1
IP address: 192.168.XXX.XXX
Token: 4679442a069f09883XXX
MAC: F0:B4:29:XX:XX:XX
room2
Model: yeelink.light.color1
IP address: 192.168.XXX.XXX
Token: 7433ab14222af5792XXX
MAC: 28:6C:07:XX:XX:XX
Flower Care
Model: hhcc.plantmonitor.v1
IP address: 134.XXX.XXX.XXX
Token: 124f90d87b4b90673XXX
MAC: C4:7C:8D:XX:XX:XX
Mi Robot Vacuum
Model: rockrobo.vacuum.v1
IP address: 192.168.XXX.XXX
Expand Down Expand Up @@ -213,5 +192,3 @@ Tokens from rooted device
=========================

If a device is rooted via `dustcloud <https://github.com/dgiese/dustcloud>`_ (e.g. for running the cloud-free control webinterface `Valetudo <https://valetudo.cloud/>`_), the token can be extracted by connecting to the device via SSH and reading the file: :code:`printf $(cat /mnt/data/miio/device.token) | xxd -p`

See also `"How can I get the token from the robots FileSystem?" in the FAQ for Valetudo <https://valetudo.cloud/pages/faq.html#how-can-i-get-the-token-from-the-robots-filesystem>`_.
2 changes: 1 addition & 1 deletion miio/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
from miio.integrations.dmaker.airfresh import AirFreshA1, AirFreshT2017
from miio.integrations.dmaker.fan import Fan1C, FanMiot, FanP5
from miio.integrations.dreame.vacuum import DreameVacuum
from miio.integrations.genericmiot import GenericMiot
from miio.integrations.genericmiot.genericmiot import GenericMiot
from miio.integrations.huayi.light import (
Huizuo,
HuizuoLampFan,
Expand Down
2 changes: 1 addition & 1 deletion miio/cloud.py
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ def get_devices(self, locale: Optional[str] = None) -> Dict[str, CloudDeviceInfo

@click.group(invoke_without_command=True)
@click.option("--username", prompt=True)
@click.option("--password", prompt=True)
@click.option("--password", prompt=True, hide_input=True)
@click.pass_context
def cloud(ctx: click.Context, username, password):
"""Cloud commands."""
Expand Down
2 changes: 1 addition & 1 deletion miio/descriptors.py
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ class PropertyDescriptor(Descriptor):
access information what types of data is available to display to users.

Prefer :meth:`@sensor <miio.devicestatus.sensor>` or
:meth:`@setting <miio.devicestatus.setting>`for constructing these.
:meth:`@setting <miio.devicestatus.setting>` for constructing these.
"""

#: The name of the property to use to access the value from a status container.
Expand Down
2 changes: 1 addition & 1 deletion miio/devicefactory.py
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ def create(
"""
dev: Device
if force_generic_miot: # TODO: find a better way to handle this.
from .integrations.genericmiot import GenericMiot
from .integrations.genericmiot.genericmiot import GenericMiot

dev = GenericMiot(host, token, model=model)
dev.info()
Expand Down
3 changes: 0 additions & 3 deletions miio/integrations/genericmiot/__init__.py
Original file line number Diff line number Diff line change
@@ -1,3 +0,0 @@
from .genericmiot import GenericMiot

__all__ = ["GenericMiot"]
2 changes: 1 addition & 1 deletion miio/tests/test_miotdevice.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
import pytest

from miio import Huizuo, MiotDevice
from miio.integrations.genericmiot import GenericMiot
from miio.integrations.genericmiot.genericmiot import GenericMiot
from miio.miot_device import MiotValueType, _filter_request_fields

MIOT_DEVICES = MiotDevice.__subclasses__()
Expand Down