diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md index 4d89474..f034e14 100644 --- a/doc/ARCHITECTURE.md +++ b/doc/ARCHITECTURE.md @@ -307,4 +307,42 @@ Quando si affronta un bug o si sviluppa una nuova funzionalità, si consiglia il * Usa il `Simple Target Sender` per inviare comandi isolati e testare specifiche risposte del sistema radar senza eseguire uno scenario completo. 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. \ No newline at end of file +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 `_.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. diff --git a/doc/manual/04_gestione_scenari_e_target.md b/doc/manual/04_gestione_scenari_e_target.md index b62d0f0..fdf3080 100644 --- a/doc/manual/04_gestione_scenari_e_target.md +++ b/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 diff --git a/doc/manual/05_configurazione_e_connessione.md b/doc/manual/05_configurazione_e_connessione.md index a225652..5f347c8 100644 --- a/doc/manual/05_configurazione_e_connessione.md +++ b/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`). diff --git a/doc/user_guide/02_primo_avvio.md b/doc/user_guide/02_primo_avvio.md index ec99aa6..076e096 100644 --- a/doc/user_guide/02_primo_avvio.md +++ b/doc/user_guide/02_primo_avvio.md @@ -57,4 +57,17 @@ Apparirà un messaggio che ti informerà sull'esito del test: * Problemi di rete (cavi, firewall). * 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. \ No newline at end of file +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. \ No newline at end of file diff --git a/doc/user_guide/03_gestire_scenari.md b/doc/user_guide/03_gestire_scenari.md index b544259..de9e193 100644 --- a/doc/user_guide/03_gestire_scenari.md +++ b/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]() *(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"**. diff --git a/doc/user_guide/04_eseguire_simulazione.md b/doc/user_guide/04_eseguire_simulazione.md index fa2774e..a6c3fd9 100644 --- a/doc/user_guide/04_eseguire_simulazione.md +++ b/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: + +- `_.trail.csv` — trail delle posizioni. +- `_.latency.csv` — campioni di latenza raccolti. +- `_.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. \ No newline at end of file diff --git a/doc/user_guide/05_analizzare_risultati.md b/doc/user_guide/05_analizzare_risultati.md index 6875dd4..aa26c15 100644 --- a/doc/user_guide/05_analizzare_risultati.md +++ b/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.