AvianVisitors: BirdNET-Pi collage frontend overlay

Adds avian/ on top of upstream BirdNET-Pi: - frontend/ static collage UI (mask-packed bird tiles, sized by detection count) - assets/ ~450 bundled kachō-e illustrations + cutouts + binary masks - api/ PHP shims for recent/lifelist/firstseen/timeseries JSON - scripts/ installer + Gemini pregen + editable prompt template - caddy/ snippet mounting /collage on existing Caddy - forwarding/ optional HA / MQTT / Cloudflare configs Default install: http://birdnet.local/collage/ with no auth. Upstream BirdNET-Pi README preserved at README.upstream.md.
2026-05-28 10:14:25 -07:00
parent 88985a3a6f
commit d0ad1454c4
705 changed files with 2276 additions and 154 deletions
@@ -0,0 +1,99 @@
+# Optional: forwarding the collage off your local network
+
+Default install hosts the collage at `http://birdnet.local/collage/` on
+your LAN with no auth. If you want it accessible from anywhere — or
+piped into Home Assistant / MQTT — pick one of the recipes below.
+
+Each recipe is independent. Skip what you don't need.
+
+---
+
+## 1. Cloudflare Tunnel (recommended for public access)
+
+Gives you a public HTTPS URL with no port forwarding and no exposed
+home IP. Free Cloudflare account required.
+
+Install `cloudflared` on the Pi:
+
+```bash
+sudo mkdir -p /usr/share/keyrings
+curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg \
+  | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
+echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main' \
+  | sudo tee /etc/apt/sources.list.d/cloudflared.list
+sudo apt update && sudo apt install -y cloudflared
+```
+
+Authenticate + create the tunnel:
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create birds
+```
+
+Add a public route — pick a hostname on a zone you own:
+
+```bash
+cloudflared tunnel route dns birds birds.your-domain.com
+```
+
+Configure the tunnel to point at the local Caddy:
+
+```bash
+sudo cp avian/forwarding/cloudflared.yml /etc/cloudflared/config.yml
+# edit /etc/cloudflared/config.yml — set `tunnel:` to your tunnel UUID
+sudo cloudflared service install
+sudo systemctl restart cloudflared
+```
+
+**Adding password protection on the public URL.** With Cloudflare in
+front, gate the public endpoint via Cloudflare Access (zero-trust
+free tier supports up to 50 users) — see Cloudflare docs. The local
+LAN URL remains unprotected. If you'd rather use HTTP Basic auth on
+Caddy itself, see [forwarding/caddy-auth.caddy](caddy-auth.caddy).
+
+---
+
+## 2. Home Assistant — surface latest detection as a sensor
+
+Add to `configuration.yaml`:
+
+```yaml
+rest:
+  - resource: http://birdnet.local/api/recent.json?hours=1
+    scan_interval: 60
+    sensor:
+      - name: "Latest Bird"
+        value_template: >
+          {% set top = value_json.species | sort(attribute='last_seen', reverse=true) | first %}
+          {{ top.com if top else 'none' }}
+        json_attributes_path: "$.species[0]"
+        json_attributes:
+          - sci
+          - n
+          - last_seen
+          - best_conf
+```
+
+Use the sensor in automations — flash a light when a new species is
+heard, etc.
+
+---
+
+## 3. MQTT — fan out detections to other services
+
+If you already run an MQTT broker, publish every new detection.
+Install `paho-mqtt` and run the bridge:
+
+```bash
+sudo pip3 install paho-mqtt --break-system-packages
+cp avian/forwarding/mqtt-bridge.py ~/avian-mqtt.py
+# edit ~/avian-mqtt.py — broker host, topic prefix
+sudo cp avian/forwarding/avian-mqtt.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now avian-mqtt
+```
+
+The bridge polls `/api/recent.json?hours=1` once a minute and
+publishes new species under `birdnet/<slug>` with the full record as
+JSON payload.
@@ -0,0 +1,12 @@
+[Unit]
+Description=AvianVisitors MQTT bridge
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/python3 /home/%i/avian-mqtt.py
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
@@ -0,0 +1,19 @@
+# Optional Basic-auth gate for the collage.
+# Use only if you're NOT putting Cloudflare Access in front of the
+# public URL. Replace the bcrypt hash below — generate via:
+#   caddy hash-password --plaintext 'your-pass'
+#
+# Drop this into /etc/caddy/conf.d/ alongside avian.caddy and reload.
+
+(avian_basicauth) {
+    basic_auth {
+        # username   bcrypt-hash
+        avian        $2a$14$REPLACE_WITH_HASH_FROM_caddy_hash-password
+    }
+}
+
+# Example: gate only the public hostname, leave LAN open.
+# https://birds.your-domain.com {
+#     import avian_basicauth
+#     reverse_proxy localhost:80
+# }
@@ -0,0 +1,11 @@
+# Cloudflare Tunnel config — copy to /etc/cloudflared/config.yml and
+# replace TUNNEL_UUID with the value printed by `cloudflared tunnel create`.
+tunnel: TUNNEL_UUID
+credentials-file: /etc/cloudflared/TUNNEL_UUID.json
+
+ingress:
+  # Public collage — points at the local Caddy on port 80.
+  - hostname: birds.your-domain.com
+    service: http://localhost:80
+  # Catch-all required by cloudflared
+  - service: http_status:404
@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Poll /api/recent.json on the Pi once a minute and publish each new
+detection to MQTT. Edit BROKER, TOPIC_PREFIX, and PI_URL below."""
+import json
+import time
+import urllib.request
+import paho.mqtt.client as mqtt  # sudo pip3 install paho-mqtt
+
+BROKER = "homeassistant.local"
+PORT = 1883
+USER = ""
+PASSWORD = ""
+TOPIC_PREFIX = "birdnet"
+PI_URL = "http://birdnet.local/api/recent.json?hours=1"
+
+seen_keys: set[str] = set()
+
+def slugify(s: str) -> str:
+    return "".join(c.lower() if c.isalnum() else "-" for c in s).strip("-")
+
+def loop(client: mqtt.Client) -> None:
+    while True:
+        try:
+            with urllib.request.urlopen(PI_URL, timeout=10) as r:
+                payload = json.loads(r.read())
+            for s in payload.get("species", []):
+                key = f"{s['sci']}|{s.get('last_seen','')}"
+                if key in seen_keys:
+                    continue
+                seen_keys.add(key)
+                topic = f"{TOPIC_PREFIX}/{slugify(s['sci'])}"
+                client.publish(topic, json.dumps(s), qos=0, retain=False)
+                print(f"published {topic}: {s.get('com')}")
+        except Exception as e:
+            print(f"poll error: {e}")
+        time.sleep(60)
+
+def main() -> None:
+    client = mqtt.Client()
+    if USER:
+        client.username_pw_set(USER, PASSWORD)
+    client.connect(BROKER, PORT, keepalive=60)
+    client.loop_start()
+    loop(client)
+
+if __name__ == "__main__":
+    main()