Runbook — Configurar una pantalla HMI

Configuración de una pantalla HMI de T-Monitor, desde el configurador hasta la imagen del sistema operativo que se instala en la Raspberry Pi.

Ficha


Tipo	Operativo (rutinario, no es un incidente)
Cuándo usarlo	Al configurar una pantalla HMI nueva
Hardware destino	Raspberry Pi 5, únicamente
Tiempo estimado	1 hora
Owner	Cristhian Lizcano — célula 3
Última ejecución	AAAA-MM-DD

Un error de configuración cuesta todo el proceso

Si la configuración de la HMI queda mal, hay que repetir la compilación completa: regenerar la base de datos, recompilar frontend y backend, reconstruir la imagen y volver a grabarla.

Por eso el paso 1 es el más crítico del runbook. Revisar la configuración con calma antes de generar los archivos ahorra horas.

Los tres repositorios

T-Monitor no vive en un solo repositorio: hacen falta tres, y cada uno cubre una capa distinta.

Repositorio	Qué contiene
t-monitor	Frontend y configurador de HMI (`hmi-configurator`)
modbus-manager	Backend, en Go
custom-rpi-images	Construcción de la imagen del sistema operativo para la Raspberry Pi

En los tres repositorios se trabaja desde la rama production

No desde main ni desde develop. Antes de empezar, verificar la rama en los tres clones:

git switch production && git pull

Trabajar desde otra rama produce archivos de configuración o binarios que no corresponden a la versión vigente. Ver Git workflow.

Flujo completo

1. Configurar la HMI en el configurador

Abrir la subaplicación hmi-configurator dentro del repositorio t-monitor. Contiene 7 módulos con toda la funcionalidad necesaria para armar la pantalla.

Módulo	Qué se hace
Equipos de comunicación	Crear los equipos que tendrá asociada esta pantalla
Diagrama unifilar	Diseñar el unifilar y asociar los equipos a sus nodos
Control	Configurar el control de la pantalla, asociándolo a los equipos creados
Estructura metalmecánica	Ordenamiento, nombres y asociación de los puntos del unifilar correspondientes
Alarmas	Setear alarmas a los dispositivos ya creados en el configurador
Usuarios	Modificar los tres usuarios principales de la HMI
Vista previa	Genera los dos archivos de salida

El orden importa

Los equipos de comunicación se crean primero: el unifilar, el control y las alarmas se asocian a equipos que ya deben existir.

Revisar antes de continuar

Este es el punto de no retorno práctico. Un equipo mal asociado, un nodo mal conectado o una alarma mal seteada no se descubre hasta que la pantalla ya está grabada en la Raspberry — y entonces toca repetir todo el proceso.

Archivos que genera

Desde el módulo de vista previa se obtienen dos archivos:

Archivo	Se usa en
`init-config.json`	Frontend
`seed.json`	Backend

2. Colocar los archivos generados

Cada archivo va en una ubicación distinta. Equivocarlas es la forma más rápida de que nada funcione.

Archivo	Destino
`init-config.json`	`t-monitor/frontend/public/`
`seed.json`	Raíz del repositorio `modbus-manager`

3. Generar la base de datos

En el repositorio modbus-manager. La base de datos es SQLite y se guarda en la carpeta data/ del repositorio:

modbus-manager/data/modbus.db

Borrar la base de datos anterior primero

Si existe una base de datos de una configuración previa, hay que eliminarla antes de ejecutar el seed. Si no, la pantalla arranca con datos de la configuración anterior mezclados.

SQLite trabaja en modo WAL, así que hay tres archivos, no uno. Borrar los tres:

rm -f data/modbus.db data/modbus.db-shm data/modbus.db-wal

# Desde la raíz de modbus-manager
go run cmd/seed/main.go

Este es el seed natural del proyecto y crea la base de datos.

4. Compilar frontend y backend

Frontend

# Desde t-monitor/frontend
npm run build

Salida: la carpeta dist/.

Backend — compilación cruzada para Raspberry Pi 5

El backend se compila desde el PC de trabajo para la arquitectura de la Raspberry Pi. No se compila en la Raspberry.

# Desde la raíz de modbus-manager
GOOS=linux GOARCH=arm64 go build -o modbus-manager-arm64 main.go

Salida: el binario modbus-manager-arm64.

Solo Raspberry Pi 5

GOARCH=arm64 corresponde al procesador de la Raspberry Pi 5. Esta guía cubre únicamente ese hardware.

5. Colocar los artefactos en `custom-rpi-images`

Los scripts de construcción buscan los archivos por nombre exacto. Si un nombre no coincide, la imagen se construye igual pero la pantalla no funciona.

Qué	Destino exacto	Se instala en la imagen como
Carpeta `dist/` del frontend	`assets/frontend-dist/`	`/var/www/hmi-app/`
Binario del backend	`assets/mi-backend-arm64`	`/usr/local/bin/hmi-backend`
Base de datos	`assets/data/modbus.db`	`/var/lib/hmi-app/data/modbus.db`

El binario hay que renombrarlo

El paso 4 produce modbus-manager-arm64, pero los scripts de construcción esperan mi-backend-arm64. Hay que renombrarlo al copiarlo:

cp modbus-manager-arm64 ~/Documentos/custom-rpi-images/assets/mi-backend-arm64

Si se copia con el nombre original, rpi-image-gen falla al no encontrar el archivo, o instala una versión anterior que sí estaba ahí.

Copiar la base de datos con el WAL vacío

El script de construcción copia únicamente modbus.db: no lleva los archivos -shm ni -wal. Si quedan escrituras pendientes en el WAL, esos datos no llegan a la imagen.

Verificar que data/modbus.db-wal esté en 0 bytes antes de copiar.

# Desde la raíz de custom-rpi-images
cp -r <ruta>/t-monitor/frontend/dist/*   assets/frontend-dist/
cp <ruta>/modbus-manager/modbus-manager-arm64  assets/mi-backend-arm64
cp <ruta>/modbus-manager/data/modbus.db  assets/data/modbus.db

6. Construir la imagen del sistema operativo

La imagen se construye con rpi-image-gen, la herramienta oficial de Raspberry Pi.

Requisitos del PC donde se compila

Requisito	Valor
Sistema operativo	Debian o Ubuntu (o una distribución derivada, con `apt`)
Arquitectura	x86_64 / amd64 — un PC de escritorio o portátil normal
Espacio libre	15 GB
Red	Conexión a internet

Por qué x86_64 y por qué hace falta emulación

La imagen que se produce es para arm64 (el procesador de la Raspberry Pi), pero se construye en un PC x86_64. Son dos arquitecturas distintas, así que durante la compilación hay que ejecutar binarios arm64 sobre el PC: eso es lo que resuelven qemu-user-static y binfmt-support.

Los nombres x86_64 y amd64 son lo mismo; arm64 y aarch64 también.

Instalación de herramientas

# 1. rpi-image-gen y sus dependencias
git clone https://github.com/raspberrypi/rpi-image-gen.git ~/Documentos/rpi-image-gen
sudo ~/Documentos/rpi-image-gen/install_deps.sh

# 2. Emulación arm64
sudo apt install qemu-user-static binfmt-support

# 3. Node.js 20 o superior, para compilar los frontends
sudo apt install nodejs npm

Clonar el proyecto

git clone git@github.com:Industrias-CTS/custom-rpi-images.git ~/Documentos/custom-rpi-images

Construir

cd ~/Documentos/rpi-image-gen
./rpi-image-gen build -S ~/Documentos/custom-rpi-images -c hmi-kiosk.yaml

7. Grabar la imagen en la Raspberry Pi

La imagen se instala en la Raspberry Pi 5 con Raspberry Pi Imager, seleccionando la opción de imagen personalizada y apuntando al archivo generado en el paso anterior.

8. Verificación

Se prueba con el hardware real:

Conectar el periférico de pantalla a la Raspberry Pi.
Encender y comprobar que la HMI arranca.
Probar la pantalla: navegación, control y lectura de los equipos.

Pendiente

Detallar qué se revisa exactamente en la prueba: qué vistas, qué controles y cómo se confirma que la comunicación Modbus con los equipos responde.

9. Qué sale mal normalmente

Síntoma	Causa	Costo
La HMI arranca pero la configuración está mal (equipos, unifilar, alarmas)	Error en el paso 1	Repetir todo el proceso: seed, compilación, imagen y grabado
La imagen no toma el backend actualizado	El binario no se renombró a `mi-backend-arm64` (paso 5)	Recompilar la imagen
La pantalla arranca con datos viejos	No se borró la base de datos anterior antes del seed (paso 3)	Repetir desde el paso 3

La lección del runbook

Todos los fallos frecuentes se originan antes de compilar, y solo se descubren después de grabar. No hay atajo: la única defensa es revisar con cuidado los pasos 1, 3 y 5 antes de avanzar.

10. Cierre

Informar al equipo de proyectos (dentro del área TAD) que la pantalla quedó configurada.
Registrar la ejecución en la tabla de abajo.

Registro de ejecuciones

Fecha	Cliente / pantalla	Quién lo ejecutó	Resultado

Preguntas abiertas

Detalle de la prueba de verificación: qué vistas y controles se revisan (paso 8).
Complementar con la documentación existente en el repositorio t-monitor (README.md, docs/QUICK_REFERENCE.md, hmi-configurator/README.md).

Los tres repositorios​

Flujo completo​

1. Configurar la HMI en el configurador​

Archivos que genera​

2. Colocar los archivos generados​

3. Generar la base de datos​

4. Compilar frontend y backend​

Frontend​

Backend — compilación cruzada para Raspberry Pi 5​

5. Colocar los artefactos en custom-rpi-images​

6. Construir la imagen del sistema operativo​

Requisitos del PC donde se compila​

Instalación de herramientas​

Clonar el proyecto​

Construir​

7. Grabar la imagen en la Raspberry Pi​

8. Verificación​

9. Qué sale mal normalmente​

10. Cierre​

Registro de ejecuciones​

Preguntas abiertas​