fosfeno/docs/instalacion.md

Instalación

La instalación es un único comando. Aun así, conviene saber qué hace por dentro, porque descarga y compila bastantes cosas y el proceso tarda.

Antes de empezar

Necesitas Raspberry Pi OS Bookworm de 64 bits con el escritorio instalado, no la versión Lite. FOSFENO muestra las visuales dentro de una ventana de Chromium a pantalla completa, así que hace falta entorno gráfico.

Conviene tener la Raspberry conectada a internet por cable durante la instalación. Se descargan paquetes del sistema, librerías y el código fuente de projectM.

El comando

git clone <URL-de-tu-gitlab>/fosfeno.git
cd fosfeno
bash install.sh

El instalador va informando de cada paso con una marca delante:

• [ OK ] el paso terminó bien.
• [ !! ] hubo un aviso. No es grave, pero conviene leerlo.
• [ XX ] hubo un fallo que detiene la instalación.

Al final resume cuántos avisos hubo. Si todo sale con [ OK ], la instalación está limpia.

Qué se instala automáticamente

El script trabaja en nueve fases. Esto es lo que hace cada una.

Comprobación del sistema. Detecta si la placa es una Pi 4 o una Pi 5, mira la versión del sistema operativo y la arquitectura. Si algo no encaja avisa, pero te deja seguir.

Paquetes del sistema. Instala con apt lo que hace falta para que todo lo demás funcione:

• Python 3 y su gestor de entornos virtuales.
• Chromium, el navegador donde se dibujan las visuales.
• Node.js y npm, para descargar las librerías de visuales.
• Git, CMake y las herramientas de compilación, necesarias para projectM.
• Las librerías de desarrollo de SDL2, OpenGL ES y POCO, que projectM usa al compilar.
• Las utilidades de PulseAudio, para detectar el micrófono.
• v4l-utils, para reconocer la cámara USB.
• xdotool y unclutter, para el control de projectM y para esconder el ratón.

Verificación de versiones. Comprueba que Python, Node, npm y CMake cumplen una versión mínima. Si alguna se queda corta lo dice claramente. Cuando es CMake quien no llega, salta la compilación de projectM en lugar de fallar entera.

Entorno de Python. Crea un entorno virtual aislado e instala Flask y Flask-SocketIO, que son el servidor web del proyecto. Después comprueba que esas librerías se importan de verdad.

Librerías de visuales. Con npm descarga Butterchurn y sus presets, Hydra, el cliente de Socket.IO y CodeMirror, que es el editor de código del panel. Copia los archivos que se usan a una carpeta web/lib y verifica uno por uno que cada copia existe y no está vacía.

projectM. Compila projectM desde su código fuente. Esto es lo que más tarda, entre diez y veinte minutos en una Raspberry. Si la compilación falla, el instalador lo avisa y sigue adelante: FOSFENO funciona igual con los otros cuatro motores. Puedes saltarte este paso desde el principio con bash install.sh --no-projectm.

Recursos. Descarga un paquete de presets para projectM y crea la carpeta data/videos, donde copiarás tus clips para el modo Mezclador.

Arranque automático. Configura la Raspberry para que, al encender el escritorio, lance FOSFENO sola. También da permiso para reiniciar y apagar la placa desde el panel sin pedir contraseña.

Puerto 80. Da permiso a Python para usar el puerto 80, que es lo que permite abrir el panel en http://la-ip-de-tu-pi/ sin escribir ningún número de puerto detrás.

Después de instalar

Falta un ajuste que el script no puede hacer por ti. Hay que decirle a la Raspberry que arranque sola en el escritorio:

sudo raspi-config

Dentro, ve a System Options, luego Boot / Auto Login, y elige Desktop Autologin. Sal y reinicia:

sudo reboot

Al volver, la Raspberry arranca directa en modo kiosko mostrando las visuales. El panel queda disponible en http://la-ip-de-tu-pi/.

Comprobar el sistema sin reinstalar

Si quieres revisar que todo sigue en su sitio, o diagnosticar un problema, hay un modo que solo comprueba y no toca nada:

bash install.sh --check

Lista las versiones de las herramientas y dice si projectM y Chromium están presentes.

Volver a ejecutar el instalador

El script se puede ejecutar las veces que quieras. No repite el trabajo ya hecho: no vuelve a compilar projectM si ya está, ni vuelve a descargar los presets si ya están. Es seguro relanzarlo si una instalación se cortó a medias.