Feature Idea: 🎮 Android Button Panel → Virtual HID Device for DCS World

> **Type:** Feature Request / Experimental Evaluation
> **Status:** 🔬 Testing in Progress
> **Priority:** Medium

---

## 📋 Description

Implement a system that allows application to act as a configurable button panel for DCS World by transmitting input events over UDP connection back to **forward_parsed_udp.py** .

This document also serves as an **experimental evaluation** to determine whether the **Virtual HID approach** is better and easier suited than **direct Export.lua commands** for the application and every Module Aircraft.

---

## 🏗️ Proposed Architecture

### Option A: Virtual HID Device *(Current Experiment)*

```
┌──────────────┐ UDP/AES-GCM ┌──────────────┐ HID Driver ┌───────────┐
│ 📱 Android │ ────────────────► │ 🐍 Python │ ───────────────► │ 🎮 DCS │
│ Button App │ │ Backend │ │ World │
└──────────────┘ └──────────────┘ └───────────┘
(vgamepad/uinput) (Std Joystick)
```

### Option B: Direct Export.lua *(Comparison)*

```
┌──────────────┐ UDP/AES-GCM ┌──────────────┐ Export.lua ┌───────────┐
│ 📱 Android │ ────────────────► │ 🐍 Python │ ───────────────► │ 🎮 DCS │
│ Button App │ │ Backend │ │ World │
└──────────────┘ └──────────────┘ └───────────┘
(Lua Socket) (LoSetCommand)
```

---

## ⚖️ Comparison Matrix

| Kriterium | Virtual HID | Export.lua |
|-----------|:-----------:|:----------:|
| DCS Native Binding UI | ✅ | ❌ |
| Works with other games | ✅ | ❌ |
| No Lua scripting needed | ✅ | ❌ |
| Module-specific commands | ❌ | ✅ |
| No virtual device setup | ❌ | ✅ |
| Lower abstraction layers | ❌ | ✅ |
| Portable solution | ✅ | ❌ |

---

## 📦 Scope

### ✅ In Scope

- New Kotlin module with configurable buttons, switches, encoders
- Bidirectional UDP communication
- Secure channel: ECDH key exchange + AES-GCM encryption via **forward_parsed_udp.py** and **crypto_handshake.py**
- Python backend exposing virtual HID device
- DCS World recognition as standard input hardware
- Cross-platform backend (Windows/Linux)
- Working also in other games (MSFS , XPLANE etc)

### ❌ Out of Scope

- Android as direct USB HID (no root/custom kernel)
- Reverse engineering of DCS internals
- Macro functionality (1 event = 1 HID input)

---

## 📐 Requirements

| Requirement | Target | Status |
|-------------|--------|:------:|
| End-to-end latency | < 10 ms | ⏳ |
| Event mapping | 1:1 (no macros) | ⏳ |
| Device identification | Fixed VID/PID | ⏳ |
| License compliance | Apache/BSD/MIT only | ⏳ |

### 🖥️ Platform Support

| Platform | Implementation | Library |
|----------|----------------|---------|
| Windows | ViGEmBus | `vgamepad` |
| Linux | uinput/evdev | `evdev` |

---

## ✅ Acceptance Criteria

- [ ] Android button press visible in DCS as costumizable modular joystick button
- [ ] Secure channel established automatically on startup
- [ ] System runs reliably for extended sessions (8h+)
- [ ] No control inputs gone lost
- [ ] No conflicts with physical input devices

---

## 🧪 Test Cases

### Phase 1: Infrastructure Setup (if use seperate .py forwarder)

- [ ] 1.1 — Python backend stable on Windows (ViGEmBus)
- [ ] 1.2 — Python backend stable on Linux (uinput)
- [ ] 1.3 — Virtual joystick visible in Windows Game Controllers
- [ ] 1.4 — Virtual joystick visible in `jstest`/`evtest` (Linux)
- [ ] 1.5 — Fixed VID/PID persists across restarts
- [ ] 1.6 — ECDH key exchange successful
- [ ] 1.7 — AES-GCM packets decoded correctly

### Phase 2: Basic HID Functionality

- [ ] 2.1 — Single button press registers
- [ ] 2.2 — Button release handled correctly
- [ ] 2.3 — Multiple simultaneous presses work
- [ ] 2.4 — Latency < 10 ms (button → HID event)
- [ ] 2.5 — No event loss at 10 Hz
- [ ] 2.6 — No event loss at 50 events/sec burst

### Phase 3: DCS World Integration

- [ ] 3.1 — DCS detects virtual joystick in Controls
- [ ] 3.2 — Button bindable via DCS UI
- [ ] 3.3 — Bound button triggers correct action
- [ ] 3.4 — Binding persists across DCS restarts
- [ ] 3.5 — No conflict with physical joysticks
- [ ] 3.6 — ✈️ F/A-18C Hornet tested
- [ ] 3.7 — 🛩️ A-10C II tested
- [ ] 3.8 — 🚁 Ka-50 tested

### Phase 4: Stability & Edge Cases

- [ ] 4.1 — Stable over 2h session
- [ ] 4.2 — Stable over 8h session
- [ ] 4.3 — Reconnect after app backgrounded
- [ ] 4.4 — Reconnect after network interruption
- [ ] 4.5 — Graceful backend restart handling
- [ ] 4.6 — No memory leaks (24h test)
- [ ] 4.7 — CPU usage < 5% idle / < 15% active

### Phase 5: Export.lua Comparison 🔬

- [ ] 5.1 — Export.lua socket connection works
- [ ] 5.2 — `LoSetCommand()` executes externally
- [ ] 5.3 — Measure latency: UDP → Export.lua → action
- [ ] 5.4 — Module-specific commands work (e.g., UFC)
- [ ] 5.5 — `GetDevice()` cockpit manipulation works
- [ ] 5.6 — **Compare latency:** HID vs Export.lua
- [ ] 5.7 — **Compare reliability:** 1000 events test

---

## 📊 Measurement Log

| Test | Date | Result | Latency | Notes |
|:----:|:----:|:------:|:-------:|-------|
| 2.4 | | ⏳ | — ms | |
| 5.3 | | ⏳ | — ms | |
| 5.6 | | ⏳ | — ms | |

---

## 🛠️ Implementation Checklist

### 📱 Android App

- [ ] Button grid UI
- [ ] Button configuration (label, ID, type)
- [ ] UDP socket management
- [ ] ECDH key exchange (client)
- [ ] AES-GCM encryption
- [ ] Connection status indicator
- [ ] Reconnect logic
- [ ] Haptic feedback
- [ ] Config save/load (JSON)

### 🐍 Python Backend

- [ ] Async UDP server
- [ ] ECDH key exchange (server)
- [ ] AES-GCM decryption
- [ ] Event queue management
- [ ] Windows: ViGEmBus integration
- [ ] Linux: uinput integration
- [ ] Button mapping config (JSON/YAML)
- [ ] Structured logging
- [ ] Systemd service (Linux)
- [ ] Windows service wrapper

### 🎮 DCS Integration

- [ ] Virtual device recognition
- [ ] Test binding profile
- [ ] Module preset profiles
- [ ] User documentation

---

## 🔮 Future Extensions

- [ ] Configurable button-to-HID mapping (JSON/YAML)
- [ ] Multi-device support
- [ ] Encoder and axis support
- [ ] Heartbeat and reconnect handling

---

## 📌 Current Status

| Phase | Status |
|-------|:------:|
| Infrastructure | ⏳In Progress|
| Basic HID | ⏳ Open |
| DCS Integration | ⏳ Open |
| Stability | ⏳ Open |
| Comparison | ⏳ Open |

---