# PyBusMonitor1553 - Project Roadmap

## Vision
Evolve from passive bus monitor to comprehensive radar simulation and control platform for GRIFO-F/TH integration testing.

---

## Phase 1: Bus Monitor ✅ (Current)

**Status**: Complete  
**Objective**: Passive monitoring of MIL-STD-1553 traffic

**Capabilities**:
- UDP packet reception/parsing
- Real-time message display (A1-A8, B1-B8)
- Traffic statistics and message rates
- Tkinter GUI with detail view

**Architecture Foundation**:
- Field descriptor pattern (BitField, EnumField, ScaledField)
- Multi-rate scheduler (50Hz, 25Hz, 6.25Hz)
- Thread-safe Queue-based updates
- Modular message definitions

---

## Phase 2: Command & Control (Next)

**Objective**: Active radar command generation and parameter injection

### 2.1 Command Interface
```python
# Public API for radar control
controller.set_master_mode(MasterMode.TWS)
controller.set_range(RangeScale.NM_80)
controller.set_scan_pattern(bars=BAR_4, azimuth=DEG_120)
controller.set_standby(False)
```

### 2.2 Navigation Data Injection
```python
# Simulate platform movement
controller.update_nav_data(
    altitude=8500.0,      # meters MSL
    velocity=(250, 45),   # m/s, heading degrees
    attitude=(5, -2, 180) # pitch, roll, yaw
)
```

### 2.3 GUI Enhancements
- **Control Panel**: Sliders/dropdowns for mode, range, scan parameters
- **Nav Data Input**: Real-time position/velocity entry
- **Command History**: Log of sent commands with timestamps

### Technical Requirements
- Validation layer for parameter ranges (per ICD limits)
- Command queuing for rate-limited transmission
- Feedback display (command sent ✓, acknowledged, rejected)

---

## Phase 3: Target Injection

**Objective**: Simulate radar returns by injecting synthetic targets

### 3.1 Track Management
```python
# Generate synthetic tracks
target_injector.create_track(
    track_id=1,
    position=(12000, 5000, 3000),  # x, y, z meters
    velocity=(150, 90),             # speed m/s, heading
    rcs=10.0                        # radar cross-section m²
)
```

### 3.2 Scenario Engine
- **Multi-target scenarios**: Formations, intercepts, evasion
- **Kinematic models**: Constant velocity, turning, acceleration
- **Playback mode**: Load pre-recorded scenarios

### 3.3 Message B Integration
- Populate MsgB1-B8 with synthetic track data
- Realistic track numbers, priorities, threat levels
- Coordinate with MsgA radar state (range/azimuth constraints)

### Technical Challenges
- Coordinate transformations (geodetic ↔ radar-relative)
- Track lifecycle (initiation, update, drop)
- Realistic timing (update rates per track quality)

---

## Phase 4: Integration Platform

**Objective**: Modular architecture for complex test scenarios

### 4.1 Plugin System
```
pybusmonitor1553/
  plugins/
    scenario_loader/   # Load JSON/XML scenario files
    telemetry_logger/  # Record all traffic to disk
    replay_engine/     # Playback recorded sessions
    external_sim/      # Interface to FlightGear, X-Plane
```

### 4.2 Scripting Interface
```python
# Python scripting for automated tests
from pybusmonitor1553 import RadarSim

sim = RadarSim()
sim.initialize_radar(mode=MasterMode.RWS, range=NM_40)
sim.inject_target(position=(10000, 0, 2000), velocity=(200, 0))
sim.run_for(seconds=30)
sim.assert_track_acquired(track_id=1)
```

### 4.3 Network Integration
- **Multi-client support**: Multiple radars on same network
- **Bridge mode**: Forward traffic between networks
- **Remote control**: Web API for external orchestration

---

## Phase 5: Advanced Features

### 5.1 Jamming & Countermeasures
- ECM simulation (noise, deception)
- Chaff/flare injection
- ECCM effectiveness testing

### 5.2 Environment Simulation
- Weather effects (rain, sea clutter)
- Terrain masking
- Multipath propagation

### 5.3 Analysis Tools
- Performance metrics (detection range, track accuracy)
- Scenario replay with annotations
- Report generation (PDF, CSV)

---

## Design Principles for Evolution

### 1. Backward Compatibility
- Bus monitor mode always available
- Existing message classes unchanged
- New features opt-in via configuration

### 2. Extensibility Points
**RadarController**:
- `apply_defaults()` → `apply_config(profile)`
- Add `validate_command()`, `queue_command()`

**MessageBase**:
- All fields settable via descriptors
- `pack()` method handles updated values
- No breaking changes to field definitions

**Scheduler**:
- Current tick-based design supports dynamic message addition
- `_build_schedule_table()` can accept runtime schedule changes

### 3. Separation of Concerns
```
core/
  controller.py      # Radar state (read-only in Phase 1)
  command_builder.py # NEW: Command generation & validation
  target_manager.py  # NEW: Track injection & kinematics
  scenario_engine.py # NEW: Script execution & orchestration
```

### 4. Configuration Management
```python
# config.yaml
mode: monitor  # monitor | control | inject | scenario

monitor:
  gui_enabled: true
  log_traffic: false

control:
  validation: strict  # strict | permissive
  command_rate_limit: 50  # Hz

inject:
  max_targets: 64
  coordinate_system: radar_relative
```

---

## Migration Path

### From Current (Monitor) to Control
1. **No code changes required** in `lib1553/` - all fields already writable
2. Add `core/command_builder.py` - validation layer
3. Extend `RadarController` with setter methods
4. GUI: add control panel tab

### From Control to Injection
1. Create `core/target_manager.py` - track kinematics
2. Implement coordinate transforms in `utils/coordinates.py`
3. Populate MsgB* with synthetic data
4. GUI: add target management panel

### Timeline Estimate
- **Phase 2**: 2-3 weeks (command interface + GUI controls)
- **Phase 3**: 3-4 weeks (target injection + kinematics)
- **Phase 4**: 4-6 weeks (plugin architecture + scripting)
- **Phase 5**: Long-term (research-driven features)

---

## Technical Debt Considerations

### Current Limitations
1. **Endianness handling**: Scattered pack/unpack logic
   - *Solution*: Centralize in `MessageBase._pack_word()`

2. **Error handling**: Limited validation on field assignments
   - *Solution*: Add `Field.validate()` hook

3. **Thread synchronization**: Queue-based but no explicit locking
   - *Solution*: Document threading model, add assertions

4. **Configuration**: Hardcoded network addresses
   - *Solution*: Move to `config.yaml` with environment overrides

### Refactoring Opportunities
- Extract UDP1553 frame handling to `lib1553/protocol.py`
- Split `MessageDispatcher` (RX) from `CommandDispatcher` (TX)
- Unify `packet_builder.py` and `packet_builder_simple.py`

---

## Success Metrics

### Phase 2 (Control)
- ✅ Radar mode change via GUI within 200ms
- ✅ All A-messages parameters modifiable
- ✅ Server MFD reflects commanded state

### Phase 3 (Injection)
- ✅ Inject 32 synthetic targets at 50Hz
- ✅ Tracks visible in server display
- ✅ Kinematic models accurate to <1% position error

### Phase 4 (Platform)
- ✅ Load/replay 10-minute scenario
- ✅ Python scripting executes 100-step test
- ✅ Plugin API documented with 3+ community plugins

---

## Conclusion

The field descriptor architecture and modular message design already support full parameter modification. Evolution to command & control requires **adding**, not **replacing**, existing code. The bus monitor remains the foundation—new capabilities layer on top as optional modes.

**Next Immediate Step**: Validate current radar initialization works correctly before adding control features.