aggiornata user_guide e architecture

doc/ARCHITECTURE.md

@@ -308,3 +308,41 @@ Quando si affronta un bug o si sviluppa una nuova funzionalità, si consiglia il
 4.  **Ispezionare lo `SimulationStateHub`:** Se c'è una discrepanza tra ciò che il motore dovrebbe calcolare e ciò che la GUI mostra, il problema è probabilmente nel `ppi_adapter`. Se i dati nello `Hub` stesso sono sbagliati, il problema è a monte (nel `SimulationEngine` o nel `DebugPayloadRouter`).
 
 Seguendo questi principi e utilizzando gli strumenti forniti, la manutenzione e l'estensione dell'applicazione dovrebbero risultare più semplici e strutturate.
+
+---
+
+## 6. Recent Changes (Nov 2025) — aggiornamenti architetturali e punti d'interesse
+
+Negli ultimi aggiornamenti del codice sono state introdotte alcune modifiche significative nella struttura e nei punti di estensione del progetto. Qui di seguito sono riepilogati i cambiamenti più rilevanti che gli sviluppatori/maintainer devono conoscere e che sono stati riflessi nella documentazione utente e tecnica.
+
+- **Target types / profiles centralizzati:** è stato introdotto il file `target_types.json` (gestito da `target_simulator/utils/target_type_manager.py`) che contiene la libreria condivisa di profili target (es. `F-16`, `B-747`). I singoli target nello `scenarios.json` fanno ora riferimento a questi profili per nome e possono applicare sovrascritture locali (es. `rcs`, `amplitude`). Questo migliora la riusabilità e il versioning dei profili.
+
+- **Persistenza scenari:** la persistenza degli scenari è gestita centralmente da `ConfigManager` con un file `scenarios.json` e scritture atomiche + backup rotativi. Nota: i profili predefiniti rimangono in `target_types.json`, mentre le assegnazioni e sovrascritture sono nel `scenarios.json`.
+
+- **Profiling delle prestazioni interno:** il `DebugPayloadRouter` e i componenti correlati raccolgono ora campioni di performance (es. `parse_ms`, `hub_ms`, `archive_ms`, `listener_ms`, `clock_ms`) quando la flag di debug `enable_performance_profiling` è attiva. I campioni vengono memorizzati in memoria e, se presenti, esportati come file `<timestamp>_<scenario>.perf.csv` nell'archivio della simulazione (`archive_simulations/`).
+
+- **IO-trace e CSV:** la scrittura asincrona delle tracce I/O (posizioni inviate/ricevute) è gestita da `target_simulator/utils/csv_logger.py`. I file temporanei sono creati nella cartella indicata da `temp_folder_name` (default `Temp/`) e poi finalizzati e spostati in `archive_simulations/` con suffissi standard (`.trail.csv`, `.latency.csv`).
+
+- **Sync Tool & External Profiler:** introdotte nuove funzionalità di debug esterne:
+    - `Sync Tool`: tool che invia messaggi `SYNC` al server per misurare RTT, offset di clock e generare report CSV di latenza (`*_sync_latency.csv`).
+    - `External Profiler`: componente che forwarda pacchetti di profilazione verso collector esterni (UDP/TCP) per permettere correlazioni tra eventi applicativi e catture di rete (PCAP). Questi strumenti sono integrati nella GUI (`SfpDebugWindow`, `ExternalProfilerWindow`) e nel flusso di logging/profiling.
+
+- **Reset atomico e comandi preparatori:** il meccanismo di avvio simulazione (`SimulationController`) invia ora reset atomici quando possibile (payload JSON unico) evitando sequenze multiple di comandi che potrebbero essere perse; quando il reset atomico non è supportato dal device, il controller applica fallback compatibili per garantire coerenza di stato.
+
+- **Mapping dei campi di profilazione nel payload JSON:** i payload `tgtinit`/`tgtset` includono ora campi opzionali come `profile`, `rcs` e `amplitude` quando la modalità JSON è abilitata. La GUI offre una schermata di Profiling/Characteristics che permette di mappare i campi di profilo e testare l'invio di payload di prova.
+
+- **Archiviazione performance e correlazione con PCAP:** oltre ai CSV interni la piattaforma suggerisce di catturare il traffico di rete (Wireshark / dumpcap / tshark) durante i test e di usare marker (`SYNC-SEQ`, campi `seq`) per facilitare la correlazione tra CSV applicativi e PCAP. I file PCAP possono essere esportati e analizzati con `tshark` per estrarre timestamp e payload utili alla correlazione.
+
+Questi cambiamenti sono stati progettati per mantenere la compatibilità con le installazioni esistenti, offrendo però strumenti più robusti per la profilazione, la diagnostica e la condivisione dei profili target.
+
+---
+
+## 7. Note finali per i Maintainer
+
+Quando si modifica il formato del payload JSON o si aggiungono nuovi campi di profilazione, assicurarsi di:
+
+1.  Aggiornare i test unitari e l'eventuale integrazione che verifica la serializzazione dei payload (es. `tests/` che controllano `tgtinit`/`tgtset`).
+2.  Aggiornare il manuale utente (`doc/manual`) e la user guide (`doc/user_guide`) con esempi di payload e screenshot della UI.
+3.  Verificare la retrocompatibilità verso `target_types.json`/`scenarios.json` e fornire procedure di migrazione se necessario.
+
+Per domande o chiarimenti sull'architettura attuale, contatta il team di sviluppo principale o apri un issue nel repository.

doc/manual/04_gestione_scenari_e_target.md

@@ -50,7 +50,9 @@ Campi aggiunti per ciascun target:
 - **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.
+Il `profile` (riferimento per nome) e le eventuali sovrascritture di `rcs`/`amplitude` vengono memorizzate nella definizione del `target` all'interno di `scenarios.json`. Le definizioni centralizzate dei profili (valori predefiniti di `rcs`, `amplitude`, descrizioni) sono invece conservate nel file `target_types.json`, gestito dal `TargetTypeManager`.
+
+Quando il `SimulationEngine` è configurato per trasmettere il payload JSON, il `SimulationController` espande il riferimento al profilo applicando i valori predefiniti dal `target_types.json` e sovrascrivendo i campi con gli eventuali valori specifici del target o del waypoint; i valori risultanti (`rcs`, `amplitude`, ecc.) sono poi inseriti nel payload inviato al device sotto test.
 
 Integrazione con l'Editor dei Waypoint
 

doc/manual/05_configurazione_e_connessione.md

@@ -27,6 +27,7 @@ Profilazione target e nuova schermata di configurazione
 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.
+- **Elenco Profili:** mostra i profili disponibili (nome profilo, descrizione breve, ultima modifica) e permette di crearne di nuovi o modificare quelli esistenti. Le definizioni di questi profili sono persistite nel file `target_types.json` (gestito da `TargetTypeManager`) mentre l'assegnazione del profilo a singoli target è memorizzata nello `scenarios.json`.
 - **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`).

doc/user_guide/02_primo_avvio.md

@@ -58,3 +58,16 @@ Apparirà un messaggio che ti informerà sull'esito del test:
     *   La porta locale (per SFP) è già usata da un altro programma.
 
 Una volta che il test ha successo, sei pronto per connetterti e lanciare la tua prima simulazione. Per farlo, premi il pulsante `Connect` nel Pannello di Connessione della finestra principale. L'indicatore di stato "Target" dovrebbe diventare verde.
+
+## 2.3. Opzioni di Debug e Cartelle di Output
+
+Prima di eseguire test di carico o profiling, controlla il file `settings.json` per le opzioni di debug. Le chiavi principali sono:
+
+- `enable_io_trace` (bool): abilita la scrittura dei CSV con le posizioni inviate e ricevute.
+- `io_trace_sent_filename` / `io_trace_received_filename` (string): nomi di file di default per i CSV di I/O.
+- `enable_performance_profiling` (bool): abilita la raccolta interna dei campioni di performance (parse_ms, hub_ms, ecc.).
+- `temp_folder_name` (string): cartella temporanea usata per i file prima della finalizzazione (default `Temp`).
+
+I file temporanei vengono creati nella cartella indicata da `temp_folder_name` e, al termine della simulazione, vengono spostati nella cartella `archive_simulations/` con nomi che includono timestamp e nome dello scenario.
+
+Se prevedi di usare l'`External Profiler` o lo `Sync Tool`, assicurati di avere privilegi per aprire le porte di rete che userai e, quando necessario, di avere Wireshark/dumpcap installati per la correlazione dei pacchetti.

doc/user_guide/03_gestire_scenari.md

@@ -6,6 +6,10 @@ Uno "scenario" è il file che contiene tutti i target e le loro traiettorie per
 
 Tutti i controlli per la gestione dei file si trovano nel **Pannello di Controllo Scenari** in alto a destra.
 
+> Nota importante: a partire dalle ultime versioni, gli scenari non sono più salvati come singoli file sparsi nella cartella del progetto. Tutti gli scenari sono conservati in un file centrale chiamato `scenarios.json` nella root del progetto. Le operazioni di salvataggio sono atomiche e il sistema mantiene più backup rotativi (es. `scenarios.json.bak1`, `scenarios.json.bak2`) per prevenire perdita di dati in caso di interruzioni.
+
+Se necessario, l'interfaccia offre la possibilità di esportare un singolo scenario in un file JSON separato (funzione `Export`) e di importare scenari da file esterni (`Import`). Queste funzioni creano o leggono file JSON di scenario standalone ma non cambiano il comportamento predefinito di `Save` che aggiorna `scenarios.json`.
+
 ![Pannello di Controllo Scenari](<percorso/relativo/a/pannello_scenari.png>)
 *(Nota: Qui puoi usare un crop dello screenshot principale che mostra solo il pannello "Scenario Controls")*
 
@@ -20,6 +24,63 @@ Tutti i controlli per la gestione dei file si trovano nel **Pannello di Controll
     1.  Carica lo scenario che vuoi cancellare usando il menu a tendina.
     2.  Clicca `Delete` e conferma l'operazione.
 
+## 3.4. Esportare / Importare scenari
+
+Se devi condividere uno scenario con un collega o mantenerne una copia separata, usa i comandi `Export` e `Import` dal `Pannello di Controllo Scenari`:
+
+- **Export:** salva il singolo scenario selezionato in un file JSON indipendente.
+- **Import:** carica un file JSON di scenario esterno e lo aggiunge (o lo sovrascrive) all'elenco interno gestito in `scenarios.json`.
+
+Questi file esportati seguono la stessa struttura JSON usata internamente (target list, traiettorie, parametri di profilazione per target quando presenti).
+
+## 3.5. Profili Target (Target Profiles)
+
+L'applicazione supporta profili target riutilizzabili che permettono di definire proprietà fisiche e di presentazione di un target (es. `rcs`, `amplitude`, `description`, `profile_name`) e di applicarli ai target nello scenario. Questo semplifica la gestione di insiemi di target con caratteristiche simili e garantisce coerenza nell'invio dei payload al server.
+
+### Dove si gestiscono
+
+- I profili possono essere creati e modificati dall'**Editor di Traiettoria** quando si crea o si modifica un target:
+    - Nella scheda `Profile` dell'editor è possibile: creare un nuovo profilo, selezionarne uno esistente o applicare un profilo al target corrente.
+    - I campi tipici sono: `Profile Name`, `Description`, `RCS (m^2)`, `Amplitude` (unità interne), e campi opzionali per metadata.
+
+In alternativa, le definizioni dei profili sono persistite centralmente nel file `target_types.json` (vedi `target_simulator/utils/target_type_manager.py`). Il gestore dei profili (`TargetTypeManager`) mantiene una libreria riutilizzabile di profili (es. `F-16`, `B-747`) che possono essere assegnati ai target per nome.
+
+### Come si usano nelle traiettorie e nei payload
+
+- Quando un target è associato a un `profile` (riferito per nome), il `SimulationController` usa i valori del profilo come predefiniti durante la generazione dei payload inviati al server. È comunque possibile sovrascrivere singoli campi (ad es. `rcs` o `amplitude`) a livello di target o di singolo waypoint; tali sovrascritture sono memorizzate nella definizione del target dentro `scenarios.json`.
+- Al momento dell'invio dello scenario (`Start Live` o `Send Init`), il `SimulationController` espande il riferimento al profilo applicando i valori ereditati e le eventuali sovrascritture, e include i campi di profilazione pertinenti nei payload JSON inviati al server (es. `tgtinit`/`tgtset`).
+
+### Esempio: profili in `target_types.json` e target che li referenzia
+
+Esempio di estratto da `target_types.json` (file centralizzato dei profili):
+
+```json
+{
+    "F-16": { "rcs": 5.0, "amplitude": 100.0, "notes": "Fighter jet" },
+    "B-747": { "rcs": 100.0, "amplitude": 500.0 }
+}
+```
+
+Esempio di target nello scenario che fa riferimento a un profilo per nome (memorizzato in `scenarios.json` come parte della definizione del target):
+
+```json
+{
+    "id": 101,
+    "label": "TGT-101",
+    "profile": "F-16",
+    "rcs": 0.9,            // valore sovrascritto a livello target (opzionale)
+    "trajectory": [ /* waypoints... */ ]
+}
+```
+
+Nel caso precedente il sistema applicherà i valori dal profilo `F-16` al target `TGT-101` ma userà `rcs=0.9` perché il valore è stato sovrascritto per quel target.
+
+### Consigli pratici
+
+- Definire profili standard (es. `small_plane`, `helicopter`, `drone`, `ship`) e riutilizzarli per i target simili.
+- Usare la funzione `Export` per condividere profili con colleghi o per conservarne una copia di backup.
+- Quando si sospetta un problema di correlazione tra target simulati e tracciati, verificare che il `rcs` e l'`amplitude` applicati siano quelli attesi (controllare la scheda `Profile` nell'Editor di Traiettoria e il payload JSON inviato dal `SfpDebugWindow`).
+
 ## 3.2. Aggiungere e Modificare un Target
 
 Una volta caricato o creato uno scenario, puoi popolarlo con i target nella scheda **"Editing scenario"**.

doc/user_guide/04_eseguire_simulazione.md

@@ -19,9 +19,12 @@ Il processo per eseguire una simulazione è semplice e si svolge principalmente
 
 4.  **Avvia la Simulazione:**
     *   Clicca sul pulsante `Start Live`.
-    *   L'applicazione eseguirà automaticamente un reset del radar per garantire una partenza pulita, invierà le posizioni iniziali dei target e poi avvierà la simulazione.
+    *   L'applicazione eseguirà automaticamente un reset del radar per garantire una partenza pulita, invierà le posizioni iniziali dei target e poi avvierà la simulazione. Il reset viene inviato tramite il comando JSON atomico quando possibile, con fallback a comandi legacy per compatibilità.
+    *   Prima di avviare una sessione di prova, è consigliabile eseguire lo `Sync Tool` (menu `Debug -> Sync Tool`) per misurare la latenza di rete e verificare che i tempi riscontrati siano compatibili con il tuo scenario di test.
     *   Il pulsante `Start Live` diventerà grigio e il pulsante `Stop Live` diventerà attivo. Il messaggio nella barra di stato cambierà in "Simulation running".
 
+    Nota sui Profili Target: prima dell'invio lo `SimulationController` espande i profili associati ai singoli target e integra i valori (es. `rcs`, `amplitude`) nei payload `tgtinit`/`tgtset` inviati al server. Eventuali sovrascritture definite a livello target o waypoint vengono applicate al momento della generazione del payload.
+
 5.  **Termina la Simulazione:**
     *   La simulazione si fermerà da sola quando tutti i target avranno completato la loro traiettoria.
     *   Per fermarla manualmente in qualsiasi momento, clicca sul pulsante `Stop Live`.
@@ -46,6 +49,14 @@ Mentre la simulazione è in corso, hai diversi strumenti per monitorarne l'andam
 
 *   **Barra di Stato:** Tieni d'occhio:
     *   **Rate (pkt/s, ev/s):** Indica quanti dati stai ricevendo dal radar. Se questo valore è a zero, significa che il radar non sta inviando dati di traccia.
-    *   **Latency (ms):** Stima il ritardo di comunicazione tra il radar e il simulatore.
+    *   **Latency (ms):** Stima il ritardo di comunicazione tra il radar e il simulatore. Per misure più accurate, usare lo `Sync Tool` e/o l'`External Profiler` (vedi `Debug -> External Profiler`).
+
+**Output di archivio:** Al termine della simulazione, i file di tracing vengono prodotti nella cartella temporanea (`Temp/`) e poi spostati in `archive_simulations/` con i seguenti suffissi:
+
+- `<timestamp>_<scenario>.trail.csv` — trail delle posizioni.
+- `<timestamp>_<scenario>.latency.csv` — campioni di latenza raccolti.
+- `<timestamp>_<scenario>.perf.csv` — dati di performance (presente solo se `enable_performance_profiling` era attivo).
+
+Queste impostazioni possono essere controllate da `settings.json` (chiavi di debug `enable_io_trace`, `enable_performance_profiling`, `temp_folder_name`).
 
 *   **Pannello dei Log:** Controlla quest'area per eventuali messaggi di errore (in rosso) che potrebbero indicare problemi durante la simulazione.

doc/user_guide/05_analizzare_risultati.md

@@ -17,6 +17,15 @@ Al termine di ogni simulazione, l'applicazione salva automaticamente un "archivi
 
     Si aprirà la finestra **Analysis Window**, che mostra un'analisi dettagliata della performance.
 
+### 5.1.1. Caricare file di profilazione e sincronizzazione
+
+L'`Analysis Window` permette ora di caricare non solo i file di trail/latency ma anche i file di performance generati dal sistema di profilazione (`.perf.csv`) e i report prodotti dallo `Sync Tool` (`*_sync_latency.csv`).
+
+- **Caricare un `.perf.csv`:** usa il pulsante `Load Performance File` nella finestra di analisi. Il grafico comparativo mostrerà i tempi di parsing, hub update e altri campioni raccolti durante la sessione.
+- **Caricare un report di Sync:** usa `Load Sync Report` per visualizzare il grafico RTT/offset e confrontarlo con i picchi di errore nel tracciamento.
+
+Puoi anche caricare la cattura PCAP correlata (generata con Wireshark/dumpcap) per correlare pacchetti di rete con gli eventi applicativi usando i marker `SYNC-SEQ` o i campi `seq` presenti nei pacchetti di profiler esterni.
+
 ## 5.2. Leggere le Statistiche di Errore
 
 La finestra di analisi ti permette di valutare quantitativamente quanto bene il tuo sistema radar ha tracciato i target simulati.