vaillant netatmo api

Vaillant-Netatmo-Api

Общий

Библиотека Python 3 для управления термостатами Vaillant с использованием API Netatmo. Он обеспечивает отображение индивидуального API Vaillant Netatmo и предлагает аналогичные функции, как официальное приложение Vaillant VSMART/ERELAX.

Примечание. Эта библиотека все еще находится в статусе пререзелиза и будет до v1.0.0. В любой из версий V0.xy могут произойти нарушительные изменения.

Установка

Библиотека может быть просто установлена ​​с помощью PIP.

pip install vaillant-netatmo-api

Библиотека требует Python 3 и имеет упорство и зависимости HTTPX.

Примечание: HTTPX в настоящее время является программным обеспечением для предварительной линии. Версия, изложенная в requirements.txt

Использование

Получение токена от API OAuth

Все API Netatmo защищены и требуют проверки подлинности. Чтобы получить этот токен, Netatmo предлагает API OAuth.

Поскольку Vaillant использует грант «Учетные данные пароля владельца ресурса», в API AuthClient есть только один метод:

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

Доступ к API термостата

Для ThermostatClient доступно три API, которые требуют токена носителя для аутентификации:

• async_get_thermostats_data : Получение всех устройств, связанных с учетной записью пользователя
• async_set_system_mode : изменение системного режима для устройства и модуля (т.е. лето, зима или морозная охрана)
• async_set_minor_mode : изменение небольшого режима для устройства и модуля (т.е. ручной режим, режим вдали или режим Hot Water Boost)
• async_sync_schedule : обновление графика данных для устройства и модуля
• async_switch_schedule : изменение активного графика для устройства и модуля

 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 )

Использование клиентов в качестве одиноких

Несмотря на то, что библиотека предлагает диспетчер контекста для использования AuthClient и ThermostatClient , это должно быть сделано только во время разработки или в очень редких сценариях использования.

Оба клиента используют httpx.AsyncClient в качестве базовой библиотеки связи HTTP, которая реализует объединение соединений и повторное использование соединений. Это означает, что выполнение нескольких согласованных запросов следует выполнять с помощью одного и того же экземпляра AuthClient или ThermostatClient , что невозможно с помощью API Context Manager, поскольку этот API будет возвращать новый экземпляр клиента каждый раз, когда вызовется метод auth_client или thermostat_client .

Для достижения оптимального использования, в котором будет использоваться объединение соединений и повторное использование соединений, как AuthClient , так и ThermostatClient должны использоваться путем инстанции клиентов и предоставления httpx.AsyncClient в конструкторе. Это предоставило клиент, который должен использоваться в качестве синглтона или с некоторым другим механизмом управления контекстом, с контекстом, шире одного блока кода или одного входящего запроса.

Вот пример для использования в домашнем помощнике.

 # 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

Подобные крючки, которые представляют какой -то контекст приложения, следует использовать при интеграции этой библиотеки в другое приложение (Flask, Django или аналогичный).

Благодарности

Эта библиотека не существовала бы, если бы не предыдущие реализации следующими проектами:

• 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

Они изложили фонд, исследуя и документируя API.

Отказ от ответственности

Эта библиотека не связана с Вайлантом или Нетатмо каким -либо образом. Если либо Vaillant, либо Netatmo решит что -либо изменить с API или заблокировать использование за пределами своих первых приложений для вечеринок, эта библиотека перестанет работать.