# Refactor dei Messaggi 1553 - Documentazione

## 📋 Sommario delle Modifiche

È stato completato un refactor completo del sistema di messaggi 1553 per utilizzare le definizioni corrette e verificate da `pybusmonitor1553`.

## 🎯 Obiettivi Raggiunti

1. ✅ **Strutture Corrette**: I messaggi ora utilizzano le strutture `ctypes` gerarchiche corrette con bitfield
2. ✅ **Mapping Completo**: Creato sistema di mappatura tra nomi flat legacy e percorsi nested reali
3. ✅ **Compatibilità Retroattiva**: L'API legacy (`get_value_for_field`, `set_value_for_field`) funziona senza modifiche alla GUI
4. ✅ **Verifica Funzionale**: Tutti i test di integrazione passano

## 📁 File Modificati/Creati

### File Principali

1. **`pymsc/core/message_definitions.py`** (sostituito)
   - Usa strutture da `PyBusMonitor1553/Grifo_E_1553lib/messages/`
   - Implementa classe base `Msg1553Base` con supporto campi nested
   - Mantiene API legacy per compatibilità

2. **`pymsc/core/field_mappings.py`** (nuovo)
   - Dizionari di mappatura per tutti i messaggi (A1-A5, B6-B7, B9-B10)
   - Funzione `get_field_path(message_id, legacy_name)` per conversione automatica
   - Singola fonte di verità per i percorsi dei campi

### File di Backup

- **`pymsc/core/message_definitions_old_backup.py`**: backup della versione precedente

## 🔑 Mappature Chiave

### Messaggio A2 (Radar Operation Command)

| Nome Legacy | Percorso Reale |
|-------------|----------------|
| `stby` | `rdr_mode_command.stby` |
| `freeze` | `rdr_mode_command.freeze` |
| `silence` | `rdr_mode_command.silence` |
| `IBIT` | `rdr_mode_command.ibit` |
| `rdr_mode_command` | `rdr_mode_command.master_mode` |
| `des_ctrl` | `rdr_mode_command.des_ctrl` |
| `range_scale` | `param1.range_scale` |
| `velocity_scale` | `param1.velocity_scale` |
| `scan_width` | `param1.scan_width` |
| `bars` | `param1.bars_num` |
| `rws_submode_command` | `param1.rws_submode` |
| `acm_submode_command` | `param1.acm_submode` |
| `gm_submode_command` | `param1.gm_submode` |

### Messaggio A1 (Radar Settings and Parameters)

| Nome Legacy | Percorso Reale |
|-------------|----------------|
| `tgt_history` | `settings.history_level` |
| `alt_block` | `settings.altitude_block` |
| `ALE_BLANKING` | `settings.ale_blanking_disable` |
| `FREQ_AGILITY` | `frequency.frequency_agility_type` |
| `channel` | `frequency.channel_selection` |
| `beacon_code` | `beacon.beacon_code` |
| `beacon_delay` | `beacon.beacon_delay` |
| `video_intensity` | `settings.sym_intensity` |
| `if_gain` | `frequency.if_gain` |
| `GND_TGT_REJ_RAD_VEL` | `settings.ground_reject_vel_high` |
| `MIN_DET_GND_TGT_RAD_VEL` | `settings.min_detect_ground_radial_vel_high` |
| `LPRF_THRESHOLD` | `settings.prf_lookup_selection` |

### Messaggio B7 (Radar Status Tellback)

| Nome Legacy | Percorso Reale |
|-------------|----------------|
| `stby_tellback` | `rdr_mode_tellback.stby` |
| `freeze_tellback` | `rdr_mode_tellback.freeze` |
| `rf_status` | `rdr_mode_tellback.rf_radiation` |
| `rdr_mode_tellback` | `rdr_mode_tellback.master_mode` |
| `lock_sts` | `rdr_mode_tellback.des_ctrl` |
| `range_scale_tellback` | `param1_tellback.range_scale` |
| `scan_width_tellback` | `param1_tellback.scan_width` |

## 🔧 Come Funziona

### 1. Accesso ai Campi (Nested)

```python
from pymsc.core.message_definitions import msg_a2

# Accesso diretto con percorso nested
value = msg_a2.get_field_value('rdr_mode_command.stby')

# Set con percorso nested
msg_a2.set_field_value('rdr_mode_command.stby', 1)
```

### 2. API Legacy (per GUI)

```python
# La GUI usa ancora nomi flat
value = msg_a2.get_value_for_field('stby')  # Automaticamente mappato a 'rdr_mode_command.stby'
msg_a2.set_value_for_field('stby', 1)       # Funziona come prima!
```

### 3. Struttura Interna

```python
# Accesso diretto alla struttura ctypes
internal_structure = msg_a2._internal  # tipo: MsgRdrOperationCommand
rdr_mode = internal_structure.rdr_mode_command  # tipo: RdrModeCommandWord (Union)

# I campi bitfield hanno getter/setter
stby_value = rdr_mode.get_stby()
rdr_mode.set_stby(1)
```

## ✅ Test Eseguiti

1. **test_new_messages.py**: Verifica struttura nested e accesso campi
2. **test_integration.py**: Verifica integrazione con GUI e command_registry
3. Tutti i test passano ✓

## 🚀 Prossimi Passi

1. **Avviare la GUI**: `python -m pymsc`
2. **Verificare i widget**: Controllare che checkbox, combobox, ecc. rispondano correttamente
3. **Test con hardware**: Verificare comunicazione 1553 reale con le nuove strutture
4. **Messaggi B9 e B10**: Implementare strutture complete quando disponibili in pybusmonitor1553

## ⚠️ Note Importanti

- Le strutture ora rispettano **esattamente** le specifiche ICD 1553
- I bitfield sono gestiti correttamente (non più `c_int` flat)
- L'allineamento è `_pack_ = 1` per corrispondere al protocollo hardware
- I warning "Lib Loaded!" e "SIZEOFFFFFFFF" sono normali (da pybusmonitor1553)
- **Campi non implementati**: Alcuni campi (es. `emergency`, `SAR_ENABLED`, `DEGRADED_PERF_STATUS`, `velocity_scale_tellback`) non esistono nelle strutture attuali e sono mappati su campi `spare` o rimossi
- I widget gestiscono correttamente i valori `None` restituiti da campi non implementati mostrando `---` o `ERR`

## 📚 Riferimenti

- Strutture originali: `_external/pybusmonitor1553/Grifo_E_1553lib/`
- Strutture copiate in: `pymsc/PyBusMonitor1553/Grifo_E_1553lib/`
- ICD Document: `doc/ICD_DECD_FTH - GRIFO-F_TH, Data Exchange Control Document for, rev -A, Draft 2.md`