SAPIUS MANUALE

Manuale di Sapius

Dalla cartella della commessa al blocco compilato. Tutto quello che serve per partire da solo.

1. Che cos’è Sapius

Sapius è il collega virtuale del programmatore PLC: legge la commessa, scrive il codice, lo porta nell’ambiente del costruttore, compila, corregge gli errori e conserva risultati e prove. Tu descrivi il risultato; le decisioni restano tue e restano scritte nel progetto. Puoi chiedergli anche proposte motivate, per esempio come organizzare i parametri di un blocco.

In TIA Portal (V16–V20) lavora su una copia verificata del tuo progetto: scrive i blocchi in SCL, li importa, compila e corregge fino a zero errori. Crea UDT, DB e tag, legge l’hardware, prepara schermate e tag HMI WinCC e le prove con PLCSIM Advanced. Per Rockwell, CODESYS, Schneider, TwinCAT e per gli HMI Optix e Weintek genera e modifica i sorgenti e i file di progetto, pronti da importare nell’ambiente del costruttore (capitolo 8).

Per la diagnosi legge i valori dal PLC con S7, Modbus TCP, OPC UA ed EtherNet/IP. Marca del PLC, ambiente di engineering e protocollo sono scelte distinte: le fai tu, commessa per commessa.

Ogni scrittura passa da un tuo sì, oppure dalla modalità di assenso che scegli (capitolo 7). Nella CPU Sapius non carica niente: il download lo fai tu da TIA, quando il lavoro ti convince.

2. Installazione

Requisiti

Sapius gira su Windows 10 a 64 bit (1809 o successivo) e su Windows 11, con WebView2. Il motore dell’agente è incluso nell’installer. Ti servono un conto su sapiusportal.it, da privato o da azienda, e l’AI che preferisci: il tuo account AI, una tua API compatibile, l’AI gestita da Sapius oppure l’AI locale sul tuo PC. Per TIA Portal: V16–V20 con Openness, .NET Framework 4.8 e il tuo utente Windows nel gruppo Siemens TIA Openness. Per le altre marche, il software di engineering del costruttore con le sue licenze.

Installare Sapius

Scarica l’installer dall’area riservata, sezione Download. Se aggiorni, chiudi Sapius prima di lanciarlo: commesse, account e preferenze restano al loro posto. Il programma si installa in C:\Program Files\Sapius; puoi aggiungere sapius al PATH. Progetti e impostazioni sono in %LOCALAPPDATA%\SapiusV2 e la disinstallazione li conserva.

Sapius_Setup_<versione>.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART

Conto e AI

Entra con email e password del conto Sapius. Se usi il tuo account ChatGPT, premi Collega ChatGPT e completa l’accesso OpenAI nel browser: sono due accessi separati. Per cambiare conto Sapius usa Logout; per cambiare ChatGPT usa lo scollegamento nel pannello dell’account e ricollegalo. I progetti rimangono sul PC.

Aggiornamenti e conoscenza

Quando è disponibile un aggiornamento compare Aggiorna ora: Sapius verifica il download con l’impronta pubblicata e poi avvia l’installer. Puoi rimandare. Al primo avvio scegli se contribuire alla conoscenza tecnica condivisa: è facoltativo e lo cambi quando vuoi nelle impostazioni (capitolo 6).

Lingua di Sapius

Scegli italiano, inglese, spagnolo, tedesco o francese dal pulsante della lingua in alto oppure da Impostazioni → Lingua, anche prima dell’accesso. La scelta resta salvata su questo PC e il cambio conserva bozze, allegati e lavoro in corso. Nelle nuove conversazioni l’assistente usa la lingua scelta, salvo una tua richiesta diversa. Codice PLC, nomi dei tag, documenti e messaggi tecnici originali restano come sono.

Icone, colonne e aiuto

La barra usa icone con descrizioni al passaggio del mouse: registro, libro del manuale, lingua, impostazioni e uscita. Il libro apre questo manuale nella lingua scelta. Trascina il bordo fra Progetti e chat o fra chat e dettagli per cambiare le larghezze, salvate su questo PC. Da tastiera seleziona il divisorio e usa le frecce; Shift aumenta il passo, Home o doppio clic ripristinano la larghezza iniziale. Nelle finestre strette i pannelli si adattano allo spazio disponibile.

Per una nuova commessa usa il + accanto a Progetti (Nuovo progetto), compila nome, cliente e revisione e conferma. Il pulsante grande in alto, con una commessa aperta, crea invece una nuova conversazione. Puoi chiedere a Sapius come usare il programma: conosce la guida della versione installata e ti spiega i passaggi.

3. Prova, prezzi e licenze

La prova di 7 giorni

Sette giorni su un progetto, con Officina, senza carta. Crea il conto, da privato o da azienda, verifica l’email e accetta le condizioni di vendita con il codice che ricevi per email (sei cifre, valido 15 minuti). In Sapius premi Attiva la prova di 7 giorni, oppure usa /prova. Durante la prova usi il tuo account AI, una tua API compatibile oppure l’AI locale.

Ogni conto e ogni PC hanno diritto a una prova. Alla scadenza non parte nessun addebito automatico: i tuoi progetti restano sul PC. Per continuare attivi l’abbonamento quando vuoi.

Il prezzo

Sapius, per postazionePrimo meseDal secondo mese
Aziende e professionisti149 € + IVA299 € + IVA al mese
Privati in Italia181,78 € IVA inclusa364,78 € IVA inclusa al mese

Il primo mese promozionale vale alla prima attivazione a pagamento del conto. L’abbonamento comprende tutti gli strumenti di Sapius, Officina, gli aggiornamenti e 10 € di saldo AI per ogni mese e postazione pagata. Puoi sempre usare il tuo account, la tua API o l’AI locale. Software e licenze dei costruttori si acquistano dai rispettivi produttori.

Acquisti e rinnovi

Nell’area riservata apri Acquisti, scegli Sapius e paga su Stripe: il riepilogo mostra l’importo e l’IVA secondo i tuoi dati di fatturazione. A pagamento confermato la licenza è nella pagina Licenze. Abbonamenti e Fatture raccolgono i documenti e la gestione del conto.

L’abbonamento si rinnova ogni mese. Lo disdici quando vuoi dall’area riservata e resta attivo fino alla fine del periodo pagato. Dalla gestione pagamenti aggiorni il metodo di pagamento. La fattura elettronica viene trasmessa a parte tramite SDI. Se acquisti da privato hai 14 giorni per recedere: il pulsante è nella pagina Acquisti, il modulo è nella pagina Modulo di recesso.

Licenza della postazione

Il pannello del conto e /licenza mostrano il codice macchina di 24 caratteri. Nella pagina Licenze dell’area riservata incolla il codice, attiva la postazione e scarica il file .licenza; poi caricalo in Sapius dal pannello del conto (Carica la licenza) oppure con /licenza <file> nel terminale.

Il codice identifica il PC: deriva dalla scheda madre oppure dall’installazione di Windows, e per questo Sapius funziona anche in macchina virtuale. Se reinstalli Windows, annulla la vecchia attivazione dalla pagina Licenze e attiva il nuovo codice. Per più macchine virtuali clonate, dai a ciascuna la propria installazione di Windows prima di attivarla.

Puoi spostare la licenza su un altro PC fino a tre volte in 12 mesi; riscaricare la stessa licenza non conta come spostamento. I tuoi progetti restano sempre sul PC.

4. AI, saldo e budget

Quattro modi di usare l’AI

  • Il tuo account AI: colleghi ChatGPT e lavori con i modelli del tuo catalogo.
  • Una tua API compatibile: indichi modello ed endpoint e lavori con il tuo fornitore.
  • AI gestita da Sapius: usi il saldo incluso nell’abbonamento e le ricariche; modelli e tariffe sono nel catalogo.
  • AI locale: il modello lavora sul tuo PC e non consuma API né saldo.

Gli strumenti di Sapius sono gli stessi in tutti e quattro i casi. La scelta vale dalle nuove conversazioni: quelle già aperte conservano modello, collegamento e profilo economico.

Con account e API propri i contenuti necessari al lavoro vanno al fornitore che hai scelto. Con l’AI gestita passano dal gateway Sapius al fornitore indicato nel catalogo. Con l’AI locale vengono elaborati sul tuo PC. La conoscenza condivisa è un’altra cosa: il consenso alle schede tecniche non riguarda chat o progetti. Consulta privacy e condizioni.

Impostare l’AI

  1. Apri Impostazioni → AI e consumo.
  2. Scegli il tuo account ChatGPT, una tua API, l’AI gestita da Sapius oppure l’AI locale.
  3. Con l’AI gestita scegli un modello del catalogo e il budget massimo in euro per il lavoro. Per una tua API indica modello, endpoint Responses compatibile e il nome della variabile d’ambiente che contiene la chiave: il segreto resta fuori da Sapius. Un endpoint locale senza autenticazione può fare a meno della variabile.
  4. Nel portale apri AI e saldo per vedere disponibilità, saldo incluso e acquistato, prenotazioni, movimenti e tariffe.

Per le nuove conversazioni con l’AI gestita o con una API compatibile è consigliato GPT 6.1 Sol (gpt-6.1-sol), con i cinque livelli di intensità low, medium, high, xhigh e max. Con il tuo account trovi i modelli del suo catalogo.

Saldo, ricariche e budget

Ogni mese pagato comprende 10 € di saldo AI per postazione, da usare entro il periodo indicato nel portale. Le ricariche facoltative sono da 20, 50 e 100 € + IVA (per i privati in Italia 24,40 €, 61,00 € e 122,00 € IVA inclusa): non hanno rinnovo automatico e restano disponibili anche al cambio del mese. Prima del pagamento Stripe mostra il totale. Le tariffe per modello sono nella pagina AI e saldo, distinte per input, cache e output; si contabilizza il consumo effettivo.

Al limite di saldo o di budget il lavoro si mette in pausa e conserva i risultati: decidi tu se alzare il limite, ricaricare o cambiare modalità. Nessuna ricarica e nessun cambio di modello partono da soli. Per cambiare il limite di una conversazione già aperta, premi il pulsante budget vicino all’intensità quando il lavoro è in pausa o terminato: il nuovo limite comprende anche quanto già consumato.

AI locale

Apri Impostazioni AI → Installa AI locale → Installa e avvia, poi scegli AI locale per una nuova conversazione. Servono Windows x64, almeno 16 GB di RAM installata, 8 GB liberi e 8 GB di disco. Il modello, circa 2,76 GB, si scarica al primo avvio e lavora sulla CPU del tuo PC.

5. Il primo progetto

Creare la commessa

Premi Nuovo progetto, indica nome, cliente e revisione e apri una conversazione. Scrivi scopo e vincoli del lavoro. Scegli il profilo di engineering del progetto: Siemens, Rockwell, Schneider Machine Expert o Control Expert, CODESYS oppure Beckhoff.

Scegliere la cartella

Apri i tre puntini accanto al titolo della commessa, poi Cartella della commessa. Sfogli le cartelle del PC senza scrivere il percorso. Conferma la revisione; con Aggiorna importi i file cambiati. I file acquisiti vengono copiati nel progetto Sapius, con fonte e revisione.

Importare documenti nelle fonti

Dagli stessi tre puntini apri Fonti → Importa. Nel normale selettore di file scegli uno o più file e aprili. Sapius usa la revisione corrente della commessa, dà un esito per ogni file e riconosce quelli già acquisiti, senza duplicare le fonti.

Le fonti restano nel progetto con origine e revisione e sono disponibili in tutte le conversazioni della commessa, anche dopo il riavvio. Sono distinte dagli allegati del messaggio, che aggiungi con il + nel compositore.

Puoi importare fino a 20 MB per file: PDF, Word .docx, Excel .xlsx/.xlsm, Markdown, CSV, XML, JSON, testo e sorgenti PLC. Il riepilogo mostra l’esito file per file. Per un PDF scannerizzato prepara una versione con testo selezionabile: Sapius conserva comunque l’originale fra le fonti.

PLC / Comunicazione

Nel pannello della commessa apri PLC / Comunicazione. Scegli marca o ambiente, famiglia o modello e protocollo. Nel secondo passaggio imposta i parametri: S7 usa host, porta, rack e slot; Modbus TCP Unit ID, base e ordine delle parole; OPC UA URL e sicurezza; EtherNet/IP famiglia CIP e percorso. Conferma salva la configurazione per i prossimi avvii; Annulla lascia tutto com’era.

Il collegamento di engineering al progetto e la comunicazione con il PLC hanno stati separati: cambi la marca senza toccare il protocollo, e viceversa.

Test della comunicazione

Premi Test per una verifica immediata. S7 verifica la negoziazione del protocollo. Per Modbus TCP, OPC UA ed EtherNet/IP indichi l’indirizzo o il tag e il tipo da leggere. Il test legge soltanto: nessun valore scritto, nessun comando alla CPU. Dopo l’esito premi Conferma per salvare la configurazione.

OPC UA conserva le verifiche dei certificati; il modulo grafico configura l’accesso anonimo.

6. Lavorare con l’agente

Conversazioni e pannelli

Scrivi il risultato che vuoi, allega le fonti con + e lascia all’agente il ciclo di lettura, modifica e verifica. Nella barra scegli l’intensità del lavoro. Il registro mostra le attività; Chiudi o Esc richiude i pannelli. Logout permette di cambiare conto.

Mentre Sapius lavora, la chat mostra aggiornamenti e attività con icone e dettagli apribili, distinti dalla risposta finale, e il piano quando il motore lo comunica. Lo scorrimento segue il lavoro quando sei vicino al fondo; se risali per leggere, mantiene la tua posizione, e Ultimi aggiornamenti ti riporta al presente. La risposta finale usa Markdown per elenchi, codice e collegamenti.

Invio manda il messaggio; Shift+Invio (Maiusc+Invio) va a capo. Anche Ctrl+Invio invia. Se l’agente sta lavorando, il messaggio va in coda, come descritto sotto; Stop è il comando separato per fermare il turno.

Per allegare usa +, trascina un file nel compositore oppure incolla una schermata. Ogni allegato può arrivare a 25 MB. Aspetta la fine del caricamento prima di inviare; togli un allegato dal prossimo messaggio con la croce nella sua scheda.

Fai clic su un allegato o un artefatto per aprire l’anteprima: immagini e PDF si mostrano nel pannello, testi e sorgenti, compreso Markdown, si leggono come testo. Gli altri formati li apri dalla cartella della commessa. Puoi allargare il pannello, trascinarne il bordo o chiuderlo; nelle finestre strette si apre sopra la chat e si chiude anche con Esc.

Dal pulsante i apri le informazioni e Aspetto: qui scegli il tema chiaro, scuro o come Windows, ricordato sulla postazione. Il menu ··· accanto al titolo della commessa apre le sue opzioni, la cartella e la comunicazione PLC.

Coda e Reindirizza

Puoi inviare altri messaggi mentre l’agente lavora: restano in coda nella conversazione e vengono elaborati in ordine. Reindirizza manda la precisazione al turno in corso, senza riavviarlo: usalo per correggere un’ipotesi o aggiungere un vincolo. Le autorizzazioni restano quelle che hai scelto.

Dopo uno Stop, un errore o un riavvio la coda resta in pausa, a tua disposizione: controllala e riprendi. Un invio dall’esito incerto non viene ripetuto da solo: decidi tu.

Risultati e memoria del progetto

Artefatti, fatti con la loro fonte, decisioni e domande aperte restano nella commessa. Un sorgente proposto, un blocco compilato, una prova in simulazione e una verifica in campo sono risultati diversi, e Sapius li tiene distinti: chiedi sempre l’esito della compilazione e le prove eseguite, insieme al file.

L’agente può proporre l’organizzazione dei DB dei parametri, il richiamo dei blocchi, la diagnostica o un collaudo adatto al contesto. Le scelte che hai già espresso restano il riferimento.

Conoscenza condivisa

Al primo avvio o nelle impostazioni puoi aderire alla condivisione di schede tecniche generali strutturate. Con l’adesione attiva Sapius le invia alla revisione del titolare, che decide la pubblicazione. Chat, documenti, sorgenti e dati della commessa restano fuori.

Le bozze a testo libero chiedono ogni volta la tua conferma. Puoi revocare l’adesione dalle impostazioni quando vuoi. Preferenze personali, fatti della commessa e lezioni condivise restano tre memorie distinte.

Dopo una correzione, Sapius collega errore, modifica e verifica riuscita e conserva sintomo, causa proposta, soluzione e condizioni di applicabilità. La ricerca riconosce anche i sinonimi tecnici italiani e inglesi, e i riscontri di riuso aiutano a valutare le lezioni.

7. Autorizzazioni, Tutto e Officina

Il consenso nel servizio

Il servizio verifica i permessi nel momento in cui esegue lo strumento: decidi tu, e solo tu. Analisi, scrittura di file, engineering offline, import nel progetto e letture dal PLC sono operazioni distinte, e ognuna conserva parametri, risultato e provenienza.

Scegliere la modalità

  • Manuale: chiede il consenso per ogni operazione oltre la pura analisi.
  • Modifiche ai file: consente file di lavoro, engineering offline e comandi locali; chiede per le classi successive.
  • Auto: comprende anche le letture dal PLC sulla destinazione dichiarata.
  • Tutto: comprende gli import TIA sulla copia di lavoro, inclusi FB, FC, nuovi DB, UDT e Main, senza un clic per ogni blocco. Il servizio registra l’assenso per ogni tentativo e contenuto.
  • Officina: un consenso su un FB o FC copre le correzioni di quel blocco per otto ore, nella stessa copia e CPU; gli altri blocchi seguono la loro autorizzazione.

Copie, controlli e ripresa

Tutto lavora sulla copia: l’originale resta com’è, e download e manovre sul PLC restano nelle tue mani. Restano attivi i controlli della copia, gli archivi e le protezioni. La sostituzione di un DB esistente segue un percorso dedicato: analisi, copia isolata, compilazione e verifica.

Quando viene richiesto un consenso, controlla destinazione e parametri. Anche un diniego resta registrato. Alla ripresa, un’operazione dall’esito incerto aspetta la tua decisione. I comandi locali possono usare file e risorse del PC: scegli la modalità in base al lavoro che vuoi affidare.

8. TIA Portal e altri ambienti

Preparare e collegare TIA

Imposta la versione di TIA e la cartella delle copie di lavoro. L’agente prepara la copia con archiviazione e riapertura, poi identifica sessione e percorso prima di collegarsi. Usa la versione del progetto, così eviti conversioni involontarie. Quando TIA mostra il consenso Openness, accettalo nell’applicazione Siemens; TIA può chiederlo di nuovo dopo un aggiornamento.

Programma e hardware

Sapius esplora CPU, blocchi, tabelle dei tag e configurazione hardware e lavora sulla copia. Scrive e importa SCL e SimaticML, organizza FB, FC, DB e UDT, richiama il lavoro nel Main, compila, legge gli errori, corregge e salva, fino a zero errori. Per aggiungere un modulo verifica catalogo, compatibilità e configurazione esistente.

Con Tutto il ciclo prosegue con il consenso che hai già dato sulla copia. Per i DB esistenti Sapius analizza gli effetti, prova la sostituzione su una copia isolata e conserva le evidenze prima dell’adozione. I blocchi protetti da know-how e il programma di sicurezza restano come sono.

WinCC e PLCSIM

Gli strumenti HMI WinCC lavorano dentro TIA su schermate, tag e liste di testi, sempre sulla copia; i template si possono inventariare ed esportare. Se il pannello usa una connessione integrata, la trovi nei tag anche quando l’elenco Connections è vuoto: non serve crearne un’altra. Con PLCSIM Advanced Sapius prova il programma su un’istanza di simulazione dedicata, separata dalla tua sessione di lavoro.

La consegna distingue la compilazione del software PLC, dell’hardware e dell’HMI. Dopo il confronto degli export, Sapius salva e può creare un archivio completo del progetto, con dimensione e SHA-256.

Altri PLC e HMI

AmbienteChe cosa fa Sapius e come prosegui
Rockwell / Studio 5000Legge gli export L5X, ne fa l’inventario e genera o modifica routine ST, tag e tipi di dati su una copia. Importi il file in Studio 5000 e compili lì.
CODESYS / Schneider Machine ExpertGenera sorgenti ST e visualizzazioni (Visualization XML) da specifica, con un catalogo di nove componenti, e legge gli export. Importi i file nel tuo IDE CODESYS o Machine Expert.
Schneider Control ExpertGenera e valida sezioni ST .XST e nuove variabili .XSY, usando se vuoi un export del tuo progetto come modello. In Control Expert importi prima le variabili e poi la sezione, analizzi e compili; se l’IDE segnala errori, li riporti a Sapius e li corregge.
Beckhoff TwinCATLegge progetti e oggetti PLC e modifica i POU in ST su una copia, con archivio. Apri la copia in XAE per compilare e attivare.
Weintek EasyBuilder ProGenera i CSV dei tag e le macro tipizzate GetData/SetData da specifica, pronti da importare in EasyBuilder Pro.
FactoryTalk OptixGenera NetLogic C# e nodi YAML per pannelli, variabili e widget, anche in una copia del progetto. Apri il progetto in FactoryTalk Optix e richiami il metodo Build.

Per ogni marca Sapius controlla il formato dei file che produce e lavora sempre su copie: l’originale resta com’è. Per importare e compilare usi il software del costruttore, con le sue licenze.

Concludere il lavoro

Chiedi una consegna con file, esito della compilazione, prove e punti aperti. Il passaggio al progetto definitivo e al PLC lo decidi tu: copi il blocco in TIA da un progetto all’altro, oppure importi il sorgente, che resta fra i file della commessa.

9. Il terminale

Avvia sapius; sapius --aiuto elenca le opzioni. Il terminale condivide progetti, fonti e controlli con la finestra. Qui l’agente usa una tua API: passa la chiave con OPENAI_API_KEY o ANTHROPIC_API_KEY.

/progetti, /nuovo, /conversazioni, /nuova, /fonti e /importa gestiscono il lavoro. /costruttore sceglie il profilo di engineering. /plc mostra la comunicazione; /plc configura file.json la salva, /plc test file.json [indirizzo tipo] esegue un test e /plc rimuovi la rimuove. /cpu resta disponibile per S7.

/accedi esci disconnette il conto; /licenza, /prova, /aggiornamenti, /registro, /riprendi e /aiuto completano i comandi principali. Quando viene richiesto un consenso serve una tua risposta esplicita: chiudere il terminale non vale come sì.

10. Se qualcosa non va

Accesso, quota e aggiornamento

Controlla prima quale conto Sapius e quale account AI sono collegati. Se la quota del tuo account OpenAI è esaurita, consulta il tuo conto OpenAI oppure passa a un altro collegamento AI dalle impostazioni. Se manca la licenza, attivala dall’area riservata. Se un aggiornamento non compare, verifica la connessione e usa il controllo aggiornamenti.

Collegamento PLC o TIA

Controlla marca, protocollo, destinazione e parametri. Per S7 verifica rack, slot e configurazione di accesso: PUT/GET e DB ad accesso standard servono per le letture S7. Per gli altri protocolli controlla l’indirizzo di prova, il tipo e le impostazioni di sicurezza. Per TIA verifica versione, gruppo Openness e finestre di dialogo in attesa.

Riprendere il lavoro

Chiudi i pannelli con Chiudi o Esc. Dopo uno Stop riapri la conversazione, controlla la coda e riprendi. Per un’operazione dall’esito incerto consulta il registro e la destinazione, poi decidi se ripeterla. Per una mano scrivi a support@sapiusportal.it: ti risponde un programmatore PLC.

11. Glossario

Commessa: progetto con fonti, revisioni e decisioni. Artefatto: file prodotto e conservato. Copia di lavoro: la copia del progetto su cui Sapius scrive. Protocollo: comunicazione con il dispositivo, scelta a parte rispetto all’IDE. Campione: valore letto dal PLC, con qualità, istante e provenienza. Compilato: accettato dal compilatore. Simulato: eseguito in un ambiente di simulazione. Verificato in campo: controllato sull’impianto, con evidenze. Officina: modalità in cui un consenso copre le correzioni dello stesso blocco per otto ore. AI gestita: AI fornita da Sapius, a saldo.