Edge Gateway

A cosa serve

• Gestire una flotta di edge gateway che Rela usa come ponti verso reti industriali isolate.
• Monitorare l'heartbeat di ogni gateway per rilevare un gateway caduto prima di perdere dati.
• Gestire registrazione, revoca e rotazione delle chiavi del gateway dalla dashboard.

Come funziona

Un edge gateway è un dispositivo che Rela registra con una chiave unica. Il gateway invia heartbeat ogni ~60 s con stato e metriche. Se l'heartbeat è perso per più di 5 minuti, il gateway viene marcato offline e Rela notifica l'amministratore. La revoca della chiave blocca il gateway istantaneamente.

Registrare un Gateway

Gli edge gateway collegano i dispositivi di campo con la piattaforma. Si registrano tramite POST /api/v1/integrations/gateways:

{
  "name": "Gateway Stabilimento Nord",
  "model": "RG-2000",
  "firmware_version": "3.1.0",
  "location": { "building": "A", "floor": 2, "zone": "production" },
  "protocols": ["modbus", "opcua", "mqtt"]
}

Al momento della registrazione, il gateway riceve un gateway_id e un token di autenticazione univoco per comunicare con l'API.

Gestione della Flotta

La vista della flotta mostra tutti i gateway del tenant con il loro stato:

Consulta la flotta tramite GET /api/v1/integrations/gateways?status=online&skip=0&limit=50.

Heartbeat

Ogni gateway invia un heartbeat periodico con metriche di sistema:

POST /api/v1/integrations/gateways/{gateway_id}/heartbeat
{
  "cpu_usage": 45.2,
  "memory_usage": 62.8,
  "disk_usage": 31.5,
  "uptime_seconds": 864000,
  "active_connections": 12,
  "firmware_version": "3.1.0"
}

L'heartbeat e atteso ogni 60 secondi. Se non ricevuto entro 5 minuti, il gateway passa allo stato degraded. Dopo 15 minuti, passa a offline.

Assegnazione delle Sorgenti Dati

I gateway vengono associati a sorgenti dati (sensori, PLC, contatori):

POST /api/v1/integrations/gateways/{gateway_id}/sources
{
  "source_id": "sensor_temp_001",
  "protocol": "modbus",
  "address": "40001",
  "poll_interval_seconds": 30,
  "data_type": "float32"
}

Un gateway puo avere fino a 500 sorgenti assegnate in base al piano.

Aggiornamento del Firmware

Gli aggiornamenti del firmware vengono distribuiti in modo controllato:

POST /api/v1/integrations/gateways/{gateway_id}/firmware
{
  "target_version": "3.2.0",
  "schedule": "2026-04-01T02:00:00Z",
  "rollback_on_failure": true
}

Il processo:

1. Viene validata la compatibilita della versione obiettivo
2. L'aggiornamento viene programmato nella finestra indicata
3. Il gateway scarica il firmware e lo verifica (checksum SHA-256)
4. L'aggiornamento viene applicato e il gateway si riavvia
5. Viene verificato l'heartbeat post-aggiornamento

Se l'heartbeat non arriva entro 10 minuti dall'aggiornamento e rollback_on_failure e attivo, si ripristina automaticamente la versione precedente.

Modalita Offline

I gateway archiviano i dati localmente quando perdono la connessione:

• Buffer locale — Fino a 72 ore di dati nell'archiviazione interna
• Sincronizzazione — Al ripristino della connessione, i dati vengono inviati in ordine cronologico
• Deduplicazione — Il server scarta i dati duplicati per timestamp + source_id
• Compressione — I dati nel buffer vengono compressi per massimizzare la capacita

Lo stato di sincronizzazione viene visualizzato nella dashboard della flotta.

Benefici chiave

• Flotta di gateway gestibile dalla dashboard — senza SSH a ognuno.
• Heartbeat automatico rileva gateway caduti in minuti.
• Revoca istantanea delle credenziali se un gateway è compromesso.
• Metriche per gateway (messaggi inviati, uptime, versione firmware).
• Stesso modello per 1 gateway o 1000 — scala orizzontalmente.