عن المشروع

يوفر هذا المستودع توثيقًا غير رسمي معكوس الهندسة لواجهة برمجة تطبيقات سحابة Hoval Connect IoT، إلى جانب تكامل مخصص مع Home Assistant قابل للتثبيت عبر HACS. وهو غير تابع لشركة Hoval ويُقدَّم كخلف للمشروع السابق الخاص ببوابة CAN-bus/MQTT؛ ولا يحتاج نهج السحابة إلى أي أجهزة إضافية، بل فقط إلى بيانات اعتماد حساب Hoval Connect. قدرات التكامل يتم التثبيت بإضافة المستودع كتكامل HACS مخصص، ثم إعادة تشغيل Home Assistant، ثم إدخال بريد Hoval Connect الإلكتروني وكلمة المرور. يتم اكتشاف المحطات والدوائر تلقائيًا. ويشدد ملف README على أن الإصدار 1.0.8 أو أحدث مطلوب، لأن بوابة تطبيقات Azure الخاصة بـ Hoval ترفض الطلبات التي يحتوي User-Agent الخاص بها على "homeassistant"؛ ولذلك يرسل التكامل معرّفه الخاص بدلًا من ذلك. ويُذكر أن الإصدارات الأقدم تفشل بخطأ HTTP 403 يشبه مشكلة في بيانات الاعتماد أو الشبكة. تشمل الكيانات المتاحة ما يلي: - كيان مروحة لكل دائرة تهوية HV: شريط تمرير سرعة مستمر من 0-100% مع إدخال مؤجل، ومفتاح تشغيل/إيقاف، ووضع تشغيل قابل للتهيئة (استئناف آخر برنامج أسبوعي تمت ملاحظته، أو تحديد week1/week2 صراحةً). - كيان مناخ لكل دائرة تدفئة HK: درجة الحرارة المستهدفة، ودرجة حرارة الغرفة الحالية، وأوضاع HVAC: Heat/Auto/Off، وإجراء HVAC الذي يعكس حالة الدائرة. - كيان سخان مياه لكل دائرة مياه ساخنة WW: درجة حرارة مستهدفة من 10-65 مئوية بخطوات 0.5 مئوية كتعزيز مؤقت ينتهي عند منتصف الليل، إضافة إلى وضعي تشغيل المضخة الحرارية والإيقاف. - اختيار برنامج لكل دائرة HV/HK/WW: week1، week2، الوضع الاقتصادي، الاستعداد، الثابت، مع عرض أسماء البرامج المعرفة من المستخدم وتمييز التكرارات. - كيانات مستشعرات مفلترة حسب نوع الدائرة، وتشمل درجات حرارة الخارج، والعادم، والتدفق، والغرفة، والخزان، والمخزن المؤقت، وحجم الهواء، والرطوبة، وCO2/VOC، وحالة التحكم، وساعات التشغيل، ودورات التبديل، والحرارة المنتجة، والطاقة المستهلكة، والتعديل، والقيم المرتبطة. - مستشعرات على مستوى المحطة لحالة الطقس، ودرجة الحرارة المتوقعة، وأحدث نوع/رسالة/طابع زمني للحدث، وعدد الأحداث النشطة. - مستشعرات ثنائية للحالة متصل/غير متصل، وحالة الخطأ، وحالة التغيير المؤقت لكل دائرة. - تصدير التشخيصات مع تنقيح تلقائي للرموز وبيانات الاعتماد ومعرفات المحطات. تشمل الخيارات وضع التشغيل، ومدة التجاوز المؤقت، وفاصل الاستطلاع (الافتراضي 60 ثانية). وهناك خدمة، hoval_connect.reset_temporary_change، تلغي تجاوزًا نشطًا على كيان مروحة أو مناخ أو سخان مياه. داخليًا، يستخدم التكامل إدارة رموز من خطوتين (رمز ID بالإضافة إلى Plant Access Token) مع تخزين مؤقت حسب TTL، وتحديث تلقائي، وقفل أحادي التنفيذ، ويتخطى الاستدعاءات عندما تكون المحطة غير متصلة، وينفذ عمليات جلب متوازية بعدد محدود من طلبات الدوائر قيد التنفيذ، ويسلسل أوامر التحكم لكل محطة ودائرة، ويطبق تخزينًا مؤقتًا متدرجًا للبرامج والأحداث والطقس. كما يدعم الاكتشاف الديناميكي للدوائر الجديدة دون إعادة تشغيل، ويوحّد الاستجابات المقسمة إلى صفحات. يتضمن المشروع Blueprint مرفقًا لـ Home Assistant ينفذ تعزيزًا صيفيًا اختياريًا يرفع HomeVent إلى 90% في فترات الظهيرة الدافئة عندما تتجاوز غرفة غير مكتبية حدًا مريحًا ويكون الهواء الخارجي معتدلًا وأبرد من الداخل، وينتهي وفق شروط قابلة للتهيئة. وتُضمَّن أمثلة مستقلة بلغة Python وBash/curl لقراءة القيم الحية والطقس والأحداث. تشمل القيود الموثقة دعم دوائر HV وHK وBL وWW وPS فقط (وليس الطاقة الشمسية أو المياه العذبة)، وعدم تحرير البرامج الزمنية، وعدم وجود سجل للطاقة أو درجة الحرارة، وعدم التحكم في وضع العطلات، وإدخال تهيئة واحد لكل حساب Hoval. والمتطلبات هي حساب Hoval Connect وHome Assistant 2024.11.0 أو أحدث. توثيق واجهة برمجة التطبيقات يوثق ملف README بنية السحابة (الجهاز إلى بوابة IoT إلى Azure IoT Hub إلى واجهة API الأساسية إلى التطبيق/التكامل)، وعناوين البنية التحتية، وتدفق مصادقة من خطوتين: منح كلمة مرور OAuth2 مقابل SAP Cloud Identity Services ينتج رمز ID (حوالي 30 دقيقة) يُستخدم كرمز Bearer، يليه استدعاء إعدادات المحطة الذي يعيد Plant Access Token (حوالي 15 دقيقة) يُرسل كـ X-Plant-Access-Token. ويسرد نقاط النهاية الخاصة بالتهيئة الأولية، وإعدادات المستخدم، والمحطات، والعقود، وإعدادات المحطة، والدوائر، والبرامج، والإعدادات، والتغييرات المؤقتة، ووضع العطلات، ونقاط نهاية الشركاء، مع أمثلة على حمولات JSON وملاحظات حول أنواع الدوائر (HK، BL، WW، FRIWA، HV، SOL، SOLB، PS، GW). ويسجل تغييرًا في واجهة API في أبريل 2026 يزيل نقاط نهاية الدوائر v1 لصالح v3 (وv4 للتغييرات المؤقتة)، ويصف نقاط نهاية التحكم التي تعيد HTTP 204، ويشير إلى نقاط النهاية الموثقة ولكن غير المختبَرة.