Files

T

ryan 01969b2d24 Integrate SimbaKit PetKit service into Docker stack and LangChain agent

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>

2026-06-12 10:24:59 -04:00

3.1 KiB

Raw Permalink Blame History

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

cp .env.example .env  # fill in PetKit credentials
uv sync
uv run python -m simbakit

Docker

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

3.1 KiB Raw Permalink Blame History