xr_teleoperate: XR Control for Unitree Humanoid Robots

Why xr_teleoperate targets Unitree hardware

xr_teleoperate addresses a specific integration problem: mapping input from an extended-reality headset to a supported Unitree humanoid robot or hand controller. The README names Apple Vision Pro, PICO 4 Ultra Enterprise, and Meta Quest 3 as examples of XR devices. This is not presented as a device-neutral robotics stack. Its supported robot and actuator list includes G1 with 29 or 23 degrees of freedom, H1 with a 4-degree-of-freedom arm, H1_2 and H2 with 7-degree-of-freedom arms, and R1_A5 and R1_A7 configurations. The listed end effectors include Dex1-1, Dex3-1, the Inspire dexterous hand, and the BrainCo dexterous hand.

The intended reader is an engineer who already has, or is prepared to learn, Unitree application development. The introduction explicitly tells newcomers to read the official documentation through at least the “Application Development” chapter. That boundary matters. The repository documentation concentrates on teleoperation integration, but it does not present xr_teleoperate as a substitute for the robot vendor's general application-development guidance, robot setup instructions, or safety practices.

The repository's release note for v1.6, dated 2026.7.29, adds H2 and R1 support in the `R1_A5` and `R1_A7` configurations. It also adds BrainCo hand controller-input support and changes the default arm reference to be relative to head yaw. Those entries describe product-specific compatibility, not broad compatibility with every Unitree robot or every XR controller.

Repository structure and XR connection path

The repository is primarily Python and separates the main project from two editable submodules. Based on the repository layout, `teleop/teleimager` is installed with `pip install -e . --no-deps`, while `teleop/televuer` is installed with `pip install -e .`. The exact division of responsibility inside those components is not described in the README, so it would be unsafe to assign every tracking and conversion task to one module without inspecting its source.

The installation documentation does confirm one important transport concern. It says the `televuer` module must have SSL certificates configured so XR devices, including Pico, Quest, and Apple Vision Pro, can connect securely over HTTPS and WebRTC. Pico and Quest receive one certificate-generation path. Apple Vision Pro receives a longer path that creates a root CA and a localhost server certificate. The server configuration also requires the host IP address to be edited into the certificate configuration, which means the HTTPS setup depends on the machine's network address rather than being entirely generic.

This structure points to a local teleoperation server reached by an XR device, with robot-specific software in the repository. It does not establish that the system is cloud operated. The certificate instructions use a localhost server identity and require the host IP in `server_ext.cnf`, which is consistent with deployment on a local network. The README does not state the WebRTC signaling method, controller sample rate, tracking coordinate system, or end-to-end mapping from headset poses to joint commands.

Installing the Python environment and repository submodules

The README documents Ubuntu 20.04 and Ubuntu 22.04 as its tested environments, while warning that other operating systems may require different configuration. It also calls the procedure the “default mode.” The first real setup step is to create a Python 3.10 Conda environment with the pinned `pinocchio` and `numpy` versions shown by the project. The following commands create the environment, activate it, clone the repository, and initialize its submodules shallowly.

conda create -n tv python=3.10 pinocchio=3.1.0 numpy=1.26.4 -c conda-forge
conda activate tv
git clone https://github.com/unitreerobotics/xr_teleoperate.git
cd xr_teleoperate
git submodule update --init --depth 1

After these commands, the current directory should be the cloned `xr_teleoperate` repository and its declared submodules should be initialized. The shallow submodule update limits clone history, which may matter when debugging dependency changes or examining older submodule revisions.

Next, install `teleimager` without automatic dependency resolution, then install `televuer` through editable installs. The repository's root `requirements.txt` additionally lists fixed versions for `matplotlib`, `rerun-sdk`, `meshcat`, and `sshkeyboard`, but the README does not show the command that installs this root file. It would be a configuration mistake to assume the two editable submodule installs automatically install every package in `requirements.txt`.

cd teleop/teleimager
pip install -e . --no-deps
cd teleop/televuer
pip install -e .

These commands place the local submodule source on the active Python environment through editable installs. They do not configure the robot, headset, certificates, or network interface.

Preparing HTTPS certificates for Pico, Quest, and Vision Pro

Certificate setup is part of the documented flow. The README links it directly to secure XR connectivity through HTTPS and WebRTC. For Pico and Quest, the documented command creates a self-signed RSA certificate pair with a validity period of 365 days. Run it from `teleop/televuer`, because that is the module named by the instructions.

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout key.pem -out cert.pem

This creates `key.pem` and `cert.pem` in the current directory. The README does not describe how those files are copied to an XR headset or consumed by the teleoperation process, so that part cannot be reduced to an invented command.

Apple Vision Pro uses a separate certificate hierarchy. The following documented commands create `rootCA.key`, `rootCA.pem`, `key.pem`, `server.csr`, and a server certificate request with the subject `/CN=localhost`.

openssl genrsa -out rootCA.key 2048
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 365 -out rootCA.pem -subj "/CN=xr-teleoperate"
openssl genrsa -out key.pem 2048
openssl req -new -key key.pem -out server.csr -subj "/CN=localhost"

The next required artifact is `server_ext.cnf`, with `subjectAltName` information matching the host address. The README says to use `ifconfig` or a similar tool to find the host IP and then edit the file with `vim`. Copying an incomplete certificate configuration would leave the HTTPS setup unverifiable. The complete configuration must come from the full README or repository file.

Moving from installation to an XR teleoperation session

The README establishes the environment, submodules, supported hardware, and certificate requirements, but it does not include the launch command for teleoperation. That omission prevents a complete first-session example without guessing. The README directs readers to Unitree's official teleoperation documentation, the repository Wiki, and OpenTeleVision for additional information. It also points newcomers to Unitree's application-development documentation.

For the first real use, start by confirming that the physical setup matches the system diagram referenced by the README. The device requirements and wiring are presented as necessary rather than optional. Next, compare the connected robot and end-effector models against the repository's supported-device table. For v1.6-era behavior, also check `CHANGELOG.md` for H2, R1, BrainCo, and the head-yaw-relative arm-reference change.

The certificate must be correct for the headset path. Pico and Quest use the simpler `key.pem` and `cert.pem` command. Apple Vision Pro requires the CA, server key, CSR, and a complete `server_ext.cnf` containing the correct host address. After those checks, follow the official Unitree teleoperation instructions for the remaining headset installation and program launch sequence. This is a documentation boundary, not a claim that the software will run immediately after `pip install`.

The repository also does not document a dry-run mode, simulator command, connection test, emergency stop procedure, or calibration command in the README. An engineer should therefore not infer that installation success establishes robot readiness. Hardware connection, model selection, certificate trust, and the Unitree-side startup procedure remain separate prerequisites.

Supported models versus deployment constraints

The support table is broad within Unitree's product family, but the phrase “Complete” should not be read as universal hardware compatibility. Each robot entry is tied to a particular degree-of-freedom configuration, and the end effectors are named individually. The release note further distinguishes `R1_A5` from `R1_A7`. A buyer or integrator must match the exact configuration rather than selecting only the robot family name.

The XR side also has documented differences. Pico and Quest share one certificate path, while Apple Vision Pro requires a CA and server configuration. The README's list names particular devices but does not claim support for every headset model. The wiring diagram is treated as a required part of installation, yet the README does not enumerate each cable or port. Operators must consult the diagram and `Device.md` rather than deriving connections from the Python package layout.

Another constraint is the head-yaw-relative arm reference introduced as the default in v1.6. That changes the reference frame used for arm control, so existing deployment assumptions about world-relative or fixed arm orientation should be checked against the updated documentation. The README does not provide a compatibility switch or explain migration behavior for existing mappings. It only says that the head-yaw-relative reference is now the default.

The repository has no GitHub releases, so there is no release asset or tagged-package installation path documented on that platform. `CHANGELOG.md` provides version history, with v1.6 dated 2026.7.29 in the README. The last repository push was on 2026-09-07. Submodule revisions remain an operational consideration because `git submodule update --init --depth 1` initializes code whose contents can change independently of the main checkout.

License, maintenance, and upgrade responsibility

The repository declares a custom license that GitHub cannot classify, and its top-level `LICENSE` file is the governing source to review. No legal interpretation is offered here. The distinction matters for adoption because an organization should check whether its intended use, redistribution, modification, and deployment model fit the actual license text rather than assuming a standard open source license from the source-code availability.

Maintenance should be assessed through concrete repository activity, not through claims of support. The repository is not archived, and its last push was on 2026-09-07. The README exposes a dated changelog, but GitHub has no releases. Upgrades may therefore require checking `CHANGELOG.md`, the main commit history, and the state of both submodules rather than upgrading through a conventional GitHub release.

Pinned Python packages are part of the upgrade cost. The environment instructions fix `pinocchio==3.1.0` and `numpy==1.26.4`, while the root requirements fix `matplotlib==3.7.5`, `rerun-sdk==0.20.1`, `meshcat==0.3.2`, and `sshkeyboard==2.3.1`. Changing these versions is not documented as a supported operation in the README. An upgrade review should therefore account for pinned dependencies, submodule commits, robot-model changes, certificate validity, and the change to head-yaw-relative arm control.

xr_teleoperate versus OpenTeleVision

The README names OpenTeleVision as an additional source of information and links to its `TeleVision` project, but it does not provide a direct feature matrix. The meaningful difference visible in the documentation is scope. xr_teleoperate is the Unitree repository with explicit support entries for Unitree robot models, hand devices, and Unitree-published setup instructions. OpenTeleVision is presented as a related external implementation from which readers can obtain more information.

That does not make OpenTeleVision an interchangeable substitute, nor does it establish which has broader hardware support. Based on the README, xr_teleoperate is the more direct reference for integrations explicitly listed in its support table, especially the current Unitree G1, H1, H1_2, H2, R1, Dex1-1, Dex3-1, Inspire hand, and BrainCo hand combinations. The trade-off is dependence on Unitree-specific documentation and hardware assumptions.

Engineers needing a vendor-neutral control layer should not select this repository on the basis of its HTTPS and WebRTC terminology. The actual input mapping and runtime command remain undocumented in the README. Before choosing an alternative or combining implementations, inspect `teleop/teleimager`, `teleop/televuer`, and the OpenTeleVision repository directly for tracking semantics, coordinate conventions, latency behavior, and supported robot models.

Editorial conclusion

Adopt xr_teleoperate if you are developing for a listed Unitree robot, end effector, or XR device and can follow Unitree's official application-development guidance. Do not treat it as a generic XR control framework or expect the README alone to define runtime, networking, safety, and robot calibration behavior. The first project-specific checks are the robot variant in `CHANGELOG.md`, the complete device wiring requirements in `Device.md`, and the official Unitree teleoperation documentation referenced by the README.

Frequently asked questions

Official sources

1. Issues
2. README
3. unitreerobotics/xr_teleoperate on GitHub