python miio
0.5.12
Diese Bibliothek (und das zugehörige CLI-Tool miiocli ) können zur Steuerung von Geräten mithilfe der miIO- und MIoT-Protokolle von Xiaomi verwendet werden.
Dies ist eine freiwillige, von der Community getragene Initiative und steht in keiner Verbindung zu einem der Unternehmen, deren Geräte von dieser Bibliothek unterstützt werden. Problemberichte und Pull-Requests sind willkommen, siehe Beitragen!
Die vollständige Dokumentation ist unter python-miio.readthedocs.io verfügbar.
Die neueste Version kann mit pip installiert werden:
pip install python-miio
Alternativ können Sie die neueste Entwicklungsversion von GitHub installieren:
pip install git+https://github.com/rytilahti/python-miio.git
Dieses Projekt wird derzeit umfassend umgestaltet. Wenn Sie an der Steuerung moderner (MIoT-)Geräte interessiert sind, möchten Sie die Git-Version (oder Vorabversionen, pip install --pre python-miio ) verwenden, bis Version 0.6.0 veröffentlicht wird.
Mit dem Befehl miiocli können Sie unterstützte Geräte über die Befehlszeile steuern, sofern Sie deren IP-Adressen und Token kennen.
Der einfachste Weg, die Tokens zu erwerben, ist die Verwendung des Befehls miiocli cloud , der sie mit micloud für Sie von Ihrem Cloud-Konto abruft:
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
Alternativ finden Sie in den Dokumenten weitere Möglichkeiten, diese zu erhalten.
Nachdem Sie Ihren Token erhalten haben, können Sie mit der Steuerung des Geräts beginnen. Erstens können Sie info verwenden, um einige allgemeine Informationen von jedem (auch noch nicht unterstützten) Gerät abzurufen:
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
Beachten Sie, dass das Befehlsfeld Ihnen den direkten Befehl zur Steuerung des Geräts gibt. Wenn das Gerät wie in der Ausgabe angegeben von der genericmiot Integration unterstützt wird, können Sie es auch mit miiocli genericmiot steuern.
Sie können jederzeit --help verwenden, um weitere Informationen zu verfügbaren Befehlen, Unterbefehlen und ihren Optionen zu erhalten.
Die meisten modernen (MIoT-)Geräte werden durch die genericmiot Integration automatisch unterstützt. Intern nutzt es Dateien („miot spec“), um sich über unterstützte Funktionen wie Sensoren, Einstellungen und Aktionen zu informieren.
Diese gerätemodellspezifische Datei wird heruntergeladen (und lokal zwischengespeichert), wenn Sie die genericmiot Integration zum ersten Mal verwenden.
Alle Funktionen unterstützter Geräte sind über die allgemeinen Befehle „ status “ (zum Anzeigen des Gerätestatus), set (zum Ändern der Einstellungen), actions zum Auflisten verfügbarer Aktionen und call zum Ausführen von Aktionen“ verfügbar.
Der status zeigt den aktuellen Gerätestatus sowie die akzeptierten Werte für Einstellungen an (markiert mit Zugriff 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)
Um eine Einstellung zu ändern, müssen Sie den Namen der Einstellung angeben (z. B. light:brightness im obigen Beispiel):
miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 set light:brightness 0
[{'did': 'light:brightness', 'siid': 2, 'piid': 3, 'code': 0}]
Die meisten Geräte bieten auch Aktionen an:
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
Diese können mit dem call ausgeführt werden:
miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 call light:toggle
{'code': 0, 'out': []}
Verwenden Sie miiocli genericmiot --help für weitere verfügbare Befehle.
Beachten Sie, dass Sie für die Verwendung dieser Integration die Git-Version verwenden müssen, bis Version 0.6.0 veröffentlicht wird.
Ältere Geräte werden hauptsächlich durch die entsprechenden Module (z. B. roborockvacuum oder fan ) unterstützt. Der Befehl info gibt den zu verwendenden Befehl aus, sofern das Gerät unterstützt wird.
Sie können die Liste der verfügbaren Befehle für ein bestimmtes Modul abrufen, indem Sie ihm das Argument --help übergeben:
$ 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.
..
Bei jedem Befehlsaufruf wird automatisch versucht, das Gerätemodell zu erkennen. In manchen Situationen (z. B. wenn das Gerät keine Cloud-Konnektivität hat) sind diese Informationen möglicherweise nicht verfügbar, was zu einem Fehler führt. Durch manuelles Definieren des Modells kann die Modellerkennung übersprungen werden:
miiocli roborockvacuum --model roborock.vacuum.s5 --ip <ip> --token <token> start
Das miiocli -Tool verfügt über das Flag --debug ( -d ), mit dem die Debug-Protokollierung aktiviert werden kann. Sie können dies mehrmals wiederholen (z. B. -dd ), um die Ausführlichkeit der Ausgabe zu erhöhen.
Einige Lösungen für die häufigsten Probleme finden Sie im Abschnitt „Fehlerbehebung“.
Wenn Sie Fragen haben, können Sie gerne ein Problem erstellen oder eine Diskussion auf GitHub starten. Alternativ können Sie sich auch unseren Matrix-Raum ansehen.
Alle Funktionalitäten dieser Bibliothek sind über das miio -Modul zugänglich. Während Sie einzelne Integrationsklassen manuell initialisieren können, ist die einfachste Möglichkeit, eine Geräteinstanz zu erhalten, die Verwendung DeviceFactory :
from miio import DeviceFactory
dev = DeviceFactory.create("<ip address>", "<token>")
dev.status()
Dadurch wird eine info an das Gerät durchgeführt, um das Modell zu erkennen und die entsprechende Geräteklasse für Sie zu erstellen.
Sie können Geräteklassen mit den folgenden Methoden überprüfen:
sensors() um Informationen über Sensoren zu erhalten.settings() um Informationen über verfügbare Einstellungen zu erhalten, die geändert werden können.actions() um Informationen über verfügbare Geräteaktionen zurückzugeben.Jedes dieser Gerätedeskriptorobjekte enthält die notwendigen Metadaten zu den verfügbaren Funktionen, um die Erstellung generischer Schnittstellen zu ermöglichen.
Hinweis: Für einige Integrationen sind möglicherweise keine Deskriptoren definiert. Das Hinzufügen ist unkompliziert, Sie können also gerne einen Beitrag leisten!
Wir freuen uns über alle Arten von Beiträgen: von Verbesserungen oder der Behebung von Fehlern bis hin zur Verbesserung der Dokumentation. Um Ihnen den Einstieg zu erleichtern, haben wir einen kurzen Leitfaden vorbereitet.
Wenn Sie als Entwickler an einem Projekt arbeiten, das über das miIO/MIoT-Protokoll kommuniziert, oder zu diesem Projekt beitragen möchten, aber kein bestimmtes Gerät haben, können Sie die von diesem Projekt bereitgestellten Simulatoren verwenden. Das miiocli Tool wird mit einfachen Simulatoren für miIO und MIoT geliefert, die zum Testen Ihres Codes verwendet werden können.
Während alle MIoT-Geräte durch die genericmiot Integration unterstützt werden, unterstützt diese Bibliothek auch die folgenden Geräte:
Erstellen Sie gerne eine Pull-Anfrage, um Unterstützung für neue Geräte sowie zusätzliche Funktionen für bereits unterstützte Geräte hinzuzufügen.
Wenn Sie diese Bibliothek für Ihr Projekt verwenden, können Sie gerne eine PR eröffnen, um sie hier aufzulisten!
Home Assistant nutzt diese Bibliothek, um mehrere Plattformen sofort zu unterstützen. Diese Liste ist unvollständig, da die Plattformen (in Klammern) möglicherweise auch andere oben aufgeführte Geräte unterstützen.
Dies ist eine Liste weiterer Projekte rund um das Xiaomi-Ökosystem, die Sie interessant finden können. Fühlen Sie sich frei, weitere verwandte Projekte einzureichen.
