Intelligente Bildüberwachung mit upcam-client & SnapShotter

Kurzfassung: Was macht dieses Setup?

Dieses Projekt ist für alle interessant, die eine Kamera nicht nur „irgendwie“ laufen lassen wollen, sondern daraus eine kleine, lokale Automatisierung bauen möchten: Bilder werden von der Kamera abgeholt, lokal gespeichert, bewertet und bei relevanter Bewegung automatisch an einen WhatsApp-Chat geschickt.

Der Charme liegt darin, dass die eigentliche Verarbeitung lokal läuft. Du bist nicht darauf angewiesen, dass jede kleine Bewegung erst durch irgendeine Kamera-Cloud geschoben wird. Gleichzeitig nutzt du für die Benachrichtigung einen bekannten Kanal: WhatsApp Web.

Architektur: Zwei Projekte, ein Workflow

Das Setup besteht aus zwei Teilen, die bewusst getrennt sind:

Früher hätte man das vielleicht als „Kamera lädt Bild runter, Skript schickt Bild weiter“ beschrieben. Das stimmt grob immer noch, wird dem aktuellen Projektstand aber nicht mehr ganz gerecht. Inzwischen ist daraus eher eine kleine Pipeline geworden:

1. Kamera liefert Snapshot oder Bildquelle.
2. Java-Ingest speichert Frames lokal.
3. SnapShotter bewertet die Frames.
4. Relevante Bilder gehen an WhatsApp.
5. Verworfene Bilder landen getrennt in einem Filter-Ordner.
6. Health-, Decision- und Notification-Dateien helfen beim Betrieb.

upcam-client: Kamera-Bilder lokal abholen

upcam-client ist der Java-Part des Setups. Er kümmert sich darum, Bilder von einer kompatiblen Kamera abzuholen und lokal bereitzustellen. Im aktuellen Repository ist das Projekt nicht mehr nur auf klassische UpCam-Setups beschränkt, sondern kennt als Kameraquellen u. a.:

• UPCAM
• REOLINK

Das ist praktisch, weil sich das Konzept damit besser auf moderne Kamera-Setups übertragen lässt. In meinem eigenen Setup ist der Gedanke: Die Kamera liefert Bildmaterial, aber die Entscheidung, was daraus wirklich relevant ist, liegt lokal in der eigenen Pipeline.

Was upcam-client macht

• Verbindung zur Kamera herstellen
• Snapshots oder Bildquellen abrufen
• Bilder lokal speichern
• Konfiguration über Properties-Dateien laden
• lokale Zugangsdaten von versionierten Defaults trennen
• optional einen einzelnen Ingest-Lauf mit --once ausführen

Warum Java?

Für den Kamera-Ingest ist Java ziemlich angenehm: stabil, gut als Dauerläufer betreibbar, stark bei Dateiverarbeitung und einfach als Windows-Service einzubinden. Für produktive Setups ist das nicht sexy, aber genau das ist hier ein Vorteil. Es soll laufen. Nicht glitzern.

SnapShotter: Bewegung bewerten & Bilder versenden

SnapShotter ist der Node.js-Part. Er verarbeitet die vom Java-Ingest erzeugten Frames, bewertet Bewegung und entscheidet, ob ein Bild relevant genug für den Versand ist.

Typischer Runtime-Flow

1. Neue Bilddateien landen im Eingangsordner, z. B. ./images/received/.
2. SnapShotter bewertet Bewegung, Helligkeit und Ereignislogik.
3. Akzeptierte Bilder werden an WhatsApp gesendet.
4. Gesendete Bilder landen z. B. in ./images/sent/.
5. Verworfene Bilder landen z. B. in ./images/filtered/.
6. Health- und Entscheidungsdaten werden in ./.state/ geschrieben.

Warum Node.js?

SnapShotter nutzt Node.js, weil der Versand über WhatsApp Web sehr gut in die JavaScript-Welt passt. Die Bibliothek whatsapp-web.js automatisiert WhatsApp Web im Hintergrund. Das ist keine offizielle WhatsApp-Business-API, sondern eine Automatisierung des Web-Clients.

Der komplette Ablauf in der Praxis

In der Praxis sieht das so aus:

1. Die Kamera stellt ein aktuelles Bild bereit.
2. upcam-client ruft dieses Bild ab und speichert es lokal.
3. SnapShotter erkennt den neuen Frame.
4. Die Filterlogik prüft, ob wirklich Bewegung oder ein relevantes Ereignis vorliegt.
5. Nur akzeptierte Bilder werden verschickt.
6. Die Entscheidung wird protokolliert.
7. Die Datei wird in den passenden Zielordner verschoben.

Das klingt nach Kleinkram, ist aber im Alltag Gold wert. Denn eine Kamera, die bei jeder Wolke, jedem Schatten und jedem Ast im Wind auslöst, nervt sehr schnell. Der eigentliche Mehrwert liegt deshalb nicht nur im Versand, sondern in der Filterung.

Installation & Repository-Setup

Das aktuelle Setup arbeitet mit zwei Repositories:

• upcam-client auf GitHub
• SnapShotter auf GitHub

Im aktuellen upcam-client-Repository ist SnapShotter als Submodule eingebunden. Deshalb ist beim Klonen wichtig, die Submodules direkt mitzuladen.

Repository inklusive Submodule klonen

git clone --recurse-submodules https://github.com/gzeuner/upcam-client.git
cd upcam-client

Falls du das Repository bereits ohne Submodule geklont hast:

git submodule update --init --recursive

Voraussetzungen

• Java 21+ für den Java-Ingest
• Maven für Build und Packaging
• Node.js 20+ für SnapShotter
• npm für die Node-Abhängigkeiten
• eine kompatible IP-Kamera bzw. Snapshot-Quelle
• ein WhatsApp-Konto für die Web-Kopplung

Setup-Skripte nutzen

Das Repository bringt Setup-Skripte mit, die eine Runtime-Struktur vorbereiten können.

./setup.sh

setup.bat

Danach kann der Java-Part über die vorbereiteten Starter aufgerufen werden.

%USERPROFILE%\upcam\upcamclient.cmd

~/upcam/upcamclient.sh

Ein einzelner Ingest-Lauf

Zum Testen ist ein einzelner Lauf praktisch. Damit kannst du prüfen, ob Kamera-Verbindung, Zugangsdaten und Zielordner korrekt funktionieren.

java -jar upcam-client-1.0-jar-with-dependencies.jar --once

Konfiguration: Kamera, Ordner, Filter, WhatsApp

Die wichtigste Regel zuerst:

Konfigurationsmodell beim Java-Ingest

upcam-client trennt versionierte Defaults von lokalen Overrides. Das ist genau richtig: Defaults dürfen ins Repo, echte Zugangsdaten nicht.

• application.properties – versionierte Defaults mit sicheren Platzhaltern
• upcamclient.properties – legacy-kompatible Defaults
• application.local.properties – lokale echte Werte, nicht versionieren
• application.local.properties.example – Vorlage für lokale Konfiguration

Die lokalen Werte sollten in application.local.properties liegen.

Minimalbeispiel für UPCAM

camera.type=UPCAM
base.url=http://upcam.local
image.daily.root.resource=/sd/${day}
upcam.user.name=admin
upcam.user.pwd=change_me

Minimalbeispiel für REOLINK

camera.type=REOLINK
reolink.host=reolink.local
reolink.httpPort=80
reolink.username=admin
reolink.password=change_me
reolink.snapshotPath=/cgi-bin/api.cgi?cmd=Snap&channel=0&rs={timestamp}

SnapShotter-Konfiguration

SnapShotter wird im Node-Projekt konfiguriert. Die zentrale Datei ist typischerweise:

• SnapShotter/src/config.js

Besonders wichtig sind diese Bereiche:

• imageFilter.nativeSignal.*
• imageFilter.delta.*
• imageFilter.brightnessGuard.*
• imageFilter.event.*
• runtime.*
• whatsapp.*
• logging.*

Betrieb, Logging & Health-Dateien

Ein gutes Überwachungssetup braucht nicht nur Bilder, sondern auch Betriebsdaten. SnapShotter schreibt deshalb Laufzeitinformationen in lokale Dateien.

Wichtige Runtime-Dateien

• Health: ./.state/runtime-health.json
• Entscheidungen: ./.state/decisions.ndjson
• Benachrichtigungen: ./.state/notifications.ndjson
• Logs: ./logs/

Das ist im Betrieb enorm hilfreich. Wenn keine Bilder mehr ankommen, willst du nicht raten müssen, ob die Kamera spinnt, WhatsApp abgemeldet ist, ein Filter zu streng greift oder der Prozess hängt.

Ordner, die nicht ins Repository gehören

Runtime-Daten, Sessions und echte Bilder gehören nicht in Git.

• application.local.properties
• images/
• logs/
• .state/
• .lock/
• dataset/
• sent/
• SnapShotter/.wwebjs_auth/

Als Windows-Service betreiben

Für den Dauerbetrieb ist ein Windows-Service deutlich stabiler als zwei offene Konsolenfenster. Die Grundidee:

• upcam-client läuft als Java-Service und holt Bilder ab.
• SnapShotter läuft als Node-Service und verarbeitet/verschickt Bilder.

Dafür eignet sich NSSM sehr gut. NSSM macht aus normalen Programmen wie javaw.exe oder node.exe echte Windows-Dienste.

Die konkrete Schritt-für-Schritt-Anleitung findest du hier:

• SnapShotter & upcam-client als Windows-Service einrichten
• Windows Services einrichten mit NSSM

Marken-, Hersteller- & Drittanbieterhinweis

Sicherheit, Datenschutz & rechtliche Hinweise

1. Kamera nicht auf öffentlichen Raum richten

Richte deine Kamera so aus, dass möglichst nur dein eigener Bereich erfasst wird. Gehwege, Straßen, Nachbargrundstücke oder gemeinschaftliche Flächen sind heikel. Technisch geht vieles – erlaubt ist deshalb noch lange nicht alles.

2. Empfänger müssen Bescheid wissen

Wenn Bilder automatisch in eine WhatsApp-Gruppe geschickt werden, sollten alle Beteiligten wissen, was dort landet, warum es dort landet und wer Zugriff darauf hat.

3. Speicherung begrenzen

Nur weil Bilder lokal gespeichert werden können, müssen sie nicht ewig gespeichert werden. Lege dir eine sinnvolle Aufbewahrungslogik zurecht. Gerade Filterordner können sonst unbemerkt wachsen.

4. Zugangsdaten schützen

Kamera-Passwörter, lokale IPs, WhatsApp-Sessions und Runtime-Dateien gehören nicht ins Repository. Nutze lokale Konfigurationsdateien, restriktive Dateirechte und sichere Backups.

5. WhatsApp nicht als Spam-Kanal nutzen

Dieses Setup ist für Benachrichtigungen im privaten oder internen Umfeld gedacht. Es ist nicht dafür gedacht, automatisiert Massennachrichten zu verschicken.

Fazit

Ressourcen & Links

• upcam-client auf GitHub
• SnapShotter auf GitHub
• whatsapp-web.js – Dokumentation
• NSSM – Non-Sucking Service Manager
• SnapShotter & upcam-client als Windows-Service einrichten
• Windows Services einrichten mit NSSM

Hinweis: Die Projekte sind öffentlich auf GitHub verfügbar. Beachte die jeweilige Lizenzdatei, Third-Party-Hinweise und die Verantwortung für dein eigenes Kamera-, Datenschutz- und Betriebssetup. Die genannten Marken und Produktnamen gehören den jeweiligen Rechteinhabern; dieses Projekt ist nicht mit WhatsApp, Meta, Reolink, UpCam oder anderen genannten Anbietern verbunden.