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 versionatomachines.inventory.json). - FactoryOS chiama solo
NODE_RED_BASE_URLcon headerX-FactoryOS-Token. - Callback telemetria/eventi: header
X-FactoryOS-Gateway-Token(o API key Frappe) verso metodi whitelisted. ingest_machine_eventeingest_machine_telemetrysono gli unici endpointallow_guest=Truedell'app, limitati aPOST: Node-RED non ha una sessione Frappe. ConX-FactoryOS-Gateway-Tokenuguale anode_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 Commandcon statoPending Approvalprima del dispatch. La mappacommandsdell'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) diventaFailed. - Eventi macchina → FactoryOS: il polling Node-RED (
ot/poller.js, ogni 10 s) generaMachine Eventsui fronti dichiarati insignal.evente gli eventiconnection_lost/connection_restored, che portano la macchina inOffline/Online. OT_WRITES_ENABLED=0eOT_SIMULATION_MODE=1sono i default dei compose. Su staging e produzione il serviziomodbus-simulator(rete internafactoryos_ot) e le envOT_SIMULATION_MODE=0,OT_FORCE_REAL=1,OT_WRITES_ENABLED=1abilitano 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 retecoolify. - Codice Desk:
apps/ez_factoryos/ez_factoryos/integrations/node_red/.
