Controlar un NVR Reolink con ESP32: API, mute y restore

Un ESP32 puede silenciar un NVR Reolink con su API HTTPS: token de login, comandos por canal, certificados autofirmados y un restore que aguanta un reinicio.

Publicado
Tiempo de lectura
10 min
Categoría
Proyectos
Un hombre pulsa el botón de un pequeño interruptor de pared, con líneas discontinuas que lo unen a tres cámaras de seguridad, cada una con un ojo tachado.

En resumen

Un ESP32 hace login en la API HTTPS del NVR Reolink, obtiene un token y envía los comandos SetPushV20 y SetRecV20 por canal. El restore reactiva ambos, incluso tras un reinicio.

Sí, un ESP32 puede controlar un NVR Reolink. Hace login en la API HTTPS del NVR en /api.cgi, recibe un token de sesión y envía los comandos SetPushV20 y SetRecV20 para apagar, canal por canal, las notificaciones push y la grabación. Un segundo juego de comandos las vuelve a encender.

Sales de casa, tus propios movimientos llenan el NVR de alertas y no tienes ganas de abrir la app de Reolink cada vez. Este artículo sigue el firmware real de Gizmo Reolink Switch, una XIAO ESP32-S3 con un botón, un zumbador y un LCD 16x2. Cada pin, número y mensaje de abajo sale de su repositorio de código abierto, y al final señalo lo que no pude verificar.

Proyecto open source ESP32 + Reolink
Gizmo Reolink Switch

Interruptor ESP32 de salida silenciosa con pulsador, zumbador, LCD I2C 16x2 y Wi-Fi para silenciar un rato las alertas y la grabación de un NVR Reolink.

  • Temporizador de salida silenciosa
  • Interfaz con pantalla LCD 16x2
  • Control directo de la API de Reolink
Echar un vistazo

Un dibujo animado de un hombre agachado en un patio trasero, asustado por una cámara de seguridad fijada a la pared

La API HTTP de Reolink es una interfaz JSON que sirve el propio NVR. Envías peticiones HTTPS POST a https://<nvr>/api.cgi?cmd=<Command>&token=<token>, y el cuerpo es siempre un array JSON de comandos, aunque haya uno solo. No encontré ninguna página oficial de la API de Reolink que pudiera enlazar, así que mi referencia es el código fuente del firmware, y todo lo que sigue describe lo que ese firmware envía y lee.

El firmware no usa autenticación Basic ni Digest. Envía un comando Login con token=null en la URL y el usuario y la contraseña en el cuerpo JSON. La respuesta trae el nombre de un token y un tiempo de lease en segundos, y el token va en el parámetro &token= de todas las llamadas siguientes.

ComandoQué hacePara qué lo usa el firmware
LoginDevuelve Token name y leaseTimeObtener un token de sesión
GetChannelstatusLista los canales con un indicador onlineEncontrar las cámaras que silenciar (solo online)
SetPushV20Configura las notificaciones push por canalSilenciar y restaurar las alertas
SetRecV20Configura la grabación por canalSilenciar y restaurar la grabación

Los detalles de las peticiones del firmware están en reolink.cpp y reolink_protocol.cpp:

  • Lease del token. Si la respuesta no trae leaseTime, el firmware asume 3600 segundos. Ese valor por defecto es una decisión de mi firmware, no un valor documentado por Reolink. Renueva el token 60 segundos antes de que acabe el lease.
  • Sesión caducada. El código de error -6 significa una sesión ausente o caducada. El firmware vuelve a hacer login y repite la llamada una vez.
  • Batching. El mute es un solo POST con una entrada SetPushV20 y una SetRecV20 por cada canal online, y el firmware lee el resultado de cada entrada.
  • Parámetros. Cada entrada lleva channel, enable y scheduleEnable, todos a 0 para silenciar y a 1 para restaurar.
  • Límites. El timeout HTTP es de 10 segundos, se rechaza una respuesta de más de 16.384 bytes, y el firmware controla los canales del 0 al 31 (lee como máximo 16 canales online).

No verifiqué qué modelos y versiones de firmware de NVR aceptan estos comandos, así que tómalo como lo que hace el firmware, no como una promesa sobre tu NVR. Antes, lanza un Login y un GetChannelstatus desde tu computadora para ver qué responde el tuyo.

¿Cómo es el código del ESP32?

El firmware usa el framework Arduino sobre PlatformIO (framework = arduino, platform = espressif32 @ 8.0.0 en platformio.ini). No usa esp_http_client: la parte HTTP es el HTTPClient de Arduino sobre un WiFiClientSecure, con ArduinoJson 7.2.2 para los cuerpos. Si estás eligiendo toolchain, mira Arduino IDE vs PlatformIO para ESP32.

El núcleo de una petición es corto. Esta es una versión recortada de lo que hace el firmware, no una copia:

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":"..."}}}])");
Lín. 8, col. 1UTF-8cpp

Dos detalles ahorran memoria. El firmware mantiene abierta una sola conexión TLS para todas las peticiones de un mute o un restore, de modo que comparten un único handshake, y luego la cierra para que ninguna sesión TLS inactiva ocupe el heap. Si mientras tanto el NVR cerró la conexión mantenida, el firmware se reconecta y reenvía los mismos comandos, algo seguro porque poner un valor a 0 o a 1 dos veces no cambia nada.

¿Por qué falla HTTPS con el certificado autofirmado de un NVR?

Un certificado autofirmado es el que el propio dispositivo firmó para sí mismo, así que ninguna autoridad de certificación pública responde por él. El comentario del propio firmware dice que los NVR Reolink suelen usar uno, y el cliente TLS del ESP32 rechaza un certificado así salvo que le indiques otra cosa. El firmware de Gizmo Reolink Switch llama a secureClient.setInsecure(), que el header de Arduino-ESP32 describe como "Don't validate the chain, just accept whatever is given. VERY INSECURE!".

El compromiso, opción por opción:

OpciónCifradoIdentidad del servidor verificadaCoste
setInsecure()SíNoNinguno, pero alguien en tu LAN podría hacerse pasar por el NVR (es lo que hace Gizmo Reolink Switch)
setCACert() con el certificado del propio NVRSíSíTienes que pegar el certificado y actualizarlo cuando el NVR lo renueve
Un certificado bajo tu control, de tu propia CASíSíTú gestionas la CA e instalas el certificado en el NVR

Omitir la verificación sigue cifrando el tráfico, así que un sniffer pasivo en tu Wi-Fi no ve nada útil. Lo que no frena es a un atacante man-in-the-middle activo, que podría presentar su propio certificado y recoger la contraseña del NVR. En una LAN doméstica me parece aceptable para un dispositivo que solo cambia dos ajustes. En una red en la que no confías, fija el certificado con setCACert().

El token de sesión también viaja en la query string de la URL, tal como la construye el firmware, así que trátalo como una contraseña mientras dure su lease. No comprobé si el NVR registra las URL de las peticiones.

¿Qué hacen realmente mute y restore?

El mute apaga las notificaciones push y la grabación en todos los canales online. El restore vuelve a encender ambas. Eso es todo, y la segunda mitad importa: el restore no lee el estado anterior del NVR para devolverlo. Pone notificaciones y grabación en activado en los canales que el switch silenció. Si habías apagado la grabación de un canal a propósito, vuelve a encenderse tras la primera salida del modo silencioso.

Dos filas de cajas: mute (login, estado de los canales, guardar en flash, enable 0) y restore (enable 1, vaciar la flash, reintentar cada 60 segundos)

Elegí "deshacer solo lo que cambiaste" en lugar de una instantánea completa, que obligaría a leer y guardar cada ajuste. El coste es el límite de arriba, y el README también lo dice. La ventaja es un estado pequeño y fácil de probar: dos bitmasks, una para notificaciones y otra para grabación, con un bit por canal.

El orden es lo importante:

  1. Pulsación larga. El firmware hace login (o reutiliza un token válido) y llama a GetChannelstatus para encontrar los canales online.
  2. Primero guardar. Escribe los canales silenciados en flash (NVS) antes de enviar ningún comando de mute, de modo que una petición interrumpida aún se pueda deshacer.
  3. Mute. Un único POST en batch pone enable a 0 en los ajustes de push y de grabación de cada canal. Los ajustes que el NVR rechaza se quitan de la lista guardada, porque nunca cambiaron.
  4. Cuenta atrás. El temporizador arranca solo cuando el mute terminó, para que las llamadas de red no le roben tiempo.
  5. Restore. Al terminar el temporizador o al cancelar, el firmware envía enable 1 para los ajustes guardados y olvida solo los que el NVR confirmó.

La lógica de las máscaras tiene tests nativos, así que puedes ejecutarla sin placa: pio test -e native en microcontroller/.

¿Qué pasa tras un reinicio o un apagón mientras está silenciado?

El firmware restaura las cámaras justo después de arrancar. Las máscaras de lo silenciado viven en NVS, el almacenamiento clave-valor en flash del ESP32, y setup() las comprueba: si algún canal sigue silenciado, marca un restore inmediato, y el loop lo ejecuta en cuanto hay Wi-Fi. La cuenta atrás no se guarda, así que un reinicio termina el modo silencioso antes de tiempo en vez de dejar las cámaras mudas. Creo que es el fallo correcto: mejor una cámara que graba de más que una que no graba nada en silencio.

Los demás fallos siguen la misma regla, conservar la máscara hasta que el NVR confirme:

SituaciónQué hace el firmwareQué muestra el LCD
El Wi-Fi está caído en el momento del restoreConserva la máscara, reintenta cada 60 sWi-Fi Offline / Will retry
NVR inalcanzable o comando rechazadoConserva la máscara, reintenta cada 60 sRestore Failed / Will retry
Una cámara silenciada está offlineRestaura las que están online, deja el resto pendienteCam Offline! / Will retry
El NVR rechaza algunos comandos de muteLos quita de la máscara, mantiene la cuenta atrásPartly Muted! / Some cams failed
El NVR rechaza el login (contraseña incorrecta)Pausa los logins durante 10 minutosNVR Login Err!, luego Login Paused / Check password
Restore aún pendiente, temporizador paradoEspera un reintento, o una pulsación larga reintenta yaAlerts Still OFF / Hold to retry

Mantener pulsado el botón mientras Alerts Still OFF está en pantalla reintenta de inmediato. El restablecimiento de fábrica (botón BOOT pulsado 10 segundos) y el cambio del login del NVR se rechazan ambos mientras haya cámaras silenciadas, porque el login guardado es lo que las restaura.

¿Qué piezas y pines usa el proyecto?

La placa es una Seeed Studio XIAO ESP32-S3 con la antena FPC conectada: la XIAO no lleva antena en la placa y sin ella no se une al Wi-Fi. Los pines salen de config.cpp.

PiezaPad de la XIAO ESP32-S3GPIONotas
BotónD01A GND, pull-up interna (INPUT_PULLUP)
ZumbadorD12Controlado en HIGH y LOW, encendido 50 ms u 800 ms
LCD SDAD45LCD I2C 16x2, backpack en 0x27
LCD SCLD56Reloj I2C
Alimentación del LCD y del zumbador5V y GND-Como lo indica el README: el pad de 5 V de la placa

El driver del LCD es la clase hd44780_I2Cexp de duinoWitchery/hd44780 1.3.2, que encuentra sola el backpack I2C y su dirección (el README la indica en 0x27, pero el firmware nunca lee esa constante). Si tu pantalla se queda en blanco, la lista de ESP32 con LCD I2C 16x2 que no funciona cubre la dirección, la alimentación de 5 V y el contraste. El zumbador se maneja con un simple digitalWrite, así que usa uno que suene con un nivel DC (un zumbador activo), no uno pasivo que necesite un tono. La elección de pines evita D2 (GPIO3), un strapping pin de arranque, y los pads serie D6 y D7. Para el resto de pines de la placa, consulta Pinout de la XIAO ESP32-S3: qué pines son seguros.

¿Cómo trabajan juntos el botón, el zumbador y el LCD?

Un solo botón lo hace todo, con un debounce de 40 ms y una pulsación larga a los 700 ms.

  • Pulsación corta en reposo: añade tiempo. Suma 1 minuto por debajo de 5 minutos, luego de 5 en 5 hasta 60. La siguiente pulsación vuelve a cero, así que si te pasas puedes corregirlo sin arrancar el temporizador.
  • Pulsación larga en reposo: inicia el modo silencioso. El LCD muestra Hold to mute con Mute for <time>.
  • Pulsación corta con el temporizador en marcha: no cambia nada y muestra Alerts OFF / Hold to cancel.
  • Pulsación larga con el temporizador en marcha: cancela y restaura.

El zumbador da un pitido de 50 ms para una selección, uno de 800 ms para un modo silencioso iniciado o un restore completado, y un doble pitido como aviso (mute parcial, restore fallido). Pita una vez en cada uno de los dos últimos segundos de la cuenta atrás. Los reintentos fallidos en segundo plano son silenciosos, para que una cámara offline no pite cada minuto.

Otros mensajes del LCD, en el orden en que los ves: Reolink Switch / Booting now..., Join Wi-Fi Setup, Set Up NVR: Open (con la dirección del switch), Checking NVR / Connecting..., NVR Linked / 3 cams online (el número de cámaras online que tengas), Quiet Mode ON / Muting cameras, Cameras Muted! / Exit safely!, Alerts OFF / 12:34 left (el formato es el tiempo restante) y Time Is Up / Alerts restored!. Mientras el firmware habla con el NVR descarta las pulsaciones del botón a propósito, porque una pulsación tardía actuaría sobre la pantalla siguiente.

¿Cómo se configuran el Wi-Fi y el login del NVR?

Nada está compilado en el firmware. En el primer arranque el LCD muestra Join Wi-Fi Setup y el switch abre un hotspot abierto llamado Gizmo-Reolink; el portal cautivo de tu teléfono abre la página de configuración. Si el aviso no aparece, mira ¿El portal cautivo del ESP32 no funciona? Cómo arreglar el aviso del Wi-Fi. Después, la página NVR del panel pide la dirección, el usuario y la contraseña, prueba el login y cuenta las cámaras online.

Tres capturas de teléfono de la aplicación web del switch: estado del switch, login del NVR y configuración del Wi-Fi

El login se guarda en NVS en la placa. El proyecto no activa el cifrado de la flash (nada en platformio.ini lo hace), así que alguien con acceso físico y un cable USB probablemente podría leerlo. La contraseña es de solo escritura: el panel nunca la recibe de vuelta, y cambiar la dirección o el usuario del NVR la borra, así que solo se envía al NVR para el que se escribió.

El panel no puede iniciar, cancelar ni reintentar el modo silencioso. Es a propósito: nadie en tu Wi-Fi puede silenciar tus cámaras sin estar junto al switch. El firmware se publica como release precompilada que puedes flashear desde la página del proyecto, como se explica en ESP Web Tools: flashea un ESP32 desde el navegador. Para otras formas de darle el Wi-Fi a una placa, mira Aprovisionamiento Wi-Fi del ESP32: portal cautivo, BLE, Improv.

Números que conviene conocer

ValorAjusteDe dónde sale
10 sTimeout HTTP por peticiónREOLINK_HTTP_TIMEOUT_MS
60 sIntervalo de reintento del restore, y margen de renovación del tokenREOLINK_RESTORE_RETRY_MS, TOKEN_REFRESH_MARGIN_SECONDS
10 minPausa de logins tras un login rechazadoREOLINK_LOGIN_PAUSE_MS
16.384 bytesRespuesta más grande aceptada del NVRREOLINK_MAX_REPLY_BYTES
60 minModo silencioso más largoTIMER_MAX_DURATION_SECONDS
3600 sLease del token asumido cuando la respuesta no trae ningunoDEFAULT_TOKEN_LEASE_SECONDS

¿Qué no hace este proyecto, y hacia dónde seguir?

El switch restaura las alertas y la grabación a activadas, no a como estaban. Habla con un solo NVR por la red local, sin comprobar el certificado. El repositorio no dice con qué modelo o versión de firmware de NVR se probó, y no puedo decirte cuáles aceptan estos comandos, así que ejecuta la comprobación de conexión de la página NVR antes de confiarle la puerta de entrada.

Si quieres la lista completa de piezas y el botón para flashear, abre Gizmo Reolink Switch. Para una carcasa donde meterlo, empieza por Reglas de diseño de carcasas ESP32 impresas en 3D que encajan, y para ver cómo encajan entre sí estos proyectos, lee ¿Qué es OpenGizmo?.

Preguntas frecuentes

Encuentra respuestas rápidas a las preguntas más comunes sobre este tema.

Sí. Un ESP32 en la misma red puede hacer login en la API HTTPS del NVR, recibir un token de sesión y enviar comandos que activan o desactivan por canal las notificaciones push y la grabación. No he verificado qué modelos y firmware de NVR aceptan estos comandos, así que prueba tu NVR antes de construir algo encima.

Publicado Actualizado

¿Listo para montar tu propio gizmo?

Elige un proyecto open source con ESP32 y sigue su guía paso a paso, desde la lista de componentes y el cableado hasta el firmware y el primer arranque.

Lee también

Explora las categorías