使用文档

覆盖从安装、多灯配置到快捷键与故障排除的完整流程。适用于 v1.5.0 及以后版本。

安装

方式一：下载 EXE（推荐）

从 最新 Release 下载 MiMonitorLightTray.exe，双击运行即可。每次 push 到 main 与每个 tag 都会自动构建。

方式二：从源码运行

git clone https://github.com/awakaze/MiMonitorLightTray.git
cd MiMonitorLightTray

python -m venv .venv
.venv\Scripts\activate
pip install -e .

mi-monitor-light-tray

要求 Python 3.9+。

首次设置

首次运行会自动打开设备列表向导。推荐流程（多设备一键导入）：

1. 点击 云端导入
2. 用小米账号 / 米家 App 扫描弹出的二维码登录
3. 在设备列表中勾选一个或多个灯具，点击 确认导入

手动添加设备

也可以点击 + 添加设备 逐个填写：

• 设备 IP：米家 App → 设备页面 → ⋮ → 更多设置 → 网络信息；或在路由器 DHCP 列表里找名称含 yeelight / monitor 的设备
• miio Token：32 位十六进制串，可用 Xiaomi-cloud-tokens-extractor 或 miiocli cloud 提取
• 显示名称：随意，会显示在弹窗上方
• 型号：留空即可，连接后自动识别

点击 测试连接 验证连通性，保存 后设备加入列表。可以对已添加的设备执行 编辑 / 删除，或按住行首 ⋮⋮ 图标 拖拽 调整显示顺序 —— 顺序决定弹窗中每个设备的显示位置。

日常使用

托盘弹窗

• 左键单击托盘图标 → 在光标附近弹出控制窗
• 弹窗按设备列表顺序为每盏灯渲染一节：设备名 + 状态 + 独立 ⏻ 开关按钮，下方是亮度 / 色温滑杆
• 窗口高度按内容自适应：一盏灯与旧版差不多，两盏灯约翻倍高
• 底部按钮从右到左：⚙ 打开设置、⏻ 关闭所有在线灯
• 点击窗口外或按 Esc 关闭弹窗
• 设备名过长时自动截断为 xxxx...，按钮位置保持固定

右键托盘菜单

每设备显示控制

在 设置 界面的设备卡片上可以直接勾选 / 取消：

• 显示亮度调节 — 是否在弹窗中显示此设备的亮度滑杆
• 显示色温调节 — 是否在弹窗中显示此设备的色温滑杆

两个开关都关掉时，该设备不会出现在弹窗里（快捷键仍生效）—— 适合"只想快捷键控制、不想在弹窗里看到"的辅助灯。

全局快捷键

在 设置 → 编辑设备 底部的"快捷键设置"里，为每盏灯单独绑定：

1. 点击快捷键输入框
2. 按下想要的按键组合（如 Ctrl+Alt+Up）
3. 输入框自动填充，可再次修改
4. 右键输入框直接清空
5. 设置调整步进（默认 5，亮度按 1–100 直加减，色温按范围百分比换算）
6. 保存

可用修饰键：Ctrl、Shift、Alt、Win

推荐组合示例：

• 亮度增加：Ctrl+Alt+Up
• 亮度降低：Ctrl+Alt+Down
• 色温增加：Ctrl+Alt+Right（偏冷白）
• 色温降低：Ctrl+Alt+Left（偏暖白）

电源策略

每盏灯在设备编辑器里都有独立的五个开关：

• 灯跟随软件启动 — 程序启动时自动开这盏灯
• 灯跟随软件关闭 — 程序退出（含托盘"退出"、Ctrl+C、任务栏关闭、Windows 关机）时自动关这盏灯
• 灯随显示器休眠开关 — 显示器休眠时关灯，唤醒时恢复休眠前状态
• 系统休眠时关灯 — 系统进入睡眠 / 休眠时关灯
• 系统唤醒时开灯 — 系统从睡眠 / 休眠恢复时开灯

每盏灯互不干扰：可以让台灯跟随软件启停、显示器挂灯跟随显示器休眠、床头灯只用系统休眠 / 唤醒 —— 组合自由。

底层实现

• 显示器休眠通过 RegisterPowerSettingNotification 订阅 GUID_CONSOLE_DISPLAY_STATE，跟随 Windows 自身的显示器电源广播，不做独立空闲计时（看视频、听音乐时不会误关）
• 系统休眠 / 唤醒监听 WM_POWERBROADCAST 的 PBT_APMSUSPEND / PBT_APMRESUMESUSPEND
• 程序退出关灯走 atexit 钩子 + 顶级窗口的 WM_QUERYENDSESSION 双保险，覆盖 Windows 强制关机场景

拖滑杆自动开灯

当灯处于关闭状态时拖动亮度或色温滑杆，程序会先发送开灯指令，再设置目标值。默认行为、无需开关 —— 避免"拖了半天没反应"。

开机自启动

在托盘右键菜单或设备列表底部勾选"开机自启动"。本质是向 HKCU\Software\Microsoft\Windows\CurrentVersion\Run 写一条 MiMonitorLightTray，不需要管理员权限，只对当前用户生效。

桌面小部件

右键托盘菜单点击 桌面小部件 即可在桌面显示一个常驻控制面板：

• 拖动标题区域移动位置
• 右键小部件可 锁定 / 解锁 位置（锁定后无法拖动，防止误碰）
• 位置、锁定状态、可见性自动持久化到 config.json 的 widget 段

启用 MIoT（实验性）

设备编辑器里的开关。适合以下情况：手上是新型 Yeelight / MIoT 设备、不在 _MIOT_MAPPINGS 白名单里、又怀疑它实际走 MIoT 协议。勾选后程序会用 lamp22 的通用 Light service spec（(siid=2, piid=1/2/3) = power/brightness/color-temperature）尝试通信。设备不兼容时会持续报错；关掉即可回到 legacy 路径。

命令行参数

MiMonitorLightTray.exe --setup    # 强制打开设备列表向导
MiMonitorLightTray.exe --debug    # 开启调试日志

配置文件

位置：%APPDATA%\MiMonitorLightTray\config.json

{
  "devices": [
    {
      "id": "1a2b3c4d",
      "ip": "192.168.1.100",
      "token": "...32 位十六进制...",
      "name": "显示器挂灯",
      "model": "yeelink.light.lamp22",
      "device_id": 12345678,
      "enable_miot_for_unknown": false,
      "power_on_at_startup": false,
      "power_off_at_exit": false,
      "power_off_on_monitor_sleep": false,
      "power_off_on_system_suspend": false,
      "power_on_on_system_resume": false,
      "brightness_up": "Ctrl+Alt+Up",
      "brightness_down": "Ctrl+Alt+Down",
      "color_temp_up": "Ctrl+Alt+Right",
      "color_temp_down": "Ctrl+Alt+Left",
      "hotkey_step": 5,
      "show_brightness": true,
      "show_color_temp": true
    }
  ],
  "widget": { "visible": false, "x": 100, "y": 100, "locked": true },
  "auto_check_update": true
}

字段说明

• devices[]：所有设备的数组。可以是空数组（此时启动会进设备列表向导）
• devices[].id：稳定标识符，新设备是 temp_xxxxxxxx，首次成功连接后自动升级为 <device_id 的 8 位十六进制>
• devices[].device_id：首次连接时从 miio info() 捕获，用于 IP 变化后的自动发现
• devices[].model：留空时启动时通过 info() 自动探测并回填
• devices[].enable_miot_for_unknown：未在 _MIOT_MAPPINGS 白名单的 Yeelight 设备强制走 MIoT
• power_*：五个独立电源策略开关
• brightness_up/down、color_temp_up/down：本设备的四个全局快捷键
• hotkey_step：快捷键调整步进（亮度：加减 N，色温：按范围 N% 换算）
• show_brightness / show_color_temp：弹窗内此设备是否显示对应滑杆
• widget：桌面小部件位置 / 可见性 / 锁定状态
• auto_check_update：启动时是否自动检查 GitHub Release

兼容设备

本程序按设备 model 自动选择 legacy 或 MIoT 协议。除少数手工 curated 的机型外，~2100 个 MIoT 灯具的协议映射与色温范围已从 home.miot-spec.com 抓取并嵌入，覆盖 yeelink、xiaomi、mijia 以及大量第三方品牌。

路由决策（按 model 优先级）

1. curated _MIOT_MAPPINGS（含 lamp22）→ MIoT
2. python-miio YeelightSpecHelper（specs.yaml 已知的 legacy 设备，41 个）→ legacy
3. 本项目 curated MODEL_CT_RANGES（手工验证过 legacy 的设备，如 lamp2）→ legacy
4. bulk _miot_data（前 3 个都没听说过的 MIoT-only 设备，~2100 个）→ MIoT
5. 完全未知 → legacy（兜底，配合"启用 MIoT 实验性"开关可改走 MIoT）

重点机型

故障排除

从 v1.4.x 升级后设备没了 / 报错

程序会自动把旧的 device 字段迁移为 devices 数组。如果没有生效，检查 %APPDATA%\MiMonitorLightTray\config.json 是否可读；实在不行删掉重新走一遍设备列表向导。

多盏灯的快捷键冲突

系统级 RegisterHotKey 每个组合只能被注册一次，所以每盏灯必须用不同的快捷键。冲突时后注册的会失败并写入日志（--debug 可看到）。

提示"已在运行"

程序已启动，检查系统托盘溢出区（右下角向上箭头）是否有图标。

状态显示"离线 — Unable to discover the device"

1. 确认挂灯通电且与电脑在同一局域网
2. 确认 IP 正确（用米家 App 或路由器复查）
3. miio 走 UDP 54321，部分企业网络 / 防火墙会拦截，可临时关闭防火墙测试
4. 程序会在后台自动尝试发现新 IP（如果 device_id 已知）

提示"miio error: Invalid token"

Token 在设备重新配对到米家时会刷新，需用 cloud-tokens-extractor 重新提取，或者用云端导入功能重新拉一次。

托盘图标不显示

Windows 资源管理器可能把它收进了溢出区，点击托盘左侧的向上箭头查看。

拖滑杆时灯有约 0.1 秒延迟

这是有意的防抖（120ms 亮度 / 180ms 色温），用来合并请求避免设备被刷爆，松开手后会立即生效。每盏灯有独立防抖器，多设备不会互相拖累。

桌面小部件只显示一盏灯

小部件目前是旧的单设备实现，多设备场景请用托盘弹窗或快捷键。

从源码构建 EXE

pip install -e ".[build]"
python scripts/build_exe.py

输出到 dist\MiMonitorLightTray.exe。脚本会用 PyInstaller 的 --onefile --noconsole，并通过 --collect-data miio 把 python-miio 的 YAML / JSON 规格文件一起打包（否则会在运行时崩溃）。构建脚本开头会自动执行 pip install -e . --no-deps --quiet 同步 dist-info，确保 EXE 报告的版本号与 pyproject.toml 一致。

运行测试

pip install -e ".[dev]"
pytest -q

测试覆盖配置序列化、托盘图标渲染、miio 包装层与防抖器。UI 与真实网络路径需要手动验证。