ryan
01969b2d24
Adds simbakit/ as a subfolder service that polls PetKit smart devices (litter box, fountain, feeder) and exposes pet weight, litter activity, and device health data via three new LangChain tools. Also fixes stale alerts bug where cleared conditions (e.g. waste bin full) persisted because the query used max alert time instead of the device's last_seen_at timestamp. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
104 lines
3.1 KiB
Markdown
104 lines
3.1 KiB
Markdown
# SimbaKit
|
|
|
|
A self-hosted PetKit data polling service with a web dashboard. Polls the PetKit cloud API every 2 minutes and stores everything in SQLite — device snapshots, alerts, pet weight, and litter box activity.
|
|
|
|
## Stack
|
|
|
|
- **Python 3.14** + **uv** for package management
|
|
- **pypetkitapi** for PetKit cloud API
|
|
- **aiohttp** for HTTP + web server
|
|
- **aiosqlite** for async SQLite
|
|
- **Chart.js** for frontend charts
|
|
- **Docker** for deployment
|
|
|
|
## Features
|
|
|
|
### Dashboard
|
|
- Device cards with live status (firmware, serial, last seen)
|
|
- Alert banner — surfaces warnings and critical issues from all devices
|
|
- Per-device detail panel with time-series charts and snapshot history
|
|
- Full raw JSON stored per poll (nothing is ever lost)
|
|
|
|
### Alerts
|
|
Automatically extracted per poll cycle based on device state:
|
|
|
|
| Device | Alerts |
|
|
|--------|--------|
|
|
| Litter box | Waste bin full, litter low, deodorant empty/low/expiring, pet detection error, device errors |
|
|
| Water fountain | Water low, filter warning/low %, malfunction |
|
|
| Feeder | Food low, blockage, desiccant expiring, battery low |
|
|
| Purifier | Liquid low, consumable expiring |
|
|
|
|
### Weight Tracker
|
|
- Pulls pet weight from litter box camera events (`device_pet_graph_out`)
|
|
- Stats: latest, average, min/max range, trend direction
|
|
- Chart with multi-pet support
|
|
- Filter by pet and time range (7d / 30d / 90d / 1y)
|
|
|
|
### Litter Activity
|
|
- Tracks every litter box visit — poop vs pee (`is_shit`)
|
|
- Stats: total visits, poop/pee count, avg time in box, avg poop weight
|
|
- Event timeline with pet name, duration, weight
|
|
|
|
## Running
|
|
|
|
### Local
|
|
```bash
|
|
cp .env.example .env # fill in PetKit credentials
|
|
uv sync
|
|
uv run python -m simbakit
|
|
```
|
|
|
|
### Docker
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Dashboard at `http://localhost:8585`.
|
|
|
|
## Config (`.env`)
|
|
|
|
```
|
|
PETKIT_USERNAME=your_email@example.com
|
|
PETKIT_PASSWORD=your_password
|
|
PETKIT_REGION=US
|
|
PETKIT_TIMEZONE=America/New_York
|
|
POLL_INTERVAL_SECONDS=120
|
|
DB_PATH=simbakit.db
|
|
WEB_HOST=127.0.0.1
|
|
WEB_PORT=8585
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
simbakit/
|
|
├── Dockerfile
|
|
├── compose.yaml
|
|
├── pyproject.toml
|
|
├── .env.example
|
|
├── docs/
|
|
│ └── petlibro-integration.md # future: Petlibro feeder support
|
|
└── src/simbakit/
|
|
├── __main__.py # entry point, signal handling
|
|
├── config.py # frozen dataclass from env vars
|
|
├── database.py # SQLite schema + read/write
|
|
├── poller.py # PetKit polling + field extraction
|
|
├── web.py # REST API (aiohttp)
|
|
└── static/index.html # dashboard SPA
|
|
```
|
|
|
|
## Database
|
|
|
|
| Table | Purpose |
|
|
|-------|---------|
|
|
| `devices` | Device registry, upserted each poll |
|
|
| `device_snapshots` | Append-only full state snapshots with raw JSON |
|
|
| `alerts` | Extracted alerts per poll cycle |
|
|
| `pet_weights` | Weight measurements from litter box events |
|
|
| `litter_events` | Poop/pee visit log with duration and weights |
|
|
|
|
## Future
|
|
|
|
- **Petlibro feeder support** — API research done, notes in `docs/petlibro-integration.md`
|