battery-monitor/README_CN.md

uConsole CM5 电池监控工具

为 Raspberry Pi uConsole CM5 设计的 Next.js 16 Web 应用程序，可实时监控和可视化电池指标。

功能特性

电池监控

• 实时监控 AXP20x 电池指标（电压、电流、功率、电量百分比）
• 交互式图表 显示电池趋势（Recharts 可视化）
• 历史数据存储 SQLite 数据库，支持会话管理
• CSV 导出 用于数据分析
• 会话管理 支持自定义命名和删除
• 直接从 Linux sysfs 读取数据 (/sys/class/power_supply/axp20x-battery/)

uConsole 智能电源调节器 🔋⚡

新功能：智能电源管理系统，防止使用 4G 模块时因电压过低导致的系统死机。

问题：4G 调制解调器需要最低 3.45V 才能可靠运行。当电池电压降至此阈值以下时，调制解调器可能会导致整个系统死机，需要物理拔出电池才能重启。

解决方案：统一的事件驱动电源调节系统：

• 监控 AC 电源和 4G 调制解调器状态 通过 udev 事件
• 动态调整 CPU 频率 基于电源和 4G 状态
• 电池电压临界告警 (< 3.45V) 通过桌面通知、音频提示和 LED 闪烁
• 处理边缘情况 如服务启动时 AC 已连接

电源模式：

条件	CPU 频率	调节器	电压监控
AC 已连接	2.4GHz	ondemand	关闭
电池 + 4G	1.8GHz	powersave	开启 (< 3.45V 告警)
仅电池	2.0GHz	ondemand	关闭

📖 阅读完整故事 | 工具指南 | English

快速安装：

cd scripts
sudo ./install-uconsole-power-regulator.sh install

从旧版 4G 电源管理器升级：

cd scripts
sudo ./install-uconsole-power-regulator.sh upgrade

卸载：

cd scripts
sudo ./install-uconsole-power-regulator.sh uninstall

硬件要求

• Raspberry Pi CM5（或 CM4）在 uConsole 中
• AXP228 电源管理芯片（uConsole 标配）
• 18650 电池 （2 节并联配置）
• 可选：4G 扩展模块

技术栈

• 框架：Next.js 16（App Router）
• 语言：TypeScript
• UI：React 19、shadcn/ui 组件、Tailwind CSS 4
• 图表：Recharts
• 数据库：SQLite（better-sqlite3）
• 硬件接口：通过 Node.js fs 访问 Linux sysfs

快速开始

安装

# 安装依赖
npm install

# 运行开发服务器
npm run dev

打开 http://localhost:3000 查看电池监控界面。

生产构建

# 生产构建
npm run build

# 运行生产服务器
npm start

数据库

应用程序会在项目根目录自动创建 battery-data.db SQLite 数据库。它存储：

• 带时间戳的电池读数
• 监控会话及元数据
• 用于分析的历史数据

使用方法

监控和记录

电池监控工具将监控（实时显示）和记录（保存到数据库）分离：

实时监控：

1. 点击**"开始监控"**开始实时数据显示
2. 电池数据每 2 秒更新一次
3. 图表显示实时数据（内存中最后 100 个读数）
4. 仅监控时数据不会保存到数据库

记录会话：

1. 监控激活时，选择记录起始点：
   • "从现在开始记录" - 从此刻开始保存
   • "从监控开始记录" - 保存自监控开始以来的所有缓冲数据
2. 点击**"开始记录"**将数据保存到数据库
3. 点击**"停止记录"**结束会话（监控继续）
4. 点击**"停止监控"**停止所有操作

为什么分离？ 这让您可以在决定记录之前观察电池行为，避免不必要的数据库写入。

导出数据

按会话导出：

• "记录会话"卡片中的每个会话都有下载按钮
• 导出该特定会话的所有读数为 CSV

自定义时间范围导出：

1. 在"导出自定义时间范围"卡片中选择开始和结束日期/时间
2. 点击**"加载数据"**在图表中预览数据
3. 点击**"导出 CSV"**直接下载而不先加载
4. 文件名自动包含日期范围

查看历史数据

1. 在"记录会话"中点击任何会话名称查看其数据
2. 或使用"导出自定义时间范围"→"加载数据"查看任意范围
3. 图表显示历史趋势
4. 点击**"返回实时视图"**返回实时监控

会话管理

1. 在**"记录会话"**卡片中查看所有会话
2. 点击会话名称查看其数据
3. 点击编辑图标重命名会话
4. 点击下载图标导出会话数据
5. 点击删除图标删除会话（需确认）

API 端点

• GET /api/battery - 当前电池数据
  • 添加 ?save=true 将读数保存到数据库
• GET /api/battery/history?start=<ISO>&end=<ISO> - 按时间范围的历史数据
• GET /api/battery/sessions - 列出所有监控会话
• GET /api/battery/sessions/:id - 获取特定会话的读数
• PATCH /api/battery/sessions/:id - 更新会话名称
• DELETE /api/battery/sessions/:id - 删除会话及读数

开发命令

npm run dev      # 开发服务器（热重载）
npm run build    # 生产构建
npm start        # 生产服务器
npm run lint     # 运行 ESLint

项目结构

battery-monitor/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/battery/        # API 路由
│   │   ├── layout.tsx          # 根布局
│   │   └── page.tsx            # 主页
│   ├── components/
│   │   ├── BatteryMonitor.tsx  # 主监控组件
│   │   └── ui/                 # shadcn/ui 组件
│   └── lib/
│       ├── db.ts               # SQLite 数据库工具
│       └── utils.ts            # 辅助函数
├── scripts/                    # uConsole 智能电源调节器
│   ├── uconsole-power-regulator.sh      # 主电源调节器
│   ├── uconsole-power-daemon.sh         # 后台监控守护进程
│   ├── voltage-monitor.sh               # 电压监控脚本
│   ├── voltage-alert-notify.sh          # 多方式告警
│   ├── voltage-monitor-control.sh       # 监控控制
│   ├── install-uconsole-power-regulator.sh
│   └── 99-uconsole-power-regulator.rules
├── STORY.md                    # 开发故事和电压发现
├── TOOL-GUIDE_CN.md            # 完整用户指南（中文）
└── public/                     # 静态资源

配置

路径别名

项目使用 @/* 引用 src/*：

import { Button } from '@/components/ui/button';
import { cn } from '@/lib/utils';

TypeScript

• 启用严格模式
• 路径别名 @/* 映射到 ./src/*
• 模块解析：bundler

故障排除

电池数据不可用

应用程序需要 AXP20x 硬件。在没有此硬件的系统上，API 将返回 500 错误。这在非 uConsole 系统上是预期行为。

4G 模块导致系统死机

如果您的 uConsole 在使用电池供电的 4G 模块时死机：

1. 安装 uConsole 智能电源调节器（见上面的安装部分）
2. 使用电池监控工具检查 4G 使用期间的电压水平
3. 考虑升级到电压保持性更好的电池（参见 TOOL-GUIDE_CN.md 了解电池推荐）
4. 调节器将在电压降至 3.45V 以下时提醒您

数据库问题

如果遇到数据库错误，可以安全地删除 battery-data.db 并重启应用程序。它会自动创建新数据库。

贡献

本项目专为 uConsole CM5 硬件设计。欢迎贡献，特别是：

• 性能优化
• 额外的电池指标
• UI/UX 改进
• 电源管理增强

许可证

MIT

致谢

• 为 ClockworkPi uConsole 构建
• UI 组件来自 shadcn/ui
• 图表由 Recharts 提供