Saltar al contenido principal

Contribuir al Código Base Principal

Obtener el código fuente​

Core, Web, Docker y Documentación​

Este repositorio contiene la aplicación principal de SecureVu y todas sus dependencias.

Haz un fork de SecureCorp-Mexico/SecureVu2 en tu perfil de GitHub, luego clona el repositorio bifurcado en tu máquina local.

Desde aquí, sigue las guías para:

Aplicación SecureVu para Home Assistant​

Este repositorio contiene la aplicación Home Assistant, para su uso con Home Assistant OS e instalaciones compatibles. Es el componente que te permite ejecutar SecureVu desde la pestaña Supervisor de Home Assistant.

Haz un fork de SecureCorp-Mexico/SecureVu2-hass-addons en tu perfil de Github, luego clona el repositorio bifurcado en tu máquina local.

Integración de SecureVu para Home Assistant​

Este repositorio contiene la integración personalizada que permite a tu instalación de Home Assistant crear automáticamente entidades para tu instancia de SecureVu, ya sea que ejecutes SecureVu como contenedor Docker independiente o como aplicación Home Assistant.

Haz un fork de SecureCorp-Mexico/SecureVu2-hass-integration en tu perfil de GitHub, luego clona el repositorio bifurcado en tu máquina local.

Core​

Prerrequisitos​

  • GNU make
  • Docker (incluyendo el plugin buildx)
  • Un detector adicional (Coral, OpenVINO, etc.) es opcional pero recomendado para simular el rendimiento en el mundo real.
nota

Un dispositivo Coral solo puede ser utilizado por un único proceso a la vez, por lo que se recomienda un dispositivo Coral adicional si se usa uno para propósitos de desarrollo.

Configuración​

1. Abrir el repositorio con Visual Studio Code​

Al abrirlo, se te pedirá que abras el proyecto en un contenedor remoto. Esto construirá un contenedor sobre el contenedor base de SecureVu con todas las dependencias de desarrollo instaladas. Esto garantiza que todos usen un entorno de desarrollo consistente sin necesidad de instalar dependencias en tu máquina host.

2. Modificar tu archivo de configuración local para pruebas​

Coloca el archivo en config/config.yml en la raíz del repositorio.

Aquí hay un ejemplo, pero modifícalo según tus necesidades:

mqtt:
  host: mqtt

cameras:
  test:
    ffmpeg:
      inputs:
        - path: /media/securevu/car-stopping.mp4
          input_args: -re -stream_loop -1 -fflags +genpts
          roles:
            - detect

Estos argumentos de entrada le indican a FFmpeg que lea el archivo mp4 en un bucle infinito. Puedes usar cualquier entrada de FFmpeg válida aquí.

3. Recopilar algunos archivos mp4 para pruebas​

Crea y coloca estos archivos en una carpeta debug en la raíz del repositorio. Aquí también se crearán las grabaciones si las habilitas en tu configuración de prueba. Actualiza tu configuración del paso 2 anterior para apuntar al archivo correcto. Puedes verificar el archivo docker-compose.yml en el repositorio para ver cómo están mapeados los volúmenes.

4. Ejecutar SecureVu desde la línea de comandos​

VS Code iniciará el archivo Docker Compose por ti y abrirá una ventana de terminal conectada a securevu-dev.

  • Dependiendo del hardware en el que estés desarrollando, es posible que necesites modificar docker-compose.yml en la raíz del proyecto para pasar un Coral USB o GPU para aceleración de hardware.
  • Ejecuta python3 -m securevu para iniciar el backend.
  • En una ventana de terminal separada dentro de VS Code, cambia al directorio web y ejecuta npm install && npm run dev para iniciar el frontend.

5. Desmontaje​

Después de cerrar VS Code, es posible que todavía tengas contenedores en ejecución. Para cerrar todo, simplemente ejecuta docker-compose down -v para limpiar todos los contenedores.

Pruebas​

Pruebas Unitarias​

GitHub ejecutará pruebas unitarias en los nuevos PR. Debes asegurarte de que todas las pruebas pasen.

python3 -u -m unittest

Aceleración de Hardware con FFmpeg​

Los siguientes comandos se usan dentro del contenedor para garantizar que la aceleración de hardware funcione correctamente.

Raspberry Pi (64bit)

Esto debería mostrar menos del 50% de CPU en top, y ~80% de CPU sin -c:v h264_v4l2m2m.

ffmpeg -c:v h264_v4l2m2m -re -stream_loop -1 -i https://streams.videolan.org/ffmpeg/incoming/720p60.mp4 -f rawvideo -pix_fmt yuv420p pipe: > /dev/null

NVIDIA GPU

ffmpeg -c:v h264_cuvid -re -stream_loop -1 -i https://streams.videolan.org/ffmpeg/incoming/720p60.mp4 -f rawvideo -pix_fmt yuv420p pipe: > /dev/null

NVIDIA Jetson

ffmpeg -c:v h264_nvmpi -re -stream_loop -1 -i https://streams.videolan.org/ffmpeg/incoming/720p60.mp4 -f rawvideo -pix_fmt yuv420p pipe: > /dev/null

VAAPI

ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format yuv420p -re -stream_loop -1 -i https://streams.videolan.org/ffmpeg/incoming/720p60.mp4 -f rawvideo -pix_fmt yuv420p pipe: > /dev/null

QSV

ffmpeg -c:v h264_qsv -re -stream_loop -1 -i https://streams.videolan.org/ffmpeg/incoming/720p60.mp4 -f rawvideo -pix_fmt yuv420p pipe: > /dev/null

Enviar un pull request​

El código debe estar formateado, revisado con linter y verificado con tipos. GitHub ejecutará estas verificaciones en los pull requests, por lo que se recomienda ejecutarlas tú mismo antes de abrir uno.

Formateo

ruff format securevu migrations docker *.py

Linting

ruff check securevu migrations docker *.py

Tipado Estático con MyPy

python3 -u -m mypy --config-file securevu/mypy.ini securevu

Interfaz Web​

Prerrequisitos​

  • Todos los prerrequisitos de core o otra instancia de SecureVu disponible localmente
  • Node.js 20

Realizar cambios​

1. Configurar una instancia de SecureVu​

La interfaz web requiere una instancia de SecureVu con la que interactuar para obtener todos sus datos. Puedes ejecutar una instancia localmente (recomendado) o conectarte a una instancia separada accesible en tu red.

Para ejecutar la instancia local, sigue las instrucciones de desarrollo de core.

Si no vas a realizar cambios en la API HTTP de SecureVu, puedes conectar el servidor de desarrollo web a cualquier instancia de SecureVu en tu red. Omite este paso y ve a 3a.

2. Instalar dependencias​

cd web && npm install

3. Ejecutar el servidor de desarrollo​

cd web && npm run dev
3a. Ejecutar el servidor de desarrollo contra una instancia no local​

Para ejecutar el servidor de desarrollo contra una instancia no local, necesitarás reemplazar los valores de localhost en vite.config.ts con la dirección IP del servidor backend no local.

4. Realizar cambios​

La interfaz web está construida usando Vite, Preact y Tailwind CSS.

Pautas y consejos generales:

  • Evita agregar más dependencias. La interfaz web pretende ser liviana y de carga rápida.
  • No hagas cambios grandes y generalizados. Abre una discusión en GitHub para ideas grandes o arquitectónicas.
  • Asegúrate de que lint pase. Este comando garantizará la conformidad básica con los estilos, aplicando tantas correcciones automáticas como sea posible, incluyendo el formateo de Prettier.
npm run lint
  • Agrega pruebas unitarias y asegúrate de que pasen. En la medida de lo posible, debes esforzarte por aumentar la cobertura de pruebas al realizar cambios. Esto ayudará a garantizar que las características no se rompan accidentalmente en el futuro.
  • Si encuentras mensajes de error como "TypeError: Cannot read properties of undefined (reading 'context')" al ejecutar pruebas, esto puede deberse a estos problemas (https://github.com/vitest-dev/vitest/issues/1910, https://github.com/vitest-dev/vitest/issues/1652) en vitest, pero no he podido resolverlos.
npm run test
  • Prueba en diferentes navegadores. Firefox, Chrome y Safari tienen diferentes peculiaridades que los hacen objetivos únicos con los que interactuar.

Documentación​

Prerrequisitos​

  • Node.js 20

Realizar cambios​

1. Instalación​

cd docs && npm install

2. Desarrollo Local​

npm run start

Este comando inicia un servidor de desarrollo local y abre una ventana del navegador. La mayoría de los cambios se reflejan en vivo sin necesidad de reiniciar el servidor.

La documentación está construida usando Docusaurus v3. Consulta la documentación de Docusaurus para obtener más información sobre cómo modificar la documentación de SecureVu.

3. Compilar (opcional)​

npm run build

Este comando genera contenido estático en el directorio build y puede servirse usando cualquier servicio de alojamiento de contenido estático.

Compilaciones oficiales​

Configurar buildx para múltiples arquitecturas

docker buildx stop builder && docker buildx rm builder # <---- if existing
docker run --privileged --rm tonistiigi/binfmt --install all
docker buildx create --name builder --driver docker-container --driver-opt network=host --use
docker buildx inspect builder --bootstrap
make push

Otros​

Nginx​

Al probar cambios de configuración de nginx desde dentro del contenedor de desarrollo, se puede usar el siguiente comando para copiar y recargar la configuración para pruebas sin reconstruir el contenedor:

sudo cp docker/main/rootfs/usr/local/nginx/conf/* /usr/local/nginx/conf/ && sudo /usr/local/nginx/sbin/nginx -s reload

Contribuir traducciones de la interfaz web​

SecureVu gestiona las traducciones directamente en el repositorio de GitHub. Para contribuir una traducción, envía un pull request con cambios en los archivos de configuración regional relevantes bajo web/public/locales/.

Al traducir, mantén la estructura de claves existente y traduce solo los valores. Asegúrate de que tus traducciones mantengan el formato adecuado, incluyendo cualquier variable de marcador de posición (como {{example}}).