Skip to content

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 (coolify su server).

Business Cube — campi di riferimento manuale ​

Su Factory Work Order esistono tre campi compilabili/leggibili da Desk, senza alcuna chiamata automatica:

CampoTipoUso operativo
external_idData, unique, label "Business Cube ID"Incollare a mano il riferimento ordine del gestionale Business Cube
sourceSelect Business Cube / Manual (default Business Cube)Indicare l'origine dell'ordine
last_syncDatetime, read-onlyTimestamp 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 ​

LatoVariabile / DocType
Frappe envNODE_RED_BASE_URL, NODE_RED_API_TOKEN, NODE_RED_GATEWAY_TOKEN
DeskMachine Connection Profile (enabled, base_url, timeout, TLS)
Node-REDFACTORYOS_API_TOKEN, FRAPPE_GATEWAY_TOKEN, MQTT_*, OT_*

Allineare token: NODE_RED_API_TOKEN ≡ FACTORYOS_API_TOKEN.

Endpoint gateway ​

Header Desk→gateway: X-FactoryOS-Token.

MetodoPathDescrizione
GET/factoryos/healthHealth / simulation / writes (rete privata)
GET/factoryos/machinesInventario attivo
POST/factoryos/machines/{id}/readLettura adapter
POST/factoryos/machines/{id}/commandsDispatch 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-REDMQTT, 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 ​

mermaid
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_audit

URL 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.

Ambientenode_red_base_url (FactoryOS)FRAPPE_BASE_URL (Node-RED)
developmenthttps://nodered-dev.152.53.248.57.sslip.io—
staginghttps://nodered-staging.152.53.248.57.sslip.iohttps://staging-factoryos.ezbit.it
productionhttps://nodered.152.53.248.57.sslip.ioURL pubblico del sito production

Gli endpoint /factoryos/* diversi da health richiedono X-FactoryOS-Token. Nessuna porta 1880/1883/502/4840 pubblicata dai container.

Verifica ​

bash
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/machines

In Desk: Machine Connection Profile → Connected; Factory Machine → Carica macchine Node-RED.

Rollback / Troubleshooting ​

SintomoAzione
Timeout / Error sul profiloVerificare URL HTTPS Node-RED, token simmetrici, servizio Node-RED up
Comando Failed con ot_writes_disabledAtteso se OT_WRITES_ENABLED=0
Letture simulateAtteso se OT_SIMULATION_MODE=1
Isolare Frappe da OTProfile enabled=0

Dettaglio modulo: Macchine.

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