# MPPT 太阳能充电控制器监控系统 基于 C 语言的 MPPT（最大功率点跟踪）太阳能充电控制器实时监控与数据采集系统。通过 **Modbus TCP** 采集设备运行数据，使用 **Mongoose** 提供 Web 仪表盘与 REST API，并将历史数据持久化到 **SQLite3**，支持多设备监控与远程参数下发。 - 协议标准：DM 系列 ModBus 485 协议 V2.1（Modbus RTU over TCP） - 支持平台：Ubuntu 24.04（x86_64）/ 树莓派 5 8G（aarch64） - 当前版本：v2.4.0 --- ## 目录 - [功能特性](#功能特性) - [系统架构](#系统架构) - [目录结构](#目录结构) - [运行环境](#运行环境) - [快速开始](#快速开始) - [配置说明](#配置说明) - [Web 界面](#web-界面) - [REST API](#rest-api) - [Modbus 协议](#modbus-协议) - [数据库](#数据库) - [systemd 后台部署](#systemd-后台部署) - [文档索引](#文档索引) - [常见问题](#常见问题) - [许可证](#许可证) --- ## 功能特性 - **实时数据采集**：每 2 秒轮询一次设备（可配置），读取电池电压、光伏电压、充电电流、功率、电量、温度、故障码、充电状态、设备类型等全部运行参数。 - **多设备支持**：单网关下最多支持 16 台 MPPT 设备（地址 1~247），可在配置文件中指定设备地址列表。 - **远程参数设置**：通过 Web 界面下发设备参数，自动适配 **FC 0x06（写单寄存器）** 与 **FC 0x10（写多寄存器）**，内置参数范围校验。 - **历史数据存储**：按可配置间隔（默认 10 秒）将数据写入 SQLite3，支持数据保留周期自动清理。 - **历史数据查询**：按时间范围查询，趋势图可视化 + 分页数据表格；默认查询区间为中国时区（UTC+8）前一天至今。 - **Web 仪表盘**：实时监控、历史查询、设备设置三个标签页，响应式布局，浏览器直接访问。 - **可靠连接**：10 秒连接/读写超时（可配置），断线自动重连；TCP 缓冲区残留清理，避免地址不匹配。 - **Web 服务自愈**：HTTP 服务异常退出后自动重新监听，配合 systemd 实现进程级与线程级双重保障。 - **并发安全**：互斥锁保护共享数据与 Socket 收发，串行化轮询线程与写入线程。 --- ## 系统架构 ``` ┌──────────────────────────────────────────────────────────┐ │ mppt_monitor 进程 │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Modbus 轮询 │ │ 数据存储 │ │ 信号处理 │ │ │ │ 线程 │ │ 线程 │ │ SIGINT/TERM │ │ │ │ (2 秒/次) │ │ (10 秒/次) │ │ 优雅退出 │ │ │ └──────┬───────┘ └──────┬───────┘ └──────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌────────────────────────────────┐ ┌──────────────┐ │ │ │ 共享数据 + sock_mutex │ │ SQLite3 DB │ │ │ └────────────────────────────────┘ │ (WAL 模式) │ │ │ ▲ └──────────────┘ │ │ │ sock_mutex │ │ ┌──────┴───────────────────────────────────────────┐ │ │ │ Mongoose HTTP 服务器（自愈线程） │ │ │ │ REST API / 静态文件 www/index.html │ │ │ └──────────────────────────────────────────────────┘ │ └───────────────────────────┬──────────────────────────────┘ │ Modbus TCP (RTU over TCP) ▼ discover.zhonjin.com:40635 （MPPT 设备网关） │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ MPPT #1 MPPT #2 ... MPPT #16 ``` 三个工作线程与一个 HTTP 事件循环： | 线程 | 职责 | 周期 | |------|------|------| | Modbus 轮询线程 | 连接/重连设备、读取 Input/Output 寄存器、更新共享数据 | 2 秒（可配置） | | 数据存储线程 | 将最新数据批量写入 SQLite，清理过期数据 | 10 秒（可配置） | | HTTP 事件循环 | 处理 REST 请求与静态页面，异常自动重启 | 事件驱动 | | 主线程 | 周期打印摘要、等待退出信号 | 10 秒 | --- ## 目录结构 ``` mppt_monitor/ ├── src/ # 应用源代码 │ ├── main.c # 主程序：线程、信号处理、启动编排 │ ├── modbus_client.h/.c # Modbus TCP 客户端（CRC、读写、参数校验） │ ├── web_server.h/.c # Mongoose HTTP 服务与 REST API │ ├── config.h/.c # INI 配置文件解析 │ └── db.h/.c # SQLite3 历史数据存储与查询 ├── www/ │ └── index.html # Web 仪表盘（Chart.js，单文件） ├── lib/ # 第三方库（随仓库提供，无需联网下载） │ ├── cJSON-1.7.19/ # cJSON 1.7.19 │ └── mongoose-7.23/ # Mongoose 7.23 ├── config.ini # 运行时配置文件 ├── Makefile # 构建脚本 ├── INSTALL.md # 快速安装指南 ├── CHANGELOG.md # 变更日志（持续更新） ├── TECHNICAL.md # 技术方案文档（持续更新） └── FAQ.md # 问答归档（持续更新） ``` > 说明：本仓库根目录的 `README.md`、`LICENSE`、`.gitignore` 为仓库级文件；实际工程位于 `mppt_monitor/` 子目录。 --- ## 运行环境 ### 硬件 - 主机：PC / 工控机 / 树莓派 5（建议 4GB 以上内存） - 被控设备：DM 系列 MPPT 太阳能充电控制器（经 Modbus TCP 网关接入） - 网络：主机需能访问设备网关地址与端口 ### 软件 - 操作系统：Ubuntu 24.04 LTS 或 Raspberry Pi OS（64 位） - 编译器：GCC（支持 C11） - 构建工具：GNU Make - 依赖库：SQLite3（运行库 + 开发头文件） - 可选：OpenSSL 3.x（TLS 支持，构建时自动探测） - 浏览器：Chrome / Edge / Firefox（用于访问仪表盘） --- ## 快速开始 ### 1. 安装依赖 **Ubuntu 24.04：** ```bash sudo apt-get update sudo apt-get install -y build-essential make libsqlite3-dev pkg-config # 可选 OpenSSL sudo apt-get install -y libssl-dev ``` **树莓派 5（Raspberry Pi OS 64 位）：** ```bash sudo apt-get update sudo apt-get install -y build-essential make libsqlite3-dev pkg-config libssl-dev ``` ### 2. 获取代码并编译 ```bash git clone https://git.zhonjin.com:40717/steven_roc/mppt_monitor.git cd mppt_monitor/mppt_monitor # 工程目录 make ``` 构建产物为 `build/mppt_monitor`。第三方库（cJSON、Mongoose）已随仓库提供，无需联网下载。 常用构建命令： ```bash make # 编译 make clean # 清理构建产物 make run # 编译并运行 make debug # 带调试符号与 AddressSanitizer ``` ### 3. 修改配置 按需编辑 `config.ini`（主要确认设备地址、网关地址、Web 端口）。默认配置： - 网关：`discover.zhonjin.com:40635` - 设备地址：`1` - 轮询间隔：2 秒 - Web 端口：`8085` ### 4. 运行 ```bash ./build/mppt_monitor ``` 启动后浏览器访问： ``` http://<主机IP>:8085 ``` > 若设置了环境变量 `DEPLOY_RUN_PORT`，Web 端口会以该变量为准（用于沙箱/容器部署）。 --- ## 配置说明 配置文件 `config.ini` 采用 INI 格式，分节如下： ```ini [modbus] host = discover.zhonjin.com # 设备网关域名或 IP port = 40635 # 网关端口 timeout_sec = 10 # 连接 / 读写超时（秒） poll_interval_sec = 2 # 轮询间隔（秒） [storage] db_path = mppt_data.db # SQLite 数据库文件路径 interval_sec = 10 # 历史数据存储间隔（秒） retention_days = 365 # 数据保留天数（超过自动清理，0 表示永久） [server] port = 8085 # Web 服务端口（DEPLOY_RUN_PORT 优先） page_size = 20 # 历史查询默认每页条数 [devices] device_addrs = 1 # 设备地址列表，逗号分隔，如 1,2,3 ``` 修改配置后需重启程序生效。 --- ## Web 界面 浏览器访问 `http://<主机IP>:8085`，包含三个标签页： 1. **实时监控（Real-time Monitor）** - 展示各设备电池电压、光伏电压、充电电流、功率、电量、温度、充电状态、故障码等 - 数据按轮询周期自动刷新 2. **历史查询（History Query）** - 日期时间范围选择器，默认中国时区前一天至今 - Chart.js 趋势曲线 + 分页数据表格 3. **设备设置（Device Settings）** - 选择设备与参数，输入值后下发 - 提交前做参数范围校验，写入结果即时提示 --- ## REST API 所有接口返回 `application/json`，并支持 CORS（跨域访问）。 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/health` | 健康检查（服务存活、连接状态） | | GET | `/api/status` | 系统运行状态汇总 | | GET | `/api/data` | 所有设备最新实时数据 | | GET | `/api/devices` | 已配置设备列表 | | GET | `/api/settings?device_addr=¶m=` | 查询指定设备指定参数当前值 | | POST | `/api/settings` | 下发设备参数 | | GET | `/api/history` | 历史数据分页查询 | | GET | `/api/history/stats` | 历史数据统计信息 | ### 查询历史数据 ``` GET /api/history?device_addr=1&start=&end=&page=1&page_size=20 ``` ### 下发参数 ```bash curl -X POST http://<主机IP>:8085/api/settings \ -H 'Content-Type: application/json' \ -d '{"device_addr": 1, "param": "battery_type", "value": 4}' ``` 请求字段： | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | `device_addr` | number | 是 | 设备地址（1~247） | | `param` | string | 是 | 参数标识（见协议寄存器映射） | | `value` | number | 是 | 目标值 | 成功响应： ```json {"success": true, "device_addr": 1, "param": "battery_type", "value": 4} ``` 失败响应： ```json {"success": false, "error": "错误原因"} ``` --- ## Modbus 协议 - 传输方式：Modbus RTU over TCP（RTU 帧封装在 TCP 连接上，帧尾带 CRC-16） - 校验：CRC-16/Modbus（多项式 0xA001，初值 0xFFFF，低字节在前） - 功能码： | 功能码 | 用途 | |--------|------| | 0x04 | 读 Input Register（运行数据，只读） | | 0x03 | 读 Holding/Output Register（可设置参数） | | 0x06 | 写单个 Holding Register（单参数下发，优先使用） | | 0x10 | 写多个 Holding Register（设备不支持 0x06 时回退） | 示例（读 10 个 Input 寄存器，设备地址 1）： ``` 请求：01 04 00 00 00 0A 70 0D 响应：01 04 14 01 0C 01 81 00 10 00 07 00 2E 00 14 00 60 00 02 00 01 00 3C E9 F1 ``` 完整寄存器地址表、读写格式、异常码与参数取值范围详见 **TECHNICAL.md** 与协议文档。 **写寄存器双通道自适应策略：** 1. 优先发送 FC 0x06（写单寄存器，响应为请求回显，共 8 字节）； 2. 若设备回异常码"功能不支持 / 地址非法"，再回退 FC 0x10（写多寄存器，正常响应 8 字节）； 3. 每条指令前保留总线空闲间隔，配合 `sock_mutex` 串行化，避免帧交错。 --- ## 数据库 - 引擎：SQLite3，单文件（默认 `mppt_data.db`） - 模式：开启 **WAL**（Write-Ahead Logging），提升并发读写性能 - 优化：在时间与设备地址字段建立索引 - 维护：按 `retention_days` 自动清理过期数据 历史记录表按"设备地址 + 时间戳"存储每次采集的全部参数，供趋势图与分页查询使用。详细表结构见 **TECHNICAL.md**。 --- ## systemd 后台部署 生产环境建议用 systemd 管理进程，实现开机自启与异常自动重启。 1. 创建服务文件 `/etc/systemd/system/mppt-monitor.service`： ```ini [Unit] Description=MPPT Solar Charge Controller Monitor After=network-online.target Wants=network-online.target [Service] Type=simple WorkingDirectory=/opt/mppt_monitor ExecStart=/opt/mppt_monitor/build/mppt_monitor Restart=always RestartSec=5 Environment=DEPLOY_RUN_PORT=8085 [Install] WantedBy=multi-user.target ``` 2. 部署并启用： ```bash sudo cp -r . /opt/mppt_monitor sudo systemctl daemon-reload sudo systemctl enable --now mppt-monitor sudo systemctl status mppt-monitor journalctl -u mppt-monitor -f # 查看日志 ``` > 树莓派部署的完整步骤（含系统烧录、网络、防火墙、时区配置）见 **TECHNICAL.md** 树莓派章节。 --- ## 文档索引 工程目录 `mppt_monitor/` 下提供以下持续更新文档： | 文档 | 内容 | |------|------| | [INSTALL.md](mppt_monitor/INSTALL.md) | 快速安装与运行指南 | | [CHANGELOG.md](mppt_monitor/CHANGELOG.md) | 版本变更与每次 bug 修复详细说明 | | [TECHNICAL.md](mppt_monitor/TECHNICAL.md) | 完整技术方案：架构、协议、API、数据库、编译配置、Ubuntu/树莓派/Docker 部署、故障排查 | | [FAQ.md](mppt_monitor/FAQ.md) | 历史问题与排查结论归档，按分类累计追加 | --- ## 常见问题 - **写入提示 "Empty request body"**：已在新版本修复。POST 需携带合法 JSON 与 `Content-Type: application/json`；新版本含 body 解析回退机制。 - **写入一直失败**：新版本默认使用 FC 0x06 并在需要时回退 FC 0x10，兼容更多固件；请同时确认参数值在允许范围内。 - **读不到数据 / 连接被立即断开**：优先排查网络可达性与服务端 **IP 白名单/授权**。可在主机上执行 `nc -vz discover.zhonjin.com 40635` 检测端口；若 TCP 能连但秒断，多为访问授权限制。 - **历史数据查不到**：确认存储间隔配置、数据库路径可写，并确认查询时间范围内程序在持续运行。 - **编译报 `sqlite3.h: No such file`**：安装开发包 `sudo apt-get install libsqlite3-dev`。 更多排查步骤见 [FAQ.md](mppt_monitor/FAQ.md)。 --- ## 许可证 详见 [LICENSE](LICENSE)。 第三方组件版权归各自所有者： - cJSON 1.7.19 - Mongoose 7.23（注意其商用授权条款） - SQLite3（公有领域） - Chart.js（用于 Web 仪表盘）