树莓派DIY：打造低功耗电子墨水屏网络带宽监控器-平芜编程栈

1. 项目概述与核心价值

如果你和我一样，对家里的网络状况总有点不放心，或者想直观地监控一下运营商的宽带是否“货真价实”，那么这个基于树莓派和电子墨水屏的带宽监控器，绝对是一个值得动手的DIY项目。它本质上是一个低成本、低功耗、可7x24小时运行的网络质量监测站。核心原理很简单：利用树莓派定期执行网络测速，然后将结果（下载、上传速度、延迟）显示在一块几乎不耗电的电子墨水屏上。这比在电脑或手机上偶尔跑一下测速软件要直观和持久得多，你可以把它放在书桌一角、路由器旁边，随时一瞥就能掌握网络状态。

这个项目的魅力在于它的实用性和极客范儿。树莓派Zero W本身功耗极低，电子墨水屏只在刷新时耗电，显示后完全断电也能保持图像，这使得整个设备可以像一个小摆件一样长期插电运行。无论是用于排查网络间歇性卡顿、监控宽带服务是否达标，还是单纯作为一个有趣的物联网（IoT）入门实践，它都非常合适。你不需要深厚的网络或编程背景，只要跟着步骤一步步来，就能亲手打造一个属于自己的智能硬件监控工具。

2. 硬件选型与连接方案解析

2.1 核心硬件清单与选型考量

这个项目的硬件核心是三件套：树莓派、以太网扩展板、电子墨水屏。选型背后有明确的逻辑。

1. 树莓派型号选择：为什么是Zero W？原文推荐使用树莓派Zero W，这是一个非常经济且平衡的选择。它集成了Wi-Fi和蓝牙，体积小巧，功耗仅1-2瓦。对于带宽监控这种轻量级任务，它的性能绰绰有余。但这里有一个关键点：如果你家的宽带是百兆以上（尤其是千兆），Zero W的Wi-Fi性能或USB 2.0接口可能成为瓶颈，无法测出真实的有线速度。因此，选型逻辑如下：

树莓派Zero W/Zero 2 W：最适合百兆及以下宽带，或对体积、功耗有极致要求的场景。使用Wi-Fi连接即可。
树莓派3B+/4B：如果你拥有百兆以上宽带，并希望获得更准确的有线速度测试结果，应选择这些带有千兆以太网口的型号。树莓派4B的True千兆以太网口能更好地匹配高速宽带。

2. 网络连接方案：Wi-Fi vs. 有线以太网这是影响测速准确性的关键。强烈建议使用有线以太网连接进行测速。Wi-Fi会受到距离、障碍物、信号干扰的极大影响，测出的速度波动大，不能真实反映运营商提供的入户带宽。这就是为什么原项目使用了Waveshare ETH/USB HUB HAT这块扩展板。它为Zero W提供了稳定的有线网络接口，同时扩展了USB口，解决了Zero W只有一个Micro USB口的窘境。如果你的树莓派是3B/4B等自带网口的型号，则无需此HAT。

3. 显示单元：为什么是电子墨水屏（E-Ink）？

超低功耗：屏幕只在刷新数据时（约每秒1-2次）消耗电能，静态显示时功耗为零。这对于需要长期监控的设备来说是理想特性。
视觉舒适：类纸质感，无背光不闪烁，适合长时间注视。
保持显示：断电后图像依然保留，信息不会消失。基于这些优点，Waveshare 2.13英寸电子墨水屏HAT成为了绝配。它通过SPI接口与树莓派通信，即插即用，省去了复杂的接线。

注意：Waveshare的电子墨水屏有多个驱动版本（如V2, V3）。务必确认你手中屏幕的具体型号，因为驱动库可能不同。购买时查看商品描述或屏幕背面标签。

2.2 硬件连接实战与注意事项

连接过程非常简单，但顺序和细节决定成败。

组装顺序：如果你使用的是树莓派Zero W和ETH HAT，首先将40针GPIO排针对齐，将ETH HAT牢牢插入树莓派Zero W。建议使用套件中附带的铜柱和螺丝固定，确保连接稳固，防止松动。然后，再将2.13英寸电子墨水屏HAT以同样的方式堆叠到ETH HAT之上。这种“三明治”式的堆叠是树莓派HAT扩展的典型方式。
供电要点：整个系统通过树莓派的Micro USB口供电。建议使用5V/2.5A或以上的电源适配器，确保在连接多个外设时供电稳定。尤其是使用树莓派4B时，对电流要求更高。
硬件检查：连接完成后，先不要急着上电。检查所有排针是否对准、有无弯针，堆叠是否平整。确认无误后，插入网线（如果使用有线连接），最后再接通电源。

3. 软件环境搭建与依赖库安装

3.1 系统初始化与远程访问配置

我们使用Raspberry Pi OS Lite（无桌面环境）作为系统，以节省资源。使用官方工具Raspberry Pi Imager刷写系统镜像到MicroSD卡是最佳选择。

关键步骤1：启用SSH（无头模式启动必备）在刷写完成的SD卡根目录（名为boot的分区），新建一个名为ssh的空文件（无任何扩展名）。这样树莓派在首次启动时会自动启用SSH服务。

关键步骤2：配置Wi-Fi（如需无线连接或初始设置）同样在boot分区，新建一个名为wpa_supplicant.conf的文件，内容如下（根据你的网络修改）：

country=CN ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev update_config=1 network={ ssid="你的Wi-Fi名称" psk="你的Wi-Fi密码" key_mgmt=WPA-PSK }

完成以上两步后，将SD卡插入树莓派，上电启动。稍等几分钟，你可以在路由器管理界面找到树莓派的IP地址，然后使用SSH客户端（如PuTTY或终端命令ssh pi@<树莓派IP>）登录。默认用户名是pi，密码是raspberry。

3.2 驱动与依赖库安装详解

登录树莓派后，首先更新系统并启用SPI接口，这是驱动墨水屏的通信桥梁。

sudo apt update && sudo apt upgrade -y sudo raspi-config

在raspi-config界面中，选择Interfacing Options->SPI->Yes启用SPI，然后重启。

接下来安装一系列必要的底层库和Python库，每一步都有其作用：

1. 安装BCM2835库：这是访问树莓派GPIO硬件的C语言库，许多底层驱动依赖它。

wget http://www.airspayce.com/mikem/bcm2835/bcm2835-1.71.tar.gz # 版本号可能更新，以官网最新为准 tar zxvf bcm2835-*.tar.gz cd bcm2835-*/ sudo ./configure sudo make sudo make check sudo make install

2. 安装WiringPi库（已归档，但部分驱动仍需要）：这是一个经典的GPIO控制库。虽然官方已停止维护，但安装兼容版本仍是稳妥做法。

sudo apt install wiringpi # 或者从备用源安装 wget https://project-downloads.drogon.net/wiringpi-latest.deb sudo dpkg -i wiringpi-latest.deb gpio -v # 检查安装是否成功

3. 安装Python库：项目脚本用Python编写，需要安装PIL（图像处理）、NumPy（数值计算，部分驱动可能用到）以及操作GPIO和SPI的库。

# 安装Python3版本（推荐，Python2已淘汰） sudo apt install python3-pip python3-pil python3-numpy -y sudo pip3 install RPi.GPIO spidev

RPi.GPIO用于控制GPIO引脚，spidev则提供了SPI通信的Python接口，是墨水屏驱动的关键。

4. 安装测速核心工具：speedtest-cli这是由Ookla（Speedtest.net官方）提供的命令行测速工具。

sudo pip3 install speedtest-cli

安装后，可以运行speedtest-cli进行手动测试，验证其是否能正常工作。

实操心得：依赖库安装过程可能因网络或镜像源问题失败。如果pip安装缓慢或失败，可以尝试更换国内镜像源，例如使用sudo pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple speedtest-cli。安装BCM2835库时，make步骤可能需要几分钟，请耐心等待。

4. 监控程序部署与配置优化

4.1 获取与测试监控脚本

原作者将代码托管在GitHub，我们将其克隆到树莓派本地。

cd ~ sudo apt install git -y # 如果未安装git git clone https://github.com/zangaby/bpimon cd bpimon

克隆后，目录里应包含bpimon.py主脚本和epd2in13_V2.py等墨水屏驱动文件。

首次运行测试：在运行脚本前，务必确认你的墨水屏型号与驱动文件匹配。如果屏幕是V3版本，你需要将bpimon.py中导入的驱动从epd2in13_V2改为epd2in13_V3，并确保驱动文件存在。

# 使用Python3运行测试 sudo python3 bpimon.py

sudo是必需的，因为直接操作GPIO和SPI硬件需要root权限。如果一切正常，你将看到屏幕刷新，显示测速结果（可能需要几十秒完成第一次测速）。如果屏幕无反应或报错，请跳至“问题排查”章节。

4.2 脚本核心逻辑解读与定制

理解脚本做了什么，有助于我们进行定制。bpimon.py的核心工作流程如下：

初始化屏幕：导入驱动，清空屏幕缓冲区。
执行测速：调用speedtest-cli命令，捕获其输出的文本。
解析结果：使用字符串处理或正则表达式，从测速结果中提取“下载速度”、“上传速度”和“延迟（Ping）”的数值。
绘制显示：使用PIL库在内存中创建一个与屏幕分辨率（250x122像素）相同的图像，设置字体、布局，将速度、延迟数值以及单位（如 Mbps, ms）绘制到图像上，通常还会加上一个时间戳。
刷新屏幕：将绘制好的图像数据通过SPI发送给墨水屏硬件，触发屏幕刷新。
清理退出：关闭SPI连接，让屏幕进入低功耗睡眠模式。

你可以定制的地方：

显示布局：修改bpimon.py中绘制文本的坐标，可以改变文字位置。
字体和大小：PIL支持加载TTF字体文件。你可以将喜欢的.ttf字体文件放到项目目录，并在脚本中指定路径，以改变显示字体。
显示内容：除了速度，你还可以添加更多信息，如公网IP地址、测试次数等。

4.3 实现自动化定时任务

我们使用Cron这个Linux系统自带的定时任务工具，让脚本每小时自动运行一次。

编辑root用户的cron表：

sudo crontab -e

如果是第一次使用，可能会让你选择编辑器，选择nano（最简单）。在文件末尾添加一行：

0 * * * * /usr/bin/python3 /home/pi/bpimon/bpimon.py

这行配置的含义是：在每个小时的第0分钟（即整点），使用/usr/bin/python3解释器来执行/home/pi/bpimon/bpimon.py这个脚本。

配置解析与优化：

0 * * * *：这是时间表达式。五个星号分别代表：分钟、小时、日、月、星期。0 * * * *即“每小时的0分”。
使用绝对路径：在cron中，环境变量可能与你的shell环境不同，因此务必使用/usr/bin/python3和脚本的绝对路径（/home/pi/bpimon/bpimon.py），这是避免“命令找不到”错误的关键。
测试cron：保存退出后，你可以手动设置一个几分钟后的任务来测试，例如*/2 * * * * ...表示每两分钟执行一次，观察屏幕是否按时刷新。

注意事项：Cron以root权限运行任务，这确保了脚本有权限访问硬件。但请确保你的脚本路径和Python解释器路径正确。如果脚本执行失败，Cron通常会发送邮件给root用户。你可以通过查看系统日志来调试Cron任务：sudo grep CRON /var/log/syslog。

5. 深度功能扩展与创意改造

基础功能实现后，这个项目还有巨大的可玩性。

5.1 数据持久化与可视化

目前的设备只显示瞬时速度。我们可以修改脚本，将每次的测速结果（时间戳、下载、上传、延迟）追加记录到一个CSV或SQLite数据库中。

# 示例：追加数据到CSV文件 import csv from datetime import datetime data = [datetime.now().strftime('%Y-%m-%d %H:%M:%S'), download_speed, upload_speed, ping] with open('/home/pi/speed_log.csv', 'a', newline='') as f: writer = csv.writer(f) writer.writerow(data)

有了历史数据，你可以：

在树莓派上本地绘图：使用matplotlib库定期生成日、周、月的速度趋势图，并选择性地显示在墨水屏上（例如，每小时刷新显示当前速度和今日平均速度）。
上传到云端仪表盘：将数据通过HTTP POST发送到自建的服务器或第三方物联网平台（如ThingsBoard、Home Assistant），在电脑或手机浏览器上查看更丰富的图表和历史分析。

5.2 集成告警机制

单纯的监控不够，异常时能通知才更实用。可以在脚本中加入判断逻辑：

if download_speed < 50: # 假设你的宽带是100M，设置50M为阈值 # 触发告警动作 # 1. 在屏幕上显示醒目的警告图标或文字 # 2. 发送邮件（使用smtplib库） # 3. 发送App推送（使用Bark、PushDeer等服务的API） # 4. 控制一个LED灯闪烁（需连接LED到GPIO）

这样，当网络速度异常下降时，你就能第一时间获知。

5.3 硬件与显示方案的变体

使用其他型号的墨水屏：Waveshare有1.54英寸、2.9英寸、7.5英寸等多种规格的屏幕。只需替换对应的驱动文件（如epd7in5.py），并调整脚本中的分辨率参数和初始化代码即可。更大的屏幕可以显示更多信息，如网络流量图、天气信息等。
去掉以太网HAT：如果使用树莓派3B/4B，它们自带网口，可以直接插网线。如果使用Zero W且不追求极限有线速度，完全可以仅用Wi-Fi连接，这样硬件成本更低，部署更灵活（只需供电，无需拉网线）。
打造一体化外壳：使用3D打印或亚克力板为你的“三明治”硬件制作一个美观的外壳，让它从一个开发板变成一个真正的桌面摆件。

6. 常见问题排查与解决实录

在实际操作中，你可能会遇到以下问题。这里是我踩过坑后总结的排查思路。

6.1 屏幕无任何反应（白屏或保持旧图）

这是最常见的问题。请按以下顺序排查：

电源与连接：确保树莓派供电充足（5V/2.5A），所有排针连接紧密无误。尝试重新插拔屏幕HAT。
SPI接口是否启用：运行ls /dev/spi*命令。如果能看到/dev/spidev0.0和/dev/spidev0.1等设备，说明SPI已启用。如果看不到，返回sudo raspi-config确认SPI已开启并重启。
驱动版本不匹配：这是最可能的原因。Waveshare的2.13英寸屏有V2和V3等多个版本，驱动不通用。
- 如何判断：查看屏幕背面标签或购买页面说明。也可以尝试运行Waveshare提供的C或Python示例程序来测试。
- 解决方法：从Waveshare官网下载对应屏幕型号的完整示例代码包。找到正确的Python驱动文件（如epd2in13_V3.py），用它替换项目中的epd2in13_V2.py，并修改bpimon.py中的导入语句。
权限问题：确保使用sudo运行Python脚本，因为直接访问SPI设备需要root权限。

6.2 测速速度远低于预期或失败

网络连接模式：确认你测的是有线速度还是Wi-Fi速度。对于准确性要求高的监控，务必使用有线连接。运行speedtest-cli --secure手动测试，观察结果。
树莓派性能瓶颈：如前所述，树莓派Zero W的USB和网络带宽有限。如果你的是千兆宽带，测速结果可能卡在200-300Mbps左右，这是Zero W的硬件上限。升级到树莓派4B能解决此问题。
speedtest-cli服务器选择：speedtest-cli会自动选择最近的服务器，但有时这个服务器可能负载过高。你可以手动指定一个服务器：先运行speedtest-cli --list查看服务器列表，然后使用speedtest-cli --server <服务器ID>测试。
后台干扰：确保测速时树莓派没有在进行大量的磁盘I/O或CPU密集型任务。

6.3 Cron定时任务不执行

检查Cron服务状态：sudo systemctl status cron确保服务是活跃（active）状态。
检查日志：sudo grep CRON /var/log/syslog查看Cron的执行日志，通常会明确显示命令执行失败的原因（如“command not found”）。
使用绝对路径：再次强调，在cron任务中，所有命令和脚本都必须使用绝对路径。
环境变量问题：Cron的环境非常精简，可能缺少PATH等变量。一个稳妥的方法是在执行的shell脚本中设置环境，或者在cron任务行中直接设置，例如：0 * * * * . /home/pi/.profile; /usr/bin/python3 /home/pi/bpimon.py。
输出重定向调试：将脚本的输出和错误信息重定向到日志文件，便于分析：0 * * * * /usr/bin/python3 /home/pi/bpimon.py >> /home/pi/cron.log 2>&1。

6.4 安装依赖库时出错

“E: Unable to locate package”：运行sudo apt update更新软件源列表。
pip安装超时或失败：更换为国内PyPI镜像源，如清华源或阿里云源。可以临时使用-i参数，或永久修改pip配置。
编译BCM2835库出错：确保已安装了基本的编译工具：sudo apt install build-essential -y。

这个项目从硬件拼装到软件调试，完整地走通了一个物联网设备从想法到实物的流程。它不仅仅是一个带宽监控器，更是一个学习Linux操作、Python编程、硬件接口和系统集成的绝佳平台。当你看到墨水屏上第一次成功显示出网络速度时，那种成就感是纯粹的。我自己的设备已经稳定运行了半年多，它让我对家里的网络状况了如指掌，甚至在一次运营商网络升级后，我通过它提供的历史数据，成功论证了升级前后的速度差异。动手去试吧，遇到问题就按上面的思路去排查，每一个问题的解决都会让你对这套系统的理解更深一层。