xdof 0.0.1
xdof: core xdof code base
Requires Python: ==3.11.*

# Getting Started

## Install everything

We use uv for installation (https://github.com/astral-sh/uv).
Note, when you are using uv in China, you might need to set a proxy to speed up the installation.

### Install uv from scratch

```
# install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# or
sudo snap install --classic astral-uv

uv venv --python 3.11
source .venv/bin/activate
```

### Optionally use the following command to get the full menagerie (of robot models)

```
git submodule update --init --recursive
```

### Install requirements

```
uv sync --all-packages
# OR, in SZ office, using a pypi index mirror
uv sync --all-packages -i https://pypi.tuna.tsinghua.edu.cn/simple
```

Note: dev dependencies are installed by default right now.

If you need to install requirements for specific projects:

```
uv sync --extra dataengine
uv sync --extra learning
# or
uv sync --extra dataengine -i https://pypi.tuna.tsinghua.edu.cn/simple
uv sync --extra learning -i https://pypi.tuna.tsinghua.edu.cn/simple
```

You will likely have to install `torch` yourself. We are currently on 2.7.0 on CUDA 12.8.

When installing a package, please install to the right dependency group.

```
uv add my-package --dev
uv add my-package --extra dataengine
uv add my-package --group learning
```

In China, when installing non-Python packages that don't have a Chinese mirror, it's
often necessary to use a proxy:

```
export http_proxy=http://192.168.50.210:10080
export https_proxy=http://192.168.50.210:10080
export socks_proxy=socks5://192.168.50.210:10081
```

## Lint

We use ruff for linting (https://docs.astral.sh/ruff/tutorial/#getting-started)

```bash
ruff check # lint
ruff check --fix # lint and fix anything fixable
ruff format # code format
```

## Type Checking

We use pyright for type checking (https://github.com/microsoft/pyright)

```bash
pyright xdof
```

## Install pre-commit hooks

```bash
pre-commit install
```

## Packages

We have packages in `packages/` that are used in the `xdof` monorepo but are intended to be distributed externally. To support this, we use `uv`'s workspaces feature and they have their own dependencies/pyproject.toml.

We need to check that everything those `packages/` imports is actually in their `pyproject.toml`, because it's possible we have in installed in our `lab42` codebase but not in the package, and it will work normally for us.

`tach` that just resolves dependencies and makes sure each package actually has everything it needs in its respective `pyproject.toml`.

We have CI check that runs

```
$ tach check
$ tach check-external
```

## How to launch a real station

### With script

```
python xdof/envs/launch.py --config-path {station_config_name}
```

`station_config_name` can be found under `configs`.

### With GUI

see [GUI.md](misc/docs/deploy-operator-gui.md)

## Gello station tutorial

see [xdof/envs/README.md](xdof/envs/README.md)

## Debugging tips

### Install NVIDIA Driver

1. find the recommended driver
   ```
   sudo ubuntu-drivers devices
   ```
2. install the recommended one
   ```
   sudo apt install nvidia-driver-{xxx}
   sudo reboot
   ```

### Realsense

NOTE: librealsense is not supported on macOS.

- If you cannot find the RealSense camera, refer to this [link](https://github.com/IntelRealSense/librealsense/blob/master/doc/distribution_linux.md).
- If you can launch `realsense-viewer` but cannot find the RealSense camera, run the following commands to debug. Make sure Secure Boot is disabled in the BIOS.

```
lsmod | grep uvcvideo
sudo modprobe uvcvideo
```

- If the RealSense D405 camera's auto-exposure does not work, change the firmware to [5.13.0.50](https://dev.realsenseai.com/docs/docs-get-started).


## More information

Deploy the operator GUI, [misc/docs/deploy-operator-gui.md](misc/docs/deploy-operator-gui.md)