Battery Tracker

A self-hosted web app for tracking rechargeable batteries — where they are, what condition they're in, and which devices they're installed in.

Built with Flask + SQLAlchemy. Runs on a Raspberry Pi or any Linux box with a systemd user service.

Features

Batteries

Add batteries in bulk (auto-generated labels like "Eneloop 001", "Eneloop 002")
Track status: Available, Installed, Retired
Store metadata: size (AA/AAA/18650/…), chemistry (NiMH/Li-ion/…), capacity, tested capacity, charge cycles, purchase date, storage location, notes
Visual health indicator when tested capacity is recorded (good/warn/bad)
Retire and unretire batteries

Devices

Add devices with a name, battery slot count, type (Remote Control, Flashlight, Sensor, …), and notes
Install batteries into devices — by brand/quantity or by picking a specific battery
Bulk install multiple batteries at once from the dashboard
Mixed-brand warning when batteries from different brands share a device
Edit device details in-place

Dashboard

Overview stats (total / available / installed / retired)
Full battery table with client-side filtering by status, brand, size, storage location, and free-text search
Column picker (Chemistry, Capacity, Storage, Purchase Date, Cycles) stored in localStorage
Quick-assign available batteries to a device without leaving the page
Bulk actions: Unassign, Retire, Delete, Set Field (storage location or brand), Install in Device

UI

Mobile-friendly: card-style table rows on small screens, full-width filter controls, stacked form buttons
Dark mode — follows the OS system preference automatically (prefers-color-scheme)
No JavaScript framework — vanilla JS only

Tech Stack

Layer	Technology
Web framework	Flask 3.x
ORM	SQLAlchemy 2.x (raw session, no Flask-SQLAlchemy)
Database	SQLite (dev) / MariaDB (prod)
WSGI server	Waitress
Process manager	systemd user service
Tests	pytest (45 acceptance tests)

Setup

Prerequisites

Python 3.10+
python3-venv

Install

git clone <repo-url>
cd battery-tracker-app

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run (development)

source .venv/bin/activate
flask run
# → http://127.0.0.1:5000

Run (production — systemd user service)

bash sbin/install-service.sh   # prompts for host/port, installs and enables the service
systemctl --user start battery-tracker
systemctl --user status battery-tracker
journalctl --user -u battery-tracker -f

Database

SQLite is used by default (batteries.db in the project root). To switch to MariaDB, set the environment variable before starting:

export DATABASE_URL="mysql+pymysql://user:pass@host/dbname"

See MIGRATION.md for migrating an existing SQLite database to MariaDB.

Seed data (optional)

source .venv/bin/activate
python seed.py

Running Tests

source .venv/bin/activate
pytest tests/ -v

Tests use a fresh temporary SQLite database per test and exercise the full HTTP stack.

Project Structure

app.py                  Flask app factory + all routes
models.py               SQLAlchemy models (Battery, Device)
config.py               Database URL config
seed.py                 Optional seed data script
migrate_to_mariadb.py   SQLite → MariaDB migration script
MIGRATION.md            MariaDB migration procedure
requirements.txt
sbin/
  install-service.sh    systemd user service installer
templates/
  base.html             Layout, CSS variables, dark mode, nav
  dashboard.html        Battery list with filters and bulk actions
  battery_add.html      Add batteries form
  battery_detail.html   Battery detail + edit
  battery_delete.html   Delete confirmation
  assign.html           Assign battery to device
  device_list.html      Device list with type filter
  device_add.html       Add device form
  device_detail.html    Device detail + install + edit
tests/
  conftest.py           pytest fixtures
  test_acceptance.py    45 acceptance tests

4.1 KiB Raw Blame History