vaillant netatmo api

Vaillant-Netatmo-Api

ทั่วไป

Library Python 3 สำหรับการจัดการเทอร์โมสทัท Vaillant โดยใช้ Netatmo API มันมีการทำแผนที่แบบหนึ่งต่อหนึ่งกับ Netatmo API ของ Vaillant และเสนอฟังก์ชั่นที่คล้ายกันกับแอพ Vaillant VSMART/ERELAX อย่างเป็นทางการ

หมายเหตุ: ไลบรารีนี้ยังคงอยู่ในสถานะ preerlease และจะเป็นจนถึง v1.0.0 อาจมีการเปลี่ยนแปลงการเปลี่ยนแปลงของ API สาธารณะในเวอร์ชัน V0.xy ใด ๆ

การติดตั้ง

ห้องสมุดสามารถติดตั้งได้ง่ายๆโดยใช้ PIP

pip install vaillant-netatmo-api

ห้องสมุดต้องใช้ Python 3 และมีความดื้อรั้นและการพึ่งพา HTTPX

หมายเหตุ: HTTPX ปัจจุบันเป็นซอฟต์แวร์ PreRelease เวอร์ชันที่ระบุไว้ใน requirements.txt ควรทำงานอย่างถูกต้อง แต่หากมีการเปลี่ยนแปลงบางอย่างโปรดตรวจสอบตัวติดตามปัญหา GitHub ของพวกเขาสำหรับปัญหาที่ทราบ

การใช้งาน

รับโทเค็นจาก OAuth API

Netatmo APIs ทั้งหมดได้รับการปกป้องและต้องการโทเค็นผู้ถือเพื่อตรวจสอบสิทธิ์ เพื่อให้ได้โทเค็นนี้ Netatmo เสนอ OAuth API

เนื่องจาก Vaillant ใช้ข้อมูลรับรองรหัสผ่านของเจ้าของทรัพยากรจึงมีเพียงวิธีเดียวใน AuthClient API:

• 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

มี API สามตัวสำหรับ ThermostatClient ซึ่งทั้งหมดนี้ต้องการโทเค็นผู้ถือสำหรับการตรวจสอบ:

• async_get_thermostats_data : รับอุปกรณ์ทั้งหมดที่เกี่ยวข้องกับบัญชีผู้ใช้
• async_set_system_mode : การเปลี่ยนโหมดระบบสำหรับอุปกรณ์และโมดูล (เช่นฤดูร้อนฤดูหนาวหรืออาการบวมเป็นฟอง)
• async_set_minor_mode : การเปลี่ยนโหมดรองสำหรับอุปกรณ์และโมดูล (เช่นโหมดแมนนวลโหมดออกไปหรือโหมดเพิ่มน้ำร้อน)
• 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 ของ Manager Contement เนื่องจาก API นี้จะส่งคืนอินสแตนซ์ใหม่ของไคลเอนต์ทุกครั้งที่ auth_client หรือ thermostat_client เรียก

เพื่อให้ได้การใช้งานที่ดีที่สุดซึ่งจะใช้การเชื่อมต่อการรวมการเชื่อมต่อและนำการเชื่อมต่อกลับมาใช้ใหม่ทั้ง AuthClient และ ThermostatClient ควรใช้โดยการสร้างอินสแตนซ์ httpx.AsyncClient ในคอนสตรัคเตอร์ สิ่งนี้ให้ลูกค้าควรใช้เป็นซิงเกิลตันหรือกับกลไกการจัดการบริบทอื่น ๆ โดยมีบริบทกว้างกว่าหนึ่งบล็อกของรหัสหรือคำขอขาเข้าหนึ่ง

นี่คือตัวอย่างสำหรับการใช้งานใน Home Assistant

 # 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 แต่อย่างใด หาก Vaillant หรือ Netatmo ตัดสินใจเปลี่ยนสิ่งใดด้วย API หรือบล็อกการใช้งานนอกแอพปาร์ตี้แรกของพวกเขาห้องสมุดนี้จะหยุดทำงาน