控制台 退出登录
持续维护 · 连续运行 46+ 天 硬件节点 / MQTT / Docker

Pi-EnvNode · 树莓派室内环境监测与告警节点

用树莓派 4B 连接 I2C 温湿度与气压传感器,配合本地 SQLite 断网环形队列与容器化 Mosquitto Broker,构建一套断电自恢复、零丢包的室内与弱电箱环境监测系统。

Raspberry Pi 4B Python 3.11 SHT30 / BMP280 (I2C) Mosquitto MQTT SQLite WAL Docker Compose
PI-ENVNODE TELEMETRY MONITOR · NODE: pi4b-rack-01 ● BROKER CONNECTED 环境温度 (SHT30 0x44) 24.68 °C 阈值 < 32.0°C · 正常 相对湿度 (SHT30 0x44) 52.40 %RH 露点 14.3°C · 无凝露风险 本地补发队列 (SQLite WAL) 0 条积压 上次断网重传: 12天前 (84条) 实时 MQTT 报文流与滤波状态 (Topic: lab/env/rack-01/telemetry · QoS 1) [11:04:00.104] I2C Read OK raw_t=24.71 raw_h=52.41 -> median_5=(24.68, 52.40) [11:04:00.118] MQTT PUB ACK mid=48291 latency=14ms topic="lab/env/rack-01/telemetry" [11:04:05.102] I2C Glitch raw_t=85.00 (CRC valid but spike > 5°C/5s) -> dropped by filter [11:04:05.119] MQTT PUB ACK mid=48292 latency=16ms payload={"temp_c":24.69,"humi":52.4} [11:04:10.000] Watchdog heartbeat sent to systemd (WATCHDOG_USEC=30000000) Uptime: 46d 14h 22m · Memory: 18.4 MB · CPU: 0.7% · SD Card Writes: < 1.2 MB/day

01 能做什么(核心应用场景)

场景 A · 机柜与弱电箱全天候巡检

7×24 小时无人值守温湿度遥测

在放有软路由、NAS 与树莓派的弱电柜内,以 5 秒/次的频率采集温湿度与气压。通过滑动窗口剔除排风扇启停带来的瞬时电磁干扰毛刺,生成平滑可靠的时序数据。

场景 B · 家庭宽带/容器重启期间零丢包

断网自动转存 SQLite,恢复后按序补传

当上游服务器维护或路由器重启导致 MQTT 连接断开时,采集端自动将遥测 JSON 写入本地 SQLite WAL 环形表(上限 5 万条),网络恢复后以每秒 50 条速率异步补齐历史曲线。

场景 C · 散热异常即时告警

连续越界去抖动告警推送

避免单次读数抖动触发误报:仅当连续 6 个采样周期(30 秒)温度超过 32°C 或湿度高于 75%RH 时,才向 `lab/env/+/alert` 主题发布高优告警并触发 Webhook 通知。

02 我是怎么实现的(系统架构与工程取舍)

系统架构与数据流图(支持点击放大查看)
1. 传感器硬件层 SHT30 温湿度 (0x44) CRC-8 硬件校验 BMP280 气压 (0x76) I2C Bus-1 @ 100kHz 2. 树莓派边缘守护进程 • 滑动窗口中位值滤波 (N=5) • Paho-MQTT 异步重连状态机 • SQLite WAL 断网环形缓冲 • systemd Watchdog 心跳保活 内存占用 < 20MB · 低写放大 3. MQTT 消息代理 Eclipse Mosquitto • 遥测: QoS 1 • 在线状态: LWT 遗嘱 • 账密鉴权 + ACL Docker 容器化部署 4. 消费与告警 • 时序归档落库 • 连续越界判定 • Webhook 推送 支持多节点扩展

关键技术选择与原因

  • 为什么选 MQTT (Mosquitto) 而非 HTTP 轮询:边缘节点处于内网 NAT 后方,MQTT 长连接开销极小,且天然支持 `Last Will (LWT)` 遗嘱消息,节点掉线能秒级感知。
  • 为什么在树莓派本地加 SQLite WAL 队列:如果只用内存队列,遇到断电或进程重启会丢失断网期间的数据;开启 WAL 模式的 SQLite 兼顾了断电安全与极低的 SD 卡写入磨损。
  • 为什么用 systemd 原生守护而非在采集端套 Docker:直接访问 `/dev/i2c-1` 并配合 `systemd` 硬件级 `WatchdogSec=30s`,比在树莓派上跑特权容器更省内存、故障排查链条更短。

遇到的典型问题与工程取舍

  • 问题 1:I2C 偶发 `Remote I/O error (Errno 121)` —— 杜邦线受风扇电源干扰偶发锁死。解决:在读取层封装指数退避重试,连续 3 次失败后自动重新初始化 SMBus 句柄并剔除首帧脏数据。
  • 问题 2:SD 卡长期写入寿命担忧 —— 取舍:正常联网时数据直接走内存发往 MQTT,不写磁盘;仅在 `on_disconnect` 状态下才写入 SQLite 缓冲表,日均磁盘写入量控制在 1.2MB 以内。
  • 个人负责范围:独立完成传感器焊接接线、Python 采集守护进程、SQLite 断网重传状态机及服务端 Docker 编排。

03 如何复现与部署(硬件接线与配置)

1. 环境要求与 I2C 接线表

硬件仅需树莓派(任意带 40-Pin GPIO 型号)与 SHT30/BMP280 模块,开启 `raspi-config` 中的 I2C 接口后按以下引脚直连:

# 树莓派 40-Pin GPIO  --->  SHT30 / BMP280 模块
Pin 1 (3.3V Power)   --->  VCC (切勿接 5V)
Pin 3 (GPIO 2 / SDA) --->  SDA
Pin 5 (GPIO 3 / SCL) --->  SCL
Pin 9 (Ground)       --->  GND

# 验证总线上是否识别到 0x44 (SHT30) 与 0x76 (BMP280)
$ sudo apt install -y i2c-tools python3-smbus2 python3-paho-mqtt
$ i2cdetect -y 1

2. 节点配置示例 (`config.yaml`)

采集端核心配置项已脱敏整理于配套技术文章中,核心参数结构如下:

node_id: "pi4b-rack-01"
i2c_bus: 1
sample_interval_sec: 5.0
median_window_size: 5
mqtt:
  host: "10.0.0.10"
  port: 1883
  topic_prefix: "lab/env/rack-01"
  qos: 1
offline_buffer:
  sqlite_path: "/var/lib/pi-envnode/buffer.db"
  max_rows: 50000

公开范围与已知限制说明:本项目完整的硬件选型、MQTT 主题设计、采集代码结构与排障命令已在下方站点博文中完整公开;部分与家庭内网告警 Webhook 绑定的私有凭证保留在本地仓库。当前版本暂不支持蓝牙传感器接入。

04 开发记录与关联文章

版本演进与下一步计划

  1. v1.2 · 2026-03

    新增 SQLite WAL 本地断网环形队列与批量补传机制,解决路由器夜间重启导致的曲线断点。

  2. v1.1 · 2026-02

    加入 5 点滑动中位值滤波与连续越界去抖动告警,消除风扇启动瞬间的温度跳变误报。

  3. v1.0 · 2026-01

    完成树莓派 I2C 传感器读取与 Mosquitto MQTT 基础遥测链路跑通。

  4. Next · 规划中

    计划接入 ESP32-C3 低功耗电池节点,作为多房间无线扩展探头汇入同一 MQTT 总线。