# rytilahti/python-miio architecture

> Architecture diagram of the GitHub repository rytilahti/python-miio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rytilahti/python-miio
- Repository: https://github.com/rytilahti/python-miio

## Overview

##### Project type and purpose
- This is an open-source Python library and CLI tool (“python-miio” / `miiocli`) for controlling Xiaomi IoT devices over the miIO and MIoT protocols.
- Its purpose is to provide a reusable library API plus a command-line interface to discover, query, control, and simulate a wide variety of Xiaomi-branded devices.

##### File structure
- Top level:
- `miio/` – the core library package, containing subpackages for protocols, the device factory, integrations (plugins) for each device type, a push server, simulators, tools for introspection, utilities, and the CLI entry point (`cli.py`).
- `devtools/` – helper scripts (e.g., container definitions, templates for new integrations).
- `docs/` – Sphinx documentation, examples, device-specific docs.
- CI and release files (`.github/workflows`, `pyproject.toml`, `CHANGELOG.md`, etc.).
- `tests/` and `miio/tests/` – unit and integration tests with fixtures.
- Patterns and conventions:
- Plugin pattern: each integration under `miio/integrations/<vendor>/<device>` implements a device class that DeviceFactory picks.
- Factory pattern: `DeviceFactory.create()` chooses the right class at runtime based on model info.
- CLI built with Click (`cli.py`, `click_common.py`).
- Separation of concerns between protocol implementation (`protocol.py`, `miioprotocol.py`, `miot_cloud.py`), data/descriptors (`descriptorcollection.py`, JSON spec files), and device abstractions.

##### Key insights from the README
- Describes two modes: “controlling modern MIoT devices” via a generic MIoT integration (downloads and caches spec files) and “controlling older miIO devices” via specific modules.
- Mentions simulators for both protocols, a push server for event subscriptions, cloud token fetching via `miio/cloud.py` (micloud).
- Shows how end users call `miiocli` which in turn uses the library under the hood.

##### Main components
a. Components
- CLI frontend (`miiocli` / `cli.py`)
- Common CLI logic (`click_common.py`)
- Library core
– DeviceFactory
– Protocol layers: miIO protocol, MIoT protocol, cloud adapter (`cloud.py` / `miot_cloud.py`)
– Descriptor layer (`descriptorcollection.py`, `descriptors.py`, JSON specs)
- Integrations/plugins (each device module under `miio/integrations`)
- Push server (`miio/push_server`)
- Simulators (`miio/devtools/simulators`)
- Devtools (template/containers)
- External services and devices
– Xiaomi cloud (token API)
– MIoT spec repository (Home.MIOT-spec)
– Physical devices on local network
b. Relationships and data flow
- User invokes `miiocli` → CLI frontend parses commands → calls library’s DeviceFactory or generic MIoT handlers
- DeviceFactory → inspects device model via protocol layer → instantiates appropriate device integration
- Integration class → uses protocol module to format command → sends UDP/TCP packets to device IP + token → receives response → maps to high-level methods / descriptors → returns to CLI
- Generic MIoT → fetches spec JSON (remote cache) → introspects features → runs status/set/call
- Cloud fetch (`miiocli cloud`) → `cloud.py` calls Xiaomi cloud → returns tokens → passed to local commands
- Push server → listens for device-initiated events → forwards to client
- Simulators → mimic actual devices (for testing) → respond to protocol messages
c. Architectural patterns and principles
- Plugin architecture for device integrations (easy to add new devices)
- Factory pattern for dynamic class instantiation
- Layered separation: CLI → core API → protocol → transport
- Single responsibility: each module focuses on one concern (protocol, device logic, CLI, docs)
d. Key technologies, frameworks, libraries
- Python 3, `click` for CLI
- Standard UDP/TCP networking for miIO / MIoT
- JSON/YAML for device descriptors and spec files
- Sphinx for documentation
- pytest for test suite
- GitHub Actions for CI and publishing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI["CLI Frontend (miiocli)"]:::cli
        CommonCLI["Common CLI Logic"]:::cli
    end

    %% Core Library
    subgraph "Core Library" 
        direction TB
        DeviceFactory["DeviceFactory"]:::core
        subgraph "Protocol Layer"
            direction TB
            MIIOProt["miIO Protocol"]:::core
            MIIOProtoImpl["miioprotocol"]:::core
            MIOTCloudProt["MIoT Cloud Adapter"]:::core
            MIOTDev["MIoT Device Models"]:::core
            MIOTModels["MIoT Models"]:::core
        end
        subgraph "Descriptor Layer"
            direction TB
            DescriptorColl["DescriptorCollection"]:::core
            Descriptors["Descriptors"]:::core
            DataSpecs["JSON/YAML Specs"]:::core
        end
        Integrations["Integrations / Plugins"]:::plugin
    end

    %% Auxiliary Tools
    subgraph "Auxiliary Tools"
        direction TB
        PushServer["Push Server"]:::aux
        Simulators["Simulators"]:::aux
        DevTools["Developer Tools"]:::aux
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        XiaomiCloud["Xiaomi Cloud API"]:::external
        MIoTSpec["MIoT Spec Repository"]:::external
        Devices["Physical Devices"]:::external
    end

    %% Relationships
    CLI -->|"uses"| CommonCLI
    CommonCLI -->|"calls"| DeviceFactory
    DeviceFactory -->|"selects via model"| Integrations
    DeviceFactory -->|"inspects via"| MIIOProt
    MIIOProt -->|"implements"| MIIOProtoImpl
    Integrations -->|"invoke"| MIIOProt
    Integrations -->|"invoke"| MIIOProtoImpl
    Integrations -->|"invoke"| MIOTCloudProt
    MIOTCloudProt -->|"fetch tokens from"| XiaomiCloud
    MIOTCloudProt -->|"use spec from"| MIoTSpec
    MIOTCloudProt --> MIOTModels
    Integrations -->|"use descriptors from"| DescriptorColl
    DescriptorColl --> Descriptors
    Descriptors --> DataSpecs
    PushServer -->|"subscribes events from"| Devices
    PushServer -->|"uses"| MIIOProt
    Simulators -->|"emulate"| MIIOProt
    Simulators -->|"emulate"| MIIOProtoImpl
    DevTools -->|"supports development of"| Integrations

    %% CLI to core
    CLI -->|"direct API calls"| DeviceFactory
    CLI -->|"cloud commands"| MIOTCloudProt

    %% Core to devices
    MIIOProt -->|"UDP/TCP"| Devices
    MIIOProtoImpl -->|"UDP/TCP"| Devices
    MIOTCloudProt -->|"HTTP"| XiaomiCloud

    %% Classes
    classDef cli fill:#f9c784,stroke:#e69500,color:#333
    classDef core fill:#9fc5e8,stroke:#2e6da4,color:#000
    classDef plugin fill:#b6d7a8,stroke:#38761d,color:#000
    classDef aux fill:#f4cccc,stroke:#c00,color:#000
    classDef external fill:#d9d9d9,stroke:#666,color:#000

    %% Click Events
    click CLI "https://github.com/rytilahti/python-miio/blob/master/miio/cli.py"
    click CommonCLI "https://github.com/rytilahti/python-miio/blob/master/miio/click_common.py"
    click DeviceFactory "https://github.com/rytilahti/python-miio/blob/master/miio/devicefactory.py"
    click MIIOProt "https://github.com/rytilahti/python-miio/blob/master/miio/protocol.py"
    click MIIOProtoImpl "https://github.com/rytilahti/python-miio/blob/master/miio/miioprotocol.py"
    click MIOTCloudProt "https://github.com/rytilahti/python-miio/blob/master/miio/miot_cloud.py"
    click MIOTDev "https://github.com/rytilahti/python-miio/blob/master/miio/miot_device.py"
    click MIOTModels "https://github.com/rytilahti/python-miio/blob/master/miio/miot_models.py"
    click DescriptorColl "https://github.com/rytilahti/python-miio/blob/master/miio/descriptorcollection.py"
    click Descriptors "https://github.com/rytilahti/python-miio/blob/master/miio/descriptors.py"
    click DataSpecs "https://github.com/rytilahti/python-miio/tree/master/miio/data/"
    click Integrations "https://github.com/rytilahti/python-miio/tree/master/miio/integrations/"
    click PushServer "https://github.com/rytilahti/python-miio/tree/master/miio/push_server/"
    click Simulators "https://github.com/rytilahti/python-miio/tree/master/miio/devtools/simulators/"
    click DevTools "https://github.com/rytilahti/python-miio/tree/master/devtools/"
```
