Skip to content

Modulo Macchine 4.0 ​

Scopo ​

Anagrafica macchine, profilo gateway Node-RED, letture, telemetria/eventi e comandi con approvazione e audit.

Prerequisiti ​

  • Stack Node-RED raggiungibile (NODE_RED_BASE_URL).
  • Token allineati: NODE_RED_API_TOKEN = FACTORYOS_API_TOKEN.
  • Ruoli: Factory Admin / Production Manager (comandi); Line Operator (letture).
  • Concetti Frappe: DocType, permessi, metodi whitelist. Vedi Fondamenti Frappe.
  • ADR: 0005 Node-RED MQTT.

DocType ​

DocTypeSerieRuolo
Factory MachineFMC-.YYYY.-Master macchina + id gateway + pannello controllo
Machine Signal Snapshot(child table)Ultimi valori segnale su Factory Machine
Machine Connection ProfileSingleEnable, URL, timeout, TLS, stato
Machine CommandMCMD-.YYYY.-Comando con workflow approvazione
Machine EventMEV-.YYYY.-Evento ingresso (idempotente)
Machine Data LogMDL-.YYYY.-Audit Read / Command / Event

Factory Machine — campi chiave ​

CampoNote
machine_name, line, machine_typeWasher, Weigher, Bagging, Metal Detector, Printer, Other
protocolSolo MQTT via Node-RED (forzato in validate)
node_red_machine_idUnico, obbligatorio (id inventario gateway)
mqtt_topicTopic opzionale
statusOnline / Offline / Unknown
last_contact, last_syncRead-only
signal_snapshotsChild table Machine Signal Snapshot (signal_key, value, quality, updated_at)
Sezione Pannello controlloHTML live: stato, valori, allarmi Warning/Error, aggiorna/comando
Bottone fetch_from_node_redSync da inventario

Machine Command — stati ​

mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> PendingApproval: submit_for_approval
  PendingApproval --> Approved: approve
  PendingApproval --> Rejected: reject
  Approved --> Queued: enqueue
  Queued --> Sent: dispatch
  Sent --> Succeeded
  Sent --> Failed
  Draft --> Cancelled

Campi: command_type, payload_json, correlation_id, audit approval/execution.

Sent → Failed anche quando Node-RED risponde ma non accetta il comando (accepted: false, es. ot_writes_disabled, value_above_max): result_summary riporta il motivo. Con scrittura Modbus riuscita result_summary mostra il valore riletto dalla macchina.

Machine Event / Data Log ​

  • Event: event_type, severity (Info/Warning/Error), external_event_id (unique), payload_json, occurred_at.
  • event_type = connection_lost porta la macchina in Offline; ogni altro evento o telemetria la riporta Online.
  • Data Log: direction = Read | Command | Event; request/response summary + JSON.

La form Factory Machine mostra nella sezione collegamenti (gruppo Node-RED) i Machine Command, Machine Event e Machine Data Log della macchina.

Simulazione Modbus — pesatrice weigher-01 ​

Servizio modbus-simulator nello stack Node-RED (rete interna factoryos_ot, porta 5020 non pubblicata), codice deploy/node-red/simulators/modbus/server.js. Ogni secondo il peso sale di 0,8 kg fino al target; a target raggiunto il lotto è pronto e la pesatrice resta ferma finché FactoryOS non conferma.

SegnaleModbusScalaScrivibile
weight_kgholding 00,01no
target_weight_kgholding 10,01 (0,5 – 50 kg)sì
batch_countholding 21no
session_idholding 3casuale a ogni avvio del simulatoreno
heartbeatcoil 0—no
tare_requestcoil 1—sì
batch_readycoil 2—sì
Comando (Desk → macchina)Segnale scrittoValore
set_target_weighttarget_weight_kgrichiesto (kg)
taretare_requesttrue fisso: il simulatore azzera il peso
ack_batchbatch_readyfalse fisso: il simulatore svuota e riparte
Evento (macchina → Desk)OrigineSeverità
batch_completedfronte di salita di batch_ready o nuovo batch_count con batch_ready alto, id weigher-01:batch_completed:<session_id>-<batch_count>Info
connection_lost / connection_restoredlettura Modbus fallita / tornataError / Info
mermaid
sequenceDiagram
  participant Sim as modbus_simulator
  participant NR as Node_RED
  participant FOS as Ez_FactoryOS
  loop ogni 10 s
    NR->>Sim: lettura registri e coil
    NR->>FOS: ingest_machine_telemetry se cambiano i valori o ogni 60 s
  end
  Sim-->>NR: batch_ready = true
  NR->>FOS: ingest_machine_event batch_completed
  FOS->>NR: Machine Command ack_batch approvato
  NR->>Sim: scrive coil batch_ready = false e rilegge
  NR-->>FOS: accepted, readback false

Procedura — collegare il gateway ​

  1. Impostare env Frappe: NODE_RED_BASE_URL, NODE_RED_API_TOKEN, opzionale NODE_RED_GATEWAY_TOKEN.
  2. Su Node-RED: stesso token in FACTORYOS_API_TOKEN / FRAPPE_GATEWAY_TOKEN.
  3. Desk → Machine Connection Profile → enabled=1, base_url = URL interno gateway, salva.
  4. Nuovo Factory Machine → Carica macchine Node-RED (o API list_node_red_machines / sync_machine_from_node_red).
  5. Lettura: bottone Desk o read_machine_data → scrive Machine Data Log.
  6. Comando: form Factory Machine → Node-RED → Invia comando (comandi ammessi dall'inventario, con limiti) → Machine Command in Pending Approval → Approva → enqueue dispatch_machine_command.
  7. Con OT_WRITES_ENABLED=0 il gateway non scrive e il comando finisce Failed con motivo ot_writes_disabled.

Uso quotidiano da Desk ​

AttivitàPercorso Desk
Verificare connessioneAwesome Bar → Machine Connection Profile → stato Connected/Error
Sincronizzare anagraficaAprire Factory Machine → Carica macchine Node-RED → selezionare id inventario
Pannello liveForm Factory Machine → sezione Pannello controllo (polling ~12s; Aggiorna da Node-RED forza read)
Leggere valoriPannello / bottone Leggi dati da Node-RED → snapshot + Machine Data Log
Inviare comandoPannello Invia comando o Node-RED → Invia comando → Approva sul Machine Command (Factory Admin / Production Manager)
Consultare eventiForm Factory Machine → collegamenti Machine Event, oppure List Machine Event → filtri machine, severity, occurred_at
Audit completoList Machine Data Log → filtri direction, machine, logged_at

Machine Command / Event / Data Log non sono shortcut nel workspace: si aprono dai collegamenti della form Factory Machine o da Awesome Bar. Machine Connection Profile si apre da Awesome Bar.

API whitelist (path Python) ​

ez_factoryos.integrations.node_red.api:

MetodoUsoRuoli
list_node_red_machinesInventarioFactory Admin, Production Manager, System Manager
sync_machine_from_node_redUpsert Factory MachineFactory Admin, Production Manager, System Manager
read_machine_dataLettura + log + aggiorna snapshot+ Line Operator
get_machine_panelAggregato stato/snapshot/allarmi/comandi; refresh=1 → read live+ Line Operator
get_machine_commandsComandi ammessi dall'inventario (segnale, valore richiesto, limiti)+ Line Operator
request_machine_commandCrea comando Pending Approval+ Line Operator
approve_machine_command / reject_machine_commandApprovalFactory Admin, Production Manager, System Manager
ingest_machine_event / ingest_machine_telemetryCallback gateway, solo POST; telemetria aggiorna anche signal_snapshotsGateway / Factory Admin, Production Manager

Document class methods su Machine Command: submit_for_approval, approve, reject.

Chiamata RPC via HTTP (esempio lettura):

bash
curl -sS -X POST https://factoryos.ezbit.it/api/method/ez_factoryos.integrations.node_red.api.read_machine_data \
  -H "Authorization: token <api_key>:<api_secret>" \
  -H "Content-Type: application/json" \
  -d '{"machine":"FMC-2026-00001","keys":["weight","speed"]}'

Sicurezza ​

  • Unici endpoint guest: ingest_machine_event / ingest_machine_telemetry, solo POST; senza X-FactoryOS-Gateway-Token valido respingono Guest (ADR-0005).
  • Token solo server-side (frappe.conf).
  • Allowlist comandi/segnali in deploy/node-red → machines.inventory.json; con la mappa commands un comando scrive solo il suo segnale.
  • Staging e produzione: scritture abilitate verso il solo modbus-simulator interno.

Modalità operative del gateway ​

Il comportamento dipende dalle env Node-RED, verificabili su GET /factoryos/health:

EnvDefault composeStaging / produzioneEffetto
OT_SIMULATION_MODE101: letture dai valori simulate dell'inventario
OT_FORCE_REAL011: usa gli adapter reali anche con simulazione attiva
OT_WRITES_ENABLED010: comandi rifiutati con ot_writes_disabled
MODBUS_WEIGHER_ENDPOINTmodbus://modbus-simulator:5020invariatoEndpoint Modbus di weigher-01

Verifica ​

bash
curl -sS -H "X-FactoryOS-Token: $TOKEN" "$NODE_RED_BASE_URL/factoryos/health"
curl -sS -H "X-FactoryOS-Token: $TOKEN" "$NODE_RED_BASE_URL/factoryos/machines"
# Locale gateway:
cd deploy/node-red && bash scripts/smoke-test.sh

Desk: profilo Connected; lettura macchina con log MDL; comando Approved→Succeeded/Failed.

Test simulazione Modbus su staging/produzione:

  1. Factory Machine weigher-01 → Leggi dati da Node-RED: mode: live, heartbeat: true.
  2. Entro 10 s compaiono Machine Data Log telemetry keys=... (direction Read).
  3. Al primo lotto completo compare un Machine Event batch_completed.
  4. Invia comando ack_batch → Approva → Machine Command Succeeded con batch_ready = False (riletto dalla macchina).
  5. Invia comando set_target_weight = 10 → Succeeded con target_weight_kg = 10; i lotti successivi si chiudono a 10 kg.

Rollback / Troubleshooting ​

CasoAzione
Isolare OTProfile enabled=0
Bloccare scrittureOT_WRITES_ENABLED=0 su Node-RED
Tornare alla simulazione softwareOT_SIMULATION_MODE=1, OT_FORCE_REAL=0 su Node-RED e riavvio
Macchina OfflineMachine Event connection_lost → controllare modbus-simulator nello stack Node-RED
Redeploy gatewayTag precedente Coolify; vedi deploy/node-red/README.md
Macchine legacy senza idPatch migrate_machine_mqtt_node_red assegna legacy-{name}

Riferimenti ​

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