vaillant netatmo api

Vaillant-Netatmo-Api

General

Biblioteca Python 3 para administrar termostatos vailant utilizando la API Netatmo. Proporciona mapeo uno a uno con la API Netatmo de Vaillant y ofrece una funcionalidad similar a la aplicación oficial VSMART/Erelax Vaillant.

Nota: Esta biblioteca todavía está en estado de prevenimiento y estará hasta V1.0.0. Puede haber cambios de ruptura en la API pública en cualquiera de las versiones V0.XY.

Instalación

La biblioteca se puede instalar simplemente usando PIP.

pip install vaillant-netatmo-api

La biblioteca requiere Python 3 y tiene dependencias de tenacidad y HTTPX.

Nota: HTTPX es actualmente un software de prevenimiento. La versión descrita en los requirements.txt debería funcionar correctamente, pero si hay algunos cambios de ruptura, verifique su rastreador de problemas de GitHub para cuestiones conocidas.

Uso

Obtener el token de la API OAuth

Todas las API de Netatmo están protegidas y requieren un token de portador para autenticarse. Para obtener este token, Netatmo ofrece una API OAuth.

Dado que Vaillant utiliza la subvención de credenciales de contraseña del propietario de los recursos, solo hay un método en la API AuthClient :

• async_token : conseguir un token de portador y almacenarlo en la tienda de tokens

 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 ,
    )

Acceder a la API del termostato

Hay tres API disponibles para el ThermostatClient , todos los cuales requieren el token de portador para la autenticación:

• async_get_thermostats_data : obtener todos los dispositivos asociados con la cuenta de usuario
• async_set_system_mode : cambio de modo de sistema para un dispositivo y módulo (es decir, verano, invierno o helado)
• async_set_minor_mode : cambio de modo menor para un dispositivo y módulo (es decir, modo manual, modo de distancia o modo de refuerzo de agua caliente)
• async_sync_schedule : actualización de datos de programación para un dispositivo y módulo
• async_switch_schedule : cambiar el horario activo para un dispositivo y 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 )

Uso de clientes como singletons

Aunque la biblioteca ofrece gerente de contexto para usar AuthClient y ThermostatClient , esto solo debe hacerse durante el desarrollo o en escenarios de uso muy poco frecuentes.

Ambos clientes usan httpx.AsyncClient como la biblioteca de comunicación HTTP subyacente, que implementa la agrupación de conexión y la reutilización de conexión. Esto significa que hacer múltiples solicitudes de concurentes debe realizarse utilizando la misma instancia del AuthClient o ThermostatClient , que no es posible mediante el uso de la API del Administrador de contexto, ya que esta API devolverá una nueva instancia del cliente cada vez que se llama auth_client o thermostat_client Method.

Para lograr un uso óptimo, que utilizará la agrupación de la conexión y la reutilización de la conexión, tanto AuthClient como ThermostatClient deben usarse instanciando a los clientes y proporcionando una instancia httpx.AsyncClient en un constructor. Este cliente proporcionado debe usarse como singleton, o con algún otro mecanismo de gestión del contexto, con el contexto más ancho que un bloque de código o una solicitud entrante.

Aquí hay un ejemplo de uso en el asistente de origen.

 # 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

Se deben usar ganchos similares que representan algún tipo de contexto de aplicación al integrar esta biblioteca en una aplicación diferente (frasco, django o similar).

Expresiones de gratitud

Esta biblioteca no existiría si no fuera por implementaciones anteriores mediante los siguientes proyectos:

• 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

Presentaron las bases explorando y documentando las API.

Renuncias

Esta biblioteca no está asociada con Vaillant o Netatmo de ninguna manera. Si Vaillant o Netatmo deciden cambiar cualquier cosa con la API, o bloquear el uso fuera de sus aplicaciones de primera fiesta, esta biblioteca dejará de funcionar.