diff --git a/AGENTS.md b/AGENTS.md index bba718dea..ef5facf17 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,6 +100,15 @@ pre-commit install --hook-type commit-msg SKIP=check-copyright-year pre-commit run --all-files ``` +- On Windows, verify `git submodule` and `python` resolve before running + pre-commit. Pre-commit updates submodules while cloning hook repositories, + and repository hooks invoke Python directly. For sparse checkouts, also + include `.reuse/` and `LICENSES/` so REUSE can resolve declared licenses. +- During a manual merge, `check-merge-conflict` can mistake an exact + seven-character reStructuredText title underline for `=======`. Resolve all + unmerged paths, verify the index with `git diff --check`, commit the merge, + and rerun `--all-files` from the clean state instead of editing an unrelated + heading. - **REUSE:** files covered by the REUSE hook need **`SPDX-FileCopyrightText`** and **`SPDX-License-Identifier`** in the form the repo already uses (for example the HTML comment block at the top of `README.md` also applies to **`AGENTS.md`** and similar docs). - **C++ formatting is enforced by CI, not pre-commit.** The hook set runs `ruff` for Python but does **not** run `clang-format`; CI (`build-ubuntu.yml`) installs **`clang-format-14`** and rejects unformatted C++ as `-Wclang-format-violations`. Before pushing, format touched C++ with the system `clang-format` (match CI's version 14) and verify: diff --git a/docs/source/getting_started/build_from_source/index.rst b/docs/source/getting_started/build_from_source/index.rst index 1eb6979d0..256c7248f 100644 --- a/docs/source/getting_started/build_from_source/index.rst +++ b/docs/source/getting_started/build_from_source/index.rst @@ -38,14 +38,18 @@ the list of dependencies. On **Ubuntu**, install build tools and clang-format: sudo apt-get update sudo apt-get install -y build-essential cmake libx11-dev clang-format-14 ccache patchelf -Runtime-only dependencies (needed to actually run teleop, not to build): +Runtime-only dependencies are not needed for the normal Wi-Fi workflow. +For USB headset automation with ``--setup-oob``, install ``adb``: + +.. code-block:: bash + + sudo apt-get install -y android-tools-adb + +For the fully USB-local ``--setup-oob --usb-local`` mode, also install +``coturn``: .. code-block:: bash - # adb — required for OOB teleop (``--setup-oob``) to talk to the headset over USB. - # coturn — required for USB-local mode (``--usb-local``); runs a local TURN server - # so WebRTC ICE can relay traffic from the headset to the CloudXR backend - # over the USB cable. sudo apt-get install -y android-tools-adb coturn Our build system uses `uv`_ for Python version and dependency management. Install `uv`_ if not already installed: diff --git a/docs/source/getting_started/quick_start.rst b/docs/source/getting_started/quick_start.rst index 232d1ad72..dfb5d6ba7 100644 --- a/docs/source/getting_started/quick_start.rst +++ b/docs/source/getting_started/quick_start.rst @@ -108,6 +108,13 @@ The first launch downloads the CloudXR Web Client SDK and asks you to review and accept the EULA on the terminal; answer the prompt once and the acceptance is remembered for subsequent runs. +.. important:: + + Run only one CloudXR runtime at a time. When a teleop example auto-launches + CloudXR, do not also run ``python -m isaacteleop.cloudxr`` in another + terminal. Competing runtimes use the same backend port and interrupt the + active session. + The CloudXR runtime uses the ``auto-webrtc`` device profile by default (Pico & Quest). For Apple Vision Pro it defaults to ``auto-native``. To override settings, write a ``KEY=value`` env file and pass it to the example @@ -134,7 +141,8 @@ To inspect the resolved settings after startup: If you prefer to run the runtime yourself in its own terminal — e.g. to keep the headset connection alive across example restarts, or to use launch modes like ``--host-client`` and ``--setup-oob`` — see - :doc:`/references/cloudxr`. + :doc:`/references/cloudxr`. Stop the auto-launched runtime before switching + to the standalone launcher. .. list-table:: Environment variables :header-rows: 1 @@ -268,6 +276,12 @@ running the CloudXR runtime and wss proxy in containerized environment; or using **Figure:** Certificate accepted page + .. important:: + + Complete the certificate-acceptance step before clicking **Connect**. + Otherwise, the headset's secure WebSocket connection can fail without a + visible error. + As illustrated in the figure above, there are 3 steps to connect to your headset: 1. Enter the IP address of the workstation running CloudXR diff --git a/examples/cloudxr_mujoco_teleop/pyproject.toml b/examples/cloudxr_mujoco_teleop/pyproject.toml index d0604d459..f7a7efcba 100644 --- a/examples/cloudxr_mujoco_teleop/pyproject.toml +++ b/examples/cloudxr_mujoco_teleop/pyproject.toml @@ -11,4 +11,5 @@ dependencies = [ "mujoco>=3.0", "numpy>=1.22.2", "scipy>=1.10", + "websockets>=14", ]