From 867943efafa2f4eca5cc20dbe588e16b348079b1 Mon Sep 17 00:00:00 2001
From: Li Shuzhen <SusanPhevos@users.noreply.github.com>
Date: Fri, 19 Dec 2025 10:18:13 +0800
Subject: [PATCH] Created Missing Fan Mode of Climate Entity in HomeKit
 (markdown)

---
 ...g-Fan-Mode-of-Climate-Entity-in-HomeKit.md | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 Missing-Fan-Mode-of-Climate-Entity-in-HomeKit.md

diff --git a/Missing-Fan-Mode-of-Climate-Entity-in-HomeKit.md b/Missing-Fan-Mode-of-Climate-Entity-in-HomeKit.md
new file mode 100644
index 0000000..deb594c
--- /dev/null
+++ b/Missing-Fan-Mode-of-Climate-Entity-in-HomeKit.md
@@ -0,0 +1,46 @@
+## Problem Description
+
+After a climate entity is added to HomeKit, the list of available fan modes is incomplete. For example, the [xiaomi.airc.h39h00](http://poc.miot-spec.srv/miot-spec-v2/instance?type=urn:miot-spec-v2:device:air-conditioner:0000A004:xiaomi-h39h00:2) climate entity exposes nine fan modes (siid=3, piid=2) in Home Assistant, yet none of them appear in HomeKit.
+
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/296cad3c-9ad8-4c31-a89a-fb6cb8de25cc" alt="9 options">
+  <br>
+  <em>Figure 1: 9 options of fan mode in climate entity</em>
+</div>
+
+## Reason
+
+HomeKit accepts only the four fan modes "auto", "low", "medium", and "high", written entirely in lowercase. Any other mode is silently ignored.
+
+According to the [Home Assistant developer documentation](https://developers.home-assistant.io/docs/core/entity/climate/#fan-modes), custom fan modes are allowed in addition to the built-in ones. xiaomi_home generates fan mode names from the device’s fan-level property and translates them into the language configured by the user. If that language is not English, the resulting strings are almost never "auto", "low", "medium", or "high", so HomeKit omits them.
+
+## Solution
+
+The description translation can be customized in `xiaomi_home/miot/specs/multi_lang.json` in which you can change the translation of the fan-level property descriptions. For example, here is the code to change the fan mode options of xiaomi.airc.h39h00 in simplified Chinese and English. Insert the following block at line 2 and keep the trailing comma:
+
+```
+  "urn:miot-spec-v2:device:air-conditioner:0000A004:xiaomi-h39h00": {
+    "zh-Hans": {
+      "service:003:property:002:valuelist:000": "auto",
+      "service:003:property:002:valuelist:001": "low",
+      "service:003:property:002:valuelist:004": "medium",
+      "service:003:property:002:valuelist:008": "high"
+    },
+    "en": {
+      "service:003:property:002:valuelist:000": "auto",
+      "service:003:property:002:valuelist:001": "low",
+      "service:003:property:002:valuelist:004": "medium",
+      "service:003:property:002:valuelist:008": "high"
+    }
+  },
+```
+
+After modifying the file, you need to restart Home Assistant and check the option `xiaomi_home > CONFIGURE > Update entity conversion rules`. "auto", "low", "medium" and "high" is shown in the fan mode of the climate entity and they will appear in HomeKit.
+
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/deed1a33-addd-4509-8e84-7db02d85fcf8" alt="4 new options">
+  <br>
+  <em>Figure 2: auto, low, medium and high options are added into the fan mode</em>
+</div>
+
+More information about multi_lang.json can be found [here](https://github.com/XiaoMi/ha_xiaomi_home?tab=readme-ov-file#multiple-language-support).