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

New Features in Ultimate Air Mouse – Complete Explanation

The Air Mouse Ultimate project includes many advanced features beyond the basic exercise requirements. This document explains each feature in detail: what it does, how it is implemented, why it matters, and how to customise it.

---

1. Auto‑Reconnect

Description:
When the WiFi connection between the phone and the PC server drops (e.g., router restart, signal loss), the Air Mouse app automatically attempts to reconnect every 5 seconds without requiring the user to manually restart the app.

How it works:

• The DataSender thread catches IOException during socket write operations and enters a retry loop.
• A separate AutoReconnect class (using a Handler) periodically checks the connection state and restarts the DataSender if needed.
• The retry uses the last known IP address (saved in preferences).

Why it matters:
Users don’t have to constantly check the connection. The Air Mouse resumes control as soon as the network is restored.

Customisation:
Adjust RECONNECT_DELAY_MS in DataSender.kt (default 5000 ms).

---

2. Sensitivity Slider

Description:
A SeekBar on the main screen allows adjusting the cursor speed from 0.2× (very slow) to 2.0× (very fast) in real time. The value is saved and persists across app restarts.

How it works:

• The slider’s position (0–100) is linearly mapped to sensitivity: sensitivity = 0.2 + (progress/100)*1.8.
• On each orientation update, the delta (dx, dy) is multiplied by this sensitivity.
• When the user stops touching the slider, the value is saved to PreferencesDataStore.

Why it matters:
Different users prefer different pointer speeds. This allows personalisation without code changes.

Implementation snippet (MainActivity.kt):

val sensitivity = 0.2f + (progress / 100f) * 1.8f
sensitivityText.text = String.format("%.2fx", sensitivity)

---

3. Double‑Click Gesture

Description:
Two quick flicks (around Y‑axis) within a configurable interval (default 400 ms) generate a double‑click. The phone vibrates (50 ms) and the green square flashes red.

How it works:

• The EnhancedGestureDetector maintains a potentialDoubleClick flag and a timer.
• On the first flick, a timer starts. If a second flick occurs before the timer expires, a double‑click is triggered.
• The interval is adjustable in Settings (200–1000 ms).

Why it matters:
Double‑click is a common desktop action (open files, select words). This gesture makes it natural.

Customisation:
Change doubleClickMaxInterval in PreferencesManager.

---

4. Right‑Click (Long Tilt)

Description:
Tilt the phone sideways (roll angle) beyond a threshold (default 45°) and hold for a duration (default 500 ms) to perform a right‑click. Haptic feedback (80 ms) and a visual flash confirm the action.

How it works:

• The detector monitors |roll| (absolute tilt).
• When the angle exceeds rightClickTiltAngle, a timer starts.
• If the angle remains above the threshold for rightClickDuration milliseconds, a right‑click message is sent to the PC.

Why it matters:
Right‑click opens context menus – essential for many applications. The long hold distinguishes it from normal cursor movement (which also uses roll but does not hold).

Customisation:
Adjust rightClickTiltAngle and rightClickDuration in Settings.

---

5. Debug Overlay

Description:
A floating window that shows real‑time sensor values: roll (degrees), yaw (degrees), gyroY (rad/s), accelY (m/s²). It can be toggled on/off without restarting the app.

How it works:

• DebugOverlayService runs as a background service and uses WindowManager to add a view with TYPE_APPLICATION_OVERLAY.
• The service is a singleton; any part of the app can call DebugOverlayService.update(roll, yaw, gyroY, accelY).
• The overlay is updated at the same rate as sensor events (≈50 Hz).

Why it matters:
Invaluable for debugging gesture thresholds and verifying calibration. You can see exactly why a gesture isn’t detected (e.g., gyroY too low).

Customisation:
Modify debug_overlay.xml for different colours, font, or position. Change params.gravity in DebugOverlayService.

---

6. Configurable Thresholds

Description:
All gesture detection parameters can be changed through the Settings dialog – no code recompilation needed. Changes take effect immediately.

Parameters adjustable:

• Click speed threshold (rad/s)
• Double‑click interval (ms)
• Right‑click tilt angle (degrees)
• Right‑click duration (ms)
• Scroll speed threshold (m/s²)
• Scroll debounce (m/s²)
• Haptic feedback on/off

How it works:

• The Settings dialog writes to PreferencesDataStore.
• EnhancedGestureDetector.reloadThresholds() reads the new values.
• The detector is used in SensorService on every sensor update.

Why it matters:
Every user has different movement patterns. This allows fine‑tuning without diving into code.

---

7. PC Server Configuration (config.json)

Description:
The console server (server.py) reads settings from a config.json file, allowing you to change the listening port, mouse sensitivity, log level, and log file path without editing code.

Example config.json:

{
    "host": "0.0.0.0",
    "port": 8080,
    "sensitivity": 0.5,
    "log_level": "INFO",
    "log_file": "airmouse.log"
}

How it works:
server.py loads the JSON file at startup. If the file doesn’t exist, it creates one with defaults. The MouseController uses the sensitivity from the config.

Why it matters:
Headless deployments, automated testing, or simply changing the port without modifying code.

Customisation:
Edit the JSON file in any text editor; restart the server for changes to take effect.

---

8. Battery Saver Mode

Description:
When the phone has been stationary for 10 seconds (no significant orientation change), the sensor sampling rate drops from 50 Hz (SENSOR_DELAY_GAME) to 20 Hz (SENSOR_DELAY_NORMAL). When movement resumes, the rate returns to 50 Hz.

How it works:

• BatterySaver monitors changes in roll and yaw.
• If the combined delta is less than a threshold for idleThresholdMs (10 s), it calls sensorService.setSamplingRate(SENSOR_DELAY_NORMAL).
• On movement, it restores the game rate.

Why it matters:
Significantly reduces battery drain when you leave the phone on the table but keep the app running.

Customisation:
Change idleThresholdMs in BatterySaver.kt.

---

9. Haptic Feedback

Description:
The phone vibrates briefly on successful gesture detection:

• Single click: 30 ms
• Double click: 50 ms
• Right click: 80 ms

The user can disable haptic feedback entirely via the Settings dialog.

How it works:
EnhancedGestureDetector calls vibrate(duration) when a gesture is detected. The method checks preferences.isHapticEnabled() before vibrating.

Why it matters:
Provides tactile confirmation, especially useful when you cannot see the screen (e.g., phone in your pocket). Disabling it saves battery.

---

10. Visual Click Flash

Description:
The green square (orientation indicator) turns red for 100 ms every time any click (left, double, right) occurs. This gives immediate visual feedback.

How it works:
In MainActivity, the gesture callback sets the square’s background colour to R.color.red, then posts a delayed runnable to set it back to R.color.green after 100 ms.

Why it matters:
Reinforces that the gesture was recognised, especially when the PC is not visible (e.g., phone held away from screen).

---

11. Scroll Inertia (Bonus)

Description:
A fast linear push (scrolling gesture) can generate multiple scroll events, simulating the effect of inertial scrolling – the page continues to scroll briefly after the push ends.

How it works (simplified):
When a scroll is detected, the app sends the initial scroll packet. If the acceleration remains high for a few consecutive frames, it sends additional scroll packets. (In the provided code, this is a basic version; more advanced inertia would use velocity decay.)

Why it matters:
Makes scrolling feel more natural, similar to touchpads or touchscreens.

Note: The basic implementation in the repository sends only one scroll per push. The “bonus” feature requires additional logic (e.g., using velocity to schedule follow‑up scrolls). This is left as an advanced exercise.

---

Summary Table of Features

Feature	Default	Adjustable?	Benefit
Auto‑reconnect	5 s delay	Yes (code)	Seamless recovery from network loss.
Sensitivity slider	0.5x	Yes (UI)	Personalise cursor speed.
Double‑click	400 ms interval	Yes (Settings)	Fast file/word selection.
Right‑click (tilt)	45° / 500 ms	Yes (Settings)	Context menus.
Debug overlay	Always off	Toggle button	Diagnose sensor issues.
Configurable thresholds	Various	Yes (Settings)	Adapt to different users.
PC server config	Port 8080, log INFO	Yes (config.json)	Easy server customisation.
Battery saver	10 s idle	Yes (code)	Extend battery life.
Haptic feedback	On	Yes (Settings)	Tactile confirmation.
Visual click flash	On (always)	Not adjustable	Immediate visual feedback.

---

These features transform the basic Air Mouse into a polished, user‑friendly, and highly customisable tool. Each feature is implemented in the code with clean separation of concerns, making it easy to understand and modify.

This document is part of the Air Mouse Ultimate project – University of Tehran, Embedded Systems Exercise.