Skip to content

Update readme to documentate how to run in WSL2 #147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vteran93 wants to merge 1 commit into
base: bugfix/pip-gym-mismatch
Choose a base branch
from
Open

Update readme to documentate how to run in WSL2 #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
254 changes: 165 additions & 89 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,89 +1,165 @@
![Python 3.8 3.9](https://github.com/f1tenth/f1tenth_gym/actions/workflows/ci.yml/badge.svg)
![Docker](https://github.com/f1tenth/f1tenth_gym/actions/workflows/docker.yml/badge.svg)
# The F1TENTH Gym environment

This is the repository of the F1TENTH Gym environment.

This project is still under heavy developement.

You can find the [documentation](https://f1tenth-gym.readthedocs.io/en/latest/) of the environment here.

## Quickstart
We recommend installing the simulation inside a virtualenv. You can install the environment by running:

```bash
virtualenv gym_env
source gym_env/bin/activate
git clone https://github.com/f1tenth/f1tenth_gym.git
cd f1tenth_gym
pip install -e .
```

Then you can run a quick waypoint follow example by:
```bash
cd examples
python3 waypoint_follow.py
```

A Dockerfile is also provided with support for the GUI with nvidia-docker (nvidia GPU required):
```bash
docker build -t f1tenth_gym_container -f Dockerfile .
docker run --gpus all -it -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix f1tenth_gym_container
````
Then the same example can be ran.

## Known issues
- Library support issues on Windows. You must use Python 3.8 as of 10-2021
- On MacOS Big Sur and above, when rendering is turned on, you might encounter the error:
```
ImportError: Can't find framework /System/Library/Frameworks/OpenGL.framework.
```
You can fix the error by installing a newer version of pyglet:
```bash
$ pip3 install pyglet==1.5.20
```
And you might see an error similar to
```
f110-gym 0.2.1 requires pyglet<1.5, but you have pyglet 1.5.20 which is incompatible.
```
which could be ignored. The environment should still work without error.

- Invalid metadata: Expected end or smeicolon (after version specifier)
>WARNING: Ignoring version 0.19.0 of gym since it has invalid metadata:
Requested gym==0.19.0 from file:///home/\<user\>/.cache/pip/wheels/c8/24/9d/db9869e09d1fbf12a10ce64362d9f161f09bdb5651e44317fe/gym-0.19.0-py3-none-any.whl (from f110-gym==0.2.1) has invalid metadata: Expected matching RIGHT_PARENTHESIS for LEFT_PARENTHESIS, after version specifier
opencv-python (>=3.) ; extra == 'all'
~~~~^
Please use pip<24.1 if you need to use this version.
INFO: pip is looking at multiple versions of f110-gym to determine which version is compatible with other requirements. This could take a while.
ERROR: Could not find a version that satisfies the requirement gym==0.19.0 (from f110-gym) (from versions: 0.0.2, 0.0.3, 0.0.4, 0.0.5, 0.0.6, 0.0.7, 0.1.0, 0.1.1, 0.1.2, 0.1.3, 0.1.4, 0.1.5, 0.1.6, 0.1.7, 0.2.0, 0.2.1, 0.2.2, 0.2.3, 0.2.4, 0.2.5, 0.2.6, 0.2.7, 0.2.8, 0.2.9, 0.2.10, 0.2.11, 0.2.12, 0.3.0, 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.4, 0.4.5, 0.4.6, 0.4.8, 0.4.9, 0.4.10, 0.5.0, 0.5.1, 0.5.2, 0.5.3, 0.5.4, 0.5.5, 0.5.6, 0.5.7, 0.6.0, 0.7.0, 0.7.1, 0.7.2, 0.7.3, 0.7.4, 0.8.0.dev0, 0.8.0, 0.8.1, 0.8.2, 0.9.0, 0.9.1, 0.9.2, 0.9.3, 0.9.4, 0.9.5, 0.9.6, 0.9.7, 0.10.0, 0.10.1, 0.10.2, 0.10.3, 0.10.4, 0.10.5, 0.10.8, 0.10.9, 0.10.11, 0.11.0, 0.12.0, 0.12.1, 0.12.4, 0.12.5, 0.12.6, 0.13.0, 0.13.1, 0.14.0, 0.15.3, 0.15.4, 0.15.6, 0.15.7, 0.16.0, 0.17.0, 0.17.1, 0.17.2, 0.17.3, 0.18.0, 0.18.3, 0.19.0, 0.20.0, 0.21.0, 0.22.0, 0.23.0, 0.23.1, 0.24.0, 0.24.1, 0.25.0, 0.25.1, 0.25.2, 0.26.0, 0.26.1, 0.26.2)
ERROR: No matching distribution found for gym==0.19.0

As the warning suggests, this is due to incompatibility between pip versions >=24.1 and gym version 0.19.0. You can resolve this by downgrading the pip used in the virtualenv:

```
pip install --upgrade pip==24.0
```

The installation steps are then as follows:

```bash
virtualenv gym_env
source gym_env/bin/activate
pip install --upgrade pip==24.0
git clone https://github.com/f1tenth/f1tenth_gym.git
cd f1tenth_gym
pip install -e .
```
## Citing
If you find this Gym environment useful, please consider citing:

```
@inproceedings{okelly2020f1tenth,
title={F1TENTH: An Open-source Evaluation Environment for Continuous Control and Reinforcement Learning},
author={O’Kelly, Matthew and Zheng, Hongrui and Karthik, Dhruv and Mangharam, Rahul},
booktitle={NeurIPS 2019 Competition and Demonstration Track},
pages={77--89},
year={2020},
organization={PMLR}
}
```
![Python 3.8 3.9](https://github.com/f1tenth/f1tenth_gym/actions/workflows/ci.yml/badge.svg)
![Docker](https://github.com/f1tenth/f1tenth_gym/actions/workflows/docker.yml/badge.svg)
# The F1TENTH Gym environment

This is the repository of the F1TENTH Gym environment.

This project is still under heavy developement.

You can find the [documentation](https://f1tenth-gym.readthedocs.io/en/latest/) of the environment here.

## Quickstart
We recommend installing the simulation inside a virtualenv. You can install the environment by running:

```bash
virtualenv gym_env
source gym_env/bin/activate
git clone https://github.com/f1tenth/f1tenth_gym.git
cd f1tenth_gym
pip install -e .
```

Then you can run a quick waypoint follow example by:
```bash
cd examples
python3 waypoint_follow.py
```

A Dockerfile is also provided with support for the GUI with nvidia-docker (nvidia GPU required):
```bash
docker build -t f1tenth_gym_container -f Dockerfile .
docker run --gpus all -it -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix f1tenth_gym_container
````
Then the same example can be ran.

## Known issues
- Library support issues on Windows. You must use Python 3.8 as of 10-2021
- On MacOS Big Sur and above, when rendering is turned on, you might encounter the error:
```
ImportError: Can't find framework /System/Library/Frameworks/OpenGL.framework.
```
You can fix the error by installing a newer version of pyglet:
```bash
$ pip3 install pyglet==1.5.20
```
And you might see an error similar to
```
f110-gym 0.2.1 requires pyglet<1.5, but you have pyglet 1.5.20 which is incompatible.
```
which could be ignored. The environment should still work without error.

- Invalid metadata: Expected end or smeicolon (after version specifier)
>WARNING: Ignoring version 0.19.0 of gym since it has invalid metadata:
Requested gym==0.19.0 from file:///home/\<user\>/.cache/pip/wheels/c8/24/9d/db9869e09d1fbf12a10ce64362d9f161f09bdb5651e44317fe/gym-0.19.0-py3-none-any.whl (from f110-gym==0.2.1) has invalid metadata: Expected matching RIGHT_PARENTHESIS for LEFT_PARENTHESIS, after version specifier
opencv-python (>=3.) ; extra == 'all'
~~~~^
Please use pip<24.1 if you need to use this version.
INFO: pip is looking at multiple versions of f110-gym to determine which version is compatible with other requirements. This could take a while.
ERROR: Could not find a version that satisfies the requirement gym==0.19.0 (from f110-gym) (from versions: 0.0.2, 0.0.3, 0.0.4, 0.0.5, 0.0.6, 0.0.7, 0.1.0, 0.1.1, 0.1.2, 0.1.3, 0.1.4, 0.1.5, 0.1.6, 0.1.7, 0.2.0, 0.2.1, 0.2.2, 0.2.3, 0.2.4, 0.2.5, 0.2.6, 0.2.7, 0.2.8, 0.2.9, 0.2.10, 0.2.11, 0.2.12, 0.3.0, 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.4, 0.4.5, 0.4.6, 0.4.8, 0.4.9, 0.4.10, 0.5.0, 0.5.1, 0.5.2, 0.5.3, 0.5.4, 0.5.5, 0.5.6, 0.5.7, 0.6.0, 0.7.0, 0.7.1, 0.7.2, 0.7.3, 0.7.4, 0.8.0.dev0, 0.8.0, 0.8.1, 0.8.2, 0.9.0, 0.9.1, 0.9.2, 0.9.3, 0.9.4, 0.9.5, 0.9.6, 0.9.7, 0.10.0, 0.10.1, 0.10.2, 0.10.3, 0.10.4, 0.10.5, 0.10.8, 0.10.9, 0.10.11, 0.11.0, 0.12.0, 0.12.1, 0.12.4, 0.12.5, 0.12.6, 0.13.0, 0.13.1, 0.14.0, 0.15.3, 0.15.4, 0.15.6, 0.15.7, 0.16.0, 0.17.0, 0.17.1, 0.17.2, 0.17.3, 0.18.0, 0.18.3, 0.19.0, 0.20.0, 0.21.0, 0.22.0, 0.23.0, 0.23.1, 0.24.0, 0.24.1, 0.25.0, 0.25.1, 0.25.2, 0.26.0, 0.26.1, 0.26.2)
ERROR: No matching distribution found for gym==0.19.0

As the warning suggests, this is due to incompatibility between pip versions >=24.1 and gym version 0.19.0. You can resolve this by downgrading the pip used in the virtualenv:

```
pip install --upgrade pip==24.0
```

The installation steps are then as follows:

```bash
virtualenv gym_env
source gym_env/bin/activate
pip install --upgrade pip==24.0
git clone https://github.com/f1tenth/f1tenth_gym.git
cd f1tenth_gym
pip install -e .
```

## 🐧 Running on WSL2 with Docker Compose
If you're using Windows with WSL2, you can run this project smoothly using Docker Compose and an X Server for graphical rendering.

1️⃣ Install an X Server on Windows
To render the simulator's graphics (e.g., PyOpenGL, Pyglet, pygame), you'll need an X Server installed on your host system.

Recommended options:

🧩 VcXsrv (free, common choice)

💠 X410 (paid, very stable)

🌀 GWSL (free, GUI-oriented)

You can read a guide here:
👉 https://www.guide2wsl.com/x11/

✅ While launching your X Server, make sure to:

Disable access control

Disable native OpenGL

Allow network connections

2️⃣ Set up your WSL environment
Add the following lines to your ~/.bashrc or ~/.zshrc to make graphical apps work inside Docker containers:

```bash
export DISPLAY=host.docker.internal:0.0
export LIBGL_ALWAYS_INDIRECT=1
```

Then, reload your shell:

```bash
source ~/.bashrc # or ~/.zshrc
```

Optional Test: make sure your X Server is working with:

```bash
sudo apt install x11-apps
xclock
```
If a clock appears, you're good to go 🕒✅

3️⃣ Build and launch the container
We provide a ready-to-use Docker Compose file. To build and start the environment:

```bash
docker-compose build --no-cache
docker-compose up -d
docker-compose exec f1tenth_gym bash
```

4️⃣ Run the simulator
Once inside the container, navigate to the examples and launch the simulation:

```bash
cd examples
python3 waypoint_follow.py
```

### 🛠️ Troubleshooting
If the container fails to connect to the display, run this from WSL:

```bash
xhost +local:
```

If you see NoSuchDisplayException, double-check that the DISPLAY variable matches your host’s IP or use host.docker.internal.



## Citing
If you find this Gym environment useful, please consider citing:

```
@inproceedings{okelly2020f1tenth,
title={F1TENTH: An Open-source Evaluation Environment for Continuous Control and Reinforcement Learning},
author={O’Kelly, Matthew and Zheng, Hongrui and Karthik, Dhruv and Mangharam, Rahul},
booktitle={NeurIPS 2019 Competition and Demonstration Track},
pages={77--89},
year={2020},
organization={PMLR}
}
```
21 changes: 21 additions & 0 deletions docker-compose.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
version: '3.8'

services:
f1tenth_gym:
build:
context: . # Asume que el Dockerfile está en el mismo directorio
dockerfile: Dockerfile
image: f1tenth_gym:latest
container_name: f1tenth_gym_container
volumes:
- .:/f1tenth_gym # Monta el código local para desarrollo interactivo
- /tmp/.X11-unix:/tmp/.X11-unix
environment:
- DISPLAY=${DISPLAY}
- LIBGL_ALWAYS_INDIRECT=1
- NVIDIA_VISIBLE_DEVICES=all
- NVIDIA_DRIVER_CAPABILITIES=all
runtime: nvidia # Requiere nvidia-docker2 o Docker >= 19.03 con soporte de GPU
network_mode: host # Útil para acceso a simuladores locales tipo ROS o GUI X11
stdin_open: true
tty: true