From 8b6fcced6616aa1798f84fbfa6207b405190ea22 Mon Sep 17 00:00:00 2001
From: Erik Andresen <erik@vontaene.de>
Date: Sun, 19 Feb 2023 11:13:41 +0100
Subject: [PATCH] gpsmagdir: Readme updates

---
 apps/gpsmagdir/README.md | 57 +++++++++++++++++++++++++++++++++-------
 apps/gpsmagdir/boot.js   |  6 ++---
 2 files changed, 50 insertions(+), 13 deletions(-)

diff --git a/apps/gpsmagdir/README.md b/apps/gpsmagdir/README.md
index b4c3acf0c..de7526ccd 100644
--- a/apps/gpsmagdir/README.md
+++ b/apps/gpsmagdir/README.md
@@ -1,12 +1,49 @@
-TODO:
-- Add Widget
+# GPS Compass heading switcher
+The GPS course and speed is calculated by the difference of positions.
+However GPS position is noisy and prone to jump around.
+This results in randomly jumping GPS course values when speed is slow or standing still.
+So in these cases a user might want to get his moving direction from a compass instead.
+This is why this app replaces the GPS heading with the compass heading when the speed is slower then 6 km/h (threshold is configurable, see settings).
+
+## Important Notes
+* **Watch orientation**
+  When the GPS is calculating the course the orientation of the watch does not matter.
+  When the Compass is used as the source of the current heading its top must obviously point at the moving direction (Usually away from you).
+* **Tilt compensation**
+  When "Navigation Compass" is installed the built-in compass gets automatic tilt compensation. This can be turned off in settings. Without "Navigation Compass" installed or this feature disabled the watch must be orientated with the display up to provide a useable compass value.
+* **Compass reset and calibration**
+  When using "Navigation Compass" as compass source (see settings) please remember to calibrate it regularly.
+  With this app installed the built-in compass calibration is automatically reset when the compass is turned on (deactivatable in settings). It can also be reset with a tap on the Widget (Bangle.js 2 only). Please note that directly after a reset the built-in compass must be turned 360 degrees to provide a useable value.
+* **True north vs magnetic north**
+  Please note that the compass does not point to the "real north" but depending on your location there is an offset, see [Magnetic declination](https://en.wikipedia.org/wiki/Magnetic_declination)
+  However the error from local magnetic interference and from calibration will probably be higher..
+
+## Widget
+The widget indicates if the current GPS heading is provided from GPS or compass.
+It can be turned off in the settings.
+On Bangle.js 2 a click on the widget does reset the built-in compass.
+
+## Settings
+* **speed**
+  - (default = 6 km/h) When lower then this use direction from compass
+* **compassSrc**
+  - off:
+  - built-in (default):
+  - Navigation Compass:
+* **reset compass on power on**
+  - off:
+  - on (default):
+* **tilt compensation**
+  - off:
+  - on (default):
+* **show Widget**
+  - Never
+  - Active (default): When replacing GPS course with compass course
+  - GPS on
+
+## TODO:
 - Add Settings
-- Test on BangleJS
 - Document settings with defaults
-- Document Widget
-- Write a summary why
-- Drop a note about compass north vs true north
-- Note that top of Bangle must point at moving direction when compass
-- Document uncompensated compass only when clock is faced up
-- Note to regularly calibrate compass before use
-- Note compass value not when NaN after calibration
+- Check magnav dependency in settings
+- note magnav silently downgrade
+- Test on BangleJS
diff --git a/apps/gpsmagdir/boot.js b/apps/gpsmagdir/boot.js
index 2ccdb4290..2195a8424 100644
--- a/apps/gpsmagdir/boot.js
+++ b/apps/gpsmagdir/boot.js
@@ -1,9 +1,9 @@
 {
   const settings = Object.assign({
     speed: 6, // when lower then this use direction from compass
-    compassSrc: 1, // [off, firmware, magnav]
+    compassSrc: 1, // [off, built-in, magnav]
     resetCompassOnPwr: true, // reset compass on power on
-    tiltCompensation: true, // tilt compensation on default compass
+    tiltCompensation: true, // tilt compensation on built-in compass
   }, require("Storage").readJSON("gpsmagdir.json", true) || {});
   const CALIBDATA = (settings.compassSrc === 2) ? require("Storage").readJSON("magnav.json",1) : undefined;
 
@@ -64,7 +64,7 @@
 
     const changeGpsCourse = (gps) => {
       if (gps.speed < settings.speed) {
-        if (settings.compassSrc === 1 && (settings.tiltCompensation || isFaceUp(Bangle.getAccel()))) { // Use uncompensated firmware heading only if face is up
+        if (settings.compassSrc === 1 && (settings.tiltCompensation || isFaceUp(Bangle.getAccel()))) { // Use uncompensated built-in compass heading only if face is up
           const heading = Bangle.getCompass().heading;
           if (!isNaN(heading)) {
             gps.courseOrig = gps.course;