Integrazioni
Scopo
Documentare i canali esterni di Ez FactoryOS: gateway OT Node-RED e i campi di riferimento manuale verso Business Cube presenti su Factory Work Order.
Prerequisiti
- Token e URL solo in env / Coolify /
site_config— mai in git. - Rete Docker privata tra stack Frappe e Node-RED (
coolifysu server).
Business Cube — campi di riferimento manuale
Su Factory Work Order esistono tre campi compilabili/leggibili da Desk, senza alcuna chiamata automatica:
| Campo | Tipo | Uso operativo |
|---|---|---|
external_id | Data, unique, label "Business Cube ID" | Incollare a mano il riferimento ordine del gestionale Business Cube |
source | Select Business Cube / Manual (default Business Cube) | Indicare l'origine dell'ordine |
last_sync | Datetime, read-only | Timestamp informativo, oggi non aggiornato da automatismi |
Comportamento su staging: scripts/staging-safety.sh svuota business_cube_api_url in site config per evitare chiamate esterne accidentali.
Non esiste nel codice alcun client, scheduler o mapping verso Business Cube: il collegamento è esclusivamente manuale tramite questi campi.
Node-RED (gateway OT)
Unico canale OT verso FactoryOS. ADR: 0005. Deploy: deploy/node-red/README.md.
Configurazione
| Lato | Variabile / DocType |
|---|---|
| Frappe env | NODE_RED_BASE_URL, NODE_RED_API_TOKEN, NODE_RED_GATEWAY_TOKEN |
| Desk | Machine Connection Profile (enabled, base_url, timeout, TLS) |
| Node-RED | FACTORYOS_API_TOKEN, FRAPPE_GATEWAY_TOKEN, MQTT_*, OT_* |
Allineare token: NODE_RED_API_TOKEN ≡ FACTORYOS_API_TOKEN.
Endpoint gateway
Header Desk→gateway: X-FactoryOS-Token.
| Metodo | Path | Descrizione |
|---|---|---|
GET | /factoryos/health | Health / simulation / writes (rete privata) |
GET | /factoryos/machines | Inventario attivo |
POST | /factoryos/machines/{id}/read | Lettura adapter |
POST | /factoryos/machines/{id}/commands | Dispatch comando (allowlist) |
Callback gateway→Desk: X-FactoryOS-Gateway-Token (o API key Frappe) su ingest_machine_event / ingest_machine_telemetry.
Modulo Python: apps/ez_factoryos/ez_factoryos/integrations/node_red/.
Protocolli
| In Desk (Factory Machine) | Trasporto reale sul gateway |
|---|---|
| MQTT via Node-RED | MQTT, Modbus TCP, OPC UA (adapter in inventario) |
Default dei compose: OT_SIMULATION_MODE=1, OT_WRITES_ENABLED=0 (letture simulate, comandi rifiutati con ot_writes_disabled). Staging e produzione usano il simulatore Modbus interno con OT_SIMULATION_MODE=0, OT_FORCE_REAL=1, OT_WRITES_ENABLED=1. Vedi Macchine.
Sequenza dati macchina
sequenceDiagram
participant Machine
participant Adapter as OT_Adapter
participant NodeRED as Node_RED
participant MQTT as Mosquitto
participant Frappe as Ez_FactoryOS
participant Log as Machine_Data_Log
Machine->>Adapter: Modbus_or_OPCUA_or_MQTT
Adapter->>NodeRED: Normalized_values
NodeRED->>MQTT: Telemetry_optional
Frappe->>NodeRED: GET_machines_POST_read_commands
NodeRED-->>Frappe: Inventory_values_ack
NodeRED->>Frappe: ingest_telemetry_event
Frappe->>Log: Persist_auditURL per ambiente
I worker Frappe (che eseguono dispatch_machine_command) sono solo sulla rete interna del proprio stack, non sulla rete coolify: FactoryOS e Node-RED si chiamano tramite gli URL HTTPS gestiti da Coolify/Traefik.
| Ambiente | node_red_base_url (FactoryOS) | FRAPPE_BASE_URL (Node-RED) |
|---|---|---|
| development | https://nodered-dev.152.53.248.57.sslip.io | — |
| staging | https://nodered-staging.152.53.248.57.sslip.io | https://staging-factoryos.ezbit.it |
| production | https://nodered.152.53.248.57.sslip.io | URL pubblico del sito production |
Gli endpoint /factoryos/* diversi da health richiedono X-FactoryOS-Token. Nessuna porta 1880/1883/502/4840 pubblicata dai container.
Verifica
curl -sS https://nodered-staging.152.53.248.57.sslip.io/factoryos/health
curl -sS -H "X-FactoryOS-Token: $TOKEN" https://nodered-staging.152.53.248.57.sslip.io/factoryos/machinesIn Desk: Machine Connection Profile → Connected; Factory Machine → Carica macchine Node-RED.
Rollback / Troubleshooting
| Sintomo | Azione |
|---|---|
| Timeout / Error sul profilo | Verificare URL HTTPS Node-RED, token simmetrici, servizio Node-RED up |
Comando Failed con ot_writes_disabled | Atteso se OT_WRITES_ENABLED=0 |
| Letture simulate | Atteso se OT_SIMULATION_MODE=1 |
| Isolare Frappe da OT | Profile enabled=0 |
Dettaglio modulo: Macchine.
