diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 1fca160..4be50f8 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -5,8 +5,8 @@ body: attributes: label: Describe the Bug / 描述问题 description: | - > A clear and concise description of what the bug is. - > 清晰且简明地描述问题。 + > A clear and concise description of what the bug is. Please include the device model information (Like xiaomi.gateway.hub1 which can be found in Device info page). + > 清晰且简明地描述问题。请注明设备 model 信息(例如 xiaomi.gateway.hub1,可在设备详情页查询)。 validations: required: true diff --git a/CHANGELOG.md b/CHANGELOG.md index 9af7631..f60eb14 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,69 @@ # CHANGELOG +## v0.4.6 +### Added +- Add tv-box device as the media player entity. [#1562](https://github.com/XiaoMi/ha_xiaomi_home/pull/1562) +- Set play-control service's play-loop-mode property as the sound mode. [#1562](https://github.com/XiaoMi/ha_xiaomi_home/pull/1562) +### Changed +- Use constant value to indicate the cloud MQTT broker host domain. [#1530](https://github.com/XiaoMi/ha_xiaomi_home/pull/1530) +- Use constant value to indicate the timer delay of refreshing devices. [#1555](https://github.com/XiaoMi/ha_xiaomi_home/pull/1555) +- Set the playing-state property as the required property in the play-control service of the speaker device. [#1552](https://github.com/XiaoMi/ha_xiaomi_home/pull/1552) +- Set the playing-state property as the required property in the optional play-control service of the television. [#1562](https://github.com/XiaoMi/ha_xiaomi_home/pull/1562) +### Fixed +- Catch paho-mqtt subscribe error properly. [#1551](https://github.com/XiaoMi/ha_xiaomi_home/pull/1551) +- After the network resumes, keep retrying to fetch the device list until it succeeds. [#1555](https://github.com/XiaoMi/ha_xiaomi_home/pull/1555) +- Catch the http post error properly. [#1555](https://github.com/XiaoMi/ha_xiaomi_home/pull/1555) +- Fixed the format and the access field of daikin.aircondition.k2 and fix: daikin.airfresh.k33 string value properties. [#1561](https://github.com/XiaoMi/ha_xiaomi_home/pull/1561) + +## v0.4.5 +### Changed +- Ignore mdns REMOVED package. [#1296](https://github.com/XiaoMi/ha_xiaomi_home/pull/1296) +- Format value type first, then evaluate by expression, and set precision at last. [#1516](https://github.com/XiaoMi/ha_xiaomi_home/pull/1516) +### Fixed +- Fix xiaomi.derh.lite temperature precision. [#1505](https://github.com/XiaoMi/ha_xiaomi_home/pull/1505) +- Fix xiaomi.waterpuri.s1200g filter property unit, lxzn.valve.02 electricity property unit, xiaomi.aircondition.c24 power consumption device class, and cuco.plug.cp7pd power consumption and power value precision. [#1517](https://github.com/XiaoMi/ha_xiaomi_home/pull/1517) + +## v0.4.4 +### Added +- Add Turkish language support. [#1468](https://github.com/XiaoMi/ha_xiaomi_home/pull/1468) +### Fixed +- Stop MQTT internal loop immediately when main loop is closed. [#1465](https://github.com/XiaoMi/ha_xiaomi_home/pull/1465) +- Fix the float value precision. [#1485](https://github.com/XiaoMi/ha_xiaomi_home/pull/1485) +- Fix the climate entity swing mode setting. [#1486](https://github.com/XiaoMi/ha_xiaomi_home/pull/1486) +- Fix the MIoT-Spec-V2 of cykj.hood.jyj22 urn version 4, lumi.motion.bmgl01 siid=2 piid=2 value-list, ykcn.valve.cbcs power property value unit, ainice.sensor_occupy.3b people-number property and qdhkl.airc.a42 hvac mode. [#1496](https://github.com/XiaoMi/ha_xiaomi_home/pull/1496) + +## v0.4.3 +### Changed +- Remove `VacuumEntityFeature.BATTERY` from the vacuum entity. [#1433](https://github.com/XiaoMi/ha_xiaomi_home/pull/1433) +- Subscribe the proxy gateway child device up messages even though the device is offline. [#1393](https://github.com/XiaoMi/ha_xiaomi_home/pull/1393) +### Fixed +- Fix the integer value step. [#1388](https://github.com/XiaoMi/ha_xiaomi_home/pull/1388) +- Fix the contact-state property value format. [#1387](https://github.com/XiaoMi/ha_xiaomi_home/pull/1387) +- Fix the MIoT-Spec-V2 of xiaomi.airc.rr0r00 swing mode and hyd.airer.lyjpro current-position. [#1394](https://github.com/XiaoMi/ha_xiaomi_home/pull/1394) +- Fix roidmi.vacuum.v60 siid=2 aiid=3 out field format. +- Ignore unsupported properties of xiaomi.wifispeaker.l15a and 759413.aircondition.iez. +- Add an alongside button entity for xiaomi.wifispeaker.l05b play action. +- Add zhimi.fan.za1 fan mode description in zh_Hans. +- Fix the error reported by pylint-4.0.0. [#1455](https://github.com/XiaoMi/ha_xiaomi_home/pull/1455) + +## v0.4.2 +### Changed +- Set the battery service's start-charge action as the fallback action to support RETURN_HOME feature of the vacuum entity. [#1344](https://github.com/XiaoMi/ha_xiaomi_home/pull/1344) +### Fixed +- Correct the property value format after expression calculation. [#1366](https://github.com/XiaoMi/ha_xiaomi_home/pull/1366) +- Fix the MIoT-Spec-V2 of xiaomi.fan.p70 and xiaomi.fan.p76 fan level, xiaomi.airc.rr0r00 and xiaomi.airc.h43h00 humidity-range, and zhimi.humidifier.ca4 water level. [#1367](https://github.com/XiaoMi/ha_xiaomi_home/pull/1367) +- Ignore the unsupported model hmpace.motion.v6nfc. +- Delete all unsupported MIoT-Spec-V2 instances of narwa.vacuum.001 and narwa.vacuum.ax11. [#1355](https://github.com/XiaoMi/ha_xiaomi_home/pull/1355) + +## v0.4.1 +### Changed +- The setting option "Cover closed position" in CONFIGURE is changed to "Cover dead zone width". [#1301](https://github.com/XiaoMi/ha_xiaomi_home/pull/1301) +- Add an alongside switch entity for 090615.aircondition.ktf and juhl.aircondition.hvac. [#1303](https://github.com/XiaoMi/ha_xiaomi_home/pull/1303) +### Fixed +- Fix the vacuum status so that the vacuum activity will not always be idle. [#1299](https://github.com/XiaoMi/ha_xiaomi_home/pull/1299) +- Set the device on when the switch status is False or None. [#1303](https://github.com/XiaoMi/ha_xiaomi_home/pull/1303) +- Hide sensitive info in printing logs. [#1328](https://github.com/XiaoMi/ha_xiaomi_home/pull/1328) +- Fix the MIoT-Spec-V2 of cuco.plug.cp2d electric current, xiaomi.fan.p45 fan level, sanmei.valve.s1 power consumption, current and voltage, xiaomi.aircondition.c17, xiaomi.aircondition.m16 and xiaomi.airc.h40h00 humidity-range unit. [#1329](https://github.com/XiaoMi/ha_xiaomi_home/pull/1329) + ## v0.4.0 ### Added - Add the watch as the device tracker entity. [#1189](https://github.com/XiaoMi/ha_xiaomi_home/pull/1189) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8030244 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,192 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Xiaomi Home Integration is an official Home Assistant integration for controlling Xiaomi IoT smart devices. It connects to devices via Xiaomi Cloud (MQTT) or locally through Xiaomi Central Hub Gateway. The integration converts MIoT-Spec-V2 device specifications into Home Assistant entities. + +## Development Commands + +### Installation & Setup +```bash +# Install to Home Assistant config directory +./install.sh /path/to/config + +# Install test dependencies +pip install pytest pytest-asyncio pytest-dependency zeroconf paho.mqtt psutil cryptography slugify +``` + +### Testing +```bash +# Run all tests +pytest -v -s -m github ./test/ + +# Run specific test files +pytest -v -s ./test/test_spec.py +pytest -v -s ./test/test_cloud.py +pytest -v -s ./test/test_lan.py + +# Check rule format +pytest -v -s -m github ./test/check_rule_format.py +``` + +### Code Quality +```bash +# Run pylint (follows Google Python Style Guide) +pylint $(git ls-files '*.py') + +# Lint specific files +pylint custom_components/xiaomi_home/*.py +``` + +### Validation +```bash +# HACS validation (run by GitHub Actions) +# Uses: hacs/action@main + +# Hassfest validation (run by GitHub Actions) +# Uses: home-assistant/actions/hassfest@master +``` + +## Architecture Overview + +### Core Components (miot/) + +The integration is built around the `miot/` core package: + +**miot_client.py**: Top-level client instance representing a logged-in Xiaomi user. Each user login creates one MIoTClient. Manages authentication, device list, and message routing. + +**miot_cloud.py**: OAuth 2.0 authentication and HTTP API calls to Xiaomi Cloud. Handles token refresh, user info, device control commands, and spec downloads. + +**miot_mips.py**: Message bus (MQTT) for subscribing to device property changes and events. Implements both cloud (MipsCloudClient) and local (MipsLocalClient) message handling. + +**miot_device.py**: Device entity class. Each MIoT device creates multiple MIoTDevice instances (one per Home Assistant entity). Handles property updates, action execution, and event processing. + +**miot_spec.py**: MIoT-Spec-V2 parser. Parses device specifications (URN-based type system) from cloud or local cache. Each spec defines services, properties, events, and actions. + +**miot_lan.py**: Local LAN control for IP devices in same network. Discovery and control without cloud (optional). + +**miot_mdns.py**: mDNS discovery for Xiaomi Central Hub Gateway services. + +**miot_storage.py**: File storage for certificates, device specs, translations, and cached data. + +**miot_network.py**: Network status monitoring and IP address detection. + +**miot_i18n.py**: Multi-language support (13 languages). Manages translations for entity names. + +### Entity Conversion (specs/specv2entity.py) + +MIoT-Spec-V2 instances are converted to Home Assistant entities using three mapping dictionaries: + +- **SPEC_DEVICE_TRANS_MAP**: Whole-device patterns (e.g., vacuum, humidifier, climate) +- **SPEC_SERVICE_TRANS_MAP**: Service-level patterns (e.g., battery, air-purifier) +- **SPEC_PROP_TRANS_MAP**: Property-level patterns (e.g., temperature, humidity) + +Conversion priority: Device > Service > Property > General rules + +### Spec Customization Files (miot/specs/) + +**spec_filter.yaml**: Filters out MIoT-Spec-V2 instances that should NOT be converted to entities. Uses device URN keys and supports wildcard matching for service/property/event/action IIDs. + +**spec_modify.yaml**: Modifies spec instances before conversion (e.g., changing value ranges, access modes). + +**multi_lang.json**: Local translation overrides with higher priority than cloud translations. Keyed by device URN (without version). + +**spec_add.json**: Additional spec definitions for devices not in cloud database. + +**bool_trans.yaml**: Boolean value translation mappings. + +After editing spec files, you MUST update conversion rules via Integration CONFIGURE page in Home Assistant. + +### Platform Files (custom_components/xiaomi_home/) + +Standard Home Assistant platform files (sensor.py, switch.py, climate.py, etc.) implement entity registration and state management. Each platform imports from miot_device.py and creates entity subclasses. + +**config_flow.py**: Configuration flow for OAuth login and device selection. + +**__init__.py**: Integration setup, entry management, and data structure initialization. + +## MIoT-Spec-V2 Concepts + +**URN Format**: `urn::::[::]` +- namespace: miot-spec-v2 (Xiaomi), bluetooth-spec (SIG), or vendor-specific +- type: device, service, property, event, action +- name: human-readable identifier (used for mapping) + +**IIDs (Instance IDs)**: Decimal identifiers +- siid: Service Instance ID +- piid: Property Instance ID +- eiid: Event Instance ID +- aiid: Action Instance ID + +**Instance Code Format**: +``` +service: # service +service::property: # property +service::property::valuelist: # value list item +service::event: # event +service::action: # action +``` + +## Naming Conventions + +From CONTRIBUTING.md: + +- **Xiaomi**: Always "Xiaomi" in text. Variables: "xiaomi" or "mi" +- **Xiaomi Home**: Always "Xiaomi Home" in text. Variables: "mihome" or "MiHome" +- **Xiaomi IoT**: Always "MIoT" in text. Variables: "miot" or "MIoT" +- **Home Assistant**: Always "Home Assistant" in text. Variables: "hass" or "hass_xxx" + +Mixed Chinese/English: Add space between Chinese and English or use Chinese quotation marks. + +## Commit Message Format + +``` +: + + + +