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.