Merge branch 'master' into codex/ios-background-central-homeform

Author: cagnulein

AGENTS.md

@@ -168,7 +168,7 @@ tst/Devices/
 - Platform-specific configuration paths
 - Profile system for multiple users/devices
 - Extensive customization options for device behavior
-- `src/settings-catalog.json` is the generated cross-platform catalog of every persistent setting declared in `src/settings.qml` and its settings child QML files. When adding, removing, or renaming any settings QML property, run `python tools/generate_settings_catalog.py` and then `python tools/generate_settings_catalog.py --check`. The check must report exact coverage before the change is complete.
+- `src/settings-catalog.json` is the manually maintained cross-platform catalog of every persistent setting declared in `src/settings.qml` and its settings child QML files. When adding, removing, or renaming any settings QML property, update `src/settings-catalog.json` by hand in the same change. Keep `settingCount` synchronized and add new settings at the end of the catalog.
 
 ## External Dependencies
 

docs/qz_faq_public.md

@@ -0,0 +1,117 @@
+# QZ (qdomyos-zwift) - Frequently Asked Questions
+
+## Getting Started / Builds
+
+### 1. Joining the beta program (Android)
+**Q: How can I join the QZ beta program / get the latest beta build?**
+
+For Android, join the beta here:
+https://play.google.com/apps/testing/org.cagnulen.qdomyoszwift
+Then update the app from the Play Store as usual.
+
+### 2. Trying a nightly/test build (APK)
+**Q: Can I try a fix or new feature before it's officially released?**
+
+Nightly debug builds are published here (replace the date with a recent one):
+https://github.com/cagnulein/qdomyos-zwift/releases/download/nightly-YYYY-MM-DD/android-debug.apk
+You can install this over your existing app without losing your settings.
+
+---
+
+## Integrations (Garmin, Google Fit, Zwift)
+
+### 3. Garmin integration
+**Q: How do I use QZ with my Garmin watch (e.g. to control treadmill speed/incline from a Garmin workout)?**
+
+Set your Garmin credentials in QZ. QZ will then download Garmin workouts
+directly and you can also push completed workouts back to Garmin
+automatically. You can also create workouts directly inside QZ.
+
+### 18. Apple Health - reading age/weight/heart rate zones automatically
+**Q: Can QZ read my age, weight, resting heart rate and HR zones automatically from Apple Health, so I don't have to update them manually?**
+
+Not currently - these values are entered manually under Settings > User and
+won't auto-update from Apple Health. If yours are out of date, update them
+there. Automatic syncing of this profile data from Apple Health is a
+possible future improvement.
+
+---
+
+## Device Compatibility
+
+### 7. Compatibility questions (new bike/treadmill/rower brand)
+**Q: Is my [bike/treadmill/rower] compatible with QZ / Zwift via QZ?**
+
+Most FTMS-compatible and many proprietary BLE trainers/treadmills/rowers are
+supported. You can try the trial version first. If your device isn't
+recognized, send a debug log so support for it can be added or fixed.
+
+### 19. Kinomap-compatible bikes (Kettler, Merach, and others)
+**Q: Does QZ work with bikes that connect to Kinomap (e.g. Kettler Racer S, Merach S28)?**
+
+Yes - any indoor bike that supports the Kinomap BLE protocol can connect
+to QZ using that protocol, with working auto resistance. This includes
+Kettler bikes and other brands such as Merach that use the same Kinomap
+BLE stack. Once QZ is connected, apps like Zwift, MyWhoosh and Rouvy can
+control resistance automatically through QZ.
+
+Try the trial first; if your bike isn't detected or resistance doesn't
+behave correctly, send a debug log.
+
+### 21. Speed shown in training app differs from bike console
+**Q: My bike console shows (e.g.) 25 km/h but the training app (Kinomap, Zwift, etc.) shows only 8 km/h - why?**
+
+These are two different things. The console speed is the actual flywheel/wheel
+speed. The training app's speed is a virtual estimate calculated from power
+output (watts) — it represents how fast you'd go on a flat road at that effort.
+QZ passes through whatever the bike reports over BLE; the discrepancy isn't
+something QZ can correct because it comes from how each app converts power to
+virtual speed.
+
+### 22. HR-linked speed control on treadmill
+**Q: Can QZ automatically adjust treadmill speed based on heart rate (e.g. reduce speed when HR is too high, restore it when HR drops)?**
+
+Yes - QZ has a heart rate linked speed feature in the treadmill settings. You
+can configure an HR threshold and speed adjustment so that when your HR goes
+above the target, QZ automatically reduces speed, and when it drops back down,
+QZ restores the original pace. This achieves the same effect as a simple
+HR-controlled interval loop.
+
+Sound alerts triggered by HR zone are not currently supported.
+
+---
+
+## Troubleshooting & Support
+
+### 9. Getting a debug log
+**Q: How do I get a debug log to send for troubleshooting?**
+
+Follow this guide:
+https://github.com/cagnulein/qdomyos-zwift/wiki/How-do-i-get-the-debug-log-in-case-something-doesn't-work%3F
+### 14. Calorie burn estimate looks way too high
+**Q: QZ shows an unrealistically high calorie burn (e.g. 30+ kcal/minute) - what's wrong?**
+
+Without a heart-rate monitor connected, QZ estimates calories from your
+speed/incline and the weight set in your profile. A very high value usually
+means the weight setting is wrong (e.g. entered in the wrong unit, kg vs
+lb) or the speed/incline readings themselves are unrealistic. Check
+Settings > User for your weight, and check the live speed/incline tiles. If
+those look correct and calories are still off, send a debug log.
+
+### 24. BLE advertising error on Android ("Cannot start advertising in ClosingState")
+**Q: QZ shows an "AdvertisingError / Cannot start advertising in ClosingState" in the debug log and another device (e.g. a second phone/tablet running a training app) can't find QZ via Bluetooth.**
+
+This is an Android BLE limitation triggered by long Bluetooth device names. Workaround:
+1. Go to Android Settings > About phone (or About tablet) > Device name.
+2. Rename the device to a **short name of 4 characters or fewer** (e.g. "tab1").
+3. Reboot the device.
+
+After the reboot, QZ should advertise correctly and be visible to other apps/devices.
+
+---
+
+### 25. Running QZ and Zwift on the same Mac (Apple Silicon / macOS)
+**Q: Can I run QZ and Zwift on the same MacBook (Apple Silicon, macOS Sequoia) to bridge my trainer?**
+
+Yes, QZ has a macOS build that runs on Apple Silicon. If you run into issues with your trainer not being detected or metrics not updating when both QZ and Zwift are on the same Mac, please share a debug log from a session that reproduces the problem so it can be diagnosed:
+https://github.com/cagnulein/qdomyos-zwift/wiki/How-do-i-get-the-debug-log-in-case-something-doesn't-work%3F

docs/settings-catalog.md

@@ -1,6 +1,6 @@
 # Settings Catalog
 
-`src/settings-catalog.json` is a generated catalog of every persistent setting declared in the settings QML files:
+`src/settings-catalog.json` is a manually maintained catalog of every persistent setting declared in the settings QML files:
 
 - `src/settings.qml`
 - `src/settings-tiles.qml`
@@ -48,16 +48,14 @@ Each virtual setting contains:
 
 ## Updating
 
-When adding, removing, or renaming a setting in any settings QML file, regenerate the catalog:
+When adding, removing, or renaming a setting in any settings QML file, update the catalog by hand in the same change.
 
-```bash
-python tools/generate_settings_catalog.py
-```
+For a new persistent setting:
 
-Then validate that the catalog still exactly covers the QML declarations:
+- Add the QML property at the end of the property list.
+- Add one matching entry to `src/settings-catalog.json`.
+- Increment top-level `settingCount`.
+- Keep `key`, `qmlType`, `defaultValue`, and `defaultExpression` aligned with the QML declaration.
+- Set `parent`, `name`, `description`, `control`, and `options` from the visible UI control.
 
-```bash
-python tools/generate_settings_catalog.py --check
-```
-
-The check fails if any QML setting is missing from the catalog, if the catalog contains an undeclared setting, if a setting is duplicated, or if declaration metadata no longer matches the QML sources.
+For a removed setting, delete its catalog entry and decrement `settingCount`. For a rename, update the catalog key in the same commit as the QML and `QZSettings` changes.

src/Home.qml

@@ -38,6 +38,18 @@ HomeForm {
         property string theme_tile_shadow_color: "#9C27B0"
         property int theme_tile_secondline_textsize: 12
         property bool skipLocationServicesDialog: false
+        property bool trainprogram_sound_on_segment: false
+    }
+
+    SoundEffect {
+        id: trainingProgramSegmentSound
+        source: "qrc:/sounds/training-program-segment.wav"
+        volume: 0.9
+    }
+
+    Connections {
+        target: rootItem
+        onTrainingProgramIntervalSoundRequested: trainingProgramSegmentSound.play()
     }
 
     MessageDialog {

src/android/src/CustomQtActivity.java

@@ -9,13 +9,16 @@
 import android.view.WindowInsets;
 import android.view.WindowManager;
 import android.view.DisplayCutout;
+import android.graphics.Insets;
 import org.qtproject.qt5.android.bindings.QtActivity;
 
 public class CustomQtActivity extends QtActivity {
     private static final String TAG = "CustomQtActivity";
 
     // Declare the native method that will be implemented in C++
-    private static native void onInsetsChanged(int top, int bottom, int left, int right);
+    private static native void onInsetsChanged(int top, int bottom, int left, int right,
+                                               int waterfallTop, int waterfallBottom,
+                                               int waterfallLeft, int waterfallRight);
     private static native void nativeOnOAuthCallback(String callbackUrl);
 
     private void dispatchOAuthCallback(Intent intent) {
@@ -63,6 +66,10 @@ public WindowInsets onApplyWindowInsets(View v, WindowInsets insets) {
                 int bottom = 0;
                 int left = 0;
                 int right = 0;
+                int waterfallTop = 0;
+                int waterfallBottom = 0;
+                int waterfallLeft = 0;
+                int waterfallRight = 0;
 
                 if (density > 0) {
                     // Use system window insets as primary source
@@ -80,6 +87,15 @@ public WindowInsets onApplyWindowInsets(View v, WindowInsets insets) {
                             right = Math.max(right, Math.round(cutout.getSafeInsetRight() / density));
                             top = Math.max(top, Math.round(cutout.getSafeInsetTop() / density));
                             bottom = Math.max(bottom, Math.round(cutout.getSafeInsetBottom() / density));
+
+                            // Android 11+ exposes curved waterfall display areas separately from cutouts.
+                            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                                Insets waterfallInsets = cutout.getWaterfallInsets();
+                                waterfallLeft = Math.round(waterfallInsets.left / density);
+                                waterfallRight = Math.round(waterfallInsets.right / density);
+                                waterfallTop = Math.round(waterfallInsets.top / density);
+                                waterfallBottom = Math.round(waterfallInsets.bottom / density);
+                            }
                         }
                     }
                 }
@@ -100,6 +116,13 @@ public WindowInsets onApplyWindowInsets(View v, WindowInsets insets) {
                               " Bottom:" + cutout.getSafeInsetBottom() + 
                               " Left:" + cutout.getSafeInsetLeft() + 
                               " Right:" + cutout.getSafeInsetRight());
+                        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                            Insets waterfallInsets = cutout.getWaterfallInsets();
+                            Log.d(TAG, "Waterfall insets - Top:" + waterfallInsets.top +
+                                  " Bottom:" + waterfallInsets.bottom +
+                                  " Left:" + waterfallInsets.left +
+                                  " Right:" + waterfallInsets.right);
+                        }
                     }
                 }
 
@@ -109,7 +132,7 @@ public WindowInsets onApplyWindowInsets(View v, WindowInsets insets) {
                 // forces edge-to-edge, triggering this before QtActivity finishes
                 // loading libqdomyos-zwift in its background thread).
                 try {
-                    onInsetsChanged(top, bottom, left, right);
+                    onInsetsChanged(top, bottom, left, right, waterfallTop, waterfallBottom, waterfallLeft, waterfallRight);
                 } catch (UnsatisfiedLinkError ignored) {
                     // Qt not ready yet; insets will be re-applied once Qt initializes.
                 }

src/android/src/HealthConnectHelper.kt

@@ -37,6 +37,7 @@ class HealthConnectHelper {
         private const val HEALTH_CONNECT_PROVIDER = "com.google.android.apps.healthdata"
         private const val PREFS_NAME = "qz_health_connect"
         private const val PREF_PERMISSION_PROMPT_PENDING = "permission_prompt_pending_v2"
+        private const val MIN_HRV_RMSSD_MILLIS = 1.0
 
         private var initialized = false
 
@@ -310,7 +311,7 @@ class HealthConnectHelper {
                         stepsCadenceSamples += StepsCadenceRecord.Sample(time = time, rate = cadence)
                     }
                 }
-                if (hasHrv && hrv > 0.0) {
+                if (hasHrv && hrv >= MIN_HRV_RMSSD_MILLIS) {
                     hrvRecords += HeartRateVariabilityRmssdRecord(
                         time = time,
                         zoneOffset = zoneOffset,

src/android/tests/org/cagnulen/qdomyoszwift/HealthConnectHelperTest.kt

@@ -327,6 +327,18 @@ class HealthConnectHelperTest {
         assertEquals(42.5, hrvRecords[0].heartRateVariabilityMillis, 0.001)
     }
 
+    @Test
+    fun `buildRecords omits HeartRateVariabilityRmssdRecord when hrv is below health connect minimum`() {
+        val samples = JSONArray().apply {
+            put(makeSample(1_000L, hrv = 0.9067155184426361))
+            put(makeSample(2_000L, hrv = 1.0))
+        }
+        val records = HealthConnectHelper.buildRecords(samples, "t", BIKE, null)
+        val hrvRecords = records.filterIsInstance<HeartRateVariabilityRmssdRecord>()
+        assertEquals(1, hrvRecords.size)
+        assertEquals(1.0, hrvRecords[0].heartRateVariabilityMillis, 0.001)
+    }
+
     @Test
     fun `buildRecords omits HeartRateVariabilityRmssdRecord when hrv is 0`() {
         val samples = JSONArray().apply { put(makeSample(1_000L)) }

src/androidstatusbar.cpp

@@ -38,27 +38,41 @@ int AndroidStatusBar::apiLevel() const
 #endif
 }
 
-void AndroidStatusBar::onInsetsChanged(int top, int bottom, int left, int right)
+void AndroidStatusBar::onInsetsChanged(int top, int bottom, int left, int right, int waterfallTop,
+                                        int waterfallBottom, int waterfallLeft, int waterfallRight)
 {
-    if (m_top != top || m_bottom != bottom || m_left != left || m_right != right) {
+    if (m_top != top || m_bottom != bottom || m_left != left || m_right != right ||
+        m_waterfallTop != waterfallTop || m_waterfallBottom != waterfallBottom ||
+        m_waterfallLeft != waterfallLeft || m_waterfallRight != waterfallRight) {
         m_top = top;
         m_bottom = bottom;
         m_left = left;
         m_right = right;
-        qDebug() << "Insets changed - Top:" << m_top << "Bottom:" << m_bottom << "Left:" << m_left << "Right:" << m_right;
+        m_waterfallTop = waterfallTop;
+        m_waterfallBottom = waterfallBottom;
+        m_waterfallLeft = waterfallLeft;
+        m_waterfallRight = waterfallRight;
+        qDebug() << "Insets changed - Top:" << m_top << "Bottom:" << m_bottom << "Left:" << m_left
+                 << "Right:" << m_right << "WaterfallTop:" << m_waterfallTop
+                 << "WaterfallBottom:" << m_waterfallBottom << "WaterfallLeft:" << m_waterfallLeft
+                 << "WaterfallRight:" << m_waterfallRight;
         emit insetsChanged();
     }
 }
 
 #ifdef Q_OS_ANDROID
 // JNI method with standard naming convention
 extern "C" JNIEXPORT void JNICALL
-Java_org_cagnulen_qdomyoszwift_CustomQtActivity_onInsetsChanged(JNIEnv *env, jobject thiz, jint top, jint bottom, jint left, jint right)
+Java_org_cagnulen_qdomyoszwift_CustomQtActivity_onInsetsChanged(JNIEnv *env, jobject thiz, jint top,
+                                                                    jint bottom, jint left, jint right,
+                                                                    jint waterfallTop, jint waterfallBottom,
+                                                                    jint waterfallLeft, jint waterfallRight)
 {
     Q_UNUSED(env);
     Q_UNUSED(thiz);
     if (AndroidStatusBar::instance()) {
-        AndroidStatusBar::instance()->onInsetsChanged(top, bottom, left, right);
+        AndroidStatusBar::instance()->onInsetsChanged(top, bottom, left, right, waterfallTop, waterfallBottom,
+                                                       waterfallLeft, waterfallRight);
     }
 }
 #endif

src/androidstatusbar.h

@@ -11,6 +11,11 @@ class AndroidStatusBar : public QObject
     Q_PROPERTY(int navigationBarHeight READ navigationBarHeight NOTIFY insetsChanged)
     Q_PROPERTY(int leftInset READ leftInset NOTIFY insetsChanged)
     Q_PROPERTY(int rightInset READ rightInset NOTIFY insetsChanged)
+    Q_PROPERTY(int waterfallTopInset READ waterfallTopInset NOTIFY insetsChanged)
+    Q_PROPERTY(int waterfallBottomInset READ waterfallBottomInset NOTIFY insetsChanged)
+    Q_PROPERTY(int waterfallLeftInset READ waterfallLeftInset NOTIFY insetsChanged)
+    Q_PROPERTY(int waterfallRightInset READ waterfallRightInset NOTIFY insetsChanged)
+    Q_PROPERTY(bool hasWaterfallDisplay READ hasWaterfallDisplay NOTIFY insetsChanged)
     Q_PROPERTY(int apiLevel READ apiLevel CONSTANT)
 
 public:
@@ -23,10 +28,16 @@ class AndroidStatusBar : public QObject
     int navigationBarHeight() const { return m_bottom; }
     int leftInset() const { return m_left; }
     int rightInset() const { return m_right; }
+    int waterfallTopInset() const { return m_waterfallTop; }
+    int waterfallBottomInset() const { return m_waterfallBottom; }
+    int waterfallLeftInset() const { return m_waterfallLeft; }
+    int waterfallRightInset() const { return m_waterfallRight; }
+    bool hasWaterfallDisplay() const { return m_waterfallTop > 0 || m_waterfallBottom > 0 || m_waterfallLeft > 0 || m_waterfallRight > 0; }
     int apiLevel() const;
 
 public slots:
-    void onInsetsChanged(int top, int bottom, int left, int right);
+    void onInsetsChanged(int top, int bottom, int left, int right, int waterfallTop, int waterfallBottom,
+                         int waterfallLeft, int waterfallRight);
 
 signals:
     void insetsChanged();
@@ -36,6 +47,10 @@ public slots:
     int m_bottom = 0;
     int m_left = 0;
     int m_right = 0;
+    int m_waterfallTop = 0;
+    int m_waterfallBottom = 0;
+    int m_waterfallLeft = 0;
+    int m_waterfallRight = 0;
 
     static AndroidStatusBar* m_instance;
 };