# xiaomi/ha_xiaomi_home architecture

> Architecture diagram of the GitHub repository xiaomi/ha_xiaomi_home, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xiaomi/ha_xiaomi_home
- Repository: https://github.com/xiaomi/ha_xiaomi_home

## Overview

Xiaomi Home is a Home Assistant integration for importing and controlling Xiaomi IoT devices. The user configures an account and selects devices; the integration represents those devices as Home Assistant entities and routes commands through cloud or supported local control. The README documents OAuth login, multiple accounts, configuration updates, action debugging, and cloud, gateway, and optional LAN control. Source excerpts establish the MIoT client’s local-first routing and several internal dependencies; unsampled flow details are omitted rather than inferred.

Main entry points: [`custom_components/xiaomi_home/miot/miot_client.py`](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_client.py) (MIoT client), [`custom_components/xiaomi_home/miot/miot_device.py`](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_device.py) (Device modeling), [`custom_components/xiaomi_home/__init__.py`](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/__init__.py) (Integration lifecycle), [`custom_components/xiaomi_home/miot/miot_cloud.py`](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_cloud.py) (Cloud API and OAuth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and integration"]
  node_flow["Account and device setup<br/>[config_flow.py]"]
  node_integration["Integration lifecycle<br/>[__init__.py]"]
  node_pages["OAuth web pages<br/>[web_pages.py]"]
end

subgraph group_device["Devices and entities"]
  node_devices["Device modeling<br/>[miot_device.py]"]
  node_entities["Home Assistant entities<br/>[climate.py]"]
  node_platforms["Other entity platforms"]
end

subgraph group_protocol["MIoT connectivity"]
  node_client["MIoT client<br/>[miot_client.py]"]
  node_cloud["Cloud API and OAuth<br/>[miot_cloud.py]"]
  node_mips["MIPS messaging<br/>[miot_mips.py]"]
  node_lan["LAN control<br/>[miot_lan.py]"]
  node_mdns["Gateway discovery<br/>[miot_mdns.py]"]
  node_network["Network status<br/>[miot_network.py]"]
end

subgraph group_support["MIoT foundations"]
  node_spec["MIoT specifications<br/>[miot_spec.py]"]
  node_specmap["Spec-to-entity mapping<br/>[specv2entity.py]"]
  node_storage[("Persistent storage<br/>[miot_storage.py]")]
  node_i18n["MIoT translations<br/>[miot_i18n.py]"]
  node_common["Shared utilities<br/>[common.py]"]
end

node_user(("Home Assistant user"))
node_ha(("Home Assistant"))
node_xiaomi["Xiaomi cloud"]

node_user -->|"configures"| node_flow
node_flow -->|"serves login"| node_pages
node_flow -->|"authenticates"| node_cloud
node_ha -.->|"loads integration"| node_integration
node_integration -->|"initializes client"| node_client
node_integration -->|"uses storage"| node_storage
node_integration -->|"uses specs"| node_spec
node_client -->|"calls API"| node_cloud
node_client -->|"dispatches messages"| node_mips
node_client -->|"routes local control"| node_lan
node_client -.->|"discovers gateways"| node_mdns
node_client -.->|"checks connectivity"| node_network
node_cloud -->|"HTTP and MQTT"| node_xiaomi
node_mips -->|"cloud messaging"| node_xiaomi
node_devices -->|"controls devices"| node_client
node_devices -->|"uses definitions"| node_spec
node_devices -->|"maps capabilities"| node_specmap
node_entities -->|"wraps devices"| node_devices
node_platforms -->|"wraps devices"| node_devices
node_ha -.->|"exposes controls"| node_entities
node_spec -->|"loads cached specs"| node_storage
node_client -->|"initializes translations"| node_i18n
node_cloud -->|"uses utilities"| node_common
node_lan -->|"uses network"| node_network
node_lan -->|"uses discovery"| node_mdns
node_mips -->|"uses utilities"| node_common

click node_flow "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/config_flow.py"
click node_integration "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/__init__.py"
click node_pages "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/web_pages.py"
click node_client "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_client.py"
click node_cloud "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_cloud.py"
click node_mips "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_mips.py"
click node_lan "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_lan.py"
click node_mdns "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_mdns.py"
click node_network "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_network.py"
click node_devices "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_device.py"
click node_entities "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/climate.py"
click node_platforms "https://github.com/xiaomi/ha_xiaomi_home/tree/main/custom_components/xiaomi_home"
click node_spec "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_spec.py"
click node_specmap "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/specs/specv2entity.py"
click node_storage "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_storage.py"
click node_i18n "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_i18n.py"
click node_common "https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/common.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flow,node_integration,node_pages,node_user toneBlue
class node_devices,node_entities,node_platforms toneAmber
class node_client,node_cloud,node_mips,node_lan,node_mdns,node_network toneMint
class node_spec,node_specmap,node_storage,node_i18n,node_common toneRose
class node_ha,node_xiaomi toneIndigo
```

## Components

### Setup and integration

- [Account and device setup](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/config_flow.py): `custom_components/xiaomi_home/config_flow.py`
- [Integration lifecycle](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/__init__.py): `custom_components/xiaomi_home/__init__.py`
- [OAuth web pages](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/web_pages.py): `custom_components/xiaomi_home/miot/web_pages.py`

### Devices and entities

- [Device modeling](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_device.py): `custom_components/xiaomi_home/miot/miot_device.py`
- [Home Assistant entities](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/climate.py): `custom_components/xiaomi_home/climate.py`
- [Other entity platforms](https://github.com/xiaomi/ha_xiaomi_home/tree/main/custom_components/xiaomi_home): `custom_components/xiaomi_home`

### MIoT connectivity

- [MIoT client](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_client.py): `custom_components/xiaomi_home/miot/miot_client.py`
- [Cloud API and OAuth](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_cloud.py): `custom_components/xiaomi_home/miot/miot_cloud.py`
- [MIPS messaging](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_mips.py): `custom_components/xiaomi_home/miot/miot_mips.py`
- [LAN control](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_lan.py): `custom_components/xiaomi_home/miot/miot_lan.py`
- [Gateway discovery](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_mdns.py): `custom_components/xiaomi_home/miot/miot_mdns.py`
- [Network status](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_network.py): `custom_components/xiaomi_home/miot/miot_network.py`

### MIoT foundations

- [MIoT specifications](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_spec.py): `custom_components/xiaomi_home/miot/miot_spec.py`
- [Spec-to-entity mapping](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/specs/specv2entity.py): `custom_components/xiaomi_home/miot/specs/specv2entity.py`
- [Persistent storage](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_storage.py): `custom_components/xiaomi_home/miot/miot_storage.py`
- [MIoT translations](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/miot_i18n.py): `custom_components/xiaomi_home/miot/miot_i18n.py`
- [Shared utilities](https://github.com/xiaomi/ha_xiaomi_home/blob/main/custom_components/xiaomi_home/miot/common.py): `custom_components/xiaomi_home/miot/common.py`

### Other components

- **Home Assistant user**
- **Home Assistant**
- **Xiaomi cloud**

## Connections

- Home Assistant user → Account and device setup: configures (evidence: `README.md`)
- Account and device setup → OAuth web pages: serves login (evidence: `custom_components/xiaomi_home/config_flow.py`)
- Account and device setup → Cloud API and OAuth: authenticates (evidence: `custom_components/xiaomi_home/config_flow.py`)
- Home Assistant → Integration lifecycle: loads integration
- Integration lifecycle → MIoT client: initializes client (evidence: `custom_components/xiaomi_home/__init__.py`)
- Integration lifecycle → Persistent storage: uses storage (evidence: `custom_components/xiaomi_home/__init__.py`)
- Integration lifecycle → MIoT specifications: uses specs (evidence: `custom_components/xiaomi_home/__init__.py`)
- MIoT client → Cloud API and OAuth: calls API (evidence: `custom_components/xiaomi_home/miot/miot_client.py`)
- MIoT client → MIPS messaging: dispatches messages (evidence: `custom_components/xiaomi_home/miot/miot_client.py`)
- MIoT client → LAN control: routes local control (evidence: `custom_components/xiaomi_home/miot/miot_client.py`)
- MIoT client → Gateway discovery: discovers gateways (evidence: `custom_components/xiaomi_home/miot/miot_client.py`)
- MIoT client → Network status: checks connectivity (evidence: `custom_components/xiaomi_home/miot/miot_client.py`)
- Cloud API and OAuth → Xiaomi cloud: HTTP and MQTT (evidence: `README.md`)
- MIPS messaging → Xiaomi cloud: cloud messaging (evidence: `README.md`)
- Device modeling → MIoT client: controls devices (evidence: `custom_components/xiaomi_home/miot/miot_device.py`)
- Device modeling → MIoT specifications: uses definitions (evidence: `custom_components/xiaomi_home/miot/miot_device.py`)
- Device modeling → Spec-to-entity mapping: maps capabilities (evidence: `custom_components/xiaomi_home/miot/miot_device.py`)
- Home Assistant entities → Device modeling: wraps devices (evidence: `custom_components/xiaomi_home/climate.py`)
- Other entity platforms → Device modeling: wraps devices (evidence: `custom_components/xiaomi_home/sensor.py`)
- Home Assistant → Home Assistant entities: exposes controls
- MIoT specifications → Persistent storage: loads cached specs (evidence: `custom_components/xiaomi_home/miot/miot_spec.py`)
- MIoT client → MIoT translations: initializes translations (evidence: `custom_components/xiaomi_home/miot/miot_client.py`)
- Cloud API and OAuth → Shared utilities: uses utilities (evidence: `custom_components/xiaomi_home/miot/miot_cloud.py`)
- LAN control → Network status: uses network (evidence: `custom_components/xiaomi_home/miot/miot_lan.py`)
- LAN control → Gateway discovery: uses discovery (evidence: `custom_components/xiaomi_home/miot/miot_lan.py`)
- MIPS messaging → Shared utilities: uses utilities (evidence: `custom_components/xiaomi_home/miot/miot_mips.py`)
