vaillant netatmo api

Vaillant-Netatmo-api

Em geral

Biblioteca Python 3 para gerenciar termostatos Vaillant usando a API NetATMO. Ele fornece um mapeamento individual com a API Netatmo da Vaillant e oferece funcionalidade semelhante à do aplicativo VAILLANT VSMART/ERELAX.

Nota: Esta biblioteca ainda está em um status de pré -lançamento e será até v1.0.0. Pode haver mudanças na API público em qualquer uma das versões v0.xy.

Instalação

A biblioteca pode ser simplesmente instalada usando PIP.

pip install vaillant-netatmo-api

A biblioteca requer Python 3 e possui dependências de tenacidade e httpx.

NOTA: Atualmente, o HTTPX é um software de pré -lançamento. A versão descrita nos requirements.txt deve estar funcionando corretamente, mas se houver algumas alterações de ruptura, verifique o rastreador de problemas do github para obter problemas conhecidos.

Uso

Recebendo o token da API OAuth

Todas as APIs do NetATMO estão protegidas e requerem um token do portador para autenticar. Para obter esse token, o Netatmo oferece uma API OAuth.

Como o Vaillant usa a concessão de credenciais de senha do proprietário do recurso, existe apenas um método na API AuthClient :

• async_token : Obter um token do portador e armazená -lo na loja de token

 from vaillant_netatmo_api import auth_client

CLIENT_ID = ""
CLIENT_SECRET = ""

def handle_token_update ( token ):
    token_string = token . serialize ()
    write_to_storage ( token_string )

async with auth_client ( CLIENT_ID , CLIENT_SECRET , handle_token_update ) as client :
    await client . async_token (
        username ,
        password ,
        user_prefix ,
        app_version ,
    )

Acessando a API do termostato

Existem três APIs disponíveis para o ThermostatClient , que exigem o token do portador para autenticação:

• async_get_thermostats_data : Obtendo todos os dispositivos associados à conta de usuário
• async_set_system_mode : Alterando o modo do sistema para um dispositivo e módulo (por exemplo, verão, inverno ou frostguard)
• async_set_minor_mode : Alterando o modo menor para um dispositivo e um módulo (por exemplo, modo manual, modo de distância ou modo de reforço de água quente)
• async_sync_schedule : Atualizando dados de programação para um dispositivo e módulo
• async_switch_schedule : alterando o cronograma ativo para um dispositivo e módulo

 from vaillant_netatmo_api import thermostat_client , SystemMode , Token

CLIENT_ID = ""
CLIENT_SECRET = ""

token_string = read_from_storage ()
token = Token . deserialize ( token_string )

def handle_token_update ( token ):
    token_string = token . serialize ()
    write_to_storage ( token_string )

async with thermostat_client ( CLIENT_ID , CLIENT_SECRET , token , handle_token_update ) as client :
    devices = await client . async_get_thermostats_data ()

    d_id = devices [ 0 ]. id
    m_id = devices [ 0 ]. modules [ 0 ]. id

    await client . async_set_system_mode ( d_id , m_id , SystemMode . WINTER )

Usando clientes como singletons

Embora a biblioteca ofereça gerente de contexto para o uso AuthClient e ThermostatClient , isso só deve ser feito durante o desenvolvimento ou em cenários de uso muito pouco frequentes.

Ambos os clientes usam httpx.AsyncClient como a biblioteca de comunicação HTTP subjacente, que implementa o pool de conexões e a reutilização da conexão. Isso significa que fazer várias solicitações concorrentes deve ser feita usando a mesma instância do AuthClient ou ThermostatClient , o que não é possível usando a API do contexto do Gerenciador, pois esta API retornará uma nova instância do cliente sempre que o método auth_client ou thermostat_client é chamado.

Para obter o uso ideal, que utilizará o pool de conexões e a reutilização de conexão, AuthClient e ThermostatClient devem ser usados ​​instantando os clientes e fornecendo a instância httpx.AsyncClient em um construtor. Este cliente fornecido deve ser usado como singleton, ou com algum outro mecanismo de gerenciamento de contexto, com o contexto mais largo que um bloco de código ou uma solicitação de entrada.

Aqui está um exemplo para uso no assistente doméstico.

 # When setting up integration with all the devices of one account, instantiate and store the client in a configuration memory store
async def async_setup_entry ( hass : HomeAssistant , entry : ConfigEntry ) -> bool :
    client = get_async_client ( hass )
    token_store = TokenStore (
        entry . data [ CONF_CLIENT_ID ],
        entry . data [ CONF_CLIENT_SECRET ],
        token ,
        handle_token_update ,
    )

    hass . data [ DOMAIN ][ entry . entry_id ] = ThermostatClient ( client , token_store )
    hass . config_entries . async_setup_platforms ( entry , PLATFORMS )

    return True

# When unloading the integration of this same account, read the client and close it manually
async def async_unload_entry ( hass : HomeAssistant , entry : ConfigEntry ) -> bool :
    unload_ok = await hass . config_entries . async_unload_platforms ( entry , PLATFORMS )
    if unload_ok :
        hass . data [ DOMAIN ]. pop ( entry . entry_id )

    return unload_ok

Ganchos semelhantes que representam algum tipo de contexto de aplicativo devem ser usados ​​ao integrar essa biblioteca em um aplicativo diferente (Flask, Django ou similar).

Agradecimentos

Esta biblioteca não existiria se não fosse para implementações anteriores pelos seguintes projetos:

• https://github.com/philippelt/netatmo-api-python
• https://github.com/jabesq/netatmo-api-python
• https://github.com/samueldumont/netatmo-api-python
• https://github.com/jabesq/pyatmo
• https://github.com/pjmaenh/pyvaillant

Eles estabeleceram a fundação explorando e documentando as APIs.

Isenções de responsabilidade

Esta biblioteca não está associada a Vaillant ou Netatmo de forma alguma. Se Vaillant ou Netatmo decidirem alterar qualquer coisa com a API ou bloquear o uso fora de seus aplicativos de primeira parte, essa biblioteca deixará de funcionar.