.. _installation: Installation ======================== *ImVR* requires a VR headset and a host machine to run the simulation & real world observation rendering. The following instructions guide you through setting up *ImVR* with a Meta Quest 3 headset using a wired connection to a host machine. Preliminary Steps ----------------------- 1. clone the *ImVR* repository: .. code-block:: bash git clone https://github.com/liuyulinn/imvr.git --recursive 2. download the necessary assets: .. code-block:: bash cd imvr bash download.sh You should see the following folder structure: .. code-block:: text imvr/ ├── adbforwarder/ # Tools for setting up a wired connection with Meta Quest 3 ├── alvr_green/ # ALVR-related components for streaming VR content ├── vr_teleop/ # Main source code for VR teleoperation │ ├── assets/ # Simulation assets │ │ ├── agents/ # Agent models and configurations │ │ ├── envs/ # Simulation environments │ │ └── ... # Other asset subdirectories │ └── ... # Other source code and modules └── ... # Additional files and directories Meta Quest 3 Setup ----------------------- Install ALVR on Meta Quest 3 following the instructions on `Meta Quest ALVR `_. You can either install it with `SideQuest `_ or download directly from Meta Quest Horizon Store. Open ALVR on the headset. You should see message like "ALVR v20.1.3" (Version can be different). Host machine setup ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. To allow wired connection with Meta Quest 3 without root privileges, you need to add a ``udev`` rule on the host machine: * Create a file named ``99-quest3.rules`` under ``/etc/udev/rules.d/`` using the following command: .. code-block:: bash echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="2833", ATTR{idProduct}=="0186", MODE="0660", GROUP="plugdev"' \ | sudo tee /etc/udev/rules.d/99-quest3.rules > /dev/null sudo udevadm control --reload-rules && sudo udevadm trigger * Add the current user to the ``plugdev`` group with .. code-block:: bash # Add your user to the docker group sudo usermod -aG plugdev $USER # Log out and log back in, or run: newgrp plugdev 2. (Skip this step if you have already set up ADB on your host machine) install ADB: .. code-block:: bash sudo apt update sudo apt install adb 3. To test connection and authorize connection to your host machine: * Run the following command from the root of the ``imvr`` repository: .. code-block:: bash ./adbforwarder/ADBForwarder * You should see output similar to: .. code-block:: text Platform: Linux Adb server started. If your device doesn't show up after connecting the device, please make sure dev mode is enabled on headset and cable or usb port is not damaged. Connected device: 2G0YC1ZF80008R Successfully forwarded device: 2G0YC1ZF80008R [eureka] * If you encounter an "unauthorized" error like below, you must approve the ADB connection on the headset: .. code-block:: text Connected device: 2G0YC1ZF80008R Skipped forwarding device: 2G0YC1ZF80008R, Error: Unauthorized Unauthorized device, please make sure you enabled developer mode on device, authorized adb connection on the device and then replug usb cable. * In some cases, the headset does not show the permission prompt. If that happens: - Ensure the cable is securely connected and that the device is visible via ``lsusb``. - Try reconnecting the cable or rebooting the headset. 4. Once you've tested and authorized the connection, you can proceed to the docker setup below. Docker Setup ----------------------- .. note:: We currently only provide a Docker release that supports controller tracking with Meta Quest. If you want to use hand tracking, please build ALVR from source and refer to :ref:`advanced`. Make sure you have the following installed and configured: - ``docker`` (Docker Engine) - Current user added to the ``docker`` group (so `docker` can run without `sudo`) - ``nvidia-container-toolkit`` - ``nvidia`` container runtime enabled Helpful guides: `Docker Engine on Ubuntu `_, `NVIDIA Container Toolkit `_ All commands below should be run from the root of the ``imvr`` repository. 1. Pull the latest docker image: .. code-block:: bash docker compose pull base 2. Start the ALVR container: .. code-block:: bash docker compose up alvr If your user does not have UID 1000, the container will adjust the user ID and ownership of files/directories using ``usermod`` and ``chown``, which can take 2–5 minutes. To view a progress bar during this process, run: .. code-block:: bash docker compose run --rm alvr Example output: .. code-block:: text Found too many files while changing user ID (usermod). Please wait for it to finish. Progress [92946/94486] : [#######################################-] 98% Finished changing ID of user 'vr' to 1004. chown 19158 files in /VRTeleop ... 3. After the container starts, you should see output similar to the following and the ALVR Dashboard window should open: .. code-block:: text Connected device: 2G0YC1ZF80008R Successfully forwarded device: 2G0YC1ZF80008R [eureka] [15:24:49.125583297 INFO winit::platform_impl::platform::x11::window] Guessed window scale factor: 1 The container runs ``ADBForwarder`` in the background and keeps ``alvr_dashboard`` in an infinite loop. You can safely close and reopen the ALVR Dashboard without restarting the container. Please refer to the following video for the ALVR connection tutorial: .. video:: assets/ALVR_connection_tutorial.mp4 :align: center :width: 600 :caption: ALVR connection setup tutorial Upon successful connection, you should see Steam's test scene with an empty floor and hand-held controllers in the VR headset. .. figure:: assets/default_scene.png :width: 600 :align: center Test scene in VR headset 4. Run the example teleoperation of the Panda robot for the Peg Insertion task: Start the base container: .. code-block:: bash docker compose run --rm base Then run the teleoperation script: .. code-block:: bash cd vr_teleop ./example.sh peg_insertion You should see the Panda robot in the VR headset, positioned on a table with a peg and a hole. You will also see coordinate axes that move in sync with your hand and controller. .. video:: assets/peg_insertion_video.mp4 :align: center :width: 300 :caption: Peg Insertion in VR View. Coordinate axes always move in sync with your hand and controller. For instructions on using teleoperation, please refer to the usage section in :ref:`xarm_gripper`. .. warning:: Make sure your NVIDIA graphics driver version is **greater than 565**, or the system can't function properly. You can check the installed version with: .. code-block:: bash nvidia-smi | grep "Driver Version" If the version is lower than 565, please update your driver through: .. code-block:: bash sudo apt install nvidia-driver-xxx # sudo apt install nvidia-driver-535 # for example