Reolink NVR mit dem ESP32 steuern: API, Mute, Restore

ESP32 schaltet einen Reolink NVR per HTTPS-API stumm: Login-Token, Kanalbefehle, selbstsignierte Zertifikate und ein Restore, das Neustarts übersteht.

Veroffentlicht
Lesezeit
9 Min.
Kategorie
Projekte
Ein Mann drückt den Knopf eines kleinen Wandschalters, von dem gestrichelte Linien zu drei Überwachungskameras führen, jede mit einem durchgestrichenen Auge.

Kurz gesagt

Ein ESP32 meldet sich an der HTTPS-API des Reolink NVR an, holt ein Token und sendet SetPushV20 und SetRecV20 pro Kanal. Restore schaltet beides wieder ein, auch nach einem Neustart.

Ja, ein ESP32 kann einen Reolink NVR steuern. Er meldet sich an der HTTPS-API des NVR unter /api.cgi an, erhält ein Sitzungs-Token und sendet die Befehle SetPushV20 und SetRecV20, um Push-Benachrichtigungen und Aufzeichnung pro Kanal auszuschalten. Ein zweiter Satz Befehle schaltet sie wieder ein.

Du gehst aus dem Haus, deine eigenen Bewegungen füllen den NVR mit Alarmen, und du willst nicht jedes Mal die Reolink-App öffnen. Dieser Beitrag folgt der echten Firmware von Gizmo Reolink Switch, einem XIAO ESP32-S3 mit Taster, Buzzer und 16x2-LCD. Jeder Pin, jede Zahl und jede Meldung unten stammt aus dem Open-Source-Repository, und am Ende sage ich, was ich nicht prüfen konnte.

Open-Source-Projekt ESP32 + Reolink
Gizmo Reolink Switch

ESP32-Schalter für den stillen Abgang mit Taster, Summer, 16x2-I2C-LCD und WLAN, der Reolink-NVR-Meldungen und Aufzeichnung kurz stummschaltet.

  • Timer für den stillen Abgang
  • Bedienung über ein 16x2-LCD
  • Direkte Steuerung über die Reolink-API
Ansehen

Eine Cartoon-Zeichnung eines Mannes, der sich in einem Hinterhof duckt und vor einer an der Wand montierten Überwachungskamera erschrickt

Die Reolink-HTTP-API ist eine JSON-Schnittstelle, die der NVR selbst bereitstellt. Du schickst HTTPS-POST-Anfragen an https://<nvr>/api.cgi?cmd=<Command>&token=<token>, und der Body ist immer ein JSON-Array mit Befehlen, auch wenn es nur einer ist. Eine offizielle Reolink-API-Seite zum Verlinken habe ich nicht gefunden, deshalb ist der Firmware-Quellcode meine Referenz, und alles Folgende beschreibt, was diese Firmware sendet und liest.

Die Firmware nutzt weder Basic- noch Digest-Authentifizierung. Sie sendet einen Login-Befehl mit token=null in der URL und Benutzername und Passwort im JSON-Body. Die Antwort enthält einen Token-Namen und eine Lease-Zeit in Sekunden, und das Token kommt in den Parameter &token= jedes weiteren Aufrufs.

BefehlWas er tutWofür die Firmware ihn nutzt
LoginLiefert Token name und leaseTimeEin Sitzungs-Token holen
GetChannelstatusListet Kanäle mit einem Online-FlagDie stummzuschaltenden Kameras finden (nur online)
SetPushV20Setzt Push-Benachrichtigungen pro KanalAlarme stummschalten und wiederherstellen
SetRecV20Setzt die Aufzeichnung pro KanalAufzeichnung stummschalten und wiederherstellen

Die Details der Anfragen stehen in reolink.cpp und reolink_protocol.cpp:

  • Token-Lease. Hat die Antwort kein leaseTime, nimmt die Firmware 3600 Sekunden an. Dieser Standardwert ist eine Entscheidung meiner Firmware, kein dokumentierter Reolink-Wert. Das Token wird 60 Sekunden vor Ablauf des Lease erneuert.
  • Abgelaufene Sitzung. Der Fehlercode -6 bedeutet eine fehlende oder abgelaufene Sitzung. Die Firmware meldet sich neu an und wiederholt den Aufruf einmal.
  • Batching. Das Mute ist ein einziger POST mit je einem SetPushV20- und einem SetRecV20-Eintrag pro Online-Kanal, und die Firmware liest das Ergebnis jedes Eintrags.
  • Parameter. Jeder Eintrag trägt channel, enable und scheduleEnable, alle auf 0 zum Stummschalten und auf 1 zum Wiederherstellen.
  • Grenzen. Das HTTP-Timeout beträgt 10 Sekunden, eine Antwort über 16.384 Bytes wird abgelehnt, und die Firmware verfolgt die Kanäle 0 bis 31 (sie liest höchstens 16 Online-Kanäle).

Ich habe nicht geprüft, welche NVR-Modelle und Firmware-Versionen diese Befehle akzeptieren. Nimm das also als das, was die Firmware tut, nicht als Zusage für deinen NVR. Schick zuerst von deinem Computer ein Login und ein GetChannelstatus, um zu sehen, was deiner antwortet.

Wie sieht der ESP32-Code aus?

Die Firmware nutzt das Arduino-Framework auf PlatformIO (framework = arduino, platform = espressif32 @ 8.0.0 in platformio.ini). Sie verwendet nicht esp_http_client: Die HTTP-Seite ist der Arduino-HTTPClient über einem WiFiClientSecure, mit ArduinoJson 7.2.2 für die Bodies. Wenn du gerade eine Toolchain auswählst, lies Arduino IDE vs. PlatformIO für den ESP32.

Der Kern einer Anfrage ist kurz. Das ist eine gekürzte Version dessen, was die Firmware tut, keine Kopie:

Trimmed from reolink.cpp
Trimmed from reolink.cpp
WiFiClientSecure secureClient;
HTTPClient http;

secureClient.setInsecure();  // accept the NVR's self-signed certificate
http.begin(secureClient, "https://192.168.1.10/api.cgi?cmd=Login&token=null");
http.setTimeout(10000);
http.addHeader("Content-Type", "application/json");
int status = http.POST(R"([{"cmd":"Login","action":0,"param":{"User":{"userName":"admin","password":"..."}}}])");
Zeile 8, Spalte 1UTF-8cpp

Zwei Details sparen Speicher. Die Firmware hält für alle Anfragen eines Mute oder Restore eine einzige TLS-Verbindung offen, sodass sie sich einen Handshake teilen, und schließt sie dann, damit keine untätige TLS-Sitzung Heap belegt. Hat der NVR die gehaltene Verbindung in der Zwischenzeit geschlossen, verbindet sich die Firmware neu und sendet dieselben Befehle noch einmal. Das ist unbedenklich, denn einen Wert zweimal auf 0 oder 1 zu setzen ändert nichts.

Warum scheitert HTTPS am selbstsignierten Zertifikat eines NVR?

Ein selbstsigniertes Zertifikat hat das Gerät für sich selbst signiert, also bürgt keine öffentliche Zertifizierungsstelle dafür. Der Kommentar in der Firmware sagt, dass Reolink-NVRs häufig eines nutzen, und der TLS-Client des ESP32 lehnt so ein Zertifikat ab, sofern du nichts anderes festlegst. Die Firmware von Gizmo Reolink Switch ruft secureClient.setInsecure() auf, was der Arduino-ESP32-Header so beschreibt: "Don't validate the chain, just accept whatever is given. VERY INSECURE!".

Der Kompromiss, Option für Option:

OptionVerschlüsseltServeridentität geprüftKosten
setInsecure()JaNeinKeine, aber jemand in deinem LAN könnte sich als NVR ausgeben (das macht Gizmo Reolink Switch)
setCACert() mit dem eigenen Zertifikat des NVRJaJaDu musst das Zertifikat einfügen und aktualisieren, wenn der NVR es erneuert
Ein Zertifikat unter deiner Kontrolle, von deiner eigenen CAJaJaDu betreibst die CA und installierst das Zertifikat auf dem NVR

Wer die Prüfung überspringt, verschlüsselt den Verkehr trotzdem, ein passiver Sniffer in deinem WLAN sieht also nichts Brauchbares. Einen aktiven Man-in-the-Middle hält das aber nicht auf: Er könnte sein eigenes Zertifikat vorzeigen und das NVR-Passwort abgreifen. In einem Heimnetz halte ich das für vertretbar bei einem Gerät, das nur zwei Einstellungen umschaltet. In einem Netz, dem du nicht traust, pinne das Zertifikat mit setCACert().

Das Sitzungs-Token reist außerdem im Query-String der URL, so wie die Firmware sie baut. Behandle es für die Dauer seines Lease also wie ein Passwort. Ob der NVR die Anfrage-URLs protokolliert, habe ich nicht geprüft.

Was machen Mute und Restore wirklich?

Mute schaltet Push-Benachrichtigungen und Aufzeichnung auf jedem Online-Kanal aus. Restore schaltet beides wieder ein. Mehr ist es nicht, und die zweite Hälfte ist wichtig: Restore liest nicht den früheren Zustand des NVR und stellt ihn wieder her. Es setzt Benachrichtigungen und Aufzeichnung auf den Kanälen, die der Switch stummgeschaltet hat, auf aktiviert. Hattest du auf einem Kanal die Aufzeichnung absichtlich ausgeschaltet, ist sie nach dem ersten Verlassen des Ruhemodus wieder an.

Zwei Reihen von Kästen: Mute (Login, Kanalstatus, in Flash speichern, enable 0) und Restore (enable 1, Flash leeren, alle 60 Sekunden erneut versuchen)

Ich habe "nur rückgängig machen, was du geändert hast" gewählt statt eines vollständigen Snapshots, der jede Einstellung zurücklesen und speichern müsste. Der Preis ist die Einschränkung oben, und das README sagt es ebenfalls. Der Vorteil ist ein kleiner, testbarer Zustand: zwei Bitmasken, eine für Benachrichtigungen und eine für Aufzeichnung, mit einem Bit pro Kanal.

Die Reihenfolge ist der Punkt:

  1. Langer Tastendruck. Die Firmware meldet sich an (oder nutzt ein gültiges Token weiter) und ruft GetChannelstatus auf, um die Online-Kanäle zu finden.
  2. Erst speichern. Sie schreibt die stummgeschalteten Kanäle in den Flash (NVS), bevor sie einen Mute-Befehl sendet, damit sich auch eine abgebrochene Anfrage noch rückgängig machen lässt.
  3. Mute. Ein gebündelter POST setzt enable für die Push- und Aufzeichnungseinstellungen jedes Kanals auf 0. Einstellungen, die der NVR ablehnt, fliegen aus der gespeicherten Liste, weil sie sich nie geändert haben.
  4. Countdown. Der Timer startet erst, wenn das Mute fertig ist, damit die Netzwerkaufrufe ihm keine Zeit klauen.
  5. Restore. Bei Timer-Ende oder Abbruch sendet die Firmware enable 1 für die gespeicherten Einstellungen und vergisst nur die, die der NVR bestätigt hat.

Die Maskenlogik hat native Tests, du kannst sie also ohne Board ausführen: pio test -e native in microcontroller/.

Was passiert nach einem Neustart oder Stromausfall im Ruhemodus?

Die Firmware stellt die Kameras gleich nach dem Booten wieder her. Die Masken der stummgeschalteten Kanäle liegen in NVS, dem Key-Value-Flash-Speicher des ESP32, und setup() prüft sie: Ist noch ein Kanal stummgeschaltet, setzt es ein Flag für ein sofortiges Restore, und die Loop führt es aus, sobald das WLAN steht. Der Countdown wird nicht gespeichert, ein Neustart beendet den Ruhemodus also früher, statt die Kameras stumm zu lassen. Das halte ich für den richtigen Fehlerfall: Eine Kamera, die zu viel aufzeichnet, ist besser als eine, die stillschweigend gar nichts aufzeichnet.

Die anderen Fehler folgen derselben Regel: Maske behalten, bis der NVR bestätigt:

SituationWas die Firmware tutDas zeigt das LCD
Das WLAN ist beim Restore wegBehält die Maske, versucht es alle 60 s erneutWi-Fi Offline / Will retry
NVR nicht erreichbar oder Befehl abgelehntBehält die Maske, versucht es alle 60 s erneutRestore Failed / Will retry
Eine stummgeschaltete Kamera ist offlineStellt die Online-Kameras wieder her, lässt den Rest offenCam Offline! / Will retry
Der NVR lehnt einige Mute-Befehle abNimmt sie aus der Maske, behält den CountdownPartly Muted! / Some cams failed
Der NVR lehnt den Login ab (falsches Passwort)Pausiert Logins für 10 MinutenNVR Login Err!, dann Login Paused / Check password
Restore steht noch aus, Timer läuft nichtWartet auf einen neuen Versuch, oder ein langer Tastendruck versucht es sofortAlerts Still OFF / Hold to retry

Hältst du den Taster gedrückt, während Alerts Still OFF auf dem Display steht, versucht die Firmware es sofort erneut. Der Werksreset (BOOT-Taste 10 Sekunden gehalten) und die Änderung des NVR-Logins werden beide abgelehnt, solange Kameras stummgeschaltet sind, denn der gespeicherte Login ist es, der sie wiederherstellt.

Welche Teile und Pins nutzt der Aufbau?

Das Board ist ein Seeed Studio XIAO ESP32-S3 mit angeschlossener FPC-Antenne: Das XIAO hat keine Antenne auf der Platine und verbindet sich ohne eine nicht mit dem WLAN. Die Pins stammen aus config.cpp.

TeilPad am XIAO ESP32-S3GPIOHinweise
TasterD01Nach GND, interner Pull-up (INPUT_PULLUP)
BuzzerD12Mit HIGH und LOW angesteuert, 50 ms oder 800 ms an
LCD SDAD4516x2-I2C-LCD, Backpack bei 0x27
LCD SCLD56I2C-Takt
Stromversorgung für LCD und Buzzer5V und GND-So steht es im README: das 5-V-Pad des Boards

Der LCD-Treiber ist die Klasse hd44780_I2Cexp aus duinoWitchery/hd44780 1.3.2, die das I2C-Backpack und seine Adresse selbst findet (das README nennt 0x27, aber die Firmware liest diese Konstante nie). Bleibt dein Display leer, deckt die Checkliste in ESP32 I2C-LCD 16x2 funktioniert nicht Adresse, 5-V-Versorgung und Kontrast ab. Der Buzzer wird mit einfachem digitalWrite geschaltet, nimm also einen, der bei einem Gleichspannungspegel Ton macht (einen aktiven Buzzer), keinen passiven, der ein Tonsignal braucht. Die Pinwahl umgeht D2 (GPIO3), einen Boot-Strapping-Pin, und die seriellen Pads D6 und D7. Zu den übrigen Pins des Boards siehe XIAO ESP32-S3 Pinbelegung: Welche Pins sind sicher.

Wie arbeiten Taster, Buzzer und LCD zusammen?

Ein Taster macht alles, mit 40 ms Entprellung und einem langen Druck ab 700 ms.

  • Kurzer Tastendruck im Leerlauf: Zeit hinzufügen. Unter 5 Minuten kommt 1 Minute dazu, danach 5 Minuten pro Druck bis 60. Der nächste Druck springt auf null zurück, sodass du ein Überschießen korrigieren kannst, ohne den Timer zu starten.
  • Langer Tastendruck im Leerlauf: Ruhemodus starten. Das LCD zeigt Hold to mute mit Mute for <time>.
  • Kurzer Tastendruck bei laufendem Timer: ändert nichts und zeigt Alerts OFF / Hold to cancel.
  • Langer Tastendruck bei laufendem Timer: abbrechen und wiederherstellen.

Der Buzzer gibt einen 50-ms-Piep für eine Auswahl, einen 800-ms-Piep für einen gestarteten Ruhemodus oder ein abgeschlossenes Restore und einen Doppelpiep als Warnung (teilweises Mute, fehlgeschlagenes Restore). In jeder der letzten beiden Sekunden des Countdowns piept er einmal. Fehlgeschlagene Wiederholungen im Hintergrund bleiben lautlos, damit eine Kamera, die offline ist, nicht jede Minute piept.

Weitere LCD-Meldungen in der Reihenfolge, in der sie dir begegnen: Reolink Switch / Booting now..., Join Wi-Fi Setup, Set Up NVR: Open (mit der Adresse des Switches), Checking NVR / Connecting..., NVR Linked / 3 cams online (die Zahl ist deine Anzahl Online-Kameras), Quiet Mode ON / Muting cameras, Cameras Muted! / Exit safely!, Alerts OFF / 12:34 left (das Format ist die Restzeit) und Time Is Up / Alerts restored!. Solange die Firmware mit dem NVR spricht, verwirft sie Tastendrücke absichtlich, weil ein verspäteter Druck sonst auf dem nächsten Bildschirm wirken würde.

Wie richtest du WLAN und NVR-Login ein?

In die Firmware ist nichts einkompiliert. Beim ersten Start zeigt das LCD Join Wi-Fi Setup, und der Switch öffnet einen offenen Hotspot namens Gizmo-Reolink; das Captive Portal deines Smartphones öffnet die Einrichtungsseite. Erscheint das Popup nicht, hilft ESP32 Captive Portal funktioniert nicht? So behebst du das WLAN-Popup. Dann nimmt die NVR-Seite des Dashboards Adresse, Benutzername und Passwort entgegen, testet den Login und zählt die Online-Kameras.

Drei Smartphone-Screenshots der Web-App des Switches: Switch-Status, NVR-Login und WLAN-Einrichtung

Der Login wird in NVS auf dem Board gespeichert. Das Projekt aktiviert keine Flash-Verschlüsselung (nichts in platformio.ini tut das), jemand mit physischem Zugriff und einem USB-Kabel könnte ihn also wohl auslesen. Das Passwort lässt sich nur schreiben, nie auslesen: Das Dashboard bekommt es nie zurück, und wer die NVR-Adresse oder den Benutzernamen ändert, löscht es, sodass es nur an den NVR gesendet wird, für den es eingegeben wurde.

Das Dashboard kann den Ruhemodus nicht starten, abbrechen oder erneut versuchen. Das ist Absicht: Niemand in deinem WLAN kann deine Kameras stummschalten, ohne am Switch zu stehen. Die Firmware gibt es als vorgebautes Release, das du von der Projektseite flashen kannst, wie in ESP Web Tools: einen ESP32 direkt im Browser flashen erklärt. Für andere Wege, einem Board sein WLAN beizubringen, siehe ESP32 WLAN-Provisioning: Captive Portal, BLE, Improv.

Zahlen, die du kennen solltest

WertEinstellungWoher es kommt
10 sHTTP-Timeout pro AnfrageREOLINK_HTTP_TIMEOUT_MS
60 sWiederholungsintervall des Restore und Vorlauf der Token-ErneuerungREOLINK_RESTORE_RETRY_MS, TOKEN_REFRESH_MARGIN_SECONDS
10 minLogin-Pause nach einem abgelehnten LoginREOLINK_LOGIN_PAUSE_MS
16.384 BytesGrößte akzeptierte NVR-AntwortREOLINK_MAX_REPLY_BYTES
60 minLängster RuhemodusTIMER_MAX_DURATION_SECONDS
3600 sAngenommenes Token-Lease, wenn die Antwort keines enthältDEFAULT_TOKEN_LEASE_SECONDS

Was kann dieser Aufbau nicht, und wie geht es weiter?

Der Switch stellt Alarme und Aufzeichnung auf aktiviert zurück, nicht auf den vorherigen Stand. Er spricht über das lokale Netzwerk mit einem NVR, ohne Zertifikatsprüfung. Das Repository sagt nicht, mit welchem NVR-Modell oder welcher Firmware-Version getestet wurde, und ich kann dir nicht sagen, welche diese Befehle akzeptieren. Führe also die Verbindungsprüfung auf der NVR-Seite aus, bevor du ihm die Haustür anvertraust.

Wenn du die komplette Teileliste und den Flash-Button willst, öffne Gizmo Reolink Switch. Für ein Gehäuse zum Einbauen fang mit 3D-gedruckte ESP32-Gehäuse: Konstruktionsregeln, die passen an, und für das große Ganze, wie diese Projekte zusammenpassen, lies Was ist OpenGizmo?.

Haufig gestellte Fragen

Finden Sie schnelle Antworten auf die haufigsten Fragen zu diesem Thema.

Ja. Ein ESP32 im selben Netzwerk kann sich an der HTTPS-API des NVR anmelden, ein Sitzungs-Token erhalten und Befehle senden, die Push-Benachrichtigungen und Aufzeichnung pro Kanal ein- oder ausschalten. Ich habe nicht geprüft, welche NVR-Modelle und Firmware diese Befehle akzeptieren, also teste deinen NVR, bevor du etwas darauf aufbaust.

Veroffentlicht Aktualisiert

Lust, dein eigenes Gizmo zu bauen?

Such dir ein Open-Source-Projekt mit dem ESP32 aus und folge der Schritt-für-Schritt-Anleitung, von der Teileliste und der Verkabelung bis zur Firmware und zum ersten Start.

Lies auch

Kategorien entdecken