Bird-Away: Raspberry Pi-powered water-based bird deterrent

A developer built Bird-Away, a Raspberry Pi-powered system that uses an RTSP camera and Claude AI to detect birds in a pool, then triggers a sprinkler to deter them. The system saves images and video clips, optionally publishing them to Cloudflare R2 for remote viewing. The project is open-source and designed for easy setup on a Raspberry Pi 4.

A Raspberry Pi service that watches a pool through an RTSP camera, asks Claude whether birds are present, and triggers a sprinkler via relay + solenoid valve to startle them. Each detection saves a still image and a short video clip, and can optionally publish both to a Cloudflare R2 bucket so they're viewable from anywhere on the internet. blogpost: https://mattsahn.github.io/bird-away-blog/ https://mattsahn.github.io/bird-away-blog/ - Raspberry Pi 4 or earlier on Wi-Fi. - Relay module wired to one Pi GPIO pin and ground. Active-high or active-low is configurable. - RTSP-capable IP camera reachable on the same network. - Solenoid valve on its own power supply, switched by the relay. The Pi must not source current to the valve directly. - Sprinkler aimed to spray over and around the pool when the valve opens. - optional - temperature/humidity sensor for monitoring ambient conditions in the enclosure - Momentary switch the contact pair on the same panel-mount button for a manual sprinkler trigger. One contact → GPIO pin default 23 , other → ground; the Pi's internal pull-up holds it HIGH at rest. The status LED stays solid while held, and releasing fires the same capture/spray/record/upload flow as a real bird detection. On the Pi: sudo apt update sudo apt install -y python3-venv ffmpeg swig liblgpio-dev git clone <this repo /home/pi/git/bird-away cd /home/pi/git/bird-away python3 -m venv .venv .venv/bin/pip install -r requirements.txt cp .env.example .env then edit: OPENROUTER API KEY, RTSP URL cp config.yaml.example config.yaml then edit GPIO pin, durations, etc. swig and liblgpio-dev are needed so pip can build the lgpio wheel, which gpiozero uses as its GPIO backend on Raspberry Pi OS Bookworm/Trixie. Without it gpiozero falls back to an experimental native pin factory and prints PinFactoryFallback warnings on startup. The clone path above /home/pi/git/bird-away matches the paths baked into systemd/bird-away.service . If you install elsewhere, edit WorkingDirectory , EnvironmentFile , and ExecStart in that unit to match. .env secrets, never committed : OPENROUTER API KEY — your OpenRouter API key https://openrouter.ai https://openrouter.ai . Routes to whichever model detector model selects. RTSP URL — full RTSP URL with credentials, e.g. rtsp://user:pass@192.168.1.50:554/stream . R2 ACCESS KEY ID / R2 SECRET ACCESS KEY — only required if r2 enabled: true in config.yaml . See Remote publishing remote-publishing-cloudflare-r2 . config.yaml tunables : interval seconds — how often to sample default 60 . spray duration — relay-on time in seconds when a bird is seen default 3 . pre spray seconds — seconds of video recorded before the spray fires, so the clip captures the moment leading up to it default 3 . post spray seconds — seconds of video recorded after the spray fires default 4 . Total clip length is pre spray seconds + spray duration + post spray seconds . gpio pin — BCM pin number wired to the relay input default 17 . relay active high — true if the relay closes on logic-high, false if active-low most cheap relay modules are active-low — check yours . capture dir — where images and clips are saved default ./captures . detector model — OpenRouter model id; default anthropic/claude-haiku-4.5 . detector base url — OpenAI-compatible base URL; default https://openrouter.ai/api/v1 . Override to point at a different provider. detector prompt — system prompt sent to the vision model. Use a YAML literal block | to write it across multiple lines. See Tuning the prompt tuning-the-prompt for what makes a good one. daytime only — when true default , only run detection between 07:00 and 19:00 local time. Set false to run 24/7 e.g. for testing or with an IR camera . motion enabled , motion threshold , motion downscale — local frame-diff gate; only call the vision API when consecutive frames differ enough. Threshold is on a 0-255 mean per-pixel scale; 5.0 is a reasonable start. status led enabled / status led pin — drive a status LED on a separate GPIO pin default 24 . Heartbeat-blinks 0.5s every 10s while the service is running, blinks 1.5s on each frame capture, and rapid-blinks 5 times on a positive bird detection. Set status led enabled: false if you don't have the LED wired. trigger button enabled / trigger button pin — manual sprinkler trigger via a momentary switch on a GPIO pin default 23 . Wired between the pin and ground; uses the Pi's internal pull-up. While held, the status LED stays solid; releasing runs the same flow as a real bird detection. Set trigger button enabled: false if no switch is wired. retention days — delete local detection- .jpg / event- .mp4 files older than this many days. Sweep runs at startup and hourly thereafter. Default 7 . Set to 0 or negative to keep everything. R2 objects are unaffected — manage their lifecycle in the bucket settings. healthcheck url / healthcheck interval seconds — liveness ping to healthchecks.io https://healthchecks.io or any URL accepting a GET . Pinged after each successful loop iteration, rate-limited to once per interval default 300s . Pings stop if the loop hangs or throws every iteration, so healthchecks.io alerts you by email/SMS. Leave blank to disable. Recommended for unattended deployments. log level — INFO or DEBUG .- R2 publishing keys r2 enabled , r2 account id , r2 bucket , r2 public base url , r2 key prefix — see Remote publishing remote-publishing-cloudflare-r2 . delete after upload — when true , skip the local JPEG write entirely and delete each MP4 right after R2 confirms the upload. Requires r2 enabled: true . Pair with capture dir: /dev/shm/bird-away for zero SD-card writes. See Minimizing SD-card writes minimizing-sd-card-writes . Optional. When r2 enabled: true , each detection's snapshot JPEG and event MP4 are uploaded to a Cloudflare R2 bucket so you can view them from any browser. R2 is S3-compatible with no egress fees and a 10 GB free tier — for typical usage this stays free indefinitely with a 30-day lifecycle rule. - Cloudflare → R2 → create a bucket e.g. bird-away . In the bucket's settings, enable the R2.dev subdomain and copy the https://pub-<hash .r2.dev URL. - R2 → "Manage R2 API tokens" → Create API token , scope Object Read & Write to that bucket. Save the Access Key ID and Secret Access Key — they're shown once. - Append to .env : R2 ACCESS KEY ID=... R2 SECRET ACCESS KEY=... - Add to config.yaml : r2 enabled: true r2 account id: <hex string from R2 dashboard r2 bucket: <bucket name r2 public base url: https://pub-<hash .r2.dev - Optional: in the R2 dashboard, add a lifecycle rule "delete objects older than 30 days" to keep storage under the free tier. Each detection produces two objects under <r2 key prefix /YYYY-MM-DD/ : detection-<ts .jpg and event-<ts .mp4 . Default r2 key prefix is events . By default R2 is additive — local copies in captures/ are also written and pruned by retention days . To make R2 the only copy and stop writing to the SD card, see Minimizing SD-card writes minimizing-sd-card-writes . When R2 publishing is enabled, the service also maintains a manifest.json in the bucket at <r2 key prefix /manifest.json . The manifest is a JSON index of the last 500 detection events with public URLs for each snapshot and video. web/index.html is a self-contained dashboard that reads this manifest and renders an interactive event timeline. The dashboard is a static site — deploy the web/ directory to Vercel: cd web npx vercel --prod Set the MANIFEST URL environment variable on the Vercel project so visitors see data immediately without any manual configuration: cd web npx vercel env add MANIFEST URL production paste: https://pub-<hash .r2.dev/events/manifest.json npx vercel --prod redeploy to pick up the new env var Or set it in the Vercel dashboard under Project → Settings → Environment Variables. The build step writes this value into dashboard-config.json , which the dashboard loads automatically on startup. Visitors can still override the URL via the settings modal or the ?manifest= query parameter. The dashboard is a single index.html with no build step, so it works anywhere: open it locally as a file, deploy to GitHub Pages or Netlify, or upload it to the same R2 bucket as your events. Live status : shows connection state, last event time, event count. Event grid : thumbnail cards for each detection with date, time, and trigger type auto / manual . Filtering : filter by date or trigger type. Lightbox : click any card to see the full snapshot; links to open the image or play the video. Auto-refresh : polls the manifest at a configurable interval default 60 seconds . Live tab : a rolling last-30-minutes view of every captured frame labeled bird / no-bird, for spotting missed detections see Real-time monitoring real-time-monitoring . If the dashboard is served from a different origin than R2 e.g. localhost or a Vercel deploy , the browser needs CORS headers on the manifest. In the Cloudflare dashboard, go to your R2 bucket → Settings → CORS policy and add: { "AllowedOrigins": " " , "AllowedMethods": "GET" , "AllowedHeaders": " " } R2.dev public subdomains include permissive CORS headers by default, so this is usually not needed unless you've customized the bucket's CORS settings. If you suspect the detector is missing birds, the Live tab gives you a rolling view of every frame the loop captured in the last 30 minutes — each labeled Bird or No bird — so you can manually spot false negatives. These frames are full-resolution the detector only ever sees a 512px copy, so small birds can hide there and carry no video. Enable it on the device config.yaml : realtime enabled: true requires r2 enabled: true realtime key prefix: realtime frames + manifest land under this prefix realtime window minutes: 30 how much the Live tab shows realtime max image dim: 0 0 = full-res; e.g. 1280 to shrink Frames upload to realtime/frames/<ts .jpg and are indexed in realtime/manifest.json — kept entirely separate from events/ , which stays real-detections-only. The dashboard derives the real-time manifest URL from the main manifest URL automatically swapping /events/ for /realtime/ ; override it in Settings if you use a custom prefix. Set up cleanup so old frames don't accumulate. R2 lifecycle rules expire objects by whole days 1-day minimum , so a true 30-minute purge isn't possible server-side — the Live tab provides the 30-minute view , and a lifecycle rule deletes the underlying objects a day later. In the Cloudflare dashboard: R2 → your bucket → Settings → Object lifecycle rules → Add rule , set the prefix to realtime/frames/ and "Delete objects" 1 day after creation. Scoping the rule to realtime/frames/ leaves realtime/manifest.json untouched it's rewritten every cycle anyway . Storage stays well within R2's free tier — one day of frames is a few hundred MB at most, and R2 egress is free. When deploying the dashboard to Vercel you can optionally set a REALTIME MANIFEST URL environment variable alongside MANIFEST URL ; the build bakes it into dashboard-config.json . It's optional — the derive fallback covers the default events / realtime prefixes. .venv/bin/python -m src.main Logs go to stdout. Output files appear under captures/ . Run these one at a time to verify each piece of the chain. .venv/bin/python scripts/test camera.py writes /tmp/bird-away-test.jpg .venv/bin/python scripts/test detector.py path/to/sample.jpg prints yes/no .venv/bin/python scripts/test sprinkler.py 1 clicks relay for 1 second .venv/bin/python scripts/test status led.py runs each LED pattern in sequence .venv/bin/python scripts/test trigger button.py press to light LED, release to log scripts/test models.py runs a list of vision models against a single saved frame so you can see how each one handles the same input. Useful when picking detector model or tuning detector prompt against tricky frames small distant birds, glare on water, dawn light, etc. . First-time setup — copy the example config the actual file is gitignored so your local tweaks stay out of the repo : cp scripts/models config.yaml.example scripts/models config.yaml Then run against any local image: .venv/bin/python scripts/test models.py captures/detection-20260426T131922Z.jpg Each model gets two prompts: a yes/no classifier the project's bird detector by default and a freeform description asks the model to describe the scene, animals, people, actions . Both prompts and the model list live in scripts/models config.yaml and can be overridden — pass --config <path to use an alternate file. The script prints the raw response from each model along with the input resolution, elapsed time, and token usage so you can compare quality, cost, and latency at a glance. sudo cp systemd/bird-away.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now bird-away journalctl -u bird-away -f The unit runs as user pi in group gpio . Adjust User= , Group= , and the paths in bird-away.service if your install location differs. For unattended deployments, SD-card wear is the most common cause of Pi death — every snapshot JPEG and event MP4 written to captures/ consumes write cycles. Cards typically tolerate 10k-100k writes per cell, and a busy day at the pool can produce dozens of MB; over months that adds up. Two settings together eliminate ~all capture-related SD writes: r2 enabled: true uploads still go to R2 delete after upload: true don't keep a local copy capture dir: /dev/shm/bird-away tmpfs RAM ; never touches the SD card How it works: JPEG snapshot. With delete after upload: true , the bytes are uploaded straight from memory via put object — write bytes is never called and image path never exists on disk. Event MP4. ffmpeg has to write to a path, so the file lives briefly in capture dir while it records. With capture dir pointed at /dev/shm a kernel-managed tmpfs sized to half of RAM by default , that "file" lives in RAM. Once the R2 upload returns success, the file is deleted. If the upload fails, the file stays so retention days can clean it up later. Bonus Faster than the SD card and survives nothing — a reboot wipes it. That's exactly what you want for transient capture data once R2 has the durable copy. /dev/shm . Tradeoff to know: with delete after upload: true , an extended R2 outage loses captures failed uploads stay on disk only until retention days expires, vs. the default behavior where they persist until you manually copy them off . For a deterrent system this is usually the right trade — SD-card death is permanent, a missed video clip is not. If you want to keep the local copies for debugging, or because you don't have R2 set up , leave delete after upload: false the default and let retention days bound disk usage. You can still point capture dir at /dev/shm/bird-away to get RAM-backed storage with retention-based cleanup — useful if you want a few days of local history without SD wear. For setups that need to run for months without intervention, the unit ships with two watchdogs and Restart=always . The defaults Just Work, but two extra one-time setup steps make recovery faster. Software watchdog already wired up . The service uses Type=notify and the main loop pings WATCHDOG=1 at the top of each iteration and once per second while sleeping. If the loop hangs for more than WatchdogSec=120 , systemd kills and restarts the process. Combined with Restart=always this also catches clean exits, OOM kills, segfaults — anything short of a kernel hang. Hardware watchdog one-time system config . The Pi's BCM watchdog will reset the SoC if the kernel itself hangs rare but possible — bad SD card sector, GPU lockup . On Pi 4/5 with current Pi OS, /dev/watchdog is already exposed; you just need to tell systemd to use it: sudo sed -i 's/^ RuntimeWatchdogSec=off/RuntimeWatchdogSec=15/' /etc/systemd/system.conf sudo systemctl daemon-reexec On older Pi OS Bullseye and earlier you may also need dtparam=watchdog=on in /boot/firmware/config.txt or /boot/config.txt on pre-Bookworm followed by a reboot. Check ls /dev/watchdog first — if it exists, you're already set. Liveness alerting. Set healthcheck url in config.yaml to a free healthchecks.io https://healthchecks.io URL — see the config docs above. This catches the failure mode where the loop is alive and pinging the watchdog but every iteration is throwing e.g. RTSP camera unreachable . False positives sprays when no birds : tighten detector prompt in config.yaml see Tuning the prompt tuning-the-prompt , or switch detector model to a stronger vision model e.g. anthropic/claude-sonnet-4.5 . Birds aren't fazed : increase spray duration , or check that the spray pattern actually covers where they land. Storage filling up : tune retention days default 7 . The service prunes captures/ at startup and hourly. R2 lifecycle rules handle the cloud copy. detector prompt is the system message sent to the vision model on every frame that passes the motion gate. The model receives the prompt plus a single still image, and the parser in src/detector.py calls it a bird if the reply starts with yes case-insensitive . A few rules of thumb: Be specific about what counts. "A bird" is ambiguous — does a duck on the deck count? Birds in flight? Reflections in the water? Most false positives and false negatives come from leaving these unstated. The default prompt explicitly covers "in, on, or near the pool including birds in flight directly above it " for that reason. Keep it short. Long prompts cost more per call and rarely improve accuracy. If you find yourself writing a paragraph, switch to a stronger detector model instead. Pin the output format. End with something like "Output only the single word." Models occasionally drift to "Yes." or "Yes, I see…" — those still match startswith "yes" , but rambling answers like "I'm not sure…" parse as no . Iterate against saved frames. Every detection writes a still to captures/ . Point scripts/test detector.py captures/<file .jpg at known bird and non-bird frames to sanity-check a prompt change before restarting the service. Restart after editing. config.yaml is read once at startup — sudo systemctl restart bird-away to pick up changes. - The Pi only switches the relay's input. The valve's power must come from a separate supply sized for the solenoid. Never wire mains AC to the Pi. - Confirm the relay polarity active-high vs active-low before attaching the valve. A relay stuck closed will leave water flowing. - The Sprinkler class drives the GPIO low on exit and on close, so a clean exit Ctrl-C, SIGTERM will shut the valve. systemd will also restart the service on failure, which forces a fresh GPIO init. ┌──────────────────────────────────────────────────────┐ │ Raspberry Pi bird-away.service │ └──────────────────────────────────────────────────────┘ Configuration ───────────── .env secrets config.yaml tunables ───────────── ────────────────────── OPENROUTER API KEY interval seconds, gpio pin, spray duration, RTSP URL detector model, detector prompt, motion , R2 ACCESS KEY ID daytime only, r2 if r2 enabled , … R2 SECRET ACCESS KEY │ │ └─────────────┬────────────┘ ▼ src/config.py ──► Config dataclass passed to all modules Per-iteration flow loops every cfg.interval seconds in src/main.py ───────────────────────────────────────────────────────────────────── src/camera.py runs a background thread PyAV / libav that holds one long-lived RTSP/TCP session and continuously decodes frames. The main loop pulls the most recent JPEG from RAM in O 1 — no per-iteration handshake. ┌──────────────┐ persistent │ RTSP camera │◄───────────────► src/camera.py │ IP cam │ H.264 stream Camera class: └──────────────┘ • bg thread: av.open + decode • capture frame → latest JPEG │ ▼ daytime only gate 07:00-19:00 local │ outside ◄───┴───► inside │ │ ▼ ▼ sleep src/motion.py MotionDetector.check frame-diff gate, local │ score < thresh ◄────┴────► score ≥ thresh │ │ ▼ ▼ sleep src/detector.py downscale → 512px Detector.is bird present │ HTTPS ▼ ┌──────────────────────┐ │ OpenRouter API │ │ Claude vision model │ │ per detector model │ └──────────┬───────────┘ │ "yes" / "no" ▼ ┌──────────┴──────────┐ ▼ no ▼ yes sleep handle event │ ┌───────────────────────────────────────────┤ ▼ ▼ pause bg thread, save still + spawn spawn ffmpeg ffmpeg recorder separate RTSP captures/event- .mp4 session, camera │ only allows 1-2 ┌────────┴────────┐ │ ▼ ▼ ▼ src/sprinkler.py src/uploader.py resume bg thread GPIO via gpiozero R2Uploader after ffmpeg + lgpio boto3 → S3 API │ │ ▼ ▼ GPIO pin 17 Cloudflare R2 public bucket Hardware chain off the Pi ─────────────────────────── GPIO 17 ──► Relay module ──► 12V solenoid valve ──► sprinkler ──► pool surface active high/ ▲ low configurable │ separate PSU never from Pi Background pieces ───────────────── systemd/bird-away.service → runs python -m src.main as user pi group gpio , restarts on failure, logs to journal captures/ → unbounded; prune via cron / tmpfiles.d scripts/test .py → per-stage smoke tests camera / detector / sprinkler