SXXXXXXX_PyBusMonitor1553/doc/Proposta-Implementazione-ARTOS.md

# Proposta di Implementazione BusMonitor1553 come Modulo ARTOS

## Sommario Esecutivo

Ho analizzato il documento ARTOS_design.md e implementato un'architettura **dual-mode** che permette a PyBusMonitor1553 di operare:
1. **Standalone** (modalità attuale con GUI/CLI) - per sviluppo e test
2. **ARTOS Module** (plugin per il Collector) - per integrazione futura

## Componenti Implementati

### 1. ARTOS Interface Layer (`core/base_module.py`)
```python
class BaseModule(abc.ABC):
    """Contratto standard per tutti i moduli ARTOS"""
    - initialize(config)   # Setup iniziale
    - start_session()      # Avvio acquisizione dati
    - stop_session()       # Arresto e cleanup
    - get_status()         # Health monitoring
```

**Allineamento con ARTOS Design**: Implementa esattamente l'interfaccia definita nel documento di design ARTOS (sezione "Definizione dell'Interfaccia Moduli").

### 2. Business Logic Core (`core/bus_monitor_core.py`)
```python
class BusMonitorCore(BaseModule):
    """Implementazione concreta del monitor 1553"""
    - Gestione connessioni UDP
    - Sistema callback per notifiche real-time
    - Recording/Replay integrato
    - Timestamp normalization
```

**Caratteristiche chiave**:
- ✅ Implementa BaseModule → compatibile ARTOS
- ✅ Mantiene compatibilità con GUI esistente
- ✅ Sistema di callback per test hooks
- ✅ Recording automatico degli eventi

### 3. Recording System (`core/data_recorder.py`)
```python
class DataRecorder:
    """Gestione Record & Replay"""
    - Cattura sequenze di messaggi
    - Salvataggio JSON con timestamp
    - Query temporali per correlazione
    - Filtri per tipo/label
```

**Allineamento con ARTOS Design**: Implementa la funzionalità "Record & Replay" descritta nella sezione 8 del design document.

---

## Architettura Proposta

```
┌────────────────────────────────────────────────────────────────┐
│                  PyBusMonitor1553 (Progetto)                    │
│                                                                  │
│  ┌────────────────────────────────────────────────────────┐   │
│  │           ARTOS BaseModule (Abstract)                  │   │
│  │  • initialize()                                        │   │
│  │  • start_session()                                     │   │
│  │  • stop_session()                                      │   │
│  │  • get_status()                                        │   │
│  │  • get_system_timestamp()  ← Time Normalization       │   │
│  └─────────────────┬──────────────────────────────────────┘   │
│                    │ implements                                │
│  ┌─────────────────▼──────────────────────────────────────┐   │
│  │         BusMonitorCore (Concrete)                      │   │
│  │  • ConnectionManager (UDP 1553)                        │   │
│  │  • DataRecorder (Record & Replay)                      │   │
│  │  • Callback System (Test Hooks)                        │   │
│  │  • Event Queue (Real-time notifications)               │   │
│  └─────────────────┬──────────────────────────────────────┘   │
│                    │                                           │
│           ┌────────┴─────────┐                                │
│           │                  │                                │
│  ┌────────▼───────┐  ┌───────▼─────────┐                     │
│  │  Tkinter GUI   │  │ ARTOS Collector │                     │
│  │  (Standalone)  │  │   (External)    │                     │
│  └────────────────┘  └─────────────────┘                     │
│                                                                │
│  Development Mode      Production Mode                         │
└────────────────────────────────────────────────────────────────┘
```

---

## Vantaggi dell'Approccio

### ✅ Dual-Mode Operation
- **Sviluppo**: Usa GUI locale per testare e debuggare
- **Produzione**: ARTOS Collector importa come modulo Python standard
- **Zero modifiche**: Stesso codice funziona in entrambi i contesti

### ✅ Time Normalization (Sincronizzazione)
Ogni evento catturato include:
```json
{
  "timestamp": 1703257822.123456,      // System time (Collector reference)
  "hw_timestamp": 0.123456,            // Hardware timestamp (se disponibile)
  "event_type": "msg_received",
  "label": "msg_a2",
  "data": { ... }
}
```

Il Collector può:
- Correlare eventi da BusMonitor + VideoReceiver + TargetSim
- Calcolare latenze end-to-end
- Rilevare anomalie temporali

### ✅ Test Automation Ready
```python
# Example: ARTOS Collector test routine
bus_monitor.register_callback("msg_a2", validate_radar_mode)
bus_monitor.start_session()

if not bus_monitor.wait_for_message("msg_b1", timeout=5.0):
    test_result.add_failure("Target not detected within 5s")
```

### ✅ Deterministic Testing
- Record live session → baseline file
- Replay in CI/CD pipeline
- Automated regression detection

---

## Workflow di Utilizzo

### Fase 1: Sviluppo Standalone (ORA)
```bash
# Current workflow - UNCHANGED
python -m pybusmonitor1553        # GUI mode
python -m pybusmonitor1553 --cli  # CLI mode
```

La GUI usa internamente `BusMonitorCore` ma con interfaccia locale Tkinter.

### Fase 2: Testing con Recording
```python
from pybusmonitor1553.core import BusMonitorCore

monitor = BusMonitorCore()
monitor.initialize({'ip': '127.0.0.1', 'send_port': 5001, 'recv_port': 5002})

# Record a test session
monitor.start_recording(filepath=Path("recordings/baseline.json"))
monitor.start_session()
# ... perform manual tests ...
monitor.stop_recording(save=True)
monitor.stop_session()
```

### Fase 3: Integrazione ARTOS (FUTURO)
```python
# In ARTOS Collector project
from pybusmonitor1553.core import BusMonitorCore

class ARTOSCollector:
    def __init__(self):
        # BusMonitor as a plugin module
        self.bus_monitor = BusMonitorCore()
        
    def run_test(self, scenario):
        # ARTOS orchestrates the test
        self.bus_monitor.initialize(scenario.bus_config)
        self.bus_monitor.register_callback("msg_a2", self.validate_radar_mode)
        self.bus_monitor.start_session()
        
        # Inject target via TargetSimulator
        self.target_sim.inject_target(scenario.target_data)
        
        # Wait for radar response on bus
        if self.bus_monitor.wait_for_message("msg_b1", timeout=5.0):
            self.test_passed()
        else:
            self.test_failed("No radar response")
```

---

## File Creati/Modificati

### Nuovi File
1. **`pybusmonitor1553/core/base_module.py`**
   - Classe astratta BaseModule (interfaccia ARTOS)
   - ~100 righe, docstring completa

2. **`pybusmonitor1553/core/data_recorder.py`**
   - Sistema recording/replay
   - Serializzazione JSON
   - Query temporali
   - ~180 righe

3. **`examples/artos_integration_example.py`**
   - Esempio completo di utilizzo ARTOS
   - Workflow: init → callbacks → recording → replay
   - ~150 righe

4. **`doc/ARTOS-Integration-Guide.md`**
   - Documentazione completa dell'integrazione
   - Diagrammi architetturali
   - Esempi di codice
   - ~400 righe

### File Modificati
1. **`pybusmonitor1553/core/bus_monitor_core.py`**
   - Esteso per implementare BaseModule
   - Aggiunto sistema callback
   - Integrato DataRecorder
   - Metodi recording/replay

2. **`pybusmonitor1553/core/__init__.py`**
   - Export delle classi ARTOS-ready

---

## Prossimi Passi Consigliati

### Short-term (Per completare il modulo standalone)
1. **Collegare MessageDB**
   - Implementare `get_message()` completo
   - Integrare notifiche nel dispatcher esistente
   - Test end-to-end con messaggi reali

2. **Test del Recording**
   - Catturare una sessione live
   - Verificare formato JSON
   - Testare replay

### Mid-term (Preparazione ARTOS)
1. **Documentazione API**
   - Docstring complete per tutti i metodi pubblici
   - Type hints rigorosi
   - Esempi d'uso

2. **Test Suite**
   - Unit test per BaseModule compliance
   - Integration test con ConnectionManager
   - Recording/Replay validation

### Long-term (Quando ARTOS sarà pronto)
1. **Packaging**
   - Setup.py configurato per installazione come libreria
   - Dependencies separate (GUI optional)
   - Versioning semantico

2. **CI/CD**
   - Test automatici con recordings baseline
   - Regression detection
   - Performance benchmarks

---

## Domande & Decisioni Aperte

### 1. MessageDB Integration
**Domanda**: Come vuoi integrare il `MessageDB` esistente con il nuovo core?

**Opzioni**:
- A) MessageDB rimane globale, BusMonitorCore vi accede direttamente
- B) MessageDB diventa attributo di BusMonitorCore (incapsulato)
- C) MessageDB viene refactorato in DataRecorder

**Consiglio**: Opzione B per massima modularità ARTOS.

### 2. Timestamp Source
**Domanda**: I messaggi 1553 hanno già un timestamp hardware?

**Se sì**: Il DataRecorder può usarlo per correlazione precisa
**Se no**: Useremo solo system_receipt_timestamp (sufficiente per la maggior parte dei test)

### 3. GUI Refactoring
**Domanda**: Vuoi refactorare la GUI esistente per usare BusMonitorCore direttamente?

**Vantaggi**:
- Un solo code path (stesso core per GUI e ARTOS)
- Facilita testing (GUI testa automaticamente il core)
- Meno duplicazione

**Svantaggi**:
- Richiede modifiche alla GUI esistente
- Potenziali regressioni temporanee

**Consiglio**: Fallo gradualmente, mantenendo la GUI legacy funzionante finché il core non è stabile.

---

## Conclusioni

L'architettura proposta soddisfa tutti i requisiti ARTOS:

✅ **Interfaccia standardizzata** (BaseModule)  
✅ **Time Normalization** (dual timestamp system)  
✅ **Record & Replay** (DataRecorder)  
✅ **Health Monitoring** (get_status())  
✅ **Test Hooks** (callback system)  

Allo stesso tempo, mantiene il progetto pienamente utilizzabile come tool standalone per lo sviluppo e il testing.

**La strategia è: sviluppare e perfezionare qui, distribuire come modulo ARTOS quando pronto.**

Dimmi cosa ne pensi e su cosa vuoi che ci concentriamo prima!