How rytilahti/python-miio works
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