From deb5db3b1cb39435ba278383e1bddbbdffef0117 Mon Sep 17 00:00:00 2001 From: Shawn Hwang Date: Mon, 16 Nov 2026 10:34:06 -0800 Subject: [PATCH 01/13] feat(egocap): station registry, station in use, and activity log in the backend Stations are now kept by the backend and chosen from the page instead of being the first entry of one station file. A station is a name, its camera type, the camera filling each role, and the capture host address last given to the headset. - A registry file beside the operator settings holds the stations and the one in use. A duplicate name, a camera in two roles, an unknown field or a bad address is refused with the specific reason. - Changing the station in use applies in process: the label shown and recorded changes and the batch rotates so the next session carries it. It is refused while a take is being written. - Recording is refused, with the reason, until a station is selected and its cameras are offered by the capture session. With no stations the configuration-free default is unchanged. - The recording snapshot carries the reason a take would be refused. - The active/inactive toggle writes the day file and the daily activity log locally; leaving a station stops its active time. - The headset address step offers this host's addresses, wireless first, and reports when the saved one is stale. Co-Authored-By: Claude Fable 5.2 Signed-off-by: Shawn Hwang --- examples/egocap/backend/egocap_web/app.py | 65 +++- .../backend/egocap_web/capture_status.py | 17 + .../backend/egocap_web/host_addresses.py | 142 +++++++ .../backend/egocap_web/operator_settings.py | 51 ++- .../backend/egocap_web/recording_command.py | 20 + .../backend/egocap_web/station_activity.py | 124 +++++++ .../backend/egocap_web/station_routes.py | 193 ++++++++++ .../backend/egocap_web/station_service.py | 227 ++++++++++++ .../egocap/backend/egocap_web/stations.py | 347 ++++++++++++++++++ .../egocap/tests/backend/test_app_stations.py | 124 +++++++ .../tests/backend/test_host_addresses.py | 131 +++++++ .../tests/backend/test_operator_settings.py | 2 +- .../tests/backend/test_recording_command.py | 44 +++ .../tests/backend/test_station_activity.py | 163 ++++++++ .../tests/backend/test_station_routes.py | 319 ++++++++++++++++ .../tests/backend/test_station_service.py | 210 +++++++++++ .../egocap/tests/backend/test_stations.py | 228 ++++++++++++ .../egocap/tests/backend/test_viser_scene.py | 6 + 18 files changed, 2398 insertions(+), 15 deletions(-) create mode 100644 examples/egocap/backend/egocap_web/host_addresses.py create mode 100644 examples/egocap/backend/egocap_web/station_activity.py create mode 100644 examples/egocap/backend/egocap_web/station_routes.py create mode 100644 examples/egocap/backend/egocap_web/station_service.py create mode 100644 examples/egocap/backend/egocap_web/stations.py create mode 100644 examples/egocap/tests/backend/test_app_stations.py create mode 100644 examples/egocap/tests/backend/test_host_addresses.py create mode 100644 examples/egocap/tests/backend/test_station_activity.py create mode 100644 examples/egocap/tests/backend/test_station_routes.py create mode 100644 examples/egocap/tests/backend/test_station_service.py create mode 100644 examples/egocap/tests/backend/test_stations.py diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py index 80dda3f7bf..ae8505942c 100644 --- a/examples/egocap/backend/egocap_web/app.py +++ b/examples/egocap/backend/egocap_web/app.py @@ -30,7 +30,9 @@ CalibrationAsset, ConfigurationError, QcConfig, + RecordingPhase, ServiceConfig, + StateError, VideoSourceSpec, ) @@ -57,11 +59,15 @@ validate_tracking_descriptor, ) from .recording_command import RecordingContext -from .recording_session import RecordingSessionCoordinator, TaskContext +from .recording_session import CoordinatorBusyError, RecordingSessionCoordinator, TaskContext from .recordings import router as recordings_router from .settings_routes import EffectiveSettings from .settings_routes import router as settings_router +from .station_activity import ACTIVITY_DIR, StationActivity from .station_config import ResolvedStation, StationConfigError, load_station_config, station_config_path_from_env +from .station_routes import router as station_router +from .station_service import TAKE_IN_PROGRESS, StationService, session_adapter +from .stations import StationError, StationStore, station_store_path from .task_file_routes import router as task_file_router from .viser_scene import VisualizationScene @@ -171,7 +177,7 @@ def _recorder_livekit_token(room: str) -> str: def _recording_config_factory( monitor: CaptureStatusMonitor, - station_label: str | None, + station_label: str | None | Callable[[], str | None], output_root: Path, on_video_sources: Callable[[frozenset[str], frozenset[str]], None] | None = None, ): @@ -185,7 +191,10 @@ def _recording_config_factory( (``recording_adapter.convert_camera_image``'s ``intrinsics`` param is always ``None`` today); declaring a schema that doesn't require them is the honest choice until that plumbing is added, rather than manufacturing - calibration values the backend doesn't actually have.""" + calibration values the backend doesn't actually have. + + ``station_label`` may be a callable, read at each session open, so a session opened after the operator + changes the station in use carries the new station's name.""" def factory() -> ServiceConfig: video_sources = tuple( @@ -216,7 +225,7 @@ def factory() -> ServiceConfig: video_sources=video_sources, qc=QcConfig(required_sources=required), calibration_assets=_station_calibration_assets(), - station_label=station_label, + station_label=station_label() if callable(station_label) else station_label, ) largest_decoded_frame_bytes = max((cam.width * cam.height * 3 for cam in video_sources), default=0) if largest_decoded_frame_bytes > 0: @@ -325,6 +334,27 @@ def check() -> tuple[bool, str | None]: return check +#: The recording phases in which no take is being written, so the station in use may change. +_STATION_CHANGE_PHASES = (RecordingPhase.IDLE, RecordingPhase.RECOVERY_REQUIRED, RecordingPhase.CLOSED) + + +def _station_change_blocked(coordinator: RecordingSessionCoordinator) -> str | None: + """Why the station in use cannot change now: a take is being recorded or a recording command is still + running. An interrupted take waiting for recovery does not block; it stays with the session it was in.""" + snapshot = coordinator.snapshot() + writing = snapshot.service is not None and snapshot.service.phase not in _STATION_CHANGE_PHASES + return TAKE_IN_PROGRESS if writing or snapshot.active_operation is not None else None + + +async def _rotate_batch_for_station(coordinator: RecordingSessionCoordinator) -> None: + """Ends the current batch so the next take opens a session under the new station label. A session's + configuration is frozen when it opens, so the label can only change between sessions.""" + try: + await coordinator.new_batch() + except (CoordinatorBusyError, StateError) as exc: + raise StationError(f"the recording session cannot change stations now: {exc}") from exc + + @asynccontextmanager async def lifespan(app: FastAPI) -> AsyncIterator[None]: """Creates and starts the one CaptureStatusMonitor for the station, @@ -424,10 +454,14 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: if resolved_station is not None and resolved_station.alignment_index is not None else None ) + # Today's active/inactive time per station, and the daily activity log it feeds. + station_activity = StationActivity(recording_output_root / ACTIVITY_DIR) + app.state.station_activity = station_activity coordinator = RecordingSessionCoordinator( _recording_config_factory( monitor, - config.station_label, + # Read at each session open: the station service below owns the label once it exists. + lambda: station_service.label(), recording_output_root, aligner.note_video_sources if aligner is not None else None, ), @@ -439,6 +473,21 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: tracking_latency=resolved_station.latency if resolved_station is not None else None, ) monitor.set_recording(coordinator) + # The station registry sits beside the operator settings. Its selected station names what is recorded and + # shown; with no station selected the deployment's own label stays in effect. + station_service = StationService( + StationStore(station_store_path(operator_settings_file)), + session_adapter( + offered_cameras=monitor.offered_camera_names, + change_blocked=lambda: _station_change_blocked(coordinator), + show_label=monitor.set_station_label, + rotate_batch=lambda: _rotate_batch_for_station(coordinator), + leave_station=station_activity.leave, + ), + default_label=config.station_label, + ) + app.state.station_service = station_service + monitor.set_station_label(station_service.label()) await monitor.start() app.state.monitor = monitor # Generated once per backend process start (a restart is the only way @@ -451,7 +500,10 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: print(f"Recording control token for this run: {control_token}", file=sys.stderr, flush=True) auto_fill_operator_name = resolved_station.auto_fill_operator_name if resolved_station is not None else False app.state.recording_context = RecordingContext( - coordinator=coordinator, control_token=control_token, auto_fill_operator_name=auto_fill_operator_name + coordinator=coordinator, + control_token=control_token, + auto_fill_operator_name=auto_fill_operator_name, + setup_gate=station_service.block_reason, ) # The 3D view settings are read once, for the view itself and for the settings report. visualization_config: VisualizationConfig | None = None @@ -517,6 +569,7 @@ def _optional_visualization( app.include_router(task_file_router) app.include_router(settings_router) app.include_router(operator_settings_router) +app.include_router(station_router) # PoC demo integration: browse/download recorded files, off unless # EGOCAP_RECORDINGS_ENABLED=1. Not part of the final system design -- see # recordings.py's own module docstring. diff --git a/examples/egocap/backend/egocap_web/capture_status.py b/examples/egocap/backend/egocap_web/capture_status.py index 0b92e7c299..692ff998c8 100644 --- a/examples/egocap/backend/egocap_web/capture_status.py +++ b/examples/egocap/backend/egocap_web/capture_status.py @@ -328,6 +328,23 @@ def camera_descriptors(self) -> tuple[p.CameraStream, ...]: return () return tuple(s for s in self.native.started.streams if isinstance(s, p.CameraStream)) + def offered_camera_names(self) -> frozenset[str] | None: + """Names of every camera the accepted session offers, CaptureServer's own and LiveKit streams alike; + None before a session has been accepted, when what it offers is not known yet.""" + if self.native.started is None: + return None + return frozenset( + s.name for s in self.native.started.streams if isinstance(s, (p.CameraStream, p.LiveKitCameraStream)) + ) + + def set_station_label(self, label: str) -> None: + """Replaces the station label every status and preview snapshot carries. The revision advances so + each viewer is sent the change, the same as any other lifecycle fact.""" + if label == self._station_label: + return + self._station_label = label + self.revision += 1 + def camera_descriptor_by_stream_id(self, stream_id: int) -> p.CameraStream | None: """The accepted camera descriptor advertising this stream ID, if any.""" for cam in self.camera_descriptors: diff --git a/examples/egocap/backend/egocap_web/host_addresses.py b/examples/egocap/backend/egocap_web/host_addresses.py new file mode 100644 index 0000000000..f0bdb60655 --- /dev/null +++ b/examples/egocap/backend/egocap_web/host_addresses.py @@ -0,0 +1,142 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The capture host address an operator enters in the headset. + +The headset connects to the capture host over the local network, so the operator needs that host's address. When +CaptureServer runs on this machine the candidates are this machine's own IPv4 addresses, wireless first: a +headset is on the wireless network, and a wired link is often a point-to-point cable to another device. When +CaptureServer runs elsewhere its own host is the only candidate. +""" + +from __future__ import annotations + +import fcntl +import ipaddress +import socket +import struct +import sys +from collections.abc import Callable, Iterable +from dataclasses import dataclass +from urllib.parse import urlsplit + +#: Linux ``ioctl`` request that returns an interface's IPv4 address. +_SIOCGIFADDR = 0x8915 + +WIRELESS, WIRED, OTHER, CAPTURE_SERVER = "wireless", "wired", "other", "capture_server" + +#: Interface name prefixes, by the kind of link they name on Linux. +_KIND_PREFIXES = ((WIRELESS, ("wl",)), (WIRED, ("eth", "en"))) + +#: Wireless first; see the module docstring. +_KIND_ORDER = (WIRELESS, WIRED, OTHER) + + +@dataclass(frozen=True) +class HostAddress: + """One address the headset could be given, and where it comes from.""" + + address: str + #: The network interface holding the address, or None when it is not one of this machine's. + interface: str | None + kind: str + + def to_json(self) -> dict[str, str | None]: + """The wire form.""" + return {"address": self.address, "interface": self.interface, "kind": self.kind} + + +def interface_kind(name: str) -> str: + """Whether an interface name is a wireless link, a wired one, or neither.""" + for kind, prefixes in _KIND_PREFIXES: + if name.startswith(prefixes): + return kind + return OTHER + + +def _interface_address(name: str) -> str | None: + """The IPv4 address of one interface through the Linux ioctl, or None when it has none.""" + with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as probe: + try: + packed = fcntl.ioctl(probe.fileno(), _SIOCGIFADDR, struct.pack("256s", name.encode()[:15])) + except OSError: + return None + return socket.inet_ntoa(packed[20:24]) + + +def _system_interfaces() -> list[tuple[str, str]]: + """Every interface of this machine with an IPv4 address, as (name, address); empty off Linux.""" + # The request number below is Linux's; elsewhere it could mean something else, so it is never sent. + if not sys.platform.startswith("linux"): + return [] + found = [] + for _index, name in socket.if_nameindex(): + address = _interface_address(name) + if address is not None: + found.append((name, address)) + return found + + +def _route_address() -> str | None: + """The address this machine would send from, found without sending anything; None when it has no route.""" + with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as probe: + try: + # Connecting a datagram socket only selects a route; no packet leaves the machine. + probe.connect(("192.0.2.1", 9)) + return probe.getsockname()[0] + except OSError: + return None + + +def local_addresses( + interfaces: Callable[[], Iterable[tuple[str, str]]] = _system_interfaces, + route_address: Callable[[], str | None] = _route_address, +) -> list[HostAddress]: + """This machine's usable IPv4 addresses, wireless first, then in the order the system lists them. + + Where interfaces cannot be listed (the ioctl is Linux only), the outbound route's address is the one + candidate. + """ + try: + listed = list(interfaces()) + except OSError: + listed = [] + usable = [ + HostAddress(address, name, interface_kind(name)) + for name, address in listed + # Loopback and link-local addresses are unreachable from a headset on the network. + if not (ipaddress.ip_address(address).is_loopback or ipaddress.ip_address(address).is_link_local) + ] + if usable: + return sorted(usable, key=lambda candidate: _KIND_ORDER.index(candidate.kind)) + fallback = route_address() + if fallback is None or ipaddress.ip_address(fallback).is_loopback: + return [] + return [HostAddress(fallback, None, OTHER)] + + +def _is_this_machine(host: str) -> bool: + """Whether a CaptureServer host names this machine: ``localhost`` or a loopback address.""" + if host == "localhost": + return True + try: + return ipaddress.ip_address(host).is_loopback + except ValueError: + return False + + +def headset_addresses( + capture_server_url: str, local: Callable[[], list[HostAddress]] = local_addresses +) -> list[HostAddress]: + """The addresses to offer for the headset, best first; empty when none can be determined.""" + host = urlsplit(capture_server_url).hostname or "" + if host == "" or _is_this_machine(host): + return local() + # A capture host on another machine is where the headset must connect, whatever this machine's addresses are. + return [HostAddress(host, None, CAPTURE_SERVER)] + + +def address_changed(saved: str | None, candidates: list[HostAddress]) -> bool: + """Whether the address saved for a station is no longer one the host has, so the headset needs updating.""" + return saved is not None and bool(candidates) and saved not in {candidate.address for candidate in candidates} diff --git a/examples/egocap/backend/egocap_web/operator_settings.py b/examples/egocap/backend/egocap_web/operator_settings.py index 5c9ad24144..1874649d71 100644 --- a/examples/egocap/backend/egocap_web/operator_settings.py +++ b/examples/egocap/backend/egocap_web/operator_settings.py @@ -141,7 +141,7 @@ def updated(self, changes: dict[str, Any]) -> OperatorSettings: return _parse(merged) -def _parse_roles(raw: Any) -> dict[str, str | None]: +def parse_camera_roles(raw: Any) -> dict[str, str | None]: """Role assignments: known roles only, each a non-empty camera name or null, no camera in two roles.""" if raw is None: return {role: None for role in CAMERA_ROLES} @@ -158,9 +158,14 @@ def _parse_roles(raw: Any) -> dict[str, str | None]: if value is not None and (not isinstance(value, str) or value.strip() == ""): raise OperatorSettingsError(f"camera_roles.{role} must be a camera name or null") roles[role] = value - assigned = [value for value in roles.values() if value is not None] - if len(assigned) != len(set(assigned)): - raise OperatorSettingsError("a camera cannot fill two roles") + # Name the camera and both roles, so the operator knows which assignment to change. + holder: dict[str, str] = {} + for role, camera in roles.items(): + if camera is None: + continue + if camera in holder: + raise OperatorSettingsError(f"camera {camera!r} cannot fill both {holder[camera]} and {role}") + holder[camera] = role return roles @@ -183,7 +188,7 @@ def _parse(raw: Any) -> OperatorSettings: raise OperatorSettingsError(f"camera_type must be one of {', '.join(CAMERA_TYPES)} or null") return OperatorSettings( camera_type=camera_type, - camera_roles=_parse_roles(raw.get("camera_roles")), + camera_roles=parse_camera_roles(raw.get("camera_roles")), task_file=_optional_text(raw, "task_file", check=is_catalog_name, what="a plain *.csv file name"), preselected_task=_optional_text( raw, "preselected_task", check=lambda v: v.strip() != "", what="a task name" @@ -270,6 +275,27 @@ def _store(request: Request) -> OperatorSettingsStore | None: return getattr(request.app.state, "operator_settings_store", None) +#: The fields that belong to a station once one is in use; the rest stay station-independent. +_STATION_FIELDS = ("camera_type", "camera_roles") + + +def _station_service(request: Request) -> Any: + """The station service (station_service.py), or None in an application built without one. Read from the + application state rather than imported: that module builds on this one.""" + return getattr(request.app.state, "station_service", None) + + +def _effective(request: Request, settings: OperatorSettings) -> dict[str, Any]: + """The wire form the page acts on: the station in use supplies the camera type and roles, so every + reader sees that station's hardware; with no station in use the stored values apply as before.""" + payload = settings.to_json() + service = _station_service(request) + selected = service.registry.selected if service is not None else None + if selected is not None: + payload.update(camera_type=selected.camera_type, camera_roles=dict(selected.camera_roles)) + return payload + + @router.get("/api/operator-settings") async def read_operator_settings(request: Request) -> JSONResponse: """Return saved settings, or defaults with a repair warning if the saved data is invalid.""" @@ -284,10 +310,13 @@ async def read_operator_settings(request: Request) -> JSONResponse: # Defaults keep the form usable so an authenticated save can repair invalid storage. logger.warning("Invalid operator settings at %s; showing defaults for repair", store.path) return JSONResponse( - {**OperatorSettings().to_json(), "warning": "Saved settings are invalid. Save to replace them."}, + { + **_effective(request, OperatorSettings()), + "warning": "Saved settings are invalid. Save to replace them.", + }, headers=_NO_STORE, ) - return JSONResponse(settings.to_json(), headers=_NO_STORE) + return JSONResponse(_effective(request, settings), headers=_NO_STORE) @router.put("/api/operator-settings") @@ -302,7 +331,13 @@ async def write_operator_settings(request: Request) -> JSONResponse: body, refused = await read_authorized_json(request, recording_context.control_token, 16 * 1024) if body is None: return refused # type: ignore[return-value] + service = _station_service(request) try: + # With a station in use, its camera fields are that station's to keep: they go to the registry, where + # the rule against changing the station in use during a take applies to them too. + station_changes = {key: body.pop(key) for key in _STATION_FIELDS if key in body} + if station_changes and (service is None or await service.update_selected(station_changes) is None): + body.update(station_changes) settings = await asyncio.to_thread( store.update, body, @@ -314,7 +349,7 @@ async def write_operator_settings(request: Request) -> JSONResponse: except OSError: logger.exception("Could not save operator settings") return JSONResponse({"detail": "could not save operator settings"}, status_code=503, headers=_NO_STORE) - return JSONResponse(settings.to_json(), headers=_NO_STORE) + return JSONResponse(_effective(request, settings), headers=_NO_STORE) @router.get("/api/tools") diff --git a/examples/egocap/backend/egocap_web/recording_command.py b/examples/egocap/backend/egocap_web/recording_command.py index 1d042ffef3..504ab99dfe 100644 --- a/examples/egocap/backend/egocap_web/recording_command.py +++ b/examples/egocap/backend/egocap_web/recording_command.py @@ -30,6 +30,7 @@ import secrets import time import uuid +from collections.abc import Callable from dataclasses import dataclass, field from typing import Any @@ -223,6 +224,10 @@ class RecordingContext: #: auto_fill_operator_name). Never a signal to commit an operator automatically: that #: still always requires the operator's own explicit "Set operator" action. auto_fill_operator_name: bool = False + #: Why station setup does not allow a take right now, or None when it does (see app.py's lifespan for + #: what it checks). Asked only when a take is admitted and when readiness is published, never while one + #: records: a setup fact changing mid-take must not interrupt it, unlike a capture source going stale. + setup_gate: Callable[[], str | None] | None = field(default=None, repr=False) batch_id: str = field(default_factory=_new_batch_id) saved_count: int = 0 last_result: dict[str, Any] | None = None @@ -325,12 +330,20 @@ def _observe(self) -> tuple[CoordinatorSnapshot, tuple[Any, ...]]: """Reads the coordinator and advances ``revision`` if the decision state changed since the last look.""" coordinator_snapshot = self.coordinator.snapshot() ready, reason = self.coordinator.readiness() + # Station setup outranks a capture reason: it is the earlier step, and fixing it is the operator's move. + blocked = self.setup_block() + if blocked is not None: + ready, reason = False, blocked decision_state = self._decision_state(coordinator_snapshot, ready, reason) if decision_state != self._last_decision_state: self._last_decision_state = decision_state self.revision += 1 return coordinator_snapshot, decision_state + def setup_block(self) -> str | None: + """Why station setup does not allow a take right now, or None; None too when no gate is installed.""" + return self.setup_gate() if self.setup_gate is not None else None + def refresh(self) -> None: """Notices a readiness or in-progress change that no callback announces. Each viewer's sender calls this every iteration, before it compares ``revision``, so such a change is pushed without any command.""" @@ -375,6 +388,9 @@ def snapshot(self) -> dict[str, Any]: and ready and coordinator_snapshot.context.task_text.strip() != "" ), + # Why a take would be refused right now, when station setup or a capture source is the cause; + # null when ready, and null when only the task is missing (the page already says so). + "not_ready_reason": None if ready else reason, # Lets a receiver drop a snapshot older than one it already # applied; restarts from 0 with the process, so a receiver # compares it only within one connection. @@ -461,6 +477,10 @@ async def apply(self, command: RecordingCommand) -> tuple[str, str | None]: if command.action == "start_episode": if self.coordinator.snapshot().context.task_text.strip() == "": return "rejected", "set a task before starting an episode" + # Station setup is checked here, at admission only (see setup_gate). + blocked = self.setup_block() + if blocked is not None: + return "rejected", blocked await self.coordinator.start_episode(operator) return "ok", None if command.action == "stop_episode": diff --git a/examples/egocap/backend/egocap_web/station_activity.py b/examples/egocap/backend/egocap_web/station_activity.py new file mode 100644 index 0000000000..bbac9714e1 --- /dev/null +++ b/examples/egocap/backend/egocap_web/station_activity.py @@ -0,0 +1,124 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The station's active/inactive time for today, and the daily activity log it feeds. + +An operator marks the station active while it is collecting and inactive while it is blocked. The state and its +intervals are kept by ``egocap.analytics.station_status_log`` in one file per day under the recording output, and +each change also rewrites that station's daily activity log beside it. Both are local files written atomically; +nothing here uploads them. +""" + +from __future__ import annotations + +import datetime +import json +import threading +import time +from collections.abc import Callable +from pathlib import Path +from typing import Any + +from egocap.analytics.station_status_log import ACTIVE, INACTIVE, StationStatusTracker + +STATES = (ACTIVE, INACTIVE) + +#: Bounded so a stray paste cannot bloat the day file every toggle rewrites. +MAX_NOTES_CHARS = 4000 + +#: The directory, under the recording output, holding the day files and the daily activity logs. +ACTIVITY_DIR = "station_status" + + +class StationActivityError(ValueError): + """A refused activity change, with a public reason.""" + + +class StationActivity: + """Today's activity for any station, behind one lock: the tracker is not safe for concurrent use.""" + + def __init__(self, log_dir: Path, clock: Callable[[], float] = time.time) -> None: + """``clock`` returns epoch seconds; tests pass their own to move through a day.""" + self._tracker = StationStatusTracker(log_dir) + self._clock = clock + self._lock = threading.Lock() + + def report(self, station: str) -> dict[str, Any]: + """Today's state and totals for ``station``, with the open segment counted up to now.""" + with self._lock: + return self._report(station, self._clock()) + + def _report(self, station: str, now: float) -> dict[str, Any]: + """The wire form of one station's day; the caller holds the lock.""" + totals = self._tracker.compute_totals(station, now=now) + return { + "station": station, + "date": datetime.date.fromtimestamp(now).isoformat(), + "state": totals["current_state"], + # None until the first change of the day: no time is counted before the operator starts it. + "since": totals["current_segment_start_ts"], + "active_seconds": totals["active_seconds"], + "inactive_seconds": totals["inactive_seconds"], + "blocker_count": totals["blocker_count"], + "notes": self._tracker.get_blocker_notes(station, now=now), + # The moment these totals were computed, so a page can keep the open segment counting locally. + "as_of": now, + } + + def change(self, station: str, *, state: Any = None, notes: Any = None) -> dict[str, Any]: + """Set the state, the blocker notes, or both, then rewrite the daily log; returns the new report.""" + if state is not None and state not in STATES: + raise StationActivityError(f"state must be one of {', '.join(STATES)}") + if notes is not None and (not isinstance(notes, str) or len(notes) > MAX_NOTES_CHARS): + raise StationActivityError(f"notes must be text of at most {MAX_NOTES_CHARS} characters") + with self._lock: + now = self._clock() + if state is not None: + self._tracker.set_state(station, state, now=now) + if notes is not None: + self._tracker.set_blocker_notes(station, notes, now=now) + self._write_log(station, now) + return self._report(station, now) + + def leave(self, station: str) -> None: + """Stop counting active time for a station that is no longer in use; a no-op unless it is active.""" + with self._lock: + now = self._clock() + # Only an open active segment keeps accumulating; an untouched station must stay untouched. + if self._tracker.get_state(station, now=now) != ACTIVE: + return + self._tracker.set_state(station, INACTIVE, now=now) + self._write_log(station, now) + + def write_log(self, station: str, *, data_seconds: float | None, valid_seconds: float | None) -> str: + """Rewrite the daily log with freshly measured recorded time; returns the log's file name.""" + with self._lock: + now = self._clock() + return self._tracker.save_daily_log( + station, now=now, data_seconds=data_seconds, valid_seconds=valid_seconds + ).name + + def _write_log(self, station: str, now: float) -> None: + """Rewrite the daily log after a change, keeping the recorded time a report last measured.""" + date = datetime.date.fromtimestamp(now).isoformat() + measured = _measured_seconds(self._tracker.daily_log_path(station, date)) + self._tracker.save_daily_log(station, date_iso=date, now=now, **measured) + + +def _measured_seconds(log_path: Path) -> dict[str, float | None]: + """The recorded-time figures already in a daily log, so a state change does not blank them.""" + try: + previous = json.loads(log_path.read_text(encoding="utf-8")) + except (OSError, ValueError): + previous = {} + if not isinstance(previous, dict): + previous = {} + return {key: _seconds(previous.get(key)) for key in ("data_seconds", "valid_seconds")} + + +def _seconds(value: Any) -> float | None: + """A stored duration as a float, or None for anything that is not a plain number.""" + if isinstance(value, bool) or not isinstance(value, (int, float)): + return None + return float(value) diff --git a/examples/egocap/backend/egocap_web/station_routes.py b/examples/egocap/backend/egocap_web/station_routes.py new file mode 100644 index 0000000000..e00ad5e50a --- /dev/null +++ b/examples/egocap/backend/egocap_web/station_routes.py @@ -0,0 +1,193 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""HTTP surface for stations: the registry, the station in use, its activity and the headset address. + +Reading the registry and today's activity is open to any page that can reach the backend, as the operator +settings are; a station's headset address and this machine's network addresses are LAN details and need the +run's control token. Every change needs that token, the same credential that admits recording commands. +""" + +from __future__ import annotations + +import asyncio +import logging +from typing import Any + +from fastapi import APIRouter, Request +from fastapi.responses import JSONResponse + +from .host_addresses import address_changed, headset_addresses +from .recording_command import control_token_valid +from .request_body import read_authorized_json +from .station_activity import StationActivityError +from .stations import StationError, StationNotFoundError + +logger = logging.getLogger("isaaccapture.egocap.station_routes") + +router = APIRouter() + +_NO_STORE = {"Cache-Control": "no-store"} +#: A station record is a few short fields; activity notes are the largest body accepted here. +_MAX_BODY_BYTES = 32 * 1024 + + +def _reply(body: dict[str, Any], status: int = 200) -> JSONResponse: + """A non-cacheable JSON reply: station state changes under the page and must never be served stale.""" + return JSONResponse(body, status_code=status, headers=_NO_STORE) + + +def _unavailable() -> JSONResponse: + """The reply while the application has not finished starting.""" + return _reply({"detail": "stations are not available yet"}, 503) + + +def _state(request: Request) -> tuple[Any, Any, Any] | None: + """The station service, activity log and recording context, or None until the lifespan has set them.""" + state = request.app.state + found = tuple( + getattr(state, name, None) for name in ("station_service", "station_activity", "recording_context") + ) + return None if any(item is None for item in found) else found # type: ignore[return-value] + + +def _holds_token(request: Request, context: Any) -> bool: + """Whether a read carries the run's control token, which unlocks the LAN details.""" + return control_token_valid(request.headers.get("x-control-token"), context.control_token) + + +def _refusal(exc: StationError) -> JSONResponse: + """A refused station change as its HTTP status: an unknown id is not found, anything else a bad request.""" + return _reply({"detail": exc.public_message}, 404 if isinstance(exc, StationNotFoundError) else 400) + + +@router.get("/api/stations") +async def list_stations(request: Request) -> JSONResponse: + """Every station, the one in use, and why each cannot record yet.""" + state = _state(request) + if state is None: + return _unavailable() + service, _activity, context = state + return _reply(service.listing(private=_holds_token(request, context))) + + +async def _change(request: Request, change: Any) -> JSONResponse: + """Run one authorized registry change and answer with the new listing.""" + state = _state(request) + if state is None: + return _unavailable() + service, _activity, context = state + body, refused = await read_authorized_json(request, context.control_token, _MAX_BODY_BYTES) + if body is None: + return refused # type: ignore[return-value] + try: + await change(service, body) + except StationError as exc: + return _refusal(exc) + except OSError: + logger.exception("Could not save the station registry") + return _reply({"detail": "could not save the station registry"}, 503) + return _reply(service.listing(private=True)) + + +@router.post("/api/stations") +async def add_station(request: Request) -> JSONResponse: + """Add a station from its name and, optionally, its hardware.""" + return await _change(request, lambda service, body: service.add(body)) + + +@router.post("/api/stations/select") +async def select_station(request: Request) -> JSONResponse: + """Put one station in use, or none for ``{"id": null}``; refused while a take is being recorded.""" + + async def select(service: Any, body: dict[str, Any]) -> None: + """Validate the id's shape here; whether it names a station is the registry's rule.""" + station_id = body.get("id") + if station_id is not None and not isinstance(station_id, str): + raise StationError("id must be a station id or null") + await service.select(station_id) + + return await _change(request, select) + + +@router.put("/api/stations/{station_id}") +async def update_station(request: Request, station_id: str) -> JSONResponse: + """Change the named fields of one station.""" + return await _change(request, lambda service, body: service.update(station_id, body)) + + +@router.delete("/api/stations/{station_id}") +async def delete_station(request: Request, station_id: str) -> JSONResponse: + """Delete one station. The credential travels in the header: a DELETE carries no body to bound or parse.""" + state = _state(request) + if state is None: + return _unavailable() + service, _activity, context = state + if not _holds_token(request, context): + return _reply({"detail": "control token rejected"}, 403) + try: + await service.remove(station_id) + except StationError as exc: + return _refusal(exc) + except OSError: + logger.exception("Could not save the station registry") + return _reply({"detail": "could not save the station registry"}, 503) + return _reply(service.listing(private=True)) + + +@router.get("/api/headset-address") +async def read_headset_address(request: Request) -> JSONResponse: + """The addresses to enter in the headset, the one saved for the station in use, and whether it is stale.""" + state = _state(request) + settings = getattr(request.app.state, "settings", None) + if state is None or settings is None: + return _unavailable() + service, _activity, context = state + if not _holds_token(request, context): + return _reply({"detail": "control token rejected"}, 403) + # Interface enumeration is a blocking system call, kept off the event loop. + candidates = await asyncio.to_thread(headset_addresses, settings.capture.capture_server_url) + selected = service.registry.selected + saved = selected.headset_address if selected is not None else None + return _reply( + { + "candidates": [candidate.to_json() for candidate in candidates], + "saved": saved, + "changed": address_changed(saved, candidates), + } + ) + + +@router.get("/api/station-activity") +async def read_station_activity(request: Request) -> JSONResponse: + """Today's active and inactive time for the station in use.""" + state = _state(request) + if state is None: + return _unavailable() + service, activity, _context = state + return _reply(await asyncio.to_thread(activity.report, service.label())) + + +@router.post("/api/station-activity") +async def change_station_activity(request: Request) -> JSONResponse: + """Mark the station in use active or inactive, save its blocker notes, or both.""" + state = _state(request) + if state is None: + return _unavailable() + service, activity, context = state + body, refused = await read_authorized_json(request, context.control_token, _MAX_BODY_BYTES) + if body is None: + return refused # type: ignore[return-value] + if "state" not in body and "notes" not in body: + return _reply({"detail": "name a state, notes, or both"}, 400) + try: + report = await asyncio.to_thread( + lambda: activity.change(service.label(), state=body.get("state"), notes=body.get("notes")) + ) + except StationActivityError as exc: + return _reply({"detail": str(exc)}, 400) + except OSError: + logger.exception("Could not save station activity") + return _reply({"detail": "could not save station activity"}, 503) + return _reply(report) diff --git a/examples/egocap/backend/egocap_web/station_service.py b/examples/egocap/backend/egocap_web/station_service.py new file mode 100644 index 0000000000..ee4c5853b8 --- /dev/null +++ b/examples/egocap/backend/egocap_web/station_service.py @@ -0,0 +1,227 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Applies station registry changes to the running session. + +The registry (stations.py) only stores values. This service decides when a change is allowed and what it does to +the live session: the station in use cannot change while a take is being recorded, and a change of the station in +use takes effect in process, without a restart. The capture session keeps running; the station label shown and +recorded changes at once, and the recording batch rotates so the next take opens a session carrying the new label. +Which cameras CaptureServer is asked for stays a deployment setting (see station_config.py). +""" + +from __future__ import annotations + +import asyncio +import logging +from collections.abc import Awaitable, Callable +from typing import Any, Protocol + +from .operator_settings import CAMERA_ROLES, CAMERA_TYPES +from .stations import Station, StationError, StationRegistry, StationStore + +logger = logging.getLogger("isaaccapture.egocap.station_service") + +#: Shown when a change would alter the station a take in progress is being recorded against. +TAKE_IN_PROGRESS = "finish or discard the current take before changing the station in use" + + +class StationSession(Protocol): + """What this service needs from the live session; the application wires the real objects in.""" + + def offered_cameras(self) -> frozenset[str] | None: + """Names of the cameras the capture session offers, or None before a session has been accepted.""" + + def change_blocked(self) -> str | None: + """Why the station in use cannot change now, or None when it can.""" + + def show_label(self, label: str) -> None: + """Publish the station label every viewer sees.""" + + async def rotate_batch(self) -> None: + """End the current recording batch so the next take opens a session with the new label; raises + :class:`StationError` when the session cannot rotate now.""" + + def leave_station(self, label: str) -> None: + """Close the activity segment of the station being left.""" + + +class StationService: + """One owner for the station in use: the registry, the label it implies, and the rules for changing either.""" + + def __init__(self, store: StationStore, session: StationSession, default_label: str) -> None: + """``default_label`` is the deployment's own station label, used while no station is selected.""" + self._store = store + self._session = session + self._default_label = default_label + # One change at a time: a rotation awaits, and a second change must not interleave with it. + self._changing = asyncio.Lock() + self._warning: str | None = None + self._registry = self._load() + self._label = self._label_of(self._registry) + + def _load(self) -> StationRegistry: + """The stored registry; an unreadable one starts empty with a warning the page shows.""" + try: + return self._store.load() + except StationError as exc: + logger.warning("Station registry is unreadable (%s); starting with no stations", exc.public_message) + self._warning = "Saved stations are unreadable. Adding a station replaces them." + return StationRegistry() + + def _label_of(self, registry: StationRegistry) -> str: + """The label recordings and viewers carry for a registry: the selected station's name, else the default.""" + selected = registry.selected + return selected.name if selected is not None else self._default_label + + @property + def registry(self) -> StationRegistry: + """The registry as last loaded or changed by this process.""" + return self._registry + + def label(self) -> str: + """The station label in effect now; read each time a recording session opens.""" + return self._label + + def block_reason(self) -> str | None: + """Why recording is not allowed for station reasons, or None. + + An empty registry blocks nothing: that is the configuration-free default. Once stations exist, one must + be selected and able to record. + """ + if not self._registry.stations: + return None + selected = self._registry.selected + if selected is None: + return "select a station before recording" + problems = selected.problems(self._session.offered_cameras()) + return f"station {selected.name!r}: {problems[0]}" if problems else None + + def listing(self, *, private: bool) -> dict[str, Any]: + """The wire form of the registry. ``private`` adds each station's headset address, a LAN detail shown + only to a caller holding the control token.""" + offered = self._session.offered_cameras() + stations = [] + for station in self._registry.stations: + record = { + "id": station.station_id, + "name": station.name, + "camera_type": station.camera_type, + "camera_roles": dict(station.camera_roles), + "problems": station.problems(offered), + } + if private: + record["headset_address"] = station.headset_address + stations.append(record) + listing: dict[str, Any] = { + "stations": stations, + "selected": self._registry.selected_id, + "roles": list(CAMERA_ROLES), + "camera_types": list(CAMERA_TYPES), + "label": self._label, + "locked_reason": self._session.change_blocked(), + } + if self._warning is not None: + listing["warning"] = self._warning + return listing + + async def add(self, fields: Any) -> Station: + """Add a station; nothing about the session in use changes, so this is allowed during a take.""" + async with self._changing: + after = await self._persist(lambda registry: registry.added(fields), touches_station_in_use=False) + return after.stations[-1] + + async def update(self, station_id: str, changes: Any) -> None: + """Change one station; changing the station in use is refused while a take is recorded.""" + async with self._changing: + in_use = self._registry.selected_id == station_id + await self._persist( + lambda registry: registry.updated(station_id, changes), touches_station_in_use=in_use + ) + + async def remove(self, station_id: str) -> None: + """Delete one station; deleting the station in use leaves nothing selected.""" + async with self._changing: + in_use = self._registry.selected_id == station_id + await self._persist(lambda registry: registry.removed(station_id), touches_station_in_use=in_use) + + async def select(self, station_id: str | None) -> None: + """Put a station in use, or none for None.""" + async with self._changing: + await self._persist(lambda registry: registry.selecting(station_id), touches_station_in_use=True) + + async def update_selected(self, changes: Any) -> Station | None: + """Change the station in use, for callers that edit "this station" without naming it; None when + nothing is selected.""" + async with self._changing: + selected_id = self._registry.selected_id + if selected_id is None: + return None + after = await self._persist( + lambda registry: registry.updated(selected_id, changes), touches_station_in_use=True + ) + return after.selected + + async def _persist( + self, apply: Callable[[StationRegistry], StationRegistry], *, touches_station_in_use: bool + ) -> StationRegistry: + """Persist one change and apply its effect on the live session; the caller holds the change lock.""" + # Refused before anything is written, so a blocked change leaves the file as it was. + if touches_station_in_use: + blocked = self._session.change_blocked() + if blocked is not None: + raise StationError(blocked) + # Validated in memory first: a refused change must not have rotated the batch. + label = self._label_of(apply(self._registry)) + relabelled = label != self._label + # Rotated before the file is written: a session still open under the old label must never + # receive a take attributed to the new one, so a refused rotation refuses the whole change. + if relabelled: + await self._session.rotate_batch() + _, after = await asyncio.to_thread(self._store.change, apply) + self._registry = after + self._warning = None + if relabelled: + previous, self._label = self._label, self._label_of(after) + # The activity log is a file write; it stays off the event loop. + await asyncio.to_thread(self._session.leave_station, previous) + self._session.show_label(self._label) + return after + + +def session_adapter( + *, + offered_cameras: Callable[[], frozenset[str] | None], + change_blocked: Callable[[], str | None], + show_label: Callable[[str], None], + rotate_batch: Callable[[], Awaitable[None]], + leave_station: Callable[[str], None], +) -> StationSession: + """A :class:`StationSession` built from plain callables, so the application can bind the real monitor, + recording context and activity log without this module importing any of them.""" + + class _Adapter: + """The callables above, under the protocol's method names.""" + + def offered_cameras(self) -> frozenset[str] | None: + """See :class:`StationSession`.""" + return offered_cameras() + + def change_blocked(self) -> str | None: + """See :class:`StationSession`.""" + return change_blocked() + + def show_label(self, label: str) -> None: + """See :class:`StationSession`.""" + show_label(label) + + async def rotate_batch(self) -> None: + """See :class:`StationSession`.""" + await rotate_batch() + + def leave_station(self, label: str) -> None: + """See :class:`StationSession`.""" + leave_station(label) + + return _Adapter() diff --git a/examples/egocap/backend/egocap_web/stations.py b/examples/egocap/backend/egocap_web/stations.py new file mode 100644 index 0000000000..2837aa200c --- /dev/null +++ b/examples/egocap/backend/egocap_web/stations.py @@ -0,0 +1,347 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The station registry: the stations an operator can choose between, and which one is in use. + +A station is a name plus the hardware that fills its roles: the camera type, which offered camera is the ego view +and which is on each wrist, and the host address last given to the headset. The registry is one JSON file beside +the operator settings, so every browser sees the same stations and they survive a restart. An empty registry is +the configuration-free default: nothing is selected, the deployment's own station label applies, and no station +rule blocks recording. + +This module holds the values and their validation only. Applying a selection to the running session lives in +station_service.py, and the HTTP surface in station_routes.py. +""" + +from __future__ import annotations + +import ipaddress +import json +import logging +import os +import secrets +import tempfile +import threading +from collections.abc import Callable +from dataclasses import dataclass, field, replace +from pathlib import Path +from typing import Any + +from .operator_settings import ( + CAMERA_ROLES, + CAMERA_TYPES, + OperatorSettingsError, + parse_camera_roles, +) + +logger = logging.getLogger("isaaccapture.egocap.stations") + +#: A registry is a site's stations, not a database; the bound keeps the file and the page small. +MAX_STATIONS = 32 +MAX_STATION_NAME_CHARS = 64 + +#: The role every station must fill before it can record: without the operator's view a take has no subject. +REQUIRED_ROLE = "ego" + +#: Operator-facing role names for messages; the page keeps its own copy for labels. +_ROLE_NAMES = {"ego": "ego (head)", "wrist_left": "left wrist", "wrist_right": "right wrist"} + +#: The fields a create or update may carry. ``control_token`` is the legacy body credential, already checked. +_EDITABLE_FIELDS = ("name", "camera_type", "camera_roles", "headset_address") +_IGNORED_FIELDS = ("control_token",) + + +class StationError(OperatorSettingsError): + """A station change that was refused, with a public, path-free reason naming what to fix.""" + + +class StationNotFoundError(StationError): + """A request named a station id the registry does not hold.""" + + +def _clean_name(raw: Any) -> str: + """A station name with surrounding and repeated whitespace removed, or a refusal saying what is wrong.""" + if not isinstance(raw, str): + raise StationError("station name must be text") + # Names are compared and shown, so "Bay 1" and "Bay 1" must not become two stations. + name = " ".join(raw.split()) + if name == "": + raise StationError("station name cannot be empty") + if len(name) > MAX_STATION_NAME_CHARS: + raise StationError(f"station name is limited to {MAX_STATION_NAME_CHARS} characters") + # The name is recorded with every session and used in a log file name; control characters have no place there. + if not name.isprintable(): + raise StationError("station name cannot contain control characters") + return name + + +def _clean_camera_type(raw: Any) -> str | None: + """A camera type the backend knows, or None for not set.""" + if raw is not None and raw not in CAMERA_TYPES: + raise StationError(f"camera_type must be one of {', '.join(CAMERA_TYPES)} or null") + return raw + + +def _clean_headset_address(raw: Any) -> str | None: + """The host address last given to the headset, as a canonical IP literal, or None when never set.""" + if raw is None: + return None + if not isinstance(raw, str): + raise StationError("headset_address must be an IP address or null") + try: + return str(ipaddress.ip_address(raw.strip())) + except ValueError: + raise StationError(f"headset_address {raw.strip()!r} is not an IP address") from None + + +@dataclass(frozen=True) +class Station: + """One station: its name and the hardware that fills its roles.""" + + station_id: str + name: str + camera_type: str | None = None + #: Which offered camera fills each role; every role is present, None where unassigned. + camera_roles: dict[str, str | None] = field(default_factory=lambda: {role: None for role in CAMERA_ROLES}) + #: The capture host address last entered in the headset; compared with today's to warn of a change. + headset_address: str | None = None + + def stored(self) -> dict[str, Any]: + """The record as written to the registry file.""" + return { + "id": self.station_id, + "name": self.name, + "camera_type": self.camera_type, + "camera_roles": dict(self.camera_roles), + "headset_address": self.headset_address, + } + + def problems(self, offered_cameras: frozenset[str] | None) -> list[str]: + """Why this station cannot record yet, most important first; empty when it can. + + ``offered_cameras`` is what the running capture session offers, or None while that is not known yet, in + which case only the assignments themselves are judged. + """ + found: list[str] = [] + if self.camera_roles[REQUIRED_ROLE] is None: + found.append(f"no camera is assigned to the {_ROLE_NAMES[REQUIRED_ROLE]} role") + if offered_cameras is None: + return found + # A role pointing at a camera the session does not offer would record nothing for that role. + for role in CAMERA_ROLES: + camera = self.camera_roles[role] + if camera is not None and camera not in offered_cameras: + found.append(f"camera {camera!r} ({_ROLE_NAMES[role]}) is not offered by the capture session") + return found + + +def _parse_station(raw: Any) -> Station: + """One stored record as a station; a malformed record is an error, never a guess.""" + if not isinstance(raw, dict): + raise StationError("each station must be an object") + station_id = raw.get("id") + if not isinstance(station_id, str) or station_id == "": + raise StationError("each station needs an id") + return Station( + station_id=station_id, + name=_clean_name(raw.get("name")), + camera_type=_clean_camera_type(raw.get("camera_type")), + camera_roles=_station_roles(raw.get("camera_roles")), + headset_address=_clean_headset_address(raw.get("headset_address")), + ) + + +def _station_roles(raw: Any) -> dict[str, str | None]: + """Role assignments for a station, refused as a station error so the route reports one error family.""" + try: + return parse_camera_roles(raw) + except OperatorSettingsError as exc: + raise StationError(exc.public_message) from None + + +def _checked_fields(changes: Any) -> dict[str, Any]: + """The editable fields a request names; an unknown field is refused so a typo is not silently dropped.""" + if not isinstance(changes, dict): + raise StationError("a station change must be an object") + unknown = sorted(set(changes) - set(_EDITABLE_FIELDS) - set(_IGNORED_FIELDS)) + if unknown: + raise StationError(f"unknown station field(s): {', '.join(unknown)}") + return {key: changes[key] for key in _EDITABLE_FIELDS if key in changes} + + +@dataclass(frozen=True) +class StationRegistry: + """Every station and the selected one. Immutable: each change returns a new registry.""" + + stations: tuple[Station, ...] = () + selected_id: str | None = None + + @property + def selected(self) -> Station | None: + """The station in use, or None when nothing is selected.""" + return self.find(self.selected_id) if self.selected_id is not None else None + + def find(self, station_id: str) -> Station | None: + """The station with this id, or None.""" + return next((station for station in self.stations if station.station_id == station_id), None) + + def require(self, station_id: str) -> Station: + """The station with this id; an unknown id is a refusal the route reports as not found.""" + station = self.find(station_id) + if station is None: + raise StationNotFoundError("no such station") + return station + + def stored(self) -> dict[str, Any]: + """The registry as written to its file.""" + return {"selected": self.selected_id, "stations": [station.stored() for station in self.stations]} + + def _refuse_duplicate_name(self, name: str, except_id: str | None) -> None: + """Refuse a name another station already has, ignoring case, so two stations never share a log.""" + for other in self.stations: + if other.station_id != except_id and other.name.casefold() == name.casefold(): + raise StationError(f"a station named {other.name!r} already exists") + + def added( + self, fields: Any, new_id: Callable[[], str] = lambda: f"st_{secrets.token_hex(4)}" + ) -> StationRegistry: + """This registry with one more station built from ``fields``; the new station is last.""" + if len(self.stations) >= MAX_STATIONS: + raise StationError(f"a registry holds at most {MAX_STATIONS} stations") + checked = _checked_fields(fields) + name = _clean_name(checked.get("name")) + self._refuse_duplicate_name(name, except_id=None) + # A colliding id would make one station shadow another; draw until it is free. + station_id = new_id() + while self.find(station_id) is not None: + station_id = new_id() + station = Station( + station_id=station_id, + name=name, + camera_type=_clean_camera_type(checked.get("camera_type")), + camera_roles=_station_roles(checked.get("camera_roles")), + headset_address=_clean_headset_address(checked.get("headset_address")), + ) + return replace(self, stations=(*self.stations, station)) + + def updated(self, station_id: str, changes: Any) -> StationRegistry: + """This registry with the named fields of one station replaced; a role change may name only some roles.""" + current = self.require(station_id) + checked = _checked_fields(changes) + merged = current + if "name" in checked: + name = _clean_name(checked["name"]) + self._refuse_duplicate_name(name, except_id=station_id) + merged = replace(merged, name=name) + if "camera_type" in checked: + merged = replace(merged, camera_type=_clean_camera_type(checked["camera_type"])) + if "camera_roles" in checked: + roles = checked["camera_roles"] + if not isinstance(roles, dict): + raise StationError("camera_roles must be an object of role to camera name or null") + merged = replace(merged, camera_roles=_station_roles({**current.camera_roles, **roles})) + if "headset_address" in checked: + merged = replace(merged, headset_address=_clean_headset_address(checked["headset_address"])) + return replace( + self, + stations=tuple(merged if station.station_id == station_id else station for station in self.stations), + ) + + def removed(self, station_id: str) -> StationRegistry: + """This registry without one station; removing the selected station leaves nothing selected.""" + self.require(station_id) + return StationRegistry( + stations=tuple(station for station in self.stations if station.station_id != station_id), + selected_id=None if self.selected_id == station_id else self.selected_id, + ) + + def selecting(self, station_id: str | None) -> StationRegistry: + """This registry with ``station_id`` in use, or nothing in use for None.""" + if station_id is not None: + self.require(station_id) + return replace(self, selected_id=station_id) + + +def parse_registry(raw: Any) -> StationRegistry: + """A stored object as a registry: unique ids and names, and a selection that names a stored station.""" + if not isinstance(raw, dict): + raise StationError("the station registry must be an object") + records = raw.get("stations", []) + if not isinstance(records, list) or len(records) > MAX_STATIONS: + raise StationError(f"stations must be a list of at most {MAX_STATIONS}") + registry = StationRegistry() + for record in records: + station = _parse_station(record) + # A hand-edited file must hold to the same uniqueness the page enforces. + if registry.find(station.station_id) is not None: + raise StationError(f"station id {station.station_id!r} appears twice") + registry._refuse_duplicate_name(station.name, except_id=None) + registry = replace(registry, stations=(*registry.stations, station)) + selected = raw.get("selected") + if selected is not None and (not isinstance(selected, str) or registry.find(selected) is None): + raise StationError("the selected station is not in the registry") + return replace(registry, selected_id=selected) + + +class StationStore: + """The registry file: absent means no stations, and every write replaces it atomically.""" + + def __init__(self, path: Path) -> None: + """Bind the file and the lock that serialises changes within this backend process.""" + self.path = path + self.lock = threading.RLock() + + def load(self) -> StationRegistry: + """The stored registry, or an empty one when nothing has been saved.""" + try: + text = self.path.read_text(encoding="utf-8") + except FileNotFoundError: + return StationRegistry() + except UnicodeError: + raise StationError("the station registry is not valid UTF-8") from None + try: + raw = json.loads(text) + except json.JSONDecodeError: + raise StationError("the station registry is not valid JSON") from None + return parse_registry(raw) + + def save(self, registry: StationRegistry) -> None: + """Write the registry through a uniquely named temporary file, so a crash never leaves half of one.""" + self.path.parent.mkdir(parents=True, exist_ok=True) + with tempfile.NamedTemporaryFile( + mode="w", encoding="utf-8", dir=self.path.parent, prefix=f".{self.path.name}.", delete=False + ) as handle: + staged = Path(handle.name) + try: + handle.write(json.dumps(registry.stored(), indent=2) + "\n") + handle.flush() + os.fsync(handle.fileno()) + handle.close() + os.replace(staged, self.path) + finally: + staged.unlink(missing_ok=True) + + def change( + self, apply: Callable[[StationRegistry], StationRegistry] + ) -> tuple[StationRegistry, StationRegistry]: + """Apply one change under the lock and persist it; returns the registry before and after. + + An unreadable registry is set aside as ``.invalid`` and replaced, so the page can repair a station + list without shell access while the bad file stays available to inspect. + """ + with self.lock: + try: + before = self.load() + except StationError: + logger.warning("Setting aside an unreadable station registry at %s", self.path) + os.replace(self.path, self.path.with_name(f"{self.path.name}.invalid")) + before = StationRegistry() + after = apply(before) + self.save(after) + return before, after + + +def station_store_path(operator_settings_file: Path) -> Path: + """The registry file, kept beside the operator settings so both stay out of the recordings browser.""" + return operator_settings_file.with_name("stations.json") diff --git a/examples/egocap/tests/backend/test_app_stations.py b/examples/egocap/tests/backend/test_app_stations.py new file mode 100644 index 0000000000..978aedd3b2 --- /dev/null +++ b/examples/egocap/tests/backend/test_app_stations.py @@ -0,0 +1,124 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The app's wiring of the station in use: when it may change, how the batch rotates, and a session's label.""" + +from __future__ import annotations + +from types import SimpleNamespace + +import pytest + +from capture_server import protocol as p +from egocap_web import app as app_module +from egocap_web.capture_status import CaptureStatusMonitor +from egocap_web.config import CaptureStatusConfig +from egocap_web.recording_session import CoordinatorBusyError +from egocap_web.station_service import TAKE_IN_PROGRESS +from egocap_web.stations import StationError +from recording_service import RecordingPhase + + +def _coordinator(phase: RecordingPhase | None, operation=None, refusal: Exception | None = None): + """A stand-in coordinator in one recording phase; ``phase`` None means no session was ever opened.""" + rotations: list[str] = [] + + async def new_batch() -> None: + if refusal is not None: + raise refusal + rotations.append("rotated") + + service = None if phase is None else SimpleNamespace(phase=phase) + snapshot = SimpleNamespace(service=service, active_operation=operation) + return SimpleNamespace(snapshot=lambda: snapshot, new_batch=new_batch, rotations=rotations) + + +@pytest.mark.parametrize( + "phase", [None, RecordingPhase.IDLE, RecordingPhase.RECOVERY_REQUIRED, RecordingPhase.CLOSED] +) +def test_the_station_may_change_whenever_no_take_is_being_written(phase): + assert app_module._station_change_blocked(_coordinator(phase)) is None + + +@pytest.mark.parametrize( + "phase", + [RecordingPhase.STARTING, RecordingPhase.RECORDING, RecordingPhase.STOPPING, RecordingPhase.FINALIZING], +) +def test_the_station_cannot_change_while_a_take_is_being_written(phase): + assert app_module._station_change_blocked(_coordinator(phase)) == TAKE_IN_PROGRESS + + +def test_the_station_cannot_change_while_a_recording_command_is_still_running(): + assert app_module._station_change_blocked(_coordinator(RecordingPhase.IDLE, operation="NEW_BATCH")) == ( + TAKE_IN_PROGRESS + ) + + +async def test_a_station_change_rotates_the_batch_and_a_refused_rotation_says_why(): + coordinator = _coordinator(RecordingPhase.IDLE) + await app_module._rotate_batch_for_station(coordinator) + assert coordinator.rotations == ["rotated"] + busy = _coordinator(RecordingPhase.IDLE, refusal=CoordinatorBusyError("an episode is active")) + with pytest.raises(StationError) as refused: + await app_module._rotate_batch_for_station(busy) + assert refused.value.public_message == "the recording session cannot change stations now: an episode is active" + + +def test_a_session_is_labelled_with_the_station_in_use_when_it_opens(tmp_path): + monitor = SimpleNamespace(camera_descriptors=(), native=SimpleNamespace(started=None)) + label = ["Bench A"] + factory = app_module._recording_config_factory(monitor, lambda: label[0], tmp_path) + assert factory().station_label == "Bench A" + label[0] = "Cart B" # the operator changed stations; the next session to open carries the new name + assert factory().station_label == "Cart B" + + +def _camera(name: str) -> p.CameraStream: + return p.CameraStream( + stream_id=1, + kind=p.StreamKind.IMAGE, + name=name, + type=p.CameraType.OAK_D_COLOR, + required=True, + width=8, + height=4, + fps=30.0, + codec=p.ImageCodec.JPEG, + jpeg_quality=80, + orientation=p.ImageOrientation(), + ) + + +def _livekit(name: str) -> p.LiveKitCameraStream: + return p.LiveKitCameraStream( + stream_id=16, + name=name, + url="wss://lk", + room="r", + publisher="o", + track="t", + timestamp_basis=p.LiveKitTimestampBasis.SENSOR_CAPTURE_MONOTONIC_US, + width=8, + height=4, + fps=30.0, + ) + + +def test_the_monitor_offers_every_camera_of_the_accepted_session_by_name(): + monitor = CaptureStatusMonitor(CaptureStatusConfig(), backend_instance_id="b1") + assert monitor.offered_camera_names() is None # nothing accepted yet: what is offered is unknown + tracking = SimpleNamespace(name="tracking") + monitor.native = SimpleNamespace( + started=SimpleNamespace(streams=(tracking, _camera("cam_head"), _livekit("cam_wrist"))) + ) + assert monitor.offered_camera_names() == frozenset({"cam_head", "cam_wrist"}) + + +def test_a_changed_station_label_is_announced_to_every_viewer_once(): + monitor = CaptureStatusMonitor(CaptureStatusConfig(station_label="Deployment"), backend_instance_id="b1") + revision = monitor.revision + monitor.set_station_label("Deployment") + assert monitor.revision == revision + monitor.set_station_label("Bench A") + assert (monitor.revision, monitor.snapshot().station_label) == (revision + 1, "Bench A") diff --git a/examples/egocap/tests/backend/test_host_addresses.py b/examples/egocap/tests/backend/test_host_addresses.py new file mode 100644 index 0000000000..0959ed9903 --- /dev/null +++ b/examples/egocap/tests/backend/test_host_addresses.py @@ -0,0 +1,131 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The capture host address offered for the headset: which addresses, in which order, and when one is stale.""" + +from __future__ import annotations + +import socket +import struct + +import pytest + +from egocap_web import host_addresses +from egocap_web.host_addresses import ( + HostAddress, + address_changed, + headset_addresses, + interface_kind, + local_addresses, +) + + +@pytest.mark.parametrize( + ("name", "kind"), + [("wlan0", "wireless"), ("wlp2s0", "wireless"), ("eth0", "wired"), ("enp3s0", "wired"), ("docker0", "other")], +) +def test_an_interface_is_classified_by_its_name(name, kind): + assert interface_kind(name) == kind + + +def test_wireless_addresses_come_first_and_unreachable_ones_are_dropped(): + listed = [ + ("lo", "127.0.0.1"), + ("enp3s0", "192.168.1.10"), + ("usb0", "169.254.7.7"), + ("docker0", "172.17.0.1"), + ("wlp2s0", "10.0.0.42"), + ] + assert local_addresses(lambda: listed, lambda: "203.0.113.9") == [ + HostAddress("10.0.0.42", "wlp2s0", "wireless"), + HostAddress("192.168.1.10", "enp3s0", "wired"), + HostAddress("172.17.0.1", "docker0", "other"), + ] + + +def _failing_interfaces(): + raise OSError("interfaces cannot be listed") + + +@pytest.mark.parametrize("interfaces", [lambda: [], lambda: [("lo", "127.0.0.1")], _failing_interfaces]) +def test_the_outbound_route_is_the_fallback_when_no_interface_is_usable(interfaces): + assert local_addresses(interfaces, lambda: "192.168.1.10") == [HostAddress("192.168.1.10", None, "other")] + assert local_addresses(interfaces, lambda: None) == [] + assert local_addresses(interfaces, lambda: "127.0.0.1") == [] + + +@pytest.mark.parametrize("url", ["ws://127.0.0.1:8082", "ws://localhost:8082", "ws://[::1]:8082", "not a url"]) +def test_a_capture_server_on_this_machine_offers_this_machines_addresses(url): + here = [HostAddress("10.0.0.42", "wlp2s0", "wireless")] + assert headset_addresses(url, lambda: here) == here + + +@pytest.mark.parametrize( + ("url", "host"), + [("ws://192.168.1.50:8082", "192.168.1.50"), ("wss://capture.example:8082", "capture.example")], +) +def test_a_capture_server_elsewhere_is_the_only_address_offered(url, host): + assert headset_addresses(url, lambda: [HostAddress("10.0.0.42", "wlp2s0", "wireless")]) == [ + HostAddress(host, None, "capture_server") + ] + + +def test_a_saved_address_is_stale_only_when_the_host_no_longer_has_it(): + candidates = [HostAddress("10.0.0.42", "wlp2s0", "wireless"), HostAddress("192.168.1.10", "enp3s0", "wired")] + assert not address_changed("192.168.1.10", candidates) # a wired address the host still has is not stale + assert address_changed("10.0.0.7", candidates) + assert not address_changed(None, candidates) + assert not address_changed("10.0.0.7", []) # nothing to compare against is not evidence of a change + + +def test_the_wire_form_names_the_interface(): + assert HostAddress("10.0.0.42", "wlp2s0", "wireless").to_json() == { + "address": "10.0.0.42", + "interface": "wlp2s0", + "kind": "wireless", + } + + +def test_interfaces_are_read_through_the_linux_ioctl_only_on_linux(monkeypatch): + def fake_ioctl(_fd, _request, packed): + name = packed.rstrip(b"\x00").decode() + if name == "down0": + raise OSError("no address") + return struct.pack("20s4s232s", b"", socket.inet_aton("10.0.0.42"), b"") + + monkeypatch.setattr(host_addresses.socket, "if_nameindex", lambda: [(1, "wlp2s0"), (2, "down0")]) + monkeypatch.setattr(host_addresses.fcntl, "ioctl", fake_ioctl) + monkeypatch.setattr(host_addresses.sys, "platform", "linux") + assert host_addresses._system_interfaces() == [("wlp2s0", "10.0.0.42")] + monkeypatch.setattr(host_addresses.sys, "platform", "darwin") + assert host_addresses._system_interfaces() == [] + + +class _Probe: + """A stand-in datagram socket: ``route`` is the address it would send from, or None for no route.""" + + route: str | None = None + + def __init__(self, *_args): + pass + + def __enter__(self): + return self + + def __exit__(self, *_exc): + return False + + def connect(self, _target): + if self.route is None: + raise OSError("network is unreachable") + + def getsockname(self): + return (self.route, 0) + + +def test_the_route_address_is_found_without_sending_and_absent_without_a_route(monkeypatch): + monkeypatch.setattr(host_addresses.socket, "socket", _Probe) + assert host_addresses._route_address() is None + monkeypatch.setattr(_Probe, "route", "192.168.1.10") + assert host_addresses._route_address() == "192.168.1.10" diff --git a/examples/egocap/tests/backend/test_operator_settings.py b/examples/egocap/tests/backend/test_operator_settings.py index 26adae108f..24fb0c2522 100644 --- a/examples/egocap/tests/backend/test_operator_settings.py +++ b/examples/egocap/tests/backend/test_operator_settings.py @@ -238,7 +238,7 @@ def test_camera_roles_start_unassigned_and_change_one_role_at_a_time(tmp_path): ({"head": "Ego"}, "unknown camera role"), ({"ego": ""}, "camera name or null"), ({"ego": 1}, "camera name or null"), - ({"ego": "Cam", "wrist_left": "Cam"}, "two roles"), + ({"ego": "Cam", "wrist_left": "Cam"}, "cannot fill both ego and wrist_left"), ("Ego", "must be an object"), ], ) diff --git a/examples/egocap/tests/backend/test_recording_command.py b/examples/egocap/tests/backend/test_recording_command.py index 5338398a40..e26e044032 100644 --- a/examples/egocap/tests/backend/test_recording_command.py +++ b/examples/egocap/tests/backend/test_recording_command.py @@ -718,3 +718,47 @@ def factory() -> ServiceConfig: await coordinator.open() on = RecordingContext(coordinator=coordinator, control_token=TEST_CONTROL_TOKEN, auto_fill_operator_name=True) assert on.snapshot()["auto_fill_operator_name"] is True + + +async def test_station_setup_blocks_a_take_at_admission_with_its_reason(tmp_path: Path): + context = await _open_context(tmp_path) + blocked: list[str | None] = ["select a station before recording"] + context.setup_gate = lambda: blocked[0] + snapshot = context.snapshot() + assert snapshot["ready_to_record"] is False + assert snapshot["not_ready_reason"] == "select a station before recording" + reply = await handle_recording_command(_command("start_episode", {"batch_id": context.batch_id}), context) + assert (reply["outcome"], reply["reason"]) == ("rejected", "select a station before recording") + assert reply["snapshot"]["episode_phase"] == "IDLE" + # Clearing the cause is announced to every viewer without any command being sent. + revision = context.revision + blocked[0] = None + context.refresh() + assert context.revision == revision + 1 + assert context.snapshot()["ready_to_record"] is True and context.snapshot()["not_ready_reason"] is None + started = await handle_recording_command(_command("start_episode", {"batch_id": context.batch_id}), context) + assert started["outcome"] == "ok" + # Station setup is asked at admission only: a cause appearing mid-take never interrupts the take. + blocked[0] = "station 'Bench A': no camera is assigned to the ego (head) role" + stopped = await handle_recording_command( + _command( + "stop_episode", {"batch_id": context.batch_id, "episode_id": started["snapshot"]["current_episode_id"]} + ), + context, + ) + assert (stopped["outcome"], stopped["snapshot"]["last_result"]["disposition"]) == ("ok", "KEPT") + + +async def test_a_capture_reason_is_published_when_station_setup_allows_a_take(tmp_path: Path): + def factory() -> ServiceConfig: + return ServiceConfig(output_root=tmp_path / "out", numeric_sources=(NUMERIC,), video_sources=()) + + coordinator = RecordingSessionCoordinator( + factory, queue_capacity=8, readiness_check=lambda: (False, "capture is not running") + ) + coordinator.set_task("Pour water.") + context = RecordingContext(coordinator=coordinator, control_token=TEST_CONTROL_TOKEN, setup_gate=lambda: None) + assert context.snapshot()["not_ready_reason"] == "capture is not running" + # Station setup outranks the capture reason: it is the earlier step. + context.setup_gate = lambda: "select a station before recording" + assert context.snapshot()["not_ready_reason"] == "select a station before recording" diff --git a/examples/egocap/tests/backend/test_station_activity.py b/examples/egocap/tests/backend/test_station_activity.py new file mode 100644 index 0000000000..7635ea2bf6 --- /dev/null +++ b/examples/egocap/tests/backend/test_station_activity.py @@ -0,0 +1,163 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Station activity: active and inactive time through a day, and the daily log it feeds.""" + +from __future__ import annotations + +import datetime +import json + +import pytest + +from egocap_web.station_activity import MAX_NOTES_CHARS, StationActivity, StationActivityError + +#: A fixed local morning, so every step of a test lands on one calendar day. +DAY_START = datetime.datetime(2026, 3, 9, 8, 0, 0).timestamp() + + +class _Clock: + def __init__(self): + self.now = DAY_START + + def __call__(self) -> float: + return self.now + + def advance(self, seconds: float) -> None: + self.now += seconds + + +def _activity(tmp_path) -> tuple[StationActivity, _Clock]: + clock = _Clock() + return StationActivity(tmp_path / "station_status", clock), clock + + +def _log(tmp_path, station: str = "bench_a") -> dict: + return json.loads((tmp_path / "station_status" / f"{station}_2026-03-09_activity.json").read_text()) + + +def test_nothing_is_counted_before_the_operator_starts_the_day(tmp_path): + activity, clock = _activity(tmp_path) + clock.advance(600) + assert activity.report("Bench A") == { + "station": "Bench A", + "date": "2026-03-09", + "state": "inactive", + "since": None, + "active_seconds": 0.0, + "inactive_seconds": 0.0, + "blocker_count": 0, + "notes": "", + "as_of": DAY_START + 600, + } + assert not (tmp_path / "station_status").exists() # reading never creates files + + +def test_the_daily_log_shows_correct_active_and_inactive_time(tmp_path): + activity, clock = _activity(tmp_path) + activity.change("Bench A", state="active") + clock.advance(3600) # an hour collecting + blocked = activity.change("Bench A", state="inactive") + assert (blocked["state"], blocked["since"]) == ("inactive", DAY_START + 3600) + clock.advance(900) # a quarter of an hour blocked + activity.change("Bench A", state="active") + clock.advance(1800) # half an hour more, still open + report = activity.report("Bench A") + assert (report["active_seconds"], report["inactive_seconds"], report["blocker_count"]) == (5400.0, 900.0, 1) + # The log on disk was written at the last change; the open segment is closed up to that moment. + assert _log(tmp_path) == { + "station": "Bench A", + "date": "2026-03-09", + "active_station_time": "1h 00m 00s", + "active_station_time_seconds": 3600.0, + "inactive_station_time": "0h 15m 00s", + "inactive_station_time_seconds": 900.0, + "data_hours": None, + "data_seconds": None, + "valid_hours": None, + "valid_seconds": None, + } + assert sorted(path.name for path in (tmp_path / "station_status").iterdir()) == [ + "2026-03-09.json", + "bench_a_2026-03-09_activity.json", + ] + + +def test_setting_the_same_state_again_does_not_restart_its_segment(tmp_path): + activity, clock = _activity(tmp_path) + activity.change("Bench A", state="active") + clock.advance(60) + again = activity.change("Bench A", state="active") + assert again["since"] == DAY_START and again["active_seconds"] == 60.0 + + +def test_notes_are_saved_with_or_without_a_state_change(tmp_path): + activity, clock = _activity(tmp_path) + assert activity.change("Bench A", notes="left glove battery")["notes"] == "left glove battery" + assert activity.report("Bench A")["state"] == "inactive" + both = activity.change("Bench A", state="active", notes="") + assert (both["state"], both["notes"]) == ("active", "") + + +@pytest.mark.parametrize( + ("change", "reason"), + [ + ({"state": "paused"}, "state must be one of active, inactive"), + ({"state": True}, "state must be one of"), + ({"notes": 7}, "notes must be text"), + ({"notes": "x" * (MAX_NOTES_CHARS + 1)}, f"at most {MAX_NOTES_CHARS} characters"), + ], +) +def test_an_invalid_change_is_refused_and_writes_nothing(tmp_path, change, reason): + activity, _ = _activity(tmp_path) + with pytest.raises(StationActivityError, match=reason): + activity.change("Bench A", **change) + assert not (tmp_path / "station_status").exists() + + +def test_leaving_a_station_stops_its_active_time_and_touches_nothing_else(tmp_path): + activity, clock = _activity(tmp_path) + activity.leave("Cart B") # never started today: stays untouched + assert not (tmp_path / "station_status").exists() + activity.change("Bench A", state="active") + clock.advance(120) + activity.leave("Bench A") + clock.advance(600) + report = activity.report("Bench A") + assert (report["state"], report["active_seconds"], report["inactive_seconds"]) == ("inactive", 120.0, 600.0) + activity.leave("Bench A") # already inactive + assert activity.report("Bench A")["blocker_count"] == 1 + + +def test_measured_recorded_time_survives_a_later_state_change(tmp_path): + activity, clock = _activity(tmp_path) + activity.change("Bench A", state="active") + clock.advance(600) + assert activity.write_log("Bench A", data_seconds=540.0, valid_seconds=480.0) == ( + "bench_a_2026-03-09_activity.json" + ) + assert (_log(tmp_path)["data_seconds"], _log(tmp_path)["valid_hours"]) == (540.0, round(480 / 3600, 4)) + activity.change("Bench A", state="inactive") + log = _log(tmp_path) + assert (log["data_seconds"], log["valid_seconds"], log["active_station_time_seconds"]) == (540.0, 480.0, 600.0) + + +@pytest.mark.parametrize("content", ["not json", "[1]", '{"data_seconds": true, "valid_seconds": "long"}']) +def test_an_unusable_previous_log_is_rewritten_without_recorded_time(tmp_path, content): + activity, _ = _activity(tmp_path) + log_dir = tmp_path / "station_status" + log_dir.mkdir() + (log_dir / "bench_a_2026-03-09_activity.json").write_text(content) + activity.change("Bench A", state="active") + assert (_log(tmp_path)["data_seconds"], _log(tmp_path)["valid_seconds"]) == (None, None) + + +def test_stations_are_tracked_independently(tmp_path): + activity, clock = _activity(tmp_path) + activity.change("Bench A", state="active") + clock.advance(300) + activity.change("Cart B", state="active") + clock.advance(300) + assert activity.report("Bench A")["active_seconds"] == 600.0 + assert activity.report("Cart B")["active_seconds"] == 300.0 diff --git a/examples/egocap/tests/backend/test_station_routes.py b/examples/egocap/tests/backend/test_station_routes.py new file mode 100644 index 0000000000..c819c06692 --- /dev/null +++ b/examples/egocap/tests/backend/test_station_routes.py @@ -0,0 +1,319 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Station routes: the token-gated registry, the activity toggle, the headset address, and the real application.""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +from types import SimpleNamespace + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from egocap_web import station_routes +from egocap_web.app import app as real_app +from egocap_web.host_addresses import HostAddress +from egocap_web.operator_settings import OperatorSettingsStore +from egocap_web.operator_settings import router as operator_settings_router +from egocap_web.station_activity import StationActivity +from egocap_web.station_service import TAKE_IN_PROGRESS, StationService, session_adapter +from egocap_web.stations import StationStore + +TOKEN = "t" * 43 +AUTH = {"X-Control-Token": TOKEN} +BENCH = {"name": "Bench A", "camera_roles": {"ego": "cam_head", "wrist_left": "cam_left"}} + + +@dataclass +class _Context: + control_token: str + + +class _Live: + """The live-session facts a test can change between requests.""" + + blocked: str | None = None + + +def _client(tmp_path: Path, live: _Live | None = None, ready: bool = True) -> TestClient: + live = live or _Live() + small = FastAPI() + small.include_router(station_routes.router) + small.include_router(operator_settings_router) + if not ready: + return TestClient(small) + activity = StationActivity(tmp_path / "station_status") + + async def rotate() -> None: + """Nothing to rotate in these tests.""" + + small.state.station_service = StationService( + StationStore(tmp_path / "stations.json"), + session_adapter( + offered_cameras=lambda: frozenset({"cam_head", "cam_left"}), + change_blocked=lambda: live.blocked, + show_label=lambda label: None, + rotate_batch=rotate, + leave_station=activity.leave, + ), + "Deployment", + ) + small.state.station_activity = activity + small.state.recording_context = _Context(control_token=TOKEN) + small.state.operator_settings_store = OperatorSettingsStore(tmp_path / "operator_settings.json") + small.state.settings = SimpleNamespace(capture=SimpleNamespace(capture_server_url="ws://127.0.0.1:8082")) + return TestClient(small) + + +def _add(client: TestClient, fields: dict = BENCH) -> str: + response = client.post("/api/stations", json=fields, headers=AUTH) + assert response.status_code == 200, response.text + return response.json()["stations"][-1]["id"] + + +@pytest.mark.parametrize( + ("method", "path"), + [ + ("get", "/api/stations"), + ("post", "/api/stations"), + ("post", "/api/stations/select"), + ("put", "/api/stations/st_1"), + ("delete", "/api/stations/st_1"), + ("get", "/api/headset-address"), + ("get", "/api/station-activity"), + ("post", "/api/station-activity"), + ], +) +def test_every_route_answers_503_until_the_application_has_started(tmp_path, method, path): + response = getattr(_client(tmp_path, ready=False), method)(path) + assert response.status_code == 503 and response.headers["cache-control"] == "no-store" + + +def test_stations_are_added_edited_selected_and_deleted(tmp_path): + client = _client(tmp_path) + assert client.get("/api/stations").json()["stations"] == [] + bench = _add(client) + cart = _add(client, {"name": "Cart B", "camera_roles": {"ego": "cam_top"}}) + selected = client.post("/api/stations/select", json={"id": bench}, headers=AUTH).json() + assert (selected["selected"], selected["label"]) == (bench, "Bench A") + edited = client.put(f"/api/stations/{cart}", json={"headset_address": "192.168.4.20"}, headers=AUTH).json() + assert edited["stations"][1]["headset_address"] == "192.168.4.20" + assert edited["stations"][1]["problems"] == [ + "camera 'cam_top' (ego (head)) is not offered by the capture session" + ] + # A second client sees the same registry, read back from the file. + assert StationStore(tmp_path / "stations.json").load().selected.name == "Bench A" + remaining = client.delete(f"/api/stations/{bench}", headers=AUTH).json() + assert [station["name"] for station in remaining["stations"]] == ["Cart B"] + assert (remaining["selected"], remaining["label"]) == (None, "Deployment") + assert client.post("/api/stations/select", json={"id": None}, headers=AUTH).status_code == 200 + + +def test_the_headset_address_is_shown_only_to_a_caller_with_the_token(tmp_path): + client = _client(tmp_path) + _add(client, {**BENCH, "headset_address": "192.168.4.20"}) + assert "headset_address" not in client.get("/api/stations").json()["stations"][0] + assert ( + "headset_address" + not in client.get("/api/stations", headers={"X-Control-Token": "wrong"}).json()["stations"][0] + ) + assert client.get("/api/stations", headers=AUTH).json()["stations"][0]["headset_address"] == "192.168.4.20" + + +@pytest.mark.parametrize( + ("method", "path", "body"), + [ + ("post", "/api/stations", BENCH), + ("post", "/api/stations/select", {"id": None}), + ("put", "/api/stations/st_1", {"name": "X"}), + ("post", "/api/station-activity", {"state": "active"}), + ], +) +def test_a_change_without_the_token_is_refused_and_changes_nothing(tmp_path, method, path, body): + client = _client(tmp_path) + assert getattr(client, method)(path, json=body).status_code == 403 + assert getattr(client, method)(path, json=body, headers={"X-Control-Token": "wrong"}).status_code == 403 + assert not (tmp_path / "stations.json").exists() and not (tmp_path / "station_status").exists() + + +def test_a_delete_needs_the_token_in_its_header(tmp_path): + client = _client(tmp_path) + bench = _add(client) + assert client.delete(f"/api/stations/{bench}").status_code == 403 + assert client.delete(f"/api/stations/{bench}", headers={"X-Control-Token": "wrong"}).status_code == 403 + assert len(client.get("/api/stations").json()["stations"]) == 1 + + +def test_a_refused_change_says_why_and_an_unknown_station_is_not_found(tmp_path): + client = _client(tmp_path) + bench = _add(client) + duplicate = client.post("/api/stations", json={"name": "bench a"}, headers=AUTH) + assert (duplicate.status_code, duplicate.json()["detail"]) == (400, "a station named 'Bench A' already exists") + clash = client.put(f"/api/stations/{bench}", json={"camera_roles": {"wrist_right": "cam_head"}}, headers=AUTH) + assert (clash.status_code, clash.json()["detail"]) == ( + 400, + "camera 'cam_head' cannot fill both ego and wrist_right", + ) + assert client.post("/api/stations/select", json={"id": 7}, headers=AUTH).json()["detail"] == ( + "id must be a station id or null" + ) + for response in ( + client.put("/api/stations/st_missing", json={"name": "X"}, headers=AUTH), + client.delete("/api/stations/st_missing", headers=AUTH), + client.post("/api/stations/select", json={"id": "st_missing"}, headers=AUTH), + ): + assert (response.status_code, response.json()["detail"]) == (404, "no such station") + + +def test_the_station_in_use_cannot_change_during_a_take(tmp_path): + live = _Live() + client = _client(tmp_path, live) + bench, cart = _add(client), _add(client, {"name": "Cart B"}) + client.post("/api/stations/select", json={"id": bench}, headers=AUTH) + live.blocked = TAKE_IN_PROGRESS + assert client.get("/api/stations").json()["locked_reason"] == TAKE_IN_PROGRESS + for response in ( + client.post("/api/stations/select", json={"id": cart}, headers=AUTH), + client.put(f"/api/stations/{bench}", json={"name": "Bench Z"}, headers=AUTH), + client.delete(f"/api/stations/{bench}", headers=AUTH), + ): + assert (response.status_code, response.json()["detail"]) == (400, TAKE_IN_PROGRESS) + live.blocked = None + assert client.post("/api/stations/select", json={"id": cart}, headers=AUTH).json()["selected"] == cart + + +def test_a_registry_that_cannot_be_written_is_a_503(tmp_path, monkeypatch): + client = _client(tmp_path) + bench = _add(client) + + def refuse(self, registry): + raise OSError("disk full") + + monkeypatch.setattr(StationStore, "save", refuse) + assert client.post("/api/stations", json={"name": "Cart B"}, headers=AUTH).status_code == 503 + assert client.delete(f"/api/stations/{bench}", headers=AUTH).status_code == 503 + + +def test_the_camera_setup_the_page_reads_is_the_station_in_use(tmp_path): + client = _client(tmp_path) + saved = client.put("/api/operator-settings", json={"camera_type": "sensing_gmsl"}, headers=AUTH) + assert saved.json()["camera_type"] == "sensing_gmsl" # no station in use: the stored value applies + bench = _add(client, {**BENCH, "camera_type": "oak_d"}) + client.post("/api/stations/select", json={"id": bench}, headers=AUTH) + read = client.get("/api/operator-settings").json() + assert (read["camera_type"], read["camera_roles"]["wrist_left"]) == ("oak_d", "cam_left") + # An edit of "this station" from the existing settings controls is saved to the station in use. + changed = client.put("/api/operator-settings", json={"camera_roles": {"wrist_left": None}}, headers=AUTH) + assert changed.json()["camera_roles"] == {"ego": "cam_head", "wrist_left": None, "wrist_right": None} + assert client.get("/api/stations").json()["stations"][0]["camera_roles"]["wrist_left"] is None + refused = client.put("/api/operator-settings", json={"camera_roles": {"wrist_left": "cam_head"}}, headers=AUTH) + assert (refused.status_code, refused.json()["detail"]) == ( + 400, + "camera 'cam_head' cannot fill both ego and wrist_left", + ) + # With nothing in use again, the station-independent value is back, untouched by the station's edits. + client.post("/api/stations/select", json={"id": None}, headers=AUTH) + assert client.get("/api/operator-settings").json()["camera_type"] == "sensing_gmsl" + + +def test_invalid_saved_settings_still_show_the_station_in_use(tmp_path): + client = _client(tmp_path) + bench = _add(client, {**BENCH, "camera_type": "oak_d"}) + client.post("/api/stations/select", json={"id": bench}, headers=AUTH) + (tmp_path / "operator_settings.json").write_text("not json") + read = client.get("/api/operator-settings").json() + assert read["camera_type"] == "oak_d" and "invalid" in read["warning"] + + +def test_the_headset_address_reports_candidates_and_a_stale_saved_address(tmp_path, monkeypatch): + client = _client(tmp_path) + seen: list[str] = [] + + def candidates(url: str) -> list[HostAddress]: + seen.append(url) + return [HostAddress("10.0.0.42", "wlp2s0", "wireless")] + + monkeypatch.setattr(station_routes, "headset_addresses", candidates) + assert client.get("/api/headset-address").status_code == 403 + nothing_in_use = client.get("/api/headset-address", headers=AUTH).json() + assert nothing_in_use == { + "candidates": [{"address": "10.0.0.42", "interface": "wlp2s0", "kind": "wireless"}], + "saved": None, + "changed": False, + } + bench = _add(client, {**BENCH, "headset_address": "10.0.0.7"}) + client.post("/api/stations/select", json={"id": bench}, headers=AUTH) + stale = client.get("/api/headset-address", headers=AUTH).json() + assert (stale["saved"], stale["changed"]) == ("10.0.0.7", True) + client.put(f"/api/stations/{bench}", json={"headset_address": "10.0.0.42"}, headers=AUTH) + assert client.get("/api/headset-address", headers=AUTH).json()["changed"] is False + assert seen[0] == "ws://127.0.0.1:8082" + + +def test_activity_is_toggled_for_the_station_in_use(tmp_path): + client = _client(tmp_path) + assert client.get("/api/station-activity").json()["station"] == "Deployment" + bench = _add(client) + client.post("/api/stations/select", json={"id": bench}, headers=AUTH) + started = client.post("/api/station-activity", json={"state": "active"}, headers=AUTH).json() + assert (started["station"], started["state"]) == ("Bench A", "active") + noted = client.post("/api/station-activity", json={"notes": "left glove battery"}, headers=AUTH).json() + assert (noted["state"], noted["notes"]) == ("active", "left glove battery") + assert client.get("/api/station-activity").json()["notes"] == "left glove battery" + # Leaving the station stops its active time, so it does not keep counting for a station nobody is at. + client.post("/api/stations/select", json={"id": None}, headers=AUTH) + assert client.get("/api/station-activity").json()["station"] == "Deployment" + client.post("/api/stations/select", json={"id": bench}, headers=AUTH) + assert client.get("/api/station-activity").json()["state"] == "inactive" + + +def test_an_activity_change_must_name_something_valid(tmp_path, monkeypatch): + client = _client(tmp_path) + empty = client.post("/api/station-activity", json={}, headers=AUTH) + assert (empty.status_code, empty.json()["detail"]) == (400, "name a state, notes, or both") + invalid = client.post("/api/station-activity", json={"state": "paused"}, headers=AUTH) + assert (invalid.status_code, invalid.json()["detail"]) == (400, "state must be one of active, inactive") + + def refuse(self, station, **_changes): + raise OSError("disk full") + + monkeypatch.setattr(StationActivity, "change", refuse) + assert client.post("/api/station-activity", json={"state": "active"}, headers=AUTH).status_code == 503 + + +def test_the_real_application_gates_recording_on_the_station_in_use(monkeypatch, unused_tcp_port, tmp_path): + from egocap_web import app as app_module + + monkeypatch.setenv("EGOCAP_CAPTURE_SERVER_URL", f"ws://127.0.0.1:{unused_tcp_port}") + monkeypatch.delenv("EGOCAP_OPERATOR_SETTINGS_FILE", raising=False) + monkeypatch.delenv("EGOCAP_STATION_CONFIG", raising=False) + monkeypatch.setattr(app_module, "_recording_output_root", lambda data_dir: tmp_path) + with TestClient(real_app) as client: + context = client.app.state.recording_context + auth = {"X-Control-Token": context.control_token} + # No stations: the configuration-free default, where only capture itself decides readiness. + assert client.get("/api/stations").json()["label"] == "Station 01" + assert context.setup_block() is None + bench = client.post("/api/stations", json=BENCH, headers=auth).json()["stations"][0]["id"] + assert (tmp_path / ".egocap" / "stations.json").is_file() + assert context.snapshot()["not_ready_reason"] == "select a station before recording" + selected = client.post("/api/stations/select", json={"id": bench}, headers=auth).json() + assert (selected["label"], selected["locked_reason"]) == ("Bench A", None) + # The label every viewer sees, and the one the next recording session will carry, changed in process. + assert client.get("/api/capture-status").json()["station_label"] == "Bench A" + assert client.app.state.station_service.label() == "Bench A" + # Capture never connected here, so what the session offers is unknown and the station itself is fine. + assert context.setup_block() is None + client.put(f"/api/stations/{bench}", json={"camera_roles": {"ego": None}}, headers=auth) + assert context.snapshot()["not_ready_reason"] == ( + "station 'Bench A': no camera is assigned to the ego (head) role" + ) + active = client.post("/api/station-activity", json={"state": "active"}, headers=auth).json() + assert (active["station"], active["state"]) == ("Bench A", "active") + assert sorted(path.name for path in (tmp_path / "station_status").iterdir())[1].startswith("bench_a_") + assert client.get("/api/headset-address").status_code == 403 + assert client.get("/api/headset-address", headers=auth).status_code == 200 diff --git a/examples/egocap/tests/backend/test_station_service.py b/examples/egocap/tests/backend/test_station_service.py new file mode 100644 index 0000000000..572c09dcbd --- /dev/null +++ b/examples/egocap/tests/backend/test_station_service.py @@ -0,0 +1,210 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The station service: when the station in use may change, and what a change does to the live session.""" + +from __future__ import annotations + +import pytest + +from egocap_web.station_service import TAKE_IN_PROGRESS, StationService, session_adapter +from egocap_web.stations import StationError, StationNotFoundError, StationStore + +BENCH = {"name": "Bench A", "camera_roles": {"ego": "cam_head", "wrist_left": "cam_left"}} +CART = {"name": "Cart B", "camera_roles": {"ego": "cam_top"}} + + +class _Session: + """A stand-in live session that records what the service asked of it.""" + + def __init__(self): + self.offered: frozenset[str] | None = frozenset({"cam_head", "cam_left", "cam_top"}) + self.blocked: str | None = None + self.rotation_refusal: str | None = None + self.events: list[tuple[str, str]] = [] + + def adapter(self): + return session_adapter( + offered_cameras=lambda: self.offered, + change_blocked=lambda: self.blocked, + show_label=lambda label: self.events.append(("show", label)), + rotate_batch=self._rotate, + leave_station=lambda label: self.events.append(("leave", label)), + ) + + async def _rotate(self) -> None: + if self.rotation_refusal is not None: + raise StationError(self.rotation_refusal) + self.events.append(("rotate", "")) + + +def _service(tmp_path, session: _Session | None = None) -> tuple[StationService, _Session]: + session = session or _Session() + return StationService(StationStore(tmp_path / "stations.json"), session.adapter(), "Deployment"), session + + +async def _with_two_stations(tmp_path) -> tuple[StationService, _Session, str, str]: + service, session = _service(tmp_path) + bench = await service.add(BENCH) + cart = await service.add(CART) + return service, session, bench.station_id, cart.station_id + + +async def test_an_empty_registry_keeps_the_deployment_label_and_blocks_nothing(tmp_path): + service, session = _service(tmp_path) + assert service.label() == "Deployment" and service.block_reason() is None + assert service.listing(private=False) == { + "stations": [], + "selected": None, + "roles": ["ego", "wrist_left", "wrist_right"], + "camera_types": ["sensing_gmsl", "oak_d"], + "label": "Deployment", + "locked_reason": None, + } + assert session.events == [] + + +async def test_adding_stations_changes_nothing_about_the_session_but_then_one_must_be_selected(tmp_path): + service, session, bench_id, _ = await _with_two_stations(tmp_path) + assert session.events == [] and service.label() == "Deployment" + assert service.block_reason() == "select a station before recording" + await service.select(bench_id) + assert service.block_reason() is None + + +async def test_selecting_a_station_relabels_the_session_and_rotates_the_batch(tmp_path): + service, session, bench_id, cart_id = await _with_two_stations(tmp_path) + await service.select(bench_id) + assert service.label() == "Bench A" + # Rotated first: a session still open under the old label must never receive a take for the new one. + assert session.events == [("rotate", ""), ("leave", "Deployment"), ("show", "Bench A")] + session.events.clear() + await service.select(cart_id) + assert session.events == [("rotate", ""), ("leave", "Bench A"), ("show", "Cart B")] + session.events.clear() + await service.select(cart_id) # no change of label, so nothing to apply + assert session.events == [] + await service.select(None) + assert service.label() == "Deployment" and session.events[-1] == ("show", "Deployment") + + +async def test_switching_is_blocked_during_a_take_and_allowed_afterwards(tmp_path): + service, session, bench_id, cart_id = await _with_two_stations(tmp_path) + await service.select(bench_id) + session.events.clear() + session.blocked = TAKE_IN_PROGRESS + for change in ( + lambda: service.select(cart_id), + lambda: service.select(None), + lambda: service.update(bench_id, {"name": "Bench Z"}), + lambda: service.update_selected({"camera_type": "oak_d"}), + lambda: service.remove(bench_id), + ): + with pytest.raises(StationError) as refused: + await change() + assert refused.value.public_message == TAKE_IN_PROGRESS + assert service.registry.selected_id == bench_id and service.label() == "Bench A" and session.events == [] + assert service.listing(private=False)["locked_reason"] == TAKE_IN_PROGRESS + # A station that is not in use is unaffected by the take, so it can still be edited, added or deleted. + await service.update(cart_id, {"name": "Cart C"}) + await service.remove(cart_id) + cart_id = (await service.add(CART)).station_id + session.blocked = None + await service.select(cart_id) + assert service.label() == "Cart B" + + +async def test_editing_the_station_in_use_applies_at_once(tmp_path): + service, session, bench_id, _ = await _with_two_stations(tmp_path) + await service.select(bench_id) + session.events.clear() + await service.update(bench_id, {"name": "Bench Z"}) + assert service.label() == "Bench Z" + assert session.events == [("rotate", ""), ("leave", "Bench A"), ("show", "Bench Z")] + session.events.clear() + updated = await service.update_selected({"camera_roles": {"wrist_left": None}}) + assert updated.camera_roles == {"ego": "cam_head", "wrist_left": None, "wrist_right": None} + assert session.events == [] # the label did not change + + +async def test_editing_this_station_with_nothing_selected_is_left_to_the_caller(tmp_path): + service, _, _, _ = await _with_two_stations(tmp_path) + assert await service.update_selected({"camera_type": "oak_d"}) is None + + +async def test_deleting_the_station_in_use_returns_to_the_deployment_label(tmp_path): + service, session, bench_id, _ = await _with_two_stations(tmp_path) + await service.select(bench_id) + await service.remove(bench_id) + assert service.registry.selected is None and service.label() == "Deployment" + assert session.events[-2:] == [("leave", "Bench A"), ("show", "Deployment")] + assert service.block_reason() == "select a station before recording" + + +async def test_a_refused_rotation_refuses_the_whole_change(tmp_path): + service, session, bench_id, _ = await _with_two_stations(tmp_path) + session.rotation_refusal = "an episode is active" + with pytest.raises(StationError): + await service.select(bench_id) + assert service.registry.selected is None and service.label() == "Deployment" + assert StationStore(tmp_path / "stations.json").load().selected is None + assert session.events == [] + + +async def test_a_refused_change_never_rotates_the_batch(tmp_path): + service, session, bench_id, _ = await _with_two_stations(tmp_path) + await service.select(bench_id) + session.events.clear() + with pytest.raises(StationError): + await service.update(bench_id, {"name": "Cart B"}) + with pytest.raises(StationNotFoundError): + await service.select("st_missing") + assert session.events == [] and service.label() == "Bench A" + + +async def test_the_station_in_use_blocks_recording_until_it_can_record(tmp_path): + service, session, bench_id, _ = await _with_two_stations(tmp_path) + await service.select(bench_id) + session.offered = frozenset({"cam_head"}) + assert service.block_reason() == ( + "station 'Bench A': camera 'cam_left' (left wrist) is not offered by the capture session" + ) + await service.update_selected({"camera_roles": {"ego": None, "wrist_left": None}}) + assert service.block_reason() == "station 'Bench A': no camera is assigned to the ego (head) role" + session.offered = None # before a capture session is accepted only the assignment itself is judged + await service.update_selected({"camera_roles": {"ego": "cam_elsewhere"}}) + assert service.block_reason() is None + + +async def test_the_listing_shows_each_stations_problems_and_keeps_the_headset_address_private(tmp_path): + service, session, bench_id, cart_id = await _with_two_stations(tmp_path) + await service.update(cart_id, {"headset_address": "192.168.4.20", "camera_roles": {"ego": "cam_gone"}}) + await service.select(bench_id) + public = service.listing(private=False) + assert public["selected"] == bench_id and public["label"] == "Bench A" + assert [station["problems"] for station in public["stations"]] == [ + [], + ["camera 'cam_gone' (ego (head)) is not offered by the capture session"], + ] + assert all("headset_address" not in station for station in public["stations"]) + private = service.listing(private=True) + assert [station["headset_address"] for station in private["stations"]] == [None, "192.168.4.20"] + + +async def test_the_registry_survives_a_restart(tmp_path): + service, _, bench_id, _ = await _with_two_stations(tmp_path) + await service.select(bench_id) + restarted, session = _service(tmp_path) + assert restarted.label() == "Bench A" and restarted.registry == service.registry + assert session.events == [] # startup publishes the label itself; nothing is rotated + + +async def test_an_unreadable_registry_starts_empty_with_a_warning_until_it_is_replaced(tmp_path): + (tmp_path / "stations.json").write_text("not json") + service, _ = _service(tmp_path) + assert service.registry.stations == () and service.block_reason() is None + assert "unreadable" in service.listing(private=False)["warning"] + await service.add(BENCH) + assert "warning" not in service.listing(private=False) + assert (tmp_path / "stations.json.invalid").read_text() == "not json" diff --git a/examples/egocap/tests/backend/test_stations.py b/examples/egocap/tests/backend/test_stations.py new file mode 100644 index 0000000000..8673a9e865 --- /dev/null +++ b/examples/egocap/tests/backend/test_stations.py @@ -0,0 +1,228 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The station registry: its validation, its changes, and the file that keeps it.""" + +from __future__ import annotations + +import json + +import pytest + +from egocap_web.stations import ( + MAX_STATION_NAME_CHARS, + MAX_STATIONS, + Station, + StationError, + StationNotFoundError, + StationRegistry, + StationStore, + parse_registry, + station_store_path, +) + +BENCH = {"name": "Bench A", "camera_type": "oak_d", "camera_roles": {"ego": "cam_head", "wrist_left": "cam_left"}} +CART = {"name": "Cart B", "camera_roles": {"ego": "cam_top", "wrist_right": "cam_grip"}} + + +def _ids(): + counter = iter(range(1000)) + return lambda: f"st_{next(counter)}" + + +def _two_stations() -> StationRegistry: + new_id = _ids() + return StationRegistry().added(BENCH, new_id).added(CART, new_id) + + +def _refusal(action) -> str: + with pytest.raises(StationError) as refused: + action() + return refused.value.public_message + + +def test_two_stations_with_different_cameras_round_trip_through_the_file(tmp_path): + store = StationStore(tmp_path / "nested" / "stations.json") + assert store.load() == StationRegistry() + registry = _two_stations().selecting("st_1") + store.save(registry) + assert store.load() == registry + assert registry.selected.name == "Cart B" + assert registry.find("st_0").camera_roles == {"ego": "cam_head", "wrist_left": "cam_left", "wrist_right": None} + assert json.loads(store.path.read_text())["stations"][1] == { + "id": "st_1", + "name": "Cart B", + "camera_type": None, + "camera_roles": {"ego": "cam_top", "wrist_left": None, "wrist_right": "cam_grip"}, + "headset_address": None, + } + assert sorted(path.name for path in store.path.parent.iterdir()) == ["stations.json"] + + +def test_a_camera_in_two_roles_is_refused_naming_the_camera_and_both_roles(): + duplicate = {"name": "Bench C", "camera_roles": {"ego": "cam_head", "wrist_left": "cam_head"}} + assert _refusal(lambda: StationRegistry().added(duplicate)) == ( + "camera 'cam_head' cannot fill both ego and wrist_left" + ) + # The same rule holds when an edit of one role collides with a role already saved. + registry = _two_stations() + assert "cannot fill both ego and wrist_right" in _refusal( + lambda: registry.updated("st_1", {"camera_roles": {"ego": "cam_grip"}}) + ) + assert registry.find("st_1").camera_roles["ego"] == "cam_top" + + +@pytest.mark.parametrize( + ("fields", "reason"), + [ + ({"name": "bench a"}, "a station named 'Bench A' already exists"), + ({"name": " Bench A "}, "a station named 'Bench A' already exists"), + ({"name": " "}, "station name cannot be empty"), + ({}, "station name must be text"), + ({"name": 7}, "station name must be text"), + ({"name": "x" * (MAX_STATION_NAME_CHARS + 1)}, f"limited to {MAX_STATION_NAME_CHARS} characters"), + ({"name": "Bay\x071"}, "control characters"), + ({"name": "New", "camera_type": "webcam"}, "camera_type must be one of"), + ({"name": "New", "camera_roles": {"overhead": "cam"}}, "unknown camera role(s): overhead"), + ({"name": "New", "camera_roles": {"ego": ""}}, "camera_roles.ego must be a camera name or null"), + ({"name": "New", "camera_roles": ["cam"]}, "camera_roles must be an object"), + ({"name": "New", "headset_address": "headset.local"}, "'headset.local' is not an IP address"), + ({"name": "New", "headset_address": 7}, "headset_address must be an IP address or null"), + ({"name": "New", "colour": "red", "size": 1}, "unknown station field(s): colour, size"), + ], +) +def test_an_invalid_new_station_is_refused_with_a_specific_reason(fields, reason): + assert reason in _refusal(lambda: _two_stations().added(fields)) + + +def test_a_change_that_is_not_an_object_is_refused(): + assert _refusal(lambda: StationRegistry().added(["Bench"])) == "a station change must be an object" + assert _refusal(lambda: _two_stations().updated("st_0", "Bench")) == "a station change must be an object" + + +def test_a_name_is_tidied_and_a_legacy_body_token_is_ignored(): + registry = StationRegistry().added({"name": " Bay \t 1 ", "control_token": "secret"}, _ids()) + assert registry.stations[0] == Station(station_id="st_0", name="Bay 1") + + +def test_a_new_id_that_is_taken_is_drawn_again(): + draws = iter(["st_0", "st_0", "st_9"]) + registry = StationRegistry().added(BENCH, lambda: next(draws)).added(CART, lambda: next(draws)) + assert [station.station_id for station in registry.stations] == ["st_0", "st_9"] + + +def test_a_real_id_is_generated_when_none_is_supplied(): + station_id = StationRegistry().added(BENCH).stations[0].station_id + assert station_id.startswith("st_") and len(station_id) == 11 + + +def test_the_registry_is_bounded(): + registry, new_id = StationRegistry(), _ids() + for index in range(MAX_STATIONS): + registry = registry.added({"name": f"Station {index}"}, new_id) + assert f"at most {MAX_STATIONS} stations" in _refusal(lambda: registry.added({"name": "One more"}, new_id)) + + +def test_an_update_changes_only_the_fields_it_names(): + registry = _two_stations().updated( + "st_0", {"name": "Bench Z", "camera_type": None, "headset_address": " 192.168.004.20 ".replace("004", "4")} + ) + station = registry.find("st_0") + assert (station.name, station.camera_type, station.headset_address) == ("Bench Z", None, "192.168.4.20") + assert station.camera_roles == {"ego": "cam_head", "wrist_left": "cam_left", "wrist_right": None} + cleared = registry.updated("st_0", {"camera_roles": {"wrist_left": None}, "headset_address": None}) + assert cleared.find("st_0").camera_roles["wrist_left"] is None + assert cleared.find("st_0").headset_address is None + # Renaming a station to its own name, in another case, is not a duplicate of itself. + assert registry.updated("st_0", {"name": "bench z"}).find("st_0").name == "bench z" + assert registry.find("st_1") == _two_stations().find("st_1") + + +def test_an_update_is_refused_for_a_taken_name_or_bad_roles(): + registry = _two_stations() + assert _refusal(lambda: registry.updated("st_0", {"name": "CART B"})) == ( + "a station named 'Cart B' already exists" + ) + assert "camera_roles must be an object" in _refusal(lambda: registry.updated("st_0", {"camera_roles": "cam"})) + + +def test_an_unknown_station_is_not_found_for_every_change(): + registry = _two_stations() + for action in ( + lambda: registry.updated("st_7", {"name": "X"}), + lambda: registry.removed("st_7"), + lambda: registry.selecting("st_7"), + ): + with pytest.raises(StationNotFoundError): + action() + + +def test_selection_follows_removal(): + registry = _two_stations().selecting("st_0") + assert registry.removed("st_1").selected_id == "st_0" + emptied = registry.removed("st_0") + assert emptied.selected is None and [station.name for station in emptied.stations] == ["Cart B"] + assert registry.selecting(None).selected is None + + +def test_a_station_reports_why_it_cannot_record(): + bench = _two_stations().find("st_0") + assert bench.problems(None) == [] + assert bench.problems(frozenset({"cam_head", "cam_left"})) == [] + assert bench.problems(frozenset({"cam_head"})) == [ + "camera 'cam_left' (left wrist) is not offered by the capture session" + ] + bare = Station(station_id="st_9", name="Bare") + assert bare.problems(None) == ["no camera is assigned to the ego (head) role"] + assert bare.problems(frozenset()) == ["no camera is assigned to the ego (head) role"] + + +@pytest.mark.parametrize( + ("raw", "reason"), + [ + ([], "the station registry must be an object"), + ({"stations": {}}, "stations must be a list"), + ({"stations": [{"name": "A"}] * (MAX_STATIONS + 1)}, "stations must be a list"), + ({"stations": ["Bench"]}, "each station must be an object"), + ({"stations": [{"name": "A"}]}, "each station needs an id"), + ({"stations": [{"id": "", "name": "A"}]}, "each station needs an id"), + ({"stations": [{"id": "a", "name": "A"}, {"id": "a", "name": "B"}]}, "station id 'a' appears twice"), + ({"stations": [{"id": "a", "name": "A"}, {"id": "b", "name": "a"}]}, "a station named 'A' already exists"), + ({"stations": [{"id": "a", "name": "A"}], "selected": "b"}, "selected station is not in the registry"), + ({"stations": [{"id": "a", "name": "A"}], "selected": 1}, "selected station is not in the registry"), + ], +) +def test_a_hand_edited_registry_must_hold_to_the_same_rules(raw, reason): + assert reason in _refusal(lambda: parse_registry(raw)) + + +def test_an_empty_object_is_an_empty_registry(): + assert parse_registry({}) == StationRegistry() + + +@pytest.mark.parametrize("content", [b"not json", b"\xff\xfe", b"[1, 2]"]) +def test_an_unusable_file_is_refused_on_load_and_set_aside_on_the_next_change(tmp_path, content): + store = StationStore(tmp_path / "stations.json") + store.path.write_bytes(content) + with pytest.raises(StationError): + store.load() + before, after = store.change(lambda registry: registry.added(BENCH, _ids())) + assert before == StationRegistry() and store.load() == after + assert (tmp_path / "stations.json.invalid").read_bytes() == content + + +def test_a_refused_change_leaves_the_file_as_it_was(tmp_path): + store = StationStore(tmp_path / "stations.json") + store.save(_two_stations()) + saved = store.path.read_text() + with pytest.raises(StationError): + store.change(lambda registry: registry.added({"name": "Bench A"})) + assert store.path.read_text() == saved + assert sorted(path.name for path in tmp_path.iterdir()) == ["stations.json"] + + +def test_the_registry_sits_beside_the_operator_settings(tmp_path): + assert station_store_path(tmp_path / ".egocap" / "operator_settings.json") == ( + tmp_path / ".egocap" / "stations.json" + ) diff --git a/examples/egocap/tests/backend/test_viser_scene.py b/examples/egocap/tests/backend/test_viser_scene.py index 1519103418..d038d817bf 100644 --- a/examples/egocap/tests/backend/test_viser_scene.py +++ b/examples/egocap/tests/backend/test_viser_scene.py @@ -708,6 +708,12 @@ def set_recording(self, coordinator): to assert about it -- just accept the attachment like the real monitor does.""" + def set_station_label(self, label): + self.station_label = label + + def offered_camera_names(self): + return None + async def test_the_lifespan_stops_capture_even_when_the_3d_view_fails_to_stop_or_start_is_cancelled(monkeypatch): import asyncio From 0d8e75ec76e202e4e962217433c8d7c730ba6ebc Mon Sep 17 00:00:00 2001 From: Shawn Hwang Date: Mon, 16 Nov 2026 10:43:42 -0800 Subject: [PATCH 02/13] feat(egocap): manage stations from the Settings dialog and toggle activity The Station tab of the Settings dialog now lists the stations and the one in use, and the status strip carries the station's active/inactive toggle. - Stations card: add, rename, delete and select stations. Each row shows what fills its roles and why it cannot record yet. The first station takes over the camera setup already saved and is put in use. Deleting asks for confirmation. During a take the station in use is frozen and the others stay editable. - The camera type and role cards edit the station in use, and LiveKit cameras can now be assigned to roles like any other offered camera. - Headset address card: shows the capture host address to enter in the headset, wireless first, remembers it per station, and warns when the saved one is no longer one of the host's. - Status strip: the toggle starts the day on its first press and keeps both totals in view between loads. - The recording indicator and the Record button give the backend's reason when a take would be refused. Co-Authored-By: Claude Fable 5.2 Signed-off-by: Shawn Hwang --- examples/egocap/backend/README.md | 23 ++ examples/egocap/frontend/README.md | 3 + .../src/App.liveRecordingWire.test.tsx | 1 + .../frontend/src/App.operatorLayout.test.tsx | 15 ++ examples/egocap/frontend/src/App.test.tsx | 2 +- examples/egocap/frontend/src/App.tsx | 22 +- .../frontend/src/HeadsetAddressCard.test.tsx | 139 ++++++++++ .../frontend/src/HeadsetAddressCard.tsx | 138 ++++++++++ .../egocap/frontend/src/OperatorBar.test.tsx | 7 + examples/egocap/frontend/src/OperatorBar.tsx | 5 +- .../src/RecordingPanel.taskCatalog.test.tsx | 1 + .../frontend/src/RecordingPanel.test.tsx | 14 + .../src/RecordingPanel.voice.test.tsx | 1 + .../frontend/src/SettingsPanel.test.tsx | 85 +++++- .../egocap/frontend/src/SettingsPanel.tsx | 120 +++++---- .../src/StationActivityToggle.test.tsx | 154 +++++++++++ .../frontend/src/StationActivityToggle.tsx | 138 ++++++++++ .../egocap/frontend/src/StationsCard.test.tsx | 212 +++++++++++++++ examples/egocap/frontend/src/StationsCard.tsx | 249 ++++++++++++++++++ .../frontend/src/recordingEligibility.ts | 4 +- .../egocap/frontend/src/recordingTypes.ts | 3 + examples/egocap/frontend/src/sentence.ts | 8 + .../egocap/frontend/src/settingsParts.tsx | 47 ++++ .../frontend/src/settingsTestDoubles.ts | 74 ++++++ .../egocap/frontend/src/stationsApi.test.ts | 113 ++++++++ examples/egocap/frontend/src/stationsApi.ts | 176 +++++++++++++ examples/egocap/frontend/src/styles.css | 107 ++++++++ .../src/useCaptureSession.hook.test.ts | 36 +++ .../egocap/frontend/src/useCaptureSession.ts | 2 + 29 files changed, 1833 insertions(+), 66 deletions(-) create mode 100644 examples/egocap/frontend/src/HeadsetAddressCard.test.tsx create mode 100644 examples/egocap/frontend/src/HeadsetAddressCard.tsx create mode 100644 examples/egocap/frontend/src/StationActivityToggle.test.tsx create mode 100644 examples/egocap/frontend/src/StationActivityToggle.tsx create mode 100644 examples/egocap/frontend/src/StationsCard.test.tsx create mode 100644 examples/egocap/frontend/src/StationsCard.tsx create mode 100644 examples/egocap/frontend/src/sentence.ts create mode 100644 examples/egocap/frontend/src/settingsParts.tsx create mode 100644 examples/egocap/frontend/src/stationsApi.test.ts create mode 100644 examples/egocap/frontend/src/stationsApi.ts diff --git a/examples/egocap/backend/README.md b/examples/egocap/backend/README.md index c2241b630e..e07c4b63c2 100644 --- a/examples/egocap/backend/README.md +++ b/examples/egocap/backend/README.md @@ -31,6 +31,9 @@ or restarts it. | `GET /api/capture-status` | Thin HTTP inspection endpoint mirroring the latest snapshot; the frontend does not poll this during normal operation. | | `GET /api/settings` | The backend's effective configuration (CaptureServer URL, sources, station file, recording root, 3D view, origin policy), read-only and gated by the `X-Control-Token` header; the page's Advanced settings tab shows it. Secrets are reported as present or absent, never by value. | | `GET`/`PUT /api/operator-settings` | The operator's station setup: the camera type (`sensing_gmsl` or `oak_d`), camera roles (`ego`, `wrist_left`, `wrist_right`), the task catalog the recording panel's picker offers (`task_file`) and the task it preselects (`preselected_task`). Kept in `.egocap/operator_settings.json` under the recording output (hidden from the recordings browser) (`EGOCAP_OPERATOR_SETTINGS_FILE` overrides the path) so every browser sees the same values. `PUT` names only the fields it changes and uses `X-Control-Token`; legacy JSON `control_token` remains accepted. A wrong token is 403 and bodies above 16 KiB are rejected with 413 before parsing. | +| `GET`/`POST /api/stations`, `PUT`/`DELETE /api/stations/{id}`, `POST /api/stations/select` | The station registry: the stations an operator chooses between and the one in use. A station is a name, a camera type, the camera filling each role and the capture host address last given to its headset. Kept in `stations.json` beside the operator settings. Every change uses `X-Control-Token` and answers with the new listing; a refusal is a 400 with the specific reason (a duplicate name, a camera in two roles, an unknown field), and an unknown id is 404. The station in use cannot be selected, edited or deleted while a take is being written. A station's headset address is listed only when the `GET` carries the token. See [Stations](#stations). | +| `GET /api/headset-address` | The addresses to enter in the headset, wireless first, the one saved for the station in use, and whether that one is stale. Needs `X-Control-Token`. | +| `GET`/`POST /api/station-activity` | Today's active and inactive time for the station in use. `POST` (`X-Control-Token`) sets `state` (`active` or `inactive`), the blocker `notes`, or both, and rewrites that station's daily activity log. | | `POST /api/task-files/import`, `DELETE /api/task-files/{name}` | Import a task catalog the operator supplies — by `name` + `content` (text uploaded from the browser) — into the imported-catalog directory beside the operator settings, once it parses; and remove an imported one. `POST` and `DELETE` use the `X-Control-Token` header (legacy JSON tokens remain accepted for `POST`); `DELETE` refuses removal of the selected catalog (409); imports also refuse replacement of that catalog until it is deselected. Imports appear in `GET /api/task-files` (as `imported`) and shadow a shipped catalog of the same name. | | `GET /api/tools` | The operator tools the Settings drawer offers (headset calibration, glove calibration, fisheye rectification for the SENSING cameras), each with whether this build can launch it. None can yet. | | `GET /api/livekit-token?room=ROOM` | Viewer token (subscribe and data messages, no media publishing) for a LiveKit room the session offers (404 otherwise, 503 without signing credentials). Which streams exist comes from CaptureServer's session message. | @@ -51,6 +54,26 @@ configured-but-invalid file blocks new recording AND requests no cameras at all goes empty too, it is not unaffected), with a reason shown in the UI, never a silent fallback. Everything else is an environment variable: +### Stations + +A site usually has several stations, and an operator picks the one they are at. The registry +([`stations.py`](egocap_web/stations.py)) holds them; the Settings dialog's Station tab edits it. + +- **No stations** is the configuration-free default: the deployment's own station label applies and no station + rule blocks recording. +- **Once stations exist**, a take is refused until one is in use and can record: its ego role is assigned and every + camera it names is offered by the capture session. The reason is published as `not_ready_reason` in the recording + snapshot and returned by a refused `start_episode`. +- **Changing the station in use applies in process.** The label shown and recorded changes at once and the + recording batch rotates, so the next take opens a session carrying the new station's name. It is refused while a + take is being written. Which cameras CaptureServer is asked for stays a deployment setting (the station file); + restarting the backend is the only way to change that. +- **The station in use supplies the camera type and roles** that `GET /api/operator-settings` returns, and a `PUT` + of those two fields is saved to it. +- **Activity.** `station_status/.json` under the recording output holds each station's active and inactive + intervals for that day, and `station_status/__activity.json` is the daily log, rewritten on every + change. Both are written atomically and stay on this machine. Leaving a station stops its active time. + | Variable | Default | Meaning | | --- | --- | --- | | `EGOCAP_STATION_CONFIG` | unset (development default) | Path to the deployment station YAML described above. | diff --git a/examples/egocap/frontend/README.md b/examples/egocap/frontend/README.md index 6d3d502d86..964f207b78 100644 --- a/examples/egocap/frontend/README.md +++ b/examples/egocap/frontend/README.md @@ -76,6 +76,9 @@ The page is built for an operator mid-take: the cameras fill it, and everything until then it says `SET UP` and what is missing. A command in flight shows at once (`STOPPING` while a take is written), because the backend's own phase only changes when the command finishes. A stale feed shows `NO FEED`, never a retained `REC`. +- **Status strip (under the bar).** The station in use, its active/inactive toggle, and the capture headline. The toggle + (`StationActivityToggle.tsx`) marks the station active while it is collecting and blocked while it is not; nothing is + counted before the first press of the day, and both totals stay in view. It needs the control token to change. - **Camera stage (middle).** It takes every pixel the bar above and the dock below leave. The head camera (the one named `head*`, otherwise the first) takes the left two-thirds and the others stack on the right; each tile carries its name and measured / advertised Hz and latency on the picture. A live take puts a red frame around the stage. diff --git a/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx b/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx index 7218e3b4e2..7097714b44 100644 --- a/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx +++ b/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx @@ -101,6 +101,7 @@ const activeSnapshot: RecordingSnapshot = { savedCount: 0, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 0, }; diff --git a/examples/egocap/frontend/src/App.operatorLayout.test.tsx b/examples/egocap/frontend/src/App.operatorLayout.test.tsx index 37fe307ff7..aff06d4429 100644 --- a/examples/egocap/frontend/src/App.operatorLayout.test.tsx +++ b/examples/egocap/frontend/src/App.operatorLayout.test.tsx @@ -58,6 +58,7 @@ function recording(overrides: Partial = {}): RecordingSnapsho savedCount: 3, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 1, ...overrides, }; @@ -147,6 +148,20 @@ describe("operator page layout", () => { }); +describe("station activity in the status strip", () => { + afterEach(() => vi.unstubAllGlobals()); + + it("shows the station's toggle beside its name once today's activity is read", async () => { + const activity = { station: "Station", date: "2026-03-09", state: "active", since: 1, active_seconds: 3_720, inactive_seconds: 0, blocker_count: 0, notes: "", as_of: 2 }; + const fetched = vi.fn(async (url: string) => new Response(JSON.stringify(url === "/api/station-activity" ? activity : {}), { status: url === "/api/station-activity" ? 200 : 503 })); + vi.stubGlobal("fetch", fetched); + const { container } = mount(); + const toggle = await screen.findByRole("button", { name: /Station active/ }); + expect(toggle.textContent).toBe("Active · 1h 02m"); + expect(container.querySelector(".status-strip .status-station + .station-activity")).not.toBeNull(); + }); +}); + describe("resizing the side panel", () => { const widthOf = (container: HTMLElement) => (container.querySelector(".op-body") as HTMLElement).style.getPropertyValue("--op-sidebar-width"); diff --git a/examples/egocap/frontend/src/App.test.tsx b/examples/egocap/frontend/src/App.test.tsx index 8999d9fcf4..56fe1e87e1 100644 --- a/examples/egocap/frontend/src/App.test.tsx +++ b/examples/egocap/frontend/src/App.test.tsx @@ -478,7 +478,7 @@ describe("Settings modal recording isolation", () => { recordingSnapshot: { batchId: "b1", episodePhase: "RECORDING", currentEpisodeId: "e1", currentEpisodeElapsedMs: 0, taskText: "Fold towel", taskDetails: "", defaultOperator: null, autoFillOperatorName: false, - savedCount: 0, lastResult: null, readyToRecord: true, revision: 0, + savedCount: 0, lastResult: null, readyToRecord: true, notReadyReason: null, revision: 0, }, })); const { container } = render(); diff --git a/examples/egocap/frontend/src/App.tsx b/examples/egocap/frontend/src/App.tsx index c16d4c220e..7bb2c62aaa 100644 --- a/examples/egocap/frontend/src/App.tsx +++ b/examples/egocap/frontend/src/App.tsx @@ -35,6 +35,7 @@ import { deviceTone, retainedTone, type Tone } from "./deviceHealth"; import { PoseViserPanel } from "./PoseViserPanel"; import { RecordingPanel } from "./RecordingPanel"; import { SettingsPanel } from "./SettingsPanel"; +import { StationActivityToggle } from "./StationActivityToggle"; import { useOperatorSettings } from "./useOperatorSettings"; import { buildRecordingActions } from "./recordingActions"; import type { RecordingPhase } from "./recordingUiReducer"; @@ -240,16 +241,25 @@ function AppHeader({ ); } -/** The compact status row beneath the header: station and the real capture - * lifecycle headline (a quiet one-liner, not a large hero). The supporting +/** The compact status row beneath the header: station, its active/inactive + * toggle, and the real capture lifecycle headline (a quiet one-liner, not a large hero). The supporting * session/provider details are reached by scrolling to their own collapsed * disclosure at the bottom of the page, not a link from here. A normal * running/current state stays quiet here; an error or stale feed instead * gets a visible banner from `StaleOrErrorBanner` below. */ -function StatusLine({ response, presentation }: { response: CaptureStatusResponse | null; presentation: Presentation }) { +function StatusLine({ + response, + presentation, + controlToken, +}: { + response: CaptureStatusResponse | null; + presentation: Presentation; + controlToken: string | null; +}) { return (
{response?.station_label ?? "Station"} + {presentation.freshnessLabel !== null && {presentation.freshnessLabel}} {presentation.headline} @@ -491,8 +501,8 @@ export default function App() { setSettingsOpen(false); setSettingsGeneration((n) => n + 1); }; - // Camera roles use the capture streams currently available on main. - const cameraSources = (snapshot?.started?.streams ?? []).filter((s) => s.kind === "camera").map((s) => s.name); + // Every camera the session offers can fill a role, whichever path its video takes to the page. + const cameraSources = (snapshot?.started?.streams ?? []).filter((s) => s.kind === "camera" || s.kind === "livekit_camera").map((s) => s.name); return (
@@ -530,7 +540,7 @@ export default function App() { hasControlToken={controlToken !== null} pendingPhase={panelPhase} /> - + {/* The cameras are the page: they take every pixel the status bar above and the controls below leave. */}
diff --git a/examples/egocap/frontend/src/HeadsetAddressCard.test.tsx b/examples/egocap/frontend/src/HeadsetAddressCard.test.tsx new file mode 100644 index 0000000000..17b497f816 --- /dev/null +++ b/examples/egocap/frontend/src/HeadsetAddressCard.test.tsx @@ -0,0 +1,139 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** The Headset address card: which address it shows, remembering it per station, and warning when it is stale. */ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react"; +import { HeadsetAddressCard, type HeadsetAddressBackend } from "./HeadsetAddressCard"; +import { SettingsHttpError } from "./settingsApi"; +import { HEADSET_ADDRESS_FIXTURE, STATIONS_FIXTURE } from "./settingsTestDoubles"; +import type { HeadsetAddress, StationRecord } from "./stationsApi"; + +afterEach(cleanup); + +const BENCH: StationRecord = { + id: "st_1", + name: "Bench A", + camera_type: null, + camera_roles: { ego: "cam_head", wrist_left: null, wrist_right: null }, + problems: [], + headset_address: null, +}; + +const TWO_NETWORKS: HeadsetAddress = { + candidates: [ + { address: "10.0.0.42", interface: "wlp2s0", kind: "wireless" }, + { address: "192.168.1.10", interface: "enp3s0", kind: "wired" }, + ], + saved: null, + changed: false, +}; + +function renderCard( + answer: HeadsetAddress | Error = HEADSET_ADDRESS_FIXTURE, + props: { controlToken?: string | null; station?: StationRecord | null } = {}, +) { + const backend: HeadsetAddressBackend = { + loadHeadsetAddress: vi.fn(async () => { + if (answer instanceof Error) throw answer; + return answer; + }), + updateStation: vi.fn(async () => STATIONS_FIXTURE), + }; + const onListing = vi.fn(); + const view = (station: StationRecord | null) => ( + + ); + const utils = render(view(props.station === undefined ? BENCH : props.station)); + return { backend, onListing, rerender: (station: StationRecord | null) => utils.rerender(view(station)) }; +} + +const address = () => screen.findByLabelText("Address to enter in the headset"); +const mark = () => screen.getByRole("button", { name: "Mark as entered in the headset" }) as HTMLButtonElement; + +describe("HeadsetAddressCard", () => { + it("shows the host's address and where it comes from", async () => { + const { backend } = renderCard(); + expect((await address()).textContent).toBe("10.0.0.42"); + expect(screen.getByText("10.0.0.42 (wlp2s0, wireless)")).toBeTruthy(); + expect(screen.queryByLabelText("Network to use")).toBeNull(); // one candidate: nothing to choose + expect(backend.loadHeadsetAddress).toHaveBeenCalledWith("tok", expect.any(AbortSignal)); + }); + + it("offers a choice of networks, wireless first, and saves the one entered with the station in use", async () => { + const { backend, onListing } = renderCard(TWO_NETWORKS); + expect((await address()).textContent).toBe("10.0.0.42"); + const chooser = screen.getByLabelText("Network to use") as HTMLSelectElement; + expect(Array.from(chooser.options).map((option) => option.textContent)).toEqual(["10.0.0.42 (wlp2s0, wireless)", "192.168.1.10 (enp3s0, wired)"]); + fireEvent.change(chooser, { target: { value: "192.168.1.10" } }); + expect((await address()).textContent).toBe("192.168.1.10"); + fireEvent.click(mark()); + await waitFor(() => expect(onListing).toHaveBeenCalledWith(STATIONS_FIXTURE)); + expect(backend.updateStation).toHaveBeenCalledWith("tok", "st_1", { headset_address: "192.168.1.10" }); + }); + + it("confirms an address already entered, and has nothing left to mark", async () => { + renderCard(TWO_NETWORKS, { station: { ...BENCH, headset_address: "10.0.0.42" } }); + expect(await screen.findByText("✓ Entered in the headset for Bench A.")).toBeTruthy(); + expect(mark().disabled).toBe(true); + // Choosing the other network makes it markable again: the headset would need that address instead. + fireEvent.change(screen.getByLabelText("Network to use"), { target: { value: "192.168.1.10" } }); + expect(mark().disabled).toBe(false); + expect(screen.queryByText(/Entered in the headset for/)).toBeNull(); + }); + + it("warns when the saved address is no longer one of the host's", async () => { + renderCard({ ...HEADSET_ADDRESS_FIXTURE, saved: "10.0.0.7", changed: true }, { station: { ...BENCH, headset_address: "10.0.0.7" } }); + expect(await screen.findByText(/The address saved for Bench A \(10\.0\.0\.7\) is no longer one of this host's/)).toBeTruthy(); + expect(mark().disabled).toBe(false); + }); + + it("names a capture host on another machine as such", async () => { + renderCard({ candidates: [{ address: "192.168.1.50", interface: null, kind: "capture_server" }], saved: null, changed: false }); + expect(await screen.findByText("192.168.1.50 (capture host)")).toBeTruthy(); + }); + + it("says so when the host has no address, and looks again on request", async () => { + const { backend } = renderCard({ candidates: [], saved: null, changed: false }); + expect(await screen.findByText(/No network address was found for this host/)).toBeTruthy(); + expect(mark().disabled).toBe(true); + fireEvent.click(screen.getByRole("button", { name: "Detect again" })); + await waitFor(() => expect(backend.loadHeadsetAddress).toHaveBeenCalledTimes(2)); + }); + + it("cannot remember an address with no station in use", async () => { + renderCard(HEADSET_ADDRESS_FIXTURE, { station: null }); + expect(await screen.findByText("Put a station in use to remember which address its headset was given.")).toBeTruthy(); + expect(mark().disabled).toBe(true); + }); + + it("reads the address again when the station's saved one changes, keeping the operator's choice", async () => { + const { backend, rerender } = renderCard(TWO_NETWORKS); + await address(); + fireEvent.change(screen.getByLabelText("Network to use"), { target: { value: "192.168.1.10" } }); + rerender({ ...BENCH, headset_address: "192.168.1.10" }); + await waitFor(() => expect(backend.loadHeadsetAddress).toHaveBeenCalledTimes(2)); + expect((await address()).textContent).toBe("192.168.1.10"); + expect(await screen.findByText("✓ Entered in the headset for Bench A.")).toBeTruthy(); + }); + + it("asks for the control token instead of loading without it", () => { + const { backend } = renderCard(HEADSET_ADDRESS_FIXTURE, { controlToken: null }); + expect(screen.getByText("Enter the control token in the recording panel to see this host's addresses.")).toBeTruthy(); + expect(backend.loadHeadsetAddress).not.toHaveBeenCalled(); + }); + + it("shows why the addresses could not be read, and why a save was refused", async () => { + renderCard(new SettingsHttpError("control token rejected")); + expect(await screen.findByText("Addresses unavailable: control token rejected")).toBeTruthy(); + cleanup(); + const { backend } = renderCard(); + backend.updateStation = vi.fn(async () => { + throw new SettingsHttpError("finish or discard the current take before changing the station in use"); + }); + await address(); + fireEvent.click(mark()); + expect(await screen.findByText("Not saved: finish or discard the current take before changing the station in use")).toBeTruthy(); + }); +}); diff --git a/examples/egocap/frontend/src/HeadsetAddressCard.tsx b/examples/egocap/frontend/src/HeadsetAddressCard.tsx new file mode 100644 index 0000000000..19aedaa948 --- /dev/null +++ b/examples/egocap/frontend/src/HeadsetAddressCard.tsx @@ -0,0 +1,138 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** + * The Headset address card of the Settings dialog: the capture host address the operator enters in the headset. + * + * The backend offers this host's addresses, wireless first. Once the operator has entered one in the headset + * they mark it, and it is saved with the station in use; when the host's address later changes, the card says + * the headset needs the new one instead of leaving a silent connection failure. + */ +import { useCallback, useEffect, useState } from "react"; +import { Card, errorMessage, useAction } from "./settingsParts"; +import type { HeadsetAddress, HostAddress, StationChange, StationListing, StationRecord } from "./stationsApi"; + +/** The calls the card makes; the dialog passes the real ones and tests pass fakes. */ +export interface HeadsetAddressBackend { + loadHeadsetAddress: (controlToken: string, signal: AbortSignal) => Promise; + updateStation: (controlToken: string, id: string, changes: StationChange) => Promise; +} + +/** What kind of link an address is on, in the operator's words. */ +const KIND_LABELS: Record = { + wireless: "wireless", + wired: "wired", + other: "other network", + capture_server: "capture host", +}; + +/** An address with where it comes from, for the chooser. */ +function describe(candidate: HostAddress): string { + const kind = KIND_LABELS[candidate.kind] ?? candidate.kind; + return candidate.interface === null ? `${candidate.address} (${kind})` : `${candidate.address} (${candidate.interface}, ${kind})`; +} + +type Loaded = { kind: "loading" } | { kind: "error"; message: string } | { kind: "loaded"; value: HeadsetAddress }; + +export interface HeadsetAddressCardProps { + controlToken: string | null; + /** The station in use, which remembers the address; null when no station is in use. */ + station: StationRecord | null; + backend: HeadsetAddressBackend; + onListing: (listing: StationListing) => void; +} + +/** Show the address to enter in the headset and remember, per station, the one that was entered. */ +export function HeadsetAddressCard({ controlToken, station, backend, onListing }: HeadsetAddressCardProps) { + const [state, setState] = useState({ kind: "loading" }); + const [chosen, setChosen] = useState(null); + // Bumped by "Detect again": the host's addresses change when a network is joined or a cable is plugged in. + const [generation, setGeneration] = useState(0); + const [{ busy, failure }, run] = useAction(); + const { loadHeadsetAddress } = backend; + const saved = station?.headset_address ?? null; + + useEffect(() => { + if (controlToken === null) return; + const controller = new AbortController(); + // A refresh keeps showing the last answer instead of flashing back to "Loading". + setState((current) => (current.kind === "loaded" ? current : { kind: "loading" })); + loadHeadsetAddress(controlToken, controller.signal).then( + (value) => { + setState({ kind: "loaded", value }); + // Keep the operator's choice while it is still offered; otherwise fall back to the best candidate. + setChosen((current) => (value.candidates.some((c) => c.address === current) ? current : (value.candidates[0]?.address ?? null))); + }, + (error: unknown) => { + if (!controller.signal.aborted) setState({ kind: "error", message: errorMessage(error) }); + }, + ); + return () => controller.abort(); + // The saved address is part of the answer, so a change to it reloads. + }, [controlToken, loadHeadsetAddress, generation, saved]); + + const detectAgain = useCallback(() => setGeneration((n) => n + 1), []); + const lead = "The headset connects to the capture host over the network. Enter this address in the headset's tracking app, then reconnect it."; + + if (controlToken === null) { + return ( + +

Enter the control token in the recording panel to see this host's addresses.

+
+ ); + } + if (state.kind !== "loaded") { + return ( + + {state.kind === "loading" ?

Loading…

:

Addresses unavailable: {state.message}

} +
+ ); + } + const { candidates, changed } = state.value; + const stationName = station?.name ?? null; + return ( + + {candidates.length === 0 ? ( +

No network address was found for this host. Check its network connection, then detect again.

+ ) : ( + <> +

+ {chosen} +

+ {candidates.length > 1 && ( + + )} + {candidates.length === 1 &&

{describe(candidates[0])}

} + + )} + {changed && saved !== null && ( +

+ The address saved for {stationName} ({saved}) is no longer one of this host's. Enter the address above in the headset, then mark it as entered. +

+ )} + {!changed && saved !== null && chosen === saved &&

✓ Entered in the headset for {stationName}.

} + {stationName === null &&

Put a station in use to remember which address its headset was given.

} +
+ + + {failure !== null && Not saved: {failure}} +
+
+ ); +} diff --git a/examples/egocap/frontend/src/OperatorBar.test.tsx b/examples/egocap/frontend/src/OperatorBar.test.tsx index eee5876db8..fc0344b28a 100644 --- a/examples/egocap/frontend/src/OperatorBar.test.tsx +++ b/examples/egocap/frontend/src/OperatorBar.test.tsx @@ -25,6 +25,7 @@ function snap(overrides: Partial = {}): RecordingSnapshot { savedCount: 0, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 1, ...overrides, }; @@ -55,6 +56,12 @@ describe("deriveRecIndicator", () => { expect(deriveRecIndicator(snap({ readyToRecord: false, taskText: "" }), true).hint).toContain("Set a task"); }); + it("says why a take would be refused, ahead of a missing task", () => { + const blocked = { readyToRecord: false, notReadyReason: "select a station before recording" }; + expect(deriveRecIndicator(snap(blocked), true)).toMatchObject({ label: "NOT READY", hint: "Select a station before recording" }); + expect(deriveRecIndicator(snap({ ...blocked, taskText: "" }), true).hint).toBe("Select a station before recording"); + }); + it("asks for whatever setup is missing instead of claiming READY", () => { const none = deriveRecIndicator(snap(), true, { operatorSet: false, controlTokenSet: false }); expect(none).toMatchObject({ label: "SET UP", variant: "warning" }); diff --git a/examples/egocap/frontend/src/OperatorBar.tsx b/examples/egocap/frontend/src/OperatorBar.tsx index f7fc345aaf..2d10fff845 100644 --- a/examples/egocap/frontend/src/OperatorBar.tsx +++ b/examples/egocap/frontend/src/OperatorBar.tsx @@ -16,6 +16,7 @@ import { chipsNeedingAttention, deriveHealthChips, type HealthChip } from "./dev import { formatElapsed } from "./RecordingPanel"; import type { RecordingSnapshot } from "./recordingTypes"; import type { RecordingPhase } from "./recordingUiReducer"; +import { sentence } from "./sentence"; /** How the recording indicator is drawn. */ export type RecVariant = "recording" | "busy" | "ready" | "idle" | "warning" | "stale"; @@ -74,7 +75,9 @@ export function deriveRecIndicator( return { label: "RECOVERY", variant: "warning", hint: "An interrupted take is blocking Record -- start a new batch" }; case "IDLE": { if (!snapshot.readyToRecord) { - return { label: "NOT READY", variant: "idle", hint: snapshot.taskText ? null : "Set a task to enable Record" }; + // The backend's reason first: station setup and capture come before the task in the operator's order. + const reason = snapshot.notReadyReason !== null ? sentence(snapshot.notReadyReason) : null; + return { label: "NOT READY", variant: "idle", hint: reason ?? (snapshot.taskText ? null : "Set a task to enable Record") }; } // The backend would admit a take, but this browser may not be allowed to start one yet. if (!setup.operatorSet || !setup.controlTokenSet) { diff --git a/examples/egocap/frontend/src/RecordingPanel.taskCatalog.test.tsx b/examples/egocap/frontend/src/RecordingPanel.taskCatalog.test.tsx index 5e6063a162..c1374e4ffe 100644 --- a/examples/egocap/frontend/src/RecordingPanel.taskCatalog.test.tsx +++ b/examples/egocap/frontend/src/RecordingPanel.taskCatalog.test.tsx @@ -36,6 +36,7 @@ function snapshot(overrides: Partial = {}): RecordingSnapshot savedCount: 0, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 0, ...overrides, }; diff --git a/examples/egocap/frontend/src/RecordingPanel.test.tsx b/examples/egocap/frontend/src/RecordingPanel.test.tsx index bc5a2eb903..6dc880ad50 100644 --- a/examples/egocap/frontend/src/RecordingPanel.test.tsx +++ b/examples/egocap/frontend/src/RecordingPanel.test.tsx @@ -46,6 +46,7 @@ function activeSnapshot(overrides: Partial = {}): RecordingSn savedCount: 0, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 0, ...overrides, }; @@ -139,6 +140,19 @@ describe("RecordingPanel", () => { expect(record.title).toBe("Required sources not ready"); }); + it("Record gives the backend's own reason when it has one", () => { + const noop = vi.fn().mockResolvedValue({ outcome: "ok", reason: null }); + render( + , + ); + const record = screen.getByRole("button", { name: /record \(s\)/i }) as HTMLButtonElement; + expect(record.disabled).toBe(true); + expect(record.title).toBe("Station 'Bench A': no camera is assigned to the ego (head) role"); + }); + it("after an interrupted take, Record points to New batch as the way to clear it", () => { const noop = vi.fn().mockResolvedValue({ outcome: "ok", reason: null }); render( diff --git a/examples/egocap/frontend/src/RecordingPanel.voice.test.tsx b/examples/egocap/frontend/src/RecordingPanel.voice.test.tsx index 0590e45e86..25f8d719a4 100644 --- a/examples/egocap/frontend/src/RecordingPanel.voice.test.tsx +++ b/examples/egocap/frontend/src/RecordingPanel.voice.test.tsx @@ -109,6 +109,7 @@ function activeSnapshot(overrides: Partial = {}): RecordingSn savedCount: 0, lastResult: null, readyToRecord: true, + notReadyReason: null, revision: 0, ...overrides, }; diff --git a/examples/egocap/frontend/src/SettingsPanel.test.tsx b/examples/egocap/frontend/src/SettingsPanel.test.tsx index 75b0256171..4b48d7b220 100644 --- a/examples/egocap/frontend/src/SettingsPanel.test.tsx +++ b/examples/egocap/frontend/src/SettingsPanel.test.tsx @@ -8,14 +8,22 @@ import { afterEach, describe, expect, it, vi } from "vitest"; import { cleanup, fireEvent, render, screen, within, waitFor } from "@testing-library/react"; import { SettingsPanel, type SettingsBackend, type StationSetup } from "./SettingsPanel"; import { SettingsHttpError, type OperatorSettings, type TaskFileListing } from "./settingsApi"; -import { KITCHEN_FIXTURE, OPERATOR_SETTINGS_FIXTURE, SETTINGS_FIXTURE, TASK_FILES_FIXTURE, TOOLS_FIXTURE } from "./settingsTestDoubles"; +import { KITCHEN_FIXTURE, OPERATOR_SETTINGS_FIXTURE, SETTINGS_FIXTURE, STATIONS_FIXTURE, TASK_FILES_FIXTURE, TOOLS_FIXTURE, fakeStationRegistry } from "./settingsTestDoubles"; afterEach(cleanup); const MID_TRAIN = { name: "Mid.csv", format: "mid_train_csv", tasks: [{ name: "fold_towel", instruction: "Fold a towel" }] }; /** A fake backend over in-memory state, so saves show up on the next load like the real one. */ -function fakeBackend(initial: Partial = {}): SettingsBackend & { operator: OperatorSettings; listing: TaskFileListing } { +function fakeBackend( + initial: Partial = {}, +): SettingsBackend & { operator: OperatorSettings; listing: TaskFileListing; registry: ReturnType } { + const registry = fakeStationRegistry(initial.stations); + /** As the backend does: the station in use supplies the camera type and roles every reader sees. */ + const effective = (): OperatorSettings => { + const inUse = registry.inUse(); + return inUse === null ? state.operator : { ...state.operator, camera_type: inUse.camera_type, camera_roles: inUse.camera_roles }; + }; const state = { operator: initial.operator ?? OPERATOR_SETTINGS_FIXTURE, listing: initial.taskFiles ?? TASK_FILES_FIXTURE, @@ -28,12 +36,26 @@ function fakeBackend(initial: Partial = {}): SettingsBackend & { o get listing() { return state.listing; }, + registry, + addStation: vi.fn(registry.addStation), + updateStation: vi.fn(registry.updateStation), + deleteStation: vi.fn(registry.deleteStation), + selectStation: vi.fn(registry.selectStation), + loadHeadsetAddress: vi.fn(registry.loadHeadsetAddress), loadDeployment: vi.fn(async () => SETTINGS_FIXTURE), - loadStationSetup: vi.fn(async () => ({ operator: state.operator, tools: state.tools, taskFiles: state.listing })), + loadStationSetup: vi.fn(async () => ({ operator: effective(), tools: state.tools, taskFiles: state.listing, stations: registry.listing })), loadTaskFile: vi.fn(async (name: string) => (name === "Mid.csv" ? MID_TRAIN : KITCHEN_FIXTURE)), - saveOperator: vi.fn(async (_token: string, changes) => { - state.operator = { ...state.operator, ...changes }; - return state.operator; + saveOperator: vi.fn(async (token: string, changes) => { + const inUse = registry.inUse(); + const { camera_type, camera_roles, ...rest } = changes; + // A station in use keeps its own camera fields; everything else is station-independent. + if (inUse !== null) { + await registry.updateStation(token, inUse.id, { ...(camera_type !== undefined && { camera_type }), ...(camera_roles !== undefined && { camera_roles }) }); + state.operator = { ...state.operator, ...rest }; + } else { + state.operator = { ...state.operator, ...changes }; + } + return effective(); }), importTaskFile: vi.fn(async (_token: string, source) => { const name = source.name; @@ -158,6 +180,57 @@ describe("Station tab", () => { }); }); +describe("Stations in the Station tab", () => { + it("adds the first station, puts it in use, and then edits that station's cameras", async () => { + const backend = fakeBackend({ operator: { ...OPERATOR_SETTINGS_FIXTURE, camera_type: "oak_d" } }); + renderPanel({ cameraSources: ["Ego", "Wrist A"] }, backend); + const stations = await screen.findByRole("region", { name: "Stations" }); + expect(screen.getByLabelText("Station readiness").textContent).not.toContain("Station"); + fireEvent.change(within(stations).getByLabelText("New station name"), { target: { value: "Bench A" } }); + fireEvent.click(within(stations).getByRole("button", { name: "Add station" })); + await waitFor(() => expect(screen.getByLabelText("Station readiness").textContent).toContain("✓ Station: Bench A")); + // The camera type saved before any station existed became the station's own. + expect(backend.registry.inUse()).toMatchObject({ name: "Bench A", camera_type: "oak_d" }); + // The setup is read again with the credential, so the cards below show the station in use. + expect(backend.loadStationSetup).toHaveBeenLastCalledWith(expect.any(AbortSignal), "tok"); + const roles = await screen.findByRole("region", { name: "Camera roles" }); + fireEvent.change(within(roles).getByLabelText("Ego (head)"), { target: { value: "Ego" } }); + fireEvent.click(within(roles).getByRole("button", { name: "Save camera roles" })); + await waitFor(() => expect(backend.registry.inUse()?.camera_roles.ego).toBe("Ego")); + expect(backend.operator.camera_roles.ego).toBeNull(); // the station-independent value is untouched + }); + + it("says when stations exist but none is in use", async () => { + const stations = { ...STATIONS_FIXTURE, stations: [{ id: "st_1", name: "Bench A", camera_type: null, camera_roles: { ego: null, wrist_left: null, wrist_right: null }, problems: [], headset_address: null }] }; + renderPanel({}, fakeBackend({ stations })); + await screen.findByRole("region", { name: "Stations" }); + expect(screen.getByLabelText("Station readiness").textContent).toContain("○ No station in use"); + }); + + it("remembers the headset address with the station in use", async () => { + const station = { id: "st_1", name: "Bench A", camera_type: null, camera_roles: { ego: null, wrist_left: null, wrist_right: null }, problems: [], headset_address: null }; + const backend = fakeBackend({ stations: { ...STATIONS_FIXTURE, stations: [station], selected: "st_1", label: "Bench A" } }); + renderPanel({}, backend); + const headset = await screen.findByRole("region", { name: "Headset address" }); + expect((await within(headset).findByLabelText("Address to enter in the headset")).textContent).toBe("10.0.0.42"); + fireEvent.click(within(headset).getByRole("button", { name: "Mark as entered in the headset" })); + expect(await within(headset).findByText("✓ Entered in the headset for Bench A.")).toBeTruthy(); + expect(backend.registry.inUse()?.headset_address).toBe("10.0.0.42"); + }); + + it("keeps the changed registry on screen when reading the setup again fails", async () => { + const backend = fakeBackend(); + renderPanel({}, backend); + const stations = await screen.findByRole("region", { name: "Stations" }); + backend.loadStationSetup = vi.fn(async () => { + throw new SettingsHttpError("stations are not available yet"); + }); + fireEvent.change(within(stations).getByLabelText("New station name"), { target: { value: "Bench A" } }); + fireEvent.click(within(stations).getByRole("button", { name: "Add station" })); + expect(await within(stations).findByLabelText("Use Bench A")).toBeTruthy(); + }); +}); + describe("Tasks tab", () => { it("lists the catalogs, lets the operator choose the one the task editor offers, and shows its preselect card", async () => { const { backend } = renderPanel(); diff --git a/examples/egocap/frontend/src/SettingsPanel.tsx b/examples/egocap/frontend/src/SettingsPanel.tsx index b034a5a515..09b7be1885 100644 --- a/examples/egocap/frontend/src/SettingsPanel.tsx +++ b/examples/egocap/frontend/src/SettingsPanel.tsx @@ -5,13 +5,28 @@ /** * The Settings dialog: a tabbed modal over the page. * - * Tabs, in the order an operator sets up a station: Station (camera type and roles), Tasks (the catalogs the task picker + * Tabs, in the order an operator sets up a station: Station (the stations and the one in use, its camera type and + * roles, and the headset address), Tasks (the catalogs the task picker * offers, imports, and the preselected task), Tools (calibration and rectification), Display (this browser's * choices and the keyboard shortcuts), Advanced (what the deployment is running with, read-only). Station and Tasks * are saved by the backend for every browser and need the run's control token to change, as recording * commands do; Tools lists unavailable stubs; Display is this browser's only; Advanced values are set where the backend is launched. */ import { useCallback, useEffect, useRef, useState, type ReactNode } from "react"; +import { Card, TokenHint, errorMessage, useAction } from "./settingsParts"; +import { HeadsetAddressCard } from "./HeadsetAddressCard"; +import { StationsCard } from "./StationsCard"; +import { + addStation, + deleteStation, + fetchHeadsetAddress, + fetchStations, + selectStation, + updateStation, + type HeadsetAddress, + type StationChange, + type StationListing, +} from "./stationsApi"; import { CAMERA_TYPE_LABELS, ROLE_LABELS, @@ -33,31 +48,49 @@ import { } from "./settingsApi"; export interface StationSetup { + /** The camera setup in effect: the station in use supplies it, else the values saved before stations existed. */ operator: OperatorSettings; tools: ToolInfo[]; taskFiles: TaskFileListing; + stations: StationListing; } /** The backend calls the dialog makes; tests inject fakes, the page uses the real ones. */ export interface SettingsBackend { loadDeployment: (signal: AbortSignal, controlToken?: string | null) => Promise; - loadStationSetup: (signal: AbortSignal) => Promise; + /** With the control token the stations carry their headset addresses. */ + loadStationSetup: (signal: AbortSignal, controlToken?: string | null) => Promise; loadTaskFile: (name: string, signal: AbortSignal) => Promise; saveOperator: (controlToken: string, changes: OperatorSettingsChange) => Promise; importTaskFile: (controlToken: string, source: TaskFileSource) => Promise; removeTaskFile: (controlToken: string, name: string) => Promise; + addStation: (controlToken: string, fields: StationChange) => Promise; + updateStation: (controlToken: string, id: string, changes: StationChange) => Promise; + deleteStation: (controlToken: string, id: string) => Promise; + selectStation: (controlToken: string, id: string | null) => Promise; + loadHeadsetAddress: (controlToken: string, signal: AbortSignal) => Promise; } export const REAL_SETTINGS_BACKEND: SettingsBackend = { loadDeployment: fetchSettings, - loadStationSetup: async (signal) => { - const [operator, tools, taskFiles] = await Promise.all([fetchOperatorSettings(signal), fetchTools(signal), fetchTaskFiles(signal)]); - return { operator, tools, taskFiles }; + loadStationSetup: async (signal, controlToken) => { + const [operator, tools, taskFiles, stations] = await Promise.all([ + fetchOperatorSettings(signal), + fetchTools(signal), + fetchTaskFiles(signal), + fetchStations(signal, controlToken), + ]); + return { operator, tools, taskFiles, stations }; }, loadTaskFile: fetchTaskFile, saveOperator: saveOperatorSettings, importTaskFile, removeTaskFile, + addStation, + updateStation, + deleteStation, + selectStation, + loadHeadsetAddress: fetchHeadsetAddress, }; export type SettingsTab = "station" | "tasks" | "tools" | "display" | "advanced"; @@ -87,11 +120,6 @@ export interface SettingsPanelProps { type Loaded = { kind: "loading" } | { kind: "error"; message: string } | { kind: "loaded"; value: T }; -/** Turn unknown request failures into a concise operator-facing explanation. */ -function errorMessage(error: unknown): string { - return error instanceof Error ? error.message : String(error); -} - /** Loads `load` each time the dialog opens, so a backend restart shows its new values; abandons a load the * dialog closed on. */ function useLoaded(open: boolean, load: (signal: AbortSignal) => Promise): [Loaded, (update: (value: T) => T) => void] { @@ -138,42 +166,6 @@ function Row({ label, value, mono = false }: { label: string; value: string; mon ); } -/** One titled block of a tab. */ -function Card({ title, lead, children }: { title: string; lead?: string; children: ReactNode }) { - return ( -
-

{title}

- {lead !== undefined &&

{lead}

} - {children} -
- ); -} - -/** Explain why station changes require the recording control token. */ -function TokenHint({ controlToken }: { controlToken: string | null }) { - if (controlToken !== null) return null; - return

Enter the control token in the recording panel to change these.

; -} - -/** The pending/failed state of one save-type action, shown next to its button. */ -function useAction(): [{ busy: boolean; failure: string | null }, (work: () => Promise) => void] { - const [busy, setBusy] = useState(false); - const [failure, setFailure] = useState(null); - /** Keep request failures visible and prevent duplicate submissions. */ - const run = (work: () => Promise) => { - setBusy(true); - setFailure(null); - work().then( - () => setBusy(false), - (error: unknown) => { - setBusy(false); - setFailure(errorMessage(error)); - }, - ); - }; - return [{ busy, failure }, run]; -} - // --- Station --------------------------------------------------------------------------------------------------- /** Offer persistent camera setup and explain which roles are currently available. */ @@ -183,18 +175,29 @@ function StationTab({ backend, cameraSources, onOperator, + onStations, }: { setup: Loaded; controlToken: string | null; backend: SettingsBackend; cameraSources: string[]; onOperator: (operator: OperatorSettings) => void; + onStations: (stations: StationListing) => void; }) { if (setup.kind !== "loaded") return ; - const { operator } = setup.value; + const { operator, stations } = setup.value; + const inUse = stations.stations.find((station) => station.id === stations.selected) ?? null; return ( <> - + + @@ -202,15 +205,19 @@ function StationTab({ + ); } /** The station's readiness at a glance: what is set, what is still to do. */ -function ReadyLine({ operator, cameraSources }: { operator: OperatorSettings; cameraSources: string[] }) { +function ReadyLine({ operator, stations, cameraSources }: { operator: OperatorSettings; stations: StationListing; cameraSources: string[] }) { const assigned = operator.roles.filter((role) => operator.camera_roles[role] !== null); const offered = assigned.filter((role) => cameraSources.includes(operator.camera_roles[role] ?? "")); + const inUse = stations.stations.find((station) => station.id === stations.selected); const items: Array<[boolean, string]> = [ + // Without any stations there is nothing to choose, so the line says nothing about them. + ...(stations.stations.length === 0 ? [] : [[inUse !== undefined, inUse === undefined ? "No station in use" : `Station: ${inUse.name}`] as [boolean, string]]), [operator.camera_type !== null, operator.camera_type === null ? "Camera type not set" : `Camera type: ${CAMERA_TYPE_LABELS[operator.camera_type]?.split(" — ")[0] ?? operator.camera_type}`], [assigned.length === operator.roles.length, `${assigned.length}/${operator.roles.length} roles assigned`], [assigned.length > 0 && offered.length === assigned.length, cameraSources.length === 0 ? "No cameras offered by the session yet" : `${offered.length}/${assigned.length} assigned cameras in this session`], @@ -761,7 +768,9 @@ export function SettingsPanel({ /** Reload restricted details when the active credential changes. */ const loadDeployment = useCallback((signal: AbortSignal) => backend.loadDeployment(signal, controlToken), [backend, controlToken]); const [deployment] = useLoaded(open && controlToken !== null, loadDeployment); - const [setup, updateSetup] = useLoaded(open, backend.loadStationSetup); + /** Reload the station setup when the credential changes: with it the stations carry their headset addresses. */ + const loadSetup = useCallback((signal: AbortSignal) => backend.loadStationSetup(signal, controlToken), [backend, controlToken]); + const [setup, updateSetup] = useLoaded(open, loadSetup); // Escape closes, as for any dialog. useEffect(() => { @@ -778,6 +787,15 @@ export function SettingsPanel({ /** Keep all tabs in sync with the persisted station setup. */ const setOperator = (operator: OperatorSettings) => updateSetup((value) => ({ ...value, operator })); + /** Show a changed registry at once, then read the setup again: the station in use supplies the camera type + * and roles, so a change of it changes what the cards below edit. */ + const setStations = (stations: StationListing) => { + updateSetup((value) => ({ ...value, stations })); + loadSetup(new AbortController().signal).then( + (fresh) => updateSetup(() => fresh), + () => undefined, // the registry change itself succeeded; the next open reloads everything + ); + }; return ( <> @@ -806,7 +824,7 @@ export function SettingsPanel({
{setup.kind === "loaded" && setup.value.operator.warning &&

{setup.value.operator.warning}

} - {tab === "station" && } + {tab === "station" && } {tab === "tasks" && } {tab === "tools" && } {tab === "display" && } diff --git a/examples/egocap/frontend/src/StationActivityToggle.test.tsx b/examples/egocap/frontend/src/StationActivityToggle.test.tsx new file mode 100644 index 0000000000..3deb89e7c7 --- /dev/null +++ b/examples/egocap/frontend/src/StationActivityToggle.test.tsx @@ -0,0 +1,154 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** The station activity toggle: what it shows through a day, how it counts between loads, and its refusals. */ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { act, cleanup, fireEvent, render, screen } from "@testing-library/react"; +import { SettingsHttpError } from "./settingsApi"; +import { StationActivityToggle, formatActivity, liveTotals, type ActivityBackend } from "./StationActivityToggle"; +import type { StationActivity } from "./stationsApi"; + +beforeEach(() => vi.useFakeTimers()); +afterEach(() => { + cleanup(); + vi.useRealTimers(); +}); + +const NOT_STARTED: StationActivity = { + station: "Bench A", + date: "2026-03-09", + state: "inactive", + since: null, + active_seconds: 0, + inactive_seconds: 0, + blocker_count: 0, + notes: "", + as_of: 1_000, +}; +const ACTIVE: StationActivity = { ...NOT_STARTED, state: "active", since: 1_000, active_seconds: 3_720, inactive_seconds: 300, blocker_count: 1 }; +const BLOCKED: StationActivity = { ...ACTIVE, state: "inactive", since: 4_720, inactive_seconds: 45, blocker_count: 2 }; + +/** A backend whose answers a test can swap between calls. */ +function fakeBackend(first: StationActivity | Error) { + const state = { answer: first as StationActivity | Error, next: ACTIVE as StationActivity | Error }; + const backend: ActivityBackend = { + load: vi.fn(async () => { + if (state.answer instanceof Error) throw state.answer; + return state.answer; + }), + change: vi.fn(async () => { + if (state.next instanceof Error) throw state.next; + return state.next; + }), + }; + return { backend, state }; +} + +/** Let the pending load or change settle, then advance the fake clock. */ +async function settle(ms = 0) { + await act(async () => { + await vi.advanceTimersByTimeAsync(ms); + }); +} + +async function renderToggle(first: StationActivity | Error, props: { controlToken?: string | null; stationLabel?: string | null } = {}) { + const fake = fakeBackend(first); + const view = (label: string | null) => ( + + ); + const utils = render(view(props.stationLabel === undefined ? "Bench A" : props.stationLabel)); + await settle(); + return { ...fake, rerender: (label: string | null) => utils.rerender(view(label)) }; +} + +const toggle = () => screen.getByRole("button") as HTMLButtonElement; + +describe("formatActivity and liveTotals", () => { + it("shows minutes and seconds, then hours and minutes", () => { + expect(formatActivity(0)).toBe("0m 00s"); + expect(formatActivity(125.9)).toBe("2m 05s"); + expect(formatActivity(3_720)).toBe("1h 02m"); + expect(formatActivity(-5)).toBe("0m 00s"); + }); + + it("counts the open segment onto the side that is open, and nothing before the day is started", () => { + expect(liveTotals(ACTIVE, 60)).toEqual({ active: 3_780, inactive: 300 }); + expect(liveTotals(BLOCKED, 60)).toEqual({ active: 3_720, inactive: 105 }); + expect(liveTotals(NOT_STARTED, 600)).toEqual({ active: 0, inactive: 0 }); + expect(liveTotals(ACTIVE, -3)).toEqual({ active: 3_720, inactive: 300 }); + }); +}); + +describe("StationActivityToggle", () => { + it("starts the day on the first press", async () => { + const { backend } = await renderToggle(NOT_STARTED); + expect(toggle().textContent).toBe("Not started"); + expect(toggle().getAttribute("aria-pressed")).toBe("false"); + expect(toggle().title).toBe("Mark the station active"); + fireEvent.click(toggle()); + await settle(); + expect(backend.change).toHaveBeenCalledWith("tok", { state: "active" }); + expect(toggle().textContent).toBe("Active · 1h 02m"); + expect(toggle().getAttribute("aria-pressed")).toBe("true"); + expect(screen.getByText("blocked 5m 00s · 1 blocker")).toBeTruthy(); + }); + + it("keeps the open segment counting between loads", async () => { + await renderToggle({ ...ACTIVE, active_seconds: 59 }); + expect(toggle().textContent).toBe("Active · 0m 59s"); + await settle(2_000); + expect(toggle().textContent).toBe("Active · 1m 01s"); + }); + + it("marks the station blocked and shows both totals", async () => { + const { backend, state } = await renderToggle(ACTIVE); + state.next = BLOCKED; + fireEvent.click(toggle()); + await settle(); + expect(backend.change).toHaveBeenCalledWith("tok", { state: "inactive" }); + expect(toggle().textContent).toBe("Blocked · 0m 45s"); + expect(toggle().title).toBe("Mark the station active"); + expect(screen.getByText("active 1h 02m · 2 blockers")).toBeTruthy(); + }); + + it("reads the totals again each minute and when the station in use changes", async () => { + const { backend, state, rerender } = await renderToggle(ACTIVE); + expect(backend.load).toHaveBeenCalledTimes(1); + state.answer = BLOCKED; + await settle(60_000); + expect(backend.load).toHaveBeenCalledTimes(2); + expect(toggle().textContent).toContain("Blocked"); + state.answer = NOT_STARTED; + rerender("Cart B"); + await settle(); + expect(backend.load).toHaveBeenCalledTimes(3); + expect(toggle().textContent).toBe("Not started"); + }); + + it("shows the state without the control token but cannot change it", async () => { + const { backend } = await renderToggle(ACTIVE, { controlToken: null }); + expect(toggle().disabled).toBe(true); + expect(toggle().title).toBe("Enter the control token in the recording panel to change this"); + fireEvent.click(toggle()); + expect(backend.change).not.toHaveBeenCalled(); + }); + + it("shows why a change was refused and keeps the last known state", async () => { + const { state } = await renderToggle(ACTIVE); + state.next = new SettingsHttpError("could not save station activity"); + fireEvent.click(toggle()); + await settle(); + expect(screen.getByText("Not saved: could not save station activity")).toBeTruthy(); + expect(toggle().textContent).toContain("Active"); + expect(toggle().disabled).toBe(false); + }); + + it("renders nothing while the activity cannot be read, and recovers on the next refresh", async () => { + const { state } = await renderToggle(new Error("offline")); + expect(screen.queryByRole("button")).toBeNull(); + state.answer = ACTIVE; + await settle(60_000); + expect(toggle().textContent).toContain("Active"); + }); +}); diff --git a/examples/egocap/frontend/src/StationActivityToggle.tsx b/examples/egocap/frontend/src/StationActivityToggle.tsx new file mode 100644 index 0000000000..f0ef9479bc --- /dev/null +++ b/examples/egocap/frontend/src/StationActivityToggle.tsx @@ -0,0 +1,138 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** + * The station's active/inactive toggle, beside the station name in the status strip. + * + * The operator marks the station active while it is collecting and inactive while it is blocked; the backend + * keeps the day's intervals and writes the daily activity log. Nothing is counted until the first press of the + * day. The open segment keeps counting here between loads, from the totals the backend computed and the time + * since this browser received them, so no clock comparison between the two machines is involved. + */ +import { useEffect, useReducer, useState } from "react"; +import { changeStationActivity, fetchStationActivity, type ActivityState, type StationActivity } from "./stationsApi"; + +/** The calls the toggle makes; the page uses the real ones and tests pass fakes. */ +export interface ActivityBackend { + load: (signal: AbortSignal) => Promise; + change: (controlToken: string, change: { state: ActivityState }) => Promise; +} + +export const REAL_ACTIVITY_BACKEND: ActivityBackend = { load: fetchStationActivity, change: changeStationActivity }; + +/** How often the totals are read again, so a change made in another tab or a new day shows up. */ +const REFRESH_MS = 60_000; + +/** A duration as the operator reads it: hours and minutes once there are hours, else minutes and seconds. */ +export function formatActivity(seconds: number): string { + const whole = Math.max(0, Math.floor(seconds)); + const hours = Math.floor(whole / 3600); + const minutes = Math.floor((whole % 3600) / 60); + if (hours > 0) return `${hours}h ${String(minutes).padStart(2, "0")}m`; + return `${minutes}m ${String(whole % 60).padStart(2, "0")}s`; +} + +/** Today's totals with the open segment counted up to now. */ +export function liveTotals(activity: StationActivity, secondsSinceReceipt: number): { active: number; inactive: number } { + // Before the first press of the day no segment is open, so nothing accrues. + const open = activity.since === null ? 0 : Math.max(0, secondsSinceReceipt); + return { + active: activity.active_seconds + (activity.state === "active" ? open : 0), + inactive: activity.inactive_seconds + (activity.state === "inactive" ? open : 0), + }; +} + +export interface StationActivityToggleProps { + /** The station label in effect; activity is kept per station, so a change of it loads that station's day. */ + stationLabel: string | null; + /** The run's control token once entered; without it the toggle shows the state but cannot change it. */ + controlToken: string | null; + backend?: ActivityBackend; +} + +/** Show whether the station is active and for how long today, and flip it on a press. */ +export function StationActivityToggle({ stationLabel, controlToken, backend = REAL_ACTIVITY_BACKEND }: StationActivityToggleProps) { + const [loaded, setLoaded] = useState<{ activity: StationActivity; receivedAt: number } | null>(null); + const [busy, setBusy] = useState(false); + const [failure, setFailure] = useState(null); + const [refresh, bumpRefresh] = useReducer((n: number) => n + 1, 0); + const [, tick] = useReducer((n: number) => n + 1, 0); + /** Keep an answer with the moment it arrived, which is what the live count is measured from. */ + const accept = (activity: StationActivity) => setLoaded({ activity, receivedAt: performance.now() }); + + useEffect(() => { + const controller = new AbortController(); + backend.load(controller.signal).then( + (activity) => { + if (!controller.signal.aborted) accept(activity); + }, + () => { + // The strip stays usable without it; the next refresh tries again. + if (!controller.signal.aborted) setLoaded(null); + }, + ); + return () => controller.abort(); + }, [backend, stationLabel, refresh]); + + useEffect(() => { + const id = setInterval(bumpRefresh, REFRESH_MS); + return () => clearInterval(id); + }, []); + + // Re-render once a second only while a segment is open; an untouched station has nothing to count. + const counting = loaded !== null && loaded.activity.since !== null; + useEffect(() => { + if (!counting) return undefined; + const id = setInterval(tick, 1000); + return () => clearInterval(id); + }, [counting]); + + if (loaded === null) return null; + const { activity, receivedAt } = loaded; + const totals = liveTotals(activity, (performance.now() - receivedAt) / 1000); + const active = activity.state === "active"; + const started = activity.since !== null; + /** Flip the state; the backend's answer replaces what is shown. */ + const toggle = () => { + if (controlToken === null || busy) return; + setBusy(true); + setFailure(null); + backend.change(controlToken, { state: active ? "inactive" : "active" }).then( + (next) => { + accept(next); + setBusy(false); + }, + (error: unknown) => { + setFailure(error instanceof Error ? error.message : String(error)); + setBusy(false); + }, + ); + }; + const label = !started ? "Not started" : active ? `Active · ${formatActivity(totals.active)}` : `Blocked · ${formatActivity(totals.inactive)}`; + const hint = controlToken === null ? "Enter the control token in the recording panel to change this" : active ? "Mark the station blocked" : "Mark the station active"; + return ( + + + {started && ( + + {/* The side not on the button, so both totals are always in view. */} + {active ? `blocked ${formatActivity(totals.inactive)}` : `active ${formatActivity(totals.active)}`} + {activity.blocker_count > 0 && ` · ${activity.blocker_count} blocker${activity.blocker_count === 1 ? "" : "s"}`} + + )} + {failure !== null && Not saved: {failure}} + + ); +} diff --git a/examples/egocap/frontend/src/StationsCard.test.tsx b/examples/egocap/frontend/src/StationsCard.test.tsx new file mode 100644 index 0000000000..c69076daa9 --- /dev/null +++ b/examples/egocap/frontend/src/StationsCard.test.tsx @@ -0,0 +1,212 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** The Stations card: adding, selecting, renaming and deleting stations, and what a take in progress freezes. */ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react"; +import { useState } from "react"; +import { SettingsHttpError } from "./settingsApi"; +import { STATIONS_FIXTURE, fakeStationRegistry } from "./settingsTestDoubles"; +import { StationsCard, type StationsBackend } from "./StationsCard"; +import type { StationListing, StationRecord } from "./stationsApi"; + +afterEach(cleanup); + +const BENCH: StationRecord = { + id: "st_1", + name: "Bench A", + camera_type: "oak_d", + camera_roles: { ego: "cam_head", wrist_left: "cam_left", wrist_right: null }, + problems: [], + headset_address: null, +}; +const CART: StationRecord = { + id: "st_2", + name: "Cart B", + camera_type: null, + camera_roles: { ego: null, wrist_left: null, wrist_right: "cam_grip" }, + problems: ["no camera is assigned to the ego (head) role", "camera 'cam_grip' (right wrist) is not offered by the capture session"], + headset_address: null, +}; +const TWO_STATIONS: StationListing = { ...STATIONS_FIXTURE, stations: [BENCH, CART], selected: "st_1", label: "Bench A" }; + +/** The card over an in-memory registry, re-rendered with each listing the backend answers with. */ +function renderCard(initial: StationListing = STATIONS_FIXTURE, options: { controlToken?: string | null; backend?: Partial } = {}) { + const registry = fakeStationRegistry(initial); + const backend: StationsBackend = { + addStation: vi.fn(registry.addStation), + updateStation: vi.fn(registry.updateStation), + deleteStation: vi.fn(registry.deleteStation), + selectStation: vi.fn(registry.selectStation), + ...options.backend, + }; + const onListing = vi.fn(); + function Harness() { + const [listing, setListing] = useState(initial); + return ( + { + onListing(next); + setListing(next); + }} + /> + ); + } + render(); + return { backend, onListing, registry }; +} + +const rows = () => within(screen.getByRole("list", { name: "Stations" })).getAllByRole("listitem"); +const button = (name: string) => screen.getByRole("button", { name }) as HTMLButtonElement; + +describe("StationsCard with no stations", () => { + it("says which label recordings carry and offers only to add one", () => { + renderCard(); + expect(screen.getByText(/Recordings carry the deployment's label, “Station 01”/)).toBeTruthy(); + expect(screen.queryByRole("list", { name: "Stations" })).toBeNull(); + expect(button("Add station").disabled).toBe(true); // nothing typed yet + }); + + it("gives the first station the camera setup already saved and puts it in use", async () => { + const { backend } = renderCard(); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: " Bench A " } }); + fireEvent.click(button("Add station")); + await waitFor(() => expect(rows()).toHaveLength(2)); // the station and the "No station" choice + expect(backend.addStation).toHaveBeenCalledWith("tok", { + camera_type: "oak_d", + camera_roles: { ego: "Ego", wrist_left: null, wrist_right: null }, + name: "Bench A", + }); + expect(backend.selectStation).toHaveBeenCalledWith("tok", "st_1"); + expect((screen.getByLabelText("Use Bench A") as HTMLInputElement).checked).toBe(true); + expect(within(rows()[0]).getByText("in use")).toBeTruthy(); + expect((screen.getByLabelText("New station name") as HTMLInputElement).value).toBe(""); + }); + + it("leaves the first station unselected when it is added during a take", async () => { + const registry = fakeStationRegistry(); + const addStation = vi.fn(async (token: string, fields: { name?: string }) => ({ + ...(await registry.addStation(token, fields)), + locked_reason: "finish or discard the current take before changing the station in use", + })); + const { backend } = renderCard(STATIONS_FIXTURE, { backend: { addStation } }); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: "Bench A" } }); + fireEvent.keyDown(screen.getByLabelText("New station name"), { key: "Enter" }); + await waitFor(() => expect(rows()).toHaveLength(2)); + expect(backend.selectStation).not.toHaveBeenCalled(); + expect(screen.getByText("Finish or discard the current take before changing the station in use.")).toBeTruthy(); + }); +}); + +describe("StationsCard with stations", () => { + it("lists each station with what fills its roles and why it cannot record", () => { + renderCard(TWO_STATIONS); + const [bench, cart, none] = rows(); + expect(bench.textContent).toContain("Ego (head): cam_head · Left wrist: cam_left · Right wrist: —"); + expect(within(bench).getByText("in use")).toBeTruthy(); + expect(cart.textContent).toContain("Ego (head): — · Left wrist: — · Right wrist: cam_grip"); + expect(cart.textContent).toContain("Cannot record yet: no camera is assigned to the ego (head) role; camera 'cam_grip' (right wrist) is not offered by the capture session."); + expect(within(none).getByText("Recording is held until a station is in use.")).toBeTruthy(); + }); + + it("adds a later station bare and does not change the station in use", async () => { + const { backend } = renderCard(TWO_STATIONS); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: "Desk C" } }); + fireEvent.click(button("Add station")); + await waitFor(() => expect(rows()).toHaveLength(4)); + expect(backend.addStation).toHaveBeenCalledWith("tok", { name: "Desk C" }); + expect(backend.selectStation).not.toHaveBeenCalled(); + }); + + it("puts another station in use, and none", async () => { + const { backend, onListing } = renderCard(TWO_STATIONS); + fireEvent.click(screen.getByLabelText("Use Cart B")); + await waitFor(() => expect((screen.getByLabelText("Use Cart B") as HTMLInputElement).checked).toBe(true)); + expect(backend.selectStation).toHaveBeenLastCalledWith("tok", "st_2"); + fireEvent.click(screen.getByLabelText("Use no station")); + await waitFor(() => expect((screen.getByLabelText("Use no station") as HTMLInputElement).checked).toBe(true)); + expect(backend.selectStation).toHaveBeenLastCalledWith("tok", null); + expect(onListing).toHaveBeenLastCalledWith(expect.objectContaining({ selected: null, label: "Station 01" })); + }); + + it("renames a station with Enter or the button, and Escape or an unchanged name saves nothing", async () => { + const { backend } = renderCard(TWO_STATIONS); + fireEvent.click(within(rows()[1]).getByRole("button", { name: "Rename" })); + const field = screen.getByLabelText("New name for Cart B") as HTMLInputElement; + expect(button("Save name").disabled).toBe(true); // unchanged + fireEvent.keyDown(field, { key: "Enter" }); + expect(backend.updateStation).not.toHaveBeenCalled(); + fireEvent.click(within(rows()[1]).getByRole("button", { name: "Rename" })); + fireEvent.change(screen.getByLabelText("New name for Cart B"), { target: { value: "Cart Z" } }); + const escape = new KeyboardEvent("keydown", { key: "Escape", bubbles: true }); + const stop = vi.spyOn(escape, "stopPropagation"); + fireEvent(screen.getByLabelText("New name for Cart B"), escape); + expect(stop).toHaveBeenCalled(); // the dialog must not close on it + expect(backend.updateStation).not.toHaveBeenCalled(); + fireEvent.click(within(rows()[1]).getByRole("button", { name: "Rename" })); + fireEvent.change(screen.getByLabelText("New name for Cart B"), { target: { value: " Cart Z " } }); + fireEvent.keyDown(screen.getByLabelText("New name for Cart B"), { key: "Enter" }); + await waitFor(() => expect(screen.getByLabelText("Use Cart Z")).toBeTruthy()); + expect(backend.updateStation).toHaveBeenCalledWith("tok", "st_2", { name: "Cart Z" }); + fireEvent.click(within(rows()[0]).getByRole("button", { name: "Rename" })); + fireEvent.change(screen.getByLabelText("New name for Bench A"), { target: { value: "Bench Z" } }); + fireEvent.click(button("Save name")); + await waitFor(() => expect(screen.getByLabelText("Use Bench Z")).toBeTruthy()); + fireEvent.click(within(rows()[0]).getByRole("button", { name: "Rename" })); + fireEvent.click(button("Cancel")); + expect(screen.queryByLabelText("New name for Bench Z")).toBeNull(); + }); + + it("deletes a station only after the operator confirms", async () => { + const { backend } = renderCard(TWO_STATIONS); + fireEvent.click(within(rows()[1]).getByRole("button", { name: "Delete" })); + fireEvent.click(button("Keep")); + expect(backend.deleteStation).not.toHaveBeenCalled(); + fireEvent.click(within(rows()[1]).getByRole("button", { name: "Delete" })); + fireEvent.click(button("Delete Cart B")); + await waitFor(() => expect(rows()).toHaveLength(2)); + expect(backend.deleteStation).toHaveBeenCalledWith("tok", "st_2"); + }); + + it("shows the backend's reason for a refused change and keeps the list", async () => { + const addStation = vi.fn(async () => { + throw new SettingsHttpError("a station named 'Bench A' already exists"); + }); + renderCard(TWO_STATIONS, { backend: { addStation } }); + fireEvent.change(screen.getByLabelText("New station name"), { target: { value: "bench a" } }); + fireEvent.click(button("Add station")); + expect(await screen.findByText("Not saved: a station named 'Bench A' already exists")).toBeTruthy(); + expect(rows()).toHaveLength(3); + }); + + it("freezes the station in use during a take and leaves the others editable", () => { + renderCard({ ...TWO_STATIONS, locked_reason: "finish or discard the current take before changing the station in use" }); + const [bench, cart] = rows(); + expect((screen.getByLabelText("Use Cart B") as HTMLInputElement).disabled).toBe(true); + expect((screen.getByLabelText("Use no station") as HTMLInputElement).disabled).toBe(true); + expect((within(bench).getByRole("button", { name: "Rename" }) as HTMLButtonElement).disabled).toBe(true); + expect((within(bench).getByRole("button", { name: "Delete" }) as HTMLButtonElement).disabled).toBe(true); + expect((within(cart).getByRole("button", { name: "Rename" }) as HTMLButtonElement).disabled).toBe(false); + expect((within(cart).getByRole("button", { name: "Delete" }) as HTMLButtonElement).disabled).toBe(false); + expect(screen.getByText("Finish or discard the current take before changing the station in use.")).toBeTruthy(); + }); + + it("changes nothing without the control token and says where to enter it", () => { + const { backend } = renderCard(TWO_STATIONS, { controlToken: null }); + expect((screen.getByLabelText("Use Cart B") as HTMLInputElement).disabled).toBe(true); + expect((screen.getByLabelText("New station name") as HTMLInputElement).disabled).toBe(true); + expect((within(rows()[1]).getByRole("button", { name: "Rename" }) as HTMLButtonElement).disabled).toBe(true); + expect(screen.getByText(/Enter the control token in the recording panel/)).toBeTruthy(); + expect(backend.addStation).not.toHaveBeenCalled(); + }); + + it("shows the warning of a registry that could not be read", () => { + renderCard({ ...STATIONS_FIXTURE, warning: "Saved stations are unreadable. Adding a station replaces them." }); + expect(screen.getByText("Saved stations are unreadable. Adding a station replaces them.")).toBeTruthy(); + }); +}); diff --git a/examples/egocap/frontend/src/StationsCard.tsx b/examples/egocap/frontend/src/StationsCard.tsx new file mode 100644 index 0000000000..bf0610b414 --- /dev/null +++ b/examples/egocap/frontend/src/StationsCard.tsx @@ -0,0 +1,249 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** + * The Stations card of the Settings dialog: the stations this site records at, and the one in use. + * + * The station in use names every recording and its activity log, and its cameras are the ones the cards below + * edit. It cannot change while a take is being recorded; the backend says so in `locked_reason` and refuses the + * change either way. A station that is not in use can always be added, renamed or deleted. + */ +import { useState } from "react"; +import { Card, TokenHint, useAction } from "./settingsParts"; +import { ROLE_LABELS } from "./settingsApi"; +import { sentence } from "./sentence"; +import type { StationChange, StationListing, StationRecord } from "./stationsApi"; + +/** The registry calls the card makes; the dialog passes the real ones and tests pass fakes. */ +export interface StationsBackend { + addStation: (controlToken: string, fields: StationChange) => Promise; + updateStation: (controlToken: string, id: string, changes: StationChange) => Promise; + deleteStation: (controlToken: string, id: string) => Promise; + selectStation: (controlToken: string, id: string | null) => Promise; +} + +/** The longest name the backend accepts, so the field stops where a save would be refused. */ +const MAX_NAME_CHARS = 64; + +/** Which camera fills each role, in one line, so two stations with different cameras can be told apart at a glance. */ +function roleSummary(station: StationRecord, roles: readonly string[]): string { + return roles.map((role) => `${ROLE_LABELS[role] ?? role}: ${station.camera_roles[role] ?? "—"}`).join(" · "); +} + +export interface StationsCardProps { + listing: StationListing; + controlToken: string | null; + backend: StationsBackend; + /** The camera setup saved before any station existed; the first station added takes it over. */ + inherited: StationChange; + /** Called with the backend's listing after every successful change. */ + onListing: (listing: StationListing) => void; +} + +/** List the stations, choose the one in use, and add, rename or delete them. */ +export function StationsCard({ listing, controlToken, backend, inherited, onListing }: StationsCardProps) { + const [{ busy, failure }, run] = useAction(); + const locked = listing.locked_reason !== null; + const canChange = controlToken !== null && !busy; + /** Run one registry change with the token and hand its listing to the dialog. */ + const change = (work: (token: string) => Promise) => { + if (controlToken !== null) run(() => work(controlToken).then(onListing)); + }; + /** Add a station; the first one takes over the camera setup already saved and is put in use. */ + const add = (name: string) => + change(async (token) => { + const first = listing.stations.length === 0; + const added = await backend.addStation(token, first ? { ...inherited, name } : { name }); + // During a take the station in use cannot change, so the new station is left for the operator to select. + if (!first || added.locked_reason !== null) return added; + return backend.selectStation(token, added.stations[added.stations.length - 1].id); + }); + + return ( + + {listing.warning !== undefined &&

{listing.warning}

} + {listing.stations.length === 0 ? ( +

+ No stations yet. Recordings carry the deployment's label, “{listing.label}”. Add a station to choose between stations here. +

+ ) : ( +
    + {listing.stations.map((station) => ( + change((token) => backend.selectStation(token, station.id))} + onRename={(name) => change((token) => backend.updateStation(token, station.id, { name }))} + onDelete={() => change((token) => backend.deleteStation(token, station.id))} + /> + ))} +
  • + +
  • +
+ )} + + {locked &&

{sentence(listing.locked_reason ?? "")}.

} + {failure !== null &&

Not saved: {failure}

} + +
+ ); +} + +/** One station: the radio that puts it in use, what fills its roles, why it cannot record, and its actions. */ +function StationRow({ + station, + roles, + inUse, + canChange, + locked, + onSelect, + onRename, + onDelete, +}: { + station: StationRecord; + roles: readonly string[]; + inUse: boolean; + canChange: boolean; + /** A take is being recorded: the station in use can be neither replaced nor edited. */ + locked: boolean; + onSelect: () => void; + onRename: (name: string) => void; + onDelete: () => void; +}) { + const [mode, setMode] = useState<"view" | "rename" | "delete">("view"); + const [draft, setDraft] = useState(station.name); + // The station in use is frozen during a take; every other station stays editable. + const editable = canChange && !(inUse && locked); + const renamed = draft.trim() !== "" && draft.trim() !== station.name; + /** Save a changed name and leave the editor; an unchanged or empty one just closes it. */ + const commitRename = () => { + if (renamed) onRename(draft.trim()); + setMode("view"); + }; + return ( +
  • +
    + + {roleSummary(station, roles)} + {station.problems.length > 0 && Cannot record yet: {station.problems.join("; ")}.} +
    + {mode === "view" && ( + <> + + + + )} + {mode === "rename" && ( + <> + + + + )} + {mode === "delete" && ( + <> + + + + )} +
  • + ); +} + +/** The name field and button that add a station. */ +function AddStation({ canChange, onAdd }: { canChange: boolean; onAdd: (name: string) => void }) { + const [name, setName] = useState(""); + const ready = canChange && name.trim() !== ""; + /** Add the typed name and clear the field for the next one. */ + const submit = () => { + if (!ready) return; + onAdd(name.trim()); + setName(""); + }; + return ( +
    + setName(e.target.value)} + onKeyDown={(e) => { + if (e.key === "Enter") submit(); + }} + /> + +
    + ); +} diff --git a/examples/egocap/frontend/src/recordingEligibility.ts b/examples/egocap/frontend/src/recordingEligibility.ts index 1a11e9c410..b07a1e4afa 100644 --- a/examples/egocap/frontend/src/recordingEligibility.ts +++ b/examples/egocap/frontend/src/recordingEligibility.ts @@ -10,6 +10,7 @@ */ import type { RecordingPhase } from "./recordingUiReducer"; +import { sentence } from "./sentence"; import type { RecordingActions, RecordingSnapshot } from "./recordingTypes"; export type RecordingActionKind = "startEpisode" | "stopEpisode" | "discardEpisode" | "taskEdit" | "newBatch"; @@ -70,7 +71,8 @@ export function computeEligibility( if (episodePhase === "RECOVERY_REQUIRED") return blocked("A take was interrupted -- use New batch to clear it"); if (episodePhase !== "IDLE") return blocked("An episode is already active"); if (snapshot.taskText === null || snapshot.taskText.trim() === "") return blocked("Set a task first"); - if (!snapshot.readyToRecord) return blocked("Required sources not ready"); + // The backend's own reason (station setup, a stale source) when it gave one. + if (!snapshot.readyToRecord) return blocked(snapshot.notReadyReason !== null ? sentence(snapshot.notReadyReason) : "Required sources not ready"); return eligible(); }), stopEpisode: result("stopEpisode", () => { diff --git a/examples/egocap/frontend/src/recordingTypes.ts b/examples/egocap/frontend/src/recordingTypes.ts index 5b2b0ab789..6b477be909 100644 --- a/examples/egocap/frontend/src/recordingTypes.ts +++ b/examples/egocap/frontend/src/recordingTypes.ts @@ -105,6 +105,9 @@ export interface RecordingSnapshot { * (no episode already active and a task is set) -- not a real observed * device/capture-source readiness signal. */ readyToRecord: boolean; + /** Why the backend would refuse a take right now, when station setup or a capture source is the cause; + * null when ready, and null when only the task is missing. */ + notReadyReason: string | null; /** The backend's count of accepted commands. Compared only within one * socket, so a snapshot older than one already applied can be dropped; * it restarts from 0 with the backend process. */ diff --git a/examples/egocap/frontend/src/sentence.ts b/examples/egocap/frontend/src/sentence.ts new file mode 100644 index 0000000000..1c43dfa358 --- /dev/null +++ b/examples/egocap/frontend/src/sentence.ts @@ -0,0 +1,8 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** A backend reason as a sentence: its messages start lower-case because they are also read mid-sentence. */ +export function sentence(reason: string): string { + return reason.charAt(0).toUpperCase() + reason.slice(1); +} diff --git a/examples/egocap/frontend/src/settingsParts.tsx b/examples/egocap/frontend/src/settingsParts.tsx new file mode 100644 index 0000000000..71bc381380 --- /dev/null +++ b/examples/egocap/frontend/src/settingsParts.tsx @@ -0,0 +1,47 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** Building blocks shared by the Settings dialog's tabs and the cards that live in them. */ +import { useState, type ReactNode } from "react"; + +/** Turn unknown request failures into a concise operator-facing explanation. */ +export function errorMessage(error: unknown): string { + return error instanceof Error ? error.message : String(error); +} + +/** One titled block of a tab. */ +export function Card({ title, lead, children }: { title: string; lead?: string; children: ReactNode }) { + return ( +
    +

    {title}

    + {lead !== undefined &&

    {lead}

    } + {children} +
    + ); +} + +/** Explain why station changes require the recording control token. */ +export function TokenHint({ controlToken }: { controlToken: string | null }) { + if (controlToken !== null) return null; + return

    Enter the control token in the recording panel to change these.

    ; +} + +/** The pending/failed state of one save-type action, shown next to its button. */ +export function useAction(): [{ busy: boolean; failure: string | null }, (work: () => Promise) => void] { + const [busy, setBusy] = useState(false); + const [failure, setFailure] = useState(null); + /** Keep request failures visible and prevent duplicate submissions. */ + const run = (work: () => Promise) => { + setBusy(true); + setFailure(null); + work().then( + () => setBusy(false), + (error: unknown) => { + setBusy(false); + setFailure(errorMessage(error)); + }, + ); + }; + return [{ busy, failure }, run]; +} diff --git a/examples/egocap/frontend/src/settingsTestDoubles.ts b/examples/egocap/frontend/src/settingsTestDoubles.ts index 3330a208f0..03efa42fd7 100644 --- a/examples/egocap/frontend/src/settingsTestDoubles.ts +++ b/examples/egocap/frontend/src/settingsTestDoubles.ts @@ -4,6 +4,7 @@ /** A complete `/api/settings` body for tests: a development default with one camera. */ import type { EffectiveSettings, OperatorSettings, TaskFileContents, TaskFileListing, ToolInfo } from "./settingsApi"; +import type { HeadsetAddress, StationChange, StationListing, StationRecord } from "./stationsApi"; export const OPERATOR_SETTINGS_FIXTURE: OperatorSettings = { camera_type: null, @@ -14,6 +15,23 @@ export const OPERATOR_SETTINGS_FIXTURE: OperatorSettings = { preselected_task: null, }; +/** A registry with no stations: the configuration-free default, where the deployment's own label applies. */ +export const STATIONS_FIXTURE: StationListing = { + stations: [], + selected: null, + roles: ["ego", "wrist_left", "wrist_right"], + camera_types: ["sensing_gmsl", "oak_d"], + label: "Station 01", + locked_reason: null, +}; + +/** One wireless address, nothing saved yet. */ +export const HEADSET_ADDRESS_FIXTURE: HeadsetAddress = { + candidates: [{ address: "10.0.0.42", interface: "wlp2s0", kind: "wireless" }], + saved: null, + changed: false, +}; + export const TASK_FILES_FIXTURE: TaskFileListing = { files: ["Kitchen.csv"], imported: [] }; export const KITCHEN_FIXTURE: TaskFileContents = { @@ -86,3 +104,59 @@ export const SETTINGS_FIXTURE: EffectiveSettings = { task_files: { dir: "/repo/examples/egocap/data/taskfiles", available: true }, origins: { allowed: [], trusted_hostnames: null }, }; + +/** An in-memory station registry that answers like the backend's, so a change shows up in the next listing. */ +export function fakeStationRegistry(initial: StationListing = STATIONS_FIXTURE) { + let listing = initial; + let nextId = initial.stations.length + 1; + /** Replace one station and return the listing, as every backend change does. */ + const replace = (id: string, change: (station: StationRecord) => StationRecord): StationListing => { + listing = { ...listing, stations: listing.stations.map((station) => (station.id === id ? change(station) : station)) }; + return listing; + }; + /** The label recordings carry: the station in use, else the deployment's own. */ + const relabel = (): StationListing => { + const inUse = listing.stations.find((station) => station.id === listing.selected); + listing = { ...listing, label: inUse?.name ?? STATIONS_FIXTURE.label }; + return listing; + }; + return { + get listing() { + return listing; + }, + set listing(next: StationListing) { + listing = next; + }, + /** The station in use, or null. */ + inUse: (): StationRecord | null => listing.stations.find((station) => station.id === listing.selected) ?? null, + addStation: async (_token: string, fields: StationChange): Promise => { + const station: StationRecord = { + id: `st_${nextId++}`, + name: fields.name ?? "", + camera_type: fields.camera_type ?? null, + camera_roles: { ego: null, wrist_left: null, wrist_right: null, ...fields.camera_roles }, + problems: [], + headset_address: fields.headset_address ?? null, + }; + listing = { ...listing, stations: [...listing.stations, station] }; + return listing; + }, + updateStation: async (_token: string, id: string, changes: StationChange): Promise => { + replace(id, (station) => ({ ...station, ...changes, camera_roles: { ...station.camera_roles, ...changes.camera_roles } })); + return relabel(); + }, + deleteStation: async (_token: string, id: string): Promise => { + listing = { ...listing, stations: listing.stations.filter((station) => station.id !== id), selected: listing.selected === id ? null : listing.selected }; + return relabel(); + }, + selectStation: async (_token: string, id: string | null): Promise => { + listing = { ...listing, selected: id }; + return relabel(); + }, + loadHeadsetAddress: async (): Promise => { + const saved = listing.stations.find((station) => station.id === listing.selected)?.headset_address ?? null; + const changed = saved !== null && !HEADSET_ADDRESS_FIXTURE.candidates.some((candidate) => candidate.address === saved); + return { ...HEADSET_ADDRESS_FIXTURE, saved, changed }; + }, + }; +} diff --git a/examples/egocap/frontend/src/stationsApi.test.ts b/examples/egocap/frontend/src/stationsApi.test.ts new file mode 100644 index 0000000000..5c368c85ea --- /dev/null +++ b/examples/egocap/frontend/src/stationsApi.test.ts @@ -0,0 +1,113 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** The station calls: what each sends, the backend's own reason on a refusal, and a body of the wrong shape. */ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { SettingsHttpError, SettingsParseError } from "./settingsApi"; +import { HEADSET_ADDRESS_FIXTURE, STATIONS_FIXTURE } from "./settingsTestDoubles"; +import { + addStation, + changeStationActivity, + deleteStation, + fetchHeadsetAddress, + fetchStationActivity, + fetchStations, + selectStation, + updateStation, + type StationActivity, +} from "./stationsApi"; + +afterEach(() => vi.unstubAllGlobals()); + +function stubFetch(status: number, body: unknown) { + const fn = vi.fn(async () => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } })); + vi.stubGlobal("fetch", fn); + return fn; +} + +const ACTIVITY: StationActivity = { + station: "Bench A", + date: "2026-03-09", + state: "active", + since: 1_000, + active_seconds: 60, + inactive_seconds: 0, + blocker_count: 0, + notes: "", + as_of: 1_060, +}; + +const JSON_AUTH = { "content-type": "application/json", "X-Control-Token": "tok" }; + +describe("the station registry", () => { + it("is read without a credential, and with one when the page has it", async () => { + const fn = stubFetch(200, STATIONS_FIXTURE); + await expect(fetchStations()).resolves.toEqual(STATIONS_FIXTURE); + expect(fn).toHaveBeenLastCalledWith("/api/stations", { signal: undefined, headers: {} }); + await fetchStations(undefined, "tok"); + expect(fn).toHaveBeenLastCalledWith("/api/stations", { signal: undefined, headers: { "X-Control-Token": "tok" } }); + }); + + it("sends every change with the control token and returns the new listing", async () => { + const fn = stubFetch(200, STATIONS_FIXTURE); + await addStation("tok", { name: "Bench A" }); + expect(fn).toHaveBeenLastCalledWith("/api/stations", { method: "POST", headers: JSON_AUTH, body: JSON.stringify({ name: "Bench A" }) }); + await updateStation("tok", "st 1", { camera_roles: { ego: "cam_head" } }); + expect(fn).toHaveBeenLastCalledWith("/api/stations/st%201", { method: "PUT", headers: JSON_AUTH, body: JSON.stringify({ camera_roles: { ego: "cam_head" } }) }); + await deleteStation("tok", "st_1"); + expect(fn).toHaveBeenLastCalledWith("/api/stations/st_1", { method: "DELETE", headers: { "X-Control-Token": "tok" } }); + await expect(selectStation("tok", null)).resolves.toEqual(STATIONS_FIXTURE); + expect(fn).toHaveBeenLastCalledWith("/api/stations/select", { method: "POST", headers: JSON_AUTH, body: JSON.stringify({ id: null }) }); + }); + + it("surfaces the backend's reason for a refusal, or the status when it gave none", async () => { + stubFetch(400, { detail: "a station named 'Bench A' already exists" }); + await expect(addStation("tok", { name: "bench a" })).rejects.toThrow(new SettingsHttpError("a station named 'Bench A' already exists")); + vi.stubGlobal("fetch", vi.fn(async () => new Response("gateway down", { status: 502 }))); + await expect(fetchStations()).rejects.toThrow(new SettingsHttpError("HTTP 502")); + }); + + it("rejects a listing of the wrong shape", async () => { + for (const body of [null, { stations: {} }, { ...STATIONS_FIXTURE, label: 7 }, { ...STATIONS_FIXTURE, roles: "ego" }]) { + stubFetch(200, body); + await expect(fetchStations()).rejects.toThrow(SettingsParseError); + } + }); +}); + +describe("the headset address", () => { + it("is read with the control token", async () => { + const fn = stubFetch(200, HEADSET_ADDRESS_FIXTURE); + await expect(fetchHeadsetAddress("tok")).resolves.toEqual(HEADSET_ADDRESS_FIXTURE); + expect(fn).toHaveBeenCalledWith("/api/headset-address", { signal: undefined, headers: { "X-Control-Token": "tok" } }); + }); + + it("reports a refusal and a malformed body", async () => { + stubFetch(403, { detail: "control token rejected" }); + await expect(fetchHeadsetAddress("wrong")).rejects.toThrow(new SettingsHttpError("control token rejected")); + stubFetch(200, { candidates: "10.0.0.42" }); + await expect(fetchHeadsetAddress("tok")).rejects.toThrow(SettingsParseError); + }); +}); + +describe("station activity", () => { + it("is read without a credential and changed with one", async () => { + const fn = stubFetch(200, ACTIVITY); + await expect(fetchStationActivity()).resolves.toEqual(ACTIVITY); + expect(fn).toHaveBeenLastCalledWith("/api/station-activity", { signal: undefined }); + await expect(changeStationActivity("tok", { state: "inactive" })).resolves.toEqual(ACTIVITY); + expect(fn).toHaveBeenLastCalledWith("/api/station-activity", { method: "POST", headers: JSON_AUTH, body: JSON.stringify({ state: "inactive" }) }); + }); + + it("reports a refusal and a malformed body", async () => { + stubFetch(400, { detail: "state must be one of active, inactive" }); + await expect(changeStationActivity("tok", { notes: "x" })).rejects.toThrow(new SettingsHttpError("state must be one of active, inactive")); + stubFetch(503, { detail: "stations are not available yet" }); + await expect(fetchStationActivity()).rejects.toThrow(new SettingsHttpError("stations are not available yet")); + for (const body of [null, { ...ACTIVITY, state: "paused" }, { ...ACTIVITY, active_seconds: "60" }, { ...ACTIVITY, station: null }]) { + stubFetch(200, body); + await expect(fetchStationActivity()).rejects.toThrow(SettingsParseError); + } + }); +}); diff --git a/examples/egocap/frontend/src/stationsApi.ts b/examples/egocap/frontend/src/stationsApi.ts new file mode 100644 index 0000000000..2c2c9865d7 --- /dev/null +++ b/examples/egocap/frontend/src/stationsApi.ts @@ -0,0 +1,176 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** + * The station registry, the station's activity for today and the headset address + * (`backend/egocap_web/station_routes.py`). + * + * Reading the registry and the activity needs nothing; a station's headset address and this host's network + * addresses are returned only with the run's control token, and every change carries it, as recording + * commands do. + */ +import { SettingsHttpError, SettingsParseError } from "./settingsApi"; + +/** One station as the backend lists it. */ +export interface StationRecord { + id: string; + name: string; + camera_type: string | null; + /** Which offered camera fills each role; null where unassigned. Every role is present. */ + camera_roles: Record; + /** Why this station cannot record yet, most important first; empty when it can. */ + problems: string[]; + /** The capture host address last entered in the headset. Present only when the request carried the token. */ + headset_address?: string | null; +} + +/** `GET /api/stations`, and the reply to every registry change. */ +export interface StationListing { + stations: StationRecord[]; + /** The id of the station in use, or null when none is: the deployment's own station label then applies. */ + selected: string | null; + roles: string[]; + camera_types: string[]; + /** The station label recordings carry right now. */ + label: string; + /** Why the station in use cannot change now (a take is being recorded), or null. */ + locked_reason: string | null; + /** Set when the saved registry could not be read. */ + warning?: string; +} + +/** The fields a station can be created or changed with; a role change may name only some roles. */ +export interface StationChange { + name?: string; + camera_type?: string | null; + camera_roles?: Record; + headset_address?: string | null; +} + +/** The backend's public reason for a refusal, or the HTTP status when it gave none. */ +async function failureOf(response: Response): Promise { + let detail = `HTTP ${response.status}`; + try { + const body = (await response.json()) as { detail?: unknown }; + if (typeof body.detail === "string") detail = body.detail; + } catch { + // A non-JSON error body keeps the status-code message. + } + return new SettingsHttpError(detail); +} + +/** Checks the fields the page reads without guarding; the rest is trusted, since the two halves ship together. */ +function parseListing(value: unknown): StationListing { + const record = (typeof value === "object" && value !== null ? value : {}) as Record; + if (!Array.isArray(record.stations) || !Array.isArray(record.roles) || typeof record.label !== "string") { + throw new SettingsParseError("station listing is malformed"); + } + return value as StationListing; +} + +/** Sends one request and parses the listing every station route answers with. */ +async function listingFrom(path: string, init: RequestInit): Promise { + const response = await fetch(path, init); + if (!response.ok) throw await failureOf(response); + return parseListing(await response.json()); +} + +/** The headers of a change: the credential, and the JSON type when a body follows. */ +function changeHeaders(controlToken: string, withBody: boolean): Record { + return withBody ? { "content-type": "application/json", "X-Control-Token": controlToken } : { "X-Control-Token": controlToken }; +} + +/** Load the registry; with the control token each station also carries its headset address. */ +export function fetchStations(signal?: AbortSignal, controlToken?: string | null): Promise { + return listingFrom("/api/stations", { signal, headers: controlToken ? { "X-Control-Token": controlToken } : {} }); +} + +/** Add a station. */ +export function addStation(controlToken: string, fields: StationChange): Promise { + return listingFrom("/api/stations", { method: "POST", headers: changeHeaders(controlToken, true), body: JSON.stringify(fields) }); +} + +/** Change the named fields of one station. */ +export function updateStation(controlToken: string, id: string, changes: StationChange): Promise { + return listingFrom(`/api/stations/${encodeURIComponent(id)}`, { method: "PUT", headers: changeHeaders(controlToken, true), body: JSON.stringify(changes) }); +} + +/** Delete one station. */ +export function deleteStation(controlToken: string, id: string): Promise { + return listingFrom(`/api/stations/${encodeURIComponent(id)}`, { method: "DELETE", headers: changeHeaders(controlToken, false) }); +} + +/** Put a station in use, or none for null. */ +export function selectStation(controlToken: string, id: string | null): Promise { + return listingFrom("/api/stations/select", { method: "POST", headers: changeHeaders(controlToken, true), body: JSON.stringify({ id }) }); +} + +/** One address the headset could be given. */ +export interface HostAddress { + address: string; + /** The network interface holding the address, or null when it is not one of the backend host's. */ + interface: string | null; + kind: string; +} + +/** `GET /api/headset-address`. */ +export interface HeadsetAddress { + /** Best first: wireless before wired. Empty when the host has no usable address. */ + candidates: HostAddress[]; + /** The address saved for the station in use, or null. */ + saved: string | null; + /** The saved address is no longer one the host has, so the headset needs the new one. */ + changed: boolean; +} + +/** Load the addresses to enter in the headset. */ +export async function fetchHeadsetAddress(controlToken: string, signal?: AbortSignal): Promise { + const response = await fetch("/api/headset-address", { signal, headers: { "X-Control-Token": controlToken } }); + if (!response.ok) throw await failureOf(response); + const body = (await response.json()) as Partial; + if (!Array.isArray(body.candidates)) throw new SettingsParseError("headset address is malformed"); + return body as HeadsetAddress; +} + +export type ActivityState = "active" | "inactive"; + +/** `GET /api/station-activity`: today's active and inactive time for the station in use. */ +export interface StationActivity { + station: string; + date: string; + state: ActivityState; + /** Epoch seconds the current state began, or null before the first change of the day. */ + since: number | null; + active_seconds: number; + inactive_seconds: number; + /** How many times the station went from active to inactive today. */ + blocker_count: number; + notes: string; + /** Epoch seconds the totals were computed at. */ + as_of: number; +} + +/** Checks the fields the toggle renders from. */ +function parseActivity(value: unknown): StationActivity { + const record = (typeof value === "object" && value !== null ? value : {}) as Record; + const numeric = typeof record.active_seconds === "number" && typeof record.inactive_seconds === "number"; + if (!numeric || (record.state !== "active" && record.state !== "inactive") || typeof record.station !== "string") { + throw new SettingsParseError("station activity is malformed"); + } + return value as StationActivity; +} + +/** Load today's activity. */ +export async function fetchStationActivity(signal?: AbortSignal): Promise { + const response = await fetch("/api/station-activity", { signal }); + if (!response.ok) throw await failureOf(response); + return parseActivity(await response.json()); +} + +/** Set the state, the blocker notes, or both. */ +export async function changeStationActivity(controlToken: string, change: { state?: ActivityState; notes?: string }): Promise { + const response = await fetch("/api/station-activity", { method: "POST", headers: changeHeaders(controlToken, true), body: JSON.stringify(change) }); + if (!response.ok) throw await failureOf(response); + return parseActivity(await response.json()); +} diff --git a/examples/egocap/frontend/src/styles.css b/examples/egocap/frontend/src/styles.css index adc36003c2..ec9dd30e7b 100644 --- a/examples/egocap/frontend/src/styles.css +++ b/examples/egocap/frontend/src/styles.css @@ -369,6 +369,52 @@ body { border-color: var(--accent); } +/* A station row: the name line on top, what fills its roles and any problem beneath it. */ +.settings-station-head { + display: flex; + align-items: center; + gap: var(--space-2); + min-width: 0; + cursor: pointer; +} + +.settings-station-head .settings-input { + flex: 1 1 200px; +} + +/* A destructive confirmation: only ever shown after the operator asked to delete. */ +.settings-danger { + height: 32px; + padding: 0 var(--space-3); + border-radius: var(--radius-chip); + border: 1px solid var(--critical); + background: transparent; + color: var(--critical); + font: inherit; + font-size: 13px; + font-weight: 600; + cursor: pointer; +} + +.settings-danger:disabled { + opacity: 0.45; + cursor: default; +} + +.settings-danger:focus-visible { + outline: 2px solid var(--critical); + outline-offset: 1px; +} + +/* The address to type into the headset: large and selectable, since it is read across to another device. */ +.headset-address { + margin: 0; + font-size: 28px; + font-weight: 700; + letter-spacing: 0.02em; + user-select: all; +} + .settings-list-main { display: flex; align-items: center; @@ -533,6 +579,67 @@ hero card so the tracking tree below starts near the top of the viewport. */ flex: 1 1 auto; } +/* The station's active/inactive toggle, beside its name. */ +.station-activity { + display: inline-flex; + align-items: baseline; + gap: var(--space-2); +} + +.station-activity-toggle { + display: inline-flex; + align-items: center; + gap: var(--space-1); + padding: 1px var(--space-2); + border-radius: var(--radius-chip); + border: 1px solid var(--border); + background: var(--surface-raised); + color: var(--text-main); + font: inherit; + font-weight: 600; + cursor: pointer; +} + +.station-activity-toggle:hover:not(:disabled) { + border-color: var(--accent); +} + +.station-activity-toggle:disabled { + cursor: default; +} + +.station-activity-toggle:focus-visible { + outline: 2px solid var(--accent); + outline-offset: 2px; +} + +.station-activity-dot { + width: 8px; + height: 8px; + border-radius: 50%; + background: var(--text-secondary); +} + +.station-activity-toggle--active { + border-color: var(--positive); +} + +.station-activity-toggle--active .station-activity-dot { + background: var(--positive); +} + +.station-activity-toggle--blocked { + border-color: var(--warning); +} + +.station-activity-toggle--blocked .station-activity-dot { + background: var(--warning); +} + +.station-activity-summary { + color: var(--text-secondary); +} + .status-strip.tone-positive .status-headline { color: var(--positive); } diff --git a/examples/egocap/frontend/src/useCaptureSession.hook.test.ts b/examples/egocap/frontend/src/useCaptureSession.hook.test.ts index 9e87cf0771..614f765f49 100644 --- a/examples/egocap/frontend/src/useCaptureSession.hook.test.ts +++ b/examples/egocap/frontend/src/useCaptureSession.hook.test.ts @@ -674,6 +674,7 @@ describe("useCaptureSession (effect integration)", () => { savedCount: 0, lastResult: null, readyToRecord: false, + notReadyReason: null, // this wire body predates the reason, so none revision: 0, }); expect(result.current.recordingSnapshotReceivedAtMonotonic).not.toBeNull(); @@ -848,6 +849,41 @@ describe("useCaptureSession (effect integration)", () => { expect(result.current.recordingSnapshot?.savedCount).toBe(3); }); + it("carries the backend's reason a take would be refused, and drops a snapshot whose reason is not text", async () => { + const { result } = renderHook(() => useCaptureSession()); + const ws1 = FakeWebSocket.instances[0]; + act(() => ws1.open()); + act(() => ws1.emitText(runningSnapshotBody(1))); + const push = (revision: number, reason: unknown) => + act(() => { + ws1.emitText( + JSON.stringify({ + type: "recording_snapshot", + snapshot: { + batch_id: "b1", + episode_phase: "IDLE", + current_episode_id: null, + current_episode_elapsed_ms: null, + task_text: "Pour water.", + default_operator: null, + auto_fill_operator_name: false, + saved_count: 0, + last_result: null, + ready_to_record: false, + not_ready_reason: reason, + revision, + }, + }), + ); + }); + push(1, "select a station before recording"); + expect(result.current.recordingSnapshot?.notReadyReason).toBe("select a station before recording"); + push(2, null); + expect(result.current.recordingSnapshot?.notReadyReason).toBeNull(); + push(3, 7); + expect(result.current.recordingSnapshot?.revision).toBe(2); + }); + it("sendRecordingCommand rejects a second send while one is already in flight", async () => { const { result } = renderHook(() => useCaptureSession()); const ws1 = FakeWebSocket.instances[0]; diff --git a/examples/egocap/frontend/src/useCaptureSession.ts b/examples/egocap/frontend/src/useCaptureSession.ts index 732f7f2a6d..7c66ec0b6a 100644 --- a/examples/egocap/frontend/src/useCaptureSession.ts +++ b/examples/egocap/frontend/src/useCaptureSession.ts @@ -211,6 +211,8 @@ function parseRecordingSnapshot(raw: unknown): RecordingSnapshot | null { savedCount: requireNonNegativeSafeInt(r.saved_count), lastResult: parseEpisodeResult(r.last_result), readyToRecord: requireBoolean(r.ready_to_record), + // Absent from a backend that predates the reason: treat as none rather than dropping the snapshot. + notReadyReason: r.not_ready_reason === undefined ? null : requireNullableString(r.not_ready_reason), revision: requireNonNegativeSafeInt(r.revision), }; } catch (err) { From 600d1433b7bf722d3def4ffd96fb4f02d222ab36 Mon Sep 17 00:00:00 2001 From: Shawn Hwang Date: Mon, 16 Nov 2026 11:03:53 -0800 Subject: [PATCH 03/13] feat(egocap): start-of-day flow, device connection test and recording gate The backend now reports the start-of-day flow (station, devices, calibration, record, wrap-up) and gates a take on it for a station in use. - Device connection test: every tracking device and camera the station needs is passed or failed with the reason; a role the station does not fill is skipped. A passed test holds for that station and that capture session only. - System checks, cached briefly because the gate is asked constantly: the calibration files of the roles in use, the glove plugin (where a missing SDK or licence shows), free disk space under the recording output, and the camera producer for cameras that arrive over LiveKit. Calibration and glove software are skipped for a mock session. - With a station in use a take is refused, with the reason, until the test has passed and the checks hold. With no stations the flow only advises, so the configuration-free default records as before. - GET /api/setup reports each step, the last test and the checks; POST /api/setup/connection-test runs the test with the control token. Co-Authored-By: Claude Fable 5.2 Signed-off-by: Shawn Hwang --- examples/egocap/backend/egocap_web/app.py | 14 +- .../egocap/backend/egocap_web/setup_checks.py | 268 +++++++++++++ .../egocap/backend/egocap_web/setup_routes.py | 76 ++++ .../backend/egocap_web/setup_service.py | 281 ++++++++++++++ .../egocap/tests/backend/test_setup_checks.py | 235 +++++++++++ .../egocap/tests/backend/test_setup_routes.py | 199 ++++++++++ .../tests/backend/test_setup_service.py | 367 ++++++++++++++++++ .../tests/backend/test_station_routes.py | 6 +- 8 files changed, 1443 insertions(+), 3 deletions(-) create mode 100644 examples/egocap/backend/egocap_web/setup_checks.py create mode 100644 examples/egocap/backend/egocap_web/setup_routes.py create mode 100644 examples/egocap/backend/egocap_web/setup_service.py create mode 100644 examples/egocap/tests/backend/test_setup_checks.py create mode 100644 examples/egocap/tests/backend/test_setup_routes.py create mode 100644 examples/egocap/tests/backend/test_setup_service.py diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py index ae8505942c..938bdea115 100644 --- a/examples/egocap/backend/egocap_web/app.py +++ b/examples/egocap/backend/egocap_web/app.py @@ -63,6 +63,8 @@ from .recordings import router as recordings_router from .settings_routes import EffectiveSettings from .settings_routes import router as settings_router +from .setup_routes import router as setup_router +from .setup_service import SetupService, capture_facts from .station_activity import ACTIVITY_DIR, StationActivity from .station_config import ResolvedStation, StationConfigError, load_station_config, station_config_path_from_env from .station_routes import router as station_router @@ -488,6 +490,15 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: ) app.state.station_service = station_service monitor.set_station_label(station_service.label()) + # The start-of-day flow: the device connection test and system checks that gate a take for a station in use. + setup_service = SetupService( + facts=lambda: capture_facts(monitor, config), + session_id=lambda: monitor.native.started.session_id if monitor.native.started is not None else None, + stations=station_service, + calibration_dir=calibration_dir, + output_root=recording_output_root, + ) + app.state.setup_service = setup_service await monitor.start() app.state.monitor = monitor # Generated once per backend process start (a restart is the only way @@ -503,7 +514,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: coordinator=coordinator, control_token=control_token, auto_fill_operator_name=auto_fill_operator_name, - setup_gate=station_service.block_reason, + setup_gate=setup_service.block_reason, ) # The 3D view settings are read once, for the view itself and for the settings report. visualization_config: VisualizationConfig | None = None @@ -570,6 +581,7 @@ def _optional_visualization( app.include_router(settings_router) app.include_router(operator_settings_router) app.include_router(station_router) +app.include_router(setup_router) # PoC demo integration: browse/download recorded files, off unless # EGOCAP_RECORDINGS_ENABLED=1. Not part of the final system design -- see # recordings.py's own module docstring. diff --git a/examples/egocap/backend/egocap_web/setup_checks.py b/examples/egocap/backend/egocap_web/setup_checks.py new file mode 100644 index 0000000000..91e7ce9285 --- /dev/null +++ b/examples/egocap/backend/egocap_web/setup_checks.py @@ -0,0 +1,268 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What a station must show before it records: the device connection test and the system checks. + +Both are lists of items, each passed, failed or skipped with the reason. The connection test asks whether +every device the station needs is connected and producing data right now; an operator runs it at the start of the +day. The system checks cover what readiness does not: calibration files, the glove plugin, free disk space and +the camera producer. A device or check the station does not use is skipped, never failed. + +This module is pure: it judges a :class:`CaptureFacts` value and never reads the capture session itself. +setup_service.py gathers the facts and keeps the last test result. +""" + +from __future__ import annotations + +from collections.abc import Callable, Mapping +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +PASS, FAIL, SKIP = "pass", "fail", "skip" + +#: The groups items are listed under, in display order. +TRACKING, CAMERAS, SYSTEM = "tracking", "cameras", "system" + +#: Free space, under the recording output, below which a take is refused: a take that fills the disk is lost. +MIN_FREE_BYTES = 10 * 1024**3 + +#: Operator-facing role names, shared by the items below. +ROLE_NAMES = {"ego": "Ego (head)", "wrist_left": "Left wrist", "wrist_right": "Right wrist"} + +#: The calibration file each camera role needs before its video can be related to the tracked pose. +ROLE_CALIBRATION = { + "ego": ("head_camera_intrinsics.json", "head_camera_extrinsics.json"), + "wrist_left": ("left_wrist_camera_intrinsics.json",), + "wrist_right": ("right_wrist_camera_intrinsics.json",), +} +#: Needed once a station has any wrist camera. +WRIST_OFFSETS = "wrist_calibration_offsets.json" + + +@dataclass(frozen=True) +class CheckItem: + """One device or check, and how it stands.""" + + id: str + group: str + label: str + status: str + #: Why it failed or was skipped; None for a pass that needs no comment. + detail: str | None = None + + def to_json(self) -> dict[str, Any]: + """The wire form.""" + return { + "id": self.id, + "group": self.group, + "label": self.label, + "status": self.status, + "detail": self.detail, + } + + +@dataclass(frozen=True) +class DeviceFact: + """One tracking device as the capture status reports it.""" + + kind: str # "headset", "controller" or "hand" + label: str + connected: bool + #: The device's own error or state, shown when it is not connected. + detail: str | None = None + + +@dataclass(frozen=True) +class CameraFact: + """One CaptureServer camera: whether it is connected and whether a frame arrived recently.""" + + connected: bool + fresh: bool + detail: str | None = None + + +@dataclass(frozen=True) +class CaptureFacts: + """Everything the checks read from the capture session, taken at one moment.""" + + running: bool = False + #: Why capture is not running, when it said. + error: str | None = None + #: A mock session has no real devices to calibrate or license. + mock: bool = False + session_id: str | None = None + #: The tracking kinds the deployment asked for: "headset", "controller", "hand". + requested: frozenset[str] = frozenset() + tracking_fresh: bool = False + devices: tuple[DeviceFact, ...] = () + cameras: Mapping[str, CameraFact] | None = None + #: Names of the camera streams the producer offers over LiveKit. + livekit_cameras: frozenset[str] = frozenset() + #: Why an offered LiveKit stream cannot be recorded, or None. + livekit_blocked: str | None = None + glove_plugin_requested: bool = False + #: The glove plugin's own state: None when available, else why not. Unused unless it was requested. + glove_plugin_error: str | None = None + + +_KIND_LABELS = {"headset": "Headset", "controller": "Controllers", "hand": "Gloves"} + + +def _tracking_items(facts: CaptureFacts) -> list[CheckItem]: + """One item per tracking device the session reports, and a failure for a requested kind it does not.""" + items: list[CheckItem] = [] + for index, device in enumerate(facts.devices): + items.append( + CheckItem( + f"device:{device.kind}:{index}", + TRACKING, + device.label, + PASS if device.connected else FAIL, + None if device.connected else (device.detail or "not connected"), + ) + ) + reported = {device.kind for device in facts.devices} + # A requested kind with no device at all would otherwise pass by having nothing to fail. + for kind in ("headset", "controller", "hand"): + if kind in facts.requested and kind not in reported: + items.append( + CheckItem( + f"device:{kind}", TRACKING, _KIND_LABELS[kind], FAIL, "not reported by the capture session" + ) + ) + # Connected devices that deliver nothing would record an empty take. + if items and not facts.tracking_fresh: + items.append(CheckItem("tracking:samples", TRACKING, "Tracking data", FAIL, "no recent sample")) + return items + + +def _camera_item(item_id: str, label: str, name: str, facts: CaptureFacts) -> CheckItem: + """How one named camera stands: a CaptureServer camera must be connected and delivering frames, a LiveKit + camera offered and recordable (its video is joined when a take starts).""" + if name in facts.livekit_cameras: + blocked = facts.livekit_blocked + return CheckItem(item_id, CAMERAS, label, FAIL if blocked else PASS, blocked) + camera = (facts.cameras or {}).get(name) + if camera is None: + return CheckItem(item_id, CAMERAS, label, FAIL, f"camera {name!r} is not offered by the capture session") + if not camera.connected: + return CheckItem(item_id, CAMERAS, label, FAIL, camera.detail or "not connected") + if not camera.fresh: + return CheckItem(item_id, CAMERAS, label, FAIL, "no recent frame") + return CheckItem(item_id, CAMERAS, label, PASS) + + +def _camera_items(facts: CaptureFacts, roles: Mapping[str, str | None] | None) -> list[CheckItem]: + """The station's cameras by role; with no station in use, every camera the session offers by name.""" + if roles is None: + names = sorted({*(facts.cameras or {}), *facts.livekit_cameras}) + return [_camera_item(f"camera:{name}", name, name, facts) for name in names] + items = [] + for role, camera in roles.items(): + label = ROLE_NAMES.get(role, role) + if camera is None: + # A station without this camera has nothing to test here. + items.append(CheckItem(f"camera:{role}", CAMERAS, label, SKIP, "not used by this station")) + else: + items.append(_camera_item(f"camera:{role}", f"{label}: {camera}", camera, facts)) + return items + + +def connection_items(facts: CaptureFacts, roles: Mapping[str, str | None] | None) -> list[CheckItem]: + """The device connection test: every tracking device and camera the station needs, each passed or failed. + + ``roles`` is the station in use's camera per role, or None when no station is in use. + """ + if not facts.running: + # Nothing can be judged device by device without a running session; say that once. + return [CheckItem("capture", TRACKING, "Capture session", FAIL, facts.error or "capture is not running")] + return [*_tracking_items(facts), *_camera_items(facts, roles)] + + +def _calibration_items( + facts: CaptureFacts, roles: Mapping[str, str | None] | None, calibration_dir: Path +) -> list[CheckItem]: + """The calibration file each camera role in use needs; skipped for a mock session or with no station.""" + if facts.mock or roles is None: + why = "mock capture has nothing to calibrate" if facts.mock else "no station in use" + return [CheckItem("calibration", SYSTEM, "Camera calibration", SKIP, why)] + needed = [name for role, names in ROLE_CALIBRATION.items() if roles.get(role) is not None for name in names] + if roles.get("wrist_left") is not None or roles.get("wrist_right") is not None: + needed.append(WRIST_OFFSETS) + if not needed: + return [ + CheckItem("calibration", SYSTEM, "Camera calibration", SKIP, "the station has no cameras assigned") + ] + missing = [name for name in needed if not (calibration_dir / name).is_file()] + detail = f"missing: {', '.join(missing)}" if missing else None + return [CheckItem("calibration", SYSTEM, "Camera calibration", FAIL if missing else PASS, detail)] + + +def _glove_item(facts: CaptureFacts) -> CheckItem: + """Whether the glove plugin loaded, which is where a missing SDK or licence shows.""" + if not facts.glove_plugin_requested: + return CheckItem("gloves", SYSTEM, "Glove plugin", SKIP, "gloves are not part of this deployment") + if facts.mock: + return CheckItem("gloves", SYSTEM, "Glove plugin", SKIP, "mock capture needs no glove software") + error = facts.glove_plugin_error + return CheckItem("gloves", SYSTEM, "Glove plugin", FAIL if error else PASS, error) + + +def _disk_item(output_root: Path, free_bytes: Callable[[Path], int], min_free_bytes: int) -> CheckItem: + """Whether the recording output has room for takes.""" + try: + free = free_bytes(output_root) + except OSError as exc: + return CheckItem( + "disk", SYSTEM, "Free disk space", FAIL, f"cannot read the recording output: {exc.strerror}" + ) + gib = 1024**3 + detail = f"{free / gib:.1f} GB free" + if free < min_free_bytes: + return CheckItem( + "disk", SYSTEM, "Free disk space", FAIL, f"{detail}; {min_free_bytes / gib:.0f} GB needed" + ) + return CheckItem("disk", SYSTEM, "Free disk space", PASS, detail) + + +def _producer_item(facts: CaptureFacts, camera_type: str | None) -> CheckItem: + """Whether the camera producer is reachable, for a station whose cameras arrive over LiveKit.""" + expected = camera_type == "sensing_gmsl" or bool(facts.livekit_cameras) + if not expected: + return CheckItem("producer", SYSTEM, "Camera producer", SKIP, "cameras are read by CaptureServer") + if not facts.livekit_cameras: + return CheckItem( + "producer", SYSTEM, "Camera producer", FAIL, "no camera stream is offered by the producer" + ) + return CheckItem( + "producer", SYSTEM, "Camera producer", FAIL if facts.livekit_blocked else PASS, facts.livekit_blocked + ) + + +def system_items( + facts: CaptureFacts, + roles: Mapping[str, str | None] | None, + camera_type: str | None, + *, + calibration_dir: Path, + output_root: Path, + free_bytes: Callable[[Path], int], + min_free_bytes: int = MIN_FREE_BYTES, +) -> list[CheckItem]: + """The checks beyond device connection: calibration files, the glove plugin, disk space and the producer.""" + return [ + *_calibration_items(facts, roles, calibration_dir), + _glove_item(facts), + _disk_item(output_root, free_bytes, min_free_bytes), + _producer_item(facts, camera_type), + ] + + +def first_failure(items: list[CheckItem]) -> str | None: + """The first failing item as one phrase, or None when nothing failed.""" + for item in items: + if item.status == FAIL: + return f"{item.label}: {item.detail}" if item.detail else item.label + return None diff --git a/examples/egocap/backend/egocap_web/setup_routes.py b/examples/egocap/backend/egocap_web/setup_routes.py new file mode 100644 index 0000000000..aa5030d703 --- /dev/null +++ b/examples/egocap/backend/egocap_web/setup_routes.py @@ -0,0 +1,76 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""HTTP surface for the start-of-day flow: where each step stands, and running the device connection test. + +Reading the flow is open to any page that can reach the backend, as the capture status is. Running the test +changes what recording is allowed to do, so it needs the run's control token. +""" + +from __future__ import annotations + +import asyncio +from typing import Any + +from fastapi import APIRouter, Request +from fastapi.responses import JSONResponse + +from .host_addresses import address_changed, headset_addresses +from .recording_command import control_token_valid + +router = APIRouter() + +_NO_STORE = {"Cache-Control": "no-store"} + + +def _reply(body: dict[str, Any], status: int = 200) -> JSONResponse: + """A non-cacheable JSON reply: the flow changes under the page.""" + return JSONResponse(body, status_code=status, headers=_NO_STORE) + + +def _state(request: Request) -> tuple[Any, Any, Any, Any] | None: + """The setup service, station service, recording context and settings, or None until the lifespan set them.""" + state = request.app.state + names = ("setup_service", "station_service", "recording_context", "settings") + found = tuple(getattr(state, name, None) for name in names) + return None if any(item is None for item in found) else found # type: ignore[return-value] + + +async def _headset_address_changed(stations: Any, settings: Any) -> bool: + """Whether the address saved for the station in use is no longer one of the capture host's.""" + selected = stations.registry.selected + saved = selected.headset_address if selected is not None else None + # Nothing saved means nothing to compare; the interfaces are not even listed. + if saved is None: + return False + candidates = await asyncio.to_thread(headset_addresses, settings.capture.capture_server_url) + return address_changed(saved, candidates) + + +async def _status(setup: Any, stations: Any, context: Any, settings: Any) -> JSONResponse: + """The flow as the page reads it.""" + changed = await _headset_address_changed(stations, settings) + return _reply(setup.status(saved_count=context.saved_count, headset_address_changed=changed)) + + +@router.get("/api/setup") +async def read_setup(request: Request) -> JSONResponse: + """Each step of the start-of-day flow, the last connection test, the system checks, and what blocks a take.""" + state = _state(request) + if state is None: + return _reply({"detail": "setup is not available yet"}, 503) + return await _status(*state) + + +@router.post("/api/setup/connection-test") +async def run_connection_test(request: Request) -> JSONResponse: + """Test every device the station in use needs now; the result decides whether a take may start.""" + state = _state(request) + if state is None: + return _reply({"detail": "setup is not available yet"}, 503) + setup, stations, context, settings = state + if not control_token_valid(request.headers.get("x-control-token"), context.control_token): + return _reply({"detail": "control token rejected"}, 403) + setup.run_connection_test() + return await _status(setup, stations, context, settings) diff --git a/examples/egocap/backend/egocap_web/setup_service.py b/examples/egocap/backend/egocap_web/setup_service.py new file mode 100644 index 0000000000..24652919af --- /dev/null +++ b/examples/egocap/backend/egocap_web/setup_service.py @@ -0,0 +1,281 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The start-of-day flow: its steps, the last device connection test, and whether station setup allows a take. + +The flow is station, devices, calibration, record, wrap-up. This service reports where each step stands and is +the recording gate: with a station in use, a take is refused until the connection test has passed for that +station in the current capture session and the system checks hold. With no stations set up nothing here gates +recording, the same configuration-free default the station registry keeps; the steps are then advisory. +""" + +from __future__ import annotations + +import shutil +import time +from collections.abc import Callable +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +from capture_server import protocol as p + +from .capture_status import CaptureStatusMonitor +from .config import CaptureStatusConfig +from .livekit_recording import unrecordable_reason +from .setup_checks import ( + FAIL, + SKIP, + CameraFact, + CaptureFacts, + CheckItem, + DeviceFact, + connection_items, + first_failure, + system_items, +) +from .station_service import StationService + +DONE, TODO, ATTENTION, SKIPPED = "done", "todo", "attention", "skipped" + +#: How old a sample may be and still count as arriving; the same window recording readiness uses. +_FRESH_SECONDS = 2.0 +#: The system checks touch the filesystem, and the gate is asked many times a second; one answer serves this long. +_SYSTEM_CACHE_SECONDS = 2.0 + +_SOURCE_KINDS = {p.SourceType.HEAD: "headset", p.SourceType.CONTROLLERS: "controller"} + + +def capture_facts(monitor: CaptureStatusMonitor, config: CaptureStatusConfig) -> CaptureFacts: + """The capture session's current state, as the checks read it.""" + native = monitor.native + now = time.monotonic() + status = native.latest_status + running = native.stopped is None and native.status is not None and native.status.running + gloves = p.PluginType.MANUS in config.plugins + requested = {_SOURCE_KINDS[source] for source in config.sources if source in _SOURCE_KINDS} + # Glove devices exist only when the glove plugin supplies the hands. + if gloves: + requested.add("hand") + tracking = monitor.preview.tracking() + cameras: dict[str, CameraFact] = {} + for camera in status.cameras if status is not None else (): + slot = monitor.preview.camera(camera.name) + cameras[camera.name] = CameraFact( + connected=camera.status is p.DeviceState.CONNECTED, + fresh=slot is not None and now - slot.received_monotonic <= _FRESH_SECONDS, + detail=camera.error or camera.status.name.lower(), + ) + started = native.started + livekit = [s for s in started.streams if isinstance(s, p.LiveKitCameraStream)] if started is not None else [] + return CaptureFacts( + running=running, + error=None if running else (monitor.snapshot().error_message or "capture is not running"), + mock=started is not None and started.mode is p.CaptureMode.MOCK, + session_id=started.session_id if started is not None else None, + requested=frozenset(requested), + tracking_fresh=tracking is not None and now - tracking.received_monotonic <= _FRESH_SECONDS, + devices=tuple( + DeviceFact( + kind=device.type, + label=device.description or device.id, + connected=device.status is p.DeviceState.CONNECTED, + detail=device.error or device.status.name.lower(), + ) + for device in (status.devices if status is not None else ()) + # A device switched off by configuration is not part of this station. + if device.status is not p.DeviceState.DISABLED + ), + cameras=cameras, + livekit_cameras=frozenset(stream.name for stream in livekit), + livekit_blocked=unrecordable_reason(started, config.capture_server_url) if livekit else None, + glove_plugin_requested=gloves, + glove_plugin_error=_glove_plugin_error(status) if gloves else None, + ) + + +def _glove_plugin_error(status: p.StatusSnapshot | None) -> str | None: + """Why the glove plugin is not available, or None when it is.""" + providers = [provider for provider in (status.providers if status is not None else ()) if provider.plugin] + if not providers: + return "not reported by the capture session" + provider = providers[0] + if provider.status is p.ProviderState.AVAILABLE: + return None + return provider.error or f"plugin is {provider.status.name.lower()}" + + +@dataclass(frozen=True) +class ConnectionTest: + """One run of the device connection test, and what it was run against.""" + + ran_at: float + station: str + session_id: str | None + items: tuple[CheckItem, ...] + + @property + def passed(self) -> bool: + """Whether no item failed.""" + return all(item.status != FAIL for item in self.items) + + def to_json(self) -> dict[str, Any]: + """The wire form.""" + return { + "ran_at": self.ran_at, + "station": self.station, + "passed": self.passed, + "items": [item.to_json() for item in self.items], + } + + +def _step(step_id: str, label: str, status: str, detail: str | None = None) -> dict[str, Any]: + """One step of the flow in its wire form.""" + return {"id": step_id, "label": label, "status": status, "detail": detail} + + +class SetupService: + """The start-of-day state for the station in use, and the gate recording asks.""" + + def __init__( + self, + *, + facts: Callable[[], CaptureFacts], + session_id: Callable[[], str | None], + stations: StationService, + calibration_dir: Callable[[], Path], + output_root: Path, + free_bytes: Callable[[Path], int] = lambda path: shutil.disk_usage(path).free, + clock: Callable[[], float] = time.time, + monotonic: Callable[[], float] = time.monotonic, + ) -> None: + """``facts`` reads the capture session now and ``session_id`` only its identity, which is all the gate + needs most of the time; ``calibration_dir`` is read each time, since the directory is an environment + setting a relaunch may change.""" + self._facts = facts + self._session_id = session_id + self._stations = stations + self._calibration_dir = calibration_dir + self._output_root = output_root + self._free_bytes = free_bytes + self._clock = clock + self._monotonic = monotonic + self._test: ConnectionTest | None = None + self._system_cache: tuple[float, str, list[CheckItem]] | None = None + + def _roles(self) -> dict[str, str | None] | None: + """The camera each role of the station in use is filled by, or None with no station in use.""" + selected = self._stations.registry.selected + return dict(selected.camera_roles) if selected is not None else None + + def run_connection_test(self) -> ConnectionTest: + """Test every device the station needs now, and keep the result for the gate.""" + facts = self._facts() + self._test = ConnectionTest( + ran_at=self._clock(), + station=self._stations.label(), + session_id=facts.session_id, + items=tuple(connection_items(facts, self._roles())), + ) + return self._test + + def current_test(self) -> ConnectionTest | None: + """The last test, while it still describes this station and this capture session; else None.""" + test = self._test + # A different station or a restarted capture session has devices this result never looked at. + if test is None or test.station != self._stations.label() or test.session_id != self._session_id(): + return None + return test + + def system(self) -> list[CheckItem]: + """The system checks, served from a short cache: they read the disk and the gate asks constantly.""" + now, station = self._monotonic(), self._stations.label() + cached = self._system_cache + if cached is not None and cached[1] == station and now - cached[0] < _SYSTEM_CACHE_SECONDS: + return cached[2] + selected = self._stations.registry.selected + items = system_items( + self._facts(), + self._roles(), + selected.camera_type if selected is not None else None, + calibration_dir=self._calibration_dir(), + output_root=self._output_root, + free_bytes=self._free_bytes, + ) + self._system_cache = (now, station, items) + return items + + def block_reason(self) -> str | None: + """Why station setup does not allow a take now, or None when it does.""" + blocked = self._stations.block_reason() + if blocked is not None: + return blocked + # With no station in use the flow is advisory: the configuration-free default records as before. + if self._stations.registry.selected is None: + return None + test = self.current_test() + if test is None: + return "run the device connection test before recording" + failure = first_failure(list(test.items)) + if failure is not None: + return f"the device connection test failed: {failure}" + return first_failure(self.system()) + + def status(self, *, saved_count: int, headset_address_changed: bool) -> dict[str, Any]: + """The flow's steps, the last test and the system checks, for the page.""" + test = self.current_test() + system = self.system() + by_id = {item.id: item for item in system} + return { + "steps": [ + self._station_step(headset_address_changed), + self._devices_step(test, [by_id["disk"], by_id["producer"]]), + self._calibration_step([by_id["calibration"], by_id["gloves"]]), + _step( + "record", + "Record", + DONE if saved_count > 0 else TODO, + f"{saved_count} saved" if saved_count else None, + ), + _step("wrap_up", "Wrap up", TODO), + ], + "connection_test": test.to_json() if test is not None else None, + "system": [item.to_json() for item in system], + "blocked_reason": self.block_reason(), + # Whether the flow gates recording, or only advises (no station in use). + "enforced": self._stations.registry.selected is not None, + } + + def _station_step(self, headset_address_changed: bool) -> dict[str, Any]: + """Station: skipped with no stations set up, done once the station in use can record.""" + registry = self._stations.registry + if not registry.stations: + return _step("station", "Station", SKIPPED, "no stations set up") + blocked = self._stations.block_reason() + if blocked is not None: + return _step("station", "Station", TODO if registry.selected is None else ATTENTION, blocked) + # Advisory: the headset cannot reach a host whose address changed, but that is not for the gate to judge. + if headset_address_changed: + return _step("station", "Station", ATTENTION, "this host's address changed; update the headset") + return _step("station", "Station", DONE, self._stations.label()) + + @staticmethod + def _devices_step(test: ConnectionTest | None, system: list[CheckItem]) -> dict[str, Any]: + """Devices: the connection test, then the disk and the camera producer.""" + if test is None: + return _step("devices", "Devices", TODO, "run the connection test") + failure = first_failure(list(test.items)) or first_failure(system) + if failure is not None: + return _step("devices", "Devices", ATTENTION, failure) + return _step("devices", "Devices", DONE, "connection test passed") + + @staticmethod + def _calibration_step(items: list[CheckItem]) -> dict[str, Any]: + """Calibration: the camera calibration files and the glove plugin; skipped when neither applies.""" + failure = first_failure(items) + if failure is not None: + return _step("calibration", "Calibration", ATTENTION, failure) + if all(item.status == SKIP for item in items): + return _step("calibration", "Calibration", SKIPPED, items[0].detail) + return _step("calibration", "Calibration", DONE) diff --git a/examples/egocap/tests/backend/test_setup_checks.py b/examples/egocap/tests/backend/test_setup_checks.py new file mode 100644 index 0000000000..3bb76b8152 --- /dev/null +++ b/examples/egocap/tests/backend/test_setup_checks.py @@ -0,0 +1,235 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The device connection test and the system checks: what passes, what fails with which reason, what is skipped.""" + +from __future__ import annotations + +import pytest + +from egocap_web.setup_checks import ( + FAIL, + PASS, + SKIP, + CameraFact, + CaptureFacts, + CheckItem, + DeviceFact, + connection_items, + first_failure, + system_items, +) + +HEADSET = DeviceFact("headset", "Headset", True) +LEFT = DeviceFact("controller", "Left controller", True) +RIGHT = DeviceFact("controller", "Right controller", True) +ROLES = {"ego": "cam_head", "wrist_left": "cam_left", "wrist_right": None} + + +def _facts(**overrides) -> CaptureFacts: + base = dict( + running=True, + session_id="s1", + requested=frozenset({"headset", "controller"}), + tracking_fresh=True, + devices=(HEADSET, LEFT, RIGHT), + cameras={"cam_head": CameraFact(True, True), "cam_left": CameraFact(True, True)}, + ) + return CaptureFacts(**{**base, **overrides}) + + +def _by_id(items: list[CheckItem]) -> dict[str, tuple[str, str | None]]: + return {item.id: (item.status, item.detail) for item in items} + + +def test_every_device_the_station_needs_passes_and_an_unused_wrist_is_skipped(): + items = connection_items(_facts(), ROLES) + assert [(item.group, item.label, item.status) for item in items] == [ + ("tracking", "Headset", PASS), + ("tracking", "Left controller", PASS), + ("tracking", "Right controller", PASS), + ("cameras", "Ego (head): cam_head", PASS), + ("cameras", "Left wrist: cam_left", PASS), + ("cameras", "Right wrist", SKIP), + ] + assert items[-1].detail == "not used by this station" + assert first_failure(items) is None + + +def test_a_stopped_capture_session_is_the_one_failure(): + stopped = connection_items(_facts(running=False, error="connection refused"), ROLES) + assert _by_id(stopped) == {"capture": (FAIL, "connection refused")} + assert _by_id(connection_items(CaptureFacts(), None)) == {"capture": (FAIL, "capture is not running")} + + +def test_a_disconnected_device_fails_with_its_own_reason(): + devices = ( + HEADSET, + DeviceFact("controller", "Left controller", False, "battery empty"), + DeviceFact("hand", "Left hand", False), + ) + items = _by_id(connection_items(_facts(devices=devices), ROLES)) + assert items["device:controller:1"] == (FAIL, "battery empty") + assert items["device:hand:2"] == (FAIL, "not connected") + assert first_failure(connection_items(_facts(devices=devices), ROLES)) == "Left controller: battery empty" + + +def test_a_requested_kind_the_session_never_reports_fails(): + facts = _facts(requested=frozenset({"headset", "controller", "hand"}), devices=(HEADSET,)) + items = _by_id(connection_items(facts, ROLES)) + assert items["device:controller"] == (FAIL, "not reported by the capture session") + assert items["device:hand"] == (FAIL, "not reported by the capture session") + assert "device:headset" not in items + + +def test_connected_devices_that_deliver_nothing_fail(): + items = _by_id(connection_items(_facts(tracking_fresh=False), ROLES)) + assert items["tracking:samples"] == (FAIL, "no recent sample") + # A cameras-only deployment has no tracking to be late. + assert "tracking:samples" not in _by_id( + connection_items(_facts(tracking_fresh=False, devices=(), requested=frozenset()), ROLES) + ) + + +@pytest.mark.parametrize( + ("camera", "detail"), + [ + (None, "camera 'cam_left' is not offered by the capture session"), + (CameraFact(False, False, "unplugged"), "unplugged"), + (CameraFact(False, True), "not connected"), + (CameraFact(True, False), "no recent frame"), + ], +) +def test_a_station_camera_fails_with_the_specific_reason(camera, detail): + cameras = {"cam_head": CameraFact(True, True)} + if camera is not None: + cameras["cam_left"] = camera + assert _by_id(connection_items(_facts(cameras=cameras), ROLES))["camera:wrist_left"] == (FAIL, detail) + + +def test_a_livekit_camera_passes_when_offered_and_fails_with_why_it_cannot_be_recorded(): + facts = _facts(cameras={}, livekit_cameras=frozenset({"cam_head", "cam_left"})) + assert _by_id(connection_items(facts, ROLES))["camera:ego"] == (PASS, None) + blocked = _facts( + cameras=None, livekit_cameras=frozenset({"cam_head", "cam_left"}), livekit_blocked="no capture time" + ) + assert _by_id(connection_items(blocked, ROLES))["camera:ego"] == (FAIL, "no capture time") + + +def test_without_a_station_every_offered_camera_is_tested_by_name(): + facts = _facts(livekit_cameras=frozenset({"lk_cam"})) + items = connection_items(facts, None) + assert [item.id for item in items if item.group == "cameras"] == [ + "camera:cam_head", + "camera:cam_left", + "camera:lk_cam", + ] + assert all(item.status == PASS for item in items) + + +def _system(tmp_path, facts=None, roles=ROLES, camera_type=None, free=50 * 1024**3): + def free_bytes(path): + if isinstance(free, OSError): + raise free + return free + + return _by_id( + system_items( + facts or _facts(), + roles, + camera_type, + calibration_dir=tmp_path / "calibration", + output_root=tmp_path / "recordings", + free_bytes=free_bytes, + ) + ) + + +def _calibrate(tmp_path, *names: str) -> None: + (tmp_path / "calibration").mkdir(exist_ok=True) + for name in names: + (tmp_path / "calibration" / name).write_text("{}") + + +def test_calibration_needs_the_files_of_the_roles_in_use(tmp_path): + assert _system(tmp_path)["calibration"] == ( + FAIL, + "missing: head_camera_intrinsics.json, head_camera_extrinsics.json, " + "left_wrist_camera_intrinsics.json, wrist_calibration_offsets.json", + ) + _calibrate( + tmp_path, "head_camera_intrinsics.json", "head_camera_extrinsics.json", "left_wrist_camera_intrinsics.json" + ) + assert _system(tmp_path)["calibration"] == (FAIL, "missing: wrist_calibration_offsets.json") + _calibrate(tmp_path, "wrist_calibration_offsets.json") + assert _system(tmp_path)["calibration"] == (PASS, None) + # A station with only the right wrist needs that wrist's file, not the left's. + right_only = {"ego": None, "wrist_left": None, "wrist_right": "cam_right"} + assert _system(tmp_path, roles=right_only)["calibration"] == ( + FAIL, + "missing: right_wrist_camera_intrinsics.json", + ) + + +def test_a_station_without_wrist_cameras_needs_no_wrist_calibration(tmp_path): + _calibrate(tmp_path, "head_camera_intrinsics.json", "head_camera_extrinsics.json") + assert _system(tmp_path, roles={"ego": "cam_head", "wrist_left": None, "wrist_right": None})[ + "calibration" + ] == (PASS, None) + + +@pytest.mark.parametrize( + ("facts", "roles", "detail"), + [ + (_facts(mock=True), ROLES, "mock capture has nothing to calibrate"), + (_facts(), None, "no station in use"), + (_facts(), {"ego": None, "wrist_left": None, "wrist_right": None}, "the station has no cameras assigned"), + ], +) +def test_calibration_is_skipped_where_it_does_not_apply(tmp_path, facts, roles, detail): + assert _system(tmp_path, facts=facts, roles=roles)["calibration"] == (SKIP, detail) + + +def test_the_glove_plugin_is_checked_only_where_gloves_are_used(tmp_path): + assert _system(tmp_path)["gloves"] == (SKIP, "gloves are not part of this deployment") + assert _system(tmp_path, facts=_facts(glove_plugin_requested=True, mock=True))["gloves"] == ( + SKIP, + "mock capture needs no glove software", + ) + assert _system(tmp_path, facts=_facts(glove_plugin_requested=True))["gloves"] == (PASS, None) + unlicensed = _facts(glove_plugin_requested=True, glove_plugin_error="licence dongle not found") + assert _system(tmp_path, facts=unlicensed)["gloves"] == (FAIL, "licence dongle not found") + + +def test_disk_space_must_leave_room_for_takes(tmp_path): + assert _system(tmp_path)["disk"] == (PASS, "50.0 GB free") + assert _system(tmp_path, free=3 * 1024**3)["disk"] == (FAIL, "3.0 GB free; 10 GB needed") + assert _system(tmp_path, free=OSError(2, "No such file or directory"))["disk"] == ( + FAIL, + "cannot read the recording output: No such file or directory", + ) + + +def test_the_camera_producer_is_checked_only_for_cameras_that_arrive_over_livekit(tmp_path): + assert _system(tmp_path)["producer"] == (SKIP, "cameras are read by CaptureServer") + assert _system(tmp_path, camera_type="sensing_gmsl")["producer"] == ( + FAIL, + "no camera stream is offered by the producer", + ) + offered = _facts(livekit_cameras=frozenset({"cam_head"})) + assert _system(tmp_path, facts=offered, camera_type="sensing_gmsl")["producer"] == (PASS, None) + blocked = _facts( + livekit_cameras=frozenset({"cam_head"}), livekit_blocked="CaptureServer is not on this machine" + ) + assert _system(tmp_path, facts=blocked)["producer"] == (FAIL, "CaptureServer is not on this machine") + + +def test_the_first_failure_reads_as_one_phrase(): + items = [ + CheckItem("a", "system", "Disk", PASS), + CheckItem("b", "system", "Gloves", FAIL), + CheckItem("c", "system", "Cam", FAIL, "x"), + ] + assert first_failure(items) == "Gloves" + assert items[2].to_json() == {"id": "c", "group": "system", "label": "Cam", "status": "fail", "detail": "x"} diff --git a/examples/egocap/tests/backend/test_setup_routes.py b/examples/egocap/tests/backend/test_setup_routes.py new file mode 100644 index 0000000000..76f3418e91 --- /dev/null +++ b/examples/egocap/tests/backend/test_setup_routes.py @@ -0,0 +1,199 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Start-of-day routes: reading the flow, running the connection test, and the real application end to end.""" + +from __future__ import annotations + +from dataclasses import dataclass +from types import SimpleNamespace + +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from egocap_web import setup_routes +from egocap_web.app import app as real_app +from egocap_web.host_addresses import HostAddress +from egocap_web.setup_checks import CameraFact, CaptureFacts, DeviceFact +from egocap_web.setup_service import SetupService +from egocap_web.station_routes import router as station_router +from egocap_web.station_service import StationService, session_adapter +from egocap_web.stations import StationStore +from tests.backend.test_preview_routes import _poll_until_sync, _ServerThread + +TOKEN = "t" * 43 +AUTH = {"X-Control-Token": TOKEN} + + +@dataclass +class _Context: + control_token: str + saved_count: int = 0 + + +async def _rotate() -> None: + """Nothing to rotate in these tests.""" + + +def _client(tmp_path, ready: bool = True) -> TestClient: + small = FastAPI() + small.include_router(setup_routes.router) + small.include_router(station_router) + if not ready: + return TestClient(small) + facts = CaptureFacts( + running=True, + mock=True, + session_id="s1", + requested=frozenset({"headset"}), + tracking_fresh=True, + devices=(DeviceFact("headset", "Headset", True),), + cameras={"cam_head": CameraFact(True, True)}, + ) + stations = StationService( + StationStore(tmp_path / "stations.json"), + session_adapter( + offered_cameras=lambda: frozenset({"cam_head"}), + change_blocked=lambda: None, + show_label=lambda label: None, + rotate_batch=_rotate, + leave_station=lambda label: None, + ), + "Deployment", + ) + small.state.station_service = stations + small.state.station_activity = object() + small.state.setup_service = SetupService( + facts=lambda: facts, + session_id=lambda: "s1", + stations=stations, + calibration_dir=lambda: tmp_path / "calibration", + output_root=tmp_path, + free_bytes=lambda path: 50 * 1024**3, + ) + small.state.recording_context = _Context(control_token=TOKEN) + small.state.settings = SimpleNamespace(capture=SimpleNamespace(capture_server_url="ws://127.0.0.1:8082")) + return TestClient(small) + + +def _steps(body: dict) -> dict[str, tuple[str, str | None]]: + return {step["id"]: (step["status"], step["detail"]) for step in body["steps"]} + + +def test_the_routes_answer_503_until_the_application_has_started(tmp_path): + client = _client(tmp_path, ready=False) + for response in (client.get("/api/setup"), client.post("/api/setup/connection-test")): + assert response.status_code == 503 and response.headers["cache-control"] == "no-store" + + +def test_the_flow_is_read_openly_and_the_test_is_run_with_the_token(tmp_path): + client = _client(tmp_path) + bench = client.post( + "/api/stations", json={"name": "Bench A", "camera_roles": {"ego": "cam_head"}}, headers=AUTH + ) + client.post("/api/stations/select", json={"id": bench.json()["stations"][0]["id"]}, headers=AUTH) + before = client.get("/api/setup").json() + assert before["enforced"] is True and before["connection_test"] is None + assert before["blocked_reason"] == "run the device connection test before recording" + assert _steps(before)["devices"] == ("todo", "run the connection test") + assert client.post("/api/setup/connection-test").status_code == 403 + assert client.post("/api/setup/connection-test", headers={"X-Control-Token": "wrong"}).status_code == 403 + assert client.get("/api/setup").json()["connection_test"] is None + after = client.post("/api/setup/connection-test", headers=AUTH).json() + assert after["blocked_reason"] is None and after["connection_test"]["passed"] is True + assert [(item["label"], item["status"]) for item in after["connection_test"]["items"]] == [ + ("Headset", "pass"), + ("Ego (head): cam_head", "pass"), + ("Left wrist", "skip"), + ("Right wrist", "skip"), + ] + assert _steps(after) == { + "station": ("done", "Bench A"), + "devices": ("done", "connection test passed"), + "calibration": ("skipped", "mock capture has nothing to calibrate"), + "record": ("todo", None), + "wrap_up": ("todo", None), + } + client.app.state.recording_context.saved_count = 2 + assert _steps(client.get("/api/setup").json())["record"] == ("done", "2 saved") + + +def test_a_changed_host_address_shows_on_the_station_step(tmp_path, monkeypatch): + client = _client(tmp_path) + calls: list[str] = [] + + def candidates(url: str) -> list[HostAddress]: + calls.append(url) + return [HostAddress("10.0.0.42", "wlp2s0", "wireless")] + + monkeypatch.setattr(setup_routes, "headset_addresses", candidates) + fields = {"name": "Bench A", "camera_roles": {"ego": "cam_head"}} + bench = client.post("/api/stations", json=fields, headers=AUTH).json()["stations"][0]["id"] + client.post("/api/stations/select", json={"id": bench}, headers=AUTH) + assert _steps(client.get("/api/setup").json())["station"] == ("done", "Bench A") + assert calls == [] # nothing saved, so the interfaces are not even listed + client.put(f"/api/stations/{bench}", json={"headset_address": "10.0.0.7"}, headers=AUTH) + assert _steps(client.get("/api/setup").json())["station"] == ( + "attention", + "this host's address changed; update the headset", + ) + client.put(f"/api/stations/{bench}", json={"headset_address": "10.0.0.42"}, headers=AUTH) + assert _steps(client.get("/api/setup").json())["station"] == ("done", "Bench A") + assert calls == ["ws://127.0.0.1:8082"] * 2 + + +def test_a_station_with_a_missing_device_cannot_record_and_says_why(monkeypatch, unused_tcp_port, tmp_path): + """The real application against the real CaptureServer in its mock mode.""" + from egocap_web import app as app_module + + station_file = tmp_path / "station.yaml" + station_file.write_text("video_sources:\n- type: oak_camera\n name: head_human_camera\n", encoding="utf-8") + monkeypatch.setenv("EGOCAP_STATION_CONFIG", str(station_file)) + monkeypatch.setenv("EGOCAP_CAPTURE_SERVER_URL", f"ws://127.0.0.1:{unused_tcp_port}") + monkeypatch.delenv("EGOCAP_OPERATOR_SETTINGS_FILE", raising=False) + monkeypatch.setattr(app_module, "_recording_output_root", lambda data_dir: tmp_path) + server = _ServerThread(unused_tcp_port) + try: + with TestClient(real_app) as client: + context = client.app.state.recording_context + auth = {"X-Control-Token": context.control_token} + monitor = client.app.state.monitor + _poll_until_sync( + lambda: monitor.snapshot().running and monitor.preview.camera("head_human_camera") is not None + ) + context.coordinator.set_task("Pour water.") + + def add(name: str, ego: str) -> str: + fields = {"name": name, "camera_roles": {"ego": ego}} + listing = client.post("/api/stations", json=fields, headers=auth).json() + return listing["stations"][-1]["id"] + + bench, cart = add("Bench A", "head_human_camera"), add("Cart B", "cart_top_camera") + + # A station whose camera the session does not offer never reaches the recording step. + client.post("/api/stations/select", json={"id": cart}, headers=auth) + missing = ( + "station 'Cart B': camera 'cart_top_camera' (ego (head)) is not offered by the capture session" + ) + assert context.snapshot()["not_ready_reason"] == missing + failed = client.post("/api/setup/connection-test", headers=auth).json() + assert failed["connection_test"]["passed"] is False and failed["blocked_reason"] == missing + ego = next(item for item in failed["connection_test"]["items"] if item["id"] == "camera:ego") + assert (ego["status"], ego["detail"]) == ( + "fail", + "camera 'cart_top_camera' is not offered by the capture session", + ) + assert _steps(failed)["station"] == ("attention", missing) + + # The station whose devices are all present passes the test and may record. + client.post("/api/stations/select", json={"id": bench}, headers=auth) + assert context.snapshot()["not_ready_reason"] == "run the device connection test before recording" + passed = client.post("/api/setup/connection-test", headers=auth).json() + assert passed["connection_test"]["passed"] is True, passed["connection_test"]["items"] + assert passed["blocked_reason"] is None + assert _steps(passed)["devices"] == ("done", "connection test passed") + assert _steps(passed)["calibration"][0] == "skipped" # mock capture has nothing to calibrate + _poll_until_sync(lambda: context.snapshot()["ready_to_record"] is True) + finally: + server.stop() diff --git a/examples/egocap/tests/backend/test_setup_service.py b/examples/egocap/tests/backend/test_setup_service.py new file mode 100644 index 0000000000..7dcf4c4dfa --- /dev/null +++ b/examples/egocap/tests/backend/test_setup_service.py @@ -0,0 +1,367 @@ +# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""The start-of-day service: the facts it reads, the steps it reports, and the gate recording asks.""" + +from __future__ import annotations + +import time +from types import SimpleNamespace + +from capture_server import protocol as p +from egocap_web.config import CaptureStatusConfig +from egocap_web.setup_checks import CameraFact, CaptureFacts, DeviceFact +from egocap_web.setup_service import SetupService, capture_facts +from egocap_web.station_service import StationService, session_adapter +from egocap_web.stations import StationStore + +BENCH = {"name": "Bench A", "camera_roles": {"ego": "cam_head", "wrist_left": "cam_left"}} +CALIBRATION = ( + "head_camera_intrinsics.json", + "head_camera_extrinsics.json", + "left_wrist_camera_intrinsics.json", + "wrist_calibration_offsets.json", +) + + +def _healthy(**overrides) -> CaptureFacts: + base = dict( + running=True, + session_id="s1", + requested=frozenset({"headset"}), + tracking_fresh=True, + devices=(DeviceFact("headset", "Headset", True),), + cameras={"cam_head": CameraFact(True, True), "cam_left": CameraFact(True, True)}, + ) + return CaptureFacts(**{**base, **overrides}) + + +class _World: + """The capture facts, clocks and disk a test can change between calls.""" + + def __init__(self, tmp_path): + self.facts = _healthy() + self.now = 1_000.0 + self.free = 50 * 1024**3 + self.fact_reads = 0 + self.tmp_path = tmp_path + + def read_facts(self) -> CaptureFacts: + self.fact_reads += 1 + return self.facts + + +async def _rotate() -> None: + """Nothing to rotate in these tests.""" + + +def _service(tmp_path) -> tuple[SetupService, StationService, _World]: + world = _World(tmp_path) + stations = StationService( + StationStore(tmp_path / "stations.json"), + session_adapter( + offered_cameras=lambda: frozenset({"cam_head", "cam_left"}), + change_blocked=lambda: None, + show_label=lambda label: None, + rotate_batch=_rotate, + leave_station=lambda label: None, + ), + "Deployment", + ) + setup = SetupService( + facts=world.read_facts, + session_id=lambda: world.facts.session_id, + stations=stations, + calibration_dir=lambda: tmp_path / "calibration", + output_root=tmp_path / "recordings", + free_bytes=lambda path: world.free, + clock=lambda: world.now, + monotonic=lambda: world.now, + ) + return setup, stations, world + + +async def _with_station_in_use(tmp_path, calibrated: bool = True): + setup, stations, world = _service(tmp_path) + await stations.select((await stations.add(BENCH)).station_id) + if calibrated: + (tmp_path / "calibration").mkdir() + for name in CALIBRATION: + (tmp_path / "calibration" / name).write_text("{}") + return setup, stations, world + + +def _steps( + setup: SetupService, saved_count: int = 0, headset_address_changed: bool = False +) -> dict[str, tuple[str, str | None]]: + status = setup.status(saved_count=saved_count, headset_address_changed=headset_address_changed) + return {step["id"]: (step["status"], step["detail"]) for step in status["steps"]} + + +async def test_with_no_stations_the_flow_advises_and_never_blocks(tmp_path): + setup, _, world = _service(tmp_path) + assert setup.block_reason() is None + status = setup.status(saved_count=0, headset_address_changed=False) + assert status["enforced"] is False and status["blocked_reason"] is None and status["connection_test"] is None + assert [(step["id"], step["label"], step["status"]) for step in status["steps"]] == [ + ("station", "Station", "skipped"), + ("devices", "Devices", "todo"), + ("calibration", "Calibration", "skipped"), + ("record", "Record", "todo"), + ("wrap_up", "Wrap up", "todo"), + ] + # The test can still be run: it then tests every camera the session offers. + test = setup.run_connection_test() + assert test.passed and (test.station, test.ran_at) == ("Deployment", 1_000.0) + assert _steps(setup)["devices"] == ("done", "connection test passed") + assert setup.block_reason() is None + + +async def test_a_station_in_use_cannot_record_until_the_connection_test_has_passed(tmp_path): + setup, _, world = await _with_station_in_use(tmp_path) + assert setup.block_reason() == "run the device connection test before recording" + assert _steps(setup) == { + "station": ("done", "Bench A"), + "devices": ("todo", "run the connection test"), + "calibration": ("done", None), + "record": ("todo", None), + "wrap_up": ("todo", None), + } + world.facts = _healthy( + cameras={"cam_head": CameraFact(True, True), "cam_left": CameraFact(False, False, "unplugged")} + ) + failed = setup.run_connection_test() + assert not failed.passed + assert setup.block_reason() == "the device connection test failed: Left wrist: cam_left: unplugged" + assert _steps(setup)["devices"] == ("attention", "Left wrist: cam_left: unplugged") + world.facts = _healthy() + assert setup.run_connection_test().passed + assert setup.block_reason() is None + status = setup.status(saved_count=3, headset_address_changed=False) + assert status["enforced"] is True and status["blocked_reason"] is None + assert status["connection_test"]["passed"] is True and status["connection_test"]["station"] == "Bench A" + assert [item["status"] for item in status["connection_test"]["items"]] == ["pass", "pass", "pass", "skip"] + assert _steps(setup, saved_count=3)["record"] == ("done", "3 saved") + + +async def test_a_passed_test_does_not_carry_to_another_station_or_capture_session(tmp_path): + setup, stations, world = await _with_station_in_use(tmp_path) + setup.run_connection_test() + assert setup.block_reason() is None + world.facts = _healthy(session_id="s2") # CaptureServer restarted: these devices were never looked at + assert setup.current_test() is None + assert setup.block_reason() == "run the device connection test before recording" + setup.run_connection_test() + cart = await stations.add({"name": "Cart B", "camera_roles": {"ego": "cam_head"}}) + await stations.select(cart.station_id) + assert setup.block_reason() == "run the device connection test before recording" + assert _steps(setup)["devices"] == ("todo", "run the connection test") + + +async def test_missing_calibration_blocks_a_take_and_shows_on_its_step(tmp_path): + setup, _, world = await _with_station_in_use(tmp_path, calibrated=False) + setup.run_connection_test() + missing = "Camera calibration: missing: " + ", ".join(CALIBRATION) + assert setup.block_reason() == missing + assert _steps(setup)["calibration"] == ("attention", missing) + status = setup.status(saved_count=0, headset_address_changed=False) + assert status["blocked_reason"] == missing + assert {item["id"]: item["status"] for item in status["system"]} == { + "calibration": "fail", + "gloves": "skip", + "disk": "pass", + "producer": "skip", + } + + +async def test_low_disk_space_blocks_a_take_and_shows_on_the_devices_step(tmp_path): + setup, _, world = await _with_station_in_use(tmp_path) + setup.run_connection_test() + world.free = 1024**3 + world.now += 5 # past the cache + assert setup.block_reason() == "Free disk space: 1.0 GB free; 10 GB needed" + assert _steps(setup)["devices"] == ("attention", "Free disk space: 1.0 GB free; 10 GB needed") + + +async def test_the_system_checks_are_cached_briefly_because_the_gate_is_asked_constantly(tmp_path): + setup, _, world = await _with_station_in_use(tmp_path) + setup.run_connection_test() + reads = world.fact_reads + for _ in range(50): + assert setup.block_reason() is None + assert world.fact_reads == reads + 1 # one read filled the cache; the other forty-nine reused it + world.free = 1024**3 + assert setup.block_reason() is None # still the cached answer + world.now += 2.5 + assert setup.block_reason() is not None + + +async def test_the_station_step_follows_the_station_in_use(tmp_path): + setup, stations, world = _service(tmp_path) + bench = await stations.add({"name": "Bench A"}) + assert _steps(setup)["station"] == ("todo", "select a station before recording") + await stations.select(bench.station_id) + assert _steps(setup)["station"] == ( + "attention", + "station 'Bench A': no camera is assigned to the ego (head) role", + ) + await stations.update(bench.station_id, {"camera_roles": {"ego": "cam_head"}}) + assert _steps(setup)["station"] == ("done", "Bench A") + # Advisory only: the gate does not judge the headset's network. + assert _steps(setup, headset_address_changed=True)["station"] == ( + "attention", + "this host's address changed; update the headset", + ) + world.facts = _healthy() + (tmp_path / "calibration").mkdir() + for name in CALIBRATION[:2]: + (tmp_path / "calibration" / name).write_text("{}") + setup.run_connection_test() + world.now += 5 + assert setup.block_reason() is None + + +async def test_calibration_is_skipped_for_a_mock_session(tmp_path): + setup, _, world = await _with_station_in_use(tmp_path, calibrated=False) + world.facts = _healthy(mock=True) + setup.run_connection_test() + assert setup.block_reason() is None + assert _steps(setup)["calibration"] == ("skipped", "mock capture has nothing to calibrate") + + +# --- reading the capture session --------------------------------------------------------------------------------- + + +def _device(kind: str, description: str, state: p.DeviceState, error: str = "") -> p.DeviceStatus: + return p.DeviceStatus( + id=f"device-{description}", + path=f"/{kind}", + type=kind, + description=description, + provider_id="provider", + status=state, + reason=p.StatusReason.NONE, + error=error, + ) + + +def _provider(plugin, state: p.ProviderState, error: str = "") -> p.ProviderStatus: + kind = p.ProviderType.PLUGIN if plugin is not None else p.ProviderType.OPENXR_RUNTIME + return p.ProviderStatus( + id="provider", + type=kind, + plugin=plugin, + name="provider", + status=state, + reason=p.StatusReason.NONE, + error=error, + ) + + +def _livekit(name: str) -> p.LiveKitCameraStream: + return p.LiveKitCameraStream( + stream_id=16, + name=name, + url="wss://lk", + room="r", + publisher="o", + track="t", + timestamp_basis=p.LiveKitTimestampBasis.SENSOR_CAPTURE_MONOTONIC_US, + width=8, + height=4, + fps=30.0, + ) + + +def _monitor( + *, status=None, running=True, started=True, stopped=None, mode=p.CaptureMode.LIVE, streams=(), fresh=() +): + """A stand-in monitor holding exactly the facts ``capture_facts`` reads.""" + now = time.monotonic() + slot = SimpleNamespace(received_monotonic=now) + stale = SimpleNamespace(received_monotonic=now - 60) + return SimpleNamespace( + native=SimpleNamespace( + started=SimpleNamespace(session_id="s1", mode=mode, streams=streams) if started else None, + status=SimpleNamespace(running=running) if started else None, + stopped=stopped, + latest_status=status, + ), + preview=SimpleNamespace( + tracking=lambda: slot if "tracking" in fresh else None, + camera=lambda name: slot if name in fresh else (stale if name == "stale_cam" else None), + ), + snapshot=lambda: SimpleNamespace(error_message="connection refused" if not started else None), + ) + + +def test_capture_facts_read_devices_cameras_and_freshness_from_the_session(): + status = p.StatusSnapshot( + updated_at_ns=1, + providers=(_provider(None, p.ProviderState.AVAILABLE),), + devices=( + _device("headset", "Headset", p.DeviceState.CONNECTED), + _device("controller", "Left controller", p.DeviceState.DISCONNECTED, "battery empty"), + _device("controller", "", p.DeviceState.DEGRADED), + _device("hand", "Left hand", p.DeviceState.DISABLED), + ), + cameras=( + p.CameraStatus("cam_head", 1, p.DeviceState.CONNECTED, p.StatusReason.NONE, ""), + p.CameraStatus("stale_cam", 2, p.DeviceState.CONNECTED, p.StatusReason.NONE, ""), + p.CameraStatus("cam_left", 3, p.DeviceState.FAILED, p.StatusReason.NONE, "unplugged"), + ), + ) + facts = capture_facts(_monitor(status=status, fresh=("tracking", "cam_head")), CaptureStatusConfig()) + assert (facts.running, facts.error, facts.mock, facts.session_id) == (True, None, False, "s1") + assert facts.requested == frozenset({"headset", "controller"}) and facts.tracking_fresh + assert facts.devices == ( + DeviceFact("headset", "Headset", True, "connected"), + DeviceFact("controller", "Left controller", False, "battery empty"), + DeviceFact("controller", "device-", False, "degraded"), + ) + assert facts.cameras == { + "cam_head": CameraFact(True, True, "connected"), + "stale_cam": CameraFact(True, False, "connected"), + "cam_left": CameraFact(False, False, "unplugged"), + } + assert (facts.livekit_cameras, facts.livekit_blocked, facts.glove_plugin_requested) == ( + frozenset(), + None, + False, + ) + + +def test_capture_facts_before_a_session_and_after_it_stopped(): + never = capture_facts(_monitor(started=False), CaptureStatusConfig()) + assert (never.running, never.error, never.session_id, never.devices, never.cameras) == ( + False, + "connection refused", + None, + (), + {}, + ) + stopped = capture_facts(_monitor(stopped=object()), CaptureStatusConfig()) + assert (stopped.running, stopped.error) == (False, "capture is not running") + assert capture_facts(_monitor(mode=p.CaptureMode.MOCK), CaptureStatusConfig()).mock is True + + +def test_capture_facts_report_the_glove_plugin_and_livekit_cameras(): + config = CaptureStatusConfig(plugins=(p.PluginType.MANUS,), capture_server_url="ws://127.0.0.1:8082") + + def glove_error(*providers) -> str | None: + status = p.StatusSnapshot(updated_at_ns=1, providers=providers) + return capture_facts(_monitor(status=status), config).glove_plugin_error + + assert glove_error(_provider(p.PluginType.MANUS, p.ProviderState.AVAILABLE)) is None + assert glove_error(_provider(p.PluginType.MANUS, p.ProviderState.FAILED, "licence dongle not found")) == ( + "licence dongle not found" + ) + assert glove_error(_provider(p.PluginType.MANUS, p.ProviderState.INITIALIZING)) == "plugin is initializing" + assert glove_error(_provider(None, p.ProviderState.AVAILABLE)) == "not reported by the capture session" + assert capture_facts(_monitor(), config).glove_plugin_error == "not reported by the capture session" + facts = capture_facts(_monitor(streams=(_livekit("lk_head"),)), config) + assert "hand" in facts.requested and facts.glove_plugin_requested + assert (facts.livekit_cameras, facts.livekit_blocked) == (frozenset({"lk_head"}), None) + remote = CaptureStatusConfig(capture_server_url="ws://192.168.1.50:8082") + assert capture_facts(_monitor(streams=(_livekit("lk_head"),)), remote).livekit_blocked is not None diff --git a/examples/egocap/tests/backend/test_station_routes.py b/examples/egocap/tests/backend/test_station_routes.py index c819c06692..6158b979ee 100644 --- a/examples/egocap/tests/backend/test_station_routes.py +++ b/examples/egocap/tests/backend/test_station_routes.py @@ -306,8 +306,10 @@ def test_the_real_application_gates_recording_on_the_station_in_use(monkeypatch, # The label every viewer sees, and the one the next recording session will carry, changed in process. assert client.get("/api/capture-status").json()["station_label"] == "Bench A" assert client.app.state.station_service.label() == "Bench A" - # Capture never connected here, so what the session offers is unknown and the station itself is fine. - assert context.setup_block() is None + # Capture never connected here, so what the session offers is unknown and the station itself is fine; + # what remains is the next step of the flow. + assert client.app.state.station_service.block_reason() is None + assert context.setup_block() == "run the device connection test before recording" client.put(f"/api/stations/{bench}", json={"camera_roles": {"ego": None}}, headers=auth) assert context.snapshot()["not_ready_reason"] == ( "station 'Bench A': no camera is assigned to the ego (head) role" From 583bb9c1df9c5fdb1749b5e0a8eed43a4880efd6 Mon Sep 17 00:00:00 2001 From: Shawn Hwang Date: Mon, 16 Nov 2026 11:09:54 -0800 Subject: [PATCH 04/13] feat(egocap): start-of-day rail and device connection test dialog A rail under the header shows the start-of-day flow, and a dialog runs the device connection test and lists the calibration and system checks. - Rail: Station, Devices, Calibration, Record and Wrap up, each done, needing attention, to do, or not needed for this station, with a short reason. The step to deal with next is highlighted, and each step opens the place it is dealt with. - Checks dialog: runs the connection test with the control token and lists each device and camera as passed, failed with the reason, or not needed, followed by the system checks and whether recording is held. It opens over the live page, so cameras stay visible while a device is fixed. - Settings opens on the tab that was asked for, and while any dialog is open the page behind it is inert and recording shortcuts are suspended. Co-Authored-By: Claude Fable 5.2 Signed-off-by: Shawn Hwang --- examples/egocap/backend/README.md | 18 ++ examples/egocap/frontend/README.md | 10 + .../frontend/src/App.operatorLayout.test.tsx | 55 +++++ examples/egocap/frontend/src/App.tsx | 51 +++- .../egocap/frontend/src/SettingsPanel.tsx | 52 +---- .../egocap/frontend/src/SetupDialog.test.tsx | 133 +++++++++++ examples/egocap/frontend/src/SetupDialog.tsx | 165 +++++++++++++ .../egocap/frontend/src/StepRail.test.tsx | 72 ++++++ examples/egocap/frontend/src/StepRail.tsx | 78 +++++++ .../egocap/frontend/src/settingsParts.tsx | 54 ++++- examples/egocap/frontend/src/setupApi.test.ts | 45 ++++ examples/egocap/frontend/src/setupApi.ts | 89 +++++++ .../egocap/frontend/src/setupTestDoubles.ts | 45 ++++ examples/egocap/frontend/src/styles.css | 218 ++++++++++++++++++ examples/egocap/frontend/src/useSetup.test.ts | 55 +++++ examples/egocap/frontend/src/useSetup.ts | 38 +++ 16 files changed, 1119 insertions(+), 59 deletions(-) create mode 100644 examples/egocap/frontend/src/SetupDialog.test.tsx create mode 100644 examples/egocap/frontend/src/SetupDialog.tsx create mode 100644 examples/egocap/frontend/src/StepRail.test.tsx create mode 100644 examples/egocap/frontend/src/StepRail.tsx create mode 100644 examples/egocap/frontend/src/setupApi.test.ts create mode 100644 examples/egocap/frontend/src/setupApi.ts create mode 100644 examples/egocap/frontend/src/setupTestDoubles.ts create mode 100644 examples/egocap/frontend/src/useSetup.test.ts create mode 100644 examples/egocap/frontend/src/useSetup.ts diff --git a/examples/egocap/backend/README.md b/examples/egocap/backend/README.md index e07c4b63c2..425bd21573 100644 --- a/examples/egocap/backend/README.md +++ b/examples/egocap/backend/README.md @@ -34,6 +34,7 @@ or restarts it. | `GET`/`POST /api/stations`, `PUT`/`DELETE /api/stations/{id}`, `POST /api/stations/select` | The station registry: the stations an operator chooses between and the one in use. A station is a name, a camera type, the camera filling each role and the capture host address last given to its headset. Kept in `stations.json` beside the operator settings. Every change uses `X-Control-Token` and answers with the new listing; a refusal is a 400 with the specific reason (a duplicate name, a camera in two roles, an unknown field), and an unknown id is 404. The station in use cannot be selected, edited or deleted while a take is being written. A station's headset address is listed only when the `GET` carries the token. See [Stations](#stations). | | `GET /api/headset-address` | The addresses to enter in the headset, wireless first, the one saved for the station in use, and whether that one is stale. Needs `X-Control-Token`. | | `GET`/`POST /api/station-activity` | Today's active and inactive time for the station in use. `POST` (`X-Control-Token`) sets `state` (`active` or `inactive`), the blocker `notes`, or both, and rewrites that station's daily activity log. | +| `GET /api/setup`, `POST /api/setup/connection-test` | The start-of-day flow: each step's state, the last device connection test, the system checks, and `blocked_reason`, why station setup holds a take. `POST` (`X-Control-Token`) tests every device the station in use needs now and answers with the new flow. See [Start-of-day flow](#start-of-day-flow). | | `POST /api/task-files/import`, `DELETE /api/task-files/{name}` | Import a task catalog the operator supplies — by `name` + `content` (text uploaded from the browser) — into the imported-catalog directory beside the operator settings, once it parses; and remove an imported one. `POST` and `DELETE` use the `X-Control-Token` header (legacy JSON tokens remain accepted for `POST`); `DELETE` refuses removal of the selected catalog (409); imports also refuse replacement of that catalog until it is deselected. Imports appear in `GET /api/task-files` (as `imported`) and shadow a shipped catalog of the same name. | | `GET /api/tools` | The operator tools the Settings drawer offers (headset calibration, glove calibration, fisheye rectification for the SENSING cameras), each with whether this build can launch it. None can yet. | | `GET /api/livekit-token?room=ROOM` | Viewer token (subscribe and data messages, no media publishing) for a LiveKit room the session offers (404 otherwise, 503 without signing credentials). Which streams exist comes from CaptureServer's session message. | @@ -70,6 +71,23 @@ A site usually has several stations, and an operator picks the one they are at. restarting the backend is the only way to change that. - **The station in use supplies the camera type and roles** that `GET /api/operator-settings` returns, and a `PUT` of those two fields is saved to it. +### Start-of-day flow + +The flow is station, devices, calibration, record, wrap-up ([`setup_service.py`](egocap_web/setup_service.py), +[`setup_checks.py`](egocap_web/setup_checks.py)). With a station in use it gates recording; with none it only advises. + +- **Device connection test.** Run on request. Every tracking device the capture session reports must be connected and + tracking data must be arriving; each camera the station assigns must be connected and delivering frames, or, for a + LiveKit camera, offered and recordable. A role the station leaves unassigned is skipped. A passed test holds for that + station and that capture session only; changing the station or restarting CaptureServer needs a new run. +- **System checks.** Read continuously and cached for two seconds: the calibration files of the roles in use under + `EGOCAP_CALIBRATION_DIR` (head intrinsics and extrinsics, each wrist's intrinsics, and the wrist offsets once a wrist + is assigned), the glove plugin's state (where a missing SDK or licence shows), at least 10 GB free under the recording + output, and the camera producer for cameras that arrive over LiveKit. Calibration and glove software are skipped for a + mock session. +- **The gate** is asked when a take is admitted and when readiness is published, never while a take records: a setup + fact changing mid-take does not interrupt it, unlike a capture source going stale. + - **Activity.** `station_status/.json` under the recording output holds each station's active and inactive intervals for that day, and `station_status/__activity.json` is the daily log, rewritten on every change. Both are written atomically and stay on this machine. Leaving a station stops its active time. diff --git a/examples/egocap/frontend/README.md b/examples/egocap/frontend/README.md index 964f207b78..d5a924ed41 100644 --- a/examples/egocap/frontend/README.md +++ b/examples/egocap/frontend/README.md @@ -76,6 +76,16 @@ The page is built for an operator mid-take: the cameras fill it, and everything until then it says `SET UP` and what is missing. A command in flight shows at once (`STOPPING` while a take is written), because the backend's own phase only changes when the command finishes. A stale feed shows `NO FEED`, never a retained `REC`. +- **Start-of-day rail (under the header).** Station, Devices, Calibration, Record and Wrap up, each done, needing + attention, still to do, or not needed for this station, with a short reason (`StepRail.tsx`). The first step that is + neither done nor skipped is highlighted. A step opens where it is dealt with: Station opens Settings on its Station tab, + Devices and Calibration open the start-of-day checks, Record puts focus on the Record control. The rail shows what + `GET /api/setup` reports and is read again when a dialog closes, when the recording readiness reason changes, and every + ten seconds; it is absent when that cannot be read. +- **Start-of-day checks (dialog).** The device connection test, run on request, lists every tracking device and camera the + station needs as passed, failed with the reason, or not needed; below it are the calibration and system checks. It + opens over the page, so the cameras stay live while a device is being fixed (`SetupDialog.tsx`). While any dialog is + open the page behind it is inert and the recording shortcuts are suspended. - **Status strip (under the bar).** The station in use, its active/inactive toggle, and the capture headline. The toggle (`StationActivityToggle.tsx`) marks the station active while it is collecting and blocked while it is not; nothing is counted before the first press of the day, and both totals stay in view. It needs the control token to change. diff --git a/examples/egocap/frontend/src/App.operatorLayout.test.tsx b/examples/egocap/frontend/src/App.operatorLayout.test.tsx index aff06d4429..b2e6c1ad16 100644 --- a/examples/egocap/frontend/src/App.operatorLayout.test.tsx +++ b/examples/egocap/frontend/src/App.operatorLayout.test.tsx @@ -11,6 +11,7 @@ import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/re import App from "./App"; import type { PreviewSnapshot } from "./captureProtocol"; import type { RecordingSnapshot } from "./recordingTypes"; +import { SETUP_NOT_TESTED, SETUP_PASSED } from "./setupTestDoubles"; import { useCaptureSession, type CaptureSessionState } from "./useCaptureSession"; vi.mock("./useCaptureSession", async (importOriginal) => { @@ -162,6 +163,60 @@ describe("station activity in the status strip", () => { }); }); +describe("start-of-day rail", () => { + /** Answer the flow and leave every other request unanswered, as a backend that is still starting would. */ + function stubSetup(body: unknown) { + const fetched = vi.fn(async (url: string) => new Response(JSON.stringify(url.startsWith("/api/setup") ? body : {}), { status: url.startsWith("/api/setup") ? 200 : 503 })); + vi.stubGlobal("fetch", fetched); + return fetched; + } + + it("shows the steps under the header and opens the checks over a page that takes no input", async () => { + const fetched = stubSetup(SETUP_NOT_TESTED); + const { container } = mount(); + const devices = await screen.findByRole("button", { name: /Step 2, Devices: to do/ }); + expect(container.querySelector(".app-header + .step-rail")).not.toBeNull(); + expect(container.querySelector(".op-body")?.hasAttribute("inert")).toBe(false); + fireEvent.click(devices); + const dialog = screen.getByRole("dialog", { name: "Start-of-day checks" }); + expect(dialog.textContent).toContain("Recording is held: run the device connection test before recording."); + // The page behind a dialog is inert, which is also what suspends the recording shortcuts. + expect(container.querySelector(".op-body")?.hasAttribute("inert")).toBe(true); + const reads = fetched.mock.calls.filter(([url]) => url === "/api/setup").length; + fireEvent.click(screen.getByRole("button", { name: "Close" })); + expect(screen.queryByRole("dialog")).toBeNull(); + expect(container.querySelector(".op-body")?.hasAttribute("inert")).toBe(false); + // Closing reads the flow again, so a fix made while the dialog was open shows on the rail at once. + await waitFor(() => expect(fetched.mock.calls.filter(([url]) => url === "/api/setup").length).toBe(reads + 1)); + }); + + it("opens the calibration step in the same checks dialog and the station step in Settings", async () => { + stubSetup(SETUP_NOT_TESTED); + mount(); + fireEvent.click(await screen.findByRole("button", { name: /Step 3, Calibration/ })); + expect(screen.getByRole("dialog", { name: "Start-of-day checks" })).not.toBeNull(); + fireEvent.click(screen.getByRole("button", { name: "Close" })); + fireEvent.click(screen.getByRole("button", { name: /Step 1, Station/ })); + const settings = screen.getByRole("dialog", { name: "Settings" }); + expect(settings.querySelector(".settings-tab--on")?.textContent).toBe("Station"); + }); + + it("puts the operator on the Record control for the record step", async () => { + stubSetup(SETUP_PASSED); + const { container } = mount(); + fireEvent.click(await screen.findByRole("button", { name: /Step 4, Record/ })); + expect(document.activeElement).toBe(container.querySelector(".recording-button--record")); + expect(screen.queryByRole("dialog")).toBeNull(); + }); + + it("shows no rail while the flow cannot be read", async () => { + vi.stubGlobal("fetch", vi.fn(async () => new Response("{}", { status: 503 }))); + const { container } = mount(); + await waitFor(() => expect(fetch).toHaveBeenCalled()); + expect(container.querySelector(".step-rail")).toBeNull(); + }); +}); + describe("resizing the side panel", () => { const widthOf = (container: HTMLElement) => (container.querySelector(".op-body") as HTMLElement).style.getPropertyValue("--op-sidebar-width"); diff --git a/examples/egocap/frontend/src/App.tsx b/examples/egocap/frontend/src/App.tsx index 7bb2c62aaa..ca87312c38 100644 --- a/examples/egocap/frontend/src/App.tsx +++ b/examples/egocap/frontend/src/App.tsx @@ -2,7 +2,7 @@ // // SPDX-License-Identifier: Apache-2.0 -import { useEffect, useId, useRef, useState, type CSSProperties } from "react"; +import { useCallback, useEffect, useId, useReducer, useRef, useState, type CSSProperties } from "react"; import { useCaptureSession, type ConnectionPhase } from "./useCaptureSession"; import type { PreviewSnapshot } from "./captureProtocol"; import { @@ -34,7 +34,11 @@ import { import { deviceTone, retainedTone, type Tone } from "./deviceHealth"; import { PoseViserPanel } from "./PoseViserPanel"; import { RecordingPanel } from "./RecordingPanel"; -import { SettingsPanel } from "./SettingsPanel"; +import { SettingsPanel, type SettingsTab } from "./SettingsPanel"; +import { SetupDialog } from "./SetupDialog"; +import type { StepId } from "./setupApi"; +import { StepRail } from "./StepRail"; +import { useSetup } from "./useSetup"; import { StationActivityToggle } from "./StationActivityToggle"; import { useOperatorSettings } from "./useOperatorSettings"; import { buildRecordingActions } from "./recordingActions"; @@ -210,7 +214,7 @@ function providerTone(status: ProviderStatus["status"]): Tone { /** The page's top bar: app title, capture mode, feed-health status and the Settings button. * There is no page/tab navigation -- the generic capture display and the * Ego Capture UI recording panel are always-present siblings on one page, and - * Settings opens as a drawer over them rather than replacing them. */ + * Settings and the start-of-day checks open as dialogs over them rather than replacing them. */ function AppHeader({ response, feedHealthLabel, @@ -492,22 +496,53 @@ export default function App() { return () => window.removeEventListener("resize", refit); }, []); const unavailable = response === null && feedHealth === "unavailable"; - const [settingsOpen, setSettingsOpen] = useState(false); + // At most one dialog is open over the page; while one is, the page behind it takes no input. + const [dialog, setDialog] = useState<"settings" | "setup" | null>(null); + const [settingsTab, setSettingsTab] = useState("station"); + // Counts Settings openings: each one starts the dialog afresh on the tab that was asked for. + const [settingsOpenings, countSettingsOpening] = useReducer((n: number) => n + 1, 0); + const settingsOpen = dialog === "settings"; + const modalOpen = dialog !== null; // The operator settings the page itself uses (camera roles). Re-read each time Settings closes, so a change // saved there reaches the tiles without a reload. const [settingsGeneration, setSettingsGeneration] = useState(0); const operatorSettings = useOperatorSettings(settingsGeneration); + // The start-of-day flow. It is read again when a dialog that can change it closes, and whenever the facts it + // is derived from change: the backend's own readiness reason, the station in use and the saved count. + const [setupGeneration, refreshSetup] = useReducer((n: number) => n + 1, 0); + const setup = useSetup(`${setupGeneration}|${recordingSnapshot?.notReadyReason ?? ""}|${response?.station_label ?? ""}|${recordingSnapshot?.savedCount ?? 0}`); + const openSettings = (tab: SettingsTab) => { + setSettingsTab(tab); + countSettingsOpening(); + setDialog("settings"); + }; const closeSettings = () => { - setSettingsOpen(false); + setDialog(null); setSettingsGeneration((n) => n + 1); + refreshSetup(); + }; + const closeSetup = useCallback(() => { + setDialog(null); + refreshSetup(); + }, []); + /** Open the place a step of the start-of-day flow is dealt with. */ + const openStep = (step: StepId) => { + if (step === "station") openSettings("station"); + else if (step === "devices" || step === "calibration") setDialog("setup"); + // Recording is the page itself: put the operator on its main control. + else if (step === "record") document.querySelector(".recording-button--record")?.focus(); }; // Every camera the session offers can fill a role, whichever path its video takes to the page. const cameraSources = (snapshot?.started?.streams ?? []).filter((s) => s.kind === "camera" || s.kind === "livekit_camera").map((s) => s.name); return (
    - setSettingsOpen(true)} /> + openSettings("station")} /> + +
    @@ -558,7 +593,7 @@ export default function App() { setControlToken={setControlToken} clearControlToken={clearControlToken} onPhaseChange={setPanelPhase} - interactionBlocked={settingsOpen} + interactionBlocked={modalOpen} />
    diff --git a/examples/egocap/frontend/src/SettingsPanel.tsx b/examples/egocap/frontend/src/SettingsPanel.tsx index 09b7be1885..5fa268dd6a 100644 --- a/examples/egocap/frontend/src/SettingsPanel.tsx +++ b/examples/egocap/frontend/src/SettingsPanel.tsx @@ -13,7 +13,7 @@ * commands do; Tools lists unavailable stubs; Display is this browser's only; Advanced values are set where the backend is launched. */ import { useCallback, useEffect, useRef, useState, type ReactNode } from "react"; -import { Card, TokenHint, errorMessage, useAction } from "./settingsParts"; +import { Card, TokenHint, errorMessage, useAction, useEscapeToClose, useModalFocus } from "./settingsParts"; import { HeadsetAddressCard } from "./HeadsetAddressCard"; import { StationsCard } from "./StationsCard"; import { @@ -712,45 +712,6 @@ function LoadState({ state, what }: { state: Loaded; what: string }) { return null; } -/** Own keyboard focus for the dialog lifetime and return it to the invoking control. */ -function useModalFocus(open: boolean) { - const dialogRef = useRef(null); - useEffect(() => { - if (!open || !dialogRef.current) return; - const dialog = dialogRef.current; - const previous = document.activeElement; - /** Recompute controls because loading, tab changes and saves can change their availability. */ - const controls = () => Array.from(dialog.querySelectorAll( - 'button, input, select, textarea, a[href], [tabindex]', - )).filter((element) => element.tabIndex >= 0 && !element.matches(":disabled") && !element.closest("[hidden], [inert]")); - /** Programmatic focus and pointer interaction must also respect the modal boundary. */ - const containFocus = (event: FocusEvent) => { - if (!dialog.contains(event.target as Node)) dialog.focus(); - }; - /** Cycle only the current dialog controls, including wraparound in either direction. */ - const onTab = (event: KeyboardEvent) => { - if (event.key !== "Tab" || event.altKey || event.ctrlKey || event.metaKey) return; - const available = controls(); - const current = available.indexOf(document.activeElement as HTMLElement); - const next = event.shiftKey - ? (current <= 0 ? available.length - 1 : current - 1) - : (current + 1) % available.length; - event.preventDefault(); - (available[next] ?? dialog).focus(); - }; - document.addEventListener("focusin", containFocus); - document.addEventListener("keydown", onTab); - dialog.focus(); - return () => { - // Release containment before restoring focus; rerenders must not recapture the invoking control. - document.removeEventListener("focusin", containFocus); - document.removeEventListener("keydown", onTab); - if (previous instanceof HTMLElement && previous.isConnected) previous.focus(); - }; - }, [open]); - return dialogRef; -} - /** Present station settings in a modal that owns focus until it closes. */ export function SettingsPanel({ open, @@ -772,16 +733,7 @@ export function SettingsPanel({ const loadSetup = useCallback((signal: AbortSignal) => backend.loadStationSetup(signal, controlToken), [backend, controlToken]); const [setup, updateSetup] = useLoaded(open, loadSetup); - // Escape closes, as for any dialog. - useEffect(() => { - if (!open) return; - /** Let Escape release the dialog from any focused control. */ - const onKey = (event: KeyboardEvent) => { - if (event.key === "Escape") onClose(); - }; - window.addEventListener("keydown", onKey); - return () => window.removeEventListener("keydown", onKey); - }, [open, onClose]); + useEscapeToClose(open, onClose); if (!open) return null; diff --git a/examples/egocap/frontend/src/SetupDialog.test.tsx b/examples/egocap/frontend/src/SetupDialog.test.tsx new file mode 100644 index 0000000000..b3e3d07c9c --- /dev/null +++ b/examples/egocap/frontend/src/SetupDialog.test.tsx @@ -0,0 +1,133 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** The start-of-day checks dialog: what it shows before and after the connection test, and running the test. */ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react"; +import { SettingsHttpError } from "./settingsApi"; +import { SetupDialog, type SetupDialogProps } from "./SetupDialog"; +import type { SetupStatus } from "./setupApi"; +import { SETUP_NOT_TESTED, SETUP_PASSED } from "./setupTestDoubles"; + +afterEach(cleanup); + +function renderDialog(overrides: Partial = {}) { + const props: SetupDialogProps = { + open: true, + onClose: vi.fn(), + setup: SETUP_NOT_TESTED, + controlToken: "tok", + onChanged: vi.fn(), + runTest: vi.fn(async () => SETUP_PASSED), + ...overrides, + }; + const utils = render(); + return { props, rerender: (next: Partial) => utils.rerender() }; +} + +const dialog = () => screen.getByRole("dialog", { name: "Start-of-day checks" }); +const rowsOf = (region: HTMLElement) => within(region).getAllByRole("listitem").map((row) => row.textContent); + +describe("SetupDialog", () => { + it("renders nothing while closed", () => { + renderDialog({ open: false }); + expect(screen.queryByRole("dialog")).toBeNull(); + }); + + it("says recording is held and why, before the test has been run", () => { + renderDialog(); + expect(screen.getByRole("status").textContent).toBe("Recording is held: run the device connection test before recording."); + const test = within(dialog()).getByRole("region", { name: "Device connection test" }); + expect(within(test).getByText("Not run yet for this station in this capture session.")).toBeTruthy(); + expect(within(test).getByRole("button", { name: "Run test" })).toBeTruthy(); + expect(rowsOf(within(dialog()).getByRole("region", { name: "Calibration and system" }))).toEqual([ + "✓Camera calibration passed", + "–Glove plugin not neededGloves are not part of this deployment", + "✓Free disk space passed211.3 GB free", + "–Camera producer not neededCameras are read by CaptureServer", + ]); + }); + + it("runs the test with the control token, shows each device, and tells the page", async () => { + const { props } = renderDialog(); + fireEvent.click(screen.getByRole("button", { name: "Run test" })); + expect(await screen.findByText(/✓ Passed at .* for Bench A/)).toBeTruthy(); + expect(props.runTest).toHaveBeenCalledWith("tok"); + expect(props.onChanged).toHaveBeenCalledTimes(1); + expect(screen.getByRole("status").textContent).toBe("Station setup allows recording."); + expect(rowsOf(screen.getByRole("region", { name: "Tracking" }))).toEqual(["✓Pico headset passed"]); + expect(rowsOf(screen.getByRole("region", { name: "Cameras" }))).toEqual([ + "✓Ego (head): cam_head passed", + "–Right wrist not neededNot used by this station", + ]); + expect(screen.getByRole("button", { name: "Run again" })).toBeTruthy(); + }); + + it("counts the failures and gives each one's reason", async () => { + const failed: SetupStatus = { + ...SETUP_PASSED, + blocked_reason: "the device connection test failed: Left wrist: cam_left: unplugged", + connection_test: { + ran_at: 1_773_050_520, + station: "Bench A", + passed: false, + items: [ + { id: "device:controller:1", group: "tracking", label: "Left controller", status: "fail", detail: "battery empty" }, + { id: "camera:wrist_left", group: "cameras", label: "Left wrist: cam_left", status: "fail", detail: "unplugged" }, + ], + }, + }; + renderDialog({ setup: failed }); + expect(screen.getByText(/2 failed at .* for Bench A/)).toBeTruthy(); + expect(rowsOf(screen.getByRole("region", { name: "Tracking" }))).toEqual(["✗Left controller failedBattery empty"]); + expect(screen.getByRole("status").textContent).toContain("Recording is held: the device connection test failed"); + }); + + it("prefers a newer read from the page over the answer of the last run", async () => { + const { rerender } = renderDialog(); + fireEvent.click(screen.getByRole("button", { name: "Run test" })); + await screen.findByText(/✓ Passed at/); + rerender({ setup: { ...SETUP_NOT_TESTED } }); // the capture session restarted: the result no longer applies + await waitFor(() => expect(screen.getByText("Not run yet for this station in this capture session.")).toBeTruthy()); + }); + + it("says the checks only advise while no station is in use", () => { + renderDialog({ setup: { ...SETUP_PASSED, enforced: false } }); + expect(screen.getByRole("status").textContent).toBe("No station is in use, so these checks advise and do not hold recording."); + }); + + it("shows the checks without the control token but cannot run the test", () => { + const { props } = renderDialog({ controlToken: null }); + const run = screen.getByRole("button", { name: "Run test" }) as HTMLButtonElement; + expect(run.disabled).toBe(true); + expect(screen.getByText("Enter the control token in the recording panel to run the test.")).toBeTruthy(); + fireEvent.click(run); + expect(props.runTest).not.toHaveBeenCalled(); + }); + + it("shows why the test could not be run and stays usable", async () => { + const runTest = vi.fn(async () => { + throw new SettingsHttpError("control token rejected"); + }); + const { props } = renderDialog({ runTest }); + fireEvent.click(screen.getByRole("button", { name: "Run test" })); + expect(await screen.findByText("Not run: control token rejected")).toBeTruthy(); + expect((screen.getByRole("button", { name: "Run test" }) as HTMLButtonElement).disabled).toBe(false); + expect(props.onChanged).not.toHaveBeenCalled(); + }); + + it("says so when the backend did not answer", () => { + renderDialog({ setup: null }); + expect(screen.getByText("The checks are unavailable: the backend did not answer.")).toBeTruthy(); + }); + + it("closes on Escape, the Close button and the backdrop, and owns focus while open", () => { + const { props } = renderDialog(); + expect(document.activeElement).toBe(dialog()); + fireEvent.keyDown(window, { key: "Escape" }); + fireEvent.click(screen.getByRole("button", { name: "Close" })); + fireEvent.click(document.querySelector(".settings-backdrop") as Element); + expect(props.onClose).toHaveBeenCalledTimes(3); + }); +}); diff --git a/examples/egocap/frontend/src/SetupDialog.tsx b/examples/egocap/frontend/src/SetupDialog.tsx new file mode 100644 index 0000000000..6b0c306bba --- /dev/null +++ b/examples/egocap/frontend/src/SetupDialog.tsx @@ -0,0 +1,165 @@ +// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +/** + * The start-of-day checks dialog: the device connection test, and the calibration and system checks. + * + * It opens over the page, so the cameras and the 3D view stay live behind it while devices are being fixed. + * The test is run on request and its result is the backend's: this dialog shows it and never judges a device + * itself. Every item is passed, failed with the reason, or marked as not applying to this station. + */ +import { useEffect, useState } from "react"; +import { sentence } from "./sentence"; +import { Card, errorMessage, useEscapeToClose, useModalFocus } from "./settingsParts"; +import { runConnectionTest, type CheckItem, type CheckStatus, type SetupStatus } from "./setupApi"; + +/** The mark and the words for each outcome; the mark alone is not text. */ +const OUTCOMES: Record = { + pass: { mark: "✓", word: "passed" }, + fail: { mark: "✗", word: "failed" }, + skip: { mark: "–", word: "not needed" }, +}; + +/** The groups of the connection test, in the order they are listed. */ +const GROUPS: ReadonlyArray<[string, string]> = [ + ["tracking", "Tracking"], + ["cameras", "Cameras"], +]; + +/** One device or check: its outcome, its name, and why when it did not simply pass. */ +function CheckRow({ item }: { item: CheckItem }) { + const outcome = OUTCOMES[item.status]; + return ( +
  • + + + {item.label} + {outcome.word} + + {item.detail !== null && {sentence(item.detail)}} +
  • + ); +} + +/** A local clock time for when the test ran. */ +function clockTime(epochSeconds: number): string { + return new Date(epochSeconds * 1000).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }); +} + +export interface SetupDialogProps { + open: boolean; + onClose: () => void; + /** The flow as the page last read it; null while it could not be read. */ + setup: SetupStatus | null; + /** The run's control token once entered; without it the checks are shown but the test cannot be run. */ + controlToken: string | null; + /** Called after the test ran, so the page reads the flow again. */ + onChanged: () => void; + runTest?: (controlToken: string) => Promise; +} + +/** Show the connection test and the system checks, and run the test on request. */ +export function SetupDialog({ open, onClose, setup, controlToken, onChanged, runTest = runConnectionTest }: SetupDialogProps) { + const dialogRef = useModalFocus(open); + useEscapeToClose(open, onClose); + // The answer to a test just run, shown at once; a newer read from the page replaces it. + const [answer, setAnswer] = useState(null); + const [busy, setBusy] = useState(false); + const [failure, setFailure] = useState(null); + useEffect(() => setAnswer(null), [setup]); + + if (!open) return null; + const shown = answer ?? setup; + /** Run the test and show the backend's result. */ + const run = () => { + if (controlToken === null || busy) return; + setBusy(true); + setFailure(null); + runTest(controlToken).then( + (result) => { + setAnswer(result); + setBusy(false); + onChanged(); + }, + (error: unknown) => { + setFailure(errorMessage(error)); + setBusy(false); + }, + ); + }; + const test = shown?.connection_test ?? null; + const failed = test === null ? 0 : test.items.filter((item) => item.status === "fail").length; + + return ( + <> +