diff --git a/README.md b/README.md index 968b58a..a4d576c 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,26 @@ -# Battery Tracker +
+ Battery Tracker +

Battery Tracker

+

Stop losing track of your batteries.

+

A fast, self-hosted web app that tells you exactly where every rechargeable battery is,
+ how healthy it is, and when it was last charged — all from any device on your network.

+
-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. +## Why Battery Tracker? + +Rechargeable batteries are everywhere — remotes, flashlights, sensors, toys, tools. Without a system, you end up guessing which batteries are dead, buying new ones you didn't need, and finding half-charged stragglers rattling around a drawer. + +Battery Tracker gives you a single source of truth: + +- **Know where every battery is.** Each battery is assigned to a device or a storage location. No more mystery batteries. +- **Track health over time.** Log capacity tests and see a trend chart. Spot batteries that are degrading before they let you down. +- **Never forget to charge.** Log charge events, track charge cycles, and see at a glance which batteries are running low. +- **Works with Home Assistant.** If you already have smart battery sensors, Battery Tracker will pull the live percentage automatically — no manual updates needed. +- **Runs on a Pi.** Lightweight enough for a Raspberry Pi Zero. No cloud, no subscription, no data leaving your home. + +--- ## Features @@ -10,34 +28,40 @@ Built with Flask + SQLAlchemy. Runs on a Raspberry Pi or any Linux box with a sy - 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) -- Battery percentage field — set manually or synced from Home Assistant; resets to 100% when a charge is logged +- Visual health indicator when tested capacity is recorded (good / warn / bad) +- Battery percentage — set manually or synced live from Home Assistant; resets to 100% when a charge is logged - 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 +- Install batteries into devices — by brand/quantity or by picking specific batteries - Bulk install multiple batteries at once from the dashboard - Mixed-brand warning when batteries from different brands share a device -- Link a device to a Home Assistant battery sensor to automatically track charge level -- Edit device details in-place +- Link a device to a Home Assistant battery sensor for automatic live percentage tracking ### Dashboard - Overview stats (total / available / installed / retired) + **Low Battery** count when any battery is below 20% +- Charge summary: total charge events and events in the last year - 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, Battery %) 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 +### History & Charts +- **Capacity history** — track tested capacity over time with a trend chart; full log in a modal with year filter and pagination +- **Charge history** — log every charge event; full log in a modal with year filter and pagination +- **Percentage history** — see a live chart of battery percentage over time; full log in a modal + ### Home Assistant Integration (optional) - Link any device to a Home Assistant entity (e.g. `sensor.tv_remote_battery`) -- A background poller fetches the current percentage on a configurable interval (default 5 min) and updates all installed batteries in that device +- Background poller fetches the current percentage on a configurable interval (default 5 min) and updates all installed batteries in that device - Low-battery warning badge (< 20%) on the dashboard, device detail, and battery detail pages - Fully optional — when `HOMEASSISTANT_URL` is not set the app works exactly as before ### 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`) +- **PWA** — installable on Android, iOS, and desktop; works as a home screen app +- **Mobile-friendly** — card-style table rows on small screens, full-width filter controls, stacked form buttons +- **Dark mode** — follows OS system preference automatically (`prefers-color-scheme`) - No JavaScript framework — vanilla JS only --- @@ -51,7 +75,7 @@ Built with Flask + SQLAlchemy. Runs on a Raspberry Pi or any Linux box with a sy | Database | SQLite (dev) / MariaDB (prod) | | WSGI server | Waitress | | Process manager | systemd user service | -| Tests | pytest (71 acceptance tests) | +| Tests | pytest (80 acceptance tests) | --- @@ -145,18 +169,24 @@ MIGRATION.md Schema migration instructions + MariaDB procedure requirements.txt sbin/ install-service.sh systemd user service installer (prompts for HA config) +static/ + icon-192.png PWA icon (192×192) + icon-512.png PWA icon (512×512) + favicon.ico Browser favicon + manifest.json PWA manifest + sw.js Service worker templates/ base.html Layout, CSS variables, dark mode, nav dashboard.html Battery list with filters, bulk actions, HA% column battery_add.html Add batteries form - battery_detail.html Battery detail + edit (includes battery_percentage field) + battery_detail.html Battery detail + history charts + modals 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 (includes ha_entity_id field) + device_detail.html Device detail + install + edit tests/ conftest.py pytest fixtures - test_acceptance.py 50 acceptance tests - test_ha_integration.py 21 HA integration tests + test_acceptance.py acceptance tests + test_ha_integration.py HA integration tests ```