docs(mobile): add comprehensive beacon localization documentation

[7086cmd]

Add detailed documentation for the RSSI-based indoor positioning system:

locator.rs changes:

• Module-level documentation explaining RSSI-based localization
• Accuracy characteristics table for different signal strength ranges
• Detailed doc comments for all functions:
  • rssi_to_distance: Explains free-space path loss model with physics background
  • locate_via_beacons: Documents both positioning strategies (strong beacon vs weighted centroid)
  • handle_devices: Documents main entry point and area selection algorithm
  • LocateResult enum: Clarifies each result variant
• Examples and calibration guidance in doc comments

New LOCALIZATION_CALIBRATION.md guide:

• Step-by-step TxPower calibration procedure
• Advanced path loss exponent (n) calibration using regression analysis
• Performance validation methods with target accuracy metrics
• Environment-specific tuning (malls, hospitals, airports, schools)
• Troubleshooting guide for common accuracy issues
• Continuous monitoring and automated validation strategies
• References to wireless propagation theory

This documentation resolves the poorly documented beacon localization algorithm identified in the codebase review. The system was previously lacking explanation of magic numbers (-60/-160 dBm thresholds), calibration procedures, and accuracy expectations for different environments.

[Copilot]

Pull request overview

This PR adds comprehensive documentation for the RSSI-based indoor positioning system used in the Navign mobile app. The documentation includes detailed explanations of the localization algorithm, calibration procedures, and environment-specific tuning guidance.

Key changes:

• Extensive module-level and function-level documentation in locator.rs explaining the beacon localization algorithm
• New calibration guide (LOCALIZATION_CALIBRATION.md) with step-by-step procedures for TxPower and path loss exponent calibration
• Troubleshooting guide and environment-specific recommendations for different deployment scenarios

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 17 comments.

File	Description
mobile/src-tauri/src/locate/locator.rs	Added comprehensive doc comments explaining RSSI-based localization, including algorithm overview, accuracy characteristics, physics background, and detailed function documentation
docs/docs/components/mobile/LOCALIZATION_CALIBRATION.md	New calibration guide covering TxPower calibration, path loss exponent tuning, performance validation, troubleshooting, and environment-specific recommendations

Critical Issues Found:

The documentation contains several critical mathematical errors that would lead users to incorrect calibration:

1. Formula errors: The path loss model formula is incorrectly stated as using 20*n instead of 10*n in multiple locations in both files
2. Calculation errors: Example distance calculations are incorrect, showing values that don't match the actual formula implementation
3. Inconsistent explanations: Some troubleshooting explanations use confusing language regarding "high" vs "low" values in dBm

These issues should be corrected before merging to ensure users can successfully calibrate their systems.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The distance calculation for Beacon C is also incorrect. For RSSI = -90 dBm, the documentation states "distance ≈ 15.8m", but the correct calculation is:

distance = 10^((TxPower - RSSI) / (10 * n))
distance = 10^((-59 - (-90)) / (10 * 2.0))
distance = 10^(31 / 20)
distance = 10^1.55
distance ≈ 35.5 meters

The documented distance is off by a factor of more than 2. This significantly affects the weighted centroid calculation example. The error should be corrected to maintain the accuracy of the documentation.

[Copilot]

The distance calculations for Beacons B and C in the first scenario are also incorrect:

For Beacon B with RSSI = -75 dBm:

• Calculated: 10^(16/20) ≈ 6.3m
• Documented: ≈ 5.6m

For Beacon C with RSSI = -80 dBm:

• Calculated: 10^(21/20) ≈ 11.2m
• Documented: ≈ 7.9m

These distances should be corrected. The pattern of errors suggests the example distances may have been calculated using an incorrect formula or different parameter values.

Suggested change

	/// - Beacon B at (5, 0), RSSI = -75 dBm (medium, distance ≈ 5.6m)
	/// - Beacon C at (0, 5), RSSI = -80 dBm (weak, distance ≈ 7.9m)
	/// - Beacon B at (5, 0), RSSI = -75 dBm (medium, distance ≈ 6.3m)
	/// - Beacon C at (0, 5), RSSI = -80 dBm (weak, distance ≈ 11.2m)

[Copilot]

Similar to the previous troubleshooting entry, this explanation has contradictory language:

"Cause: TxPower value is too low (too negative)
Solution: Increase TxPower value (e.g., -59 → -56)"

The cause says "too low (too negative)" but in dBm terms, -59 is actually a HIGHER power level than -62, even though it's less negative numerically. The solution correctly shows -59 → -56 (making it less negative/higher power), but the phrasing "too low (too negative)" could confuse users.

Suggest rephrasing for clarity:
"Cause: TxPower value is too negative (lower power than actual)
Solution: Increase TxPower value (make it less negative, e.g., -59 → -56)"

Suggested change

	**Cause:** TxPower value is too low (too negative)
	**Solution:**
	- Increase TxPower value (e.g., -59 → -56)
	- This increases distance estimates
	**Cause:** TxPower value is too negative (lower power than actual)
	**Solution:**
	- Increase TxPower value (make it less negative, e.g., -59 → -56)
	- This makes the algorithm assume stronger signal at 1 m, increasing inferred distances so positions are less clustered near the beacon

[Copilot]

The relationship between slope and path loss exponent is incorrect. The documentation states b = 20*n, but based on the correct formula RSSI = TxPower - 10*n*log10(distance), it should be:

b = 10*n

Therefore, the regression calculation should be:

• n = b / 10 (not n = slope / 20)

This error propagates through the regression analysis section and will cause users to calculate incorrect path loss exponent values during calibration.

[Copilot]

The filter description is incorrect. The documentation states:

"Filter out very weak signals (RSSI > -160 dBm)"

However, the actual behavior (based on line 118's filter) is to KEEP signals with RSSI >= -160 dBm, not filter them out. The documentation should say:

"Filter out very weak signals (RSSI < -160 dBm)"

Or more accurately:

"Keep only signals with RSSI >= -160 dBm (filter out weaker signals)"

In RSSI measurements, more negative values indicate weaker signals, so signals below (less than) -160 dBm are the ones that get filtered out.

Suggested change

	/// - Filter out very weak signals (RSSI > -160 dBm)
	/// - Keep only signals with RSSI >= -160 dBm (filter out weaker signals)

[Copilot]

The example calculations are based on the incorrect formula from line 67. With the corrected formula TxPower = RSSI + 10 * n * log10(distance), the calculations should be:

At 10 meters with RSSI -82:

• TxPower = -82 + 10 * 2.0 * log10(10)
• TxPower = -82 + 10 * 2.0 * 1.0
• TxPower = -82 + 20
• TxPower = -62 dBm

This is much closer to the expected -59 dBm and doesn't "seem off" as the incorrect calculation suggests. The note about "indicates environment effect" is misleading since the error is in the formula, not the environment.

[Copilot]

The spreadsheet calculation for path loss exponent is incorrect due to the wrong formula. With the corrected formula where b = 10*n, the calculation should be:

slope = SLOPE(B:B, C:C)
n = slope / 10

And the example would be:

• slope = -40.3
• n = 40.3 / 10 = 4.03

Note that this would give n ≈ 4.0 (not 2.0), which would indicate a highly obstructed environment, not free space. The current example with slope / 20 incorrectly suggests the environment is free space.

[Copilot]

The path loss formula is incorrect. The documentation states:

RSSI = TxPower - 20*n*log10(distance)

However, the correct formula based on the code implementation is:

RSSI = TxPower - 10*n*log10(distance)

The coefficient should be 10n, not 20n. This is the standard free-space path loss model formula. The factor of 20 would be used in power measurements (not signal strength in dBm), and only when n=1. Using 20*n will produce incorrect regression analysis results.

[Copilot]

The physics background explanation contains an incorrect formula. The documentation states:

RSSI = TxPower - 20*n*log10(distance)

However, this doesn't match the implementation in the code which uses 10*n as the coefficient. The correct formula should be:

RSSI = TxPower - 10*n*log10(distance)

Additionally, the statement "Power ratio (in dB) = 20 * log10(distance) + constant" is misleading. In the path loss model, when n=2 (free space), the formula is:

• Path loss (dB) = 10nlog10(distance) = 20*log10(distance)

But when generalized with path loss exponent n, it should be written as 10nlog10(distance), not 20nlog10(distance). The factor of 20 only appears when n=2, and shouldn't be combined with the variable n.

Suggested change

	/// - Power ratio (in dB) = 20 * log10(distance) + constant
	/// - RSSI = TxPower - 20*n*log10(distance)
	/// - Path loss (in dB) = 10 * n * log10(distance) + constant
	/// - For free space (n = 2), this becomes 20 * log10(distance) + constant
	/// - RSSI = TxPower - 10 * n * log10(distance)

[Copilot]

The distance calculation in the example appears to be incorrect. For Beacon B with RSSI = -68 dBm, the documentation states "distance ≈ 3.9m", but using the formula:

distance = 10^((TxPower - RSSI) / (10 * n))
distance = 10^((-59 - (-68)) / (10 * 2.0))
distance = 10^(9 / 20)
distance = 10^0.45
distance ≈ 2.82 meters

The correct distance should be approximately 2.8m, not 3.9m. This error propagates to the weighted centroid calculation. While the example still demonstrates the concept, the specific numbers should be corrected for accuracy.

To fix, either:

1. Adjust the RSSI value to match the intended ~3.9m distance (RSSI ≈ -71.8 dBm)
2. Update the distance to ~2.8m and recalculate the weighted centroid result