Zeus Herald: Zuverlässige Kamera-Benachrichtigungen mit Telegram und ntfy

Kurzfassung: Was ist Zeus Herald?

Zeus Herald ist ein lokal laufender Node.js-Dienst, der Snapshots von IP-Kameras abholt, Bewegungen erkennt und nur relevante Ereignisbilder an dein Handy schickt – über Telegram, ntfy oder beides.

Die eigentliche Auswertung bleibt lokal. Du brauchst keine Kamera-Cloud, die jede Bewegung erst irgendwohin schickt. Gleichzeitig entfällt die fragilste Stelle des alten Setups: die Browser-Automation um WhatsApp Web.

Warum ein Nachfolger? Vorteile gegenüber upcam-client & SnapShotter

Die alte Kombination aus upcam-client (Java) und SnapShotter (Node.js + whatsapp-web.js) hat lange gut funktioniert. Mit der Zeit sind aber genau die Punkte nervig geworden, die bei einem unattended Setup am meisten stören:

• WhatsApp-Web-Sessions laufen ab oder brauchen erneutes Scannen.
• Chromium frisst RAM und macht den Prozess schwerer zu überwachen.
• Zwei Runtime-Welten (Java + Node) bedeuten doppelte Wartung, doppelte Service-Konfiguration und mehr Stellen, an denen etwas hängen kann.
• Die Filterlogik in SnapShotter war mächtig, aber auch komplex zu tunen.

Die wichtigsten Vorteile auf einen Blick

Der eigentliche Gewinn ist weniger „mehr Features“, sondern weniger Reibung im Alltag: weniger abgelaufene Sessions, weniger RAM, weniger Stellen, an denen man raten muss, warum gerade nichts ankommt.

Architektur: Zwei Prozesse, ein klarer Flow

Zeus Herald trennt bewusst zwei Aufgaben:

Die Bewegungserkennung entscheidet einmal pro Frame. Alle aktivierten Notifier bekommen danach dasselbe komprimierte Bild. Das spart doppelte Bildverarbeitung und hält die Logik übersichtlich.

Telegram und ntfy statt WhatsApp Web

Der größte operative Unterschied zum Vorgänger: Es gibt keine WhatsApp-Web-Session mehr. Stattdessen nutzt Zeus Herald zwei etablierte, dokumentierte Kanäle.

Telegram Bot API

• Offizielle Bot-API von Telegram
• Bilder gehen als Foto an einen privaten Chat oder eine Gruppe
• Mehrere Empfänger über eine private Gruppe möglich
• Chat-ID lässt sich mit einem Hilfsbefehl ermitteln

ntfy

• HTTP-basiertes Push-System (ntfy.sh oder selbst gehostet)
• Bilder werden per PUT an ein Topic geschickt
• Sehr leichtgewichtig und gut für self-hosted Setups
• Mit Token und privatem Server deutlich sicherer als ein öffentliches Topic

Installation & erster Start

Voraussetzungen

• Node.js 20+
• eine per HTTP erreichbare Kamera mit Snapshot-Endpunkt (Reolink empfohlen, UpCam optional)
• optional: Telegram-Bot und/oder ntfy-Topic

Repository klonen und vorbereiten

git clone https://github.com/gzeuner/zeus-herald.git
cd zeus-herald
npm install
cp .env.example .env

Danach die lokale .env mit echten Werten füllen – und diese Datei niemals committen oder teilen.

Erste Funktionstests

npm run lint
npm test
npm run check:banned

npm run ingest:once
npm run notify:latest
npm run motion:once

Telegram einrichten

1. Bei Telegram den @BotFather öffnen und einen neuen Bot anlegen.
2. Den Bot-Token notieren.
3. Den Bot in einen privaten Chat oder eine private Gruppe einladen (bei Gruppen: Bot als Mitglied hinzufügen und ggf. eine Nachricht schreiben).
4. Die Chat-ID ermitteln.

TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=123456789:AA...dein_token...
TELEGRAM_CHAT_ID=-1001234567890

Die Chat-ID findest du am einfachsten so:

npm run telegram:chat-id

Der Befehl liest die Updates des Bots und zeigt sichtbare Chats an. Für private Gruppen ist die ID meist negativ und beginnt mit -100.

ntfy einrichten

ntfy ist bewusst simpel: Du legst ein Topic an und schickst Bilder per HTTP PUT dorthin. Auf dem Handy installierst du die ntfy-App und abonnierst dasselbe Topic.

NTFY_ENABLED=true
NTFY_URL=https://ntfy.sh/dein-langes-privates-topic
# Optional, empfohlen bei eigenem Server:
# NTFY_TOKEN=tk_...

Danach kannst du den Versand unabhängig von der Kamera testen:

npm run notify:latest

Kamera konfigurieren (Reolink & UpCam)

Reolink ist der primäre und am besten unterstützte Weg. UpCam bleibt optional möglich.

Minimalbeispiel Reolink

CAMERA_TYPE=reolink
CAMERA_ID=front
INGEST_MODE=files_only
INGEST_TARGET_DIR=images/received
INGEST_INTERVAL_MS=3000

REOLINK_HOST=192.168.1.50
REOLINK_HTTP_PORT=80
REOLINK_USER=admin
REOLINK_PASSWORD="dein_passwort"
REOLINK_CHANNEL=0
REOLINK_SNAPSHOT_PATH=/cgi-bin/api.cgi?cmd=Snap&channel={channel}&rs={timestamp}&user={usernameEncoded}&password={passwordEncoded}

REOLINK_BURST_ENABLED=true
REOLINK_BURST_COUNT=2
REOLINK_BURST_INTERVAL_MS=350
REOLINK_BURST_REQUIRE_SIGNAL=true

Mit REOLINK_BURST_REQUIRE_SIGNAL=true speichert der Ingest nur dann mehrere Frames, wenn die Kamera selbst Bewegung meldet. Das spart Speicher und reduziert sinnlose Auswertung.

Optional: UpCam

CAMERA_TYPE=upcam
UPCAM_SNAPSHOT_URL=http://upcam.local/snapshot.jpg
# oder Host + Basic Auth:
# UPCAM_HOST=upcam.local
# UPCAM_USER=admin
# UPCAM_PASSWORD=change_me

Bewegungserkennung und Filter

Die Motion-Stufe ist bewusst pragmatischer als das alte SnapShotter-Zonenmodell. Der Ablauf:

1. JPEG dekodieren
2. auf Arbeitsbreite skalieren
3. optional oberen Bildrand abschneiden
4. ROI-Polygone anwenden
5. Grauwert-Pixel mit dem vorherigen Frame vergleichen
6. Bestätigungsframes, Cooldown und maximale Sendungen pro Ereignis anwenden

MOTION_RECEIVED_DIR=images/received
MOTION_FILTERED_DIR=images/filtered
MOTION_SENT_DIR=images/sent
MOTION_POLL_MS=250
MOTION_NOTIFY=true

MOTION_IMAGE_DECODE_ENABLED=true
MOTION_RESIZE_WIDTH=512
MOTION_CROP_TOP_PX=24
MOTION_PIXEL_DIFF_THRESHOLD=12
MOTION_SCORE_THRESHOLD=0.012
MOTION_CONFIRM_COUNT=1
MOTION_COOLDOWN_MS=1000
MOTION_MAX_SENDS=20

ROI-Polygone kannst du als JSON hinterlegen, wenn nur bestimmte Bildbereiche relevant sind (Einfahrt, Terrasse, Briefkasten). Der Rest des Bildes wird dann bei der Auswertung ignoriert.

Dauerbetrieb, Health und Cleanup

Im Alltag laufen zwei Prozesse dauerhaft:

npm run ingest
npm run motion

Was im Betrieb hilft

• Health-Datei: standardmäßig unter state/health.json
• Decision-Log: optional über DECISION_LOG=1
• Prozess-Locks: unter .lock/, verhindern doppelte Instanzen
• Cleanup: alte Bilder und Logs werden automatisch aufgeräumt

CLEANUP_ENABLED=true
CLEANUP_INTERVAL_MS=300000
CLEANUP_IMAGES_MAX_AGE_HOURS=36
CLEANUP_LOGS_MAX_AGE_HOURS=48

Als Windows-Service mit NSSM

Für den Dauerbetrieb auf Windows eignet sich NSSM hervorragend. Wichtig: ein Prozess = ein Service.

• Service 1: zeus-herald-ingest
  Path: …\npm.cmd
  Startup directory: Projektordner
  Arguments: run ingest
• Service 2: zeus-herald-motion
  Path: …\npm.cmd
  Startup directory: Projektordner
  Arguments: run motion

Vor dem Umschalten auf Services den Flow manuell so lange testen, bis Ingest, Motion und Notifier stabil laufen. Erst dann die alten Java-/WhatsApp-Dienste abschalten.

Migration von den alten Projekten

Die alte Pipeline bleibt vorerst lauffähig, wird aber nicht mehr aktiv weiterentwickelt. Der empfohlene Weg:

1. Zeus Herald parallel installieren und .env befüllen.
2. Kamera mit npm run ingest:once testen.
3. Versand mit npm run notify:latest prüfen.
4. Motion einmalig und dann dauerhaft laufen lassen.
5. Erst wenn der neue Flow stabil ist, die alten Java- und WhatsApp-Prozesse stoppen.

Sicherheit, Datenschutz & Hinweise

1. Kameraausrichtung: möglichst nur den eigenen Bereich erfassen.
2. Empfänger informieren: Wer Bilder in einer Telegram-Gruppe oder über ntfy bekommt, sollte wissen, was dort ankommt.
3. Speicherung begrenzen: Cleanup-Zeiten bewusst setzen; Filter- und Sent-Ordner wachsen sonst unbemerkt.
4. Secrets schützen: .env nie committen, nie in öffentliche Cloud-Ordner legen, restriktive Dateirechte nutzen.
5. ntfy absichern: öffentliches Topic nur mit langem, geheimem Namen – besser privater Server mit Token.
6. ZIP-Deployments: enthalten standardmäßig die lokale .env und sind damit private Artefakte.

Fazit

Ressourcen & Links