KartoshaHv/tapo-voltage-monitor

# tapo-voltage-monitor **使用 TP-Link Tapo 智能插座监控墙壁插座电压 —— 无需电压表。** [Русская версия](README.ru.md) ## 为什么开发它 家里的电源、路由器或其他小设备坏了 —— 而你怀疑是供电不稳？你可以用你手头可能已经有的 Tapo P110 或 P115 智能插座来进行检测。 Tapo 应用只显示瓦数。但插座内部的芯片其实也能测量电压 —— 只是 TP-Link 从未在任何地方显示它。这个程序知道如何提取它。 它每隔几秒钟记录一次电压，并在浏览器中显示一个友好的页面：图表、实时数据，以及电压超出安全范围的每一刻的列表。它还能检测**停电**：插座内部有一个“通电后经过的秒数”计数器，当该计数器重置时，工具就知道断电了 —— 即使断电期间你的电脑处于关机状态。这样记录下来的一周数据，是你与电力公司交涉的有力证据。  ## 这些数字代表什么 在 230 V 电压的国家/地区，标准允许范围是 **207 到 253 V** —— 这就是图表上的灰色区域。只要曲线保持在这个区域内，一切正常。当电压偏离这个区域时，麻烦就来了：程序会用红色标记该时刻，并将其添加到事件表中 —— 记录发生的时间、持续了多久以及偏离了多少。（居住在 120 V 电压的国家？在配置文件中将 `voltage_norm` 设置为 `[114, 126]` 即可。） ## 你需要准备什么 - **一个 TP-Link Tapo P110 或 P115 智能插座。** 较便宜的 P100/P105 不行 —— 它们没有计量芯片。该插座必须在 Tapo 应用中设置好并连接到你的 Wi-Fi。 - **一台用于记录的电脑**（同一家庭网络中的任何 Windows / Mac / Linux 机器均可）。当电脑关机或休眠时，记录会暂停。 - **Python** —— 运行此程序所需的免费运行环境。从 [python.org/downloads](https://www.python.org/downloads/) 下载，并确保在安装过程中勾选 **“Add Python to PATH”**。 ## 设置（只需一次，约 10 分钟） ### 步骤 1. 允许访问插座 在手机的 Tapo 应用中：**Me → Third-Party Services → Third-Party Compatibility → enable**。如果没有这一步，插座将拒绝与程序通信。如果之后连接仍然失败，请将该设置关闭再打开，并将插座从墙上拔下 10 秒钟。 ### 步骤 2. 找到插座的 IP 地址 家庭网络上的每个设备都有一个类似 `192.168.1.135` 的地址。你可以在 Tapo 应用中看到它：打开插座 → 齿轮图标 → **Device Info** → IP 那一行。 最好在路由器设置中“固定”该地址（该功能通常称为 DHCP 预留或“静态 IP”）—— 否则路由器某天可能会给插座分配不同的地址，程序将会找不到它。不知道怎么操作？没关系 —— 如果程序停止工作了，重新检查一下地址即可。 ### 步骤 3. 下载并安装程序 打开终端（在 Windows 上：按开始键，输入 `powershell`，回车）并逐一运行以下命令： ``` git clone https://github.com/KartoshaHv/tapo-voltage-monitor cd tapo-voltage-monitor pip install -r requirements.txt ``` 没有 `git`？更简单的方法：在项目的 GitHub 页面上按下绿色的 **Code → Download ZIP** 按钮，将其解压到任意位置，在该文件夹中打开终端，只需运行 `pip install -r requirements.txt`。 ### 步骤 4. 输入你的插座信息 使用任意文本编辑器打开 `config.json` 并输入你自己的地址。你可以按照自己习惯的方式为插座命名： ``` { "plugs": { "living_room": "192.168.1.135", "bedroom": "192.168.1.129" }, "interval_seconds": 3, "dashboard_port": 8765, "voltage_norm": [207, 253] } ``` 只有一个插座也可以 —— 只保留一行即可。 ### 步骤 5. 向程序提供你的 Tapo 登录信息 程序使用你的 Tapo 应用邮箱和密码连接到插座。为了防止密码出现在文件中，它被存储在系统的环境变量中。在终端中运行（替换为你自己的值）： ``` # Windows — 然后关闭终端并打开一个新的终端 setx TAPO_EMAIL "you@example.com" setx TAPO_PASSWORD "your_password" # Mac / Linux export TAPO_EMAIL="you@example.com" TAPO_PASSWORD="your_password" ``` ## 使用方法 在 Windows 上，双击程序文件夹中的 **start.bat**。会出现两个黑窗口（数据采集器和带有图表的微型网站 —— 不要关闭它们，最小化即可），然后你的浏览器会自动打开仪表盘。 如果浏览器没有自动打开，请在地址栏中输入 **http://localhost:8765**。 右上角的按钮可以切换时间段：小时、天、周、全部时间。页面每 10 秒自动刷新一次。 在 Mac 和 Linux 上，在两个终端中分别运行 `python monitor.py` 和 `python dashboard.py`，而不是使用 start.bat。 **想在购买任何东西之前先预览一下吗？** 运行 `python demo_data.py` —— 它会模拟生成一周看起来合理的数据，让你无需任何插座即可探索仪表盘。 为了收集有用的证据，让电脑至少运行一天 —— 最好是一周 —— 并禁用睡眠模式（Settings → System → Power → Sleep: never），否则记录会不断暂停。 ## 诚实的局限性 - 该插座不是专业仪器：读数可能会有 1-2 V 的误差。但是电压骤降和骤升 —— 这才是最值得关注的部分 —— 会完美显示出来。 - 每 3 秒读取一次读数。任何智能插座在物理层面上都无法捕捉到非常短暂的尖峰电压（几分之一秒）。如果你的图表看起来非常平稳，但设备却不断损坏，罪魁祸首很可能正是这种微尖峰 —— 解决办法是使用优质的浪涌保护器或 UPS，而不是进行更多测量。 - 我们读取电压的方式是非官方的（TP-Link 没有提供相关文档）。未来的固件更新可能会取消此功能 —— 在这种情况下，程序会如实告知，并继续记录用电功率数据。 - 停电检测无法区分真正的断电和有人拔掉了插座 —— 因为对插座来说，这是同一个事件。而且，如果在一个断电间隔内发生了多次停电，它只会被算作一次停电（计数器只记录最后一次通电的时间）。 ## 遇到问题了吗？ | 发生了什么 | 怎么做 | |---|---| | `FORBIDDEN` 或 `Unauthorized` 错误 | 步骤 1 未执行或尚未生效：将 Third-Party Compatibility 开关关掉再打开，将插座拔下 10 秒钟，等待几分钟 | | 找不到插座 | 检查 IP 地址（步骤 2）—— 路由器可能已经更改了它。电脑和插座必须在同一个网络中 | | 电压列为空 | 你的固件没有公开电压数据 —— 在 Tapo 应用中更新插座（齿轮图标 → Firmware Update）并重启程序 | | 仪表盘是空的 / “No data” | 确保 monitor.py 窗口已打开并正在打印数字 | | `python is not recognized...` | 安装 Python 时没有勾选“Add Python to PATH” —— 请勾选该选项后重新安装 | ## 给好奇者的解释：工作原理 所有数据都会写入到一个普通的 `power_log.csv` 文件中 —— 你可以用 Excel 打开它。程序使用 [python-kasa](https://github.com/python-kasa/python-kasa) 库通过家庭网络直接与插座通信（不会向互联网发送任何内容），并向其发送一个未公开的命令 —— `get_emeter_data` —— 固件会通过该命令暴露伏特和安培数： ``` {"current_ma": 744, "voltage_mv": 234120, "power_mw": 141916} ``` 这个技巧是通过对比 python-kasa 社区收集的设备转储信息发现的。程序中还有一个 `analyze.py` —— 它可以在不打开浏览器的情况下，生成文本报告和图表图像。 ## 许可证 MIT —— 可自由使用。本程序与 TP-Link 没有任何关联。我们不对烧毁的电子设备负责 —— 尽管拯救它们正是我们的初衷 :)

标签：Python, 无后门, 智能家居, 物联网, 监控工具, 逆向工具