Skip to content

Commit 1eb0da0

Browse files
juelgjuelg
committed
docs: improved readme
1 parent 90f23dc commit 1eb0da0

1 file changed

Lines changed: 69 additions & 35 deletions

File tree

‎README.md‎

Lines changed: 69 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,43 @@
1-
<img src="https://raw.githubusercontent.com/RobotControlStack/robotcontrolstack.github.io/refs/heads/master/static/images/rcs_logo_line.svg" alt="rcs logo" width="100%">
1+
<div align="center">
2+
<img src="https://raw.githubusercontent.com/RobotControlStack/robotcontrolstack.github.io/refs/heads/master/static/images/rcs_logo_line.svg" alt="rcs logo" width="60%">
23

3-
**Robot Control Stack (RCS)** is a flexible Gymnasium wrapper-based robot control interface made for robot learning and specifically Vision-Language-Action (VLA) models.
4-
It unifies MuJoCo simulation and real world robot control with four supported robots: FR3/Panda, xArm7, UR5e and SO101.
5-
It ships with several pre-build apps including data collection via teleoperation and remote model inference via [vlagents](https://github.com/RobotControlStack/vlagents).
4+
### A lean, ROS-free Sim-to-Real framework for training and deploying Vision-Language-Action (VLA) models and Reinforcement Learning (RL) agents.
65

6+
[![Documentation](https://img.shields.io/badge/docs-robotcontrolstack.org-blue.svg)](https://robotcontrolstack.org)
7+
[![Paper](https://img.shields.io/badge/paper-ICRA_2026-green.svg)](https://robotcontrolstack.github.io/)
8+
[![Release](https://img.shields.io/github/v/release/RobotControlStack/robot-control-stack?color=orange)](https://github.com/RobotControlStack/robot-control-stack/releases)
9+
[![License](https://img.shields.io/github/license/RobotControlStack/robot-control-stack?color=blueviolet)](https://github.com/RobotControlStack/robot-control-stack/blob/main/LICENSE)
10+
[![CI Status](https://github.com/RobotControlStack/robot-control-stack/actions/workflows/ci.yaml/badge.svg)](https://github.com/RobotControlStack/robot-control-stack/actions)
11+
</div>
712

8-
<video
9-
src="https://github.com/user-attachments/assets/21ac29af-373b-46aa-8a08-ae0ae8c0e235"
10-
autoplay
11-
muted
12-
loop
13-
playsinline
14-
style="max-width: 100%;">
15-
</video>
13+
---
1614

17-
## Wrapper-Based Architecture
15+
**Robot Control Stack (RCS)** is a flexible, native [Gymnasium](https://gymnasium.farama.org/) wrapper-based robot control interface designed specifically for modern robot learning and Vision-Language-Action (VLA) models.
16+
17+
It completely unifies **MuJoCo simulation** and real-world physical robot control into a single, seamless API. Currently, RCS natively supports four robots out-of-the-box: **Franka FR3/Panda, xArm7, UR5e, and SO101.**
18+
19+
![RCS Demo](https://raw.githubusercontent.com/RobotControlStack/robotcontrolstack.github.io/refs/heads/master/static/videos/grid.webp)
20+
21+
## 🚀 Why use Robot Control Stack?
22+
23+
Traditional robotics middleware (like ROS/ROS2) and complex motion planning pipelines (like MoveIt or standard `ros2_control`) are built for asynchronous, distributed systems. This often becomes a massive bottleneck when attempting to train modern, synchronous machine learning models.
24+
25+
**RCS is built differently:**
26+
* **Zero ROS Overhead:** No complex message-passing, middleware, or network configuration required. Run natively in Python with a lightweight C++ backend.
27+
* **Frictionless Sim-to-Real:** Train your Reinforcement Learning or VLA policies in our MuJoCo Gymnasium wrapper, and deploy the *exact same code* directly to physical hardware.
28+
* **Synchronous Execution:** Optimized specifically for the highly parallelized, synchronous data collection required by modern ML workflows.
29+
* **Ready-to-Use Apps:** Ships with pre-built applications for data collection via teleoperation and remote model inference via [vlagents](https://github.com/RobotControlStack/vlagents).
30+
31+
## 🧩 Wrapper-Based Architecture
32+
33+
RCS utilizes a highly modular, wrapper-based architecture, allowing you to easily stack capabilities (cameras, grippers, action spaces) as needed.
1834

1935
<img src="docs/_static/rcs_architecture_small.svg" alt="rcs architecture diagram" width="100%">
2036

21-
## Example
22-
Flexibly compose your gym environment to your needs:
37+
## 💻 Example: Composing your Environment
38+
39+
Flexibly compose your Gymnasium environment to fit your exact training needs. *For common environment compositions, factory functions such as `rcs.envs.creators.SimEnvCreator` are provided.*
40+
2341
```python
2442
from time import sleep
2543

@@ -93,18 +111,21 @@ if __name__ == "__main__":
93111
act = {"tquat": [0.01, 0, 0, 0, 0, 0, 1], "gripper": [0]}
94112
obs, reward, terminated, truncated, info = env.step(act)
95113
print(obs)
114+
96115
```
97-
For common environment compositions factory functions such as `rcs.envs.creators.SimEnvCreator` are provided.
98-
This and other example can be found in the [examples](examples/) folder.
99116

100-
## Installation
117+
> **Note:** This and other examples can be found in the [`examples/`]() folder.
118+
119+
## 🛠️ Installation
120+
101121
### From Source
102122

103-
Make sure that common build tools i.e. `build-essential` and a C++ compiler like `gcc` or `clang` are installed on your system/conda/docker.
123+
Make sure that common build tools (i.e., `build-essential`) and a C++ compiler like `gcc` or `clang` are installed on your system/conda/docker.
124+
125+
*RCS works best in Python 3.11, and all extensions have been tested to work in 3.11.*
104126

105-
RCS works best in python 3.11, all extensions have been tested to work in 3.11.
106-
- For python >3.11 the `rcs_realsense` extension wont work for the pyrealsense2 version that RCS is using.
107-
- For python >3.12 the ompl python module is not available on pypi as of now. If OMPL is not used, it's save to remove this dependency in the pyproject.toml.
127+
* *For Python >3.11: The `rcs_realsense` extension won't work due to the `pyrealsense2` version RCS utilizes.*
128+
* *For Python >3.12: The `ompl` python module is currently not available on PyPI. If OMPL is not used, it is safe to remove this dependency in `pyproject.toml`.*
108129

109130
```shell
110131
# setup environment
@@ -117,32 +138,43 @@ pip install --group build_deps
117138

118139
# install rcs
119140
pip install -ve .
141+
120142
```
121143

122144
### Via PyPI/pip
123-
Coming soon...
124145

125-
## Hardware Extensions
146+
*Coming soon...*
126147

127-
RCS supports various hardware extensions (e.g., FR3, xArm7, RealSense). These are located in the `extensions` directory.
148+
## 🦾 Hardware Extensions
128149

129-
To install an extension:
150+
RCS supports various hardware extensions to seamlessly connect your policies to the real world (e.g., FR3, xArm7, RealSense). These are located in the `extensions` directory.
151+
152+
To install a specific robot extension (example for Franka FR3):
130153

131154
```shell
132155
pip install -ve extensions/rcs_fr3
133156
```
134157

135-
For a full list of extensions and detailed documentation, visit [robotcontrolstack.org/extensions](https://robotcontrolstack.org/extensions).
158+
For a full list of extensions and detailed documentation, visit **[robotcontrolstack.org/extensions](https://robotcontrolstack.org/extensions)**.
159+
160+
## ⚠️ Troubleshooting & FAQ
161+
* **License error or group argument not found during installation?** Make sure you are using a pip version `>=25.1` and setuptools version `>=45`.
162+
* **Dependency error during installation?** Make sure you are using Python 3.11. RCS extensions currently do not support 3.12+ due to OMPL and RealSense dependencies.
163+
* **Simulation is running too slow?** Check that you have enable on-demand rendering: `SimCameraSet(..., render_on_demand=True)` to render camera frames only once per step. Resolution and number of cameras in the scene has a large impact on simulation speed. Make sure to use a decent GPU when rendering is enabled.
164+
136165

137-
## Documentation
138-
For full documentation, including installation, usage, and API reference, please visit:
139-
**[robotcontrolstack.org](https://robotcontrolstack.org)**
166+
## 📚 Documentation
140167

141-
## Contribution
142-
For contribution guidelines checkout [robotcontrolstack.org/contributing](https://robotcontrolstack.org/contributing)
168+
For full documentation, including advanced installation, modular usage, and API references, please visit:
169+
👉 **[robotcontrolstack.org](https://robotcontrolstack.org)**
143170

144-
## Citation
145-
If you find RCS useful for your academic work, please consider citing it:
171+
## 🤝 Contribution
172+
173+
We welcome contributions from the robotics and ML community! For contribution guidelines, please check out **[robotcontrolstack.org/contributing](https://robotcontrolstack.org/contributing)**.
174+
175+
## 📝 Citation
176+
177+
If you find RCS useful for your academic work please consider citing it:
146178

147179
```bibtex
148180
@inproceedings{juelg2026robotcontrolstack,
@@ -153,4 +185,6 @@ If you find RCS useful for your academic work, please consider citing it:
153185
note={Accepted for publication.}
154186
}
155187
```
156-
For more scientific info, visit the [paper website](https://robotcontrolstack.github.io/).
188+
189+
For more scientific information and supplementary videos, visit the **[paper website](https://robotcontrolstack.github.io/)**.
190+

0 commit comments

Comments
 (0)