python miio
0.5.12
Cette bibliothèque (et l'outil cli qui l'accompagne, miiocli ) peut être utilisée pour contrôler des appareils utilisant les protocoles miIO et MIoT de Xiaomi.
Il s'agit d'un effort volontaire mené par la communauté et n'est affilié à aucune des sociétés dont les appareils sont pris en charge par cette bibliothèque. Les rapports de problèmes et les demandes d'extraction sont les bienvenus, voir contribuer !
La documentation complète est disponible sur python-miio.readthedocs.io.
La version la plus récente peut être installée en utilisant pip :
pip install python-miio
Vous pouvez également installer la dernière version de développement depuis GitHub :
pip install git+https://github.com/rytilahti/python-miio.git
Ce projet fait actuellement l'objet d'un effort de refactorisation majeur. Si vous souhaitez contrôler les appareils modernes (MIoT), vous souhaitez utiliser la version git (ou les versions préliminaires, pip install --pre python-miio ) jusqu'à la sortie de la version 0.6.0.
La commande miiocli permet de contrôler les appareils pris en charge à partir de la ligne de commande, étant donné que vous connaissez leurs adresses IP et leurs jetons.
Le moyen le plus simple d'acquérir les jetons consiste à utiliser la commande miiocli cloud , qui les récupère pour vous depuis votre compte cloud à l'aide de 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
Vous pouvez également consulter la documentation pour connaître d'autres moyens de les obtenir.
Une fois que vous avez votre token, vous pouvez commencer à contrôler l'appareil. Tout d'abord, vous pouvez utiliser info pour obtenir des informations génériques à partir de n'importe quel appareil (même non pris en charge) :
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
Notez que le champ de commande qui vous donne la commande directe à utiliser pour contrôler l'appareil. Si le périphérique est pris en charge par l'intégration genericmiot comme indiqué dans le résultat, vous pouvez également utiliser miiocli genericmiot pour le contrôler.
Vous pouvez toujours utiliser --help pour obtenir plus d'informations sur les commandes, sous-commandes et leurs options disponibles.
La plupart des appareils modernes (MIoT) sont automatiquement pris en charge par l'intégration genericmiot . En interne, il utilise des fichiers (« miot spec ») pour connaître les fonctionnalités prises en charge, telles que les capteurs, les paramètres et les actions.
Ce fichier spécifique au modèle d'appareil sera téléchargé (et mis en cache localement) lorsque vous utiliserez l'intégration genericmiot pour la première fois.
Toutes les fonctionnalités des appareils pris en charge sont disponibles à l'aide des commandes communes status (pour afficher l'état de l'appareil), set (pour modifier les paramètres), actions pour répertorier les actions disponibles et call pour exécuter des actions.
L'exécution status affichera l'état actuel de l'appareil, ainsi que les valeurs acceptées pour les paramètres (marquées par 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)
Pour modifier un paramètre, vous devez fournir le nom du paramètre (par exemple, light:brightness dans l'exemple ci-dessus) :
miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 set light:brightness 0
[{'did': 'light:brightness', 'siid': 2, 'piid': 3, 'code': 0}]
La plupart des appareils proposeront également des 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
Ceux-ci peuvent être exécutés à l’aide de la commande call :
miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 call light:toggle
{'code': 0, 'out': []}
Utilisez miiocli genericmiot --help pour plus de commandes disponibles.
Notez que l'utilisation de cette intégration nécessite que vous utilisiez la version git jusqu'à la sortie de la version 0.6.0.
Les appareils plus anciens sont principalement pris en charge par leurs modules correspondants (par exemple, roborockvacuum ou fan ). La commande info affichera la commande à utiliser, si le périphérique est pris en charge.
Vous pouvez obtenir la liste des commandes disponibles pour un module donné en lui passant l'argument --help :
$ 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.
..
Chaque appel de commande tentera automatiquement de détecter le modèle de l'appareil. Dans certaines situations (par exemple, si l'appareil ne dispose pas de connectivité cloud), ces informations peuvent ne pas être disponibles, provoquant une erreur. Définir le modèle manuellement permet de sauter la détection du modèle :
miiocli roborockvacuum --model roborock.vacuum.s5 --ip <ip> --token <token> start
L'outil miiocli a un indicateur --debug ( -d ) qui peut être utilisé pour activer la journalisation du débogage. Vous pouvez répéter cette opération plusieurs fois (par exemple, -dd ) pour augmenter la verbosité de la sortie.
Vous pouvez trouver des solutions aux problèmes les plus courants dans la section Dépannage.
Si vous avez des questions, n'hésitez pas à créer un problème ou à démarrer une discussion sur GitHub. Alternativement, vous pouvez consulter notre salle Matrix.
Toutes les fonctionnalités de cette bibliothèque sont accessibles via le module miio . Bien que vous puissiez initialiser manuellement des classes d'intégration individuelles, le moyen le plus simple d'obtenir une instance de périphérique consiste à utiliser DeviceFactory :
from miio import DeviceFactory
dev = DeviceFactory.create("<ip address>", "<token>")
dev.status()
Cela effectuera une requête info sur l'appareil pour détecter le modèle et construira la classe d'appareil correspondante pour vous.
Vous pouvez introspecter les classes d’appareils à l’aide des méthodes suivantes :
sensors() pour obtenir des informations sur les capteurs.settings() pour obtenir des informations sur les paramètres disponibles qui peuvent être modifiés.actions() pour renvoyer des informations sur les actions disponibles sur l'appareil.Chacun de ces objets renvoie des objets descripteurs de périphérique, qui contiennent les métadonnées nécessaires sur les fonctionnalités disponibles pour permettre la construction d'interfaces génériques.
Remarque : certaines intégrations peuvent ne pas avoir de descripteurs définis. Les ajouter est simple, alors n'hésitez pas à contribuer !
Nous acceptons toutes sortes de contributions : des améliorations ou corrections de bugs à l'amélioration de la documentation. Nous avons préparé un petit guide pour vous aider à démarrer.
Si vous êtes un développeur travaillant sur un projet communiquant via le protocole miIO/MIoT, ou souhaitez contribuer à ce projet mais ne disposez pas d'un appareil spécifique, vous pouvez utiliser les simulateurs fournis par ce projet. L'outil miiocli est livré avec des simulateurs simples pour miIO et MIoT qui peuvent être utilisés pour tester votre code.
Bien que tous les appareils MIoT soient pris en charge via l'intégration genericmiot , cette bibliothèque prend également en charge les appareils suivants :
N'hésitez pas à créer une pull request pour ajouter la prise en charge de nouveaux appareils ainsi que des fonctionnalités supplémentaires pour ceux déjà pris en charge.
Si vous utilisez cette bibliothèque pour votre projet, n'hésitez pas à ouvrir un PR pour la répertorier ici !
Home Assistant utilise cette bibliothèque pour prendre en charge plusieurs plates-formes prêtes à l'emploi. Cette liste est incomplète car les plateformes (entre parenthèses) peuvent également prendre en charge d'autres appareils répertoriés ci-dessus.
Voici une liste d’autres projets autour de l’écosystème Xiaomi que vous pouvez trouver intéressants. N'hésitez pas à soumettre d'autres projets connexes.
