Files/ComputerAssignments/CA2/code/docs/Troubleshooting_Guide.md

Air Mouse – Complete Troubleshooting Guide

This document covers every possible issue you may encounter while building, installing, calibrating, and using the Air Mouse. Each problem is explained with its root cause, diagnostic steps, and a proven solution. Use this as your first resource when something doesn’t work.

---

📖 Table of Contents

1. Installation & Dependency Issues
2. Network & Connection Problems
3. Android App Issues
4. Calibration & Sensor Problems
5. Cursor Movement & Gesture Problems
6. Performance & Battery Issues
7. Build & Compilation Problems
8. Video Recording & Submission Issues

---

1. Installation & Dependency Issues

1.1 pip install pyautogui fails with SOCKS proxy error

Symptoms:

ERROR: Could not install packages due to an OSError: Missing dependencies for SOCKS support.

Root cause: Your terminal or system has http_proxy/https_proxy environment variables set to a SOCKS proxy, but pip lacks the PySocks library.

Diagnostic steps:

echo $http_proxy
echo $https_proxy

If they return a value (e.g., socks5://...), the proxy is active.

Solution (temporary – per session):

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy ALL_PROXY
pip install pyautogui

Solution (permanent): Remove the proxy lines from your shell config (.bashrc, .zshrc, .bash_profile).

Alternative: Install PySocks first:

pip install PySocks
pip install pyautogui

1.2 pip install fails with “Could not find a version that satisfies the requirement”

Symptoms: ERROR: Could not find a version that satisfies the requirement pyautogui

Root cause: The mirror URL (https://pypi.devneeds.ir/simple/) may be unreachable due to network restrictions, or the index is down.

Solution: Use the default PyPI (if internet is unrestricted):

pip install pyautogui

Or use a different mirror:

pip install pyautogui -i https://pypi.org/simple/

1.3 Java not found when running build_apk.sh

Symptoms: [ERROR] Java not found. Please install Java 11 (JDK) and add it to PATH.

Root cause: Java JDK 11 is not installed or not in PATH.

Solution (macOS):

brew install openjdk@11
export PATH="/usr/local/opt/openjdk@11/bin:$PATH"

Solution (Ubuntu/Debian):

sudo apt install openjdk-11-jdk

Solution (Windows): Download from Adoptium and run the installer – check “Add to PATH”.

Verify:

java -version
# Should show openjdk version "11.0.x"

1.4 sdkmanager not found when building APK

Symptoms: sdkmanager not found. Make sure Android SDK command-line tools are installed...

Root cause: Android command‑line tools are missing or not extracted to the expected location (~/android-sdk/cmdline-tools/latest/).

Solution:

1. Download from Google.
2. Extract to ~/android-sdk/cmdline-tools/.
3. Rename the extracted folder to latest:

   mkdir -p ~/android-sdk/cmdline-tools
   unzip commandlinetools-linux-*.zip -d ~/android-sdk/cmdline-tools
   mv ~/android-sdk/cmdline-tools/cmdline-tools ~/android-sdk/cmdline-tools/latest
   

4. Set ANDROID_HOME and update PATH:

   export ANDROID_HOME=~/android-sdk
   export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools
   

1.5 Android app installation fails with INSTALL_FAILED_UPDATE_INCOMPATIBLE

Symptoms: ADB says INSTALL_FAILED_UPDATE_INCOMPATIBLE or the phone says “App not installed”.

Root cause: An older version of Air Mouse is still installed, or the signatures don’t match.

Solution: Uninstall the existing version first:

adb uninstall com.airmouse

Then re‑install the APK.

---

2. Network & Connection Problems

2.1 Connection refused on phone when tapping “Start”

Symptoms: Toast message “Network error: Connection refused” or status stays “Not connected”.

Root causes:

• PC server is not running.
• IP address is wrong (e.g., 127.0.0.1 or a different subnet).
• Firewall blocks port 8080.
• Phone and PC are on different WiFi networks.

Diagnostic steps:

1. On PC, check if server is listening:

   netstat -an | grep 8080
   

   Should show LISTENING (Windows) or LISTEN (Linux/macOS).

2. On PC, find your correct IP:

   • Windows: ipconfig → look for IPv4 Address under your active WiFi adapter (e.g., 192.168.1.10).
   • macOS/Linux: ifconfig or ip addr → look for inet 192.168.x.x or 10.x.x.x.

3. Temporarily disable firewall:

   • Windows: Control Panel → Windows Defender Firewall → Turn off (test only).
   • macOS: System Settings → Network → Firewall → Off.
   • Linux: sudo ufw disable (Ubuntu) or sudo systemctl stop firewalld.

4. On phone, verify WiFi connection: Settings → WiFi → same network name as PC.

Solution: Ensure server is running (python gui.py), enter the correct IP, and re‑enable firewall after adding an exception for port 8080.

2.2 High latency / cursor lags behind phone movement

Symptoms: Cursor moves noticeably after you rotate the phone (delay >100 ms).

Root causes:

• WiFi congestion (many devices on same channel).
• Phone CPU overloaded (battery saver mode, background apps).
• PC server running on a slow machine or under heavy load.

Diagnostic steps:

• Test with a different WiFi network (e.g., phone hotspot).
• Close other apps on phone and PC.
• Check PC CPU usage (Task Manager / top).

Solutions:

• Use 5 GHz WiFi if available (less interference).
• Reduce sensor sampling rate (change to SENSOR_DELAY_NORMAL in SensorService.kt).
• Increase server sensitivity to reduce packet frequency? Not recommended. Instead, optimise PC code.

2.3 Connection drops frequently or auto‑reconnect fails

Symptoms: “Disconnected” appears in server log, then reconnects after a few seconds.

Root causes:

• Unstable WiFi (signal strength low).
• Router drops idle TCP connections.
• Phone goes into deep sleep (if battery saver interferes).

Solutions:

• Move phone and PC closer to router.
• On PC, add a TCP keep‑alive (not implemented in basic server, but you can add a periodic heartbeat message from phone).
• In Android, ensure AutoReconnect is enabled and working (it tries every 5 seconds).

---

3. Android App Issues

3.1 App crashes immediately on opening

Symptoms: The app shows a white screen for a second then closes.

Root causes:

• Missing sensor (phone lacks gyroscope or magnetometer).
• Missing permission (Internet, Vibrate).
• Resource not found (layout ID mismatch).

Diagnostic steps:

• Connect phone to PC, run adb logcat | grep -i exception to see the crash log.

Common exceptions and fixes:

Exception	Cause	Solution
SensorManager.getDefaultSensor returned null	Phone lacks sensor	Use a different phone (or add fallback in code).
Permission denied for INTERNET	Permission not granted	Re‑install app and grant permissions manually.
No view found for id	XML ID typo	Check that all IDs in MainActivity.kt match activity_main.xml.

3.2 Green square doesn’t rotate

Symptoms: The green square stays fixed, even when you rotate the phone.

Root causes:

• Sensor service not started.
• Orientation callback not set.
• Fusion algorithm not receiving data.

Diagnostic steps:

• Check status text: does it say “Air Mouse Active”?
• In debug overlay (if enabled), do roll/yaw values change?
• Look at adb logcat for “SensorService” logs.

Solution:

• Ensure you tapped “Start Air Mouse” after calibration.
• Re‑calibrate sensors (especially magnetometer).
• Restart the app.

3.3 App shows “Calibration complete” but calibration actually failed

Symptoms: Toast says “Calibration done” but cursor still drifts or gestures don’t work.

Root cause: The calibration functions may have thrown an exception that was caught silently, or the user did not follow the instructions (e.g., moved phone during gyro calibration).

Solution: Force re‑calibration with careful steps:

• Gyro: Place phone on a perfectly still table – do not hold it.
• Magnetometer: Move in a large figure‑8 pattern covering all axes, away from metal objects.
• Accelerometer: (Simplified) keep phone still on a flat surface.

3.4 Debug overlay not showing

Symptoms: Tapping “Show Debug” does nothing, or a toast says “Overlay permission required”.

Root cause: The app does not have SYSTEM_ALERT_WINDOW permission.

Solution: Grant overlay permission manually:

• Go to phone Settings → Apps → Air Mouse → Overlay permission → Allow.
• Or, on first tap of “Show Debug”, the app should open the permission screen automatically. If not, restart the app.

---

4. Calibration & Sensor Problems

4.1 Cursor drifts even when phone is perfectly still

Root cause: Gyro bias not properly removed – either calibration was skipped or phone moved during gyro calibration.

Solution: Re‑calibrate gyro on a flat, stationary surface. Do not hold the phone in your hand.

4.2 Yaw (horizontal orientation) drifts over time

Root cause: Magnetometer calibration was incomplete (hard‑iron offset not fully measured) or there is a magnetic disturbance (laptop speakers, metal desk).

Solution:

• Re‑calibrate magnetometer by moving the phone in a large figure‑8 for the full 30 seconds, covering all orientations.
• Keep the phone away from laptop speakers, magnets, or metal surfaces during use.

4.3 Tilt (roll/pitch) is inaccurate (phone level not matching cursor level)

Root cause: Accelerometer calibration not performed or simplified 1‑point method insufficient.

Solution: Implement the full 6‑point accelerometer calibration (collect data in ±X, ±Y, ±Z orientations) – see CalibrationHelper.kt for the method.

4.4 Scroll triggers randomly when phone is still

Root cause: Hand tremor or sensor noise exceeds scrollSpeedThreshold.

Solution: Increase the scroll threshold in Settings (e.g., from 8.0 to 12.0 m/s²). Also, ensure the phone is held firmly.

4.5 Click / double‑click never triggers

Root cause: Threshold too high, or user not flicking fast enough.

Diagnostic: In debug overlay, watch GyroY value while flicking. It should exceed the clickSpeedThreshold (default 5.0 rad/s). If not, either lower the threshold or flick harder.

Solution: Go to Settings → lower click speed threshold to 3.0 or 4.0.

---

5. Cursor Movement & Gesture Problems

5.1 Cursor moves opposite to phone rotation

Root cause: Axis sign convention mismatch between phone and PC.

Solution: In MainActivity.kt, invert the delta signs:

val deltaX = -(yaw - lastYaw) * sensitivity * 0.8f
val deltaY = -(roll - lastRoll) * sensitivity * 0.8f

Rebuild and re‑install.

5.2 Cursor jumps erratically

Root cause: High sensitivity combined with high‑frequency noise; or network packet loss.

Solutions:

• Lower the sensitivity slider.
• Add a low‑pass filter on the deltas (simple moving average) in MainActivity.kt.
• Ensure stable WiFi.

5.3 Scroll direction is reversed

Root cause: Sign of accelerometer Y axis may be opposite on some phones.

Solution: In SensorService.kt, invert the scroll direction:

if (scroll != 0) gestureCallback?.invoke(
    if (scroll > 0) MotionDetector.Gesture.SCROLL_UP else MotionDetector.Gesture.SCROLL_DOWN
)

5.4 Right‑click triggers too easily or not at all

Root cause: Tilt threshold or hold duration not tuned.

Solution: Adjust in Settings:

• Increase rightClickTilt (e.g., to 60°) to require more tilt.
• Increase rightClickDuration (e.g., 700 ms) to require longer hold.

---

6. Performance & Battery Issues

6.1 Phone gets hot and battery drains fast

Root cause: Sensor sampling at 50 Hz continuously, even when phone is not moving.

Solution: Enable battery saver (it is on by default). The app reduces sampling rate to 20 Hz after 10 seconds of no movement. To verify, look at BatterySaver logs.

Manual workaround: Stop Air Mouse when not in use (tap “Stop” or close the app).

6.2 PC server uses high CPU

Root cause: The asyncio event loop is busy, or the GUI log area grows too large.

Solution:

• Limit log area size (in gui.py, set a maximum line count).
• Use console server (server.py) if you don’t need GUI.

6.3 Cursor movement is choppy / stuttering

Root cause: Network jitter or PC CPU spikes.

Solutions:

• Lower sensor sampling rate (change SENSOR_DELAY_GAME to SENSOR_DELAY_NORMAL in SensorService.kt).
• On PC, close other resource‑heavy applications.

---

7. Build & Compilation Problems

7.1 ./gradlew: Permission denied (macOS/Linux)

Solution:

chmod +x gradlew

7.2 Gradle sync fails with “Could not resolve all dependencies”

Root cause: Internet restriction or missing repository.

Solution:

• Ensure you have internet access.
• If behind a proxy, set Gradle proxy settings in ~/.gradle/gradle.properties:

  systemProp.http.proxyHost=proxy.youruniversity.edu
  systemProp.http.proxyPort=8080
  

7.3 sdkmanager fails with “java.net.SocketException: Permission denied”

Root cause: Firewall or antivirus blocking sdkmanager.

Solution: Temporarily disable firewall, or run the script with admin privileges.

7.4 APK build succeeds but APK size is very small (<1 MB)

Root cause: Build failed silently, producing an empty or corrupted APK.

Check: Look for error messages in the build output. Common cause: missing Java or incorrect ANDROID_HOME.

Solution: Run ./gradlew assembleDebug --stacktrace to see full error.

---

8. Video Recording & Submission Issues

8.1 Video shows phone screen only, not laptop screen

Root cause: Only one camera used.

Solution:

• Use a second phone or a webcam to record both screens together.
• Or use screen mirroring software like scrcpy to show phone screen on laptop, then record the laptop screen only.

8.2 Video length exceeds 5 minutes

Root cause: Too much content.

Solution: Practice the script (provided in VIDEO_SCRIPT.md) – it fits within 5 minutes. Remove unnecessary pauses.

8.3 Perfetto trace file too large to submit

Root cause: Traces can be hundreds of MB.

Solution: Compress the trace (gzip or zip) before uploading. Or only submit a short trace (10 seconds) as requested.

---

9. Quick Reference – Common Solutions Summary

Problem	Most Likely Fix
pip install SOCKS error	unset http_proxy https_proxy
Connection refused	Check PC IP, firewall, server running
Cursor drifts	Re‑calibrate gyro (phone still on table)
Yaw drifts	Re‑calibrate magnetometer (figure‑8, 30s)
Click not detected	Lower clickSpeedThreshold in Settings
Scroll not working	Increase scrollSpeedThreshold or flick harder
App crashes on open	Check sensor availability, grant permissions
Green square doesn’t rotate	Ensure “Start Air Mouse” tapped
High battery drain	Enable battery saver (default on)
Build fails – Java not found	Install JDK 11, set JAVA_HOME

---

10. Getting Further Help

If none of the above solves your issue:

1. Collect logs:

   • Android: adb logcat -s AirMouse:* SensorService:* DataSender:*
   • PC server: check airmouse.log (console server) or the GUI log area.

2. Check the official exercise forum (if available) – your problem may have been answered.

3. Contact teaching assistants with:

   • Phone model and Android version.
   • PC OS and Python version.
   • Exact error message (screenshot or copy‑paste).
   • Steps you have already tried.

---

This troubleshooting guide is part of the Air Mouse Ultimate project – University of Tehran, Embedded Systems Exercise.
Keep it handy – it will save you hours of frustration.