Decide that cmd=start must report a refused start; record it and wait on the API for baselines

The maintainer's call (2026-08-28): /control?cmd=start answering {"result":
true} for a start the app refused is wrong, however the current wording
reads. openapi.yaml now says the result reflects whether the measurement
actually began, both control operations reference the new
`control-start-refused` entry, and that entry is `decided` with the
canonical behaviour and what each platform does today. Both app TODO files
carry the item; the entry goes when both agree.

Separately, --record-ble-baseline no longer reads stdin. Switching remote
access on is the operator's last step and is exactly what makes the phone
answer, so the tool waits for the API instead of for a keypress
(--record-wait, default 240 s). It runs the same whether or not anyone is
at the terminal it started from, which is what this session needs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Staacks

docs/remote-interface/openapi.yaml

@@ -260,12 +260,19 @@ paths:
       tags: [control]
       summary: Start, stop, clear, or write a value
       operationId: control
+      x-phyphox-inconsistency: [control-start-refused]
       description: |
         Sends a command to the running experiment. Always answers with
         `{"result": true}` or `{"result": false}`; the response says whether the
-        command was accepted, not whether it has finished taking effect.
+        command was accepted, not whether it has finished taking effect — except
+        for `start`, where the result must reflect whether the measurement
+        actually began (see `cmd=start` below).
 
         - `start` — begin measuring, or begin the countdown if timed run is on.
+          An experiment can refuse to start — most commonly because a Bluetooth
+          device it needs is not connected yet — and the result is then `false`.
+          A client that must be certain can also read `status.measuring` from a
+          subsequent `/get`.
         - `stop` — stop measuring.
         - `clear` — discard buffered data, stopping the measurement if it is running.
         - `set` — write a single value into a buffer. This is how the remote
@@ -326,6 +333,7 @@ paths:
       tags: [control]
       summary: Start, stop, clear, or write a value (POST)
       operationId: controlPost
+      x-phyphox-inconsistency: [control-start-refused]
       description: |
         Identical to `GET /control`, with the command and its parameters in the
         request body, e.g. `{"cmd": "set", "buffer": "height", "value": 1.87}`.
@@ -737,7 +745,10 @@ components:
       properties:
         result:
           type: boolean
-          description: Whether the command was accepted.
+          description: |
+            Whether the command was accepted. For `cmd=start` this means the
+            measurement actually began: a start the experiment refuses answers
+            `false`.
 
     SetResult:
       type: object

inconsistencies.yml

@@ -89,3 +89,37 @@
     A non-power-of-two number of input samples yields a different output
     length and different values on the two platforms; a power-of-two input
     gives identical results on both.
+
+- id: control-start-refused
+  title: 'A refused start still answers {"result": true}'
+  area: remote-interface
+  status: decided
+  canonical: >-
+    `/control?cmd=start` must answer `{"result": false}` when the experiment
+    was not started. Whether a start succeeds is not something a remote client
+    can otherwise determine: the only other signal is `status.measuring` in a
+    subsequent `/get`, which requires a second request and a race-free moment
+    to make it in.
+  affects:
+    android: >-
+      Answers `{"result": true}` for a start the app refused. Observed on a
+      Pixel 3 with a Bluetooth experiment whose device was not yet fully
+      connected: the app put "The Bluetooth device is not connected. Experiment
+      can not be started." on screen, `status.measuring` stayed false, and
+      `/control?cmd=start` reported success.
+    ios: >-
+      Same shape - the result reports that the command was accepted rather than
+      that the measurement began. Not re-verified on hardware for this entry.
+  verified: >-
+    2026-08-27, Android development build on a Pixel 3 against an ESP32 running
+    the Arduino randomNumbers example (phyphox-docs device lab, ble suite).
+  summary: >-
+    A client that starts an experiment over the remote interface cannot tell
+    from the answer whether it is running. The documented meaning of `result`
+    is "whether the command was accepted", and both apps answer that
+    literally - a start that the app then refuses, because a Bluetooth device
+    is not connected or another precondition fails, is still reported as
+    successful. The maintainer decided (2026-08-28) that the result must
+    reflect whether the measurement actually started. Until both apps are
+    fixed, poll `status.measuring` from `/get` to confirm a start rather than
+    trusting the answer.

tools/lab/ble.py

@@ -1162,6 +1162,11 @@ def record_baselines(devices, args):
     remote access on, and then does the measuring and the writing itself.
     Ten scenarios is ten pauses; this happens once per reference release,
     not per run.
+
+    The wait is for the REMOTE API, not for a keypress: switching remote
+    access on is the operator's last step and is precisely what makes the
+    phone answer, so the tool needs no terminal of its own and the
+    operator needs no second action to say "done".
     """
     import datetime
     cfg = load_scenarios()
@@ -1198,24 +1203,23 @@ def record_baselines(devices, args):
             print(f"   !! {msg}")
             failed.append(f"{label}: {msg}")
             continue
+        # The operator's own actions ARE the signal, so nothing is read
+        # from stdin: switching remote access on is the last step, and it
+        # is exactly what makes the API answer. Waiting for that instead
+        # of for a keypress means this runs the same way whether a person
+        # is at a terminal or driving it from somewhere else.
         print(f"   On {dev_id}, by hand:\n"
               f"     1. add an experiment for a Bluetooth device and pick "
               f"{name!r}\n"
               f"     2. let it load, then switch remote access on from the "
               f"menu\n"
-              f"   Enter to record, or 's' to skip this scenario: ", end="",
-              flush=True)
-        try:
-            if (input().strip().lower() or "") == "s":
-                failed.append(f"{label}: skipped by the operator")
-                continue
-        except EOFError:
-            print("\n!! not an interactive terminal - this mode needs one")
-            return 1
+              f"   waiting up to {args.record_wait:.0f} s for the phone to "
+              f"start serving...", flush=True)
 
-        if wait_api(dev.base, args.api_wait) is None:
-            print("   !! the phone is not serving the remote API - is remote "
-                  "access on, and on this network?")
+        if wait_api(dev.base, args.record_wait) is None:
+            print("   !! nothing served within the wait - skipping this one. "
+                  "Remote access not switched on, a different network, or "
+                  "the experiment did not load")
             failed.append(f"{label}: no remote API")
             continue
         meta = {}

tools/lab/run.py

@@ -356,6 +356,11 @@ def main():
                          "automation seam, so a human connects the phone "
                          "and switches remote access on for each scenario. "
                          "Pass one --devices id")
+    ap.add_argument("--record-wait", type=float, default=240.0,
+                    help="--record-ble-baseline: seconds to wait per scenario "
+                         "for the operator to connect the phone and switch "
+                         "remote access on. The API answering IS the signal; "
+                         "nothing is read from stdin")
     ap.add_argument("--ble-scenario", metavar="[LIB/]EXAMPLE",
                     help="ble suite: run only this scenario (bring-up and "
                          "debugging - the report is marked as narrowed)")