Battery Monitor for uConsole CM5

A Next.js 16 web application designed for Raspberry Pi uConsole CM5 that monitors and visualizes battery metrics in real-time.

Features

Battery Monitoring

• Real-time monitoring of AXP20x battery metrics (voltage, current, power, percentage)
• Interactive charts showing battery trends (Recharts visualization)
• Historical data storage in SQLite database with session management
• CSV export for data analysis
• Session management with custom naming and deletion
• Reads directly from Linux sysfs (/sys/class/power_supply/axp20x-battery/)

uConsole Smart Power Regulator 🔋⚡

NEW: Intelligent power management system that prevents voltage-induced system hangs when using 4G module on battery.

The Problem: The 4G modem requires minimum 3.45V to operate reliably. When battery voltage drops below this threshold, the modem can hang the entire system, requiring physical battery removal to restart.

The Solution: Unified event-driven power regulation that:

• Monitors both AC power and 4G modem states via udev events
• Adjusts CPU frequency dynamically based on power source and 4G status
• Alerts when battery voltage is critical (< 3.45V) with desktop notifications, audio alerts, and LED blinks
• Handles edge cases like service starting with AC already connected

Power Modes:

Condition	CPU Frequency	Governor	Voltage Monitoring
AC Connected	2.4GHz	ondemand	Off
Battery + 4G	1.8GHz	powersave	On (< 3.45V alerts)
Battery Only	2.0GHz	ondemand	Off

📖 Read the Full Story | Tool Guide | 中文版

Quick install:

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

Upgrade from old 4G Power Manager:

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

Uninstall:

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

Hardware Requirements

• Raspberry Pi CM5 (or CM4) in uConsole
• AXP228 Power Management IC (standard in uConsole)
• 18650 batteries (2x in parallel configuration)
• Optional: 4G expansion module

Tech Stack

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• UI: React 19, shadcn/ui components, Tailwind CSS 4
• Charts: Recharts
• Database: SQLite (better-sqlite3)
• Hardware Interface: Linux sysfs via Node.js fs

Getting Started

Installation

# Install dependencies
npm install

# Run development server
npm run dev

Open http://localhost:3000 to view the battery monitor.

Production Build

# Build for production
npm run build

# Run production server
npm start

Database

The application automatically creates battery-data.db SQLite database in the project root. It stores:

• Battery readings with timestamps
• Monitoring sessions with metadata
• Historical data for analysis

Usage

Monitoring and Recording

The Battery Monitor separates monitoring (real-time display) from recording (saving to database):

Live Monitoring:

1. Click "Start Monitoring" to begin real-time data display
2. Battery data updates every 2 seconds
3. Charts show live data (last 100 readings in memory)
4. Data is NOT saved to database while only monitoring

Recording Sessions:

1. While monitoring is active, choose recording start point:
   • "Record from now" - Start saving from this moment
   • "Record from monitoring start" - Save all buffered data since monitoring began
2. Click "Start Recording" to save data to database
3. Click "Stop Recording" to end the session (monitoring continues)
4. Click "Stop Monitoring" to stop everything

Why separate them? This lets you observe battery behavior before deciding to record, avoiding unnecessary database writes.

Exporting Data

Per-Session Export:

• Each session in the "Recording Sessions" card has a download button
• Exports all readings for that specific session as CSV

Custom Time Range Export:

1. Select start and end date/time in the "Export Custom Time Range" card
2. Click "Load Data" to preview the data in charts
3. Click "Export CSV" to download without loading first
4. Filename includes the date range automatically

Historical Data Viewing

1. Click any session name in "Recording Sessions" to view its data
2. Or use "Export Custom Time Range" → "Load Data" for arbitrary ranges
3. Charts display historical trends
4. Click "Back to Live View" to return to real-time monitoring

Session Management

1. View all sessions in the "Recording Sessions" card
2. Click session names to view their data
3. Click edit icon to rename sessions
4. Click download icon to export session data
5. Click delete icon to remove sessions (with confirmation)

API Endpoints

• GET /api/battery - Current battery data
  • Add ?save=true to save reading to database
• GET /api/battery/history?start=<ISO>&end=<ISO> - Historical data by time range
• GET /api/battery/sessions - List all monitoring sessions
• GET /api/battery/sessions/:id - Get readings for specific session
• PATCH /api/battery/sessions/:id - Update session name
• DELETE /api/battery/sessions/:id - Delete session and readings

Development Commands

npm run dev      # Development server with hot reload
npm run build    # Production build
npm start        # Production server
npm run lint     # Run ESLint

Project Structure

battery-monitor/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/battery/        # API routes
│   │   ├── layout.tsx          # Root layout
│   │   └── page.tsx            # Home page
│   ├── components/
│   │   ├── BatteryMonitor.tsx  # Main monitoring component
│   │   └── ui/                 # shadcn/ui components
│   └── lib/
│       ├── db.ts               # SQLite database utilities
│       └── utils.ts            # Helper functions
├── scripts/                    # uConsole Smart Power Regulator
│   ├── uconsole-power-regulator.sh      # Main power regulator
│   ├── uconsole-power-daemon.sh         # Background monitoring daemon
│   ├── voltage-monitor.sh               # Voltage monitoring script
│   ├── voltage-alert-notify.sh          # Multi-method alerting
│   ├── voltage-monitor-control.sh       # Monitor control
│   ├── install-uconsole-power-regulator.sh
│   └── 99-uconsole-power-regulator.rules
├── STORY.md                    # Development story and voltage discovery
├── TOOL-GUIDE.md               # Complete user guide
└── public/                     # Static assets

Configuration

Path Aliases

The project uses @/* to reference src/*:

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

TypeScript

• Strict mode enabled
• Path alias @/* maps to ./src/*
• Module resolution: bundler

Troubleshooting

Battery Data Not Available

The application requires AXP20x hardware. On systems without this hardware, the API will return 500 errors. This is expected behavior on non-uConsole systems.

System Hangs with 4G Module

If your uConsole hangs when using the 4G module on battery:

1. Install the uConsole Smart Power Regulator (see installation section above)
2. Use the Battery Monitor to check voltage levels during 4G usage
3. Consider upgrading to batteries with better voltage retention (see TOOL-GUIDE.md for battery recommendations)
4. The regulator will alert you if voltage drops below 3.45V

Database Issues

If you encounter database errors, you can safely delete battery-data.db and restart the application. It will create a new database automatically.

Contributing

This project is designed specifically for the uConsole CM5 hardware. Contributions are welcome, especially:

• Performance optimizations
• Additional battery metrics
• UI/UX improvements
• Power management enhancements

License

MIT

Acknowledgments

• Built for ClockworkPi uConsole
• UI components from shadcn/ui
• Charts powered by Recharts