SXXXXXXX_ControlPanel/doc/ARTOS_design.md

Progetto ARTOS: Airborne Radar Test & Orchestration System

Documento di Specifica e Design (Draft v1.0)

1. Introduzione

Il sistema ARTOS ha lo scopo di automatizzare i test di validazione su un'unità radar aeronautica trattata come "Black Box". Il sistema orchestra l'iniezione di scenari (target simulator, comandi 1553) e la cattura sincronizzata delle risposte del radar su molteplici canali trasmissivi (Bus 1553, Video SFP, JSON API).

2. Architettura di Sistema

Il sistema è composto da un core centrale (Collector) e da tre moduli specializzati gestiti come dipendenze esterne.

2.1 Componenti principali

• Collector Core: L'unità logica che gestisce l'esecuzione dei test, la sincronizzazione dei dati e la generazione dei report.
• BusMonitor1553: Modulo per l'interfacciamento con il bus avionico (lettura/scrittura messaggi).
• TargetSimulator: Modulo JSON-based per l'iniezione di target virtuali e la configurazione dello scenario.
• VideoReceiver (SFP): Modulo per la ricezione e il salvataggio del flusso video/immagini dal radar.

2.2 Schema di Comunicazione

Il Collector interagisce con i moduli tramite API Python standardizzate. Ogni modulo deve fornire:

1. Un metodo di inizializzazione e test connessione.
2. Un meccanismo di avvio/arresto cattura.
3. Un flusso di dati in uscita corredato di timestamp nativi (quelli del modulo o dell'hardware).

---

3. Gestione della Sincronizzazione (Time Normalization)

Questa è la funzione critica del Collector. Dato che ogni sorgente ha una propria base temporale, il Collector implementerà un Normalizzatore Temporale:

1. Cattura: Ogni pacchetto dati (1553, Immagine, JSON) viene marcato al momento dell'arrivo con un system_receipt_timestamp.
2. Mapping: Se il pacchetto contiene un timestamp interno (es. il timestamp hardware del bus 1553), il Collector crea una funzione di mapping per correlare il tempo hardware con il tempo di sistema.
3. Allineamento: In fase di analisi, il Collector ricostruisce la sequenza degli eventi ordinando tutti i pacchetti in un'unica timeline coerente, permettendo di verificare, ad esempio, dopo quanti millisecondi dall'iniezione di un target (JSON) esso appare sul bus 1553 o nel video.

---

4. Definizione dell'Interfaccia Moduli (Plugin System)

Ogni modulo (1553, Video, Target Sim) dovrà implementare una classe derivata da un'interfaccia base definita dal Collector. Questo garantisce che il Collector possa comandare i moduli senza conoscerne i dettagli implementativi interni.

Metodi richiesti per ogni modulo:

• initialize(config): Configurazione iniziale (porte, IP, file di log).
• start_session(): Avvio della cattura dati o della simulazione.
• stop_session(): Arresto pulito e chiusura dei file.
• get_status(): Ritorna lo stato di salute del modulo (Link UP/DOWN, etc.).
• get_data_stream(): (Opzionale) Interfaccia per lo streaming dei dati verso il Collector per monitoraggio real-time.

---

5. Strategia di Archiviazione Dati (Data Storage)

Per bilanciare prestazioni e facilità di analisi, ARTOS utilizzerà un sistema Hybrid Storage:

1. Raw Binary Storage: Il flusso video SFP e i log grezzi del 1553 vengono salvati direttamente su disco in formato binario per massimizzare il throughput.
2. Relational Database (SQLite): Il Collector mantiene un database centralizzato dove registra:
   • Eventi di sistema (inizio/fine test).
   • Timestamp e puntatori ai file binari (es: "Frame 100 si trova all'offset X del file Y").
   • Messaggi del bus 1553 decodificati (per ricerche rapide).
   • Esiti degli assert automatici.

---

6. Motore di Test e Validazione

Il Collector eseguirà dei "Test Plan" composti da sequenze di comandi e verifiche.

6.1 Verifiche Automatiche (Deterministic)

Il sistema interroga i dati provenienti dal modulo 1553 e verifica:

• Risposta Temporale: Il tempo intercorso tra un comando e il cambio di stato hardware.
• Integrità Dati: Correttezza dei checksum e dei range di valori sul bus.

6.2 Verifiche Manuali Assistite (Human-in-the-loop)

Per le verifiche visuali (es. forma dei simboli o posizionamento cursore):

1. Il Collector identifica il timestamp dell'evento.
2. Estrae il frame video corrispondente tramite il modulo SFP.
3. Presenta all'operatore l'immagine con un overlay grafico (es. un cerchio rosso dove dovrebbe trovarsi il waypoint).
4. L'operatore conferma il "Pass/Fail".

---

7. Interfaccia Utente (UI) e Visualizzazione

La GUI sarà sviluppata utilizzando Tkinter per garantire massima portabilità e leggerezza.

• Video Panel: Una sezione dedicata alla visualizzazione dei frame ricevuti via SFP.
• Overlay Engine: Utilizzo di OpenCV per il disegno in tempo reale di simboli grafici (waypoint, cursori, target) sopra il flusso video basandosi sulle coordinate estratte dai dati 1553/JSON.
• Control Panel: Pulsanti per avvio/arresto test, selezione scenari e trigger per la validazione manuale.

---

8. Funzionalità Record & Replay

Il sistema supporta la creazione di test tramite "cattura dal vivo":

1. Modalità Recording: L'operatore esegue manovre manuali sul radar. Il Collector registra ogni pacchetto 1553 inviato, ogni target iniettato e lo stato del radar.
2. Sequence File: Viene generato un file di sequenza che descrive gli eventi su una timeline.
3. Modalità Replay: Il Collector legge la sequenza e "riesegue" il test. Se una risposta del radar differisce da quella registrata (oltre una certa tolleranza), il test viene marcato come Failed.

---

Definizione del Codice: L'interfaccia dei Moduli

Iniziamo ora a tradurre questa architettura in codice Python. Come abbiamo discusso, definiamo una Classe Base Astratta che tutti i tuoi moduli (1553, Video, TargetSim) dovranno implementare. Questo è il primo passo per rendere il Collector agnostico rispetto all'hardware.

Userò il modulo abc (Abstract Base Classes) di Python per definire il contratto.

import abc
from datetime import datetime
from typing import Any, Dict, Optional


class BaseModule(abc.ABC):
    """
    Abstract Base Class that defines the mandatory interface for all ARTOS modules.
    Every specialized module (1553, Video, TargetSim) must inherit from this.
    """

    def __init__(self, name: str):
        self.module_name = name
        self.is_running = False

    @abc.abstractmethod
    def initialize(self, config: Dict[str, Any]) -> bool:
        """
        Setup the communication and resources.
        :param config: Dictionary containing IP, ports, or hardware addresses.
        :return: True if initialization is successful, False otherwise.
        """
        pass

    @abc.abstractmethod
    def start_session(self) -> None:
        """
        Starts the data acquisition or simulation.
        """
        self.is_running = True

    @abc.abstractmethod
    def stop_session(self) -> None:
        """
        Stops the module and releases resources.
        """
        self.is_running = False

    @abc.abstractmethod
    def get_status(self) -> Dict[str, Any]:
        """
        Returns the health status of the module.
        :return: A dictionary with status information.
        """
        pass

    def get_system_timestamp(self) -> float:
        """
        Helper to get a uniform system timestamp for data normalization.
        :return: Current system time in seconds (float).
        """
        return datetime.now().timestamp()

Analisi del codice proposto:

1. Perché abc.ABC? Utilizziamo le classi astratte per forzare i moduli futuri ad avere gli stessi metodi. Se provi a istanziare un modulo a cui manca initialize, Python solleverà un errore.
2. initialize: Prende un dizionario di configurazione. Questo ti permette di passare parametri diversi (es. un IP per il video, un indirizzo bus per il 1553) usando la stessa firma.
3. get_system_timestamp: Ho inserito un metodo comune per la normalizzazione temporale. Ogni pacchetto dati catturato dai moduli derivati potrà chiamare questo metodo per avere un riferimento temporale coerente con il PC che ospita il Collector.
4. PEP8: Nomi in inglese, nomi di classi in PascalCase, metodi in snake_case, e docstrings concise.