Skip to content

Commit 4802cf3

Browse files
j3soonj3soon
authored
Merge pull request #64 from j3soon/docs/website
Add document website
2 parents cf63c8a + c2f7299 commit 4802cf3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+2467
-1215
lines changed

‎.github/workflows/build-docs.yml

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Ref: https://squidfunk.github.io/mkdocs-material/publishing-your-site/
2+
name: Build Documentation
3+
on:
4+
push:
5+
branches:
6+
- master
7+
- main
8+
permissions:
9+
contents: write
10+
jobs:
11+
deploy:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v3
15+
# Ref: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#note-when-using-build-environments
16+
with:
17+
fetch-depth: '0'
18+
- uses: actions/setup-python@v4
19+
with:
20+
python-version: 3.x
21+
- uses: actions/cache@v2
22+
with:
23+
key: ${{ github.ref }}
24+
path: .cache
25+
- run: pip install -r requirements.txt
26+
- run: mkdocs gh-deploy --force
27+
# Ref: https://github.com/ojacques/mkdocs-git-committers-plugin-2
28+
# Ref: https://github.com/ojacques/mkdocs-git-committers-plugin-2/issues/51#issuecomment-1951450239
29+
env:
30+
MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.MKDOCS_GIT_COMMITTERS_APIKEY }}
31+
32+
# DONE (Deploy the site):
33+
# - In the forked GitHub repo page, go to `Settings > Pages` and change `Branch` to `gh-pages`:
34+
# https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
35+
# - Visit the site at `https://<username>.github.io/<repository>`
36+
# - For using custom domain, refer to the link below:
37+
# https://www.mkdocs.org/user-guide/deploying-your-docs/#custom-domains
38+
# - To publish the site to other platforms, refer to the link below:
39+
# https://squidfunk.github.io/mkdocs-material/publishing-your-site/
40+
# - Take Netlify as an example, follow:
41+
# https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-netlify/
42+
# Make sure to also set up the secrets:
43+
# https://docs.netlify.com/environment-variables/get-started/#site-environment-variables

‎README.md

Lines changed: 28 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,25 +6,37 @@ A repo containing essential ROS2 Humble features for controlling Autonomous Mobi
66

77
> Please note that this repo is under rapid development. The code is not guaranteed to be stable, and breaking changes may occur.
88
9-
## Pre-built Docker Images
9+
The documentation is hosted on <https://j3soon.github.io/ros2-essentials/>.
1010

11-
The following Docker images can be pulled by `docker pull <IMAGE_NAME>` or by `docker compose pull` in the corresponding directory.
11+
## Pre-built Workspaces
12+
13+
Pre-built Docker images for each workspace can be pulled by running `docker compose pull` in the corresponding workspace directory.
1214

1315
Pulling the pre-built Docker images can bypass the time-consuming building process (for both docker compose & devcontainers).
1416

15-
| Docker Image | amd64 | arm64 | Notes | Maintainer |
16-
|--------------|-------|-------|-------|------------|
17-
| `j3soon/ros2-template-ws` [[tags](https://hub.docker.com/r/j3soon/ros2-template-ws/tags)][[code](./template_ws)] | ✔️ | ✔️ | | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
18-
| `j3soon/ros2-orbslam3-ws` [[tags](https://hub.docker.com/r/j3soon/ros2-orbslam3-ws/tags)][[code](./orbslam3_ws)] | ✔️ | ❌ | | [Assume Zhan](https://github.com/Assume-Zhan) |
19-
| `j3soon/ros2-rtabmap-ws` [[tags](https://hub.docker.com/r/j3soon/ros2-rtabmap-ws/tags)][[code](./rtabmap_ws)] | ✔️ | ❌ | | [Assume Zhan](https://github.com/Assume-Zhan) |
20-
| `j3soon/ros2-ros1-bridge-ws` [[tags](https://hub.docker.com/r/j3soon/ros2-ros1-bridge-ws/tags)][[code](./ros1_bridge_ws)] | ✔️ | ✔️ | Skip linting | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
21-
| `j3soon/ros2-ros1-bridge-build-ws` [[tags](https://hub.docker.com/r/j3soon/ros2-ros1-bridge-build-ws/tags)][[code](./ros1_bridge_ws)] | ✔️ | ✔️ | Skip linting | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
22-
| `j3soon/ros2-cartographer-ws` [[tags](https://hub.docker.com/r/j3soon/ros2-cartographer-ws/tags)][[code](./cartographer_ws)] | ✔️ | ✔️ | | [Assume Zhan](https://github.com/Assume-Zhan) |
23-
| `j3soon/ros2-husky-ws` [[tags](https://hub.docker.com/r/j3soon/ros2-husky-ws/tags)][[code](./husky_ws)] | ✔️ | ✔️ | Real-world support | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
24-
| `j3soon/ros2-kobuki-ws` [[tags](https://hub.docker.com/r/j3soon/ros2-kobuki-ws/tags)][[code](./kobuki_ws)] | ✔️ | ✔️ | Real-world support | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
25-
| `j3soon/ros2-vlp-ws` [[tags](https://hub.docker.com/r/j3soon/ros2-vlp-ws/tags)][[code](./vlp_ws)] | ✔️ | ✔️ | Real-world support | [Assume Zhan](https://github.com/Assume-Zhan) |
26-
| `j3soon/ros2-gazebo-world-ws` [[tags](https://hub.docker.com/r/j3soon/ros2-gazebo-world-ws/tags)][[code](./gazebo_world_ws)] | ✔️ | ❌️ | | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
27-
| `j3soon/ros2-aloha-ws` [[tags](https://hub.docker.com/r/j3soon/ros2-aloha-ws/tags)][[code](./aloha_ws)] | ✔️ | ✔️ | Simulation only | |
17+
| Workspace | amd64 | arm64 | Notes | Maintainer |
18+
|-----------|-------|-------|-------|------------|
19+
| [Template](https://j3soon.github.io/ros2-essentials/template-ws/) | ✔️ | ✔️ | | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
20+
| [ORB-SLAM3](https://j3soon.github.io/ros2-essentials/orbslam3_ws) | ✔️ | ❌ | | [Assume Zhan](https://github.com/Assume-Zhan) |
21+
| [RTAB-Map](https://j3soon.github.io/ros2-essentials/rtabmap_ws/) | ✔️ | ❌ | | [Assume Zhan](https://github.com/Assume-Zhan) |
22+
| [ROS1 Bridge](https://j3soon.github.io/ros2-essentials/ros1_bridge_ws/) | ✔️ | ✔️ | Skip linting | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
23+
| [Cartographer](https://j3soon.github.io/ros2-essentials/cartographer_ws/) | ✔️ | ✔️ | | [Assume Zhan](https://github.com/Assume-Zhan) |
24+
| [Clearpath Husky](https://j3soon.github.io/ros2-essentials/husky_ws/) | ✔️ | ✔️ | Real-world support | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
25+
| [Yujin Robot Kobuki](https://j3soon.github.io/ros2-essentials/kobuki_ws/) | ✔️ | ✔️ | Real-world support | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
26+
| [Velodyne VLP-16](https://j3soon.github.io/ros2-essentials/vlp_ws/) | ✔️ | ✔️ | Real-world support | [Assume Zhan](https://github.com/Assume-Zhan) |
27+
| [Gazebo World](https://j3soon.github.io/ros2-essentials/gazebo_world_ws/) | ✔️ | ❌️ | | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
28+
| [ALOHA](https://j3soon.github.io/ros2-essentials/aloha_ws/) | ✔️ | ✔️ | Simulation only | |
29+
30+
## Building Documentation
31+
32+
```sh
33+
virtualenv venv -p python3
34+
source venv/bin/activate
35+
cd docs
36+
pip install -r requirements.txt
37+
mkdocs serve
38+
# Go to https://127.0.0.1:8000 to view the site.
39+
```
2840

2941
## Acknowledgement
3042

@@ -39,7 +51,7 @@ Disclaimer: this is not an official NVIDIA product.
3951

4052
## License
4153

42-
All modifications are licensed under [Apache License 2.0](./LICENSE).
54+
All modifications are licensed under [Apache License 2.0](https://github.com/j3soon/ros2-essentials/blob/main/LICENSE).
4355

4456
However, this repository includes many dependencies released under different licenses. For information on these licenses, please check the commit history. Make sure to review the license of each dependency before using this repository.
4557

‎aloha_ws/README.md

Lines changed: 2 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,3 @@
1-
# aloha_ws
1+
# ROS 2 Essentials Workspace
22

3-
## Start Container
4-
5-
```sh
6-
cd ~/ros2-essentials/aloha_ws/docker
7-
xhost +local:docker
8-
docker compose up
9-
# The first build will take a while (~10 mins), please wait patiently.
10-
```
11-
12-
The commands in the following sections assume that you are inside the Docker container:
13-
14-
```sh
15-
# in a new terminal
16-
docker exec -it ros2-aloha-ws bash
17-
```
18-
19-
## View Robot Model in RViz
20-
21-
```sh
22-
ros2 launch interbotix_xsarm_descriptions xsarm_description.launch.py robot_model:=vx300s use_joint_pub_gui:=true
23-
```
24-
25-
It is worth noting that `aloha_vx300s.urdf.xacro` and `vx300s.urdf.xacro` files are identical. We opt to use `vx300s` since `aloha_vx300s` seems to lack corresponding configs, such as those for MoveIt 2.
26-
27-
![](figure/rviz.png)
28-
29-
## View Robot Model in Gazebo
30-
31-
```sh
32-
ros2 launch interbotix_xsarm_sim xsarm_gz_classic.launch.py robot_model:=vx300s
33-
```
34-
35-
## ROS 2 Control
36-
37-
```sh
38-
ros2 launch interbotix_xsarm_control xsarm_control.launch.py robot_model:=vx300s use_sim:=true
39-
# and then use the `Interbotix Control Panel`.
40-
```
41-
42-
![](figure/ros2-control.png)
43-
44-
## MoveIt 2 with RViz
45-
46-
```sh
47-
ros2 launch interbotix_xsarm_moveit xsarm_moveit.launch.py robot_model:=vx300s hardware_type:=fake
48-
```
49-
50-
![](figure/moveit-rviz.png)
51-
52-
## MoveIt 2 with Gazebo
53-
54-
```sh
55-
ros2 launch interbotix_xsarm_moveit xsarm_moveit.launch.py robot_model:=vx300s hardware_type:=gz_classic
56-
```
57-
58-
![](figure/moveit-gazebo.png)
59-
60-
## MoveIt 2 with Isaac Sim
61-
62-
Prepare USD files:
63-
64-
```sh
65-
cd /home/ros2-essentials/aloha_ws/isaacsim/scripts
66-
./create_urdf_from_xacro.sh
67-
python3 create_vx300s_from_urdf.py
68-
python3 create_vx300s_with_omnigraph.py
69-
```
70-
71-
and run:
72-
73-
```sh
74-
ros2 launch interbotix_xsarm_moveit xsarm_moveit.launch.py robot_model:=vx300s hardware_type:=isaac
75-
# and then move the target and use the `MotionPlanning` panel.
76-
```
77-
78-
![](figure/moveit-isaacsim.png)
79-
80-
### Debugging with Isaac Sim
81-
82-
The Isaac Sim app can be launched with:
83-
84-
```sh
85-
isaacsim omni.isaac.sim
86-
```
87-
88-
Keep in mind that the standalone scripts can be easily debugged in Isaac Sim's `Script Editor`.
89-
Simply copy the code, omitting anything related to SimulationApp (remove the beginning and end),
90-
and paste to the `Script Editor` and run it.
91-
92-
To open pre-configured USD file with OmniGraph:
93-
94-
- `File > Open` and click `My Computer`, then in `File name:` type:
95-
```
96-
/home/ros2-essentials/aloha_ws/isaacsim/assets/vx300s_og.usd
97-
```
98-
- Click `Window > Visual Scripting > Action Graph`
99-
- In the `Action Graph` tab, click `Edit Action Graph` and select `/ActionGraph`
100-
- Click `Play (SPACE)`
101-
102-
View the current joint states:
103-
104-
```sh
105-
# in a new terminal
106-
docker exec -it ros2-aloha-ws bash
107-
ros2 topic echo /vx300s/joint_states
108-
```
109-
110-
A specific world can also be directly launched and played with:
111-
112-
```sh
113-
isaacsim omni.isaac.sim --exec '/home/ros2-essentials/aloha_ws/isaacsim/scripts/open_isaacsim_stage.py --path /home/ros2-essentials/aloha_ws/isaacsim/assets/vx300s_og.usd'
114-
```
115-
116-
To access Nucleus from Isaac Sim, you should [install Nucleus](https://docs.omniverse.nvidia.com/nucleus/latest/workstation/installation.html) with default username/password `admin:admin` on your host machine or connect to an external Nucleus server.
117-
118-
## References
119-
120-
- [Interbotix X-Series Arms \| Trossen Robotics Documentation](https://docs.trossenrobotics.com/interbotix_xsarms_docs/index.html)
121-
- [ROS 2 Interface](https://docs.trossenrobotics.com/interbotix_xsarms_docs/ros_interface/ros2.html)
122-
- [ROS 2 Standard Software Setup](https://docs.trossenrobotics.com/interbotix_xsarms_docs/ros_interface/ros2/software_setup.html)
123-
- [ROS 2 Open Source Packages](https://docs.trossenrobotics.com/interbotix_xsarms_docs/ros2_packages.html)
124-
- [Stationary ALOHA Software Setup \| Trossen Robotics Documentation](https://docs.trossenrobotics.com/aloha_docs/getting_started/stationary/software_setup.html)
3+
Please visit <https://j3soon.github.io/ros2-essentials/> for documentation.

‎cartographer_ws/README.md

Lines changed: 2 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,78 +1,3 @@
1-
# ROS2 Cartographer
1+
# ROS 2 Essentials Workspace
22

3-
### Run with docker
4-
5-
```bash
6-
git clone https://github.com/j3soon/ros2-essentials.git
7-
```
8-
9-
```bash
10-
cd ros2-essentials/cartographer_ws/docker
11-
docker compose pull
12-
docker compose up -d --build
13-
```
14-
15-
### Simple Test With Turtlebot3
16-
17-
- Attach to the container
18-
19-
```sh
20-
docker attach ros2-cartographer-ws
21-
cd /home/ros2-essentials/cartographer_ws
22-
```
23-
- Open the turtlebot simulation in `tmux`
24-
25-
```bash
26-
export TURTLEBOT3_MODEL=burger
27-
ros2 launch turtlebot3_gazebo turtlebot3_world.launch.py
28-
```
29-
- Run the SLAM node in new window of `tmux`
30-
31-
```bash
32-
ros2 launch turtlebot3_cartographer cartographer.launch.py is_sim:=True
33-
```
34-
- Run the control tool in new window of `tmux`
35-
36-
```bash
37-
rqt_robot_steering
38-
```
39-
40-
### Building Packages
41-
42-
```sh
43-
docker attach ros2-cartographer-ws
44-
cd /home/ros2-essentials/cartographer_ws
45-
rosdep update
46-
rosdep install --from-paths src --ignore-src --rosdistro humble -y
47-
colcon build
48-
```
49-
50-
> After the build process, make sure to source the `install/setup.bash` file.
51-
> Otherwise, ROS2 will not locate the executable files. You can open a new terminal to accomplish this.
52-
53-
### Multi LiDAR - Single Robot SLAM test
54-
55-
#### Simulation
56-
57-
- multi_lidar_desp package: Description of a robot with multiple LiDARs.
58-
- multi_lidar_gazebo package: Gazebo simulation of the robot with robot state publisher.
59-
60-
```bash
61-
ros2 launch multi_lidar_gazebo multi_lidar_gazebo.launch.py
62-
```
63-
64-
#### Run the SLAM node
65-
66-
- Run the cartographer SLAM node in new window of `tmux`
67-
```bash
68-
ros2 launch cartographer_demo cartographer_demo.launch.py is_sim:=True
69-
```
70-
71-
- Run the control tool in new window of `tmux`
72-
```bash
73-
rqt_robot_steering
74-
```
75-
76-
#### References
77-
78-
- [Cartographer Demo](https://google-cartographer-ros.readthedocs.io/en/latest/demos.html)
3+
Please visit <https://j3soon.github.io/ros2-essentials/> for documentation.

0 commit comments

Comments
 (0)