Home

AIFA Smart 整合研究筆記

這份 wiki 記錄 PinLin/aifa-smart-homeassistant 整合背後的逆向研究、設計決策、實機驗證結果。

整合本身只專注於 AIFA i-Ctrl AC（Classic 機型 / 冷氣專用）的控制。其他 AIFA 設備類型（i-Ctrl 通用 IR hub、i-Ctrl AC Plus、i-Ctrl Pro Plus）目前不在 scope 內。

整合做了什麼

• 用 AIFA Smart 帳號登入 AIFA cloud
• 從 cloud 拉 hub + sub-device + saved function/macro 列表
• 用整合送 AC 結構化命令（fea0...f0 packet）給 hub 控制冷氣
• 透過 hub 的長連 TLS broadcast 讀回 AC 觀察狀態（mode / target temp）
• 把這些變成 HA 的 climate / switch / sensor / binary_sensor / button 實體

本 wiki 怎麼讀

新使用者建議路線：

1. Architecture / Cloud REST API — AIFA cloud 33 個 endpoint 全景
2. Architecture / Cloud TLS Relay — App / 整合跟 cloud 之間的長連 TLS（控制 hub + 收 hub broadcast）
3. Architecture / Classic vs Plus — 兩代協定的差別
4. IR Protocol — fea0...f0 結構化 packet schema + BCD 編碼

研究跟驗證細節：

5. Empirical Findings — 拔電 / 拔網路 / Plus / turbo/PS bit 等實機驗證結果
6. Decisions Log — 哪些功能砍了、為什麼

待做：

7. Open Test Plans — 等實機跑的測試（Plus 5 位碼路徑）

維護者 runbook：

8. Regen AC Catalog — 從 Firebase RC 重新產生 ac_catalog.py 的步驟

關鍵環境資訊

AIFA app package	tw.com.aifa.ictrl_pro
AIFA app version studied	1.2.5
Cloud API base	https://api.aifaremote.com
Cloud TLS relay	aifaremote.com:8751
Hub model studied	i-Ctrl AC (Classic, firmware v4)
Reference sub-device	Daikin AC, deviceCode=11, sub_device_id=31867
OAuth client_id	Ecp5TUQxtOjdQ24u

對整合的限制要設定的期望

• integration scope 只到 i-Ctrl AC（Classic 機型） — Plus 線（i-Ctrl AC Plus / i-Ctrl Pro Plus）走完全不同的 TLS 協定，沒支援。詳見 Architecture / Classic vs Plus。
• 整合不替你 sync cloud → hub — 如果 hub 離線時你在 AIFA app 改 code，整合活著的時候不會幫你補 set-code。詳見 Decisions Log「為什麼不做 auto-sync」段。