Open-PetCam

Open-PetCam turns a Raspberry Pi and a USB camera into a private, self-hosted pet camera. It provides an authenticated live stream, motion snapshots, recordings, a searchable gallery, and optional on-device cat detection without sending video to a cloud service.

Features

• Authenticated MJPEG live stream with a focused mobile-friendly viewer
• Motion detection with configurable sensitivity and cooldown
• Manual snapshots and MP4 recording
• Gallery with timestamps, filtering, pagination, and retention controls
• EfficientDet-Lite0 cat detection through LiteRT, gated by motion to reduce CPU usage
• Raspberry Pi systemd service with camera retry and filesystem hardening
• Optional GitHub Actions deployment over Tailscale with health checks and rollback

Hardware and software

The reference setup uses a Raspberry Pi 5 and a USB V4L2 camera. Other Linux systems and cameras may work if OpenCV can open the device. Raspberry Pi OS 64-bit is recommended. Python 3.11 or newer, ffmpeg, and v4l2-ctl are required.

Always shut a Raspberry Pi down cleanly before removing power. Camera workloads write media and filesystem metadata; repeated hard power loss can corrupt flash storage.

Local development

git clone https://github.com/karacanil/Open-PetCam.git
cd Open-PetCam
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Replace PETCAM_AUTH_PASS in .env with a long random password, then run:

python -m petcam.app

Open http://localhost:8080. Useful endpoints include /live, /gallery, /stream, and /healthz.

Raspberry Pi installation

The production layout keeps application releases separate from persistent data:

/opt/petcam/releases/       immutable application releases
/opt/petcam/current         symlink to the active release
/var/lib/petcam/media       snapshots and recordings
/var/lib/petcam/config      runtime settings
/var/lib/petcam/models      detector models
/etc/petcam/petcam.env      credentials and machine-specific configuration

Follow deploy/README.md for the backup-first systemd installation and optional GitHub/Tailscale deployment workflow.

Cat detection

Fetch the pinned, checksum-verified EfficientDet-Lite0 model:

python scripts/fetch_model.py models/efficientdet_lite0_320_ptq.tflite
python scripts/model_smoke.py models/efficientdet_lite0_320_ptq.tflite

Then set the following values in .env or /etc/petcam/petcam.env:

PETCAM_CAT_DETECTOR_BACKEND=tflite
PETCAM_CAT_TFLITE_MODEL_PATH=/var/lib/petcam/models/efficientdet_lite0_320_ptq.tflite
PETCAM_CAT_TFLITE_CLASS_ID=16
PETCAM_CAT_TFLITE_SCORE_THRESHOLD=0.30

Class index 16 is the zero-based EfficientDet COCO index for cats. The bundled OpenCV Haar cascades remain available as a lightweight fallback by setting PETCAM_CAT_DETECTOR_BACKEND=haar.

To test your own properly licensed images offline:

python scripts/cat_detect_test.py /path/to/images \
  --backend tflite \
  --model models/efficientdet_lite0_320_ptq.tflite \
  --threshold 0.30 \
  --out cat-test-output

Do not commit private camera snapshots or third-party images without redistribution permission.

Tests

pip install -r requirements-dev.txt
ruff check petcam scripts tests wsgi.py gunicorn.conf.py
pytest
python scripts/fetch_model.py /tmp/efficientdet.tflite
python scripts/model_smoke.py /tmp/efficientdet.tflite

Security

Open-PetCam is intended for private networks. Do not expose port 8080 directly to the public internet. Use Tailscale, another trusted VPN, or a properly configured HTTPS reverse proxy. Change the example password before first launch and keep .env out of version control.

See SECURITY.md for reporting vulnerabilities and deployment guidance.

License

Open-PetCam is licensed under GPL-3.0. See LICENSE.