dubey/datacat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f126202410260151b5c4795d5660c5bbc3294ce4
datacat/README.md
Tanishq Dubey f126202410 feat: add activity history, insights, and cat usage events 
- Add activity history collection for cat usage events
- Add insight metrics (total cycles, average cycles, cycles today)
- Add cat usage events with weight for LR4
- Add intermediate state events (cycle started, cycle complete, etc.)
- Add pet visits_24h metric from weight history
- Add new LR4 metrics: lifetime_cycles, dfi_trigger_count, cat_detected
- Add configurable activity lookback window to prevent duplicate events
- Add API call delays to avoid rate limiting
- Update default poll interval to 5 minutes
- Update documentation with new metrics and events
2025-12-16 15:37:34 -05:00

269 lines
8.5 KiB
Markdown
Raw Blame History

# Datacat
Collect metrics from Whisker Litter Robot devices and submit to Datadog.
Datacat connects to the Whisker API (used by Litter-Robot and Feeder-Robot devices) and periodically collects metrics, submitting them to Datadog for monitoring and alerting.
## Supported Devices
- **Litter-Robot 3** - Original connected litter box
- **Litter-Robot 4** - Newer model with additional sensors
- **Feeder-Robot** - Automatic pet feeder
## Features
- Collects metrics from all connected robots every 5 minutes (configurable)
- Fetches activity history to detect cat usage events
- Collects insight data (cycle counts, daily averages)
- Submits metrics to Datadog via DogStatsD
- Emits Datadog events for state changes (cat usage, drawer full, offline, errors)
- Supports pet profile metrics (weight, health status, visit count)
- Dry-run mode for testing without submitting metrics
- Configuration via environment variables or YAML file
## Installation
### Using UV (recommended)
```bash
# Clone the repository
git clone https://github.com/yourusername/datacat.git
cd datacat
# Install with UV
uv sync
# Run
uv run python -m datacat
```
### Using pip
```bash
pip install .
datacat
```
### Using Docker
```bash
# Build the image
docker build -t datacat .
# Run with environment variables
docker run -d \
-e WHISKER_USERNAME=your-email@example.com \
-e WHISKER_PASSWORD=your-password \
-e DATADOG_API_KEY=your-api-key \
datacat
```
## Configuration
Datacat can be configured via environment variables, a YAML config file, or both. Environment variables take precedence over config file values.
### Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `WHISKER_USERNAME` | Whisker account email | Yes |
| `WHISKER_PASSWORD` | Whisker account password | Yes |
| `DATADOG_API_KEY` | Datadog API key | Yes |
| `DATADOG_APP_KEY` | Datadog application key | No |
| `DATADOG_SITE` | Datadog site (default: `datadoghq.com`) | No |
| `DATACAT_POLL_INTERVAL` | Polling interval in seconds (default: `300`) | No |
| `DATACAT_INCLUDE_PETS` | Include pet metrics (default: `true`) | No |
| `DATACAT_EMIT_EVENTS` | Emit Datadog events (default: `true`) | No |
| `DATACAT_COLLECT_ACTIVITY` | Fetch activity history (default: `true`) | No |
| `DATACAT_COLLECT_INSIGHTS` | Fetch insight data (default: `true`) | No |
| `DATACAT_API_DELAY` | Delay between API calls in seconds (default: `1.0`) | No |
| `DATACAT_ACTIVITY_LOOKBACK` | Only emit events for activities within N minutes (default: `10`) | No |
| `DATACAT_METRIC_PREFIX` | Metric prefix (default: `litterrobot`) | No |
| `DATACAT_CONFIG_FILE` | Path to YAML config file | No |
### Config File (YAML)
```yaml
whisker:
username: "your-email@example.com"
password: "your-password"
datadog:
api_key: "your-datadog-api-key"
app_key: "your-datadog-app-key" # optional
site: "datadoghq.com"
metric_prefix: "litterrobot"
collector:
poll_interval_seconds: 300
include_pets: true
emit_events: true
collect_activity_history: true
collect_insights: true
api_call_delay_seconds: 1.0
activity_lookback_minutes: 10
```
## Usage
```bash
# Run continuously (default)
datacat
# Run with config file
datacat -c config.yaml
# Run once and exit
datacat --once
# Dry run (log metrics instead of submitting)
datacat --dry-run
# Verbose logging
datacat -v
```
## Metrics
### Litter Robot Metrics (LR3 & LR4)
| Metric | Type | Description |
|--------|------|-------------|
| `litterrobot.online` | Gauge | 1 if online, 0 if offline |
| `litterrobot.waste_drawer_level` | Gauge | Drawer fullness (0-100%) |
| `litterrobot.cycle_count` | Gauge | Cycles since last reset |
| `litterrobot.cycle_capacity` | Gauge | Max cycles before full |
| `litterrobot.waste_drawer_full` | Gauge | 1 if drawer is full |
| `litterrobot.is_sleeping` | Gauge | 1 if in sleep mode |
| `litterrobot.wait_time_minutes` | Gauge | Clean cycle delay |
| `litterrobot.night_light_enabled` | Gauge | Night light status |
| `litterrobot.panel_lock_enabled` | Gauge | Panel lock status |
| `litterrobot.power_status` | Gauge | 2=AC, 1=DC, 0=NC |
### Insight Metrics (from Activity History)
| Metric | Type | Description |
|--------|------|-------------|
| `litterrobot.insight.total_cycles` | Gauge | Total cycles in last 30 days |
| `litterrobot.insight.average_cycles` | Gauge | Average daily cycles |
| `litterrobot.insight.cycles_today` | Gauge | Cycles completed today |
### Litter Robot 4 Additional Metrics
| Metric | Type | Description |
|--------|------|-------------|
| `litterrobot.litter_level` | Gauge | Litter level (0-100%) |
| `litterrobot.litter_level_calculated` | Gauge | Calculated litter level from ToF sensor |
| `litterrobot.pet_weight` | Gauge | Last recorded cat weight (lbs) from robot scale |
| `litterrobot.scoops_saved` | Gauge | Environmental savings counter |
| `litterrobot.wifi_rssi` | Gauge | WiFi signal strength (dBm) |
| `litterrobot.night_light_brightness` | Gauge | Brightness level |
| `litterrobot.hopper_enabled` | Gauge | Hopper status |
| `litterrobot.lifetime_cycles` | Count | Total lifetime clean cycles |
| `litterrobot.odometer_power_cycles` | Count | Total power cycles |
| `litterrobot.odometer_empty_cycles` | Count | Total empty cycles |
| `litterrobot.dfi_trigger_count` | Count | Drawer full indicator triggers |
| `litterrobot.cat_detected` | Gauge | 1 if cat currently detected |
### Feeder Robot Metrics
| Metric | Type | Description |
|--------|------|-------------|
| `feederrobot.food_level` | Gauge | Food level (0-100%) |
| `feederrobot.gravity_mode_enabled` | Gauge | Gravity mode status |
| `feederrobot.meal_insert_size` | Gauge | Meal insert size (cups) |
### Pet Metrics
| Metric | Type | Description |
|--------|------|-------------|
| `litterrobot.pet.weight` | Gauge | Pet weight from profile (lbs) |
| `litterrobot.pet.estimated_weight` | Gauge | User-entered estimated weight |
| `litterrobot.pet.last_weight_reading` | Gauge | Last sensor weight reading |
| `litterrobot.pet.is_healthy` | Gauge | Health status |
| `litterrobot.pet.is_active` | Gauge | Active status |
| `litterrobot.pet.age` | Gauge | Pet age |
| `litterrobot.pet.visits_24h` | Gauge | Litter box visits in last 24 hours |
### Tags
All metrics include the following tags:
- `robot_id` - Unique robot identifier
- `robot_serial` - Robot serial number
- `robot_name` - User-defined robot name
- `robot_model` - Robot model (Litter-Robot 3, Litter-Robot 4, Feeder-Robot)
- `status` - Current robot status (for litter robots)
Pet metrics include:
- `pet_id` - Unique pet identifier
- `pet_name` - Pet name
- `pet_type` - Pet type (cat/dog)
## Events
Datacat emits Datadog events for important state changes. Events are sourced from both real-time state changes and activity history polling.
### Cat Usage Events
| Event | Alert Type | Description |
|-------|------------|-------------|
| Cat used litter box | Info | Cat detected and weighed (LR4 includes weight) |
| Cat detected | Info | Cat is using the litter box |
### Cycle Events
| Event | Alert Type | Description |
|-------|------------|-------------|
| Clean cycle started | Info | Cleaning cycle has begun |
| Clean cycle complete | Info | Cleaning cycle finished |
| Litter dispensed | Info | Litter hopper dispensed (LR4 with hopper) |
### Warning Events
| Event | Alert Type | Description |
|-------|------------|-------------|
| Drawer full | Warning | Waste drawer needs emptying |
| Drawer almost full | Warning | 1-2 cycles remaining |
| Robot went offline | Warning | Lost connection to robot |
| Bonnet removed | Warning | Bonnet has been removed |
| On battery backup | Warning | Running on DC power |
| Pinch detected | Warning | Pinch was detected |
| Food level low | Warning | Feeder below 20% |
### Error Events
| Event | Alert Type | Description |
|-------|------------|-------------|
| Cat sensor fault | Error | Cat sensor has a fault |
| Over torque fault | Error | Motor over torque detected |
| Dump position fault | Error | Dump position fault |
| Home position fault | Error | Home position fault |
### Success Events
| Event | Alert Type | Description |
|-------|------------|-------------|
| Robot back online | Success | Robot reconnected |
## Development
```bash
# Install with dev dependencies
uv sync
# Run linter
uv run ruff check src/
# Run formatter
uv run ruff format src/
```
## Disclaimer
This project uses the unofficial [pylitterbot](https://github.com/natekspencer/pylitterbot) library to communicate with the Whisker API. The API is reverse-engineered and may break at any time. Use at your own risk.
## License
MIT
Reference in New Issue View Git Blame Copy Permalink