python miio
0.5.12
Esta biblioteca (e sua ferramenta cli que a acompanha, miiocli ) pode ser usada para controlar dispositivos usando os protocolos miIO e MIoT da Xiaomi.
Este é um esforço voluntário e conduzido pela comunidade e não é afiliado a nenhuma das empresas cujos dispositivos são suportados por esta biblioteca. Relatórios de problemas e solicitações pull são bem-vindos, consulte contribuir!
A documentação completa está disponível em python-miio.readthedocs.io.
A versão mais recente pode ser instalada usando pip :
pip install python-miio
Alternativamente, você pode instalar a versão de desenvolvimento mais recente do GitHub:
pip install git+https://github.com/rytilahti/python-miio.git
Este projeto está atualmente em andamento em um grande esforço de refatoração. Se você estiver interessado em controlar dispositivos modernos (MIoT), você deseja usar a versão git (ou pré-lançamentos, pip install --pre python-miio ) até que a versão 0.6.0 seja lançada.
O comando miiocli permite controlar dispositivos suportados a partir da linha de comando, desde que você conheça seus endereços IP e tokens.
A maneira mais simples de adquirir os tokens é usando o comando miiocli cloud , que os busca na sua conta na nuvem usando o 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
Alternativamente, consulte a documentação para outras maneiras de obtê-los.
Depois de receber seu token, você pode começar a controlar o dispositivo. Primeiro, você pode usar info para obter algumas informações genéricas de qualquer dispositivo (mesmo ainda sem suporte):
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
Observe o campo de comando que fornece o comando direto a ser usado para controlar o dispositivo. Se o dispositivo for compatível com a integração genericmiot conforme indicado na saída, você também poderá usar miiocli genericmiot para controlá-lo.
Você sempre pode usar --help para obter mais informações sobre comandos, subcomandos disponíveis e suas opções.
A maioria dos dispositivos modernos (MIoT) são automaticamente suportados pela integração genericmiot . Internamente, ele usa arquivos ("miot spec") para descobrir os recursos suportados, como sensores, configurações e ações.
Este arquivo específico do modelo do dispositivo será baixado (e armazenado em cache localmente) quando você usar a integração genericmiot pela primeira vez.
Todos os recursos dos dispositivos suportados estão disponíveis usando os comandos comuns status (para mostrar o estado do dispositivo), set (para alterar as configurações), actions para listar as ações disponíveis e call para executar ações.
A execução do status mostrará o estado atual do dispositivo e também os valores aceitos para configurações (marcados com acesso 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)
Para alterar uma configuração, você precisa fornecer o nome da configuração (por exemplo, light:brightness no exemplo acima):
miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 set light:brightness 0
[{'did': 'light:brightness', 'siid': 2, 'piid': 3, 'code': 0}]
A maioria dos dispositivos também oferece ações:
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
Eles podem ser executados usando o comando call :
miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 call light:toggle
{'code': 0, 'out': []}
Use miiocli genericmiot --help para obter mais comandos disponíveis.
Observe que o uso dessa integração requer que você use a versão git até o lançamento da versão 0.6.0.
Dispositivos mais antigos são suportados principalmente por seus módulos correspondentes (por exemplo, roborockvacuum ou fan ). O comando info produzirá o comando a ser usado, se o dispositivo for compatível.
Você pode obter a lista de comandos disponíveis para qualquer módulo passando o argumento --help para ele:
$ 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.
..
Cada chamada de comando tentará detectar automaticamente o modelo do dispositivo. Em algumas situações (por exemplo, se o dispositivo não tiver conectividade com a nuvem) esta informação pode não estar disponível, causando um erro. Definir o modelo manualmente permite pular a detecção do modelo:
miiocli roborockvacuum --model roborock.vacuum.s5 --ip <ip> --token <token> start
A ferramenta miiocli possui um sinalizador --debug ( -d ) que pode ser usado para ativar o log de depuração. Você pode repetir isso várias vezes (por exemplo, -dd ) para aumentar o detalhamento da saída.
Você pode encontrar algumas soluções para os problemas mais comuns na seção Solução de problemas.
Se você tiver alguma dúvida, sinta-se à vontade para criar um problema ou iniciar uma discussão no GitHub. Alternativamente, você pode conferir nossa sala Matrix.
Todas as funcionalidades desta biblioteca são acessíveis através do módulo miio . Embora você possa inicializar classes de integração individuais manualmente, a maneira mais simples de obter uma instância de dispositivo é usar DeviceFactory :
from miio import DeviceFactory
dev = DeviceFactory.create("<ip address>", "<token>")
dev.status()
Isso executará uma consulta info ao dispositivo para detectar o modelo e construirá a classe de dispositivo correspondente para você.
Você pode examinar classes de dispositivos usando os seguintes métodos:
sensors() para obter informações sobre sensores.settings() para obter informações sobre as configurações disponíveis que podem ser alteradas.actions() para retornar informações sobre as ações disponíveis do dispositivo.Cada um desses retorna objetos descritores de dispositivos, que contêm os metadados necessários sobre os recursos disponíveis para permitir a construção de interfaces genéricas.
Nota: algumas integrações podem não ter descritores definidos. Adicioná-los é simples, então fique à vontade para contribuir!
Aceitamos todos os tipos de contribuições: desde melhorias ou correção de bugs até melhorias na documentação. Preparamos um breve guia para você começar.
Se você é um desenvolvedor trabalhando em um projeto que se comunica utilizando o protocolo miIO/MIoT, ou deseja contribuir com este projeto mas não possui um dispositivo específico, você pode utilizar os simuladores disponibilizados por este projeto. A ferramenta miiocli vem com simuladores simples para miIO e MIoT que podem ser usados para testar seu código.
Embora todos os dispositivos MIoT sejam suportados através da integração genericmiot , esta biblioteca também suporta os seguintes dispositivos:
Sinta-se à vontade para criar uma solicitação pull para adicionar suporte para novos dispositivos, bem como recursos adicionais para os já suportados.
Se você estiver usando esta biblioteca para o seu projeto, sinta-se à vontade para abrir um PR para listá-la aqui!
O Home Assistant usa esta biblioteca para oferecer suporte a várias plataformas prontas para uso. Esta lista está incompleta porque as plataformas (entre parênteses) também podem suportar outros dispositivos listados acima.
Esta é uma lista de outros projetos em torno do ecossistema Xiaomi que você pode achar interessantes. Sinta-se à vontade para enviar mais projetos relacionados.
