Skip to content

Commit 38d01bd

Browse files
SuhanVerseSuhanVerse
committed
docs: update readme for install guide
1 parent 1ecff3d commit 38d01bd

1 file changed

Lines changed: 298 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 298 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,298 @@
1-
# Learning-ROS2
1+
# 🐢 Learning-ROS2
2+
3+
A personal workspace for learning and experimenting with **ROS 2 Humble** using Docker, GPU acceleration (NVIDIA RTX 4060), and VS Code integration. This README documents setup, installation, and usage so anyone can reproduce the environment.
4+
5+
---
6+
7+
## 📖 What is ROS 2?
8+
9+
ROS 2 (Robot Operating System 2) is a flexible framework for writing robot software. It provides:
10+
11+
- A publish/subscribe communication system between nodes
12+
- Tools for simulation (Gazebo, RViz2)
13+
- Libraries for robotics, AI, and machine learning integration
14+
- Support for C++ and Python development
15+
16+
---
17+
18+
## 📚 Table of contents
19+
20+
- [Overview](#-overview)
21+
- [Design choices](#-design-choices)
22+
- [Prerequisites (Host: Manjaro Linux)](#-prerequisites-host-manjaro-linux)
23+
- [Recommended (Docker) installation](#-recommended-docker-installation)
24+
25+
- [NVIDIA / GPU passthrough](#nvidia--gpu-passthrough)
26+
- [Docker Compose example](#docker-compose-example)
27+
- [Common container workflow](#common-container-workflow)
28+
29+
- [Developing inside the container (VS Code)](#developing-inside-the-container-vs-code)
30+
- [Building & running ROS 2 packages](#building--running-ros-2-packages)
31+
- [Alternative installation methods](#-alternative-installation-methods)
32+
- [Tips & troubleshooting](#tips--troubleshooting)
33+
- [Resources & further reading](#resources--further-reading)
34+
- [License](#license)
35+
36+
---
37+
38+
## 🏁 Overview
39+
40+
This repository prioritizes a **Docker-first** approach so you get a reproducible, clean development environment with minimal interference from host packages. That also makes GPU acceleration, VS Code integration, and CI-friendly builds much simpler.
41+
42+
**Why Docker?**
43+
44+
- Isolates ROS 2 Humble environment from host package manager (Manjaro)
45+
- Easier to enable NVIDIA GPU support via `--gpus` and `nvidia-container-toolkit`
46+
- Quick reproducible setup for teammates or future you
47+
48+
---
49+
50+
## ⚙️ Design choices
51+
52+
1. **Docker (Recommended)** – reproducible, GPU-enabled, minimal host changes.
53+
2. **AUR packages** – quicker to get binaries but can break with rolling releases.
54+
3. **Source build** – most flexible but time-consuming; only recommended for maintainers or for experimental changes to core packages.
55+
56+
---
57+
58+
## 🧾 Prerequisites (Host: Manjaro Linux)
59+
60+
These steps assume you have an NVIDIA GPU (RTX 4060) and want GPU acceleration inside the container.
61+
62+
1. Install NVIDIA drivers (host):
63+
64+
```bash
65+
# verify drivers are active
66+
nvidia-smi
67+
```
68+
69+
2. Install Docker and enable the service:
70+
71+
```bash
72+
sudo pacman -Syu docker
73+
sudo systemctl enable --now docker
74+
```
75+
76+
3. Install NVIDIA container tooling (on Manjaro):
77+
78+
```bash
79+
sudo pacman -S nvidia-container-toolkit
80+
sudo nvidia-ctk runtime configure --runtime=docker
81+
sudo systemctl restart docker
82+
```
83+
84+
4. Test GPU passthrough:
85+
86+
```bash
87+
docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi
88+
```
89+
90+
You should see your RTX 4060 listed in the container output.
91+
92+
---
93+
94+
## ✅ Recommended (Docker) installation
95+
96+
### 1) Clone this repository
97+
98+
```bash
99+
git clone https://github.com/SuhanVerse/Learning-ROS2.git
100+
cd Learning-ROS2
101+
```
102+
103+
### 2) Example Dockerfile (optional)
104+
105+
If you want a custom image (base: ubuntu 22.04 + ROS Humble):
106+
107+
```dockerfile
108+
# Dockerfile
109+
FROM ubuntu:22.04
110+
ARG DEBIAN_FRONTEND=noninteractive
111+
112+
# Install basic dependencies and ROS 2 Humble
113+
RUN apt-get update && apt-get install -y \
114+
curl gnupg2 lsb-release locales sudo \
115+
&& locale-gen en_US.UTF-8
116+
117+
# Add ROS 2 repo and install (shortened for brevity)
118+
# ... follow official ROS 2 instructions to add keys and apt sources
119+
120+
# Create a user (optional)
121+
RUN useradd -m developer && echo "developer:developer" | chpasswd && adduser developer sudo
122+
USER developer
123+
WORKDIR /home/developer
124+
125+
CMD ["/bin/bash"]
126+
```
127+
128+
> Tip: You can start from `ros:humble` or `ros:humble-ros-base` official images for faster iteration.
129+
130+
### 3) docker-compose.yml (example)
131+
132+
A minimal `docker-compose.yml` for development with GPU support:
133+
134+
```yaml
135+
version: "3.8"
136+
services:
137+
ros2_dev:
138+
image: ros:humble
139+
container_name: ros2_dev
140+
tty: true
141+
privileged: true
142+
network_mode: "host"
143+
environment:
144+
- DISPLAY=${DISPLAY}
145+
- QT_X11_NO_MITSHM=1
146+
volumes:
147+
- $HOME/LEARN:/root/LEARN
148+
- /tmp/.X11-unix:/tmp/.X11-unix:rw
149+
deploy:
150+
resources:
151+
reservations:
152+
devices:
153+
- capabilities: [gpu]
154+
runtime: nvidia
155+
command: /bin/bash
156+
```
157+
158+
**Start the container:**
159+
160+
```bash
161+
docker compose up -d --build
162+
```
163+
164+
Attach to the container shell:
165+
166+
```bash
167+
docker exec -it ros2_dev bash
168+
```
169+
170+
Inside the container, source ROS 2:
171+
172+
```bash
173+
source /opt/ros/humble/setup.bash
174+
```
175+
176+
---
177+
178+
## 🖥️ Developing with VS Code
179+
180+
You can configure VS Code to open a terminal that drops you into the running container with your workspace sourced. Examples for `.vscode/settings.json` and `.vscode/tasks.json` are shown below.
181+
182+
**Example: `settings.json` terminal profile**
183+
184+
```json
185+
{
186+
"terminal.integrated.profiles.linux": {
187+
"ROS2-Docker": {
188+
"path": "/bin/bash",
189+
"args": [
190+
"-c",
191+
"docker exec -it ros2_dev bash -c '(source /opt/ros/humble/setup.bash && source /root/LEARN/install/setup.bash) || true; exec bash'"
192+
]
193+
}
194+
},
195+
"terminal.integrated.defaultProfile.linux": "ROS2-Docker"
196+
}
197+
```
198+
199+
**Example: `tasks.json` snippets for running talker/listener**
200+
201+
```json
202+
{
203+
"version": "2.0.0",
204+
"tasks": [
205+
{
206+
"label": "run talker",
207+
"type": "shell",
208+
"command": "docker exec -it ros2_dev bash -c 'source /opt/ros/humble/setup.bash && source /root/LEARN/install/setup.bash && ros2 run demo_nodes_cpp talker'"
209+
},
210+
{
211+
"label": "run listener",
212+
"type": "shell",
213+
"command": "docker exec -it ros2_dev bash -c 'source /opt/ros/humble/setup.bash && source /root/LEARN/install/setup.bash && ros2 run demo_nodes_cpp listener'"
214+
}
215+
]
216+
}
217+
```
218+
219+
> Tip: Use the Remote - Containers extension if you prefer VS Code to manage containers for you.
220+
221+
---
222+
223+
## 🛠 Building your workspace (inside container)
224+
225+
Assuming your ROS 2 workspace is at `/root/LEARN` inside the container:
226+
227+
```bash
228+
# inside container
229+
cd /root/LEARN
230+
colcon build
231+
source install/setup.bash
232+
```
233+
234+
Install extra packages if needed (example):
235+
236+
```bash
237+
apt update && apt install -y ros-humble-turtlesim
238+
```
239+
240+
Run the simulator:
241+
242+
```bash
243+
# Terminal 1
244+
ros2 run turtlesim turtlesim_node
245+
246+
# Terminal 2
247+
ros2 run demo_nodes_cpp talker
248+
ros2 run demo_nodes_cpp listener
249+
```
250+
251+
---
252+
253+
## 🔁 Common workflow (quick checklist)
254+
255+
- Start container: `docker compose up -d`
256+
- Attach shell: `docker exec -it ros2_dev bash`
257+
- Source ROS 2 and workspace: `source /opt/ros/humble/setup.bash && source /root/LEARN/install/setup.bash`
258+
- Build: `colcon build`
259+
- Run nodes with `ros2 run` or `ros2 launch`
260+
261+
---
262+
263+
## 🧭 Alternative installation methods on Manjaro
264+
265+
1. **AUR packages** – search for `ros-humble-*` packages in AUR. Good for quick native installs but may require maintenance.
266+
2. **Source build** – follow official ROS 2 instructions to build from source. This is useful if you need bleeding-edge patches or custom core changes.
267+
268+
---
269+
270+
## 🛠 Tips & troubleshooting
271+
272+
- `nvidia-smi` not visible in container: ensure `nvidia-container-toolkit` is installed and `docker run --gpus all` works.
273+
- Permission issues with Docker: add your user to the `docker` group or use `sudo` for Docker commands.
274+
- `DISPLAY` issues for GUI apps: ensure X11 socket is mounted (`/tmp/.X11-unix`) and `xhost +local:root` (or better: more secure alternatives).
275+
- If `colcon build` fails: check package `package.xml` and `CMakeLists.txt` for missing dependencies, and `rosdep` can help install OS dependencies.
276+
277+
---
278+
279+
## 🔗 Resources & further reading
280+
281+
- ROS 2 official docs: [https://docs.ros.org/en/humble/](https://docs.ros.org/en/humble/)
282+
- Colcon build tool: [https://colcon.readthedocs.io/](https://colcon.readthedocs.io/)
283+
- NVIDIA Container Toolkit: [https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/)
284+
- ROS 2 tutorials (beginner-friendly)
285+
286+
---
287+
288+
## 🤝 Contributing
289+
290+
Feel free to open issues or PRs if you have suggestions, updates for newer ROS 2 distributions or better Docker setups.
291+
292+
---
293+
294+
## 📜 License
295+
296+
Licensed under the **Apache-2.0** License.
297+
298+
---

0 commit comments

Comments
 (0)