a tiny lil desktop widget that watches over ur battery so u don't have to uwu
a cute lil dark-themed battery monitor that reads directly from the linux kernel (/sys/class/power_supply/) and shows u everything u need to know about ur battery pack ˘◡˘
- 🔋 battery widget — a custom drawn battery graphic with a gradient fill that changes color as charge drops (green → yellow → red) plus a lil ⚡ bolt when charging !!
- 📊 pack voltage — total pack voltage in volts
- 🔬 per-cell voltage — pack voltage divided by cell count (configurable uwu)
- 🌡️ temperature — battery temp in °C (when ur kernel provides it)
- ⏱️ time estimate — estimated time until full or empty, calculated from energy + current draw
- 📈 history chart — a scrolling line graph of the last 10 minutes of charge history
- 💾 persistent settings — remembers ur cell count between restarts !!
- 🧠 auto cell detection — on first launch it estimates ur cell count from voltage + state of charge using the li-ion discharge curve (so smart omg)
╭──────────────────────────────────────── BATTERY MONITOR ─ ✕ ╮
│ │
│ ┌──────────────────────┐┐ Status 🔋 Discharging │
│ │ ████████████░░░░ 94%│┤ Pack Voltage 8.371 V │
│ └──────────────────────┘┘ Per Cell 4.186 V / cell │
│ Temperature – │
│ Time Left 3h 12m │
│ │
│ CHARGE HISTORY │
│ 100 ┤ │
│ 94 ┤╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮ │
│ └────────────────────────────────────────── time │
│ │
│ Cells per pack: ┌─┐ (Li-ion / LiPo: 3.0 – 4.2 V/cell) │
│ │2│ │
│ └─┘ │
╰──────────────────────────────────────────────────────────────────╯
(uses the catppuccin mocha color palette 🎨)
- 🐧 linux (reads from
/sys/class/power_supply/) - 🐍 python 3.11+
- a battery (obviously uwu)
pip install PyQt6 pyqtgraph PyQt6-Chartsor with a venv if u prefer keeping things tidy ˘ᵕ˘
python -m venv .venv
source .venv/bin/activate
pip install PyQt6 pyqtgraph PyQt6-Chartspython3 main.pythat's it !! it'll auto-detect ur battery and even guess the cell count for u on first launch (✿◠‿◠)
use the lil spinbox at the bottom to set how many cells ur pack has. it saves automatically to ~/.config/batterymonitor/config.json so u never have to set it again uwu
on the very first run, battery monitor looks at ur current voltage and state of charge and uses the li-ion discharge curve to estimate how many cells u have. for example — if ur pack is at 95% charge and reads 8.37V, it figures out that's ~4.18V/cell → 2 cells. pretty smart for a lil app ehe
batteryMonitor/
├── main.py # 🚀 entry point
├── requirements.txt # 📦 dependencies
└── battery_monitor/
├── data_source.py # 🔍 reads /sys/class/power_supply/
├── battery_widget.py # 🎨 custom QPainter battery graphic
├── chart_widget.py # 📈 scrolling history chart
├── settings_widget.py # ⚙️ cell count spinbox
├── main_window.py # 🪟 frameless rounded window + layout
├── config.py # 💾 persistent json config
└── theme.py # 🎨 catppuccin mocha colors + stylesheet
| chemistry | v/cell range | notes |
|---|---|---|
| li-ion / lipo | 3.0 – 4.2V | ✅ full curve support for cell estimation |
| lifepo4 | 2.5 – 3.65V | |
| lead acid | ~2V/cell | |
| laptop battery | varies | ✅ works great, set cells to 1 for pack-level readings |
/sys/class/power_supply/BAT0/
├── capacity → charge percentage
├── voltage_now → microvolts
├── current_now → microamps
├── status → Charging / Discharging / Full
├── energy_now → microwatt-hours remaining
├── energy_full → microwatt-hours at full charge
├── temp → temperature (tenths of °C)
└── time_to_empty_now → kernel time estimate (when available)
time estimates use kernel-provided values when available, and fall back to energy_remaining ÷ power_draw when not. polls every 5 seconds — lightweight and battery friendly !! (ironic i know)
- 🌡️ no temperature? — not all kernels/batteries expose
temp. if urs doesn't, it'll just show–and that's ok !! - ⏱️ time shows
–? — means current draw is ~0 (fully charged, or kernel can't measure it). totally normal when plugged in ˘◡˘ - 🔌 no battery detected? — check that
/sys/class/power_supply/BAT0(or similar) exists on ur system
MIT — do whatever u want with it (づ￣ ³￣)づ
made with ♡ and way too much caffeine