140 lines
4.1 KiB
Markdown
140 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
git clone <repo-url>
|
|
cd battery-tracker-app
|
|
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Run (development)
|
|
|
|
```bash
|
|
source .venv/bin/activate
|
|
flask run
|
|
# → http://127.0.0.1:5000
|
|
```
|
|
|
|
### Run (production — systemd user service)
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
export DATABASE_URL="mysql+pymysql://user:pass@host/dbname"
|
|
```
|
|
|
|
See `MIGRATION.md` for migrating an existing SQLite database to MariaDB.
|
|
|
|
### Seed data (optional)
|
|
|
|
```bash
|
|
source .venv/bin/activate
|
|
python seed.py
|
|
```
|
|
|
|
---
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
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
|
|
```
|