datacat/README.md

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)

# 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

pip install .
datacat

Using Docker

# 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)

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

# 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

# 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 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