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
| DocType | Serie | Ruolo |
|---|---|---|
| Factory Machine | FMC-.YYYY.- | Master macchina + id gateway + pannello controllo |
| Machine Signal Snapshot | (child table) | Ultimi valori segnale su Factory Machine |
| Machine Connection Profile | Single | Enable, URL, timeout, TLS, stato |
| Machine Command | MCMD-.YYYY.- | Comando con workflow approvazione |
| Machine Event | MEV-.YYYY.- | Evento ingresso (idempotente) |
| Machine Data Log | MDL-.YYYY.- | Audit Read / Command / Event |
Factory Machine — campi chiave
| Campo | Note |
|---|---|
machine_name, line, machine_type | Washer, Weigher, Bagging, Metal Detector, Printer, Other |
protocol | Solo MQTT via Node-RED (forzato in validate) |
node_red_machine_id | Unico, obbligatorio (id inventario gateway) |
mqtt_topic | Topic opzionale |
status | Online / Offline / Unknown |
last_contact, last_sync | Read-only |
signal_snapshots | Child table Machine Signal Snapshot (signal_key, value, quality, updated_at) |
| Sezione Pannello controllo | HTML live: stato, valori, allarmi Warning/Error, aggiorna/comando |
Bottone fetch_from_node_red | Sync da inventario |
Machine Command — stati
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 --> CancelledCampi: 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_lostporta la macchina inOffline; ogni altro evento o telemetria la riportaOnline.- 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.
| Segnale | Modbus | Scala | Scrivibile |
|---|---|---|---|
weight_kg | holding 0 | 0,01 | no |
target_weight_kg | holding 1 | 0,01 (0,5 – 50 kg) | sì |
batch_count | holding 2 | 1 | no |
session_id | holding 3 | casuale a ogni avvio del simulatore | no |
heartbeat | coil 0 | — | no |
tare_request | coil 1 | — | sì |
batch_ready | coil 2 | — | sì |
| Comando (Desk → macchina) | Segnale scritto | Valore |
|---|---|---|
set_target_weight | target_weight_kg | richiesto (kg) |
tare | tare_request | true fisso: il simulatore azzera il peso |
ack_batch | batch_ready | false fisso: il simulatore svuota e riparte |
| Evento (macchina → Desk) | Origine | Severità |
|---|---|---|
batch_completed | fronte 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_restored | lettura Modbus fallita / tornata | Error / Info |
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 falseProcedura — collegare il gateway
- Impostare env Frappe:
NODE_RED_BASE_URL,NODE_RED_API_TOKEN, opzionaleNODE_RED_GATEWAY_TOKEN. - Su Node-RED: stesso token in
FACTORYOS_API_TOKEN/FRAPPE_GATEWAY_TOKEN. - Desk → Machine Connection Profile →
enabled=1,base_url= URL interno gateway, salva. - Nuovo Factory Machine → Carica macchine Node-RED (o API
list_node_red_machines/sync_machine_from_node_red). - Lettura: bottone Desk o
read_machine_data→ scrive Machine Data Log. - Comando: form Factory Machine → Node-RED → Invia comando (comandi ammessi dall'inventario, con limiti) → Machine Command in
Pending Approval→ Approva → enqueuedispatch_machine_command. - Con
OT_WRITES_ENABLED=0il gateway non scrive e il comando finisceFailedcon motivoot_writes_disabled.
Uso quotidiano da Desk
| Attività | Percorso Desk |
|---|---|
| Verificare connessione | Awesome Bar → Machine Connection Profile → stato Connected/Error |
| Sincronizzare anagrafica | Aprire Factory Machine → Carica macchine Node-RED → selezionare id inventario |
| Pannello live | Form Factory Machine → sezione Pannello controllo (polling ~12s; Aggiorna da Node-RED forza read) |
| Leggere valori | Pannello / bottone Leggi dati da Node-RED → snapshot + Machine Data Log |
| Inviare comando | Pannello Invia comando o Node-RED → Invia comando → Approva sul Machine Command (Factory Admin / Production Manager) |
| Consultare eventi | Form Factory Machine → collegamenti Machine Event, oppure List Machine Event → filtri machine, severity, occurred_at |
| Audit completo | List 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:
| Metodo | Uso | Ruoli |
|---|---|---|
list_node_red_machines | Inventario | Factory Admin, Production Manager, System Manager |
sync_machine_from_node_red | Upsert Factory Machine | Factory Admin, Production Manager, System Manager |
read_machine_data | Lettura + log + aggiorna snapshot | + Line Operator |
get_machine_panel | Aggregato stato/snapshot/allarmi/comandi; refresh=1 → read live | + Line Operator |
get_machine_commands | Comandi ammessi dall'inventario (segnale, valore richiesto, limiti) | + Line Operator |
request_machine_command | Crea comando Pending Approval | + Line Operator |
approve_machine_command / reject_machine_command | Approval | Factory Admin, Production Manager, System Manager |
ingest_machine_event / ingest_machine_telemetry | Callback gateway, solo POST; telemetria aggiorna anche signal_snapshots | Gateway / Factory Admin, Production Manager |
Document class methods su Machine Command: submit_for_approval, approve, reject.
Chiamata RPC via HTTP (esempio lettura):
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, soloPOST; senzaX-FactoryOS-Gateway-Tokenvalido respingono Guest (ADR-0005). - Token solo server-side (
frappe.conf). - Allowlist comandi/segnali in
deploy/node-red→machines.inventory.json; con la mappacommandsun comando scrive solo il suo segnale. - Staging e produzione: scritture abilitate verso il solo
modbus-simulatorinterno.
Modalità operative del gateway
Il comportamento dipende dalle env Node-RED, verificabili su GET /factoryos/health:
| Env | Default compose | Staging / produzione | Effetto |
|---|---|---|---|
OT_SIMULATION_MODE | 1 | 0 | 1: letture dai valori simulate dell'inventario |
OT_FORCE_REAL | 0 | 1 | 1: usa gli adapter reali anche con simulazione attiva |
OT_WRITES_ENABLED | 0 | 1 | 0: comandi rifiutati con ot_writes_disabled |
MODBUS_WEIGHER_ENDPOINT | modbus://modbus-simulator:5020 | invariato | Endpoint Modbus di weigher-01 |
Verifica
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.shDesk: profilo Connected; lettura macchina con log MDL; comando Approved→Succeeded/Failed.
Test simulazione Modbus su staging/produzione:
- Factory Machine
weigher-01→ Leggi dati da Node-RED:mode: live,heartbeat: true. - Entro 10 s compaiono Machine Data Log
telemetry keys=...(direction Read). - Al primo lotto completo compare un Machine Event
batch_completed. - Invia comando
ack_batch→ Approva → Machine CommandSucceededconbatch_ready = False (riletto dalla macchina). - Invia comando
set_target_weight= 10 →Succeededcontarget_weight_kg = 10; i lotti successivi si chiudono a 10 kg.
Rollback / Troubleshooting
| Caso | Azione |
|---|---|
| Isolare OT | Profile enabled=0 |
| Bloccare scritture | OT_WRITES_ENABLED=0 su Node-RED |
| Tornare alla simulazione software | OT_SIMULATION_MODE=1, OT_FORCE_REAL=0 su Node-RED e riavvio |
Macchina Offline | Machine Event connection_lost → controllare modbus-simulator nello stack Node-RED |
| Redeploy gateway | Tag precedente Coolify; vedi deploy/node-red/README.md |
| Macchine legacy senza id | Patch migrate_machine_mqtt_node_red assegna legacy-{name} |
