智能家居物联网IoT协议【免费下载链接】python-miioPython library console tool for controlling Xiaomi smart appliances项目地址https://gitcode.com/gh_mirrors/py/python-miio点击查看免费下载python-miio 是用于控制小米智能家电的 Python 库与命令行工具其 CHANGELOG.md 完整记录了从 2017 年 0.0.5 到 2024 年 0.6.0.dev0 的全部版本轨迹。本文以这份 2343 行的变更日志为主线结合仓库源码系统梳理该项目的核心架构演进——包括 integrations 目录重组、设备描述符descriptors体系、DeviceFactory工厂模式、genericmiot全量 MIoT 设备支持、推送服务器与模拟器等关键里程碑并附上可直接运行的miiocli实战命令。读完本文你将掌握 python-miio 的版本脉络、如何从日志信息中理解每次升级的破坏性变更以及如何利用DeviceFactory与内省接口在自有项目中集成小米设备。一、版本时间线总览CHANGELOG 覆盖了项目从无到有的完整过程可划分为四个明显阶段版本段时间范围核心主题0.0.5 – 0.1.42017 年 4 月 – 8 月初代扫地机控制python-mirobo 时期、UDP 协议通信0.2.0 – 0.3.x2017 年 9 月 – 2018 年更名为 python-miio、mDNS 发现、设备矩阵扩张0.4.0 – 0.5.122018 年 – 2022 年 7 月统一 CLImiiocli、MIoT 协议初支持、推送服务与云端取 token0.6.0.dev02024 年 3 月架构大重构integrations 独立包、描述符体系、genericmiot、模拟器早期版本的 CHANGELOG 由 github_changelog_generator 自动生成见 CHANGELOG.md 末尾注释后期转为基于 Pull Request 标签的半自动维护。理解这一时间线有助于判断不同版本之间 API 的兼容关系——尤其是 0.5.x 与 0.6.0.dev0 之间存在显著的破坏性变更。二、0.6.0.dev0里程碑式预发布与架构重构0.6.0.dev02024-03-13是 CHANGELOG 中篇幅最大的版本条目。它被明确定位为“为测试与开发通过 PyPI 提供的预发布版本尚不适合终端用户”但同时是项目历史上规模最大的一次发布超过 200 个 PR、364 个文件变更、13748 行新增与 5114 行删除并首次实现对所有 miot/miotspec 设备的支持。2.1 核心变更一integrations 迁入独立包日志明确指出对大多数库使用者而言最直观的变化是所有设备集成实现从主包下迁移到了miio.integrations之下的厂商专属目录。这一变动对应 PR #1697Reorganize all integrations to vendor-specific dirs。在仓库中可以看到其落地结果例如miio/integrations/roborock/vacuum/vacuum.pymiio/integrations/zhimi/airpurifier/airpurifier.pymiio/integrations/yeelight/light/yeelight.pymiio/integrations/genericmiot/genericmiot.py在此之前0.5.9 起的过渡期真空吸尘器模块曾短暂位于miio.integrations.vacuum.roborock本次重构将“按设备类型”的组织方式最终统一为“按厂商vendor再按类型”的树形结构。这一调整也体现在 miio/integrations/init.py 的包结构上。2.2 核心变更二DeviceFactory 取代硬编码实例化日志给出的迁移建议是不再直接 import 具体实现类而是使用DeviceFactory构造实例。仓库中的 miio/devicefactory.py 提供了这一机制的完整实现from miio import DeviceFactory dev DeviceFactory.create(ip address, token) dev.status()其底层逻辑值得展开对应 miio/devicefactory.py若未指定model先构造一个基础Device实例并执行info()查询自动探测设备型号通过class_for_model()在已注册的“型号 → 实现类”映射表中查找对应实现支持通配符型号如GenericMiot注册的*或带前缀的xxx*并按最长前缀匹配排序返回最具体实现见 miio/devicefactory.py找不到实现时抛出DeviceException(No implementation found for model ...)。设备类注册是自动完成的Device.__init_subclass__会在每个实现类创建时将其注册到DeviceFactory见 miio/device.py。此外DeviceFactory还暴露了integrations与models两个 CLI 子命令可列出当前支持的所有集成与型号。2.3 核心变更三可内省接口与描述符体系0.6.0.dev0 最重要的功能特性是可内省接口introspectable interfacesstatus()、sensors()、settings()、actions()四个方法让下游用户如 Home Assistant无需在代码中硬编码设备细节即可动态支持设备。这套机制建立在“设备描述符descriptors”之上对应 miio/descriptors.py 与 miio/descriptorcollection.py。描述符体系在本次发布中还经历了一系列 API 重命名详见 2.6 节并配套了多个装饰器实现miio/devicestatus.py 中的sensor、setting、action装饰器用于在状态类上声明可内省的传感器、设置项与动作SettingDescriptor支持min_value/max_value/step/range_attribute、choices/choices_attribute等约束描述对应 PR #1587、#16020.6.0 还实现了 DeviceStatus 容器的“嵌入”机制embedding即一个状态容器可作为另一个状态容器的子项挂载通过__作为分隔符访问PR #1526、#1573。2.4 核心变更四genericmiot 全量 MIoT 设备支持日志称这是“设备支持量最大的一次发布”通过 genericmiot 集成所有 miot/miotspec 设备均可被控制对应命令为miiocli genericmiot。这是对库原始设计的一次重大改变——这类设备需要下载外部托管的规格文件miot spec才能工作首次使用时自动下载并缓存一段时间对应 PR #1581 Add generic miot support。源码印证了这一点miio/integrations/genericmiot/genericmiot.py 中GenericMiot._supported_models [*]即默认匹配所有型号。其工作流程为initialize_model()通过MiotCloud按型号获取设备模型见 miio/integrations/genericmiot/genericmiot.py依据模型创建属性properties与动作actions的描述符status()使用get_properties查询所有可读属性并限制单次最多 10 个属性以规避过大的 UDP 数据报见 miio/integrations/genericmiot/genericmiot.py。规格文件的下拉与缓存逻辑位于 miio/miot_cloud.py缓存目录使用platformdirs.user_cache_dir(python-miio)缓存有效期为 6 小时cache_hours6见 miio/miot_cloud.py型号映射文件名为model-to-urn.json当同一型号存在多个版本时info_for_model会自动选择最新版本并记录警告见 miio/miot_cloud.py。日志中特别修复了若干相关缺陷包括“确保缓存目录存在”“缓存文件损坏时的容错处理”等PR #1798、#1819。genericmiot 还支持通过 miio/integrations/genericmiot/metadata/ 下的 YAML 元数据如base.yaml、common.yaml、miotspec.yaml对设备自带名称进行润色与修正。2.5 核心变更五miIO 与 MIoT 模拟器日志提到新增了 miio 与 miot 两类模拟器用于在没有实体设备的情况下进行开发这也正是 MIoT 支持本身的开发工具。仓库中的实现位于miio/devtools/simulators/miiosimulator.pymiio/devtools/simulators/miotsimulator.py配套的文档可参考 docs/simulator.rst。0.6.0 同时修复了 miio-simulator 启动失败PR #1792、miotsimulator 只读属性检查PR #1690等问题并让模拟器对 info 查询返回 localhost 地址PR #1657。2.6 破坏性变更清单0.6.0.dev0 列出的破坏性变更如下升级到 0.6 系列的既有代码需要逐一核对引入基于设备描述符的公共接口PR #1845描述符的property重命名为status_attributePR #1759移除{Light,Vacuum}InterfacesPR #1743SettingDescriptor的type重命名为setting_typePR #1715允许为 push server 定义device_idPR #1710所有集成重组到厂商专属目录PR #1697移除长期废弃的miio.vacuum模块PR #1607miotdevice.set_property_by允许传入自定义名称PR #1576改进 viomi.vacuum.v8styj02ym支持PR #1559清理库抛出的异常体系PR #1558test-properties 迁移到 devtools 命令下PR #1505实现可内省的 settingsPR #1500放弃 Python 3.7 支持PR #1469。三、0.5.x 系列事件推送、云端取 token 与设备矩阵扩张3.1 0.5.12PushServer 事件推送与云端 Token0.5.122022-07-18的两个亮点在 CHANGELOG 中占据了主导地位其一事件推送支持。借助miio.PushServer支持设备的事件回调PR #1446。其原理是利用场景scene功能订阅事件当时已知仅网关类设备支持文档见 docs/push_server.rst。仓库中的实现位于 miio/push_server/server.py配套的示例位于 docs/examples/push_server/如gateway_alarm_trigger.py、gateway_button_press.py。0.6.0 进一步将 push server 泛化PR #1531并尽量使用 asyncio 设施PR #1521。其二云端获取 Token。通过可选的micloud依赖可一次性从云账户获取所有设备的 tokenPR #1460命令为miiocli cloudAPI 层则提供miio.CloudInterface源码位于 miio/cloud.pymiiocli cloud Username: exampleexample.com Password: name of the device (Device offline ) Model: example.device.v1 Token: b1946ac92492d2347c6235b4d2611184 IP: 192.168.xx.xx (mac: ab:cd:ef:12:34:56) DID: 123456789 Locale: cn此外 0.5.12 还要求 click 8PR #1378、新增device_id属性PR #1384、引入统一的真空吸尘器接口VacuumInterface与风扇速度预设PR #1368、#1405、支持 Roborock 自动集尘PR #1188。3.2 0.5.11流量解析器与废弃类清理0.5.112022-03-07引入网络流量解析器devtools/parse_pcap.py即仓库中的 devtools/pcapparser.py在 0.6.0 中并入devtools命令体系给定 token 即可打印解密后的设备流量是协议逆向与调试的重要工具。该版本还一次性废弃/移除了大量旧类PR #1343迁移对照如下已废弃类替代AirFreshVA4AirFreshAirHumidifierCA1、AirHumidifierCB1、AirHumidifierCB2AirHumidifierAirDogX5、AirDogX7SMAirDogX3AirPurifierMB4AirPurifierMiotPlug、PlugV1、PlugV3ChuangmiPlugFanP9、FanP10、FanP11FanMiotDreameVacuumMiotDreameVacuumVacuumRoborockVacuum同时wifi_led被废弃改用ledPR #1342。3.3 0.5.0 起的 MIoT 初代支持MIoT 协议支持始于 0.5.02020-06-04当时的口号是“为了庆祝新协议集成从 0.4 跳到 0.5”。首批 MIoT 设备为空气净化器 3/3Hzhimi.airpurifier.mb3、ma4配套工具是 devtools/miottemplate.py用于根据 miot spec 生成设备实现模板并可“按型号下载 miot spec 文件”PR #904。0.5.5.2 出于兼容性重新加入了MiotDevice构造函数的mapping参数PR #985并允许限制单次查询属性数量max_propertiesPR #981。MIoT 设备的核心 API 在 miio/miot_device.py 中实现包括get_property_by(siid, piid)、set_property_by(siid, piid, value)、call_action_by(siid, aiid)等这一“按 siid/piid 寻址”的模型正是 0.6.0 genericmiot 得以动态支持任意设备的基础。3.4 0.5.x 新增设备一览0.5.x 期间设备支持持续扩张CHANGELOG 中明确列出的代表性新增包括0.5.12dmaker.fan.p33米家智能落地扇 2 Pro、zhimi.airpurifier.za1、Roborock G10Sroborock.vacuum.a46、zhimi.airp.mb5空气净化器 4、Dreame 多款dreame.vacuum.p2150o等0.5.10zhimi.heater.za2、Dreame F9dreame.vacuum.p2008、空气净化器 4 Prozhimi.airp.va2、deerma.humidifier.jsq{s,5}0.5.9mijia.vacuum.v2米家 G1 扫地机、mmgg.pet_waterer.s1宠物饮水机0.5.5scishare.coffee.s1102咖啡机、dmaker.airfresh.a1、zhimi.heater.mc2、yeelink.switch.sw1、leshow.fan.ss4、airdog.airpurifier.{x3,x5,x7sm}、yunmi.waterpuri.lx9/lx11、xiaomi.aircondition.mc1/mc2/mc4/mc5、lumi.curtain.hagl05等。四、0.4.x 时代miiocli 统一 CLI 与设备矩阵成型0.4.02018-12的核心成就是miiocli统一命令行接口PR #191yawor它取代了此前零散的 mirobo/miplug 等工具将所有已支持设备接入同一套 CLI 体系。此后每个设备模块均可用统一的参数风格调用miiocli roborockvacuum --help Usage: miiocli roborockvacuum [OPTIONS] COMMAND [ARGS]... Options: --ip TEXT [required] --token TEXT [required] --id-file FILE --help Show this message and exit. Commands: add_timer Add a timer. ..0.4.x 期间每次发布都伴随新设备0.4.1 加入新风机 VA2 与飞利浦床头灯0.4.2 移除长期废弃的 mirobo 包、解除 construct 版本锁定0.4.4 支持净化器 2s 与roborock.vacuum.e2/c10.4.5 支持 Chuangmi Plug M3、Air Purifier Pro V7、Aqara 摄像头0.4.6 支持空气质量监测仪 S1、chuangmi.camera.ipc009、多款风扇、智能马桶盖与 16 路继电器0.4.7 支持除湿机、小爱闹钟、空气质量监测仪 2 代与欧版智能插座0.4.8 支持 STYJ02YM 扫地机、deerma.humidifier.mjjsq、新风机 T2017、飞利浦台灯等。五、0.1–0.3 早期历史更名、发现机制与 token 提取CHANGELOG 清晰记录了项目起源0.3.02017-10-21从python-mirobo 更名为 python-miio旧包继续兼容一段时间但鼓励迁移到新的miio包。同期加入的miio-extract-tokens工具可从米家 App 的 Android 备份或 iOS/Android 数据库SQLite中提取并解密 token源码见 miio/extract_tokens.py成为当时新用户上手的关键入口。发现机制同样经历了迭代0.1.3 起发现改用mDNSzeroconf旧握手协议仍可通过--handshake true使用0.3.6 实现“按需懒发现”lazy discovery0.5.x 引入miiocli discover命令。仓库中的 miio/discovery.py 是这些演进的最终形态且 0.6.0 移除了硬编码的型号信息PR #1695。0.3.x 还沉淀了一批影响至今的工程决策0.3.2 引入 Sphinx 文档见 docs/0.3.5 统一异常体系、所有设备异常派生自DeviceException对应 miio/exceptions.py0.3.8 加入固件更新与语音包安装能力miio/updater.py并放弃 Python 3.4。六、贯穿版本史的主题兼容性、质量与工具链6.1 废弃与兼容策略CHANGELOG 中最频繁出现的主题之一是“废弃 → 移除”的渐进式演进。典型链条包括Strip→PowerStrip0.3.1Vacuum→RoborockVacuum0.5.9 废弃、0.6.0 移除miio.vacuumwifi_led→led0.5.11depth→water_level/water_tank_detached0.5.7clean_details的return_list参数移除0.5.8。0.6.0 还在主模块入口加入了对直接导入集成类的弃用警告PR #1813进一步引导用户转向DeviceFactory。6.2 Python 版本与依赖管理Python 支持下限逐步提升3.40.3.8 放弃→ 3.50.3.4 起→ 3.60.4.7 起→ 3.7 不再支持0.6.0.dev0CI 同步加入 Python 3.12PR #1851依赖管理在 0.5.1 转向poetry 与 pyproject.toml0.5.9 改用 poetry-core 构建仓库当前使用 uv见 pyproject.toml 与 uv.lock0.5.9 加入py.typed标记miio/py.typed0.5.7 起代码通过 mypy 检查0.6.0 支持 pydantic v2 的 v1 垫片PR #1816并通过__cli_output__统一 CLI 输出PR #1762、#1847。6.3 测试与工程质量日志反复出现测试覆盖率的提升0.3.3 起为各设备净化器、加湿器、空气质量监测仪、飞利浦灯具等补写单元测试0.4.8 引入 Azure pipeline 与 black/flake8/isort pre-commit 钩子0.5.x 增加 codeql、pre-commit hooks 更新与代码覆盖度看护0.6.0 将模拟设备与状态对象移入 conftestPR #1873。仓库中每个集成目录下都带有tests/与test_*.py例如 miio/integrations/zhimi/airpurifier/tests/、miio/integrations/roborock/vacuum/tests/是学习各设备实现语义命令名、参数取值、状态枚举的最佳参考。七、如何应用这份 CHANGELOG实用指引对于 python-miio 的开发者与集成者这份 CHANGELOG 的实战价值在于判断升级影响0.6.0.dev0 是唯一包含大规模破坏性变更的版本升级前务必对照“Breaking changes”清单逐一迁移0.5.x 内部的小版本升级主要影响类名与属性名可用上文废弃对照表快速定位。掌握统一控制入口现代设备优先走miiocli genericmiot其status/set/actions/call四类命令覆盖了传感器的读取、设置的修改与动作的执行miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 status miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 set light:brightness 60 miiocli genericmiot --ip 127.0.0.1 --token 00000000000000000000000000000000 call light:toggle按图索骥阅读源码CHANGELOG 中每个条目都对应 PR 与具体的源码模块——描述符体系看 miio/descriptors.py 与 miio/descriptorcollection.py设备自动发现看 miio/devicefactory.pyMIoT 模型解析看 miio/miot_models.py规格文件下载缓存看 miio/miot_cloud.py协议加解密看 miio/protocol.py 与 miio/miioprotocol.py。开发调试无实体设备时使用 docs/simulator.rst 所述的模拟器需要逆向协议时使用 devtools/pcapparser.py获取 token 优先miiocli cloud其他途径见 docs/discovery.rst 与 docs/legacy_token_extraction.rst。结语CHANGELOG.md 不仅仅是版本号的流水账它实质上是 python-miio 技术架构的编年史从单一扫地机控制工具到覆盖全品类小米家电的协议库再到以描述符、工厂与泛化集成genericmiot为核心的模块化架构。理解这条演进主线就等于掌握了该库的设计哲学——渐进式废弃、接口内省化、设备支持泛化这也为二次开发、集成贡献如为既有设备补充描述符元数据提供了清晰的路线图。赞分享智能家居物联网IoT协议【免费下载链接】python-miioPython library console tool for controlling Xiaomi smart appliances项目地址https://gitcode.com/gh_mirrors/py/python-miio点击查看免费下载相关推荐python-miio 实战指南用 miiocli 与 Python API 控制小米智能设备miIO / MIoT 协议python miio 实战指南用 miiocli 与 Python API 控制小米智能设备miIO / MIoT 协议 本指南以仓库根目录的 READ智能家居物联网IoT协议深入理解python-miio协议miIO与MIoT技术详解深入理解python miio协议miIO与MIoT技术详解 想要掌握小米智能家居设备的控制原理吗python miio库为你提供了完整的解决方案这个强大智能家居物联网IoT协议Vector快速上手Kubernetes 十分钟部署日志收集管道附避坑记录Vector快速上手Kubernetes 十分钟部署日志收集管道附避坑记录 凌晨三点告警响起来某台节点磁盘占用 97%日志把应用写入堵死了。你需要的不可观测性数据工程数据集成日志分析上一篇cppast诊断日志系统构建可靠的C代码分析工具下一篇图表绘制工具Diagram——将ASCII艺术转变为手绘风格图表的神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考