Manuale Utente SoftAgent

Verificare che l'ambiente soddisfi i requisiti e prepararsi all'installazione.

1. Verificare che il PC di destinazione esegua Windows 10/11 x64.
2. Verificare di avere i privilegi di account amministratore (l'installer attiva una richiesta di elevazione UAC).
3. Verificare che il firewall consenta il traffico UDP in entrata sulla porta 6500 (porta di ascolto di SoftAgent).
4. Il pacchetto installer è self-contained — non è necessario pre-installare runtime .NET sulla macchina di destinazione.

• Possibilità di eseguire programmi come amministratore (elevazione UAC accettata).
• La porta UDP 6500 non è occupata da un altro programma.

• Più PC controllati possono usare lo stesso installer — configurare porta e indirizzo di segnalazione indipendentemente su ciascuno.
• Per i progetti espositivi, si raccomanda di impostare tutti i PC controllati per il login automatico con un account amministratore affinché l'attività di avvio automatico si attivi in modo affidabile.

Completare l'installazione e confermare che SoftAgent funzioni normalmente nel vassoio di sistema.

1. Fare doppio clic su SoftAgent-Setup-versione.exe e fare clic su Sì nella richiesta UAC per consentire i privilegi di amministratore.
2. Seguire la procedura guidata dell'installer per completare l'installazione (default: C:\Program Files\SoftAgent\).
3. Nella pagina di completamento, facoltativamente spuntare 'Avvia SoftAgent ora', o avviare manualmente dopo.
4. Dopo l'avvio, SoftAgent appare nel vassoio di sistema (nessuna finestra principale si apre).
5. Fare clic destro sull'icona del vassoio e selezionare 'Apri configurazione' — confermare che la finestra principale appaia con 4 schede (Proprietà / Programmi / Watchdog / Impostazioni).

• L'icona di SoftAgent appare nel vassoio di sistema.
• Task Manager mostra entrambi i processi SoftAgent.App e SoftAgent.Watchdog in esecuzione.
• Il clic destro sul vassoio mostra: Apri configurazione / Stato / Pausa Watchdog / Apri directory log / Informazioni / Esci.

SoftAgent usa un'architettura dual-process: il processo App gestisce la funzionalità, e il Watchdog monitora e riavvia automaticamente l'App in caso di crash — si proteggono reciprocamente.

Completare la configurazione di base e confermare che l'agente funzioni tramite ping UDP.

1. Fare doppio clic sull'icona del vassoio per aprire la finestra principale, passare alla scheda Impostazioni.
2. Confermare che la porta di ascolto sia 6500 (o modificarla se necessario), e spuntare 'Avvio automatico' per registrare l'attività pianificata.
3. Per l'integrazione con SoftControl, inserire l'IP:porta della macchina SoftControl nel campo 'Indirizzo di segnalazione'.
4. Fare clic su 'Salva e applica' per salvare la configurazione.
5. Aprire PowerShell e inviare un ping per verificare:
6. $u = New-Object System.Net.Sockets.UdpClient
7. $b = [Text.Encoding]::UTF8.GetBytes('ping')
8. $u.Send($b, $b.Length, '127.0.0.1', 6500)
9. $r = $u.Receive([ref](New-Object System.Net.IPEndPoint([Net.IPAddress]::Any, 0)))
10. [Text.Encoding]::UTF8.GetString($r)
11. Ricevere ok:pong conferma che l'agente funziona normalmente.

• L'invio di ping riceve la risposta ok:pong.
• La casella di spunta avvio automatico nella scheda Impostazioni viene salvata.
• L'esecuzione di schtasks /Query /TN SoftAgent mostra l'attività pianificata registrata.

• Modificare la porta ma dimenticare di fare clic su 'Salva e applica', così la modifica non ha effetto.
• Inserire la porta della console di gestione HTTP invece della porta di ascolto UDP.

Padroneggiare il formato dei comandi e i livelli di rischio per un uso sicuro di SoftAgent.

1. Formato comando: verbo o verbo:arg (argomento segue i due punti), ad es. volume:80 o ping.
2. Risposta successo: ok:<codice>, ad es. ok:pong o ok:volume.
3. Risposta fallimento: err:<codice>, ad es. err:wol.invalidMac.
4. Tre livelli di rischio: Sicuro (nessuna interruzione, ripetibile) / Dirompente (interrompe sessione/processo ma senza perdita dati) / Distruttivo (spegnimento/riavvio/disconnessione ecc.).
5. I comandi distruttivi mostrano una finestra di dialogo di conferma nell'interfaccia. Quando attivati da remoto, il chiamante è responsabile della conferma dell'intento.

• L'invio di ping riceve ok:pong, confermando che la connessione e il formato del comando sono corretti.
• L'invio di describe riceve un elenco JSON di capacità con tutti i comandi supportati e i relativi livelli di rischio.

Il comando describe restituisce l'elenco completo delle capacità di questa istanza SoftAgent, incluso il nome, la descrizione, il livello di rischio e se è richiesta conferma per ogni comando — utile per la scoperta delle capacità durante l'integrazione con SoftControl o sistemi AI.

Padroneggiare i comandi Sicuri per il controllo del volume quotidiano e il monitoraggio dello stato.

1. Sonda di connettività: ping (risponde ok:pong, conferma che l'agente è online).
2. Ottenere l'elenco capacità: describe (restituisce JSON con tutti i comandi con descrizioni e livelli di rischio).
3. Scoperta dispositivi: discover (restituisce un JSON snapshot heartbeat con hostname, IP, MAC, volume, stato guard).
4. Aumentare il volume di un passo: volup (default +5% per chiamata).
5. Diminuire il volume di un passo: voldown (default -5% per chiamata).
6. Attivare/disattivare muto: mute (alternare tra muto e non muto).
7. Ottenere l'indirizzo MAC della NIC primaria: getmac (restituisce formato maiuscolo separato da trattini, ad es. AA-BB-CC-DD-EE-FF).
8. Inviare pacchetto magico Wake-on-LAN: wol:AA-BB-CC-DD-EE-FF (svegliare la macchina con il MAC specificato).
9. Simulazione tastiera: key:^s (Ctrl+S), key:{F5} (tasto F5), key:Ciao (digitare caratteri).

• Il comando ping restituisce ok:pong.
• volup/voldown cambia il volume della macchina controllata.
• Il comando wol sveglia la macchina di destinazione (richiede WoL abilitato sulla destinazione).

• Usare discover per ottenere rapidamente lo stato corrente di una macchina controllata (IP, volume, stato guard) — utile per i controlli di salute batch di SoftControl.
• key: usa la sintassi Microsoft SendKeys: ^ è Ctrl, % è Alt, + è Shift, tasti speciali tra parentesi graffe come {ENTER}.

Padroneggiare blocco schermo, avvio/arresto processi e comandi di annullamento spegnimento.

1. Bloccare lo schermo: lock (blocca la workstation corrente — ri-accedere per ripristinare).
2. Annullare uno spegnimento/riavvio ritardato in sospeso: cancelshutdown (usare durante il conto alla rovescia dello spegnimento).
3. Avviare un elemento watchdog per ID: run:id (ad es. run:db-player avvia l'elemento chiamato db-player).
4. Fermare un elemento watchdog per ID: stop:id (ferma e mette in pausa il watchdog — il processo non verrà riavviato automaticamente).
5. Avviare un programma gestito per indice: startpro:0 (avvia il programma all'indice 0 nell'elenco programmi gestiti).
6. Fermare un programma gestito per indice: killpro:0.
7. Fermare tutti i programmi gestiti: killall.

• Dopo lock, la macchina controllata mostra la schermata di blocco.
• Dopo run:id, l'elemento watchdog corrispondente si avvia — lo stato cambia da Fermato a In esecuzione nella scheda Watchdog.
• cancelshutdown inviato durante un conto alla rovescia di spegnimento annulla lo spegnimento.

• Usare run/stop con l'ID watchdog (un identificatore stabile) piuttosto che startpro/killpro con indice (l'indice cambia quando gli elementi vengono eliminati o riordinati).
• Gli ID watchdog sono configurati nella scheda Watchdog di SoftAgent. Aggiornare i comandi di SoftControl se si rinomina un ID.

Eseguire in modo sicuro operazioni distruttive come spegnimento, riavvio e disconnessione.

1. Spegnimento ritardato (raccomandato): shutdown:60 (spegnimento dopo 60 secondi, cancelshutdown può annullare durante il conto alla rovescia).
2. Spegnimento immediato (usare con cautela): shutdown (nessun ritardo, non può essere annullato).
3. Riavvio ritardato (raccomandato): reboot:60 (riavvio dopo 60 secondi).
4. Riavvio nel BIOS/UEFI: reboot:firmware (richiede supporto firmware UEFI).
5. Disconnettere l'utente corrente: logoff (confermare che non ci siano dati non salvati prima di eseguire).
6. Abilitare/Disabilitare UAC: uac:off / uac:on (modifica registro, richiede riavvio per avere effetto, richiede admin).
7. Abilitare/Disabilitare i gesti sul bordo touchscreen: edgeswipe:off / edgeswipe:on.
8. Abilitare/Disabilitare la riparazione automatica all'avvio di Windows: autorepair:off / autorepair:on.

• Dopo shutdown:60, il sistema mostra una notifica con conto alla rovescia 'spegnimento tra 60 secondi'.
• cancelshutdown inviato durante il conto alla rovescia annulla lo spegnimento.

• Inviare shutdown senza ritardo, rendendo impossibile annullare — la macchina controllata si spegne immediatamente.
• Dopo uac:off, non riavviare e assumere che UAC sia già disabilitato (richiede riavvio per avere effetto).

I comandi di spegnimento richiedono privilegi di amministratore. Se i permessi sono insufficienti, viene restituito un codice di errore chiaro come err:power.denied — nessun fallimento silenzioso.

Completare la configurazione di base affinché SoftAgent possa essere correttamente scoperto e controllato da SoftControl.

1. Aprire la finestra principale di SoftAgent e passare alla scheda Impostazioni.
2. Porta di ascolto (default 6500): SoftControl e altri controller inviano comandi UDP a questa porta.
3. Indirizzo di segnalazione (formato IP:porta): SoftAgent invia heartbeat JSON periodici a questo indirizzo; inserire l'IP e la porta di ascolto di SoftControl.
4. Intervallo heartbeat (secondi): default 10 secondi; gli heartbeat contengono hostname, IP, MAC, volume, stato guard, ecc.
5. Ritardo avvio automatico (secondi): ritardo dopo il login prima che SoftAgent si avvii (utile per aspettare la disponibilità della rete).
6. Fare clic su 'Salva e applica' dopo le modifiche — le modifiche alla porta mostrano un avviso persistente 'Riavvio richiesto'; le altre modifiche hanno effetto immediato.

• La configurazione ha effetto immediato dopo il salvataggio (le modifiche alla porta richiedono riavvio).
• Se è configurato un indirizzo di segnalazione, SoftControl dovrebbe iniziare a ricevere heartbeat JSON periodici da questo SoftAgent.

• Per più PC controllati, si raccomanda di usare la stessa porta (6500) su tutti per semplificare l'inserimento dei comandi batch in SoftControl.
• Lasciare vuoto l'indirizzo di segnalazione significa che SoftAgent non invierà proattivamente heartbeat ma risponderà comunque ai comandi UDP.

Modificare la configurazione IP della macchina controllata tramite l'interfaccia di SoftAgent senza RDP.

1. Aprire la finestra principale, passare alla scheda Proprietà e selezionare la scheda di rete di destinazione nel menu a tendina del pannello di rete.
2. Dopo aver selezionato una NIC, IP corrente, subnet mask, gateway, DNS e indirizzo MAC vengono compilati automaticamente.
3. Alternare la modalità 'IP statico / DHCP': i campi sono modificabili in modalità Statica; di sola lettura in modalità DHCP.
4. Compilare l'IP di destinazione, subnet mask, gateway e DNS (modalità Statica).
5. Fare clic su 'Modifica impostazioni IP' e confermare nella finestra di dialogo di conferma.
6. Il cambio IP è un'operazione distruttiva — la connessione corrente si interrompe dopo la modifica. Riconnettersi con il nuovo IP.

• Dopo la modifica, la macchina controllata può essere raggiunta con ping al nuovo indirizzo IP.
• Il JSON heartbeat di SoftAgent mostra l'indirizzo IP aggiornato.

Il cambio IP è distruttivo. Prima di procedere, confermare che il nuovo IP sia raggiungibile sulla LAN per evitare di perdere l'accesso remoto alla macchina controllata.

Configurare l'avvio automatico affinché SoftAgent riprenda automaticamente l'esecuzione dopo il riavvio del PC controllato.

1. Nella scheda Impostazioni della finestra principale, spuntare 'Avvio automatico'.
2. Fare clic su 'Salva e applica'.
3. Verificare con: schtasks /Query /TN SoftAgent in PowerShell — confermare che l'attività pianificata sia registrata.
4. Trigger attività: ONLOGON (si attiva dopo il login dell'utente) con livello di privilegio HIGHEST.
5. Per impostare un ritardo di avvio (aspettare la rete o servizi dipendenti), impostare i secondi nel campo 'Ritardo avvio automatico'.
6. Per disabilitare l'avvio automatico, deselezionare 'Avvio automatico' e salvare.

• schtasks /Query /TN SoftAgent mostra che l'attività esiste ed è abilitata.
• Dopo il riavvio del PC controllato, SoftAgent appare automaticamente nel vassoio di sistema dopo il login.

Completare la configurazione dei comandi SoftAgent in SoftControl per il controllo basato su pulsanti delle macchine controllate.

1. Accedere al pannello di amministrazione SoftControl e aprire Gestione comandi.
2. Creare un nuovo comando, selezionare il protocollo UDP.
3. Impostare l'indirizzo di destinazione all'IP del PC controllato (ad es. 192.168.1.101).
4. Impostare la porta alla porta di ascolto di SoftAgent (default 6500).
5. Impostare il testo del comando al comando specifico, ad es.: volup (volume su), mute (attiva/disattiva muto), lock (blocca schermo), shutdown:60 (spegnimento tra 60s).
6. Salvare e testare il comando singolarmente — confermare che la macchina controllata risponda correttamente.
7. Associare il comando verificato a un pulsante nell'interfaccia front-end di SoftControl.

• Dopo che SoftControl invia il comando UDP, SoftAgent della macchina controllata esegue l'azione.
• I log di SoftControl mostrano che il comando è stato inviato con successo (risposta OK).

• Creare un set di comandi per ogni macchina controllata, usando il nome del dispositivo come prefisso (ad es. 'Sala-PC-01_Spegnimento') per una facile manutenzione.
• Per operazioni batch come la chiusura dell'esposizione, usare i gruppi di comandi di SoftControl — aggiungere i comandi di spegnimento per più macchine a un gruppo e attivare una volta.

Configurare la segnalazione heartbeat per monitorare lo stato online della macchina controllata da SoftControl.

1. Nelle impostazioni di SoftAgent, configurare l'indirizzo di segnalazione all'IP:porta di SoftControl (interfaccia UDP esterna di SoftControl, default 8818).
2. SoftAgent invia immediatamente un heartbeat all'avvio, poi continua all'intervallo configurato (default 10 secondi).
3. Il JSON heartbeat include: agentId (identificatore univoco dispositivo), hostname, ip/mac (informazioni rete), volume/muted (stato audio), guards (stati processi watchdog), uptimeSeconds.
4. Per interrogare attivamente lo stato corrente di una macchina controllata, inviare discover da SoftControl — SoftAgent restituisce uno snapshot heartbeat.
5. Il campo guards negli heartbeat indica se i processi watchdog sono in esecuzione normalmente, rivelando crash o stati di abbandono.

• SoftControl riceve heartbeat JSON periodici da SoftAgent.
• L'invio di discover riceve una risposta JSON con hostname, IP, volume e altre informazioni.

Configurare il watchdog di riavvio automatico dopo crash per le applicazioni espositive.

1. Aprire la finestra principale di SoftAgent e passare alla scheda Watchdog.
2. Fare clic su 'Sfoglia...' per selezionare l'exe da monitorare, facoltativamente impostare un nome e un ID watchdog (identificatore stabile usato per i comandi run/stop).
3. Fare clic su 'Aggiungi' per metterlo nell'elenco watchdog. Il controllo toggle individuale controlla se il watchdog di questo elemento è abilitato.
4. Il toggle master del watchdog è in cima alla scheda — disabilitarlo mette in pausa tutto il watchdog (sincronizzato con il menu 'Pausa Watchdog' del vassoio).
5. I badge di stato mostrano lo stato di ogni elemento: In esecuzione / Fermato / Crash / Abbandonato (watchdog abbandonato dopo troppi crash nella finestra temporale).
6. Dopo un crash, SoftAgent riavvia con backoff esponenziale (inizialmente 5 secondi, raddoppiando ogni volta; abbandonato dopo il superamento del limite nella finestra temporale).

• Il programma monitorato mostra lo stato 'In esecuzione' nell'elenco watchdog.
• Terminare manualmente il processo monitorato e SoftAgent lo riavvia automaticamente dopo un ritardo.
• Il campo guards nel JSON heartbeat riflette gli ultimi stati watchdog.

Non modificare arbitrariamente l'ID watchdog — i comandi run/stop di SoftControl dipendono da esso. Se rinomini un ID, aggiorna i comandi SoftControl corrispondenti.

Ripristinare il canale di controllo comandi UDP.

1. Confermare che SoftAgent sia visibile nel vassoio di sistema (il processo è in esecuzione).
2. Confermare che la porta di invio corrisponda alla porta di ascolto configurata di SoftAgent (default 6500).
3. Controllare se il Firewall di Windows consente il traffico UDP in entrata sulla porta 6500.
4. Provare prima ping da localhost (127.0.0.1) per escludere problemi di rete, poi provare da remoto.
5. Controllare i file di log in %ProgramData%\SoftAgent\logs\ per i record di ricezione comandi.

• L'invio di ping a 127.0.0.1 riceve ok:pong, confermando che SoftAgent e la porta UDP funzionano.
• L'invio di ping da una macchina remota riceve anche una risposta, confermando che il percorso di rete è libero.

Garantire che SoftAgent venga eseguito con privilegi di amministratore per supportare tutti i comandi a livello di sistema.

1. Confermare che SoftAgent venga eseguito con diritti admin: l'avvio automatico usa l'attività pianificata con privilegio HIGHEST; per l'avvio manuale, fare clic destro sull'exe e 'Esegui come amministratore'.
2. Se i comandi vengono attivati tramite SoftControl, SoftControl stesso non necessita di diritti admin — i privilegi sono determinati da SoftAgent sul lato controllato.
3. Controllare la colonna 'Elevato' per SoftAgent.App.exe nella scheda Dettagli di Task Manager — dovrebbe mostrare 'Sì'.
4. Se non è in esecuzione come admin, uscire da SoftAgent e riavviarlo come amministratore.

• La scheda Dettagli di Task Manager mostra 'Sì' nella colonna Elevato per SoftAgent.App.exe.
• I comandi volup/voldown rispondono normalmente (nessun admin richiesto — utile per la verifica di base).
• Il comando lock blocca lo schermo della macchina controllata (livello Dirompente — conferma che il privilegio è corretto).

Diagnosticare e correggere i fallimenti dell'avvio automatico.

1. Eseguire schtasks /Query /TN SoftAgent in PowerShell per confermare che l'attività pianificata esiste.
2. Se l'attività non esiste, aprire la scheda Impostazioni di SoftAgent, ri-spuntare 'Avvio automatico' e salvare.
3. Confermare che il PC usi il login automatico (comune nelle esposizioni) piuttosto che aspettare il login manuale — il trigger dell'attività è ONLOGON, richiedendo che un utente acceda.
4. Se configurato per il login automatico, confermare che l'account di login automatico abbia i permessi per eseguire l'attività (richiede account amministratore).
5. Controllare i log recenti in %ProgramData%\SoftAgent\logs\ per i motivi del fallimento all'avvio.

• L'output di schtasks /Query /TN SoftAgent contiene trigger ONLOGON e privilegio HIGHEST.
• Dopo il riavvio del PC controllato e il login, SoftAgent appare automaticamente nel vassoio di sistema.

Comprendere perché il watchdog ha abbandonato e ripristinare il monitoraggio dell'applicazione di destinazione.

1. Nella scheda Watchdog della finestra principale di SoftAgent, controllare il badge di stato — conferma lo stato 'Abbandonato'.
2. Controllare i file di log in %ProgramData%\SoftAgent\logs\ per la ragione specifica del crash (errori prima di ogni crash).
3. Correggere la causa radice dei crash dell'applicazione monitorata (errore di configurazione, dipendenza mancante, conflitto porta, ecc.).
4. Dopo la correzione, alternare il toggle individuale dell'elemento watchdog su off poi on nella scheda Watchdog (o inviare run:id da SoftControl) per ri-attivare il watchdog.
5. Confermare che lo stato dell'elemento watchdog cambi in 'In esecuzione' e rimanga stabile nel tempo.

• Dopo aver corretto l'applicazione monitorata, lo stato del watchdog cambia da 'Abbandonato' a 'In esecuzione'.
• Il JSON heartbeat mostra lo stato dell'elemento watchdog corrispondente aggiornato a in esecuzione.

Abbandonato è un comportamento intenzionale per prevenire storm di riavvio infiniti che impattano le risorse di sistema. La soluzione reale è correggere la causa radice del crash — non ri-attivare manualmente il watchdog ripetutamente.