Integración con Home Assistant

La mejor manera de integrarse con Home Assistant es utilizar la integración oficial.

Instalación

Preparación

La integración de SecureVu requiere que la integración mqtt esté instalada y configurada manualmente primero.

Consulta la documentación de la integración MQTT para obtener más detalles.

Además, MQTT debe estar habilitado en tu archivo de configuración de SecureVu y SecureVu debe estar conectado al mismo servidor MQTT que Home Assistant para que muchas de las entidades creadas por la integración funcionen, por ejemplo:

mqtt:
  enabled: True
  host: mqtt.server.com # the address of your HA server that's running the MQTT integration
  user: your_mqtt_broker_username
  password: your_mqtt_broker_password

Instalación de la integración

Disponible a través de HACS como repositorio predeterminado. Para instalar:

• Usa HACS para instalar la integración:

Home Assistant > HACS > Click in the Search bar and type "SecureVu" > SecureVu

• Reinicia Home Assistant.
• Luego agrega/configura la integración:

Home Assistant > Settings > Devices & Services > Add Integration > SecureVu

Nota: También necesitarás tener media_source habilitado en tu configuración de Home Assistant para que aparezca el Navegador de Medios.

(Opcional) Instalación de la tarjeta Lovelace

Para instalar la tarjeta Lovelace complementaria opcional, consulta las instrucciones de instalación separadas para esa tarjeta.

Configuración

Al configurar la integración, se te pedirá la URL de tu instancia de SecureVu, que puede apuntar al puerto no autenticado interno (5000) o al puerto autenticado (8971) de tu instancia. Esto puede verse como http://<host>:5000/.

Ejemplos con Docker Compose

Si estás ejecutando Home Assistant y SecureVu con Docker Compose en el mismo dispositivo, aquí hay algunos ejemplos.

Home Assistant ejecutándose con red de host

No se recomienda ejecutar SecureVu en modo de red de host. En este ejemplo, usarías http://172.17.0.1:5000 o http://172.17.0.1:8971 al configurar la integración.

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    network_mode: host
    ...

  securevu:
    image: ghcr.io/securecorp-mexico/securevu2:stable
    ...
    ports:
      - "172.17.0.1:5000:5000"
      ...

Home Assistant sin red de host o en un archivo compose separado

En este ejemplo, se recomienda conectarse al puerto autenticado, por ejemplo, http://securevu:8971 al configurar la integración. No es necesario mapear el puerto para el contenedor de SecureVu.

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    # network_mode: host
    ...

  securevu:
    image: ghcr.io/securecorp-mexico/securevu2:stable
    ...
    ports:
      # - "172.17.0.1:5000:5000"
      ...

Aplicación Home Assistant

Si estás usando la aplicación Home Assistant, la URL debe ser una de las siguientes dependiendo de la variante de la aplicación que estés usando. Ten en cuenta que si estás usando la aplicación Proxy, NO debes apuntar la integración a la URL del proxy. Simplemente ingresa la misma URL utilizada para acceder a SecureVu directamente desde tu red.

Variante de la aplicación	URL
SecureVu	http://ccab4aaf-securevu:5000
SecureVu (Full Access)	http://ccab4aaf-securevu-fa:5000
SecureVu Beta	http://ccab4aaf-securevu-beta:5000
SecureVu Beta (Full Access)	http://ccab4aaf-securevu-fa-beta:5000

SecureVu ejecutándose en una máquina separada

Si ejecutas SecureVu en un dispositivo separado dentro de tu red local, Home Assistant necesitará acceso al puerto 8971.

Red local

Usa http://<securevu_device_ip>:8971 como URL para la integración de modo que se requiera autenticación.

tip

La URL anterior asume que tienes TLS deshabilitado. Por defecto, TLS está habilitado y SecureVu usará un certificado autofirmado. HomeAssistant fallará al conectarse por HTTPS al puerto 8971 ya que no puede verificar el certificado autofirmado. Deshabilita TLS y usa HTTP desde HomeAssistant, o configura SecureVu para ser accesible con un certificado válido.

services:
  securevu:
    image: ghcr.io/securecorp-mexico/securevu2:stable
    ...
    ports:
      - "8971:8971"
      ...

Tailscale u otra red privada

Usa http://<securevu_device_tailscale_ip>:5000 como URL para la integración.

services:
  securevu:
    image: ghcr.io/securecorp-mexico/securevu2:stable
    ...
    ports:
      - "<tailscale_ip>:5000:5000"
      ...

Opciones

Home Assistant > Configuration > Integrations > SecureVu > Options

Opción	Descripción
RTSP URL Template	Una plantilla jinja2 que se usa para reemplazar la URL de transmisión RTSP estándar (p. ej., para uso con proxies inversos). Esta opción solo se muestra a usuarios que tienen el modo avanzado habilitado. Consulta transmisiones RTSP más abajo.

Entidades Proporcionadas

Plataforma	Descripción
camera	Transmisión de cámara en vivo (requiere RTSP).
image	Imagen del último objeto detectado para cada cámara.
sensor	Estados para monitorear el rendimiento de SecureVu, conteos de objetos para todas las zonas y cámaras.
switch	Entidades de interruptor para activar/desactivar detección, grabaciones e instantáneas.
binary_sensor	Una entidad de sensor binario de "movimiento" por cámara/zona/objeto.

Soporte para Navegador de Medios

La integración proporciona:

• Navegación de grabaciones de objetos rastreados con miniaturas
• Navegación de instantáneas
• Navegación de grabaciones por mes, día, cámara, hora

Esto es accesible a través de "Navegador de Medios" en el panel del menú izquierdo en Home Assistant.

Transmisión de Clips a Dispositivos de Medios

La integración admite la transmisión de clips y transmisiones de cámara a dispositivos de medios compatibles.

tip

Para que los clips puedan transmitirse a dispositivos de medios, se requiere audio y puede ser necesario habilitarlo para las grabaciones.

NOTA: Incluso si tu cámara no admite audio, el audio deberá estar habilitado para que la Transmisión sea aceptada.

API de Cámara

Para deshabilitar una cámara dinámicamente

action: camera.turn_off
data: {}
target:
  entity_id: camera.back_deck_cam  # your SecureVu camera entity ID

Para habilitar una cámara que ha sido deshabilitada dinámicamente

action: camera.turn_on
data: {}
target:
  entity_id: camera.back_deck_cam  # your SecureVu camera entity ID

API de Notificaciones

Muchas personas no quieren exponer SecureVu a la web, por lo que la integración crea algunos endpoints de API públicos que pueden usarse para notificaciones.

Para cargar una miniatura de un objeto rastreado:

https://HA_URL/api/securevu/notifications/<event-id>/thumbnail.jpg

Para cargar una instantánea de un objeto rastreado:

https://HA_URL/api/securevu/notifications/<event-id>/snapshot.jpg

Para cargar un clip de video de un objeto rastreado usando un dispositivo Android:

https://HA_URL/api/securevu/notifications/<event-id>/clip.mp4

Para cargar un clip de video de un objeto rastreado usando un dispositivo iOS:

https://HA_URL/api/securevu/notifications/<event-id>/master.m3u8

Para cargar un gif de vista previa de un objeto rastreado:

https://HA_URL/api/securevu/notifications/<event-id>/event_preview.gif

Para cargar un gif de vista previa de un elemento de revisión:

https://HA_URL/api/securevu/notifications/<review-id>/review_preview.gif

Para cargar la miniatura de un elemento de revisión:

https://HA_URL/api/securevu/notifications/<review-id>/<camera>/review_thumbnail.webp

Transmisión RTSP

Para que las transmisiones en vivo funcionen, deben ser accesibles en el puerto RTSP (predeterminado: 8554) en <securevuhost>:8554. Home Assistant se conectará directamente a ese puerto de transmisión cuando se vea la cámara en vivo.

Plantilla de URL RTSP

Para casos de uso avanzados, este comportamiento puede cambiarse con la opción de plantilla de URL RTSP. Cuando se establece, esta cadena reemplazará la dirección de transmisión predeterminada derivada del comportamiento predeterminado descrito anteriormente. Esta opción admite plantillas jinja2 y tiene las variables del diccionario camera de la API de SecureVu disponibles para la plantilla. Ten en cuenta que ningún estado de Home Assistant está disponible para la plantilla, solo el diccionario de cámara de SecureVu.

Esto es potencialmente útil cuando SecureVu está detrás de un proxy inverso, y/o cuando el puerto de transmisión predeterminado no es accesible para Home Assistant (p. ej., reglas de firewall).

Ejemplos de Plantilla de URL RTSP

Usar un número de puerto diferente:

rtsp://<securevu_host>:2000/front_door

Usar el nombre de la cámara en la URL de transmisión:

rtsp://<securevu_host>:2000/{{ name }}

Usar el nombre de la cámara en la URL de transmisión, convirtiéndolo primero a minúsculas:

rtsp://<securevu_host>:2000/{{ name|lower }}

Soporte para Múltiples Instancias

La integración de SecureVu admite sin problemas el uso de múltiples servidores SecureVu.

Requisitos para Múltiples Instancias

Para que múltiples instancias de SecureVu funcionen correctamente, los parámetros topic_prefix y client_id deben configurarse de manera diferente por servidor. Consulta la configuración de MQTT para saber cómo establecerlos.

URLs de la API

Cuando se configuran múltiples instancias de SecureVu, las URLs de la API deben incluir un identificador para indicarle a Home Assistant a qué instancia de SecureVu hacer referencia. El identificador utilizado es el parámetro MQTT client_id incluido en la configuración, y se usa así:

https://HA_URL/api/securevu/<client-id>/notifications/<event-id>/thumbnail.jpg

https://HA_URL/api/securevu/<client-id>/clips/front_door-1624599978.427826-976jaa.mp4

Tratamiento Predeterminado

Cuando se configura una sola instancia de SecureVu, el parámetro client-id no necesita especificarse en las URLs/identificadores — se asume esa única instancia. Cuando se configuran múltiples instancias de SecureVu, el usuario debe especificar explícitamente a qué servidor se refiere.

Preguntas Frecuentes

Si estoy detectando múltiples objetos, ¿cómo asigno el binary_sensor correcto a la cámara en HomeKit?

La integración de HomeKit vincula aleatoriamente uno de los sensores binarios (entidades de sensor de movimiento) agrupados con el dispositivo de cámara en Home Assistant. Puedes especificar un linked_motion_sensor en la configuración de HomeKit de Home Assistant para cada cámara.

He configurado automatizaciones basadas en los sensores de ocupación. A veces la automatización se ejecuta porque los sensores se activan, pero luego miro en SecureVu y no puedo encontrar el objeto que activó el sensor. ¿Es esto un error?

No. Los sensores de ocupación tienen menos verificaciones porque a menudo se usan para cosas como encender las luces donde la latencia debe ser lo más baja posible. Por lo tanto, los falsos positivos a veces pueden activar estos sensores. Si deseas filtrado de falsos positivos, debes usar un sensor MQTT en el tema securevu/events o securevu/reviews.