WAIT — Slowing — last commit 3mo ago

• Last commit 3mo ago
• 15 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 3mo ago
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

A Home Assistant custom component that integrates Xiaomi IoT smart devices via the MIoT (Mi IoT) protocol, enabling local and cloud control of Xiaomi smart home devices (lights, climate, covers, fans, etc.) through Home Assistant's entity framework. It bridges Home Assistant's entity model with Xiaomi's proprietary device specification format and provides both LAN and cloud communication paths. Single-component monolith under custom_components/xiaomi_home/ with domain-specific modules: platform integrations (light.py, climate.py, etc.), MIoT protocol layer (miot/ directory containing client, cloud, LAN, spec parsing), i18n for UI strings, and config_flow.py for async setup. The miot/ subdirectory abstracts device communication; platform files (binary_sensor.py, etc.) consume the MIoT client to expose entities.

Home Assistant users who own Xiaomi smart home devices and want to control them natively within Home Assistant without third-party bridges. Home Assistant developers extending support for additional Xiaomi device types. Xiaomi customers in regions with Xiaomi cloud support (China, EU, etc.).

Actively developed and production-ready. The repo shows recent commits, structured CI/CD via GitHub Actions (test.yaml, validate.yaml, release.yaml), comprehensive i18n support (13 language files), and clear versioning via tags and CHANGELOG. Home Assistant version requirement is pinned to ≥2024.4.4, indicating tight integration with a stable ecosystem.

Primary risk is Xiaomi API/protocol stability—the integration depends on Xiaomi's cloud services and MIoT spec compliance (custom_components/xiaomi_home/miot/miot_cloud.py, miot_spec.py). Single maintainer risk exists given it's an official Xiaomi repo but community-contributed code. Breaking changes could occur if Xiaomi's authentication or device spec format shifts. Network-dependent behavior (both LAN via miot_lan.py and cloud) introduces potential fragility in air-gapped or unstable networks.

Actively maintained with recent commits implied by CHANGELOG and test workflow configuration. The repo demonstrates structured release process (release.yaml), linting validation (.pylintrc, validate.yaml), and multi-language support additions. No specific PR/milestone data visible, but the presence of comprehensive GitHub Actions suggests active CI/CD and testing discipline.

git clone https://github.com/XiaoMi/ha_xiaomi_home.git
cd ha_xiaomi_home
./install.sh /config

Or via HACS from Home Assistant UI, or manual copy of custom_components/xiaomi_home to ~/.homeassistant/custom_components/. Requires Home Assistant ≥2024.4.4 and Xiaomi account login.

Daily commands: Install into Home Assistant via install.sh script or HACS, restart Home Assistant, then navigate to Settings > Devices & services > Add Integration > Xiaomi Home > login with Xiaomi account. No standalone dev server; testing is done via Home Assistant's test framework (inferred from test.yaml CI workflow).

• custom_components/xiaomi_home/__init__.py — Main entry point for the Home Assistant integration; handles component setup, device discovery, and lifecycle management
• custom_components/xiaomi_home/config_flow.py — Configuration flow for user onboarding and OAuth authentication; essential for setup process
• custom_components/xiaomi_home/miot/miot_client.py — Core MIoT protocol client abstracting cloud and LAN communication; central dependency for all device operations
• custom_components/xiaomi_home/miot/miot_device.py — Device abstraction layer mapping Xiaomi MIoT spec to Home Assistant entities; bridges protocol and HA platform
• custom_components/xiaomi_home/miot/miot_spec.py — Specification parser for Xiaomi device models; decodes device capabilities and property mappings
• custom_components/xiaomi_home/manifest.json — Integration metadata defining dependencies, supported HA versions, and component requirements

Add Support for a New Device Platform (e.g., New Sensor Type)

1. Create new platform module following the pattern: custom_components/xiaomi_home/YOUR_PLATFORM.py (custom_components/xiaomi_home/sensor.py)
2. Import and set up the platform in the main init.py async_setup_entry function (custom_components/xiaomi_home/__init__.py)
3. Add device spec filtering rules in spec_filter.yaml to identify device types that match your platform (custom_components/xiaomi_home/miot/specs/spec_filter.yaml)
4. Map spec properties to HA attributes in spec_modify.yaml if custom transformation is needed (custom_components/xiaomi_home/miot/specs/spec_modify.yaml)
5. Add translation strings for entity names in translation JSON files (custom_components/xiaomi_home/translations/en.json)

Add Support for a New Device Model

1. Query Xiaomi MIoT spec server and save the JSON response in custom storage (custom_components/xiaomi_home/miot/miot_spec.py)
2. Add model-to-spec mapping in the LAN profile database for local device discovery (custom_components/xiaomi_home/miot/lan/profile_models.yaml)
3. If needed, add encryption/decryption rules for the device model (custom_components/xiaomi_home/miot/miot_mips.py)

Extend Cloud Authentication (OAuth/Token Handling)

1. Modify OAuth redirect handler and token exchange logic (custom_components/xiaomi_home/miot/web_pages.py)
2. Update config flow to handle new auth methods or scopes (custom_components/xiaomi_home/config_flow.py)
3. Store and refresh tokens using the storage abstraction (custom_components/xiaomi_home/miot/miot_storage.py)

Improve Local Device Discovery

1. Enhance mDNS discovery filters or add new service type detection (custom_components/xiaomi_home/miot/miot_mdns.py)
2. Extend device model recognition by adding profiles (custom_components/xiaomi_home/miot/lan/profile_models.yaml)
3. Add tests for new discovery scenarios (test/test_mdns.py)

• Home Assistant (Python 3.11+) — Official integration must comply with HA framework for entity platform, config flow, and lifecycle management
• MIoT Protocol (Xiaomi IoT Specification) — Native Xiaomi device communication standard; avoids reverse-engineering and ensures compatibility across device families
• OAuth 2.0 + Cloud API — Secure remote access and device discovery; required for cloud-based control and fallback when LAN unavailable
• mDNS + Local LAN discovery — Privacy-preserving local control without cloud dependency; reduces latency and improves reliability
• YAML for specs and profiles — Declarative device model mappings; allows non-code customization and easy community contributions

• Unified miot_client abstraction over cloud and LAN backends

  • Why: Simplifies platform code and enables transparent fallback (cloud if LAN fails)
  • Consequence: Adds abstraction layer overhead; requires careful client state management for dual-path communication

• Spec caching and local profile models (profile_models.yaml)

  • Why: Reduces cloud API calls and speeds up repeated device setup
  • Consequence: Profiles can become stale; requires periodic updates and manual override mechanisms

• File-based storage instead of HA native storage

  • Why: Direct control over token/profile persistence and easier debugging
  • Consequence: Manual migration required if HA storage API changes; less integrated with HA core features

• Separate LAN encryption (MIPS) vs. cloud (HTTPS/TLS)

  • Why: LAN
  • Consequence: undefined

Xiaomi authentication state is tied to cloud login (miot_cloud.py); offline Home Assistant cannot discover or control cloud-only devices. LAN control requires mDNS discovery (miot_mdns.py) and firewall rules to allow local communication. Device profiles are hardcoded in YAML (profile_models.yaml)—unsupported device models silently fail or require manual spec entry. Async/await patterns throughout; synchronous code in platform callbacks will deadlock. Home Assistant version pinning (≥2024.4.4) means older HA instances are incompatible; check CHANGELOG for breaking changes. Entity unique_id construction must be consistent to avoid entity duplication on updates (watch miot_device.py).

• MIoT (Mi IoT) Protocol — Core protocol this integration implements; understanding MIoT spec structure (properties, actions, events) is essential to adding device support or debugging device communication
• Home Assistant Entity Platform Pattern — This repo uses HA's platform abstraction (light.py, climate.py, etc. inherit from base platform classes); required to add new device types or modify entity behavior
• Async/Await and asyncio — Entire codebase is async-first (config_flow, device comms, entity updates); synchronous code will block Home Assistant's event loop and cause timeouts
• mDNS (Multicast DNS) Discovery — Used by miot_mdns.py for local LAN device discovery without relying on cloud; required for understanding how devices are found on the local network
• OAuth 2.0 / Xiaomi Cloud Authentication — miot_cloud.py implements Xiaomi's OAuth flow for user login; understanding token lifecycle, refresh, and error handling is critical for cloud-dependent device control
• YAML Schema and Device Profile Mapping — profile_models.yaml uses YAML to map device model IDs to MIoT specs; adding new devices requires understanding this schema format and how it's parsed by miot_spec.py
• Home Assistant Unique IDs and Entity Registry — Entity identification and deduplication relies on correctly constructed unique_id (see miot_device.py); mistakes cause duplicate entities or lost configuration on updates

• home-assistant/core — Home Assistant framework that this integration extends; required to understand entity API, config_flow, and async patterns
• hacs/integration — HACS repository that hosts and distributes this integration; users install via HACS as primary method
• XiaoMi/device-miot-spec — Official Xiaomi MIoT device specification repository; defines the device schema that miot_spec.py and profile_models.yaml parse
• jghauser/paho-mqtt-homeassistant-discovery — Alternative MQTT-based Xiaomi integration for Home Assistant; shows competing approach to device discovery vs. cloud API
• hassio-addons/addon-xiaomi-mirobo — Companion Xiaomi add-on for roborock vacuum integration; demonstrates ecosystem of related Xiaomi device support in HA

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for miot_client.py and miot_device.py

The core communication layer (custom_components/xiaomi_home/miot/miot_client.py and miot_device.py) lacks visible test coverage. These modules handle critical device communication, authentication, and property mapping. Adding unit tests would improve reliability and make future refactoring safer. This directly supports the Home Assistant requirement for stable integrations.

• [ ] Create tests/miot/test_miot_client.py with tests for connection handling, timeout scenarios, and error states
• [ ] Create tests/miot/test_miot_device.py with tests for property mapping, state updates, and device initialization
• [ ] Add pytest fixtures in tests/conftest.py for mock Xiaomi devices and network responses
• [ ] Update .github/workflows/test.yaml to run pytest and report coverage metrics
• [ ] Document test patterns in CONTRIBUTING.md for future contributor guidance

Add integration tests for config_flow.py authentication scenarios

The config_flow.py handles OAuth authentication and device discovery, which are critical user-facing features. There are no visible integration tests validating the full flow from authentication token exchange through device pairing. This gap increases risk of regressions when authentication logic changes.

• [ ] Create tests/test_config_flow.py with integration tests for OAuth redirect handling
• [ ] Add tests for device discovery flow (miot_mdns.py integration)
• [ ] Test error handling for invalid credentials and network failures
• [ ] Add mock data fixtures in tests/fixtures/mock_oauth_responses.json
• [ ] Verify all Home Assistant config flow step transitions work correctly

Add CI workflow for validating i18n JSON syntax and completeness across all language files

The repo includes 12 language files in custom_components/xiaomi_home/miot/i18n/ and custom_components/xiaomi_home/translations/. Currently there's no automated validation that these JSON files are syntactically correct or that translation keys are consistent across languages. This can lead to silent breakage in non-English locales.

• [ ] Create .github/workflows/i18n_validate.yaml to validate JSON syntax for all i18n files
• [ ] Add schema validation ensuring all keys present in en.json exist in other language files
• [ ] Create a Python script (custom_components/xiaomi_home/miot/i18n/validate_translations.py) to check for missing translation keys
• [ ] Add pre-commit hook configuration in .pylintrc or new .pre-commit-config.yaml
• [ ] Document translation contribution guidelines in CONTRIBUTING.md with validation examples

• Add comprehensive type hints to custom_components/xiaomi_home/miot/miot_device.py—currently lacks type annotations, making it harder for new contributors to understand device state management
• Create unit tests for custom_components/xiaomi_home/miot/miot_spec.py spec parsing logic—the critical path for translating vendor schemas to entities has no visible test coverage in the repo structure
• Document the MIoT profile schema in custom_components/xiaomi_home/miot/lan/profile_models.yaml with inline comments and a schema reference guide—new contributors cannot understand required/optional fields without reading code

The Xiaomi Home Integration for Home Assistant shows a moderate security posture with concerning areas around cloud authentication, OAuth handling, and LAN communication. The codebase handles sensitive IoT device credentials and cloud tokens, requiring careful implementation of encryption, validation, and secure storage practices

• High · OAuth Redirect Page HTML File — custom_components/xiaomi_home/miot/resource/oauth_redirect_page.html. The presence of 'oauth_redirect_page.html' in the resource directory suggests OAuth credential handling. HTML files serving OAuth redirects could be vulnerable to CSRF attacks, open redirect vulnerabilities, or improper state parameter validation if not carefully implemented. Fix: Audit the OAuth implementation for: (1) Proper CSRF token validation, (2) State parameter verification, (3) Redirect URL validation against whitelist, (4) Secure token storage practices
• High · Cloud Authentication Handling — custom_components/xiaomi_home/miot/miot_cloud.py. The 'miot_cloud.py' module handles cloud authentication. Without code inspection, potential risks include: plaintext credential storage, insufficient encryption for sensitive tokens, or improper session management. Fix: Ensure: (1) Credentials are never logged or stored in plaintext, (2) Tokens use encryption at rest, (3) TLS/SSL enforced for all cloud communications, (4) Token rotation and expiration implemented, (5) No hardcoded API keys or secrets
• Medium · LAN Communication Security — custom_components/xiaomi_home/miot/miot_lan.py. LAN-based device communication in 'miot_lan.py' may be vulnerable to man-in-the-middle attacks if device communication lacks encryption or certificate validation. Fix: Verify: (1) All LAN communications use encrypted protocols, (2) Certificate pinning or validation is implemented, (3) Device discovery mechanisms are secure, (4) No unencrypted protocol fallbacks
• Medium · External Specification Files — custom_components/xiaomi_home/miot/specs/. YAML and JSON specification files in the 'specs/' directory are loaded at runtime. If these files can be modified or come from untrusted sources, they could enable arbitrary code execution or configuration bypass. Fix: Implement: (1) File integrity verification (checksums/signatures), (2) Restrict file permissions, (3) Validate schema strictly before loading, (4) Consider code-signing specifications
• Medium · No Visible Dependency Pinning — custom_components/xiaomi_home/manifest.json (implied). The dependency file content was not provided, but the README mentions Core >= 2024.4.4. Without strict version pinning in requirements, transitive dependencies could introduce vulnerabilities. Fix: Ensure all dependencies in manifest.json have specific pinned versions (not ranges) or use hash verification for security-critical packages
• Medium · Config Flow User Input Handling — custom_components/xiaomi_home/config_flow.py. The 'config_flow.py' processes user input for device configuration. Improper validation could lead to injection attacks or configuration bypass. Fix: Verify: (1) All user inputs are validated and sanitized, (2) No user input directly used in commands/queries, (3) Configuration schema validation is strict, (4) Error messages don't leak sensitive information
• Low · Multiple Language Files — custom_components/xiaomi_home/miot/i18n/, custom_components/xiaomi_home/translations/. i18n and translation files could be vectors for injection if not properly validated when loaded, though impact is typically low. Fix: Ensure translation files are only loaded from trusted sources and JSON parsing is strict without custom deserialization
• Low · Web Pages Module — custom_components/xiaomi_home/miot/web_pages.py. The 'web_pages.py' module serves web content. Potential XSS vulnerabilities if user-controlled data is rendered in HTML without escaping. Fix: Ensure all dynamic content is properly HTML-escaped, use templating engines with auto-escaping, implement CSP headers

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/XiaoMi/ha_xiaomi_home shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live XiaoMi/ha_xiaomi_home repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/XiaoMi/ha_xiaomi_home.

What it runs against: a local clone of XiaoMi/ha_xiaomi_home — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in XiaoMi/ha_xiaomi_home | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 131 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of XiaoMi/ha_xiaomi_home. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/XiaoMi/ha_xiaomi_home.git
#   cd ha_xiaomi_home
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of XiaoMi/ha_xiaomi_home and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "XiaoMi/ha_xiaomi_home(\\.git)?\\b" \\
  && ok "origin remote is XiaoMi/ha_xiaomi_home" \\
  || miss "origin remote is not XiaoMi/ha_xiaomi_home (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "custom_components/xiaomi_home/__init__.py" \\
  && ok "custom_components/xiaomi_home/__init__.py" \\
  || miss "missing critical file: custom_components/xiaomi_home/__init__.py"
test -f "custom_components/xiaomi_home/config_flow.py" \\
  && ok "custom_components/xiaomi_home/config_flow.py" \\
  || miss "missing critical file: custom_components/xiaomi_home/config_flow.py"
test -f "custom_components/xiaomi_home/miot/miot_client.py" \\
  && ok "custom_components/xiaomi_home/miot/miot_client.py" \\
  || miss "missing critical file: custom_components/xiaomi_home/miot/miot_client.py"
test -f "custom_components/xiaomi_home/miot/miot_device.py" \\
  && ok "custom_components/xiaomi_home/miot/miot_device.py" \\
  || miss "missing critical file: custom_components/xiaomi_home/miot/miot_device.py"
test -f "custom_components/xiaomi_home/miot/miot_spec.py" \\
  && ok "custom_components/xiaomi_home/miot/miot_spec.py" \\
  || miss "missing critical file: custom_components/xiaomi_home/miot/miot_spec.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 131 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~101d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/XiaoMi/ha_xiaomi_home"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.