aggiornati i manuali con le ultime funzionalità introdotte.

doc/manual/02_concetti_fondamentali.md

@@ -42,6 +42,8 @@ Per risolvere questo problema, abbiamo introdotto il concetto di un **sistema di
     b.  La **ruota** e la **trasla** utilizzando i dati dell'origine della simulazione per convertirla in una posizione assoluta nel "mondo".
     c.  Calcola la sua posizione finale **relativa** alla posizione *corrente* dell'ownship per la corretta visualizzazione sulla PPI.
 
+Nota sulla convenzione degli assi: l'allineamento degli assi cartesiani e la convenzione di segno per azimuth/heading seguono la convenzione del server (0° = Nord, angoli positivi in senso antiorario). Eventuali aggiustamenti (ad es. inversione di segno in ingresso) vengono normalizzati dal `ppi_adapter` in fase di trasformazione.
+
 Questo approccio garantisce che le traiettorie simulate si evolvano in un sistema di coordinate stabile e inerziale, mentre l'ownship è libero di muoversi nel mondo come dettato dai dati di navigazione reali.
 
 ### 2.2.3. Dati Simulati vs. Dati Reali

doc/manual/03_interfaccia_principale.md

@@ -17,6 +17,23 @@ La finestra principale è suddivisa in diverse aree funzionali, ciascuna con un
 5.  *Etichetta "5" che punta al **Pannello dei Log** (in basso).*
 6.  *Etichetta "6" che punta alla **Barra di Stato** (in fondo).*
 
+Nota sulla nuova schermata di Profilazione
+
+Nella barra degli strumenti principale è disponibile un collegamento alla nuova finestra `External Profiler / Profiling` (menu `Debug` e voce `External Profiler...` o dalla sezione `Connection`). Questa finestra consente di avviare il profiler esterno che monitora le porte dedicate e di aprire la configurazione dei profili target per assegnarli ai target nel `Trajectory Editor`.
+
+Placeholder immagine - Layout consigliato
+
+*(Placeholder: `panoramica_gui_profiling.png`)*
+
+Suggerimento layout per lo screenshot:
+
+- Area centrale: `PPI Display` (grande) con etichette sovrapposte.
+- Colonna destra: `Pannello di Controllo Scenari` in alto e sotto l'elenco dei profili/strumenti (link rapido a `External Profiler`).
+- Barra superiore: icone di accesso rapido (`Settings`, `Connection`, `External Profiler`).
+- Barra inferiore: indicatori di stato e metriche (latency, pkt/s, uso risorse).
+
+Consiglio: inserire lo screenshot reale dell'app e aggiungere etichette numerate che rimandino alle descrizioni nel manuale. Se preferisci, posso generare un mockup PNG da aggiungere al repository.
+
 ---
 
 ## 3.2. Il PPI Display
@@ -27,6 +44,7 @@ Il Plan Position Indicator (PPI) è il componente visivo centrale dell'applicazi
 *   **Caratteristiche:**
     *   **Griglia Polare:** Mostra anelli di range (in miglia nautiche) e linee di azimut (in gradi).
     *   **Controlli Radar:** Permettono di cambiare il range massimo visualizzato e di attivare/disattivare l'animazione della linea di scansione dell'antenna.
+    *   **Visualizzazione antenna:** L'icona e la linea di scansione dell'antenna possono essere mostrate sul PPI e sono aggiornate in base al `platform azimuth` fornito dallo scenario o dal server. Questo aiuta a verificare l'allineamento della scena rispetto alla direttività radar.
     *   **Modalità di Visualizzazione:** Offre le modalità `North-Up` e `Heading-Up` (vedi Capitolo 2.3 per i dettagli).
     *   **Opzioni di Visualizzazione:** Consente di mostrare/nascondere selettivamente i punti e le tracce (trail) dei target simulati e reali.
     *   **Legenda:** Identifica i simboli grafici per l'ownship, i target simulati e i target reali.

doc/manual/04_gestione_scenari_e_target.md

@@ -9,9 +9,11 @@ La gestione degli scenari avviene tramite il **Pannello di Controllo Scenari** (
 1.  **Creazione:** Si preme il pulsante `New...` e si assegna un nome al nuovo scenario. L'applicazione crea uno scenario vuoto e lo seleziona.
 2.  **Popolamento:** Si aggiungono uno o più target utilizzando il pannello "Editing scenario" (vedi sezione successiva).
 3.  **Salvataggio:** Le modifiche vengono salvate periodicamente tramite il pulsante `Save`. Utilizzando `Save As...` è possibile creare una copia dello scenario corrente con un nuovo nome.
-4.  **Caricamento:** Utilizzando il menu a tendina, è possibile passare da uno scenario all'altro. L'applicazione caricherà la configurazione del target dal file `.json` corrispondente.
+4.  **Caricamento:** Utilizzando il menu a tendina, è possibile passare da uno scenario all'altro. L'applicazione caricherà la configurazione dal file `scenarios.json` (vedi nota sotto).
 
-Tutti gli scenari sono salvati come file `JSON` individuali all'interno di una cartella `scenarios/` situata nella directory principale dell'applicazione.
+Gli scenari sono gestiti centralmente in un file JSON chiamato `scenarios.json` collocato nella directory principale dell'applicazione. La persistenza è gestita dal `ConfigManager` e avviene con scritture atomiche per evitare corruzioni in caso di interruzioni di processo.
+
+Il `ConfigManager` mantiene inoltre backup rotanti (ad es. `scenarios.json.bak1`, `scenarios.json.bak2`, …) in modo da poter recuperare versioni precedenti in caso di necessità. Per compatibilità con versioni precedenti, se `scenarios.json` non è presente viene effettuato un fallback a eventuali definizioni contenute in `settings.json`.
 
 ## 4.2. L'Editor di Traiettoria (`TrajectoryEditorWindow`)
 
@@ -37,6 +39,61 @@ La finestra è divisa in due sezioni:
     *   Un PPI dedicato mostra un'anteprima statica del percorso completo del target.
     *   I controlli di playback (`Play`, `Pause`, `Stop`, `Speed`) permettono di avviare una simulazione visiva della traiettoria per verificarne il comportamento dinamico prima di salvarla. Lo slider sottostante consente di navigare rapidamente lungo la timeline della simulazione.
 
+Profilazione e parametri di target
+
+L'editor dei target è stato esteso per supportare la profilazione per-target: in fase di creazione o modifica di un target è ora possibile definire, oltre ai parametri cinematici, un profilo di caratteristiche che sarà inviato al server e usato nelle viste di debug/analisi.
+
+Campi aggiunti per ciascun target:
+
+- **Nome profilo:** stringa identificativa del profilo del target (es. `F-16_Profile`, `Bird_Small`).
+- **Caratteristiche:** campo libero strutturato (descrizione sintetica dei parametri ad alto livello: tipo piattaforma, firma radar attesa, note operative).
+- **RCS (radar cross section):** valore numerico opzionale che rappresenta la sezione radar attesa del target; può essere inviato periodicamente nel payload JSON quando abilitato.
+- **Amplitude:** campo numerico opzionale che descrive l'ampiezza del ritorno radar e può essere associato a ciascuna misura trasmessa.
+
+Questi campi vengono memorizzati nello `scenarios.json` all'interno della definizione del `target` e, quando il `SimulationEngine` è configurato per trasmettere il payload JSON, i valori di `rcs` e `amplitude` sono inseriti nel payload inviato al device sotto test.
+
+Integrazione con l'Editor dei Waypoint
+
+L'Editor dei Waypoint espone ora la possibilità di assegnare ad uno specifico waypoint modificatori sui valori di `rcs` e `amplitude` (es. cambi di firma radar durante una manovra). Questo permette di simulare variazioni dinamiche delle caratteristiche radar del target lungo la traiettoria.
+
+Visualizzazione e analisi
+
+I valori di `rcs` e `amplitude` sono visibili nella finestra di debug `SFP Packet Inspector` (scheda `RIS` / `Polar` / `JSON`) quando il server o il simulatore li invia; inoltre possono essere registrati nei CSV di debug se abilitato `enable_io_trace`.
+
+Mockup `TrajectoryEditor` con pannello Profiling
+
+*(Placeholder: `editor_traiettoria_profilazione.png`)*
+
+Layout consigliato per la `TrajectoryEditor`:
+
+- Sinistra: **Lista Waypoint e Controlli** (Add/Edit/Remove, ordine sequenza).
+- Centro: **Anteprima Traiettoria (PPI)** con playback e slider timeline.
+- Destra: **Profiling / Characteristics Panel**:
+    - `Profile Name` (input)
+    - `Description` (multi-line)
+    - `RCS (dBsm)` (numeric)
+    - `Amplitude` (numeric)
+    - `Override per Waypoint` (checkbox + link al Waypoint Editor)
+    - `Assign To Target` (dropdown)
+    - `Test Profile` (button)
+
+Esempio di payload JSON (snippet) che potrebbe essere inviato al server quando il protocollo JSON è abilitato:
+
+```json
+{
+    "CMD": "tgtset",
+    "target_id": 3,
+    "timestamp": 1699999999.123,
+    "position": { "x_ft": 12345.6, "y_ft": -2345.1, "z_ft": 15000 },
+    "velocity": { "vx_fps": 400.0, "vy_fps": 0.0 },
+    "rcs": 1.25,
+    "amplitude": 0.87,
+    "profile": "F-16_Profile"
+}
+```
+
+Nota: i nomi dei campi (`rcs`, `amplitude`, `profile`) sono coerenti con le chiavi aspettate dalle viste di debug e dall'archivio; possono variare a seconda dell'implementazione server, pertanto la schermata di Profiling offre un meccanismo di mapping e test per adattarsi a payload differenti.
+
 ## 4.3. L'Editor dei Waypoint e le Manovre (`WaypointEditorWindow`)
 
 Questa è la finestra modale in cui si definiscono i parametri di una singola manovra. Il contenuto della finestra cambia dinamicamente in base al "Tipo di Manovra" selezionato.

doc/manual/05_configurazione_e_connessione.md

@@ -20,6 +20,63 @@ Questa finestra di dialogo, accessibile dal menu `Settings -> Connection...` o d
 
 La finestra permette di configurare in modo indipendente la comunicazione per l'invio dei dati dei target (`Target Connection`) e per un'eventuale comunicazione secondaria con un'altra LRU (`LRU Connection`). Per ogni connessione, è possibile scegliere il tipo di protocollo e impostarne i parametri specifici.
 
+Profilazione target e nuova schermata di configurazione
+
+È stata aggiunta una scheda di configurazione dedicata alla profilazione dei target e alla loro integrazione con la comunicazione verso il server. Questa nuova schermata è accessibile dalla finestra di connessione (`Settings -> Connection...`) o direttamente dall'Editor di Traiettoria tramite un pulsante `Profiling/Characteristics`.
+
+Caratteristiche della schermata di profilazione:
+
+- **Elenco Profili:** mostra i profili disponibili (nome profilo, descrizione breve, ultima modifica) e permette di crearne di nuovi o modificare quelli esistenti.
+- **Assegnazione Target → Profilo:** consente di associare un profilo a un target specifico all'interno dello scenario corrente.
+- **Opzioni di invio:** scegliere se includere i campi `rcs` e `amplitude` nei payload JSON inviati al server, con opzione per invio statico (valore fisso) o dinamico (override da waypoint).
+- **Test profilo:** invia un singolo payload di prova con il profilo selezionato (utilizza lo stesso meccanismo del `Simple Target Sender` nello `SFP Packet Inspector`).
+
+Quando un profilo è assegnato a un target, i relativi campi vengono inclusi nelle operazioni di `tgtinit` / payload JSON (se il protocollo JSON è attivo). L'Editor di Traiettoria mostra uno stato di sincronizzazione che indica se il profilo assegnato è stato inviato correttamente al server.
+
+Placeholder immagine - Scheda Profiling
+
+*(Placeholder: `connection_profiling_tab.png`)*
+
+Layout consigliato per la scheda Profiling nella `ConnectionSettingsWindow`:
+
+- Colonna sinistra: **Elenco Profili** (tabella con colonne `Name`, `Type`, `Last Modified`).
+- Colonna destra superiore: **Dettaglio Profilo** (Name, Description, RCS, Amplitude, Tags).
+- Colonna destra inferiore: **Opzioni di invio** (checkbox `Include in JSON`, `Send dynamic per waypoint`, `Test profile`).
+- Footer: pulsanti `Save Profile`, `Assign to Target`, `Send Test Payload`.
+
+Esempio di configurazione `settings.json` per abilitare IO-trace e profiling:
+
+```json
+{
+	"debug": {
+		"enable_io_trace": true,
+		"io_trace_sent_filename": "sent_positions.csv",
+		"io_trace_received_filename": "received_positions.csv",
+		"temp_folder_name": "Temp",
+		"enable_performance_profiling": true
+	}
+}
+```
+
+Esempio di payload JSON di `tgtinit`/`tgtset` con profilo incluso:
+
+```json
+{
+	"CMD": "tgtinit",
+	"targets": [
+		{
+			"target_id": 3,
+			"profile": {
+				"name": "F-16_Profile",
+				"rcs": 1.25,
+				"amplitude": 0.87,
+				"characteristics": "Fast jet, small RCS"
+			}
+		}
+	]
+}
+```
+
 ## 5.2. Dettaglio dei Protocolli
 
 ### 5.2.1. Configurazione SFP (Simple Fragmentation Protocol)
@@ -31,6 +88,9 @@ SFP è un protocollo basato su UDP progettato per la trasmissione affidabile di
 *   **Local Port:** La porta UDP su cui l'applicazione si metterà in ascolto per ricevere i pacchetti di ritorno (es. ACK SFP o dati reali dal radar). **È fondamentale che questa porta non sia in uso da altre applicazioni sulla macchina.**
 *   **Use JSON Protocol:** Se selezionato, il simulatore invierà gli aggiornamenti dei target utilizzando un payload JSON compatto, invece del formato testuale legacy. Questo è il metodo preferito per i sistemi radar che lo supportano, in quanto più efficiente e strutturato.
 *   **Prediction Offset (ms):** Un valore in millisecondi che introduce una compensazione manuale per la latenza. Il motore di simulazione anticiperà il calcolo della posizione del target di questo intervallo di tempo prima di inviare i dati, per compensare la latenza di rete e di elaborazione del server.
+*   **RCS / Amplitude (opzionali):** Alcune implementazioni SFP supportano l'inclusione di campi `rcs` (radar cross section) e `amplitude` per target singoli. Se il device remoto li riconosce, questi campi vengono inviati nei payload (soprattutto in modalità JSON) e possono essere visualizzati nelle viste di debug.
+*   **Comandi preparatori e reset atomico:** L'implementazione utilizza talvolta comandi preparatori (es. impostazioni di riga terminale) e reset atomici per evitare perdite di messaggi durante la fase di inizializzazione. Ad esempio vengono inviati comandi preparatori prima di effettuare un reset globale dei target e, quando possibile, il reset viene eseguito in modo atomico (evitando sequenze multiple che potrebbero essere perse).
+*   **Nota sulla porta locale:** Quando si usa SFP assicurarsi che la `Local Port` non sia occupata; l'apertura del socket è parte del controllo eseguito da `Test Connection`.
 
 ### 5.2.2. Configurazione TFTP (Trivial File Transfer Protocol)
 

doc/manual/06_esecuzione_simulazione.md

@@ -39,6 +39,12 @@ Premere `Start Live` non avvia semplicemente il movimento dei target. Innesca un
 3.  **Invio dello Scenario Iniziale:** L'intera configurazione dello scenario (posizioni iniziali di tutti i target) viene inviata al sistema radar in un'unica operazione atomica (es. tramite un singolo payload JSON o una sequenza `tgtinit`).
 4.  **Avvio del `SimulationEngine`:** Solo dopo che i passaggi precedenti sono stati completati con successo, viene avviato il thread del `SimulationEngine`. Da questo momento in poi, il motore inizierà a calcolare gli stati successivi dei target e a inviare comandi di aggiornamento (`tgtset` o payload JSON) a intervalli regolari.
 
+Note operative e robustezza del processo di start
+
+*   **Reset atomico e comandi preparatori:** Per ridurre al minimo la possibilità di perdite o condizioni inconsistenti durante l'inizializzazione, l'applicazione può inviare comandi preparatori al device (ad es. impostazioni di riga o parametri) e quindi effettuare un reset atomico delle tracce/target quando supportato dal server. Questo approccio è preferito rispetto all'invio di molteplici comandi singoli che potrebbero essere persi.
+*   **Sincronizzazione orologi e misurazione latenze:** Prima o durante la fase di start possono essere scambiati messaggi di sincronizzazione (SYNC) per stimare il ritardo di comunicazione tra client e server. I valori di latenza stimata vengono poi resi disponibili nelle metriche della sessione e possono essere usati per tarare il `Prediction Offset`.
+*   **Avvio non bloccante:** Il processo di start è stato progettato per non bloccare l'interfaccia grafica. Le operazioni di setup (reset, invio scenario, sincronizzazione) avvengono in background; l'interfaccia rimane reattiva e mostra lo stato di avanzamento fino al momento in cui il motore inizia a riprodurre la simulazione.
+
 Questo processo garantisce che il sistema radar e il simulatore siano allineati allo stesso stato iniziale prima che il movimento dinamico abbia inizio.
 
 ## 6.3. Analisi Post-Simulazione

doc/manual/07_strumenti_di_debug.md

@@ -48,6 +48,14 @@ La finestra è suddivisa in tre aree principali:
     *   `BIN`: Mostrano un dump esadecimale.
     *   `JSON`: Formattano e visualizzano il payload come un albero JSON.
 
+Altre funzionalità di debug SFP
+
+*   **Parsing avanzato degli header:** L'inspector decodifica ora in modo dettagliato l'header SFP campo per campo (inclusi flag, flow ID, TID e altri campi del protocollo) per facilitare l'analisi a basso livello.
+*   **Supporto `ris_status` e campi addizionali:** I payload di tipo RIS possono contenere campi estesi (es. `rcs`, `amplitude`) o messaggi di stato specifici (`ris_status`) che vengono interpretati e visualizzati nella scheda `RIS` quando presenti.
+*   **Raw vs Simplified:** È possibile scegliere fra una vista `raw` (dump esadecimale completo) e una vista `simplified` che mostra i campi più rilevanti in forma tabellare per una lettura rapida.
+*   **Visualizzazione in Coordinate Polari (RIS - Polar):** Nella scheda `RIS` è disponibile anche una vista che mostra i dati dei target in coordinate polari (range, azimut, altitudine). Questa rappresentazione è utile per confrontare rapidamente le misure radar con le coordinate polari usate nella definizione degli scenari.
+*   **IO trace CSV:** Se abilitato (flag di debug in `settings.json` o tramite l'interfaccia di debug), l'applicazione può salvare tracce I/O e latenze in file CSV per analisi esterne. I file CSV di debug vengono creati per default nella cartella `Temp/` a meno di diversa configurazione.
+
 ## 7.2. Pannello Livelli di Log (`LoggerPanel`)
 
 Accessibile da `Debug -> Logger Levels...`, questa finestra permette di controllare dinamicamente, a runtime, il livello di verbosità dei log per ogni singolo modulo dell'applicazione.
@@ -70,4 +78,175 @@ Accessibile da `Debug -> Logger Levels...`, questa finestra permette di controll
     2.  Si seleziona il logger di interesse.
     3.  Si sceglie il livello di log desiderato dal menu a tendina (`DEBUG` per la massima verbosità, `INFO` per il normale funzionamento, `WARNING` o `ERROR` per visualizzare solo i problemi).
     4.  Si preme `Apply`. La modifica ha effetto immediato.
-*   **Persistenza:** Le modifiche ai livelli di log vengono salvate in un file `logger_prefs.json`, in modo da essere mantenute tra un'esecuzione e l'altra dell'applicazione.
+*   **Persistenza:** Le modifiche ai livelli di log vengono salvate in un file `logger_prefs.json`, in modo da essere mantenute tra un'esecuzione e l'altra dell'applicazione.
+
+## 7.3. Profiling e analisi delle prestazioni
+
+L'applicazione include inoltre un sistema di profilazione pensato per analizzare le prestazioni di alcune funzionalità core eseguite continuamente durante la comunicazione con il server (invio/ricezione pacchetti, elaborazione del payload, aggiornamento display). Questo strumento è utile per individuare colli di bottiglia e per validare l'impatto delle ottimizzazioni.
+
+- **Cosa misura:** tempi di round-trip e latenza delle operazioni SFP, durata delle routine di parsing/dispatch, tempi di aggiornamento grafico (es. draw del PPI) e latenza tra messaggi di sincronizzazione (SYNC).
+- **Output:** I dati di profilazione possono essere salvati in formato CSV per analisi esterne. Per convenzione i file di report vengono collocati nella cartella `Temp/` o in una directory configurata dall'utente. I CSV includono timestamp, nome dell'operazione e durata in millisecondi.
+- **Integrazione esterna:** È possibile correlare i report di profilazione con catture packet (PCAP) analizzate con Wireshark per ottenere una visione combinata di traffico di rete e tempi di elaborazione lato applicazione. Alcuni strumenti ausiliari presenti nel repository aiutano a generare marker compatibili con Wireshark.
+- **Come attivarlo:** Il profiling è abilitabile tramite l'interfaccia di debug o tramite un flag di configurazione (es. sezione `debug` in `settings.json`). Quando attivato, l'overhead è minimizzato e i dati vengono raccolti in modo incrementale.
+
+Configurazione e nomi delle impostazioni
+
+*   **Opzioni di debug/IO-trace (chiavi `DEBUG_CONFIG` / `settings.json`):**
+    *   `enable_io_trace` (bool): abilita la scrittura dei CSV con le posizioni inviate e ricevute.
+    *   `io_trace_sent_filename` (string): nome file di default per le posizioni inviate (default: `sent_positions.csv`).
+    *   `io_trace_received_filename` (string): nome file di default per le posizioni ricevute (default: `received_positions.csv`).
+    *   `temp_folder_name` (string): cartella temporanea in cui vengono creati i file CSV prima dello spostamento in `archive_simulations/` (default: `Temp`).
+*   **Profiling delle prestazioni:**
+    *   `enable_performance_profiling` (bool): se `True` il `PayloadRouter` raccoglie campioni di prestazione interni (parse_ms, hub_ms, archive_ms, listener_ms, clock_ms) che vengono poi esportati.
+
+Produzione dei file
+
+*   I file di IO-trace (posizioni inviate / ricevute) sono prodotti nella cartella indicata da `temp_folder_name` (default `Temp`) e hanno i nomi configurati nelle chiavi precedenti.
+*   Al termine della simulazione lo `SimulationArchive` finalizza i file temporanei e li rinomina spostandoli nella cartella `archive_simulations/` con suffissi standard:
+    *   `<timestamp>_<scenario>.trail.csv` — file trail delle posizioni (simulated/real).
+    *   `<timestamp>_<scenario>.latency.csv` — file delle latenze campionate.
+    *   `<timestamp>_<scenario>.perf.csv` — file delle performance (generato se `enable_performance_profiling` era attivo durante la sessione).
+
+Nota: i nomi dei file e la cartella temporanea possono essere personalizzati tramite `settings.json` e `DEBUG_CONFIG`.
+
+Nota: il profiling è pensato per l'uso in ambiente di laboratorio o sviluppo; non è consigliato abilitarlo in scenari di produzione a causa dell'overhead aggiuntivo e della possibile generazione di grandi volumi di dati.
+
+## 7.4. Sync Tool (Strumento di Misura Latenza)
+
+Lo `SyncTool` è uno strumento di debug pensato per misurare e riportare la latenza di rete e delle pipeline applicative tra il simulator e il server radar. Viene usato per raccogliere una serie di campioni temporali correlati tra il client e il server, per calcolare RTT (round-trip time), offset di clock e, quando possibile, la latency unidirezionale stimata.
+
+*(Placeholder per l'immagine)*
+
+**Descrizione dell'Immagine:** `sync_tool.png`
+*Screenshot della finestra `SyncTool` che mostra i controlli di avvio/test, un grafico temporale dei campioni di latenza, una tabella con gli ultimi campioni e i pulsanti di export.*
+
+### Cosa fa
+
+- Invia messaggi di tipo `SYNC` (o un pacchetto di ping custom) al server e attende la risposta.
+- Se il server include un timestamp nel payload di risposta, il tool raccoglie sia il timestamp locale che quello server-side per calcolare il clock offset e stimare la latenza one-way.
+- Calcola RTT per ogni scambio e produce statistiche aggregate (media, mediana, deviazione standard, percentili).
+- Salva un report CSV con tutti i campioni e permette l'esportazione immediata per analisi esterne o per correlazione con catture PCAP.
+
+### Come lo fa (meccanismo e dettagli tecnici)
+
+- Sequenza di test: il tool invia N messaggi `SYNC` numerati (configurabili) a intervalli configurabili (es. 100 ms).
+- Misurazioni raccolte per ciascun pacchetto:
+    - `local_send_ts`: timestamp locale di invio (epoch ms).
+    - `server_ts`: timestamp fornito dal server nella risposta (se disponibile).
+    - `local_recv_ts`: timestamp locale di ricezione (epoch ms).
+    - `seq`: identificatore di sequenza del test.
+    - `rtt_ms`: tempo di andata/ritorno in ms = `local_recv_ts - local_send_ts`.
+    - `clock_offset_ms`: se `server_ts` è presente, offset stimato = `server_ts - (local_send_ts + local_recv_ts)/2`.
+- Calcolo aggregato: il tool calcola media/mediana/std/p95/p99 su `rtt_ms` e fornisce una stima affidabile dell'instabilità di rete durante il test.
+- Correlazione PCAP: il tool può inserire nei log un marcatore (es. `SYNC-SEQ:<seq>`) che facilita la ricerca dei pacchetti corrispondenti in una cattura PCAP con Wireshark.
+
+### Interfaccia (campi principali)
+
+- **Target / Endpoint:** selezione dell'endpoint SFP o del communicator da testare.
+- **Count:** numero di ping da inviare (default 100).
+- **Interval (ms):** intervallo tra i ping (default 100 ms).
+- **Payload size:** dimensione del campo opzionale da inviare (per test di frammentazione).
+- **Start / Stop:** pulsanti per avviare o interrompere il test.
+- **Export CSV:** esporta il report completo in `Temp/` oppure copia in percorso scelto dall'utente.
+- **Grafico:** visualizzazione temporale dei valori RTT e/o offset, utile per individuare jitter o spike.
+
+### Output e formato CSV di esempio
+
+Per comodità il CSV prodotto ha intestazioni chiare; un esempio di riga:
+
+```
+local_send_ts,local_recv_ts,server_ts,seq,rtt_ms,clock_offset_ms
+1700832000000,1700832000105,1700832000008,1,105,8
+1700832000100,1700832000207,1700832000105,2,107,5
+```
+
+Il file per default viene creato nella cartella temporanea (`Temp/`) e, se richiesto, può essere salvato o inserito nell'`archive_simulations/` con un nome del tipo `<timestamp>_sync_latency.csv`.
+
+### Note operative e consigli
+
+- Eseguire il test in condizioni il più possibile ripetibili (stesso network path, poca attività concorrente) per ottenere valori consistenti.
+- Se il server non fornisce timestamp, il tool può comunque misurare RTT ma non può stimare l'offset di clock one-way.
+- Per analisi dettagliate, abbinare il report CSV con una cattura PCAP del test e usare il marcatore `SYNC-SEQ` per correlare i pacchetti.
+- Non abilitare test con payload molto grandi su reti di produzione senza autorizzazione: possono disturbare i dispositivi intermedi (frammentazione, MTU).
+
+### Esempio di uso rapido
+
+1. Selezionare l'endpoint SFP desiderato nella tendina `Target`.
+2. Impostare `Count=200` e `Interval=50` per un test con maggior risoluzione.
+3. Premere `Start` e attendere il completamento.
+4. Esportare il CSV e aprirlo con Excel o uno script Python per analizzare percentili e anomalie.
+
+### Integrazione con gli altri strumenti di debug
+
+- Il `SyncTool` complementa la profilazione interna (`enable_performance_profiling`) fornendo una vista puntuale della latenza di rete end-to-end.
+- I CSV del `SyncTool` possono essere caricati nel `PerformanceAnalysisWindow` per confrontare i tempi di rete con i tempi di elaborazione applicativa.
+
+---
+
+## 7.5. External Profiler (Profiler Esterno)
+
+L'`ExternalProfiler` è uno strumento di debug che permette di inoltrare dati di profilazione e marker temporali verso strumenti esterni (es. Wireshark, strumenti di logging remoti, sistemi di raccolta packet) e di ricevere dati da altri endpoint di profilazione. È pensato per integrare la profilazione applicativa interna con l'analisi a livello di rete e con tool di terze parti.
+
+*(Placeholder per l'immagine)*
+
+**Descrizione dell'Immagine:** `external_profiler.png`
+*Screenshot della finestra `ExternalProfilerWindow` che mostra i campi di configurazione (IP/Port, Protocollo, Enable Forwarding), lo stato della connessione, e pochi campioni in streaming.*
+
+### Concetto e scopo
+
+- **Concetto:** l'`ExternalProfiler` invia (o riceve) pacchetti di profilazione serializzati (tipicamente JSON su UDP/TCP) verso un collector esterno. Questi pacchetti contengono marker temporali, identificatori di sequenza, e talvolta payload con campioni di durata (es. parse_ms, hub_ms, archive_ms) o eventi speciali (es. `SYNC-SEQ`).
+- **Scopo:** permettere la correlazione tra il comportamento interno dell'applicazione (tempi di parsing/dispatch/archive) e il traffico di rete osservabile esternamente; abilitare strumenti di analisi avanzata che non sono integrati nell'app (es. visualizzazione PCAP in Wireshark, aggregatori di metriche, ELK stack).
+
+### Come funziona (flusso)
+
+1. L'utente abilita il forwarding dalla finestra `ExternalProfilerWindow` e configura l'endpoint (IP/porta, protocollo UDP/TCP).
+2. Durante l'esecuzione, il `PayloadRouter` o il `SimulationController` invia pacchetti di profiling all'endpoint configurato; ciascun pacchetto può contenere:
+    - `timestamp` (epoch ms o epoch s + fractional), `seq` (sequenza), `type` (es. `perf_sample`, `sync_marker`), e un payload JSON con i campi di tempo.
+3. L'endpoint esterno riceve i pacchetti e li registra in un file PCAP/PCAPNG (se catturato come traffico di rete) oppure in un sink di logging.
+4. L'utente può poi correlare i CSV `.perf.csv` generati internamente con la cattura PCAP, utilizzando i timestamp/seq presenti in entrambi i flussi.
+
+### Configurazione tipica
+
+- **Protocollo:** UDP (consigliato per basso overhead) o TCP (affidabilità maggiore).
+- **Host / Port:** indirizzo del collector (es. `192.168.1.10:55000`). Il `ExternalProfilerWindow` espone questi campi come input utente.
+- **Forwarding Options:** includere o escludere payload voluminosi, abilitare compressione (se supportata), abilitare marcatore `SYNC-SEQ` per correlazione.
+
+### Strumenti terzi consigliati e come usarli
+
+1) Wireshark (GUI)
+
+- **Cattura:** avviare una cattura sull'interfaccia di rete corretta; se si conosce la porta UDP/TCP del profiler, impostare un capture filter per ridurre il traffico catturato ad es. `udp port 55000`.
+- **Display filter:** per isolare i messaggi del profiler usare ad es. `udp.port == 55000` oppure `frame contains "SYNC-SEQ"` per trovare i marker testuali.
+- **Time display:** impostare `View -> Time Display Format -> Date and Time of Day` o `Seconds Since Beginning of Capture` a seconda del tipo di correlazione che si desidera fare. Per confrontare con CSV epoch, usare `frame.time_epoch` (visibile quando si esportano i campi).
+- **Esportazione timestamp:** `File -> Export Packet Dissections -> As CSV...` e includere il campo `frame.time_epoch` e il campo contenente i dati del payload (es. `data`) per allineare i record con il CSV applicativo.
+- **Ricerca avanzata:** usare `Find Packet` con la stringa `SYNC-SEQ:<seq>` per trovare il pacchetto corrispondente.
+- **Statistiche / Grafici:** `Statistics -> IO Graphs` o `Statistics -> Flow Graph` per visualizzare andamento temporale, spike e ritardi.
+
+2) dumpcap / tshark (CLI)
+
+- Esempio cattura (salva in `sync_capture.pcapng` filtrando per porta UDP):
+
+```powershell
+dumpcap -i 1 -f "udp port 55000" -w sync_capture.pcapng
+```
+
+- Esempio estrazione timestamp e payload (estrarre solo pacchetti contenenti marker):
+
+```powershell
+tshark -r sync_capture.pcapng -Y 'frame contains "SYNC-SEQ"' -T fields -e frame.time_epoch -e data > sync_packets.txt
+```
+
+Nota: sostituire `-i 1` con l'indice dell'interfaccia corretta; sostituire `55000` con la porta configurata.
+
+3) Correlazione automatica
+
+- Una volta ottenuti i due file (CSV interno `.perf.csv` o report `sync_latency.csv` e la cattura PCAP/CSV dei pacchetti), allineare i record usando il campo `frame.time_epoch` (epoch in secondi con frazione). Se i timestamp interni sono in millisecondi dall'epoch, convertirli in secondi (dividere per 1000) oppure convertire i timestamp PCAP in ms.
+- Se i clock non sono sincronizzati, usare i marker di `SYNC-SEQ` per calcolare l'offset tra i due timeline e correggere i valori prima della correlazione.
+
+### Buone pratiche
+
+- Usare UDP per ridurre l'impatto sul timing (meno overhead), ma ricordare che i pacchetti UDP possono andare persi: segnare quindi i `seq` per identificare perdite.
+- Abilitare la compressione o limitare i payload se si cattura su reti con limite di banda.
+- Tenere conto dell'overhead aggiunto dal forwarding: i pacchetti di profilazione dovrebbero essere piccoli e numerosi solo se necessario.
+
+---

doc/manual/08_riferimenti_tecnici.md

@@ -49,13 +49,16 @@ Questo file contiene tutte le impostazioni globali dell'applicazione, esclusi gl
 
 ### 8.1.2. File degli Scenari (`scenarios.json`)
 
-Questo file contiene le definizioni di tutti gli scenari creati dall'utente. È un dizionario JSON in cui ogni chiave è il nome di uno scenario.
+Le definizioni degli scenari dell'utente sono raccolte in un singolo file JSON chiamato `scenarios.json`, organizzato come un dizionario dove ogni chiave è il nome dello scenario.
 
-*   **Ogni scenario** contiene a sua volta una lista di `targets`.
+*   **Ogni scenario** contiene una lista di `targets` e i relativi parametri.
-*   **Ogni target** contiene il suo `target_id` e una lista di `trajectory` (i waypoint).
+*   **Ogni target** contiene il suo `target_id`, flag di stato (`active`, `traceable`, ecc.) e una lista `trajectory` (i waypoint).
-*   **Ogni waypoint** è un oggetto che descrive una manovra con i suoi parametri specifici.
+*   **Ogni waypoint** descrive una manovra con i suoi parametri specifici.
 
-*Esempio di Struttura:*```json
+Il salvataggio e il ripristino degli scenari sono gestiti dal `ConfigManager`: le scritture su `scenarios.json` sono atomiche e vengono mantenuti backup rotanti (`scenarios.json.bak1`, `scenarios.json.bak2`, …) per garantire la resilienza dei dati. In assenza di `scenarios.json` viene effettuato un fallback a eventuali definizioni presenti in `settings.json`.
+
+*Esempio di struttura (semplificata):*
+```json
 {
     "Scen_Virata_Semplice": {
         "name": "Scen_Virata_Semplice",
@@ -65,22 +68,7 @@ Questo file contiene le definizioni di tutti gli scenari creati dall'utente. È
                 "active": true,
                 "traceable": true,
                 "use_spline": false,
-                "trajectory": [
+                "trajectory": [ /* waypoint objects */ ]
-                    {
-                        "maneuver_type": "Fly to Point",
-                        "target_range_nm": 50.0,
-                        "target_azimuth_deg": 45.0,
-                        "target_altitude_ft": 20000.0,
-                        "target_velocity_fps": 843.9,
-                        "target_heading_deg": 270.0
-                    },
-                    {
-                        "maneuver_type": "Dynamic Maneuver",
-                        "duration_s": 20.0,
-                        "lateral_acceleration_g": 2.0,
-                        "turn_direction": "Right"
-                    }
-                ]
             }
         ]
     }
@@ -89,14 +77,22 @@ Questo file contiene le definizioni di tutti gli scenari creati dall'utente. È
 
 ### 8.1.3. File di Archivio Simulazione (`YYYYMMDD_HHMMSS_NomeScenario.json`)
 
-Questi file, salvati nella cartella `archive_simulations/`, contengono un resoconto completo di una singola sessione di simulazione.
+Questi file, salvati nella cartella `archive_simulations/`, contengono un resoconto completo di una singola sessione di simulazione e i dati necessari per l'analisi posteriore.
 
-*   **`metadata`**: Informazioni sulla sessione (timestamp, durata, latenza stimata, etc.).
+*   **`metadata`**: Informazioni sulla sessione (timestamp, durata, latenza stimata, versione del software, informazioni di sincronizzazione clock, ecc.).
+    *   **Nota sui file di output delle metriche e del profiling:** Durante la sessione il sistema può generare diversi file CSV utili per l'analisi:
+        *   `<timestamp>_<scenario>.trail.csv` — file "trail" delle posizioni (simulated/real) finalizzato e spostato nella cartella `archive_simulations/`.
+        *   `<timestamp>_<scenario>.latency.csv` — file delle latenze campionate e finalizzato nella cartella `archive_simulations/`.
+        *   `<timestamp>_<scenario>.perf.csv` — file delle performance (se `enable_performance_profiling` era attivo). Questo file, quando prodotto, viene scritto direttamente nella cartella `archive_simulations/`.
+        
+      Il JSON di archivio (`<timestamp>_<scenario>.json`) contiene i campi `trail_file` e `latency_file` che indicano i nomi dei file finali per trail e latency. Il file `.perf.csv` viene generato se erano presenti campioni di performance raccolti durante l'esecuzione; tuttavia la presenza di un riferimento esplicito a questo file nel blocco `metadata` può variare a seconda della versione. Se non troviate il riferimento nei metadati, verificate la cartella `archive_simulations/` per il file `*.perf.csv` corrispondente.
 *   **`scenario_definition`**: Una copia dello scenario così com'era al momento dell'avvio.
-*   **`ownship_trajectory`**: Una serie di snapshot dello stato dell'ownship durante la simulazione.
+*   **`ownship_trajectory`**: Serie di snapshot dello stato dell'ownship durante la simulazione; contiene anche coordinate geografiche (`lat`, `lon`) quando disponibili.
-*   **`simulation_results`**: Il cuore dei dati. Un dizionario per `target_id` che contiene due liste:
+*   **`simulation_results`**: Dati per `target_id` con due insiemi principali:
-    *   **`simulated`**: La "ground truth" di tutti gli stati `(timestamp, x, y, z)` generati dal `SimulationEngine`.
+    *   **`simulated`**: La "ground truth" (serie di `(timestamp, x, y, z)` o con lat/lon se presente) generata dal `SimulationEngine`.
-    *   **`real`**: Tutti gli stati `(timestamp, x, y, z)` ricevuti dal sistema radar per quel target.
+    *   **`real`**: Gli stati `(timestamp, x, y, z)` ricevuti dal sistema radar per quel target.
+
+Oltre al file JSON di archivio, la sessione può includere riferimenti a file CSV di performance e latenze (es. `latency_<timestamp>.csv`) generati se il flag di debug per l'IO-trace era abilitato. Nei metadati è presente un campo che indica i percorsi ai file CSV prodotti (ad es. `latency_csv_path`, `perf_csv_path`). Questo aiuta ad integrare le analisi numeriche esterne con i dati dell'archivio JSON.
 
 ## 8.2. Glossario