প্রকল্প সম্পর্কে

এই রিপোজিটরিতে Hoval Connect IoT ক্লাউড API-এর আনঅফিসিয়াল, রিভার্স-ইঞ্জিনিয়ারড ডকুমেন্টেশন এবং HACS-এর মাধ্যমে ইনস্টলযোগ্য একটি Home Assistant কাস্টম ইন্টিগ্রেশন দেওয়া আছে। এটি Hoval-এর সাথে অধিভুক্ত নয় এবং আগের একটি CAN-bus/MQTT গেটওয়ে প্রকল্পের উত্তরসূরি হিসেবে উপস্থাপন করা হয়েছে; ক্লাউড পদ্ধতিতে অতিরিক্ত হার্ডওয়্যার লাগে না, শুধু Hoval Connect অ্যাকাউন্ট ক্রেডেনশিয়াল প্রয়োজন। ইন্টিগ্রেশনের সক্ষমতা একটি কাস্টম HACS ইন্টিগ্রেশন হিসেবে রিপোজিটরি যোগ করে, Home Assistant রিস্টার্ট করে এবং Hoval Connect ইমেইল ও পাসওয়ার্ড দিয়ে ইনস্টলেশন সম্পন্ন করা হয়। প্ল্যান্ট ও সার্কিট স্বয়ংক্রিয়ভাবে আবিষ্কৃত হয়। README-তে জোর দিয়ে বলা হয়েছে যে সংস্করণ 1.0.8 বা তার নতুন সংস্করণ প্রয়োজন, কারণ Hoval-এর Azure Application Gateway এমন অনুরোধ প্রত্যাখ্যান করে যার User-Agent-এ "homeassistant" থাকে; ইন্টিগ্রেশন তার বদলে নিজস্ব শনাক্তকারী পাঠায়। পুরোনো রিলিজ HTTP 403 দিয়ে ব্যর্থ হয় বলে জানা গেছে, যা দেখতে ক্রেডেনশিয়াল বা নেটওয়ার্ক সমস্যার মতো মনে হতে পারে। যেসব entity প্রকাশ করা হয়: - প্রতিটি HV ভেন্টিলেশন সার্কিটের জন্য Fan entity: ডিবাউন্সড ইনপুটসহ অবিচ্ছিন্ন 0-100% স্পিড স্লাইডার, on/off টগল এবং কনফিগারযোগ্য টার্ন-অন মোড (সর্বশেষ পর্যবেক্ষণ করা সপ্তাহের প্রোগ্রামে ফিরে যাওয়া, অথবা স্পষ্টভাবে week1/week2)। - প্রতিটি HK হিটিং সার্কিটের জন্য Climate entity: টার্গেট তাপমাত্রা, বর্তমান রুম তাপমাত্রা, Heat/Auto/Off HVAC মোড এবং সার্কিটের অবস্থা প্রতিফলিতকারী HVAC action। - প্রতিটি WW গরম পানির সার্কিটের জন্য Water heater entity: মিডনাইটে মেয়াদ শেষ হওয়া অস্থায়ী বুস্ট হিসেবে 0.5 C ধাপে 10-65 C টার্গেট তাপমাত্রা, সাথে heat-pump ও off অপারেশন মোড। - প্রতিটি HV/HK/WW সার্কিটের জন্য Program select: week1, week2, eco mode, standby, constant; ব্যবহারকারী-নির্ধারিত প্রোগ্রামের নাম দেখানো হয় এবং পুনরাবৃত্ত নামগুলোর পার্থক্য নির্ধারণ করা হয়। - সার্কিটের ধরন অনুযায়ী ফিল্টার করা Sensor entity: outside, exhaust, flow, room, tank ও buffer তাপমাত্রা, air volume, humidity, CO2/VOC, control status, operating hours, switching cycles, উৎপাদিত তাপ, ব্যয়িত শক্তি, modulation এবং সম্পর্কিত মান। - প্ল্যান্ট-স্তরের sensors: weather condition, forecast temperature, latest event type/message/timestamp এবং active event count। - প্রতিটি সার্কিটের জন্য online/offline, error status ও temporary-change state জানানোর Binary sensors। - টোকেন, ক্রেডেনশিয়াল ও প্ল্যান্ট ID স্বয়ংক্রিয়ভাবে redact করে diagnostics export। বিকল্পগুলোর মধ্যে রয়েছে টার্ন-অন মোড, অস্থায়ী override সময়কাল এবং polling interval (ডিফল্ট 60 s)। hoval_connect.reset_temporary_change নামে একটি service ফ্যান, climate বা water-heater entity-তে সক্রিয় override বাতিল করে। অভ্যন্তরীণভাবে ইন্টিগ্রেশন TTL ক্যাশিং, auto-refresh ও single-flight locking সহ দুই-ধাপের টোকেন ব্যবস্থাপনা (ID token এবং Plant Access Token) ব্যবহার করে; প্ল্যান্ট অফলাইনে থাকলে কল এড়িয়ে যায়, সীমিত সংখ্যক in-flight সার্কিট অনুরোধ রেখে সমান্তরাল fetch করে, প্রতিটি প্ল্যান্ট ও সার্কিটের জন্য কন্ট্রোল কমান্ড সিরিয়ালাইজ করে এবং প্রোগ্রাম, ইভেন্ট ও আবহাওয়ার জন্য tiered caching প্রয়োগ করে। এটি রিস্টার্ট ছাড়াই নতুন সার্কিটের গতিশীল আবিষ্কার সমর্থন করে এবং paginated response স্বাভাবিকীকৃত করে। একটি অন্তর্ভুক্ত Home Assistant Blueprint ঐচ্ছিক summer boost বাস্তবায়ন করে; উষ্ণ বিকেলে কোনো non-office রুমের তাপমাত্রা comfort threshold ছাড়িয়ে গেলে এবং বাইরের বাতাস মাঝারি ও ঘরের চেয়ে শীতল থাকলে এটি HomeVent-কে 90%-এ উন্নীত করে, এবং কনফিগারযোগ্য শর্তে শেষ হয়। লাইভ মান, আবহাওয়া ও ইভেন্ট পড়ার জন্য স্বতন্ত্র Python এবং Bash/curl উদাহরণ অন্তর্ভুক্ত রয়েছে। নথিভুক্ত সীমাবদ্ধতাগুলোর মধ্যে রয়েছে শুধুমাত্র HV, HK, BL, WW ও PS সার্কিটের জন্য সমর্থন (solar বা fresh-water নয়), time-program সম্পাদনা নেই, শক্তি বা তাপমাত্রার ইতিহাস নেই, holiday mode নিয়ন্ত্রণ নেই এবং প্রতি Hoval অ্যাকাউন্টে একটি config entry। প্রয়োজনীয়তা হলো একটি Hoval Connect অ্যাকাউন্ট এবং Home Assistant 2024.11.0 বা তার নতুন সংস্করণ। API ডকুমেন্টেশন README ক্লাউড আর্কিটেকচার (ডিভাইস থেকে IoT gateway, Azure IoT Hub, core API এবং app/integration), পরিকাঠামোর URL এবং দুই-ধাপের প্রমাণীকরণ প্রবাহের বর্ণনা দেয়: SAP Cloud Identity Services-এর বিরুদ্ধে OAuth2 password grant থেকে প্রায় 30 মিনিটের একটি ID token পাওয়া যায়, যা Bearer token হিসেবে ব্যবহৃত হয়; এরপর plant settings কল থেকে প্রায় 15 মিনিটের একটি Plant Access Token ফেরত আসে, যা X-Plant-Access-Token হিসেবে পাঠানো হয়। এতে bootstrap, user settings, plants, contracts, plant settings, circuits, programs, settings, temporary changes, holiday mode এবং partner endpoint-এর তালিকা, উদাহরণ JSON payload এবং সার্কিটের ধরন (HK, BL, WW, FRIWA, HV, SOL, SOLB, PS, GW) সম্পর্কে নোট রয়েছে। এতে 2026 সালের এপ্রিলের একটি API পরিবর্তনের তথ্য লিপিবদ্ধ আছে, যেখানে v1 circuit endpoint সরিয়ে v3 (এবং temporary changes-এর জন্য v4) ব্যবহার করা হয়েছে; কন্ট্রোল endpoint HTTP 204 ফেরত দেয় বলে বর্ণনা করা হয়েছে এবং কোন endpoint নথিভুক্ত কিন্তু পরীক্ষিত নয় তা উল্লেখ করা হয়েছে।