Ganter Lab
Accedi Scarica

Gli strumenti, area per area

Che cosa fa ogni strumento che un agente può chiamare, raggruppato per l'interruttore di capacità che lo annuncia.

Visualizza come Markdown

I nomi degli strumenti sono identificatori stabili in snake_case. Gli errori sono strutturati e utilizzabili: una chiamata fallita restituisce che cosa è andato storto più un suggerimento che nomina lo strumento o il passo che lo risolve, così un agente si corregge da solo invece di tirare a indovinare. Quando l'area Backup (gestione) è attiva, il server istruisce anche gli agenti a creare un backup della configurazione prima di modificarla. Quale di questi elenchi un agente veda davvero è che cosa apre ogni area.

Connector: lettura

Strumento Che cosa fa
connector_browse Elenca l'albero configurato con lo stato di salute in tempo reale: per Modbus RTU driver, linea seriale, dispositivo, tag; per ogni altro driver driver, dispositivo, tag con accanto la cartella di ciascun dispositivo. Rivela gli alias dei tag (Driver.Folders….Device.Tag) che usano tag_read, tag_write e le espressioni di Logic. Gli alias sono nulli mentre il server integrato è fermo.
tag_read Legge i valori in tempo reale di un tag tramite l'alias: il valore grezzo a livello di dispositivo, il valore ingegneristico dopo la catena di conversione, la qualità e le due marche temporali.

Connector: configurazione

Strumento Che cosa fa
driver_capabilities Elenca ogni driver che l'applicazione può servire con i campi di connessione che un dispositivo richiede, il modello di indirizzamento dei tag (indirizzo a testo libero e/o campi tipizzati), il supporto al rilevamento e i suoi parametri, gli intervalli di temporizzazione e i tipi di valore supportati. È la mappa che un agente legge prima di device_upsert o tag_upsert.
serial_line_list Elenca ogni linea seriale Modbus RTU salvata, comprese quelle disabilitate e vuote, con il suo id stabile e i valori di temporizzazione configurati, automatici ed effettivi.
serial_line_upsert Crea una linea Modbus RTU o ne aggiorna una tramite l'id stabile. Nome e stato di abilitazione cambiano in qualsiasi momento; anche l'intervallo minimo tra le transazioni cambia mentre la linea è abilitata; porta seriale, velocità in baud, formato seriale e timeout di risposta cambiano solo mentre la linea salvata è disabilitata.
serial_line_delete Elimina una linea tramite l'id stabile. Una linea che contiene ancora dispositivi viene rifiutata, a meno che la chiamata non autorizzi esplicitamente l'eliminazione di ogni dispositivo e tag figlio.
device_upsert Crea o aggiorna un dispositivo per driver più nome (il driver è immutabile dopo la creazione). Cambiano solo i parametri forniti; i campi di connessione dipendono dal driver; spostare un dispositivo in una cartella riscrive ogni riferimento ai suoi vecchi indirizzi di tag. La modifica viene riconciliata subito nel server in esecuzione.
device_delete Elimina un dispositivo e tutti i suoi tag; riconciliato subito nel server in esecuzione.
tag_upsert Crea o aggiorna un tag su un dispositivo. L'indirizzamento dipende dal driver (indirizzo a testo libero e/o campi tipizzati); la risposta riporta l'indirizzo di bus assemblato e l'alias per tag_read. Comprende le fasi della lettura non valida (azione su NaN e presentazione dell'errore di lettura) per i tag numerici.
tag_delete Elimina un tag; riconciliato subito.

Logic: lettura

Strumento Che cosa fa
logic_browse Sfoglia lo spazio degli indirizzi di Logic a partire dalla radice, lo stesso albero a punti che legge ogni espressione: System, Server, Connector, Variables, Alarms, Process e Assets. Le cartelle create dall'operatore sono livelli reali dell'indirizzo; i punti figli portano il valore in tempo reale e la qualità.
logic_read Legge un punto tramite il suo indirizzo a punti (per esempio Variables.Setpoint) e restituisce il valore in tempo reale e la qualità.

Logic: configurazione

Gli upsert sono parziali (i parametri omessi mantengono il loro valore) e ogni bozza fusa supera la stessa convalida che applicano gli editor di Logic; una bozza non valida viene respinta e nulla resta applicato a metà.

Strumento Che cosa fa
variable_upsert Crea o aggiorna una variabile: Expression (una singola espressione JavaScript di sola lettura sullo spazio degli indirizzi) o Memory (un valore scrivibile, facoltativamente ritentivo). Il nome è la chiave e, ripulito, l'indirizzo; il parametro della cartella la archivia, riscrivendo ogni riferimento al vecchio indirizzo.
variable_delete Elimina una variabile per percorso, compreso il suo valore ritenuto. I canali collegati a essa perdono la sorgente.
action_upsert Crea o aggiorna un'azione: un blocco di istruzioni JavaScript con esattamente due verbi di scrittura, l'assegnazione a una variabile Memory e la scrittura del tag ingegneristico. Convalidata staticamente, mai eseguita al salvataggio.
action_delete Elimina un'azione per nome. Gli attivatori collegati a essa restano inattivi.
trigger_upsert Crea o aggiorna un attivatore a intervallo: ogni intervalMs (minimo 100) l'azione collegata scatta sulla coda della logica; un battito durante un'esecuzione ancora in corso viene saltato. Il collegamento all'azione è debole e avviene per nome.
trigger_delete Elimina un attivatore; l'azione collegata resta intatta.
alarm_upsert Crea o aggiorna un allarme: un'espressione di condizione Bool, la priorità (Critical/High/Medium/Low), i ritardi di attivazione e di rientro, se è richiesta la tacitazione e lo stile di segnalazione. Salvare una condizione o una temporizzazione modificata azzera la macchina a stati in esecuzione.
alarm_delete Elimina un allarme per percorso; una segnalazione attiva viene prima azzerata.
logic_folder_upsert Crea, rinomina o riarchivia una cartella di organizzazione di una sezione (Variables, Alarms, Actions, Triggers; al massimo tre livelli). Per Variables e Alarms il percorso della cartella fa parte dell'indirizzo, quindi rinomine e spostamenti riscrivono ogni espressione, script, condizione e collegamento di dashboard sottostante.
logic_folder_delete Elimina una cartella. Nulla di ciò che conteneva viene distrutto: elementi e sottocartelle risalgono di un livello e i riferimenti vengono riscritti; una collisione di nomi nella destinazione fa rifiutare l'eliminazione.

Logic: comando

Tutti questi passano dalla coda unica della logica e vengono registrati con origine MCP.

Strumento Che cosa fa
variable_write Scrive un valore in una variabile Memory (convertito al suo tipo di uscita, ritenuto se la variabile è ritentiva). Le variabili Expression sono calcolate e rifiutano le scritture.
tag_write Scrive un valore ingegneristico su un tag scrivibile: percorre all'indietro la catena di conversione del tag, viene convertito al tipo del dispositivo e scritto sull'apparecchiatura. I tag di sola lettura e i driver di sola lettura vengono rifiutati con il motivo.
action_run Esegue un'azione sulla coda della logica e ne restituisce l'esito e la durata. Un'azione disabilitata fallisce senza essere eseguita.
alarm_ack Tacita un allarme, la risposta dell'operatore; non fa nulla quando non c'è niente in attesa.
alarm_ack_all Tacita ogni allarme che lo attende, in un solo elemento della coda della logica e con ogni transizione registrata.

Server: lettura

Strumento Che cosa fa
server_status Riferisce lo stato di salute del server OPC UA integrato: stato di esecuzione, tempo di attività, URL dell'endpoint, sessioni client collegate e dimensione dello spazio degli indirizzi configurato.

Server: comando

Strumento Che cosa fa
server_start Avvia il server OPC UA integrato, materializzando la configurazione attuale. Non fa nulla quando è già in esecuzione.
server_stop Ferma il server in modo ordinato. La comunicazione con i dispositivi, le letture dei tag e lo spazio degli indirizzi di Logic in tempo reale si fermano finché non riparte.
server_restart Ferma e poi avvia, rimaterializzando la configurazione; è la ricarica completa dopo una serie di modifiche.
connector_refresh Riconcilia in modo incrementale il server in esecuzione con i dispositivi configurati (aggiunge, rimuove, ricrea) senza un riavvio completo; è il modo più leggero per applicare le modifiche.
device_discover Esegue la scansione di rilevamento dei dispositivi di un driver e restituisce i candidati con i loro tag, senza salvare nulla. Partecipano solo i driver il cui protocollo supporta una vera scansione; i candidati già esistenti sono segnalati come tali.

Diario: lettura

Strumento Che cosa fa
logs_read Legge il flusso di diario in tempo reale di tutto il programma (lo stesso della console di Eventi), filtrato per gravità minima (Debug/Information/Warning/Error, predefinito Information), area (App/Server/Connector/Logic/Process/Dashboard/Agent/Licensing), componente e una sottostringa di contesto; restituisce le corrispondenze più recenti (predefinito 100, al massimo 500). Le azioni degli agenti sono registrate nell'area Agent.
event_history_read Legge la cronologia persistente degli eventi di esercizio, che sopravvive ai riavvii: transizioni di allarme, di occorrenza e di interblocco. Filtra per tipo (Alarm/Occurrence/Interlock), un periodo UTC inclusivo e un livello (priorità dell'allarme, gravità dell'occorrenza o transizione dell'interblocco); dalla più recente, predefinito 100, al massimo 500. Rigorosamente di sola lettura: nulla può cancellare o eliminare le voci del diario.

Process: lettura

Strumento Che cosa fa
process_models Elenca per intero i modelli di Process: canali, gruppi condivisi, unità con il cablaggio risolto e lo stato di esecuzione, procedure, pannelli, ricette, valutazioni, occorrenze, più la libreria globale dei modelli di rapporto. È la mappa che un agente legge prima di avviare qualcosa.
process_runs Elenca le prove, dalla più recente: id, nome, stato, verdetto, che cosa è stato eseguito, chi l'ha avviata (Station/User/Automation/Agent), tempi e avanzamento dei cicli. Può essere ristretto alle prove attive e limitato nel numero (predefinito 50).
process_run Legge per id il registro congelato completo di una prova: istantanea, metadati, criteri giudicati con il numero di campioni, episodi ed eventi di occorrenza, scritture di ricetta come eseguite, commenti, e gli artefatti congelati di rapporto ed etichetta con i loro tentativi di stampa. Facoltativamente calcola il numero di righe del datalog e l'intervallo di tempo.
unit_status Riferisce lo stato in tempo reale di un'unità: se è in prova (con la prova attiva) e il valore ingegneristico attuale dietro ogni canale, letto senza registrare.

Process: configurazione

Strumento Che cosa fa
process_view_configure Configura esattamente un pannello di un modello: l'icona disegnata accanto e se il pannello compare nella pagina View. Nient'altro dell'aggregato di Process è scrivibile via MCP; il resto si modifica nella pagina Process.

Process: comando

Le prove avviate, concluse o commentate da un agente registrano Agent come autore, mai l'operatore che per caso è collegato al banco di prova.

Strumento Che cosa fa
process_snapshot Cattura una riga di datalog su un'unità fuori da una procedura. Ogni chiamata crea una nuova prova Instant, già conclusa, negli Storici, senza valutazione (verdetto None).
process_evaluate Cattura una riga di datalog e la giudica con una valutazione; crea una prova Instant conclusa e ne restituisce il verdetto.
process_recipe_apply Applica una volta una ricetta Instant a un'unità attraverso l'unico punto di scrittura di Process e i blocchi sulle sorgenti. Comanda l'apparecchiatura; non crea alcuna prova (le scritture vengono registrate). Le ricette Temporal sono rifiutate.
process_start Avvia la prova di una procedura su un'unità, con un oggetto JSON per i campi di metadati della procedura. Metadati obbligatori mancanti o non validi, un'unità già in prova o un conflitto di blocco su un canale condiviso fanno rifiutare l'avvio. Restituisce l'id della nuova prova.
process_stop Ferma una prova in corso: blocco di finalizzazione, istantanea congelata nello storico, verdetto calcolato.
process_hold Sospende il profilo temporale di una prova all'ultimo setpoint; il datalog continua a registrare.
process_resume Riprende il profilo temporale di una prova sospesa.
process_abort Interrompe una prova da Running o Held: la finalizzazione viene eseguita, l'istantanea viene scritta, lo stato diventa Aborted e il verdetto NOK.
process_comment Aggiunge un commento con marca temporale nel file di una prova: una nota nella cronologia mentre è attiva, una nota successiva quando è finita.
process_report Genera (o rigenera) il rapporto PDF di una prova conclusa e ne restituisce il percorso del file. Un modello di documento nominato dalla libreria globale prevale su quello configurato nella procedura; senza né l'uno né l'altro vale il layout predefinito con tutte le sezioni. Rifiutato mentre la prova è attiva.
process_run_delete Elimina definitivamente una prova registrata: il puntatore nell'indice dello storico e il file di database della singola prova. Rifiutato mentre è attiva; la configurazione resta intatta.

Dashboard: configurazione

Strumento Che cosa fa
dashboard_list Elenca le dashboard (oppure, nominando un modello, i sinottici di quel modello): dimensione della griglia, cartella, icona, contrassegno di avvio, visibilità per ruolo e ogni componente con la sua posizione, il suo livello e il JSON delle proprietà, più ogni rete di tratti salvata. Restituisce anche il catalogo dei tipi di componente con la dimensione predefinita e l'insieme di proprietà predefinito di ciascun tipo.
dashboard_upsert Crea o aggiorna una dashboard per nome: dimensione della griglia (una riduzione che lascerebbe orfano un componente viene respinta), cartella e icona nell'elenco delle visualizzazioni, contrassegno di avvio, visibilità della barra di stato a schermo intero e visibilità per ruolo. Nominare un modello indirizza invece i sinottici di quel modello. Le pagine di dashboard aperte riflettono subito la modifica.
dashboard_delete Elimina una dashboard e i suoi componenti per nome; nominare un modello elimina invece il sinottico di quel modello.
component_upsert Aggiunge un componente per tipo (collocato nella prima cella libera con la dimensione predefinita del tipo, salvo indicazione diversa) oppure ne aggiorna uno per id. La collocazione deve stare dentro la griglia; la sovrapposizione è ammessa e il livello z decide l'ordine di disegno; il JSON delle proprietà è l'insieme tipizzato di quel tipo. Nominare un modello indirizza invece i sinottici di quel modello, così un sinottico creato là si può impaginare qui.
component_delete Rimuove un componente per id; nominare un modello indirizza invece i sinottici di quel modello.
connection_upsert Collega due morsetti di un simbolo con una rete di tratti tipizzata, risolvendo tipo, ruolo e direzione dal catalogo dei simboli esattamente come fa l'editor dell'area di disegno. Le estremità che si risolvono in tipi diversi falliscono, a meno che non sia esplicitamente ammesso un tratto indefinito; un ancoraggio che porta già un tratto viene respinto. Nominare un modello indirizza invece i sinottici di quel modello.
connection_delete Rimuove una rete di tratti per id e revisione attesa, così un'eliminazione basata su dati vecchi viene respinta invece di cancellare una modifica più recente; nominare un modello indirizza invece i sinottici di quel modello.

Interfaccia: automazione

Questi strumenti pilotano la finestra reale dell'applicazione; esistono perché un agente possa verificare l'interfaccia che vede l'operatore, non una sua simulazione. Le interazioni vengono inviate alla shell in esecuzione, quindi la condotta prevista è far seguire a ogni gesto un ui_screenshot e osservarne l'effetto, e le corrispondenze ambigue tornano come elenchi di candidati invece che come un clic indovinato.

Strumento Che cosa fa
ui_state Riferisce lo stato della shell: pagina attiva, pagine disponibili, tema, dimensione e visibilità della finestra, e l'indirizzo di loopback su cui questa istanza serve la propria interfaccia. È la chiamata di orientamento che precede tutto il resto.
ui_navigate Attiva una pagina della shell tramite il suo nome stabile, che è in inglese su ogni stazione: View, Process, Logic, Connector, Users, Validation, Events, Agent, Settings, Account. Viene accettata anche l'etichetta che la barra di navigazione mostra nella lingua della stazione.
ui_screenshot Cattura la finestra così come appare sullo schermo in un file PNG e ne restituisce il percorso assoluto; se la finestra è nascosta nell'area di notifica la ripristina prima. Può catturare una singola zona nominata dello schermo (un'area data-doc-region univoca e visibile) invece dell'intera finestra, e una zona mancante, nascosta o ambigua fallisce elencando le zone visibili invece di ripiegare in silenzio sulla cattura completa.
ui_scroll Fa scorrere la zona di scorrimento principale della pagina attiva all'inizio, alla fine o di un numero di schermate, restituendo gli scostamenti così che una pagina lunga si possa percorrere tutta.
ui_set_theme Applica il tema (System, Light o Dark). Viene salvato esattamente come dal menu del tema nella barra del titolo, quindi un agente ben educato ripristina il valore originale quando ha finito.
ui_resize Ridimensiona la finestra ripristinata in unità indipendenti dal dispositivo, limitata al minimo della finestra; utile per verificare le impaginazioni strette.
ui_click Fa clic sul pulsante, collegamento, casella di spunta o interruttore visibile il cui testo corrisponde; caselle di spunta e interruttori si trovano tramite l'etichetta del campo e il risultato riferisce lo stato raggiunto. L'ambiguità restituisce i candidati invece di sceglierne uno.
ui_set_text Scrive un valore in una casella di testo identificata dall'etichetta del suo campo, confermando il collegamento come farebbe la digitazione.
ui_select Seleziona un elemento tramite il testo visibile: un percorso separato da barre percorre un albero, espandendolo lungo la strada; un solo segmento corrisponde anche a elementi di elenco, schede, voci di casella combinata e righe di griglia nella pagina attuale.

Backup: gestione

Strumento Che cosa fa
backup_create Crea un'istantanea a caldo del database di configurazione nella cartella dei backup, con una nota facoltativa. Le prove registrate vivono fuori dalla configurazione e non vengono mai toccate dal backup né dal ripristino.
backup_list Elenca i backup della configurazione (nome del file, data di creazione, dimensione, nota) più l'eventuale ripristino già programmato.

Non esiste deliberatamente alcuno strumento di eliminazione dei backup: la conservazione è solo dell'operatore, nella pagina Backup.

Backup: ripristino

Strumento Che cosa fa
backup_restore Programma un backup perché sostituisca la configurazione attuale al prossimo avvio dell'applicazione. Nulla cambia nell'applicazione in esecuzione e lo strumento non la riavvia mai; la configurazione che sta per essere sostituita viene prima salvata automaticamente in un'istantanea, e l'operatore può annullare il ripristino in attesa dalle Impostazioni fino al riavvio. Rifiutato mentre una registrazione è attiva.

Impostazioni: gestione

Strumento Che cosa fa
settings_read Legge le preferenze di visualizzazione e di ciclo di vita della stazione: formati di data, ora e numero, cifre decimali, tema, contrassegni di chiusura nell'area di notifica e di rapporto di errore.
localization_set Aggiorna le preferenze di visualizzazione (parziale: i parametri omessi restano). Solo visualizzazione: archiviazione, ingressi e uscite dei driver e registrazioni usano sempre il formato invariante.
asset_list Elenca le risorse dell'utente (immagini, icone, colori) con id, valori e percorsi.
asset_import Importa un PNG/JPG dal percorso di un file locale nella libreria di risorse dell'applicazione e restituisce l'id della nuova risorsa. I byte vengono copiati, quindi il file di origine può essere spostato in seguito.
symbol_validate Convalida il contenuto di un simbolo passato per intero (SVG grezzo o pacchetto v2) senza salvare nulla: è una prova a vuoto dell'importazione vera, e restituisce errori, avvisi del depuratore e un riepilogo di ciò che è stato riconosciuto. La descrizione dello strumento porta il contratto completo del simbolo portabile.
symbol_import Importa il contenuto di un simbolo passato per intero come nuova risorsa simbolo dell'utente e ne restituisce l'id e il riferimento user:<guid>. Crea sempre una nuova risorsa; un nome in collisione riceve un suffisso automatico.