Configurar dispositivo

Guía completa para instalar el agente rud1-fw en una Raspberry Pi y registrarla en la plataforma rud1-es.

Requisitos

• ✓Raspberry Pi 3B+, 4 o 5 (también funciona en otras distros Linux ARM64/AMD64)
• ✓Raspberry Pi OS Lite 64-bit (recomendado) o Ubuntu Server 22.04
• ✓Tarjeta SD de 8 GB o superior
• ✓Conexión a internet durante la configuración
• ✓Acceso por SSH o teclado + pantalla
• ✓Una cuenta activa en rud1.es con una clave API creada

Instalación del agente rud1-fw

Método 1: Instalación automática (recomendado)

La forma más sencilla de instalar el agente es mediante el script de instalación oficial. Conéctate a tu Raspberry Pi por SSH y ejecuta:

# Descarga e instala el agente con un solo comando
curl -fsSL https://get.rud1.es/install.sh | sudo bash

El script de instalación realiza automáticamente los siguientes pasos:

• Detecta la arquitectura del sistema (ARM64, ARM32, AMD64)
• Descarga el binario apropiado desde GitHub Releases
• Crea los directorios necesarios (/etc/rud1-agent, /var/lib/rud1-agent, etc.)
• Instala y habilita el servicio systemd
• Genera un archivo de configuración de ejemplo en /etc/rud1-agent/config.yaml

Método 2: Instalación manual

Si prefieres instalar el agente manualmente o no tienes acceso a internet en el dispositivo:

# 1. Descarga el binario para ARM64
wget https://github.com/rud1-es/rud1-fw/releases/latest/download/rud1-agent-linux-arm64 -O /tmp/rud1-agent
chmod +x /tmp/rud1-agent
sudo mv /tmp/rud1-agent /usr/local/bin/rud1-agent

# 2. Crea los directorios necesarios
sudo mkdir -p /etc/rud1-agent /var/lib/rud1-agent /var/log/rud1-agent
sudo chmod 700 /var/lib/rud1-agent

# 3. Copia el archivo de configuración
sudo cp config.example.yaml /etc/rud1-agent/config.yaml

# 4. Instala el servicio systemd
sudo cp rud1-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable rud1-agent

Compilar desde fuente (desarrollo)

Si quieres compilar el agente desde el código fuente (por ejemplo, para desarrollo o modificaciones propias):

git clone https://github.com/rud1-es/rud1-fw
cd rud1-fw
make build-pi   # Cross-compila para Raspberry Pi (ARM64)
# O en la propia RPi:
make build

Configuración básica

Edita el archivo de configuración principal en /etc/rud1-agent/config.yaml. El mínimo necesario para conectarse a la nube es:

cloud:
  enabled: true
  base_url: https://rud1.es
  api_secret: "TU_DEVICE_API_SECRET"

El valor de api_secret es tu clave API de rud1-es. Puedes crear una en rud1.es → Configuración → Claves API.

Para una referencia completa de todas las opciones de configuración, consulta la referencia de configuración.

Iniciar el agente

sudo systemctl start rud1-agent
sudo systemctl status rud1-agent

# Ver logs en tiempo real
journalctl -u rud1-agent -f

Si el servicio arranca correctamente, verás en los logs mensajes como agent started y el código de registro generado.

Encontrar el código de registro

La primera vez que el agente arranca, genera un código de registro único que necesitarás para vincular el dispositivo con tu cuenta de rud1-es:

journalctl -u rud1-agent | grep registration_code
# Salida: registration_code="RUD1-ABCD-1234"

Registrar el dispositivo en rud1-es

Con el agente en marcha y el código de registro a mano, sigue estos pasos desde el dashboard de rud1-es:

Verificar la conexión

Una vez registrado, puedes verificar que todo funciona correctamente:

• El dispositivo muestra estado ONLINE en el dashboard de rud1-es
• En la pestaña Live del dispositivo verás CPU, memoria y temperatura actualizándose cada 60 segundos (intervalo de heartbeat por defecto)
• Los logs del agente muestran heartbeat sent periódicamente

Solución de problemas iniciales

El dispositivo muestra estado PROVISIONING

El agente está en marcha pero el código de registro aún no se ha introducido en rud1-es. Sigue los pasos de la sección Registrar el dispositivo para completar el proceso.

El dispositivo muestra estado OFFLINE

Causas habituales: el valor de cloud.api_secret es incorrecto o la Raspberry Pi no tiene conexión a internet. Verifica ambas cosas y reinicia el agente.

Revisar los logs del agente

# Últimos 10 minutos
journalctl -u rud1-agent --since "10 minutes ago"

# Seguir logs en tiempo real
journalctl -u rud1-agent -f