Skip to content

ADR-0005: Node-RED come unico gateway OT (MQTT / Modbus / OPC UA) ​

Status ​

Accepted (aggiornato 2026-09)

Context ​

Ez FactoryOS deve collegare macchinari industriali senza esporre protocolli OT (Modbus, OPC UA, MQTT) direttamente nel container Frappe. Servono discovery macchine, letture on-demand, telemetria periodica e comandi con audit/approvazione. La rete di stabilimento non è ancora raggiungibile dalla VPS: il primo rilascio usa modalità simulazione.

Decision ​

  • Unico protocollo configurabile su Factory Machine: MQTT via Node-RED (il trasporto Desk resta disaccoppiato dagli adapter OT).
  • Node-RED + Mosquitto sono servizi Docker Compose custom su Coolify (ambienti development / staging / production), rete privata, senza porte pubbliche.
  • Adapter OT nel gateway: modbus_tcp, opcua, mqtt (inventario versionato machines.inventory.json).
  • FactoryOS chiama solo NODE_RED_BASE_URL con header X-FactoryOS-Token.
  • Callback telemetria/eventi: header X-FactoryOS-Gateway-Token (o API key Frappe) verso metodi whitelisted.
  • ingest_machine_event e ingest_machine_telemetry sono gli unici endpoint allow_guest=True dell'app, limitati a POST: Node-RED non ha una sessione Frappe. Con X-FactoryOS-Gateway-Token uguale a node_red_gateway_token (confronto a tempo costante) la richiesta passa; senza token valido si applica il controllo ruoli, che respinge Guest.
  • I comandi macchina passano da Machine Command con stato Pending Approval prima del dispatch. La mappa commands dell'inventario lega ogni comando a un solo segnale scrivibile; la risposta Modbus include la rilettura del segnale (readback). Un comando rifiutato dal gateway (accepted: false) diventa Failed.
  • Eventi macchina → FactoryOS: il polling Node-RED (ot/poller.js, ogni 10 s) genera Machine Event sui fronti dichiarati in signal.event e gli eventi connection_lost / connection_restored, che portano la macchina in Offline / Online.
  • OT_WRITES_ENABLED=0 e OT_SIMULATION_MODE=1 sono i default dei compose. Su staging e produzione il servizio modbus-simulator (rete interna factoryos_ot) e le env OT_SIMULATION_MODE=0, OT_FORCE_REAL=1, OT_WRITES_ENABLED=1 abilitano letture e scritture verso il solo simulatore.

Consequences ​

  • Nessun client Modbus/OPC UA nell’app Frappe.
  • Inventario macchine versionato sul gateway.
  • Segreti solo in env Coolify (FACTORYOS_API_TOKEN / NODE_RED_API_TOKEN).
  • Coolify continua a gestire proxy/HTTPS pubblici; Node-RED non richiede Traefik dedicato.
  • Hostname univoci per ambiente (node-red-development|staging|production) evitano collisioni sulla rete coolify.
  • Codice Desk: apps/ez_factoryos/ez_factoryos/integrations/node_red/.

References ​

Ez FactoryOS — MES per Ortobellina / OP Raggio di Sole · App Frappe v16 ez_factoryos