robopark 3.3.37 → 3.3.39

package/vision/app_pi_clean.py

@@ -1,79 +1,274 @@
 from flask import Flask, Response, jsonify, request
 from flask_cors import CORS
-import argparse
-import glob
-import cv2
+import argparse
+import glob
+import cv2
 import os
 import sys
 import time
 import numpy as np
-import threading
-import requests
-import base64
-import struct
+import threading
+import requests
+import base64
+import struct
+import subprocess
 
 app = Flask(__name__)
 CORS(app)
 
-# Camera management. Production installs create /dev/robopark-camera from
-# the primary USB capture interface, avoiding /dev/videoN renumbering.
-def _normalize_camera_device(value):
-    configured = str(value or "").strip()
-    if configured.lower() in ("", "auto", "default", "first"):
-        if sys.platform.startswith("linux"):
-            return "/dev/robopark-camera" if os.path.exists("/dev/robopark-camera") else "/dev/video0"
-        return 0
-    if configured.isdigit():
-        return int(configured)
-    return configured
-
-
-_configured_camera = os.getenv("ROBOPARK_CAMERA_DEVICE", "")
-current_camera_index = _normalize_camera_device(_configured_camera)
-camera = None
-camera_lock = threading.Lock()
-frame_condition = threading.Condition()
-latest_frame_bytes = None
-latest_frame_sequence = 0
-camera_worker_started = False
-camera_read_started_at = 0.0
-camera_last_frame_at = 0.0
-audio_input_device = "default"
-audio_output_device = "default"
-ROBOVISION_AUDIO_URL = os.getenv("ROBOVISION_AUDIO_URL", "http://127.0.0.1:8000")
-_camera_inventory_cache = []
-_camera_inventory_cache_at = 0.0
-CAMERA_INVENTORY_CACHE_SECONDS = 30.0
-
-def _open_camera(index):
-    # On Windows, cv2.VideoCapture(index) with no explicit backend can
-    # auto-probe into an unrelated backend (e.g. Orbbec's "obsensor") that
-    # fails with "Camera index out of range" for a perfectly normal UVC
-    # webcam — isOpened() then stays False forever and callers retry in an
-    # infinite doomed loop. Force DirectShow, the backend that actually
-    # enumerates standard Windows webcams.
-    if sys.platform == 'win32':
-        return cv2.VideoCapture(index, cv2.CAP_DSHOW)
-    if sys.platform.startswith('linux'):
-        cap = cv2.VideoCapture(index, cv2.CAP_V4L2)
-        if cap.isOpened():
-            cap.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc(*'MJPG'))
-            cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)
-            cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)
-            cap.set(cv2.CAP_PROP_FPS, 15)
-        return cap
-    return cv2.VideoCapture(index)
+# Camera management. Production installs create /dev/robopark-camera from
+# the primary USB capture interface, avoiding /dev/videoN renumbering.
+def _normalize_camera_device(value):
+    configured = str(value or "").strip()
+    if configured.lower() in ("", "auto", "default", "first"):
+        if sys.platform.startswith("linux"):
+            return "/dev/robopark-camera" if os.path.exists("/dev/robopark-camera") else "/dev/video0"
+        # Off-Pi we scan instead of assuming index 0: a Windows kiosk with a
+        # virtual/IR device in the way exposes the real webcam at 1 or 2.
+        return "auto"
+    if configured.isdigit():
+        return int(configured)
+    return configured
+
+
+_configured_camera = os.getenv("ROBOPARK_CAMERA_DEVICE", "")
+current_camera_index = _normalize_camera_device(_configured_camera)
+camera = None
+camera_lock = threading.Lock()
+frame_condition = threading.Condition()
+latest_frame_bytes = None
+latest_frame_sequence = 0
+camera_worker_started = False
+camera_watchdog_started = False
+camera_read_started_at = 0.0
+camera_last_frame_at = 0.0
+audio_input_device = "default"
+audio_output_device = "default"
+ROBOVISION_AUDIO_URL = os.getenv("ROBOVISION_AUDIO_URL", "http://127.0.0.1:8000")
+_camera_inventory_cache = []
+_camera_inventory_cache_at = 0.0
+CAMERA_INVENTORY_CACHE_SECONDS = 30.0
+_camera_name_cache = []
+_camera_name_cache_at = 0.0
+CAMERA_NAME_CACHE_SECONDS = 30.0
+
+CAMERA_SCAN_MAX_INDEX = int(os.getenv("ROBOPARK_CAMERA_SCAN_MAX", "3"))
+CAMERA_OPEN_MAX_ATTEMPTS = int(os.getenv("ROBOPARK_CAMERA_OPEN_ATTEMPTS", "3"))
+CAMERA_FIRST_FRAME_TRIES = 5
+CAMERA_FIRST_FRAME_DELAY = 0.15
+
+active_camera_device = None
+active_camera_backend = None
+camera_open_attempts = []
+camera_open_error = None
+
+
+def _camera_backends():
+    """Backends to try, in the order most likely to bind on this platform.
+
+    Windows leads with Media Foundation because that is the stack Chrome's
+    getUserMedia uses, and the kiosk that fails here streams fine in the
+    browser. DirectShow alone logs "backend is generally available but can't
+    be used to capture by index" and never binds on that hardware; it stays as
+    the second try because some older UVC bridges only enumerate there.
+    Linux/Pi keeps V4L2 first — unchanged from the original behaviour.
+    """
+    if sys.platform == 'win32':
+        return [
+            (getattr(cv2, 'CAP_MSMF', cv2.CAP_ANY), 'msmf'),
+            (getattr(cv2, 'CAP_DSHOW', cv2.CAP_ANY), 'dshow'),
+            (cv2.CAP_ANY, 'default'),
+        ]
+    if sys.platform.startswith('linux'):
+        return [(getattr(cv2, 'CAP_V4L2', cv2.CAP_ANY), 'v4l2'), (cv2.CAP_ANY, 'default')]
+    return [(cv2.CAP_ANY, 'default')]
+
+
+def _tune_capture(cap):
+    if sys.platform.startswith('linux'):
+        cap.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc(*'MJPG'))
+        cap.set(cv2.CAP_PROP_FPS, 15)
+    cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)
+    cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)
+
+
+def _capture_yields_frame(cap):
+    """isOpened() is not proof of a working camera — MSMF/DSHOW both hand back
+    an "open" handle that never decodes a frame. Only a real read counts."""
+    for _ in range(CAMERA_FIRST_FRAME_TRIES):
+        try:
+            success, frame = cap.read()
+        except Exception as exc:
+            return False, f"read() raised {exc}"
+        if success and frame is not None and getattr(frame, 'size', 0):
+            return True, None
+        time.sleep(CAMERA_FIRST_FRAME_DELAY)
+    return False, f"opened but produced no frame in {CAMERA_FIRST_FRAME_TRIES} reads"
+
+
+def _open_camera(index, backend=None):
+    """Open one device with one backend. Returns the capture (possibly closed)."""
+    if backend is None:
+        backend = _camera_backends()[0][0]
+    cap = cv2.VideoCapture(index, backend)
+    if cap.isOpened():
+        _tune_capture(cap)
+    return cap
+
+
+def _windows_camera_names():
+    """Friendly camera names from Windows PnP, via PowerShell (no new deps).
+
+    OpenCV exposes no device-name API, so the correlation to indices is
+    positional and therefore HEURISTIC: the Nth camera PnP entity is assumed
+    to be OpenCV index N. That holds on the usual one-or-two-camera kiosk but
+    can be wrong when virtual cameras, IR sensors or non-UVC 'Image' devices
+    are installed. Selecting by index is always exact; selecting by name
+    depends on this guess.
+    """
+    script = (
+        "Get-CimInstance Win32_PnPEntity -ErrorAction SilentlyContinue | "
+        "Where-Object { $_.PNPClass -eq 'Camera' -or $_.PNPClass -eq 'Image' } | "
+        "ForEach-Object { $_.Name }"
+    )
+    try:
+        completed = subprocess.run(
+            ["powershell", "-NoProfile", "-NonInteractive", "-Command", script],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            creationflags=getattr(subprocess, 'CREATE_NO_WINDOW', 0),
+        )
+    except Exception as exc:
+        print(f"Camera name enumeration failed: {exc}")
+        return []
+    return [line.strip() for line in (completed.stdout or "").splitlines() if line.strip()]
+
+
+def _camera_names():
+    global _camera_name_cache, _camera_name_cache_at
+    now = time.monotonic()
+    if now - _camera_name_cache_at < CAMERA_NAME_CACHE_SECONDS:
+        return _camera_name_cache
+    names = _windows_camera_names() if sys.platform == 'win32' else []
+    _camera_name_cache = names
+    _camera_name_cache_at = now
+    return names
+
+
+def _match_device_name(wanted):
+    """Resolve a human-typed camera name to device values.
+
+    Same matching rules as the microphone picker in audio-select.ts: exact
+    case-insensitive first, then a unique substring; ambiguity resolves to
+    nothing rather than a coin flip.
+    """
+    lower = wanted.strip().lower()
+    if not lower:
+        return []
+    if sys.platform.startswith('linux'):
+        pairs = [(entry.get("name", ""), entry.get("id")) for entry in _enumerate_cameras()]
+    else:
+        pairs = [(name, index) for index, name in enumerate(_camera_names())]
+    exact = [value for name, value in pairs if name.lower() == lower]
+    if len(exact) == 1:
+        return exact
+    partial = [value for name, value in pairs if lower in name.lower()]
+    if len(partial) == 1:
+        return partial
+    return []
+
+
+def _camera_candidates(device):
+    """Device values to try, in order, for the currently configured selection."""
+    text = str(device).strip()
+    if text.lower() == 'auto':
+        return list(range(CAMERA_SCAN_MAX_INDEX + 1))
+    if text.isdigit():
+        return [int(text)]
+    if text.startswith('/dev/') or os.path.sep in text:
+        return [text]
+    return _match_device_name(text)
+
+
+def _acquire_camera():
+    """Try every candidate device against every backend until one yields a frame.
+
+    Returns (capture, device, backend_label, attempt_log). `capture` is None if
+    nothing worked; the log names every backend/index pair that was tried and
+    why it failed, so the operator is not left guessing.
+    """
+    attempts = []
+    candidates = _camera_candidates(current_camera_index)
+    if not candidates:
+        known = ", ".join(_camera_names()) or "(none reported by the OS)"
+        attempts.append(f"no camera matches name {current_camera_index!r}; OS reports: {known}")
+        return None, None, None, attempts
+
+    for device in candidates:
+        for backend, label in _camera_backends():
+            cap = None
+            try:
+                cap = cv2.VideoCapture(device, backend)
+            except Exception as exc:
+                attempts.append(f"{label}:{device} VideoCapture() raised {exc}")
+                continue
+            if not cap.isOpened():
+                attempts.append(f"{label}:{device} isOpened()=False")
+                cap.release()
+                continue
+            _tune_capture(cap)
+            ok, reason = _capture_yields_frame(cap)
+            if ok:
+                return cap, device, label, attempts
+            attempts.append(f"{label}:{device} {reason}")
+            cap.release()
+    return None, None, None, attempts
 
 
 def get_camera():
-    global camera, current_camera_index
-    if camera is None or not camera.isOpened():
-        camera = _open_camera(current_camera_index)
-        camera.set(cv2.CAP_PROP_FRAME_WIDTH, 640)
-        camera.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)
-        print(f"Camera {current_camera_index} initialized")
+    global camera, active_camera_device, active_camera_backend
+    global camera_open_attempts, camera_open_error
+    if camera is not None and camera.isOpened():
+        return camera
+
+    cap, device, backend, attempts = _acquire_camera()
+    camera_open_attempts = attempts
+    if cap is None:
+        camera = None
+        active_camera_device = None
+        active_camera_backend = None
+        camera_open_error = "; ".join(attempts) or "no candidate devices"
+        return None
+
+    camera = cap
+    active_camera_device = device
+    active_camera_backend = backend
+    camera_open_error = None
+    for failure in attempts:
+        print(f"Camera probe skipped {failure}")
+    print(f"Camera opened: device={device} backend={backend}")
     return camera
 
+
+def _report_camera_unavailable():
+    backends = "/".join(label for _, label in _camera_backends())
+    candidates = _camera_candidates(current_camera_index)
+    listed = ", ".join(str(c) for c in candidates) or "(none)"
+    print("=" * 60)
+    print("CAMERA UNAVAILABLE - giving up after "
+          f"{CAMERA_OPEN_MAX_ATTEMPTS} attempts")
+    print(f"  configured device : {current_camera_index}")
+    print(f"  backends tried    : {backends}")
+    print(f"  devices tried     : {listed}")
+    for failure in camera_open_attempts or ["(no candidate devices to try)"]:
+        print(f"  - {failure}")
+    print("  OS-reported cameras: " + (", ".join(_camera_names()) or "(none)"))
+    print("  Fix: plug in / free the camera, then POST /api/camera/switch "
+          "(or restart). Set ROBOPARK_CAMERA_DEVICE to a name or index; "
+          "GET /api/media/inventory lists what this machine can see.")
+    print("=" * 60)
+
 # Global variables
 latest_detections = []
 lock = threading.Lock()
@@ -252,39 +447,52 @@ def send_webhook(frame_data):
     except Exception as e:
         print(f"Error preparing webhook: {e}")
 
-def camera_worker():
-    global latest_detections, motion_detection_active, motion_detected_state
-    global last_motion_time, motion_frame_buffer
-    global latest_frame_bytes, latest_frame_sequence
-    global camera_read_started_at, camera_last_frame_at, camera
-
-    prev_gray = None
-
-    while True:
-        with camera_lock:
-            cam = get_camera()
-        if cam is None or not cam.isOpened():
-            time.sleep(1)
-            continue
-
-        camera_read_started_at = time.monotonic()
-        try:
-            # This is the only camera reader. Do not hold camera_lock here:
-            # the watchdog must be able to release a wedged V4L2 handle.
-            success, frame = cam.read()
-        except Exception as exc:
-            print(f"Camera read error: {exc}")
-            success, frame = False, None
-        finally:
-            camera_read_started_at = 0.0
-        if not success:
-            with camera_lock:
-                if camera is cam:
-                    camera.release()
-                    camera = None
-            time.sleep(0.1)
-            continue
-        camera_last_frame_at = time.monotonic()
+def camera_worker():
+    global latest_detections, motion_detection_active, motion_detected_state
+    global last_motion_time, motion_frame_buffer
+    global latest_frame_bytes, latest_frame_sequence
+    global camera_read_started_at, camera_last_frame_at, camera
+
+    global camera_worker_started
+
+    prev_gray = None
+    failed_opens = 0
+
+    while True:
+        with camera_lock:
+            cam = get_camera()
+        if cam is None or not cam.isOpened():
+            failed_opens += 1
+            if failed_opens >= CAMERA_OPEN_MAX_ATTEMPTS:
+                # Bounded, not infinite: a doomed 1/sec retry loop buries the
+                # real error. Clearing the started flag lets an explicit
+                # /api/camera/switch or a new /video_feed request try again.
+                _report_camera_unavailable()
+                with frame_condition:
+                    camera_worker_started = False
+                return
+            time.sleep(1)
+            continue
+        failed_opens = 0
+
+        camera_read_started_at = time.monotonic()
+        try:
+            # This is the only camera reader. Do not hold camera_lock here:
+            # the watchdog must be able to release a wedged V4L2 handle.
+            success, frame = cam.read()
+        except Exception as exc:
+            print(f"Camera read error: {exc}")
+            success, frame = False, None
+        finally:
+            camera_read_started_at = 0.0
+        if not success:
+            with camera_lock:
+                if camera is cam:
+                    camera.release()
+                    camera = None
+            time.sleep(0.1)
+            continue
+        camera_last_frame_at = time.monotonic()
 
         # Run object detection
         processed_frame, detections = detect_objects(frame, conf_threshold=0.5)
@@ -333,59 +541,64 @@ def camera_worker():
 
             prev_gray = gray
 
-        ret, buffer = cv2.imencode('.jpg', processed_frame, [cv2.IMWRITE_JPEG_QUALITY, 80])
-        if not ret:
-            continue
-        with frame_condition:
-            latest_frame_bytes = buffer.tobytes()
-            latest_frame_sequence += 1
-            frame_condition.notify_all()
-
-
-def _ensure_camera_worker():
-    global camera_worker_started
-    with frame_condition:
-        if camera_worker_started:
-            return
-        camera_worker_started = True
-    threading.Thread(target=camera_worker, name='robovision-camera', daemon=True).start()
-    threading.Thread(target=_camera_watchdog, name='robovision-camera-watchdog', daemon=True).start()
-
-
-def _camera_watchdog():
-    global camera, camera_read_started_at
-    while True:
-        time.sleep(2.0)
-        started = camera_read_started_at
-        if not started or time.monotonic() - started < 8.0:
-            continue
-        print("Camera read stalled for 8s; releasing V4L2 handle")
-        with camera_lock:
-            if camera is not None:
-                try:
-                    camera.release()
-                except Exception:
-                    pass
-                camera = None
-        camera_read_started_at = 0.0
-
-
-def generate_frames():
-    _ensure_camera_worker()
-    sequence = -1
-    while True:
-        with frame_condition:
-            frame_condition.wait_for(
-                lambda: latest_frame_bytes is not None and latest_frame_sequence != sequence,
-                timeout=5.0,
-            )
-            if latest_frame_bytes is None or latest_frame_sequence == sequence:
-                continue
-            frame_bytes = latest_frame_bytes
-            sequence = latest_frame_sequence
-
-        yield (b'--frame\r\n'
-               b'Content-Type: image/jpeg\r\n\r\n' + frame_bytes + b'\r\n')
+        ret, buffer = cv2.imencode('.jpg', processed_frame, [cv2.IMWRITE_JPEG_QUALITY, 80])
+        if not ret:
+            continue
+        with frame_condition:
+            latest_frame_bytes = buffer.tobytes()
+            latest_frame_sequence += 1
+            frame_condition.notify_all()
+
+
+def _ensure_camera_worker():
+    global camera_worker_started, camera_watchdog_started
+    with frame_condition:
+        if camera_worker_started:
+            return
+        camera_worker_started = True
+        start_watchdog = not camera_watchdog_started
+        camera_watchdog_started = True
+    threading.Thread(target=camera_worker, name='robovision-camera', daemon=True).start()
+    if start_watchdog:
+        # The worker can restart after a bounded open failure; the watchdog is
+        # stateless and must not be duplicated each time it does.
+        threading.Thread(target=_camera_watchdog, name='robovision-camera-watchdog', daemon=True).start()
+
+
+def _camera_watchdog():
+    global camera, camera_read_started_at
+    while True:
+        time.sleep(2.0)
+        started = camera_read_started_at
+        if not started or time.monotonic() - started < 8.0:
+            continue
+        print("Camera read stalled for 8s; releasing V4L2 handle")
+        with camera_lock:
+            if camera is not None:
+                try:
+                    camera.release()
+                except Exception:
+                    pass
+                camera = None
+        camera_read_started_at = 0.0
+
+
+def generate_frames():
+    _ensure_camera_worker()
+    sequence = -1
+    while True:
+        with frame_condition:
+            frame_condition.wait_for(
+                lambda: latest_frame_bytes is not None and latest_frame_sequence != sequence,
+                timeout=5.0,
+            )
+            if latest_frame_bytes is None or latest_frame_sequence == sequence:
+                continue
+            frame_bytes = latest_frame_bytes
+            sequence = latest_frame_sequence
+
+        yield (b'--frame\r\n'
+               b'Content-Type: image/jpeg\r\n\r\n' + frame_bytes + b'\r\n')
 
 @app.route('/')
 def index():
@@ -395,23 +608,27 @@ def index():
 def video_feed():
     return Response(generate_frames(), mimetype='multipart/x-mixed-replace; boundary=frame')
 
-@app.route('/api/detections')
-def get_detections():
-    with lock:
-        return jsonify(latest_detections)
-
-
-@app.route('/api/camera/status')
-def camera_status():
-    age = None if not camera_last_frame_at else round(time.monotonic() - camera_last_frame_at, 3)
-    return jsonify({
-        "device": str(current_camera_index),
-        "open": bool(camera is not None and camera.isOpened()),
-        "worker_started": camera_worker_started,
-        "frame_sequence": latest_frame_sequence,
-        "last_frame_age_seconds": age,
-        "read_stalled": bool(camera_read_started_at and time.monotonic() - camera_read_started_at >= 8.0),
-    })
+@app.route('/api/detections')
+def get_detections():
+    with lock:
+        return jsonify(latest_detections)
+
+
+@app.route('/api/camera/status')
+def camera_status():
+    age = None if not camera_last_frame_at else round(time.monotonic() - camera_last_frame_at, 3)
+    return jsonify({
+        "device": str(current_camera_index),
+        "active_device": active_camera_device,
+        "active_backend": active_camera_backend,
+        "error": camera_open_error,
+        "attempts": camera_open_attempts,
+        "open": bool(camera is not None and camera.isOpened()),
+        "worker_started": camera_worker_started,
+        "frame_sequence": latest_frame_sequence,
+        "last_frame_age_seconds": age,
+        "read_stalled": bool(camera_read_started_at and time.monotonic() - camera_read_started_at >= 8.0),
+    })
 
 @app.route('/api/caption')
 def get_caption():
@@ -426,149 +643,190 @@ def caption_mode():
     caption_mode_enabled = bool(data.get('enabled', False))
     return jsonify({"enabled": caption_mode_enabled})
 
-@app.route('/api/cameras', methods=['GET'])
-def list_cameras():
-    global _camera_inventory_cache, _camera_inventory_cache_at
-    now = time.monotonic()
-    if now - _camera_inventory_cache_at < CAMERA_INVENTORY_CACHE_SECONDS:
-        return jsonify({"cameras": _camera_inventory_cache, "current": current_camera_index})
-
-    available = []
-    if sys.platform.startswith('linux'):
-        # Query capabilities without starting a stream. Opening every V4L2
-        # node through OpenCV also opens metadata/output nodes and can contend
-        # with the camera stream already owned by RoboVision.
-        import fcntl
-        vidioc_querycap = 0x80685600
-        video_capture = 0x00000001
-        video_capture_mplane = 0x00001000
-        device_caps_flag = 0x80000000
-        for candidate in sorted(glob.glob('/dev/video*')):
-            fd = None
-            try:
-                fd = os.open(candidate, os.O_RDONLY | os.O_NONBLOCK)
-                capability = bytearray(104)
-                fcntl.ioctl(fd, vidioc_querycap, capability, True)
-                capabilities = struct.unpack_from('=I', capability, 84)[0]
-                device_caps = struct.unpack_from('=I', capability, 88)[0]
-                effective = device_caps if capabilities & device_caps_flag else capabilities
-                if not effective & (video_capture | video_capture_mplane):
-                    continue
-                card = bytes(capability[16:48]).split(b'\0', 1)[0].decode('utf-8', 'replace')
-                available.append({
-                    "index": candidate,
-                    "id": candidate,
-                    "name": card or f"Camera {candidate}",
-                    "backend": "v4l2",
-                })
-            except (OSError, ValueError):
-                continue
-            finally:
-                if fd is not None:
-                    os.close(fd)
-    else:
-        for candidate in range(4):
-            cap = _open_camera(candidate)
-            if cap.isOpened():
-                available.append({"index": candidate, "id": str(candidate), "name": f"Camera {candidate}", "backend": "dshow"})
-            cap.release()
-
-    _camera_inventory_cache = available
-    _camera_inventory_cache_at = now
-    return jsonify({"cameras": available, "current": current_camera_index})
+def _enumerate_cameras():
+    """List cameras with friendly names. Cached: probing reopens devices."""
+    global _camera_inventory_cache, _camera_inventory_cache_at
+    now = time.monotonic()
+    if now - _camera_inventory_cache_at < CAMERA_INVENTORY_CACHE_SECONDS:
+        return _camera_inventory_cache
+
+    available = []
+    if sys.platform.startswith('linux'):
+        # Query capabilities without starting a stream. Opening every V4L2
+        # node through OpenCV also opens metadata/output nodes and can contend
+        # with the camera stream already owned by RoboVision.
+        import fcntl
+        vidioc_querycap = 0x80685600
+        video_capture = 0x00000001
+        video_capture_mplane = 0x00001000
+        device_caps_flag = 0x80000000
+        for candidate in sorted(glob.glob('/dev/video*')):
+            fd = None
+            try:
+                fd = os.open(candidate, os.O_RDONLY | os.O_NONBLOCK)
+                capability = bytearray(104)
+                fcntl.ioctl(fd, vidioc_querycap, capability, True)
+                capabilities = struct.unpack_from('=I', capability, 84)[0]
+                device_caps = struct.unpack_from('=I', capability, 88)[0]
+                effective = device_caps if capabilities & device_caps_flag else capabilities
+                if not effective & (video_capture | video_capture_mplane):
+                    continue
+                card = bytes(capability[16:48]).split(b'\0', 1)[0].decode('utf-8', 'replace')
+                available.append({
+                    "index": candidate,
+                    "id": candidate,
+                    "name": card or f"Camera {candidate}",
+                    "backend": "v4l2",
+                })
+            except (OSError, ValueError):
+                continue
+            finally:
+                if fd is not None:
+                    os.close(fd)
+    else:
+        names = _camera_names()
+        for candidate in range(CAMERA_SCAN_MAX_INDEX + 1):
+            # Positional name correlation — see _windows_camera_names().
+            name = names[candidate] if candidate < len(names) else f"Camera {candidate}"
+            if camera is not None and camera.isOpened() and candidate == active_camera_device:
+                # Never reopen the device the streaming worker owns.
+                available.append({"index": candidate, "id": str(candidate), "name": name,
+                                  "backend": active_camera_backend, "active": True})
+                continue
+            for backend, label in _camera_backends():
+                cap = cv2.VideoCapture(candidate, backend)
+                opened = cap.isOpened()
+                cap.release()
+                if opened:
+                    available.append({"index": candidate, "id": str(candidate), "name": name,
+                                      "backend": label, "active": False})
+                    break
+
+    _camera_inventory_cache = available
+    _camera_inventory_cache_at = now
+    return available
+
+
+@app.route('/api/cameras', methods=['GET'])
+def list_cameras():
+    return jsonify({
+        "cameras": _enumerate_cameras(),
+        "current": current_camera_index,
+        "active_device": active_camera_device,
+        "active_backend": active_camera_backend,
+    })
+
+def _reselect_camera(value):
+    """Point the worker at a new device (index, name or path) and revive it."""
+    global camera, current_camera_index, camera_open_error, camera_open_attempts
+    with camera_lock:
+        if camera:
+            camera.release()
+        current_camera_index = _normalize_camera_device(value)
+        camera = None
+        camera_open_error = None
+        camera_open_attempts = []
+    # The worker exits after a bounded open failure; an explicit selection is
+    # the operator saying "try again".
+    _ensure_camera_worker()
+
 
 @app.route('/api/camera/switch', methods=['POST'])
-def switch_camera():
-    global camera, current_camera_index
+def switch_camera():
     data = request.json or {}
-    new_index = data.get('device', data.get('index', 0))
-    if isinstance(new_index, str) and new_index.isdigit():
-        new_index = int(new_index)
-
-    with camera_lock:
-        if camera:
-            camera.release()
-        current_camera_index = _normalize_camera_device(new_index)
-        camera = None
-
-    return jsonify({"status": "ok", "camera_index": current_camera_index})
-
-
-def _audio_inventory():
-    """Adapt RoboVision's existing audio_server_pi /devices response."""
-    try:
-        response = requests.get(f"{ROBOVISION_AUDIO_URL.rstrip('/')}/devices", timeout=0.8)
-        response.raise_for_status()
-        payload = response.json()
-        inputs, outputs = [], []
-        for device in payload.get("devices", []):
-            item = {
-                "id": str(device["index"]),
-                "name": str(device.get("name", f"Audio device {device['index']}")),
-                "backend": "robovision_audio",
-                "sample_rate": device.get("default_samplerate"),
-            }
-            if device.get("max_input_channels", 0) > 0:
-                inputs.append(item.copy())
-            if device.get("max_output_channels", 0) > 0:
-                outputs.append(item.copy())
-        return inputs, outputs, {
-            "input": payload.get("bluetooth_input"),
-            "output": payload.get("bluetooth_output"),
-            "online": True,
-        }
-    except Exception as exc:
-        return [], [], {"online": False, "error": str(exc)}
-
-
-@app.route('/api/media/inventory', methods=['GET'])
-def media_inventory():
-    cameras = list_cameras().get_json().get("cameras", [])
-    inputs, outputs, audio_state = _audio_inventory()
-    return jsonify({
-        "video": [{"id": "auto", "name": "Auto detect"}, {"id": "none", "name": "Disable camera"}] + cameras,
-        "audio_input": inputs,
-        "audio_output": outputs,
-        "selected": {
-            "video_device": str(current_camera_index),
-            "audio_device": str(audio_state.get("input") if audio_state.get("input") is not None else audio_input_device),
-            "audio_output_device": str(audio_state.get("output") if audio_state.get("output") is not None else audio_output_device),
-        },
-        "audio_server": audio_state,
-        "source": "robovision_pi",
-    })
-
-
-@app.route('/api/media/config', methods=['GET', 'POST'])
-def media_config():
-    global audio_input_device, audio_output_device, camera, current_camera_index
-    if request.method == 'POST':
-        data = request.json or {}
-        if "video_device" in data:
-            value = str(data["video_device"])
-            if value not in ("", "auto", "none"):
-                switch_camera_value = value
-                if camera:
-                    camera.release()
-                current_camera_index = _normalize_camera_device(switch_camera_value)
-                camera = None
-        if "audio_device" in data:
-            audio_input_device = str(data["audio_device"])
-        if "audio_output_device" in data:
-            audio_output_device = str(data["audio_output_device"])
-        if "audio_device" in data or "audio_output_device" in data:
-            # audio_server_pi.py is RoboVision's authoritative selector.
-            # It accepts its original sounddevice indices via input/output.
-            payload = {}
-            if "audio_device" in data:
-                payload["input"] = int(audio_input_device) if audio_input_device.isdigit() else audio_input_device
-            if "audio_output_device" in data:
-                payload["output"] = int(audio_output_device) if audio_output_device.isdigit() else audio_output_device
-            try:
-                requests.post(f"{ROBOVISION_AUDIO_URL.rstrip('/')}/set-device", json=payload, timeout=0.8).raise_for_status()
-            except Exception:
-                pass
-    return jsonify({"video_device": str(current_camera_index), "audio_device": audio_input_device, "audio_output_device": audio_output_device, "source": "robovision_pi"})
+    new_index = data.get('device', data.get('index', 0))
+    if isinstance(new_index, str) and new_index.isdigit():
+        new_index = int(new_index)
+
+    _reselect_camera(new_index)
+    return jsonify({"status": "ok", "camera_index": current_camera_index})
+
+
+def _audio_inventory():
+    """Adapt RoboVision's existing audio_server_pi /devices response."""
+    try:
+        response = requests.get(f"{ROBOVISION_AUDIO_URL.rstrip('/')}/devices", timeout=0.8)
+        response.raise_for_status()
+        payload = response.json()
+        inputs, outputs = [], []
+        for device in payload.get("devices", []):
+            item = {
+                "id": str(device["index"]),
+                "name": str(device.get("name", f"Audio device {device['index']}")),
+                "backend": "robovision_audio",
+                "sample_rate": device.get("default_samplerate"),
+            }
+            if device.get("max_input_channels", 0) > 0:
+                inputs.append(item.copy())
+            if device.get("max_output_channels", 0) > 0:
+                outputs.append(item.copy())
+        return inputs, outputs, {
+            "input": payload.get("bluetooth_input"),
+            "output": payload.get("bluetooth_output"),
+            "online": True,
+        }
+    except Exception as exc:
+        return [], [], {"online": False, "error": str(exc)}
+
+
+@app.route('/api/media/inventory', methods=['GET'])
+def media_inventory():
+    cameras = _enumerate_cameras()
+    inputs, outputs, audio_state = _audio_inventory()
+    return jsonify({
+        "video": [{"id": "auto", "name": "Auto detect"}, {"id": "none", "name": "Disable camera"}] + cameras,
+        "video_state": {
+            "active_device": active_camera_device,
+            "active_backend": active_camera_backend,
+            "open": bool(camera is not None and camera.isOpened()),
+            "error": camera_open_error,
+            "attempts": camera_open_attempts,
+            # Names come from the OS, indices from OpenCV; the pairing is
+            # positional and best-effort (see _windows_camera_names()). The raw
+            # OS list is exposed too so an operator can see when it is longer
+            # than the list of indices OpenCV can actually open.
+            "name_correlation": "heuristic" if sys.platform == 'win32' else "exact",
+            "os_reported_names": _camera_names(),
+        },
+        "audio_input": inputs,
+        "audio_output": outputs,
+        "selected": {
+            "video_device": str(current_camera_index),
+            "audio_device": str(audio_state.get("input") if audio_state.get("input") is not None else audio_input_device),
+            "audio_output_device": str(audio_state.get("output") if audio_state.get("output") is not None else audio_output_device),
+        },
+        "audio_server": audio_state,
+        "source": "robovision_pi",
+    })
+
+
+@app.route('/api/media/config', methods=['GET', 'POST'])
+def media_config():
+    global audio_input_device, audio_output_device, camera, current_camera_index
+    if request.method == 'POST':
+        data = request.json or {}
+        if "video_device" in data:
+            value = str(data["video_device"])
+            if value not in ("", "none"):
+                # "auto" is a legitimate selection now — it means scan.
+                _reselect_camera(value)
+        if "audio_device" in data:
+            audio_input_device = str(data["audio_device"])
+        if "audio_output_device" in data:
+            audio_output_device = str(data["audio_output_device"])
+        if "audio_device" in data or "audio_output_device" in data:
+            # audio_server_pi.py is RoboVision's authoritative selector.
+            # It accepts its original sounddevice indices via input/output.
+            payload = {}
+            if "audio_device" in data:
+                payload["input"] = int(audio_input_device) if audio_input_device.isdigit() else audio_input_device
+            if "audio_output_device" in data:
+                payload["output"] = int(audio_output_device) if audio_output_device.isdigit() else audio_output_device
+            try:
+                requests.post(f"{ROBOVISION_AUDIO_URL.rstrip('/')}/set-device", json=payload, timeout=0.8).raise_for_status()
+            except Exception:
+                pass
+    return jsonify({"video_device": str(current_camera_index), "audio_device": audio_input_device, "audio_output_device": audio_output_device, "source": "robovision_pi"})
 
 @app.route('/api/motion/status', methods=['GET'])
 def motion_status():
@@ -646,11 +904,11 @@ if __name__ == '__main__':
     print("RoboVision - Raspberry Pi Vision Server (Minimal)")
     print("=" * 60)
     print(f"Starting Flask server on http://0.0.0.0:{args.port}")
-    if webhook_url:
-        print(f"Motion webhook: {webhook_url}")
-    print(f"Motion detection: {'ARMED' if motion_detection_active else 'off (POST /api/motion/toggle to arm)'}")
-    print("=" * 60)
-    # Start the single camera owner at boot. Production motion and MJPEG
-    # readiness must not depend on an operator opening the dashboard first.
-    _ensure_camera_worker()
-    app.run(host='0.0.0.0', port=args.port, debug=False, threaded=True)
+    if webhook_url:
+        print(f"Motion webhook: {webhook_url}")
+    print(f"Motion detection: {'ARMED' if motion_detection_active else 'off (POST /api/motion/toggle to arm)'}")
+    print("=" * 60)
+    # Start the single camera owner at boot. Production motion and MJPEG
+    # readiness must not depend on an operator opening the dashboard first.
+    _ensure_camera_worker()
+    app.run(host='0.0.0.0', port=args.port, debug=False, threaded=True)