feat(scroll): report a panel that cannot reach its refresh cap, and suggest one it can hold (#759)

* feat(scroll): report a panel that cannot reach its refresh cap, and suggest one it can hold Scroll speeds are solved against display.hardware.limit_refresh_rate_hz, which is only a ceiling. A panel that cannot reach it still moves whole pixels per frame, but every scroll runs slow by the shortfall and the "smooth" ladder is the cap's, not the panel's. A user rig (Pi 4, 2x128x64, adafruit-hat-pwm, pwm_bits 9, gpio_slowdown 5) measured 107.6-113.1 Hz under a 120 Hz cap: 60 px/s ran at 55, and nothing said why. - scroll_config: refresh_shortfall() (more than 3% under the planned rate), holdable_cap() (a multiple of 10, 5% under the measurement, since the measurement is the fast end of an uncapped panel's drift), and describe_refresh_shortfall(). - FrameTimingRecorder.plan_refresh(): once the measured period has held for three trusted windows, a shortfall is logged once as a warning naming the cap to use. DisplayManager calls it only for a real panel, not the emulator or the fallback canvas. The stats file records planned_refresh_hz (additive). - GET /api/v3/config/refresh-rate, plus a hint under the Display tab's Limit Refresh Rate field (js/pages/display.js) with a button that fills in the suggested cap. - _panel_refresh_hz (behind the Vegas slider's advice) ignores a measurement written under a different cap, so a changed cap stops being advised from the old rate before the display restarts. Verified on ledpi with a temporary 200 Hz cap: the warning logged about a minute after the restart ("about 132 Hz ... Set Limit Refresh Rate to 120 Hz"), the endpoint returned the same shortfall, and the Display tab showed the hint; its button filled in 120. ledpi was restored afterwards. Rebased onto main after the Display tab became an ES-module page (#771); the hint moved from inline script into display.js, with a jsdom test. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> * fix(scroll): count only agreeing windows toward the refresh shortfall; ignore a null planned rate Review fixes on #759. - A window the period estimate rejects (more than MAX_REFRESH_DROP faster than the adopted period) no longer counts toward the shortfall check, and it restarts the run. After a loaded start fixed a slow period, later windows at the real, faster rate were rejected yet still counted, so the warning could name the slow rate against a cap the panel was meeting. It now needs REFRESH_CHECK_WINDOWS consecutive windows that agree with the period. - _panel_refresh_hz treats a stats file whose planned_refresh_hz key is present but null as no measurement. The emulator and the fallback canvas write it that way (DisplayManager never plans a refresh for them), and their frame rate says nothing about the cap. A file with no such key (an older display) keeps the old behaviour. Three new tests fail on the previous code and pass now. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-10 00:56:35 +00:00 · 2026-10-09 10:40:08 -04:00
parent 370c8fe273
commit 1bcb524fc3
14 changed files with 458 additions and 5 deletions
@@ -158,11 +158,23 @@ def _panel_refresh_hz(config):
    cap = scroll_config.refresh_hz_from_config(config)
    try:
        with open(frame_timing.default_stats_path(), encoding='utf-8') as fh:
-            measured = float(json.load(fh).get('measured_refresh_hz') or 0)
+            stats = json.load(fh)
+        measured = float(stats.get('measured_refresh_hz') or 0)
+        recorded = 'planned_refresh_hz' in stats
+        planned = float(stats.get('planned_refresh_hz') or 0)
    except (OSError, ValueError, TypeError, AttributeError):
+        measured = planned = 0.0
+        recorded = False
+    # Reject a stale file from a previous hardware config: one written under
+    # another cap (the display has not restarted since it changed), or, from
+    # a display too old to record its cap (no such key), a measurement far
+    # off this one. A key that is present but null means the display's frames
+    # are not paced by a panel (the emulator, the fallback canvas): its
+    # "refresh rate" says nothing about the cap.
+    if recorded and not planned:
+        measured = 0.0
+    elif planned and abs(planned - cap) > 0.5:
        measured = 0.0
-    # Reject a stale file from a previous hardware config: a measurement far
-    # off the cap says the config changed since it was written.
    if measured > 0 and 0.5 * cap <= measured <= 1.5 * cap:
        return measured, 'measured'
    return cap, 'configured'
@@ -189,6 +201,29 @@ def get_scroll_speed_advice():
    return jsonify({'status': 'success', 'data': advice})


+@api_v3.route('/config/refresh-rate', methods=['GET'])
+def get_refresh_rate():
+    """The refresh cap, what the panel measured, and a cap it can hold.
+
+    Backs the hint under the Display tab's Limit Refresh Rate field. Scroll
+    speeds are solved against the cap, so a panel that cannot reach it runs
+    every scroll slow; ``shortfall`` (None when the panel keeps up, or nothing
+    has been measured yet) says by how much and suggests a cap.
+    """
+    from src.common import scroll_config
+    if not api_v3.config_manager:
+        return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500
+    config = api_v3.config_manager.load_config()
+    planned = scroll_config.refresh_hz_from_config(config)
+    hz, source = _panel_refresh_hz(config)
+    measured = hz if source == 'measured' else None
+    return jsonify({'status': 'success', 'data': {
+        'planned_hz': planned,
+        'measured_hz': round(measured, 1) if measured else None,
+        'shortfall': scroll_config.refresh_shortfall(measured, planned),
+    }})
+
+
@api_v3.route('/config/schedule', methods=['GET'])
 def get_schedule_config():
    """Get current schedule configuration"""
@@ -92,6 +92,45 @@ function refreshScrollSpeedHint(root, ctx) {
    }, HINT_DELAY_MS);
 }

+// ── the refresh-cap hint ─────────────────────────────────────────────────────
+// Scroll speeds are worked out against the cap, so a panel that cannot reach
+// it runs every scroll slow. The display has measured a cap it can hold.
+function showRefreshRateHint(root, ctx) {
+    const hint = root.querySelector('#limit_refresh_rate_hz_hint');
+    const input = root.querySelector('#limit_refresh_rate_hz');
+    if (!hint || !input) return;
+    const doc = root.ownerDocument;
+    const win = doc.defaultView;
+    ctx.api.get('/api/v3/config/refresh-rate', { signal: ctx.signal })
+        .then(function(body) {
+            const s = body.status === 'success' && body.data.shortfall;
+            hint.textContent = '';
+            if (!s) return;
+            hint.appendChild(doc.createTextNode(
+                'This panel refreshes at about ' + Math.round(s.measured_hz) +
+                ' Hz, below this ' + Math.round(s.planned_hz) + ' Hz cap, so scrolls run about ' +
+                s.slow_percent + '% slower than set.' + (s.suggested_cap_hz ? ' ' : '')));
+            if (!s.suggested_cap_hz) return;
+            const btn = doc.createElement('button');
+            btn.type = 'button';
+            btn.className = 'underline font-medium';
+            btn.textContent = 'Use ' + s.suggested_cap_hz + ' Hz';
+            btn.addEventListener('click', function() {
+                input.value = s.suggested_cap_hz;
+                input.dispatchEvent(new win.Event('input', { bubbles: true }));
+                input.dispatchEvent(new win.Event('change', { bubbles: true }));
+                hint.textContent = 'Save, then restart the display, to apply ' +
+                    s.suggested_cap_hz + ' Hz.';
+            });
+            hint.appendChild(btn);
+            hint.appendChild(doc.createTextNode(', a cap it can hold.'));
+        })
+        .catch(function(error) {
+            if (quiet(error) || error.body) return;
+            hint.textContent = '';
+        });
+}
+
 function renderScrollSpeedHint(root, hint, slider, a) {
    const doc = root.ownerDocument;
    const win = doc.defaultView;
@@ -303,6 +342,7 @@ export function init(root, ctx) {
    // when it already is), then every 5 s while it stays there.
    ctx.visibility.every(SYNC_POLL_MS, function() { pollSyncStatus(root, ctx); });

+    showRefreshRateHint(root, ctx);
    startPluginOrder(root, ctx);
    active = ctx;
 }
@@ -319,6 +319,7 @@
                           min="0"
                           max="1000"
                           class="form-control">
+                    <p id="limit_refresh_rate_hz_hint" class="mt-1 text-xs text-amber-700" aria-live="polite"></p>
                </div>
            </div>