SXXXXXXX_PyBusMonitor1553/doc/ICD-Implementation-Notes.md

# Note di Implementazione ICD - Discrepanze e Decisioni

**Documento**: Tracciamento discrepanze tra specifica ICD e implementazione di riferimento  
**Riferimento ICD**: `ICD_DECD_FTH - GRIFO-F_TH, Data Exchange Control Document for, rev -A, Draft 2`  
**Implementazione di Riferimento**: GrifoScope C++ (`th_b1553_icd.h`)  
**Data Prima Revisione**: Dicembre 2025

---

## 🎯 Principio Guida

**In caso di discrepanza tra ICD documento e implementazione C++ GrifoScope, si segue SEMPRE l'implementazione C++.**

**Motivazioni**:
1. GrifoScope è il software di riferimento testato e funzionante sul campo
2. Il simulatore radar GRIFO-F/TH risponde ai messaggi codificati secondo l'implementazione C++
3. La compatibilità binaria con il sistema esistente è requisito critico
4. L'ICD documento potrebbe contenere errori di trascrizione o versioni superate

---

## 📋 Discrepanze Identificate

### 1. Designation Control Field (A2/01 e B7/01)

**ICD Documento** (Sezione 7.1.2.1 - Tab. A2/01-B):
```
Field B: Designation Control
Bit No: 04, 05, 06, 07 (4 bits)
NOT VALID = decimal 15 (0b1111)
```

**Implementazione C++ GrifoScope** (`th_b1553_icd.h`, linee 434-444):
```cpp
typedef idd_bitfield_u16_t<IDD_REVBIT16(6), 3, des_control_t> des_control_field_t;
//                          IDD_REVBIT16(6) → LSB position = 15-6 = 9
//                                       ^^^ Width = 3 bits (NON 4!)

enum des_control_t {
  LOCK_ON,           // 0
  LOCK_ON_DTT,       // 1
  TRANS_HPT_BUT,     // 2
  REJECT,            // 3
  LOCK_ON_STT,       // 4
  DES_TRACK_LABEL,   // 5
  EXEC_SAR,          // 6
  NOT_VALID          // 7 (massimo rappresentabile con 3 bits)
};
```

**Decisione Implementativa**:
- ✅ **Adottato**: 3 bits, range 0-7, NOT_VALID = 7
- ❌ **Scartato**: 4 bits, range 0-15, NOT_VALID = 15

**Impatto**:
- Tutti i bit successivi in Word A2/01 e B7/01 shiftati di 1 posizione verso sinistra
- File modificati:
  - `pybusmonitor1553/lib1553/constants.py`: `DesignationControl` enum corretta
  - `pybusmonitor1553/lib1553/messages/msg_a2.py`: `designation_ctrl` width=3
  - `pybusmonitor1553/lib1553/messages/msg_b7.py`: `designation_status` width=3

**Verifica Compatibilità**:
```python
# Test: tools/compare_a2_messages.py
# Risultato: ✓ MATCH binario al 100% con encoding C++ atteso
Phase 1: Expected=0x0E88, Actual=0x0E88 ✓
Phase 2: Expected=0x0E00, Actual=0x0E00 ✓
```

---

## 🔍 Metodologia di Verifica

Quando si implementano nuovi messaggi o si modificano strutture esistenti:

### Step 1: Confronto ICD vs C++

```bash
# Leggere definizione ICD documento
doc/ICD_DECD_FTH...md → Sezione specifica messaggio

# Verificare implementazione C++ (fonte di verità)
___OLD/_old/cpp/GrifoScope/GrifoSdkEif/pub/TH/th_b1553_icd.h
```

### Step 2: Analisi Typedef C++

La macro `IDD_REVBIT16(N)` converte bit ICD MSB-first a LSB position:
```cpp
#define IDD_REVBIT16(pos) (15 - pos)

// Esempio:
typedef idd_bitfield_u16_t<IDD_REVBIT16(8), 1, stby_selection_t> stby_field_t;
// IDD_REVBIT16(8) = 15-8 = 7 (LSB shift position)
// Width = 1 bit
// In MSB numbering: 15-7 = Bit 8 (ICD)
```

### Step 3: Implementazione Python

```python
# msg_aX.py o msg_bX.py
field_name = EnumField(
    word_index=X,
    start_bit=N,    # Numero bit ICD (MSB-first, 0-15)
    width=W,        # Width da C++ typedef
    enum_cls=EnumClass
)

# La classe Field calcola automaticamente:
# _shift = 16 - (start_bit + width)
```

### Step 4: Test Binario

```python
# Creare test dedicato simile a tools/compare_a2_messages.py
# Verificare encoding word-per-word contro valori attesi C++
assert actual_word == expected_cpp_word, f"Mismatch: 0x{actual_word:04X} != 0x{expected_cpp_word:04X}"
```

---

## 📊 Tabella Riepilogativa Campi Critici

| Messaggio | Word | Campo | ICD Bits | C++ Bits | Python start_bit | Python width |
|-----------|------|-------|----------|----------|------------------|--------------|
| A2 | 01 | master_mode | 00-03 | 00-03 | 0 | 4 |
| A2 | 01 | designation_ctrl | 04-07 ❌ | 04-06 ✅ | 4 | 3 |
| A2 | 01 | int_bit_req | 08 ❌ | 07 ✅ | 7 | 1 |
| A2 | 01 | standby_cmd | 09 ❌ | 08 ✅ | 8 | 1 |
| A2 | 01 | freeze_cmd | 10 ❌ | 09 ✅ | 9 | 1 |
| A2 | 01 | pwr_up_stop | 11 ❌ | 10 ✅ | 10 | 1 |
| A2 | 01 | reserved | 12 ❌ | 11 ✅ | 11 | 1 |
| A2 | 01 | silence | 13 ❌ | 12 ✅ | 12 | 1 |
| B7 | 01 | master_mode_tb | 00-03 | 00-03 | 0 | 4 |
| B7 | 01 | designation_status | 04-07 ❌ | 04-06 ✅ | 4 | 3 |
| B7 | 01 | int_bit_status | 08 ❌ | 07 ✅ | 7 | 1 |
| B7 | 01 | standby_status | 09 ❌ | 08 ✅ | 8 | 1 |
| B7 | 01 | freeze_status | 10 ❌ | 09 ✅ | 9 | 1 |
| B7 | 01 | degraded_status | 11 ❌ | 10 ✅ | 10 | 1 |
| B7 | 01 | reserved | 12 ❌ | 11 ✅ | 11 | 1 |
| B7 | 01 | rf_radiation_status | 13 ❌ | 12 ✅ | 12 | 1 |
| B7 | 01 | transition_status | 14 ❌ | 13 ✅ | 13 | 1 |
| B7 | 01 | last_acq_result | 15 ❌ | 14 ✅ | 14 | 1 |

**Legenda**:
- ❌ = ICD documento (ERRATO, non usare)
- ✅ = Implementazione C++ (CORRETTO, usato nel codice)

---

## 🔄 Storia Revisioni

| Data | Autore | Modifiche |
|------|--------|-----------|
| 2025-12-12 | AI/Developer | Documento creato. Identificata discrepanza Designation Control (3 vs 4 bits). Corretti A2/01 e B7/01. Verificata compatibilità binaria. |

---

## 📞 Contatti e Segnalazioni

Se vengono identificate nuove discrepanze:

1. **Non modificare il codice** basandosi solo sull'ICD documento
2. **Verificare** sempre con `th_b1553_icd.h` C++
3. **Documentare** in questo file la discrepanza trovata
4. **Testare** compatibilità binaria con test dedicato
5. **Aggiornare** tabella riepilogativa

---

## 🔗 Riferimenti

- **ICD Documento**: `doc/ICD_DECD_FTH - GRIFO-F_TH, Data Exchange Control Document for, rev -A, Draft 2.md`
- **Header C++ Riferimento**: `___OLD/_old/cpp/GrifoScope/GrifoSdkEif/pub/TH/th_b1553_icd.h`
- **Implementazione Simulator**: `___OLD/_old/cpp/GrifoScope/GrifoMCS/GADS/MCS/MCS_G346/g346/g346_a1a2.cpp`
- **Architettura Tecnica**: `doc/Technical-Architecture.md` (Sezione 2.4)
- **Test Compatibilità**: `tools/compare_a2_messages.py`