Files/ComputerAssignments/CA2/FINAL_PROJECT_DOCUMENTATION.md

# AirMouse Pro — Master System Architecture & Verification Report

**Project Root:** `~/Documents/uni/CPS/Files/ComputerAssignments/CA2`  
**System:** Cyber-Physical System (CPS) AirMouse Pro  
**Version:** 3.0.0  

---

## 1. Executive Summary
AirMouse Pro is a high-precision, low-latency cyber-physical system transforming an Android smartphone into a 3D air-mouse and spatial gesture controller for desktop operating systems. The system comprises four tightly integrated subsystems:
1. **Android Client (Kotlin):** Sensor reading, Madgwick AHRS fusion (beta=0.041), 3-step calibration (Gyro bias, Mag figure-8, Accel 6-position), motion gesture engine, Perfetto trace integration.
2. **Go Desktop Server:** High-throughput native server supporting TCP (9090), WebSocket (9091), UDP Discovery (9092), and REST Admin API (8081).
3. **Python MCP Server & Bridge (`airmouse_server_mcp.py`):** FastMCP tool suite with 444 system, ADB, PyAutoGUI, calibration, build, and Perfetto analysis tools.
4. **Antigravity Workspace (.agents):** 22 domain skills, development rules, dynamic memory state, and extended 5-lifecycle hook engine.

---

## 2. Mathematical Models & Sensor Fusion
- **Madgwick AHRS Gain (beta):** Fixed at 0.041 for optimal gyro drift rejection and accelerometer stability.
- **Gyro Units:** Raw rad/s directly from Android `SensorManager` without unit double conversion.
- **Gesture Engine Thresholds:**
  - Click: Angular speed > 8.0 rad/s on Gyro Y-axis (300ms cooldown).
  - Double Click: Interval < 400ms between consecutive left clicks.
  - Scroll: Acceleration > 8.0 m/s^2 (2.0 m/s^2 debounce threshold, 100ms cooldown).
  - Right-Click: Roll tilt > 45° held for >= 500ms.
- **Cursor Motion Pipeline:** Power-law non-linear acceleration combined with Kalman predictive blending.

---

## 3. Network Architecture & Protocols
- **TCP Socket (Port 9090):** Primary newline-delimited JSON stream for orientation and commands with 500ms ACK retransmissions (max 3 retries).
- **WebSocket (Port 9091):** Browser dashboard and Web UI event channel.
- **UDP Discovery (Port 9092):** Auto-discovery of local PC servers on LAN.
- **REST Admin API (Port 8081):** Runtime status inspection and dynamic configuration.

---

## 4. Verification & QA Status
- **Environment & Build:** Java, Go, Android SDK, and Python syntax verified 100%.
- **Go Native Server:** `-race` detector clean, unit tests passing.
- **Android Client:** Gradle assembleDebug & assembleRelease compiled cleanly.
- **MCP Server:** Syntax check and FastMCP stdio interface verified.