vaillant netatmo api

Vaillant-netatmo-API

Umum

Perpustakaan Python 3 untuk Mengelola Termostat Vaillant Menggunakan API NetAtmo. Ini menyediakan pemetaan satu-ke-satu dengan Netatmo API Vaillant dan menawarkan fungsionalitas yang sama dengan aplikasi resmi Vaillant VSmart/erelax.

CATATAN: Perpustakaan ini masih dalam status pra -leel dan akan sampai v1.0.0. Mungkin ada perubahan perubahan pada API publik di salah satu versi V0.XY.

Instalasi

Perpustakaan dapat diinstal menggunakan PIP.

pip install vaillant-netatmo-api

Perpustakaan membutuhkan Python 3 dan memiliki ketergantungan keuletan dan httpx.

Catatan: HTTPX saat ini merupakan perangkat lunak prerelease. Versi yang diuraikan dalam requirements.txt harus berfungsi dengan baik, tetapi jika ada beberapa perubahan yang melanggar, silakan periksa pelacak masalah GitHub mereka untuk masalah yang diketahui.

Penggunaan

Mendapatkan token dari OAuth API

Semua API NetAtmo dilindungi dan membutuhkan token pembawa untuk mengotentikasi. Untuk mendapatkan token ini, NetAtmo menawarkan OAuth API.

Karena Vaillant menggunakan hibah kredensial kata sandi pemilik sumber daya, hanya ada satu metode di AuthClient API:

• async_token : mendapatkan token pembawa dan menyimpannya di toko 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 ,
    )

Mengakses API Thermostat

Ada tiga API yang tersedia untuk ThermostatClient , yang semuanya memerlukan token pembawa untuk otentikasi:

• async_get_thermostats_data : mendapatkan semua perangkat yang terkait dengan akun pengguna
• async_set_system_mode : Mengubah mode sistem untuk perangkat dan modul (mis. Musim panas, musim dingin atau frostguard)
• async_set_minor_mode : Mengubah mode minor untuk perangkat dan modul (mis. Mode manual, mode tandang atau mode penambah air panas)
• async_sync_schedule : Memperbarui data jadwal untuk perangkat dan modul
• async_switch_schedule : Mengubah jadwal aktif untuk perangkat dan modul

 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 )

Menggunakan klien sebagai singleton

Meskipun perpustakaan menawarkan Context Manager untuk menggunakan AuthClient dan ThermostatClient , ini hanya boleh dilakukan selama pengembangan atau dalam skenario penggunaan yang sangat jarang.

Kedua klien menggunakan httpx.AsyncClient sebagai perpustakaan komunikasi HTTP yang mendasarinya, yang mengimplementasikan pengumpulan koneksi dan penggunaan kembali koneksi. Ini berarti melakukan banyak permintaan konsuren harus dilakukan dengan menggunakan contoh yang sama dari AuthClient atau ThermostatClient , yang tidak dimungkinkan dengan menggunakan API Manajer Konteks karena API ini akan mengembalikan contoh baru klien setiap kali metode auth_client atau thermostat_client dipanggil.

Untuk mencapai penggunaan yang optimal, yang akan memanfaatkan pengumpulan koneksi dan penggunaan kembali koneksi, baik AuthClient dan ThermostatClient harus digunakan dengan membuat instantiasi klien dan memberikan instance httpx.AsyncClient dalam konstruktor. Ini disediakan klien harus digunakan sebagai singleton, atau dengan beberapa mekanisme manajemen konteks lainnya, dengan konteks yang lebih lebar dari satu blok kode atau satu permintaan masuk.

Berikut adalah contoh untuk penggunaan di rumah asisten.

 # 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

Kait serupa yang mewakili semacam konteks aplikasi harus digunakan saat mengintegrasikan pustaka ini ke dalam aplikasi yang berbeda (Flask, Django atau serupa).

Ucapan Terima Kasih

Perpustakaan ini tidak akan ada jika bukan karena implementasi sebelumnya oleh proyek -proyek berikut:

• 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

Mereka meletakkan fondasi dengan menjelajahi dan mendokumentasikan API.

Penafian

Perpustakaan ini tidak terkait dengan Vaillant atau NetAtmo dengan cara apa pun. Jika Vaillant atau NetAtmo memutuskan untuk mengubah apa pun dengan API, atau memblokir penggunaan di luar aplikasi partai pertama mereka, perpustakaan ini akan berhenti bekerja.