TeddieM8/grid-monitor
GitHub: TeddieM8/grid-monitor
结合 ESP32 嵌入式硬件与数字孪生引擎的安全低压直流电力监控平台，提供实时数据采集、故障检测和能源预测功能。
Stars: 0 | Forks: 0
# Grid Monitor - 安全低压过流保护继电器
一个完整的赛博物理系统，在安全的低压直流环境中演示实时监控、故障检测和保护逻辑。作为面向可再生能源和电力系统工程职位的作品集项目而构建。
## 概述
**Grid Monitor** 是一个 SCADA 风格的监控平台，它将小型的物理太阳能装置或直流电路连接到数字孪生引擎，持续比较预期与实际性能，并在发生故障时发出警报。该系统演示了：
- **电气工程：** 传感器设计、电路保护、功率计算
- **嵌入式系统：** 具备本地缓冲和 MQTT 通信的 ESP32 固件
- **物联网与实时数据：** 传感器采集、WiFi 流传输、时序记录
- **数据工程：** ETL pipeline、时序数据库、查询优化
- **后端开发：** FastAPI、PostgreSQL、身份验证、RESTful API
- **故障检测：** 基于规则和统计的异常检测
- **机器学习：** 能源预测（可选：LSTM、XGBoost）
- **数字孪生：** 虚拟电力模型与实测真实情况的比较
- **仪表板：** 带有实时图表和警报的专业 Web UI
## 快速开始
### 硬件组装
1. 从[购物清单](docs/BOM.md)中**订购组件**（约 70–120 英镑）
2. 按照[硬件指南](docs/HARDWARE.md)**连接传感器节点**
3. 将**固件刷入** ESP32（参见[固件设置](docs/FIRMWARE.md)）
4. 在 Raspberry Pi 或本地机器上**运行后端**（参见[后端设置](docs/BACKEND.md)）
5. 在 `http://localhost:5000` **打开仪表板**
### 面向开发（无硬件）
```
# Clone 仓库
git clone https://github.com/TeddieM8/grid-monitor
cd grid-monitor
# 安装依赖
pip install -r requirements.txt
# 运行模拟器
python simulator.py
# 在另一个终端中，启动 collector
python collector.py
# 在第三个终端中，启动 dashboard
python dashboard.py
# 在浏览器中打开 http://localhost:5000
```
**模拟器** 生成带有故障注入的真实电压、电流和温度读数，因此您可以在没有硬件的情况下开发和测试整个系统。
## 架构
```
┌─────────────────────────────────────────────────────────────┐
│ Physical Layer │
├─────────────────────────────────────────────────────────────┤
│ Solar Panels / DC Circuit → INA219 + DS18B20 Sensors │
│ ↓ │
│ ESP32 Microcontroller │
│ (MQTT Publisher) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Data Pipeline │
├─────────────────────────────────────────────────────────────┤
│ MQTT Broker (Mosquitto) → Collector → PostgreSQL / SQLite │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Backend & Digital Twin │
├─────────────────────────────────────────────────────────────┤
│ FastAPI Server │
│ ├─ REST API (/readings, /alerts, /forecast) │
│ ├─ Digital Twin Engine (expected vs actual) │
│ ├─ Fault Detection (rule-based + ML) │
│ └─ Forecasting (persistence, linear regression, LSTM) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Dashboard (React / HTML) │
├─────────────────────────────────────────────────────────────┤
│ Live gauges, charts, alerts, forecast, system health │
└─────────────────────────────────────────────────────────────┘
```
## 项目结构
```
grid-monitor/
├── README.md # This file
├── HANDOFF.md # Project state & roadmap
├── requirements.txt # Python dependencies
├── shopping_list.html # Component shopping list
│
├── firmware/ # ESP32 firmware (MicroPython or C++)
│ ├── main.py # Main firmware loop
│ ├── sensors.py # Sensor reading functions
│ ├── mqtt.py # MQTT communication
│ ├── rtc.py # RTC (DS3231) for accurate timestamps
│ └── sdcard.py # SD card local buffering
│
├── backend/ # Python backend
│ ├── config.py # Shared configuration
│ ├── simulator.py # Synthetic sensor data generator
│ ├── collector.py # MQTT subscriber & DB writer
│ ├── dashboard.py # Flask web server
│ ├── twin.py # Digital twin engine
│ ├── forecast.py # Energy forecasting models
│ ├── fault_detection.py # Anomaly & fault detection
│ └── database.py # DB schema & helpers
│
├── templates/ # Web UI
│ └── dashboard.html # Dashboard (industrial SCADA style)
│
├── tests/ # Unit tests
│ ├── test_twin.py # Digital twin tests
│ ├── test_forecast.py # Forecasting tests
│ └── test_fault_detection.py # Fault detection tests
│
├── docker/ # Docker deployment
│ ├── Dockerfile # Backend container
│ ├── docker-compose.yml # Full stack (API, DB, MQTT)
│ └── mosquitto.conf # MQTT broker config
│
├── docs/ # Documentation
│ ├── HARDWARE.md # Sensor node assembly guide
│ ├── FIRMWARE.md # Firmware development & flashing
│ ├── DATABASE.md # Schema, indexing, optimization
│ ├── API.md # REST API specification
│ ├── DIGITAL_TWIN.md # Twin engine algorithms
│ ├── FORECASTING.md # ML models & training
│ ├── DEPLOYMENT.md # Docker, cloud, systemd
│ └── SHOPPING_LIST.md # Components & suppliers
│
└── cad/ # CAD models (Fusion, AutoCAD)
├── enclosure.f3d # Sensor node housing (Fusion)
├── sld.dwg # Substation single-line diagram (AutoCAD)
└── pcb/
└── overcurrent_relay.kicad # Protection relay PCB design
```
## 核心功能
### 实时监控
- 持续测量电压、电流和温度
- 1 秒采样率，延迟 < 100ms
- 具有专业工业美感的实时仪表板
- 历史数据保留和时序查询
### 故障检测
- **基于规则：** 过流持续时间逻辑（反时限保护）
- **基于统计：** 对效率比率的 z-score 异常检测
- **基于机器学习：** 孤立森林或单分类 SVM（可选）
- 自动生成警报，支持 email/SMS 钩子（可扩展）
### 数字孪生
- 基于以下因素计算预期功率输出：
- 面板规格（Pmpp、Voc、Isc、温度系数）
- 辐照度（lux → W/m²）
- 温度降额（在 STC 以上，效率损失约 0.4% / °C）
- 组件串拓扑和逆变器损耗
- 与实测输出进行对比
- 生成性能比、容量系数、健康评分
### 预测
- **持续性模型：** 朴素基线（重复之前的值）
- **线性回归：** 辐照度到功率的映射
- **随机森林：** 处理多个特征（温度、湿度、一天中的时间）
- **XGBoost：** 优化的梯度提升（如果已安装）
- **LSTM：** 用于多步提前预测的可选深度学习
- 1 小时、24 小时、7 天的预测范围及误差指标
### 本地弹性
- WiFi 不可用时的 SD 卡缓冲
- RTC (DS3231) 确保即使在断电后也能提供准确的时间戳
- 重新连接时自动刷新至后端
- 消息去重可防止重复计算
### 专业仪表板
- **深色 SCADA 主题** - 工业美学（而非 Web 2.0 气泡风格）
- **实时仪表：** 电压、电流、温度及颜色编码的状态
- **趋势图：** 滚动显示 2 小时历史记录，支持缩放/平移
- **警报面板：** 按时间排序的故障日志，带有严重程度标签
- **预测视图：** 7 天能源预测与实际对比
- **系统健康：** 性能比、累计能量、正常运行时间
## 固件设置 (ESP32)
### 前置条件
- 用于您的 ESP32 开发板的 USB 数据线
- Esptool 或 Arduino IDE
- MicroPython 或 Arduino C++（任选其一）
### 状态：设计完成，硬件测试待定
⚠️ **重要：** `firmware/` 中的固件代码已完全设计、编写文档并准备好刷入 ESP32。但是，它**尚未经过**真实硬件组件（INA219 传感器、DS18B20 温度探头、DS3231 RTC 或 SD 卡模块）的**测试**。
**当前状态：**
- ✓ 代码已编写并记录
- ✓ 已确定 MicroPython 库
- ✓ 引脚分配已敲定
- ⏳ 等待硬件组装和真实传感器测试
**后续步骤（原型组装完成后）：**
1. 将固件刷入 ESP32
2. 针对实际的 INA219 和 DS18B20 模块进行测试
3. 调试传感器读数和 MQTT 发布
4. 验证 SD 卡的本地缓冲功能
5. 根据实际性能进行优化
### MicroPython（推荐用于学习）
```
# 下载适用于 ESP32-WROOM-32 的 MicroPython firmware
# https://micropython.org/download/esp32/
# 刷入 firmware（使用 esptool）
esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash -z 0x1000 esp32-20250131-v1.24.bin
# 复制 firmware 文件到 ESP32（使用 ampy）
ampy --port /dev/ttyUSB0 put firmware/main.py
ampy --port /dev/ttyUSB0 put firmware/sensors.py
ampy --port /dev/ttyUSB0 put firmware/mqtt.py
ampy --port /dev/ttyUSB0 put firmware/rtc.py
ampy --port /dev/ttyUSB0 put firmware/sdcard.py
# 通过 serial monitor 连接并重启
```
有关详细说明，请参阅 [docs/FIRMWARE.md](docs/FIRMWARE.md)。
## 后端设置 (Linux / Raspberry Pi)
### 前置条件
- Python 3.9+
- PostgreSQL 12+（或用于开发的 SQLite）
- Mosquitto MQTT broker
- Git
### 安装
```
# Clone 仓库
git clone https://github.com/TeddieM8/grid-monitor
cd grid-monitor
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# 安装 Python 依赖
pip install -r requirements.txt
# 安装 Mosquitto（Linux）
sudo apt-get install mosquitto mosquitto-clients
# 启动 Mosquitto
mosquitto -d # daemon mode
# 设置数据库（PostgreSQL）
psql -U postgres -f docs/schema.sql
# 或者使用 SQLite（无需设置，基于文件）
sqlite3 grid_monitor.db < docs/schema.sql
```
### 运行系统
**终端 1：Collector（订阅 MQTT，写入数据库）**
```
python collector.py
```
**终端 2：Simulator（生成合成传感器数据）**
```
python simulator.py
```
**终端 3：Dashboard（Flask Web 服务器）**
```
python dashboard.py
# 打开 http://localhost:5000
```
或者使用 Docker 一次性运行所有服务：
```
docker-compose up
```
## 配置
编辑 `backend/config.py` 进行自定义：
```
# MQTT
MQTT_BROKER = "localhost"
MQTT_PORT = 1883
MQTT_TOPIC = "gridmon/site1/readings"
# 数据库
DATABASE_URL = "sqlite:///grid_monitor.db" # or PostgreSQL
# 警报阈值
OVERCURRENT_A = 5.0 # Amps
OVERCURRENT_HOLD = 3 # Consecutive samples
UNDERVOLTAGE_V = 10.8 # Volts (10% below nominal 12V)
OVERVOLTAGE_V = 13.2 # Volts (10% above nominal)
OVERTEMP_C = 70.0 # Degrees C
# 面板参数（用于 digital twin）
PANEL_PMPP = 10.0 # Watts at STC
PANEL_VMAX = 18.0 # Volts at MPPT
PANEL_TEMP_COEFFICIENT = -0.004 # %/°C (efficiency loss)
```
## API 参考
所有 endpoint 均返回 JSON。完整规范请参见 [docs/API.md](docs/API.md)。
### 健康与状态
```
GET /health
GET /api/latest
```
### 历史数据
```
GET /api/readings?hours=2
GET /api/alerts?limit=20
GET /api/forecast?horizon=24h
```
### 配置
```
GET /api/config
POST /api/config (admin only)
```
### 预测
```
GET /api/forecast/1h
GET /api/forecast/24h
GET /api/forecast/7d
```
## 测试
```
# 运行所有测试
pytest
# 运行特定测试套件
pytest tests/test_twin.py -v
# 运行覆盖率测试
pytest --cov=backend tests/
```
### 测试状态
- **单元测试：** ✓ 完成（所有 40 多个测试均通过）
- **集成测试：** 待定（需要真实硬件）
- **现场验证：** 待定（在原型部署之后）
**当前覆盖率：**
- 数字孪生物理模型：100% ✓
- 预测 pipeline：95% ✓
- 故障检测规则：100% ✓
**下一阶段（硬件组装）：**
一旦原型构建并部署完成，这些测试将：
1. 根据真实传感器数据进行验证
2. 扩展集成测试
3. 对真实故障进行性能基准测试
## 部署
### 本地机器 / Raspberry Pi
```
# 使用 systemd（推荐）
sudo cp deployment/grid-monitor.service /etc/systemd/system/
sudo systemctl start grid-monitor
sudo systemctl enable grid-monitor # Auto-start on boot
```
### Docker
```
docker-compose up -d
docker-compose logs -f dashboard
```
### 云端 (AWS / DigitalOcean)
有关容器化、环境变量和托管数据库的指导，请参阅 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)。
## 许可证
MIT 许可证 — 详情请参阅 [LICENSE](LICENSE)。
## 联系与延伸阅读
- **硬件组装：** [docs/HARDWARE.md](docs/HARDWARE.md)
- **固件开发：** [docs/FIRMWARE.md](docs/FIRMWARE.md)
- **数据库设计：** [docs/DATABASE.md](docs/DATABASE.md)
- **API 规范：** [docs/API.md](docs/API.md)
- **数字孪生理论：** [docs/DIGITAL_TWIN.md](docs/DIGITAL_TWIN.md)
- **机器学习预测：** [docs/FORECASTING.md](docs/FORECASTING.md)
- **部署与 DevOps：** [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)
如有任何问题或疑问，请提交 GitHub issue。
**旨在展示真实的工程思维：从第一性原理的电路设计到生产环境的部署。**
标签：AV绕过, ESP32, FastAPI, SCADA监控, 嵌入式系统, 数字孪生, 测试用例, 物联网, 电力系统, 请求拦截, 逆向工具