Files/ComputerAssignments/CA2/FINAL_PROJECT_DOCUMENTATION.html

<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head>
<meta charset="utf-8">
<title>FINAL_PROJECT_DOCUMENTATION</title>
<style>

body { font-family: Tahoma, 'Segoe UI', sans-serif; line-height: 2.0; font-size: 11pt; color: #0f172a; padding: 30px; background-color: #ffffff; }
h1 { color: #1e1b4b; border-bottom: 3px solid #4f46e5; padding-bottom: 10px; font-size: 22pt; margin-top: 30px; }
h2 { color: #1e293b; background-color: #f1f5f9; border-right: 5px solid #3b82f6; padding: 8px 12px; font-size: 16pt; margin-top: 25px; }
h3 { color: #2563eb; font-size: 13pt; margin-top: 20px; }
p { text-align: justify; margin-bottom: 15px; }
pre { background-color: #0f172a; color: #f8fafc; padding: 15px; border-radius: 6px; font-family: Courier, monospace; font-size: 10pt; overflow-x: auto; }
code { background-color: #f1f5f9; color: #0f172a; padding: 2px 5px; border-radius: 4px; font-family: Courier, monospace; }
table { border-collapse: collapse; width: 100%; margin: 20px 0; }
th, td { border: 1px solid #cbd5e1; padding: 10px; text-align: right; }
th { background-color: #f1f5f9; }
ul, ol { padding-right: 25px; }

</style>
</head>
<body>
<div class="container">
<h1>AirMouse Pro — Master System Architecture &amp; Verification Report</h1>
<p><strong>Project Root:</strong> <code>~/Documents/uni/CPS/Files/ComputerAssignments/CA2</code><br />
<strong>System:</strong> Cyber-Physical System (CPS) AirMouse Pro<br />
<strong>Version:</strong> 3.0.0  </p>
<hr />
<h2>1. Executive Summary</h2>
<p>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. <strong>Android Client (Kotlin):</strong> 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. <strong>Go Desktop Server:</strong> High-throughput native server supporting TCP (9090), WebSocket (9091), UDP Discovery (9092), and REST Admin API (8081).
3. <strong>Python MCP Server &amp; Bridge (<code>airmouse_server_mcp.py</code>):</strong> FastMCP tool suite with 444 system, ADB, PyAutoGUI, calibration, build, and Perfetto analysis tools.
4. <strong>Antigravity Workspace (.agents):</strong> 22 domain skills, development rules, dynamic memory state, and extended 5-lifecycle hook engine.</p>
<hr />
<h2>2. Mathematical Models &amp; Sensor Fusion</h2>
<ul>
<li><strong>Madgwick AHRS Gain (beta):</strong> Fixed at 0.041 for optimal gyro drift rejection and accelerometer stability.</li>
<li><strong>Gyro Units:</strong> Raw rad/s directly from Android <code>SensorManager</code> without unit double conversion.</li>
<li><strong>Gesture Engine Thresholds:</strong></li>
<li>Click: Angular speed &gt; 8.0 rad/s on Gyro Y-axis (300ms cooldown).</li>
<li>Double Click: Interval &lt; 400ms between consecutive left clicks.</li>
<li>Scroll: Acceleration &gt; 8.0 m/s^2 (2.0 m/s^2 debounce threshold, 100ms cooldown).</li>
<li>Right-Click: Roll tilt &gt; 45° held for &gt;= 500ms.</li>
<li><strong>Cursor Motion Pipeline:</strong> Power-law non-linear acceleration combined with Kalman predictive blending.</li>
</ul>
<hr />
<h2>3. Network Architecture &amp; Protocols</h2>
<ul>
<li><strong>TCP Socket (Port 9090):</strong> Primary newline-delimited JSON stream for orientation and commands with 500ms ACK retransmissions (max 3 retries).</li>
<li><strong>WebSocket (Port 9091):</strong> Browser dashboard and Web UI event channel.</li>
<li><strong>UDP Discovery (Port 9092):</strong> Auto-discovery of local PC servers on LAN.</li>
<li><strong>REST Admin API (Port 8081):</strong> Runtime status inspection and dynamic configuration.</li>
</ul>
<hr />
<h2>4. Verification &amp; QA Status</h2>
<ul>
<li><strong>Environment &amp; Build:</strong> Java, Go, Android SDK, and Python syntax verified 100%.</li>
<li><strong>Go Native Server:</strong> <code>-race</code> detector clean, unit tests passing.</li>
<li><strong>Android Client:</strong> Gradle assembleDebug &amp; assembleRelease compiled cleanly.</li>
<li><strong>MCP Server:</strong> Syntax check and FastMCP stdio interface verified.</li>
</ul>
</div>
</body>
</html>